From 56f0826d8e2fad9e078c973a5a6a3367d09abe19 Mon Sep 17 00:00:00 2001 From: Guus der Kinderen Date: Sat, 15 Jul 2023 15:42:25 +0200 Subject: [PATCH 1/5] 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 From 9aa2318f8c1722eedda9223d2dd7a4c924e1f5b7 Mon Sep 17 00:00:00 2001 From: Dan Caseley Date: Thu, 20 Jul 2023 22:21:53 +0100 Subject: [PATCH 2/5] Tiny punctuation fix --- documentation/implementing-authprovider-guide.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/implementing-authprovider-guide.html b/documentation/implementing-authprovider-guide.html index 72774768c7..0617f67282 100644 --- a/documentation/implementing-authprovider-guide.html +++ b/documentation/implementing-authprovider-guide.html @@ -154,7 +154,7 @@

    Should I include all the dependencies that my code needs?

    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: + dedicated class path. For another, the load order of plugins could lead to hairy scenarios, 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! From 28afd189aa039bf58eb6adea49a63949e2c28cfc Mon Sep 17 00:00:00 2001 From: Dan Caseley Date: Thu, 20 Jul 2023 22:22:00 +0100 Subject: [PATCH 3/5] Tiny punctuation fix --- documentation/implementing-groupprovider-guide.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/implementing-groupprovider-guide.html b/documentation/implementing-groupprovider-guide.html index a2a0bde251..ab0b748bc8 100644 --- a/documentation/implementing-groupprovider-guide.html +++ b/documentation/implementing-groupprovider-guide.html @@ -161,7 +161,7 @@

    Should I include all the dependencies that my code needs?

    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: + dedicated class path. For another, the load order of plugins could lead to hairy scenarios, 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! From 172408acf8de148697108b322e0e045d1dfa791e Mon Sep 17 00:00:00 2001 From: Dan Caseley Date: Thu, 20 Jul 2023 22:22:06 +0100 Subject: [PATCH 4/5] Tiny punctuation fix --- documentation/implementing-userprovider-guide.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/implementing-userprovider-guide.html b/documentation/implementing-userprovider-guide.html index 2e9328a8c9..acb5db8a2d 100644 --- a/documentation/implementing-userprovider-guide.html +++ b/documentation/implementing-userprovider-guide.html @@ -153,7 +153,7 @@

    Should I include all the dependencies that my code needs?

    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: + dedicated class path. For another, the load order of plugins could lead to hairy scenarios, 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! From c827d2dd58f5baf358ce83b1145cb009e097228e Mon Sep 17 00:00:00 2001 From: Dan Caseley Date: Thu, 20 Jul 2023 22:22:11 +0100 Subject: [PATCH 5/5] Tiny punctuation fix --- documentation/pluggable-roster-support-guide.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/pluggable-roster-support-guide.html b/documentation/pluggable-roster-support-guide.html index fca459a4af..53f8e0bd3c 100644 --- a/documentation/pluggable-roster-support-guide.html +++ b/documentation/pluggable-roster-support-guide.html @@ -127,7 +127,7 @@

    Should I include all the dependencies that my code needs?

    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: + dedicated class path. For another, the load order of plugins could lead to hairy scenarios, 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!