# 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);