Plug-in Developer Manual

This manual describes first how to create plug-ins for HIPE. The final chapter describes the mechanism that HIPE component developers can use to become aware of plug-ins.

Quick guide: Creating Simple Plug-ins

Plug-ins can be created to do lots of fancy things, but most of the time people will want to use them to share some pools, some Jython scripts, and/or possible some Java code. These standard cases are described here. One case does not exclude the other; combining the steps from the different cases described here will work.

General procedure for creating a plug-in

In general, a plug-in is just a JAR or a ZIP-file with a name that follows the following pattern: [name]_[version].[extension]. The name can be any string (it is allowed to contain underscores). The name is followed by an underscore. The version is a series of integers separated by dots: "1", "2.0", "2.3.4.5", etc, are allowed as the version. The extension should be "jar" or "zip". An example of a plug-in filename is myplugin_0.1.jar.

On Unix you can use the jar facility from the bin directory of the JDK to create jar-files. I recommend to cd to the directory where you have prepared your plug-in and create the jar-file in a different place, as follows:

> jar cvf $HOME/myplugin_0.1.jar *

The options to jar we used here are cvf: c for "create", v for "verbose" and f fore filename.

If you use Windows, you can use any compression program, as long as it a can write "zip" or "jar" file format. For example, PeaZip.

How to create a plug-in with some pools

Plug-ins can contain LocalStores. To create a plug-in with one or more LocalStores, create a directory called {{pools}}, copy the LocalStores in there and create a jar or zip with the pools directory.

Unix shell example: Assuming your LocalStores are in the default directory, {{$HOME/.hcss/lstore}} and you want to share {{poolA}} and {{poolB}}:

> mkdir pools
> cp -r $HOME/.hcss/lstore/poolA
> cp -r $HOME/.hcss/lstore/poolB
> jar cf $HOME/myplugin_0.1.jar pools

You probably will want to name your plug-in differently than "myplugin" though -- give it a name that says something about its contents. To change the name, just rename the file.

How to create a plug-in with some Jython code

We make a distinction between two types of Jython code, and how you create the plug-in depends which type you have. First, there is what we call "user scripts". These are meant to be scripts that a user should execute, such as a script that does some kind of processing. The other kind is a script that defines some functionality, for example a Task. In this second case, the user should not execute the script to use it (which would define the Task), the user should run the Task. This kind of script should be run by HIPE when it starts, so that the user has the Task available for use. We therefore call that kind "initialization scripts".

To create a plug-in with one or more user scripts, copy them to a directory called "scripts" and create a zip or jar containing that directory.

Unix shell example:

> mkdir scripts
> cp ~/work/scriptsForPlugin/*.py scripts
> jar cf $HOME/myplugin_0.1.jar scripts

Plug-ins support only one initialization script, but you can define multiple Tasks from a single script. The initialization script must be called plugin.py and it must be at the top or root-level of the jar or zip.

Unix shell example:

> mkdir scripts
> cp ~/work/myTasks.py plugin.py
> jar cf $HOME/myplugin_0.1.jar plugin.py

How to create a plug-in with some Java code

To add (compiled) Java code to a plug-in, the Java code has to be in a JAR itself. Add the JAR to a directory called "jars" and create a plug-in with this directory:

> mkdir jars
> cp ~/work/out/library.jar jars
> jar cf $HOME/myplugin_0.1.jar jars

For information on how to create a JAR file with your Java code, see the JAR Documentation.

Combinations of the above

If you want to create a plug-in that has an initialization script, some user scripts and a handful of pools, the easiest thing is to create a separate directory. Copy everything in there (the scripts directory, pools directory, etc) and create a zip or jar with everything:

> jar cf $HOME/myplugin_0.1.jar *

What you must avoid / Invalid plug-ins

When sharing things with plug-ins, you are not limited the items described in the previous section. You can add anything to a plug-in, but there are a few things that would make the plug-in invalid. An invalid plug-in would fail to install.

The following would make the plug-in invalid: - a file called scripts, pools or jars at the top-level of the file - a file or directory called work at the top-level of the file. HIPE uses this directory as an internal workspace.

Slightly more advanced topics

Customizing your plug-in

the plugin.xml options

Advanced: The plug-in installation process

Using a custom installer

Using a WebStart installer

Configuring the plug-in post-installation

Advanced: Using Java code from your plug-in from Jython

Remove? Works automatically?

For HIPE component developers: Reacting to plug-ins from your component

PluginRegistry

PluginProcessor

-- PaulBalm - 27 Aug 2010

Edit | Attach | Watch | Print version | History: r38 | r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r2 - 2010-08-27 - PaulBalm
 
This site is powered by the TWiki collaboration platform Powered by Perl