plugin-dev-guide.html 9.68 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2

Matt Tucker's avatar
Matt Tucker committed
3 4
<html>
<head>
5 6
    <title>Jive Messenger Plugin Guide</title>
    <link href="style.css" rel="stylesheet" type="text/css">
Matt Tucker's avatar
Matt Tucker committed
7
</head>
8

Matt Tucker's avatar
Matt Tucker committed
9 10 11 12
<body>

<h1>Jive Messenger Plugin Developer Guide</h1>

13 14
<a name="top"></a>

Matt Tucker's avatar
Matt Tucker committed
15 16 17 18
<h2>Introduction</h2>

<p>
Plugins enhance the functionality of Jive Messenger. This document is a
19 20
developer's guide for creating plugins.
</p>
Matt Tucker's avatar
Matt Tucker committed
21 22 23

<h2>Structure of a Plugin</h2>

24
<p>
25
Plugins live in the <tt>plugins</tt> directory of <tt>messengerHome</tt>. When a plugin
Matt Tucker's avatar
Matt Tucker committed
26
is deployed as a JAR file, it is automatically expanded into a directory. The files in a
27
plugin directory are as follows:
28 29 30 31 32 33 34
</p>

<fieldset>
    <legend>Plugin Structure</legend>
<pre>myplugin/
 |- plugin.xml     &lt;- Plugin definition file
 |- classes/       &lt;- Resources your plugin needs (i.e., a properties file)
Matt Tucker's avatar
Matt Tucker committed
35 36
 |- lib/           &lt;- Libraries (JAR files) your plugin needs
 |- web            &lt;- Resources for Admin Console integration.
Matt Tucker's avatar
Matt Tucker committed
37 38
     |- web.xml
     |- images/
39 40 41
</pre>
</fieldset>

Matt Tucker's avatar
Matt Tucker committed
42 43
<p>The <tt>web</tt> directory exists for plugins that need to add content
to the Jive Messenger Admin Console. Further details are below.</p>
Matt Tucker's avatar
Matt Tucker committed
44

45
<p>
Matt Tucker's avatar
Matt Tucker committed
46 47
The <tt>plugin.xml</tt> file specifies the main Plugin class. A sample
file might look like the following:
48
</p>
Matt Tucker's avatar
Matt Tucker committed
49

50 51 52
<fieldset>
    <legend>Sample plugin.xml</legend>
<pre class="xml">
Matt Tucker's avatar
Matt Tucker committed
53 54
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;plugin&gt;
55
    <span class="comment">&lt;!-- Main plugin class --&gt;</span>
Matt Tucker's avatar
Matt Tucker committed
56
    &lt;class&gt;org.example.ExamplePlugin&lt;/class&gt;
Matt Tucker's avatar
Matt Tucker committed
57

58 59 60 61 62 63
    <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;
Matt Tucker's avatar
Matt Tucker committed
64

65 66 67 68
    <span class="comment">&lt;!-- Admin console entries --&gt;</span>
    &lt;adminconsole&gt;
        <span class="comment">&lt;!-- More on this below --&gt;</span>
    &lt;/adminconsole&gt;
Matt Tucker's avatar
Matt Tucker committed
69 70
&lt;/plugin&gt;
</pre>
71 72
</fieldset>

73 74
<p>The meta-data fields that can be set in the plugin.xml file:

Matt Tucker's avatar
Matt Tucker committed
75
<ul>
76 77 78 79 80 81 82
    <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>
Matt Tucker's avatar
Matt Tucker committed
83 84
</ul></p>

85 86
<p>Your plugin class must be implement the
<tt><a href="javadoc/org/jivesoftware/messenger/container/Plugin.html">Plugin</a></tt>
Matt Tucker's avatar
Matt Tucker committed
87
interface from the <a href="javadoc/index.html">Jive Messenger API</a> as
Matt Tucker's avatar
Matt Tucker committed
88
well as have a default (no argument) contructor. The Plugin interface has
89
methods for initializing and destroying the plugin.
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
</p>

<fieldset>
    <legend>Sample plugin implementation</legend>
<pre class="java">
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 void initialize(PluginManager manager, File pluginDirectory) {
        <span class="comment">// Your code goes here</span>
    }

    public void destroy() {
        <span class="comment">// Your code goes here</span>
    }
}
</pre>
</fieldset>
Matt Tucker's avatar
Matt Tucker committed
117 118 119 120

<h2>Modifying the Admin Console</h2>

<p>Plugins can add tabs, sections, and pages to the admin console. There
Matt Tucker's avatar
Matt Tucker committed
121
are a several steps to accomplishing this:
Matt Tucker's avatar
Matt Tucker committed
122 123

<ul>
124 125 126 127 128 129 130 131 132 133 134 135 136
    <li>An &lt;adminconsole/&gt; section must be added to the
            <tt>plugin.xml</tt> file.
    </li>
    <li>JSP files must be compiled and put into the classpath of the
        plugin. A <tt>web.xml</tt> file containing the compiled JSP
        servlet entries must be put into the <tt>web/</tt> directory
        of the plugin. <i>Note:</i> the Jive Messenger build script
        can assist with compiling JSPs and creating the web.xml. This
        is detailed below.
    </li>
    <li>Any images required by your JSP pages must live in <tt>web/images/</tt>
        directory. Only GIF and PNG images are supported.
    </li>
Matt Tucker's avatar
Matt Tucker committed
137
</ul>
Matt Tucker's avatar
Matt Tucker committed
138

139
<p>The <tt>&lt;adminconsole /&gt;</tt> section of <tt>plugin.xml</tt> defines additional
Matt Tucker's avatar
Matt Tucker committed
140 141
tabs, sections and entries in the Admin Console framework. A sample
<tt>plugin.xml</tt> file might look like the following:</p>
Matt Tucker's avatar
Matt Tucker committed
142

143 144 145
<fieldset>
    <legend>Sample plugin.xml</legend>
<pre class="xml">
Matt Tucker's avatar
Matt Tucker committed
146 147
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;plugin&gt;
148
    <span class="comment">&lt;!-- Main plugin class --&gt;</span>
Matt Tucker's avatar
Matt Tucker committed
149
    &lt;class&gt;org.example.ExamplePlugin&lt;/class&gt;
150 151 152 153 154 155 156 157 158 159 160

    <span class="comment">&lt;!-- Admin console entries --&gt;</span>
    &lt;adminconsole&gt;
        &lt;tab id="mytab" name="Example" url="my-plugin-admin.jsp" description="Click to manage..."&gt;
            &lt;sidebar id="mysidebar" name="My Plugin"&gt;
               &lt;item id="my-plugin" name="My Plugin Admin"
                   url="my-plugin-admin.jsp"
                   description="Click to administer settings for my plugin" /&gt;
            &lt;/sidebar&gt;
        &lt;/tab&gt;
    &lt;/adminconsole&gt;
Matt Tucker's avatar
Matt Tucker committed
161
&lt;/plugin&gt;
162 163
</pre>
</fieldset>
Matt Tucker's avatar
Matt Tucker committed
164

165 166 167
<p>
In this example, we've defined a new tab "Example", a sidebar section
"My Plugin" and a page "My Plugin Admin". We've registered <tt>my-plugin-admin.jsp</tt>
Matt Tucker's avatar
Matt Tucker committed
168 169
as the page. You can override existing tabs, sections, and items by using
the existing id attribute values in your own <tt>&lt;adminconsole&gt;</tt> defintion.
170 171
</p>

Matt Tucker's avatar
Matt Tucker committed
172 173 174 175 176 177 178 179 180 181 182 183
<h3>Admin Console Best Practices</h3>

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:

<ul>
		<li>Integrate into existing tabs and sidebar sections whenever possible
        instead of creating your own. Only create new tabs for very
				significant new functionality.
		<li>Don't use the word "plugin" in names of tabs, sidebars and items.
				For example, instead of having an item called "Gateway Plugin", it
Matt Tucker's avatar
Matt Tucker committed
184
				could be called "Gateway Settings".
Matt Tucker's avatar
Matt Tucker committed
185 186 187 188 189
		<li>Try to match the UI of the existing admin console in your custom
		    plugin pages.
		<li>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.
Matt Tucker's avatar
Matt Tucker committed
190
</ul>
Matt Tucker's avatar
Matt Tucker committed
191

192
<h2>Using the Jive Messenger Build Script</h2>
Matt Tucker's avatar
Matt Tucker committed
193

194
<p>
Matt Tucker's avatar
Matt Tucker committed
195 196
The Jive Messenger build script will help you build and develop plugins. It
looks for plugin development directories in the following format:
197 198
</p>

Matt Tucker's avatar
Matt Tucker committed
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
<fieldset>
    <legend>Plugin Structure</legend>
<pre>myplugin/
 |- plugin.xml     &lt;- Plugin definition file
 |- classes/       &lt;- Resources your plugin needs (i.e., a properties file)
 |- lib/           &lt;- Libraries your plugin needs
 |- src/
     |- java       &lt;- Java source code for your plugin
     |   |- com
     |       |- mycompany
     |           |- *.java
     |- web
         |- *.jsp      &lt;- JSPs your plugin uses for the admin console
         |- images/    &lt;- Any images your JSP pages need (optional)
</pre>
</fieldset>

Matt Tucker's avatar
Matt Tucker committed
216
<p>The build script will compile source files and JSPs and create a valid
Matt Tucker's avatar
Matt Tucker committed
217 218 219 220
plugin structure and JAR file. Put your plugin directories in the <tt>src/plugins</tt>
directory of the source distribution and then use <tt>ant plugins</tt> to
build your plugins.</p>

221 222 223 224
<p>Any JAR files your plugin needs during compilation should be put
into the <tt>lib</tt> directory. These JAR files will also be copied into
the plugin's generated <tt>lib</tt> directory as part of the build process.

Matt Tucker's avatar
Matt Tucker committed
225 226
<h2>Implementing Your Plugin</h2>

Matt Tucker's avatar
Matt Tucker committed
227
<p>Plugins have full access to the Jive Messenger API. This provides a tremendous
Matt Tucker's avatar
Matt Tucker committed
228 229 230 231
amount of flexibility for what plugins can accomplish. However, there are several integration
points that are the most common:

<ol>
Matt Tucker's avatar
Matt Tucker committed
232 233 234 235 236
    <li>Register a plugin as a <a href="javadoc/org/jivesoftware/messenger/Component.html">Component</a>.
 Components receive all packets addressed to a particular sub-domain. For example,
 <tt>test_component.example.com</tt>. So, a packet sent to <tt>joe@test_component.example.com</tt> 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
Matt Tucker's avatar
Matt Tucker committed
237
 example above); sub-domains are only used for routing within the XMPP server.
Matt Tucker's avatar
Matt Tucker committed
238 239

   <li>Register a plugin as an <a href="javadoc/org/jivesoftware/messenger/IQHandler.html">IQHandler</a>. IQ handlers respond to IQ packets with a particular element name and
240
  namespace. The following code snippet demonstrates how to register an IQHandler:
Matt Tucker's avatar
Matt Tucker committed
241

242 243 244 245 246
  <pre>
  IQHandler myHandler = new MyIQHander();
  IQRouter iqRouter = XMPPServer.getInstance().getIQRouter();
  iqRouter.addHandler(myHandler);
  </pre>
Matt Tucker's avatar
Matt Tucker committed
247

Matt Tucker's avatar
Matt Tucker committed
248 249 250
</ol>

</p>
Matt Tucker's avatar
Matt Tucker committed
251

Matt Tucker's avatar
Matt Tucker committed
252 253 254 255 256 257 258 259
<h2>Plugin FAQ</h2>

<b>Can I deploy a plugin as a directory instead of a JAR?</b>
<p>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.</p>

<b>What license agreement are plugins subject to?</b>
Matt Tucker's avatar
Matt Tucker committed
260 261
<p>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
Matt Tucker's avatar
Matt Tucker committed
262 263 264
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.

265 266
<br><br>

Matt Tucker's avatar
Matt Tucker committed
267 268
</body>
</html>