From 56f0826d8e2fad9e078c973a5a6a3367d09abe19 Mon Sep 17 00:00:00 2001 From: Guus der Kinderen Date: Sat, 15 Jul 2023 15:42:25 +0200 Subject: [PATCH] Documentation: add classpath FAQs to provider guides --- .../implementing-authprovider-guide.html | 24 +++++++++++++++++-- .../implementing-groupprovider-guide.html | 24 +++++++++++++++++-- .../implementing-userprovider-guide.html | 24 +++++++++++++++++-- .../pluggable-roster-support-guide.html | 24 +++++++++++++++++-- 4 files changed, 88 insertions(+), 8 deletions(-) diff --git a/documentation/implementing-authprovider-guide.html b/documentation/implementing-authprovider-guide.html index 9e3ffbfa39..72774768c7 100644 --- a/documentation/implementing-authprovider-guide.html +++ b/documentation/implementing-authprovider-guide.html @@ -87,8 +87,8 @@

The AuthProvider extension point

  • Make the class available in a jar and make this available to Openfire by placing it in the lib directory. - There are numerous ways to package a jar with this class inside it, popular build systems such as Gradle and Maven - can make your life easier. + Why not use an Openfire plugin, you ask? Read the FAQ entry below! There are numerous ways to package a + jar with this class inside it, popular build systems such as Gradle and Maven can make your life easier.
  • Set the property provider.auth.className to be the full name of your class, e.g. @@ -140,6 +140,26 @@

    How do I ensure my custom class is visible on the Openfire classpath?

    available at startup.

    +

    Should I include all the dependencies that my code needs?

    +

    + Yes, and no. Your code will run using the same classpath as Openfire. Openfire's dependencies are already on + that classpath. If your code uses the same dependencies, you do not need to include them again. You can add + other dependencies, either by packaging them in your jar file, or by placing them in the openfire lib folder. +

    +

    + Beware of conflicting dependencies! Sometimes, packaging dependencies in an all-containing jar, and renaming + the packages of those dependencies (shade them), can be helpful. +

    + +

    Isn't it easier to deploy my code as an Openfire plugin?

    +

    + It is not recommended to use a plugin for packaging and deploying your provider. For one, plugins use a + dedicated class path. For another, the load order of plugins could lead to hairy scenario's, and finally: + plugins can be unloaded at runtime. This all could lead to a running Openfire service for which you + cannot guarantee that your provider is loaded at all times. For these reasons, we recommend creating a jar + file instead of an Openfire plugin, and placing that jar file in Openfire's lib directory! +

    +

    Can I see some examples?

    Openfire's own authentication mechanism makes use of the AuthProvider API! If you want to get diff --git a/documentation/implementing-groupprovider-guide.html b/documentation/implementing-groupprovider-guide.html index 301b4282f1..a2a0bde251 100644 --- a/documentation/implementing-groupprovider-guide.html +++ b/documentation/implementing-groupprovider-guide.html @@ -93,8 +93,8 @@

    The GroupProvider extension point

  • Make the class available in a jar and make this available to Openfire by placing it in the lib directory. - There are numerous ways to package a jar with this class inside it, popular build systems such as Gradle and Maven - can make your life easier. + Why not use an Openfire plugin, you ask? Read the FAQ entry below! There are numerous ways to package a + jar with this class inside it, popular build systems such as Gradle and Maven can make your life easier.
  • Set the property provider.group.className to be the full name of your class, e.g. @@ -147,6 +147,26 @@

    How do I ensure my custom class is visible on the Openfire classpath?

    available at startup.

    +

    Should I include all the dependencies that my code needs?

    +

    + Yes, and no. Your code will run using the same classpath as Openfire. Openfire's dependencies are already on + that classpath. If your code uses the same dependencies, you do not need to include them again. You can add + other dependencies, either by packaging them in your jar file, or by placing them in the openfire lib folder. +

    +

    + Beware of conflicting dependencies! Sometimes, packaging dependencies in an all-containing jar, and renaming + the packages of those dependencies (shade them), can be helpful. +

    + +

    Isn't it easier to deploy my code as an Openfire plugin?

    +

    + It is not recommended to use a plugin for packaging and deploying your provider. For one, plugins use a + dedicated class path. For another, the load order of plugins could lead to hairy scenario's, and finally: + plugins can be unloaded at runtime. This all could lead to a running Openfire service for which you + cannot guarantee that your provider is loaded at all times. For these reasons, we recommend creating a jar + file instead of an Openfire plugin, and placing that jar file in Openfire's lib directory! +

    +

    Can I see some examples?

    Openfire's own group functionality makes use of the GroupProvider API! If you want to get diff --git a/documentation/implementing-userprovider-guide.html b/documentation/implementing-userprovider-guide.html index f10546f59e..2e9328a8c9 100644 --- a/documentation/implementing-userprovider-guide.html +++ b/documentation/implementing-userprovider-guide.html @@ -86,8 +86,8 @@

    The UserProvider extension point

  • Make the class available in a jar and make this available to Openfire by placing it in the lib directory. - There are numerous ways to package a jar with this class inside it, popular build systems such as Gradle and Maven - can make your life easier. + Why not use an Openfire plugin, you ask? Read the FAQ entry below! There are numerous ways to package a + jar with this class inside it, popular build systems such as Gradle and Maven can make your life easier.
  • Set the property provider.user.className to be the full name of your class, e.g. @@ -139,6 +139,26 @@

    How do I ensure my custom class is visible on the Openfire classpath?

    available at startup.

    +

    Should I include all the dependencies that my code needs?

    +

    + Yes, and no. Your code will run using the same classpath as Openfire. Openfire's dependencies are already on + that classpath. If your code uses the same dependencies, you do not need to include them again. You can add + other dependencies, either by packaging them in your jar file, or by placing them in the openfire lib folder. +

    +

    + Beware of conflicting dependencies! Sometimes, packaging dependencies in an all-containing jar, and renaming + the packages of those dependencies (shade them), can be helpful. +

    + +

    Isn't it easier to deploy my code as an Openfire plugin?

    +

    + It is not recommended to use a plugin for packaging and deploying your provider. For one, plugins use a + dedicated class path. For another, the load order of plugins could lead to hairy scenario's, and finally: + plugins can be unloaded at runtime. This all could lead to a running Openfire service for which you + cannot guarantee that your provider is loaded at all times. For these reasons, we recommend creating a jar + file instead of an Openfire plugin, and placing that jar file in Openfire's lib directory! +

    +

    Can I see some examples?

    Openfire's own user functionality makes use of the UserProvider API! If you want to get diff --git a/documentation/pluggable-roster-support-guide.html b/documentation/pluggable-roster-support-guide.html index 7071e9d51e..fca459a4af 100644 --- a/documentation/pluggable-roster-support-guide.html +++ b/documentation/pluggable-roster-support-guide.html @@ -85,8 +85,8 @@

    The RosterItemProvider extension point

  • Make the class available in a jar and make this available to Openfire by placing it in the lib directory. - There are numerous ways to package a jar with this class inside it, popular build systems such as Gradle and Maven - can make your life easier. + Why not use an Openfire plugin, you ask? Read the FAQ entry below! There are numerous ways to package a + jar with this class inside it, popular build systems such as Gradle and Maven can make your life easier.
  • Set the property 'provider.roster.className' to be the full name of your class, e.g. 'com.foo.bar.MyRosterItemProvider'. @@ -113,6 +113,26 @@

    How do I ensure my custom class is visible on the Openfire classpath?

    available at startup.

    +

    Should I include all the dependencies that my code needs?

    +

    + Yes, and no. Your code will run using the same classpath as Openfire. Openfire's dependencies are already on + that classpath. If your code uses the same dependencies, you do not need to include them again. You can add + other dependencies, either by packaging them in your jar file, or by placing them in the openfire lib folder. +

    +

    + Beware of conflicting dependencies! Sometimes, packaging dependencies in an all-containing jar, and renaming + the packages of those dependencies (shade them), can be helpful. +

    + +

    Isn't it easier to deploy my code as an Openfire plugin?

    +

    + It is not recommended to use a plugin for packaging and deploying your provider. For one, plugins use a + dedicated class path. For another, the load order of plugins could lead to hairy scenario's, and finally: + plugins can be unloaded at runtime. This all could lead to a running Openfire service for which you + cannot guarantee that your provider is loaded at all times. For these reasons, we recommend creating a jar + file instead of an Openfire plugin, and placing that jar file in Openfire's lib directory! +

    +

    Will I have a degradation in performance using a custom RosterItemProvider?

    It completely depends on your implementation. As with any Openfire customisation or plugin, badly written