Documentation: add classpath FAQs to provider guides

documentation/implementing-authprovider-guide.html

@@ -87,8 +87,8 @@ <h2>The AuthProvider extension point</h2>
             </li>
             <li>
                 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.
             </li>
             <li>
                 Set the property <code>provider.auth.className</code> to be the full name of your class, e.g.
@@ -140,6 +140,26 @@ <h4>How do I ensure my custom class is visible on the Openfire classpath?</h4>
             available at startup.
         </p>
 
+        <h4>Should I include all the dependencies that my code needs?</h4>
+        <p>
+            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.
+        </p>
+        <p>
+            Beware of conflicting dependencies! Sometimes, packaging dependencies in an all-containing jar, and renaming
+            the packages of those dependencies (<em>shade</em> them), can be helpful.
+        </p>
+
+        <h4>Isn't it easier to deploy my code as an Openfire plugin?</h4>
+        <p>
+            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 <em>unloaded</em> 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!
+        </p>
+
         <h4>Can I see some examples?</h4>
         <p>
             Openfire's own authentication mechanism makes use of the <code>AuthProvider</code> API! If you want to get

documentation/implementing-groupprovider-guide.html

@@ -93,8 +93,8 @@ <h2>The GroupProvider extension point</h2>
             </li>
             <li>
                 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.
             </li>
             <li>
                 Set the property <code>provider.group.className</code> to be the full name of your class, e.g.
@@ -147,6 +147,26 @@ <h4>How do I ensure my custom class is visible on the Openfire classpath?</h4>
             available at startup.
         </p>
 
+        <h4>Should I include all the dependencies that my code needs?</h4>
+        <p>
+            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.
+        </p>
+        <p>
+            Beware of conflicting dependencies! Sometimes, packaging dependencies in an all-containing jar, and renaming
+            the packages of those dependencies (<em>shade</em> them), can be helpful.
+        </p>
+
+        <h4>Isn't it easier to deploy my code as an Openfire plugin?</h4>
+        <p>
+            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 <em>unloaded</em> 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!
+        </p>
+
         <h4>Can I see some examples?</h4>
         <p>
             Openfire's own group functionality makes use of the <code>GroupProvider</code> API! If you want to get

documentation/implementing-userprovider-guide.html

@@ -86,8 +86,8 @@ <h2>The UserProvider extension point</h2>
             </li>
             <li>
                 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.
             </li>
             <li>
                 Set the property <code>provider.user.className</code> to be the full name of your class, e.g.
@@ -139,6 +139,26 @@ <h4>How do I ensure my custom class is visible on the Openfire classpath?</h4>
             available at startup.
         </p>
 
+        <h4>Should I include all the dependencies that my code needs?</h4>
+        <p>
+            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.
+        </p>
+        <p>
+            Beware of conflicting dependencies! Sometimes, packaging dependencies in an all-containing jar, and renaming
+            the packages of those dependencies (<em>shade</em> them), can be helpful.
+        </p>
+
+        <h4>Isn't it easier to deploy my code as an Openfire plugin?</h4>
+        <p>
+            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 <em>unloaded</em> 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!
+        </p>
+
         <h4>Can I see some examples?</h4>
         <p>
             Openfire's own user functionality makes use of the <code>UserProvider</code> API! If you want to get

documentation/pluggable-roster-support-guide.html

@@ -85,8 +85,8 @@ <h2>The RosterItemProvider extension point</h2>
             </li>
             <li>
                 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.
             </li>
             <li>
                 Set the property 'provider.roster.className' to be the full name of your class, e.g. 'com.foo.bar.MyRosterItemProvider'.
@@ -113,6 +113,26 @@ <h4>How do I ensure my custom class is visible on the Openfire classpath?</h4>
             available at startup.
         </p>
 
+        <h4>Should I include all the dependencies that my code needs?</h4>
+        <p>
+            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.
+        </p>
+        <p>
+            Beware of conflicting dependencies! Sometimes, packaging dependencies in an all-containing jar, and renaming
+            the packages of those dependencies (<em>shade</em> them), can be helpful.
+        </p>
+
+        <h4>Isn't it easier to deploy my code as an Openfire plugin?</h4>
+        <p>
+            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 <em>unloaded</em> 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!
+        </p>
+
         <h4>Will I have a degradation in performance using a custom RosterItemProvider?</h4>
         <p>
             It completely depends on your implementation. As with any Openfire customisation or plugin, badly written