Updated plugin interface (JM-176).

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

documentation/docs/plugin-dev-guide.html

@@ -22,9 +22,9 @@ developer's guide for creating plugins.
 <h2>Structure of a Plugin</h2>
 
 <p>
-Plugins live in the <tt>plugins</tt> directory of <tt>messengerHome</tt>. If
-a plugin is deployed as a JAR file, it will be automatically expanded into
-a directory. The files in a plugin directory are as follows:
+Plugins live in the <tt>plugins</tt> directory of <tt>messengerHome</tt>. When a plugin
+is deployed as a JAR file, it is automatically expanded into a directory. The files in a 
+plugin directory are as follows:
 </p>
 
 <fieldset>
@@ -54,7 +54,14 @@ file might look like the following:
 &lt;plugin&gt;
     <span class="comment">&lt;!-- Main plugin class --&gt;</span>
     &lt;class&gt;org.example.ExamplePlugin&lt;/class&gt;
-
+    
+    <span class="comment">&lt;!-- Plugin meta-data --&gt;</span>
+    &lt;name&gt;Example Plugin&lt;/name&gt;
+    &lt;description&gt;This is an example plugin.&lt;/description&gt;
+    &lt;author&gt;Jive Software&lt;/author&gt;
+    &lt;version&gt;1.0&lt;/version&gt;
+    &lt;minServerVersion&gt;2.1.2&lt;/minServerVersion&gt;
+    
     <span class="comment">&lt;!-- Admin console entries --&gt;</span>
     &lt;adminconsole&gt;
         <span class="comment">&lt;!-- More on this below --&gt;</span>
@@ -63,12 +70,23 @@ file might look like the following:
 </pre>
 </fieldset>
 
+<p>The meta-data fields that can be set in the plugin.xml file:
+
+<ul> 
+    <li>name -- the name of the plugin.</li>
+    <li>description -- the description of the plugin.</li>
+    <li>author -- the author of the plugin.</li>
+    <li>version -- the version of the pluginn.</li>
+    <li>minServerVersion -- the minimum version of Jive Messenger required
+          to run the plugin (supported by Jive Messenger 2.1.2 and later). If the
+          server version is less than the required value, the plugin will not be started.</li>
+</ul></p> 
+ 
 <p>Your plugin class must be implement the
 <tt><a href="javadoc/org/jivesoftware/messenger/container/Plugin.html">Plugin</a></tt>
 interface from the <a href="javadoc/index.html">Jive Messenger API</a> as 
 well as have a default (no argument) contructor. The Plugin interface has
-methods for initializing and destroying the plugin, as well as methods for retrieving meta-data
-such as the plugin name, description, version, and author.
+methods for initializing and destroying the plugin.
 </p>
 
 <fieldset>
@@ -86,22 +104,6 @@ import java.io.File;
  */
 public class ExamplePlugin implements Plugin {
 
-    public String getName() {
-        return "My Plugin";
-    }
-
-    public String getDescription() {
-        return "A simple plugin";
-    }
-
-    public String getAuthor() {
-        return "Johnny Java Coder";
-    }
-
-    public String getVersion() {
-        return "1.0";
-    }
-
     public void initialize(PluginManager manager, File pluginDirectory) {
         <span class="comment">// Your code goes here</span>
     }

src/java/org/jivesoftware/messenger/container/Plugin.java

@@ -41,6 +41,11 @@ import java.io.File;
  * <?xml version="1.0" encoding="UTF-8"?>
  * <plugin>
  *     <class>org.example.YourPlugin</class>
+ *     <name>Example Plugin</name>
+ *     <description>This is an example plugin.</description>
+ *     <author>Foo Inc.</author>
+ *     <version>1.0</version>
+ *     <minServerVersion>2.1.2</minServerVersion>
  * &lt;/plugin&gt;</pre>
  *
  * Each plugin will be loaded in its own class loader.
@@ -49,45 +54,23 @@ import java.io.File;
  */
 public interface Plugin {
 
-    /**
-     * Returns the name of this plugin.
-     *
-     * @return the plugin's name.
-     */
-    public String getName();
-
-    /**
-     * Returns the description of the plugin or <tt>null</tt> if there is no description.
-     *
-     * @return this plugin's description.
-     */
-    public String getDescription();
-
-    /**
-     * Returns the author of this plugin.
-     *
-     * @return the plugin's author.
-     */
-    public String getAuthor();
-
-    /**
-     * The plugin's version.
-     *
-     * @return the version of the plugin.
-     */
-    public String getVersion();
-
     /**
      * Initializes the plugin.
      *
      * @param manager the plugin manager.
      * @param pluginDirectory the directory where the plugin is located.
      */
-    public void initialize(PluginManager manager, File pluginDirectory);
+    public void initializePlugin(PluginManager manager, File pluginDirectory);
 
     /**
-     * Destroys the plugin.
+     * Destroys the plugin.<p>
+     *
+     * Implementations of this method must release all resources held
+     * by the plugin such as file handles, database or network connections,
+     * and references to core Jive Messenger classes. In other words, a
+     * garbage collection executed after this method is called must be able
+     * to clean up all plugin classes.
      */
-    public void destroy();
+    public void destroyPlugin();
 
 }
\ No newline at end of file

src/java/org/jivesoftware/messenger/container/PluginManager.java

 /**
+
  * $RCSfile$
+
  * $Revision$
+
  * $Date$
+
  *
+
  * Copyright (C) 2004 Jive Software. All rights reserved.
+
  *
+
  * This software is published under the terms of the GNU Public License (GPL),
+
  * a copy of which is included in this distribution.
+
  */
 
 package org.jivesoftware.messenger.container;
 
 import org.jivesoftware.util.Log;
+import org.jivesoftware.util.Version;
+
 import org.jivesoftware.messenger.JiveGlobals;
+import org.jivesoftware.messenger.XMPPServer;
+
 import org.jivesoftware.admin.AdminConsole;
+
 import org.dom4j.Document;
+
 import org.dom4j.Element;
+
 import org.dom4j.Attribute;
+
 import org.dom4j.io.SAXReader;
 
+
+
 import java.io.*;
+
 import java.util.*;
+
 import java.util.jar.JarFile;
+
 import java.util.jar.JarEntry;
+
 import java.util.zip.ZipFile;
+
 import java.util.concurrent.ScheduledExecutorService;
+
 import java.util.concurrent.ScheduledThreadPoolExecutor;
+
 import java.util.concurrent.TimeUnit;
 
 /**
@@ -35,11 +61,13 @@ import java.util.concurrent.TimeUnit;
  * @see Plugin
  * @author Matt Tucker
  */
+
 public class PluginManager {
 
     private File pluginDirectory;
     private Map<String,Plugin> plugins;
     private Map<Plugin,PluginClassLoader> classloaders;
+    private Map<Plugin,File> pluginDirs;
     private boolean setupMode = !(Boolean.valueOf(JiveGlobals.getXMLProperty("setup")).booleanValue());
     private ScheduledExecutorService executor = null;
 
@@ -51,6 +79,7 @@ public class PluginManager {
     public PluginManager(File pluginDir) {
         this.pluginDirectory = pluginDir;
         plugins = new HashMap<String,Plugin>();
+        pluginDirs = new HashMap<Plugin,File>();
         classloaders = new HashMap<Plugin,PluginClassLoader>();
     }
 
@@ -72,9 +101,10 @@ public class PluginManager {
         }
         // Shutdown all installed plugins.
         for (Plugin plugin : plugins.values()) {
-            plugin.destroy();
+            plugin.destroyPlugin();
         }
         plugins.clear();
+        pluginDirs.clear();
         classloaders.clear();
     }
 
@@ -112,11 +142,29 @@ public class PluginManager {
             if (pluginConfig.exists()) {
                 SAXReader saxReader = new SAXReader();
                 Document pluginXML = saxReader.read(pluginConfig);
+                // See if the plugin specifies a version of Jive Messenger
+                // required to run.
+                Element minServerVersion = (Element)pluginXML.selectSingleNode(
+                        "/plugin/minServerVersion");
+                if (minServerVersion != null) {
+                    String requiredVersion = minServerVersion.getTextTrim();
+                    Version version = XMPPServer.getInstance().getServerInfo().getVersion();
+                    String hasVersion = version.getMajor() + "." + version.getMinor() + "." +
+                            version.getMicro();
+                    if (hasVersion.compareTo(requiredVersion) < 0) {
+                        String msg = "Ignoring plugin " + pluginDir.getName() + ": requires " +
+                                "server version " + requiredVersion;
+                        Log.warn(msg);
+                        System.out.println(msg);
+                        return;
+                    }
+                }
                 PluginClassLoader pluginLoader = new PluginClassLoader(pluginDir);
                 String className = pluginXML.selectSingleNode("/plugin/class").getText();
                 plugin = (Plugin)pluginLoader.loadClass(className).newInstance();
-                plugin.initialize(this, pluginDir);
+                plugin.initializePlugin(this, pluginDir);
                 plugins.put(pluginDir.getName(), plugin);
+                pluginDirs.put(plugin, pluginDir);
                 classloaders.put(plugin, pluginLoader);
                 // Load any JSP's defined by the plugin.
                 File webXML = new File(pluginDir, "web" + File.separator + "web.xml");
@@ -157,7 +205,7 @@ public class PluginManager {
     }
 
     /**
-     * Unloads a plugin. The {@link Plugin#destroy()} method will be called and then
+     * Unloads a plugin. The {@link Plugin#destroyPlugin()} method will be called and then
      * any resources will be released.
      *
      * @param pluginName the name of the plugin to unload.
@@ -176,9 +224,10 @@ public class PluginManager {
         }
 
         PluginClassLoader classLoader = classloaders.get(plugin);
-        plugin.destroy();
+        plugin.destroyPlugin();
         classLoader.destroy();
         plugins.remove(pluginName);
+        pluginDirs.remove(plugin);
         classloaders.remove(plugin);
     }
 
@@ -189,6 +238,80 @@ public class PluginManager {
         return loader.loadClass(className);
     }
 
+    /**
+     * Returns the name of a plugin. The value is retrieved from the plugin.xml file
+     * of the plugin. If the value could not be found, <tt>null</tt> will be returned.
+     *
+     * @param plugin the plugin.
+     * @return the plugin's name.
+     */
+    public String getName(Plugin plugin) {
+        return getElementValue(plugin, "/plugin/name");
+    }
+
+    /**
+     * Returns the description of a plugin. The value is retrieved from the plugin.xml file
+     * of the plugin. If the value could not be found, <tt>null</tt> will be returned.
+     *
+     * @param plugin the plugin.
+     * @return the plugin's description.
+     */
+    public String getDescription(Plugin plugin) {
+        return getElementValue(plugin, "/plugin/description");
+    }
+
+    /**
+     * Returns the author of a plugin. The value is retrieved from the plugin.xml file
+     * of the plugin. If the value could not be found, <tt>null</tt> will be returned.
+     *
+     * @param plugin the plugin.
+     * @return the plugin's author.
+     */
+    public String getAuthor(Plugin plugin) {
+        return getElementValue(plugin, "/plugin/author");
+    }
+
+    /**
+     * Returns the version of a plugin. The value is retrieved from the plugin.xml file
+     * of the plugin. If the value could not be found, <tt>null</tt> will be returned.
+     *
+     * @param plugin the plugin.
+     * @return the plugin's version.
+     */
+    public String getVersion(Plugin plugin) {
+        return getElementValue(plugin, "/plugin/version");
+    }
+
+    /**
+     * Returns the value of an element selected via an xpath expression from
+     * a Plugin's plugin.xml file.
+     *
+     * @param plugin the plugin.
+     * @param xpath the xpath expression.
+     * @return the value of the element selected by the xpath expression.
+     */
+    private String getElementValue(Plugin plugin, String xpath) {
+        File pluginDir = pluginDirs.get(plugin);
+        if (pluginDir == null) {
+            return null;
+        }
+        try {
+            File pluginConfig = new File(pluginDir, "plugin.xml");
+            if (pluginConfig.exists()) {
+                SAXReader saxReader = new SAXReader();
+                Document pluginXML = saxReader.read(pluginConfig);
+                Element element = (Element)pluginXML.selectSingleNode(xpath);
+                if (element != null) {
+                    return element.getTextTrim();
+                }
+            }
+        }
+        catch (Exception e) {
+            Log.error(e);
+        }
+        return null;
+    }
+
     /**
      * A service that monitors the plugin directory for plugins. It periodically
      * checks for new plugin JAR files and extracts them if they haven't already
@@ -296,7 +419,7 @@ public class PluginManager {
          *
          * @param pluginName the name of the plugin.
          * @param file the JAR file
-         * @param dir the directory to extract the plugin to. 
+         * @param dir the directory to extract the plugin to.
          */
         private void unzipPlugin(String pluginName, File file, File dir) {
             try {

src/plugins/broadcast/plugin.xml

@@ -5,4 +5,9 @@
 -->
 <plugin>
     <class>org.jivesoftware.messenger.plugin.BroadcastPlugin</class>
+    <name>Broadcast Plugin</name>
+    <description>Broadcasts messages to users.</description>
+    <author>Jive Software</author>
+    <version>1.1</version>
+    <minMessengerVersion>3.1.0</minMessengerVersion>
 </plugin>
\ No newline at end of file

src/plugins/broadcast/src/java/org/jivesoftware/messenger/plugin/BroadcastPlugin.java

@@ -50,6 +50,7 @@ public class BroadcastPlugin implements Plugin, Component {
     private List<JID> allowedUsers;
     private boolean groupMembersAllowed;
     private ComponentManager componentManager;
+    private PluginManager pluginManager;
 
     /**
      * Constructs a new broadcast plugin.
@@ -63,23 +64,8 @@ public class BroadcastPlugin implements Plugin, Component {
 
     // Plugin Interface
 
-    public String getName() {
-        return "Broadcast Plugin";
-    }
-
-    public String getDescription() {
-        return "Broadcasts messages to users.";
-    }
-
-    public String getAuthor() {
-        return "Jive Software";
-    }
-
-    public String getVersion() {
-        return "1.0";
-    }
-
-    public void initialize(PluginManager manager, File pluginDirectory) {
+    public void initializePlugin(PluginManager manager, File pluginDirectory) {
+        pluginManager = manager;
         sessionManager = SessionManager.getInstance();
         groupManager = GroupManager.getInstance();
 
@@ -93,7 +79,7 @@ public class BroadcastPlugin implements Plugin, Component {
         }
     }
 
-    public void destroy() {
+    public void destroyPlugin() {
         // Unregister component.
         try {
             componentManager.removeComponent(serviceName);
@@ -101,6 +87,8 @@ public class BroadcastPlugin implements Plugin, Component {
         catch (Exception e) {
             componentManager.getLog().error(e);
         }
+        componentManager = null;
+        pluginManager = null;
         sessionManager = null;
         groupManager = null;
         allowedUsers.clear();
@@ -116,6 +104,16 @@ public class BroadcastPlugin implements Plugin, Component {
 
     // Component Interface
 
+    public String getName() {
+        // Get the name from the plugin.xml file.
+        return pluginManager.getName(this);
+    }
+
+    public String getDescription() {
+        // Get the description from the plugin.xml file.
+        return pluginManager.getDescription(this);
+    }
+
     public void processPacket(Packet packet) {
         // Only respond to incoming messages. TODO: handle disco, presence, etc.
         if (packet instanceof Message) {