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:

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:

<?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.

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:

<?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:

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.

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.