Documentation of plugin database support (JM-672).

git-svn-id: http://svn.igniterealtime.org/svn/repos/wildfire/trunk@3855 b35dd754-fafc-0310-a699-88a17e54d16e

documentation/docs/plugin-dev-guide.html

@@ -36,6 +36,7 @@ plugin directory are as follows:
  |- icon_small.gif  <- Optional small (16x16) icon associated with the plugin (can also be a .png file)
  |- icon_large.gif  <- Optional large (32x32) icon associated with the plugin (can also be a .png file)
  |- classes/        <- Resources your plugin needs (i.e., a properties file)
+ |- database/       <- Optional database schema files that your plugin needs
  |- lib/            <- Libraries (JAR files) your plugin needs
  |- web             <- Resources for Admin Console integration, if any
      |- WEB-INF/
@@ -66,9 +67,9 @@ file might look like the following:
     <description>This is an example plugin.</description>
     <author>Jive Software</author>
     <version>1.0</version>
-    <date>07/15/2005</date>
-    <url>http://www.jivesoftware.org/pluginX</url>
-    <minServerVersion>2.2.0</minServerVersion>
+    <date>07/01/2006</date>
+    <url>http://www.jivesoftware.org/plugins</url>
+    <minServerVersion>3.0.0</minServerVersion>
 
     <span class="comment">&lt;!-- Admin console entries --&gt;</span>
     &lt;adminconsole&gt;
@@ -86,11 +87,31 @@ file might look like the following:
     <li>author -- the author of the plugin.</li>
     <li>version -- the version of the plugin.</li>
     <li>date -- the date the plugin was released. The date must be in the form MM/dd/yyyy, such
-          as 07/15/2005.</li>
+          as 07/01/2006.</li>
     <li>url -- a URL where additional information about the plugin is available.</li>
     <li>minServerVersion -- the minimum version of Wildfire required
           to run the plugin (supported by Wildfire 2.1.2 and later). If the
           server version is less than the required value, the plugin will not be started.</li>
+    <li>databaseKey -- if the plugin requires it's own database tables, the databaseKey element should
+            be set with a schema key name (often the same name as the plugin). Database
+            schema files for each supported database should then be placed in the <tt>database</tt>
+            directory of the plugin. For example, given the key "foo", schema files would be called
+            "foo_mysql.sql", "foo_oracle.sql", etc. The scripts should make an entry into the
+            jiveVersion table using the key so that schema version information can be tracked, e.g.:<br><br>
+
+            <tt>INSERT INTO jiveVersion (name, version) VALUES ('foo', 0);</tt><br><br>
+    </li>
+    <li>databaseVersion -- the database schema version (if a database schema is defined). New plugins
+            with a database schema should start at version 0. If future versions of the plugin
+            require updates to the schema, those updates can be defined by creating sub-directories
+            in the <tt>database</tt> directory for each version number. For example, the directories
+            <tt>database/1</tt> and <tt>database/2</tt> would contain scripts such as "foo_mysql.sql"
+            and "foo_oracle.sql" that contain the relevant database changes for each version. Each
+            script should update version information in the jiveVersion table, e.g.:<br><br>
+
+            <tt>UPDATE jiveVersion set version=1 where name='foo';</tt><br><br>
+
+    </li>
     <li>parentPlugin -- the name of the parent plugin (given as "foo" for the "foo.jar" plugin).
             When a plugin has a parent plugin, the parent plugin's class loader will be used instead
             of creating a new class loader. This lets plugins work together more closely. A