Plug-in Developer Manual

This manual describes first how to create plug-ins for HIPE. In most cases, you will only have to read the relevant sections from the Quick Guide chapter. The final chapter describes the mechanism that HIPE component developers can use to become aware of plug-ins. For more information on the plug-in framework, see the Design document. User documentation on plugins is available on this page.

Plug-ins are available in HIPE starting version 5.0.

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 in this chapter. One case (pools, Jython or Java) 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 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", "", etc, are allowed as the version. The extension should be "jar" or "zip" (lowercase). 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, I like PeaZip.

All components of a plug-in are optional: Even an empty JAR-file is a valid plug-in that you can install perfectly well. Only, it doesn't do anything of course. For that, see the next sections.

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 create a plug-in with poolA and poolB:

> mkdir pools
> cp -r $HOME/.hcss/lstore/poolA pools
> cp -r $HOME/.hcss/lstore/poolB pools
> 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 of the plug-in, you can just rename the file.

When the plug-in is installed, the pools will appear in the Data Access section of the preferences (see Edit --> Preferences).

Tip, idea You can also share LocalStores using the Export View in HIPE. This will give you a compressed file with the pool, in the format of your choosing. Another user can import this file using the Import View, to recreate the LocalStore in his HIPE session (and in future HIPE sessions). This is simple and straightforward and there's nothing wrong with it. Plug-ins have more features, such as versions, title and description, and a plug-in can contain accompanying scripts, for example. Also, pools delivered as part of a plug-in are not installed to your LocalStore directory, they are kept in the plug-in directory, so they do not mix with your personal LocalStores. If a plug-in is published on a web-site (HTTP or FTP), then installation of a plug-in is slightly easier, since the download and unpacking are done automatically in a single step instead of two steps.

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

When this plug-in is installed, a menu item with the name of the plug-in will appear on the Tools menu. Pointing to the menu item opens a submenu with all scripts. Clicking on one of the scripts will open it in the editor.

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

Unix shell example:

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

This script is similar in function to the script that is contained in many of the Java packages in the HCSS. However, the must have some obligatory lines of code, which are not required for the script.

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

Note that the JARs are included integrally in the plug-in JAR; you should not unpack your JARs with Java code and include the loose class files in the plug-in JAR. To clarify further, if you get a listing from your plug-in JAR using jar tf plugin-1.0.jar, you might get a listing like this:


This plug-in contains a JAR called filtering.jar, which in turn might contain any number of Java classes.

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

How to create a plug-in with a Task Red star, highlightNEW

To easiest way to avoid the hassle that is involved in "making a new task work in HIPE", is to create a plug-in with the task inside. This section will show you how that's done. First, I'll make the assumption that the Task is written in Jython. (If your Task is in Java, do not despair, it's actually easier. Hints will be provided at the end of this section.)

  • Decide on a new for your plug-in. Say you call your plug-in SmartTask and the task it contains is called MyTask.
  • Create a new directory and cd into it
  • Save your task to a separate file in this directory, for example
  • In the same directory, create a file called with the following contents (edit as needed):

### EDIT here
### End section for the you to edit

# Imports
from herschel.ia.gui.apps.plugin import PluginRegistry
from herschel.ia.gui.kernel.Tool import Category
from herschel.ia.task.views import TaskToolRegistry 

# Find the basedirectory of the plugin
pluginRegistry = PluginRegistry.getInstance()
plugin = pluginRegistry.get(name)
basedir = plugin.pluginDir

# "Import" the task
execfile(basedir.absolutePath + '/' + taskFileName)

# Register task in HIPE session -- EDIT next two lines as needed
myTask = MyTask()
TaskToolRegistry.getInstance().register(myTask, [Category.SPIRE])

# Clean up
del(name, taskFileName)
del(pluginRegistry, plugin, basedir)

  • Create the plug-in with the following command: jar cf ../SmartTask_0.1.jar *
  • Test drive:
    • Remove or comment properties and other settings you had to get your task into HIPE
    • Start HIPE and verify that the task isn't there
    • Select Tools --> Plug-ins --> Install New
    • Click the browse icon and look for your SmartTask_0.1.jar. Install it.
    • You're done! Restart HIPE to see your Task in action.

If you thought that was easy, have a look at the slightly more advanced topics to find out how to automatically enable and disable your plug-in, depending on the HIPE version the user is running at the time (for compatibility reasons) and how to allow your users to get automatic notifications of new versions of your plug-in.

If that wasn't easy, please do let me know.

So... What if your task was in Java? You apply the above recipe with the following changes:

  • Create a JAR file with the .class files for your task inside (this might be only one file if you have only one class).
  • Create a subdirectory called jars and copy the JAR file there.
  • Modify the as follows:
    • Remove the sections "Find the base directory of the plug-in" and "Import the task"
    • Instead, import the task as you would in Java (from import MyTask)
  • That's all.

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

Organizing your into several shorter scripts

If your growse large, it becomes difficult to maintain. You can organize the into several files and call these from the script as follows. First, you have to find the directory in which your plug-in is installed. The next few lines assign this directory to the variable basedir:

from herschel.ia.gui.apps.plugin import PluginRegistry
reg = PluginRegistry.getInstance()

name = 'myPluginName' # fill in the name of the plug-in here
plugin = reg.get(name)
basedir = plugin.pluginDir.absolutePath

Using this base directory, you can execute scripts in your plug-in using the execfile command:

execfile(basedir + '/')
execfile(basedir + '/')
execfile(basedir + '/')

Note that you can store these scripts in subdirectories within your plug-in as well.

Compatibility information

It is highly recommended to include a file called plugin.xml at the top-level (root directory) of your plug-in and use it to specify the compatible HIPE versions. You do this by specifying a minimum version which with HIPE is compatible, and a maximum version. You should always specify a maximum version, because you don't know if your plug-in will be compatible with the next version of HIPE. If you distribute a plug-in when HIPE v1.0 is current, you should specify that is compatible with versions up to 1.0.*. This means that your plug-in is compatible with all builds from the 1.0 track, which means all 1.x releases. This is correct, because if 1.1 has been released now, and your plug-in is compatible, you know that it will be compatible with release 1.2 as well. No compatible changes are allowed in existing release tracks.

Note that the version is specified using build track plus build number, not with the release number. So, for example, release 4.6 was built on the 4.0 track and it's build 1467. In the version compatibility information in plugin.xml you would specify release 4.6 as 4.0.1467.

The plugin.xml allows for much more customization. An example plugin.xml, which includes compatibility information, is given in the next section.

You can also specify (for instance) "all builds on the 5.0 track", using "5.0.*". Note, however, the asterisk is not a wildcard. It's interpreted as a very high number, so it is only intended to be used to specify the upper limit of compatible versions (maxVersion). Using it in the lower limit, minVersion, is allowed, but this is normally not what you want. See the example in the next section.

Warning, important The compatibility checking was added in HIPE v7.0. Earlier versions of HIPE ignore this information.

Customizing your plug-in

HIPE allows for the plug-in to specify additional information about itself using a file called plugin.xml at the root-level of the plug-in jar or zip.

Below is an example of plugin.xml file with some of the different elements it can have:

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns:em="">

   <description>This plug-in provides tasks for analysis of data.</description>

   <!-- Compatible starting user release 5.0 (build 1760), not with earlier builds -->
   <!-- Compatible with all 6.x releases (all builds from the 6.0 track) -->



All of the elements of this XML file are optional, except <plugin>. If you're not interested in any of the elements, just don't add this file.

The description and the contributors page are shown on the plug-in details panel. In HIPE, select Plug-ins from the Tools menu. Select a plug-in (if you have one installed!) and click "Details".

The icon is used on the Plug-ins panel (the one that opens when you select Plug-ins from the Tools menu in HIPE). The value is the location of a "resource" on the classpath. The value given here gives the default plug-in icon, which is a green puzzle piece. To add your own icon, add it to a jar, add the jar to the jars directory and specify the filename of the icon in the plugin.xml.

The properties elements specifies a properties file in the plug-in, containing properties that are loaded when the plug-in is started. The plug-in is started at HIPE start-up, unless it is disabled from the GUI. If the custom properties file contains properties that are already defined in the system, they are ignored and a warning is printed.

The compatibility information, minVersion, maxVersion, and also the updateURL will be explained later.

Adding a license

It is possible to add a license text to a plug-in. All you have to do is add a file called LICENSE.txt to the root-level of the plug-in. This license will be displayed on the License tab of the Plug-in details panel.

Adding a menu item to the Help menu

You may want to add an entry in HIPE's Help menu, that the user can use to get help about your plug-in specifically. One way to do this is to add a menu item that opens the web-browser on the user's system and directs it to an on-line resource (the Help section of your plug-in's homepage for instance). An example plug-in is attached. See the and the helpMenu.src.jar in this plug-in for the source code of this example.

Using your plug-in under jylaunch

HIPE plug-ins are centered, logically, on HIPE. You need HIPE to install them (unless you know and perform all installation steps manually), and they are installed in a HIPE-specific directory. Note that HIPE is one HCSS application, and jylaunch is an entirely different HCSS application. Even so, jylaunch loads and activates plug-ins when it starts in much the same way as HIPE does.

For example, if your plug-in contains a script defining some Tasks and it also contains some data pools, and you have installed your plug-in using HIPE, then you will be able to use these Tasks and the data from a script that is run with jylaunch.

However, there is a difference between scripts run under HIPE and under jylaunch, which can have the effect that a plug-in cannot be correctly started under jylaunch, because its initialization script does not run. The difference is that HIPE at start-up first imports all Herschel code, using the general Herschel import statement:

from herschel.all import *

A typical error caused by not having imported all Herschel code is:

NameError: TableDataset

TableDataset is a class that is readily imported after start-up, in HIPE, but not under jylaunch. To make a plug-in work under jylaunch, the recommended approach is to import the classes that are needed at the start of the file. You can also use the above general Herschel import statement, but note that it takes significant time to execute.

Advanced topics

The plug-in installation process

The standard plug-in installation process just decompresses the plug-in into the plug-in directory and "starts" the plug-in. The plug-in directory is $HOME/.hcss/apps/hipe/plugins/[name]/[version]. You can view this directory by opening the plug-ins panel in HIPE (select Plug-ins from the Tools menu). Click the plug-in and select "Browse plug-in" from the View menu in the plug-ins panel.

Starting the plug-in means:

  • add all JARs to the Java and Jython class-loader(s)
  • load the custom properties
  • execute the initialization script, load
  • add the menu items for the user scripts
  • execute any registered PluginProcessors (see below)

In this order.

In general, the installation process of a plug-in consists of two steps or phases. For simple plug-ins, such as have been described until now, the second phase is skipped. Only the first phase, which is called "bootstrap", is executed. During this bootstrap installation, the plug-in is downloaded from the URL that indicates its location, and the jar or zip is decompressed in the plug-in directory. Note that the directory, that the plug-in is unpacked into, contains the version of the plug-in. This means that multiple versions of a plug-in can exist on a user's disk, but when HIPE starts, only the latest version of each plug-in will be started.

The second phase is called "custom installation". This allows the plug-in developer to execute an external installation program and dynamically configure the plug-in. For example, one can run a complete, separate installation program during this step, which installs an external Java program somewhere on the user's disk. Then for this plug-in to contribute something to HIPE, probably the JARs of the external program have to be added to the HIPE classpath. This can be done during this phase as well.

Using a custom installer

To run a custom installer during phase 2, you can add a class called Installer to the plug-in top-level dir. This class must implement the interface herschel.ia.gui.apps.plugin.Installer and it must be in the default package (i.e. no package).

After completion of phase 1, the install(PluginEnv) method of this interface is called. This method could call the main method of the installation program, included in the jars directory. When this completes, the Installer could add references to external JARs that were just installed. The method addJar of the PluginEnv class can be used to do that.


The Plug-ins panel in HIPE, from the Edit menu, allows to "remove a plug-in completely" or to "roll back to a previous version". This means to remove either all versions or just the latest one, undoing in effect the bootstrap installation. There is no way to run a "custom uninstaller" explicitly.

Enabling and disabling plug-ins

The Plug-ins panel in HIPE also allows to "disable" or to "enable" a plug-in (depending on whether it is currently enabled or disabled). A disabled plug-in is simply not started. It is loaded into the Plug-in Registry (see below), but it is not started.

The disabled or enabled status is persisted to disk, so that if a plug-in is disabled or enabled, it will still be in that state when HIPE is restarted.

Loading classes from included JARs

Normally, when including one or more JARs in your plug-in, you don't have to worry about class paths, class loaders, etcetera. If you import and instantiate a class from such a JAR using Jython or in Java, this will work as normal.

The exception is when you explicitly use a class loader to load a class. Suppose you include a JAR with a JDBC driver to connect to a relational database. Typically you will have to load the driver by its class name, to be able to use it. To be able to load such a class, which is in a JAR that is not on the standard Java class path but inside a plug-in, you must use a class loader that knows about this JAR. The recommended way to do this is to use the ObjectUtil class:

// to get the Class object:
Class<?> c = ObjectUtil.getClass("my.package.MyClass");
// or to create an object of this class
my.package.MyClass object = ObjectUtil<my.package.MyClass>.newInstance("my.package.MyClass");

The newInstance method uses the default constructor. If you need to use a different constructor, use the Class object.

Automatic Updates

The plug-in author has two ways to provide the users with updates: It is possible to update the compatibility of plug-ins that users have installed, and it is possible to offer users new versions of plug-ins.

If a plug-in was released before HIPE v6 was released, its plugin.xml should state that it is compatible up to and including HIPE "5.0.*". When the first version (release candidate?) of HIPE v6 comes out, the author should check if the existing version of the plug-in is still compatible with HIPE v6. Normally, this will be the case. If so, the author will want to update the compatibility information in the plug-in on the user's disk, to include compatibility with HIPE v6.

The point of offering new versions of plug-ins is self-evident.

The mechanism to provide this information relies on the plug-in registry, which is an XML file on a web-server. This XML file should contain entries for the available versions of the plug-in, plus the compatibility information of each version. Such a registry file could look as follows:

<?xml version="1.0" encoding="UTF-8"?>

<RDF:RDF xmlns:RDF=""

  <!-- This Description includes all the update and compatibility information for a
       single plug-in called "example1". You can list information for multiple plug-ins in
       the same file. -->
  <!-- NOTE The value of the "about" attribute is not a description but the name of the plug-in! -->
  <RDF:Description about="example1">

        <!-- Each "li" entry is a different version of the same plug-in -->
            <em:version>2.2</em:version> <!-- This is the version number of the plug-in -->


           <!-- This is where this version of the plug-in will be downloaded from -->




           <!-- This is where this version of the plug-in will be downloaded from -->




The above example registry file lists two versions of a plug-in called "example1": Version 2.2 and 2.3. Version 2.2 is stated to be compatible with HIPE v5.0 (the user release, not earlier builds) and also all builds of the 6.0 track. Version 2.3 is compatible version HIPE release 6.0 starting RC1 and all succeeding builds.

Should HIPE v7 be released and version 2.3 of the plug-in turns out to be compatible, then the author should update the "maxVersion" of version 2.3 to "7.0.*". HIPE instances that have the plug-in "example1" installed will check the registry file at start-up and update the information if necessary.

If version 2.4 of the plug-in is released, it can also simply be added to the registry. HIPE instances having the plug-in installed will suggest the update to the user, if the version of HIPE is compatible.

The only pending question is how HIPE instances that have the plug-in "example1" installed find the registry. The answer is: Via an "updateLink" reference in the plugin.xml.


For examples, see DpHipePlugins. Any of the plug-ins can be downloaded and inspected using the jar tool or any other zip program. Among examples offered are:

  • SPIA: This plug-in contains:
    • A HIPE SPIA perspective
    • An initialization script defining Tasks. This initialization scripts also has the registration for the perspective at the bottom.
  • The "demonstration plug-in" contains:
    • A more fully-featured plug-in descriptor file, plugin.xml
    • An initialization script
    • A few user scripts (the scripts themselves are trivial)
    • Custom properties that are added to the HIPE configuration
    • A custom installer for phase 2 ("custom installater" -- see advanced topics). The source code for this installer is also included, this is for your convenience only.
    • A license

For HIPE component developers: Working with plug-ins in HIPE

Some HIPE components may have to perform some actions when a plug-in is installed. For example, the Preferences panel is the one that picks up the pools from the plug-ins when they are installed. Such things are done by registering a PluginProcessor.

Once plug-ins have been installed and are started, HIPE components can find them in the Plug-in Registry (for example, the Plug-ins Panel that can be opened from the Tools menu).

PluginRegistry and Plugin class

The Plug-in Registry, implemented by the PluginRegistry class, is a singleton that allows access to all plug-ins currently installed (latest versions only). The elements that in the registry are of the Plugin class. They are keyed by the plug-in name and sorted alphabetically.

The Plugin class reflects the installed plug-in in its plug-in directory: It has accessors to get the information from the plugin.xml file, you can ask it which JARs and scripts the user has installed, etc. And finally, you can use this class to start, stop and enable/disable the plug-in. Starting and stopping is normally managed by HIPE though, so it is unlikely that you will need to call those methods.


You can implement the PluginProcessor interface (herschel.ia.gui.apps.plugin package) and register it on the PluginRegistry. This processor will be called when any plug-in is started (the onStart method) and also when any plug-in is stopped (onStop method).

In principle, all plug-ins are started when HIPE is started, and presumably you will also register your PluginProcessor when HIPE is started. This gives rise to a race condition: Depending on whether you manage to register the processor a little bit earlier or later, it may or may not get called for some of the plug-ins. This is solved by making sure that all PluginProcessors that are registered are also called for all plug-ins that have been started already. Effectively this simply means you do not have to worry about this; if you register your processor, it will be called for all plug-ins that have been started and those that will still be started during HIPE start-up.

-- PaulBalm - 27 Aug 2010

Topic attachments
I Attachment History Action Size Date Who CommentSorted ascending
Unknown file formatjar demoHelpMenu_1.0.jar r1 manage 6.4 K 2011-03-25 - 12:44 PaulBalm Plug-in demonstrating adding a Help menu item
Edit | Attach | Watch | Print version | History: r38 | r21 < r20 < r19 < r18 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r19 - 2011-10-17 - PaulBalm
This site is powered by the TWiki collaboration platform Powered by Perl