# Jive Messenger Plugin Developer Guide

## Introduction

Plugins enhance the functionality of Jive Messenger. This document is a developer's guide for creating plugins.

## Structure of a Plugin

Plugins live in the `plugins` directory of `messengerHome`. 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:

Plugin Structure

    myplugin/
     |- plugin.xml     <- Plugin definition file
     |- classes/       <- Resources your plugin needs (i.e., a properties file)
     |- lib/           <- Libraries (JAR files) your plugin needs
     |- web            <- Resources for Admin Console integration.
         |- web.xml
         |- images/

The `web` directory exists for plugins that need to add content to the Jive Messenger Admin Console. Further details are below.

The `plugin.xml` file specifies the main Plugin class. A sample file might look like the following:

Sample plugin.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <plugin>
        <!-- Main plugin class -->
        <class>org.example.ExamplePlugin</class>

        <!-- Admin console entries -->
        <adminconsole>
            <!-- More on this below -->
        </adminconsole>
    </plugin>

Your plugin class must be implement the `Plugin` interface from the Jive Messenger API 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.

Sample plugin implementation

    package org.example;

    import org.jivesoftware.messenger.container.Plugin;
    import org.jivesoftware.messenger.container.PluginManager;

    import java.io.File;

    /**
     * A sample plugin for Jive Messenger.
     */
    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) {
            // Your code goes here
        }

        public void destroy() {
            // Your code goes here
        }
    }

## Modifying the Admin Console

Plugins can add tabs, sections, and pages to the admin console. There are a several steps to accomplishing this:

- An <adminconsole/> section must be added to the `plugin.xml` file.
- JSP files must be compiled and put into the classpath of the plugin. A `web.xml` file containing the compiled JSP servlet entries must be put into the `web/` directory of the plugin. Note: the Jive Messenger build script can assist with compiling JSPs and creating the web.xml. This is detailed below.
- Any images required by your JSP pages must live in `web/images/` directory. Only GIF and PNG images are supported.

The `<adminconsole />` section of `plugin.xml` defines additional tabs, sections and entries in the Admin Console framework. A sample `plugin.xml` file might look like the following:

Sample plugin.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <plugin>
        <!-- Main plugin class -->
        <class>org.example.ExamplePlugin</class>

        <!-- Admin console entries -->
        <adminconsole>
            <tab id="mytab" name="Example" url="my-plugin-admin.jsp" description="Click to manage...">
                <sidebar id="mysidebar" name="My Plugin">
                   <item id="my-plugin" name="My Plugin Admin"
                       url="my-plugin-admin.jsp"
                       description="Click to administer settings for my plugin" />
                </sidebar>
            </tab>
        </adminconsole>
    </plugin>

In this example, we've defined a new tab "Example", a sidebar section "My Plugin" and a page "My Plugin Admin". We've registered `my-plugin-admin.jsp` as the page. You can override existing tabs, sections, and items by using the existing id attribute values in your own `<adminconsole>` defintion.

## Using the Jive Messenger Build Script

The Jive Messenger build script will help you build and develop plugins. It looks for plugin development directories in the following format:

Plugin Structure

    myplugin/
     |- plugin.xml     <- Plugin definition file
     |- classes/       <- Resources your plugin needs (i.e., a properties file)
     |- lib/           <- Libraries your plugin needs
     |- src/
         |- java       <- Java source code for your plugin
         |   |- com
         |       |- mycompany
         |           |- *.java
         |- web
             |- *.jsp      <- JSPs your plugin uses for the admin console
             |- images/    <- Any images your JSP pages need (optional)

The build script will compile source files and JSPs and create a valid plugin structure and JAR file. Put your plugin directories in the `src/plugins` directory of the source distribution and then use `ant plugins` to build your plugins.

Any JAR files your plugin needs during compilation should be put into the `lib` directory. These JAR files will also be copied into the plugin's generated `lib` directory as part of the build process.

## Implementing Your Plugin

Plugins have full access to the Jive Messenger API. This provides a tremendous amount of flexibility for what plugins can accomplish. However, there are several integration points that are the most common:

1. Register a plugin as a Component. Components receive all packets addressed to a particular sub-domain. For example, `test_component.example.com`. So, a packet sent to `joe@test_component.example.com` would be delivered to the component. Note that the sub-domains defined as components are unrelated to DNS entries for sub-domains. All XMPP routing at the socket level is done using the primary server domain (example.com in the example above); sub-domains are only used for routing within the XMPP server.
2. Register a plugin as an IQHandler. IQ handlers respond to IQ packets with a particular element name and namespace. The following code snippet demonstrates how to register an IQHandler:

         IQHandler myHandler = new MyIQHander();
         IQRouter iqRouter = XMPPServer.getInstance().getIQRouter();
         iqRouter.addHandler(myHandler);

## Plugin FAQ

Can I deploy a plugin as a directory instead of a JAR?

No, all plugins must be deployed as JAR or WAR files. When a JAR or WAR is not present for the plugin, Jive Messenger assumes that the file has been deleted and that the users wants to destroy the plugin, so it also deletes the directory.

What license agreement are plugins subject to?

Because Jive Messenger is released under the Open Source GPL license, any plugins developed must also be released under the GPL or a compatible Open Source license (such as Apache). It is a violation of the license agreement to create plugins that are not Open Source. Please see the Jive Messenger website if you need different licensing terms for Jive Messenger.