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. 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:
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:
The meta-data fields that can be set in the plugin.xml file:
name -- the name of the plugin.
description -- the description of the plugin.
author -- the author of the plugin.
version -- the version of the pluginn.
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.
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.
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:
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.
Admin Console Best Practices
There are several best practices to consider when making changes to
the Jive Messenger admin console via a plugin. The general theme is
that plugins should integrate seamlessly:
Integrate into existing tabs and sidebar sections whenever possible
instead of creating your own. Only create new tabs for very
significant new functionality.
Don't use the word "plugin" in names of tabs, sidebars and items.
For example, instead of having an item called "Gateway Plugin", it
could be called "Gateway Settings".
Try to match the UI of the existing admin console in your custom
plugin pages.
There is no need to create an admin console entry to show plugin
meta-data. Instead, let Jive Messenger inform the user about which
plugins are installed and provide plugin management.
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:
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:
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.
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.