Difference: DpHipePluginsDeveloperManual (1 vs. 37)

Revision 372016-07-27 - JaimeSaiz

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 167 to 157
  This plug-in provides tasks for analysis of data. http://www.esa.int
Changed:
<
<
herschel/ia/gui/apps/plugin/Extension.png
>
>
herschel/ia/gui/apps/plugin/Extension_32x32.png
  custom.properties

<-- Compatible starting user release 5.0 (build 1760), not with earlier builds -->
Line: 183 to 173
  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".
Changed:
<
<
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 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. Icons not having 32x32 pixel resolution will be scaled to fit this size when shown in the plug-ins panel.
  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.

Revision 362016-04-19 - JaimeSaiz

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 25 to 25
 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:
Changed:
<
<
> jar cvf $HOME/myplugin_0.1.jar *
>
>
> jar cvf $HOME/myplugin_0.1.jar *
  The options to jar we used here are cvf: c for "create", v for "verbose" and f for filename.
Line: 44 to 43
 > mkdir pools
> cp -r $HOME/.hcss/lstore/poolA pools
> cp -r $HOME/.hcss/lstore/poolB pools
Changed:
<
<
> jar cf $HOME/myplugin_0.1.jar 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.
Changed:
<
<
When the plug-in is installed, the pools will appear in the Data Access section of the preferences (see Edit --> Preferences).
>
>
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.
Line: 64 to 62
 
> mkdir scripts
> cp ~/work/scriptsForPlugin/*.py scripts
Changed:
<
<
> jar cf $HOME/myplugin_0.1.jar 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 in 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.
Line: 76 to 73
 
> mkdir scripts
> cp ~/work/myTasks.py plugin.py
Changed:
<
<
> jar cf $HOME/myplugin_0.1.jar plugin.py
>
>
> jar cf $HOME/myplugin_0.1.jar plugin.py
  This plugin.py script is similar in function to the __init__.py script that is contained in many of the Java packages in the HCSS. However, the __init__.py must have some obligatory lines of code, which are not required for the plugin.py script.
Line: 88 to 84
 
> mkdir jars
> cp ~/work/out/library.jar jars
Changed:
<
<
> jar cf $HOME/myplugin_0.1.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:
Changed:
<
<
META-INF/

>
>
META-INF/

 META-INF/MANIFEST.MF jars/ jars/filtering.jar
Line: 104 to 98
 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.

Deleted:
<
<
Some hints on using the plug-in: Suppose that the filtering.jar contains two classes: my.filtering.FilterA and my.filtering.FilterB. If you run HIPE with your plug-in installed, you may want to import both filters using:

from my.filters import *

And this may give you an error:

<type 'exceptions.ImportError'>: No module named my

This can be solved with the command: import my

After that, "normal imports" like from my.filters import * will work.

To help your users, you may want to add the statement import my to your plugin.py file, so that it is already executed when HIPE starts.

 

How to create a plug-in with a Task

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. If your Task is in Java, please refer to MyFirstJavaTask and if it's in Jython, see MyFirstJythonTask on the HIPE Community Wiki. Both these pages start by explaining how to write a task in their respective language, and both pages contain a section "Turning the task into a HIPE plug-in".

Line: 130 to 107
 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:
Changed:
<
<
> jar cf $HOME/myplugin_0.1.jar *
>
>
> jar cf $HOME/myplugin_0.1.jar *
 

What you must avoid / Invalid plug-ins

Line: 153 to 128
  name = 'myPluginName' # fill in the name of the plug-in here plugin = reg.get(name)
Changed:
<
<
basedir = plugin.pluginDir.absolutePath
>
>
basedir = plugin.pluginDir.absolutePath
  Using this base directory, you can execute scripts in your plug-in using the execfile command:

execfile(basedir + '/a.py')
execfile(basedir + '/b.py')
Changed:
<
<
execfile(basedir + '/c.py')
>
>
execfile(basedir + '/c.py')
  Note that you can store these scripts in subdirectories within your plug-in as well.
Line: 205 to 177
  https://www.mysite.com/registry.xml
Changed:
<
<
>
>
  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.
Line: 235 to 206
 class ImportScanAmorphosTask(Task,ExternalHelp): # ... def getHelpURL(self):
Changed:
<
<
return String("http://herschel.esac.esa.int/twiki/bin/view/Public/ScanAmorphosPlugin")
>
>
return String("http://herschel.esac.esa.int/twiki/bin/view/Public/ScanAmorphosPlugin")
 Thus, by typing in console
Changed:
<
<
help(importScanAmorphos) pressing the task's GUI help button, or selecting the task in the Tasks view and selecting the Help -> Help (External) menu option, your browser will open the web page you have provided.
>
>
help(importScanAmorphos)

pressing the task's GUI help button, or selecting the task in the Tasks view and selecting the Help -> Help (External) menu option, your browser will open the web page you have provided.

Using preferences in your plug-in

 
Added:
>
>
A plug-in can use preferences as any other code integrated in HIPE.

It can also register custom preferences panels, which will be included in the preferences tree that is shown when executing Edit > Preferences.

ALERT! Warning:

Preferences cannot be read during the Jython initialization. For plugins, it means that trying to consult a preference while running the plugin.py would throw an IllegalStateException, for example:

from herschel.ia.gui.kernel.prefs import UserPreferences
print UserPreferences.get("MyPluginCategory", "myPreference") # Exception that prevents the plugin from correctly finalizing its initialization

Now, preferences can be accessed once HIPE start-up has finished. For that, schedule it like in this example:

from herschel.ia.gui.kernel import SiteApplication
from java.lang import Runnable

class PreferenceReader(Runnable):
    def run(self):
        from herschel.ia.gui.kernel.prefs import UserPreferences
        print UserPreferences.get("MyPluginCategory", "myPreference")

SiteApplication.getSite().runWhenStarted(PreferenceReader(), False)
 

Using your plug-in in HIPE batch mode (was: jylaunch)

Line: 249 to 244
 The jylaunch command was replaced in HIPE 11 by "HIPE batch mode", which is invoked simply by calling the hipe command, followed by the filename of the script to execute.

Plug-ins can be used in the same way in batch mode as from the GUI, with the same caveats as processing scripts. HIPE in batch mode does not load all Herschel classes on start-up, like the GUI does, to save time. The HIPE GUI executes the following command at start-up:

Deleted:
<
<
 
Changed:
<
<
from herschel.all import *
>
>
from herschel.all import *
  The fact that in batch mode this command is not executed, can lead to different problems. A typical error caused by not having imported all Herschel code is:
Deleted:
<
<
 
Changed:
<
<
NameError: TableDataset
>
>
NameError: TableDataset
  TableDataset is a class that is readily imported after start-up, in the GUI, but not in batch mode.
Line: 311 to 301
 // to get the Class object: Class<?> c = ObjectUtil.getClass("my.package.MyClass"); // or to create an object of this class
Changed:
<
<
my.package.MyClass object = ObjectUtil<my.package.MyClass>.newInstance("my.package.MyClass");
>
>
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.
Line: 371 to 359
 

Changed:
<
<
>
>
  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 future versions of HIPE.
Changed:
<
<
Contrary to earlier recommendations, I now recommend to specify that the latest (current) version of your plug-in is compatible with all future versions, by specifying an asterisk: *. If it it turns out that at some version of HIPE the plug-in does not work anymore, users can disable it manually and/or you can update the registry file to specify the new maximum. Experience shows this works better than specifying the current HIPE version as the maximum version, and updating it when new HIPE versions come out. Plug-ins tend to get blocked inadvertently.
>
>
Contrary to earlier recommendations, I now recommend to specify that the latest (current) version of your plug-in is compatible with all future versions, by specifying an asterisk: *. If it it turns out that at some version of HIPE the plug-in does not work anymore, users can disable it manually and/or you can update the registry file to specify the new maximum. Experience shows this works better than specifying the current HIPE version as the maximum version, and updating it when new HIPE versions come out. Plug-ins tend to get blocked inadvertently.
  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.
Line: 403 to 390
  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).
Changed:
<
<

PluginRegistry and Plugin class

>
>

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.
Line: 421 to 408
  Original author: Paul Balm - 27 Aug 2010
Added:
>
>

 
Deleted:
<
<

 
<-- COMMENT BOX CODE - DO NOT EDIT -->
Added:
>
>
 
Changed:
<
<
blog comments powered by Disqus
>
>
blog comments powered by Disqus
 
<-- END OF COMMENT BOX CODE -->
Changed:
<
<

>
>

</verbatim>
 
META FILEATTACHMENT attr="" autoattached="1" comment="Plug-in demonstrating adding a Help menu item" date="1301057081" name="demoHelpMenu_1.0.jar" path="demoHelpMenu_1.0.jar" size="6601" user="Main.PaulBalm" version="1"
META FILEATTACHMENT attr="h" autoattached="1" comment="Script for Google Analytics" date="1350656841" name="GoogleAnalytics.txt" path="GoogleAnalytics.txt" size="549" user="Main.DavideRizzo" version="1"

Revision 352015-02-17 - JaimeSaiz

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 289 to 289
  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.
Changed:
<
<
The custom installation is executed on the Swing Event Dispatch Thread (the "EDT"). Unless the custom installation specifically avoids this, HIPE will be blocked and not redrawn while the custom installation is in progress. If long operations are included in the custom installation process (meaning taking more than one or a few seconds), it is advisable to off-load this work to a background thread, for example using javax.swing.SwingWorker.
>
>
The custom installation is executed in a background thread. Note that it implies that any code related with GUIs would require an explicit call to be run in the EDT (Event Dispatching Thread), for example by means of SwingUtilities.invokeLater, EDT.run or EDT.call.
 

Uninstallation

Revision 342014-06-24 - AlvarGarcia

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 415 to 415
  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.
Added:
>
>

Further information

For any questions regarding plug-in development, please send an email to Alvar.Garcia@sciops.esa.int.

Original author: Paul Balm - 27 Aug 2010

 
Deleted:
<
<
-- PaulBalm - 27 Aug 2010
 
<-- COMMENT BOX CODE - DO NOT EDIT -->

Revision 332014-02-13 - AlvarGarcia

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 15 to 15
 

Quick Guide: Creating Simple Plug-ins

Changed:
<
<
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.
>
>
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 possibly 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

Line: 28 to 28
 > jar cvf $HOME/myplugin_0.1.jar *
Changed:
<
<
The options to jar we used here are cvf: c for "create", v for "verbose" and f fore filename.
>
>
The options to jar we used here are cvf: c for "create", v for "verbose" and f for 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.
Line: 67 to 67
 > jar cf $HOME/myplugin_0.1.jar scripts
Changed:
<
<
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.
>
>
When this plug-in is installed, a menu item with the name of the plug-in will appear in 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 plugin.py and it must be at the top or root-level of the jar or zip.
Line: 103 to 103
  This plug-in contains a JAR called filtering.jar, which in turn might contain any number of Java classes.
Changed:
<
<
For information on how to create a JAR file with your Java code, see the JAR Documentation.
>
>
For information on how to create a JAR file with your Java code, see the JAR Documentation.
  Some hints on using the plug-in: Suppose that the filtering.jar contains two classes: my.filtering.FilterA and my.filtering.FilterB. If you run HIPE with your plug-in installed, you may want to import both filters using:
Line: 145 to 145
 

Organizing your plugin.py into several shorter scripts

Changed:
<
<
If your plugin.py growse large, it becomes difficult to maintain. You can organize the plugin.py into several files and call these from the plugin.py 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:
>
>
If your plugin.py grows large, it becomes difficult to maintain. You can organize the plugin.py into several files and call these from the plugin.py 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
Line: 174 to 174
  Here we will describe how to include compatibility information inside the plug-in itself, but if you can, it's advisable to use a plug-in version registry. This is described in the section Automatic Updates below.
Changed:
<
<
Compatible HIPE versions are specified giving a minimum version which with HIPE is compatible, and a maximum version. Experience shows that unless you already know that the latest HIPE version is incompatible, it's best to specify * as the maximum compatible version. Otherwise you will have to regularly update the maximum version to allow for new HIPE versions. It's less maintenance to act when an incompatibility is found, and specify a maximum version at that time.
>
>
Compatible HIPE versions are specified giving a minimum version with which HIPE is compatible, and a maximum version. Experience shows that unless you already know that the latest HIPE version is incompatible, it's best to specify * as the maximum compatible version. Otherwise you will have to regularly update the maximum version to allow for new HIPE versions. It's less maintenance to act when an incompatibility is found, and specify a maximum version at that time.
  Specifying a minimum version of 1.0.* and maximum version of * means that your plug-in is compatible with all builds from the 1.0 track, and all future versions. 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. If an incompatibility is introduced in HIPE in build 1000 on the 4.0 track, then your maximum version should be set to 4.0.999.
Line: 394 to 394
 
    • An initialization script
    • A few user scripts (the scripts themselves are trivial)
    • Custom properties that are added to the HIPE configuration
Changed:
<
<
    • 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 custom installer for phase 2 ("custom installer" -- 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

Revision 322013-10-18 - JavierDiaz

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 123 to 123
 

How to create a plug-in with a Task

Changed:
<
<
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. If your Task is in Java, please refer to MyFirstJavaTask and if it's in Jython, see MyFirstJythonTask no the HIPE Community Wiki. Both these pages start by explaining how to write a task in their respective language, and both pages contain a section "Turning the task into a HIPE plug-in".
>
>
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. If your Task is in Java, please refer to MyFirstJavaTask and if it's in Jython, see MyFirstJythonTask on the HIPE Community Wiki. Both these pages start by explaining how to write a task in their respective language, and both pages contain a section "Turning the task into a HIPE plug-in".
 

Combinations of the above

Line: 228 to 228
  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 plugin.py and the helpMenu.src.jar in this plug-in for the source code of this example.
Added:
>
>

Linking to external help pages

To provide more integrated help, you can link an external web page to your tasks (for example) by implementing herschel.ia.gui.kernel.parts.ExternalHelp.

class ImportScanAmorphosTask(Task,ExternalHelp):
# ...
  def getHelpURL(self):
        return String("http://herschel.esac.esa.int/twiki/bin/view/Public/ScanAmorphosPlugin")
Thus, by typing in console
help(importScanAmorphos)
pressing the task's GUI help button, or selecting the task in the Tasks view and selecting the Help -> Help (External) menu option, your browser will open the web page you have provided.
 

Using your plug-in in HIPE batch mode (was: jylaunch)

The jylaunch command was replaced in HIPE 11 by "HIPE batch mode", which is invoked simply by calling the hipe command, followed by the filename of the script to execute.

Revision 312013-05-07 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 138 to 138
 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:

Changed:
<
<
  • 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.
>
>
  • a file called scripts, pools, bundle.xml or jars at the top-level of the file
 

Slightly more advanced topics

Line: 229 to 228
  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 plugin.py and the helpMenu.src.jar in this plug-in for the source code of this example.
Changed:
<
<

Using your plug-in under jylaunch

>
>

Using your plug-in in HIPE batch mode (was: jylaunch)

 
Changed:
<
<
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.
>
>
The jylaunch command was replaced in HIPE 11 by "HIPE batch mode", which is invoked simply by calling the hipe command, followed by the filename of the script to execute.
 
Changed:
<
<
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:

>
>
Plug-ins can be used in the same way in batch mode as from the GUI, with the same caveats as processing scripts. HIPE in batch mode does not load all Herschel classes on start-up, like the GUI does, to save time. The HIPE GUI executes the following command at start-up:
 
from herschel.all import *
Changed:
<
<
A typical error caused by not having imported all Herschel code is:
>
>
The fact that in batch mode this command is not executed, can lead to different problems. A typical error caused by not having imported all Herschel code is:
 
NameError: TableDataset
Changed:
<
<
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 plugin.py file. You can also use the above general Herschel import statement, but note that it takes significant time to execute.
>
>
TableDataset is a class that is readily imported after start-up, in the GUI, but not in batch mode.

To make a plug-in work in batch mode, the recommended approach is to import the classes that are needed at the start of the plugin.py file. You can also use the above general Herschel import statement, but note that it takes significant time to execute.

 

Advanced topics

Revision 302013-05-07 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->

<-- END OF ANALYTICS CODE -->
Changed:
<
<

Plug-in Author Manual

>
>

Plug-in Author 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.

Revision 292013-05-06 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 123 to 123
 

How to create a plug-in with a Task

Changed:
<
<
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. If your Task is in Java, please refer to MyFirstJavaTask and if it's in Jython, see MyFirstJythonTask. Both these pages start by explaining how to write a task in their respective language, and both pages contain a section "Turning the task into a HIPE plug-in".
>
>
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. If your Task is in Java, please refer to MyFirstJavaTask and if it's in Jython, see MyFirstJythonTask no the HIPE Community Wiki. Both these pages start by explaining how to write a task in their respective language, and both pages contain a section "Turning the task into a HIPE plug-in".
 

Combinations of the above

Line: 420 to 420
 
<-- END OF COMMENT BOX CODE -->

Deleted:
<
<
META FILEATTACHMENT attr="h" autoattached="1" comment="Script for Google Analytics" date="1350656841" name="GoogleAnalytics.txt" path="GoogleAnalytics.txt" size="549" user="Main.DavideRizzo" version="1"
 
META FILEATTACHMENT attr="" autoattached="1" comment="Plug-in demonstrating adding a Help menu item" date="1301057081" name="demoHelpMenu_1.0.jar" path="demoHelpMenu_1.0.jar" size="6601" user="Main.PaulBalm" version="1"
Added:
>
>
META FILEATTACHMENT attr="h" autoattached="1" comment="Script for Google Analytics" date="1350656841" name="GoogleAnalytics.txt" path="GoogleAnalytics.txt" size="549" user="Main.DavideRizzo" version="1"

Revision 282013-01-31 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 105 to 105
  For information on how to create a JAR file with your Java code, see the JAR Documentation.
Added:
>
>
Some hints on using the plug-in: Suppose that the filtering.jar contains two classes: my.filtering.FilterA and my.filtering.FilterB. If you run HIPE with your plug-in installed, you may want to import both filters using:

from my.filters import *

And this may give you an error:

<type 'exceptions.ImportError'>: No module named my

This can be solved with the command: import my

After that, "normal imports" like from my.filters import * will work.

To help your users, you may want to add the statement import my to your plugin.py file, so that it is already executed when HIPE starts.

 

How to create a plug-in with a Task

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. If your Task is in Java, please refer to MyFirstJavaTask and if it's in Jython, see MyFirstJythonTask. Both these pages start by explaining how to write a task in their respective language, and both pages contain a section "Turning the task into a HIPE plug-in".

Line: 349 to 365
  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.
Changed:
<
<
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.
>
>
The only pending question is how HIPE instances that have the plug-in "example1" installed find the registry. The answer is: Via an "updateURL" reference in the plugin.xml.
 

Examples

Line: 404 to 420
 
<-- END OF COMMENT BOX CODE -->

Deleted:
<
<
META FILEATTACHMENT attr="" autoattached="1" comment="Plug-in demonstrating adding a Help menu item" date="1301057081" name="demoHelpMenu_1.0.jar" path="demoHelpMenu_1.0.jar" size="6601" user="Main.PaulBalm" version="1"
 
META FILEATTACHMENT attr="h" autoattached="1" comment="Script for Google Analytics" date="1350656841" name="GoogleAnalytics.txt" path="GoogleAnalytics.txt" size="549" user="Main.DavideRizzo" version="1"
Added:
>
>
META FILEATTACHMENT attr="" autoattached="1" comment="Plug-in demonstrating adding a Help menu item" date="1301057081" name="demoHelpMenu_1.0.jar" path="demoHelpMenu_1.0.jar" size="6601" user="Main.PaulBalm" version="1"

Revision 272013-01-17 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 153 to 153
 

Compatibility information

Changed:
<
<
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.
>
>
In general, each version of the plug-in will be compatible with a range of HIPE versions. Maybe version 1.0 to 1.7 of the plug-in is compatible with HIPE 7 to 9, but then for version 2.0 of the plug-in, the plug-in was redesigned, and it's only compatible with HIPE version 10 and up. Or an incompatible change was introduced in HIPE that made that the plug-in versions 1.7 and below stopped working. It's possible to specify this information precisely, either in the plug-in itself, or in an XML file that is accessible from the web, called the plug-in version registry. The advantage of putting the information into the plug-in version registry is that you as plug-in author can update it whenever you want. HIPE will retrieve this information automatically upon start-up and it will take priority over information that was included in the plug-in.
 
Changed:
<
<
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.
>
>
If a plug-in is said not to be compatible with the HIPE version that you're starting, then HIPE will disable the plug-in, to prevent problems. If you exit HIPE and start a (older?) version of HIPE that is compatible, then the plug-in will be enabled normally. Or, if you're running two different versions of HIPE at the same time, then your plug-in might be enabled in one version and disabled in another. Also, following the above example, suppose you run HIPE 9 and version 1.7 of the plug-in, then upgrade to HIPE 10 and version 2.0 of the plug-in. Then, as long as you don't explicitly remove plug-in versions, starting HIPE 9 will start with version 1.7 of the plug-in enabled (the highest compatible version), whereas HIPE 10 will start normally with version 2.0 of the plug-in.
 
Changed:
<
<
The plugin.xml allows for much more customization. An example plugin.xml, which includes compatibility information, is given in the next section.
>
>
Here we will describe how to include compatibility information inside the plug-in itself, but if you can, it's advisable to use a plug-in version registry. This is described in the section Automatic Updates below.

Compatible HIPE versions are specified giving a minimum version which with HIPE is compatible, and a maximum version. Experience shows that unless you already know that the latest HIPE version is incompatible, it's best to specify * as the maximum compatible version. Otherwise you will have to regularly update the maximum version to allow for new HIPE versions. It's less maintenance to act when an incompatibility is found, and specify a maximum version at that time.

Specifying a minimum version of 1.0.* and maximum version of * means that your plug-in is compatible with all builds from the 1.0 track, and all future versions. 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. If an incompatibility is introduced in HIPE in build 1000 on the 4.0 track, then your maximum version should be set to 4.0.999.

Finally, it should be noted that 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.

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

 
Deleted:
<
<
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.
 

Customizing your plug-in

Revision 262012-11-26 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->
Line: 161 to 161
  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.
Deleted:
<
<
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.

Line: 180 to 178
 
<-- Compatible starting user release 5.0 (build 1760), not with earlier builds -->
5.0.1760
Changed:
<
<
<-- Compatible with all 6.x releases (all builds from the 6.0 track) -->
6.0.*
>
>
<-- Compatible with all future HIPE versions -->
*
  https://www.mysite.com/registry.xml
Line: 323 to 321
  2.3

6.0.1883

Changed:
<
<
6.0.*
>
>
*
 
<-- This is where this version of the plug-in will be downloaded from -->
https://www.mysite.com/example1_2.3.jar
Line: 338 to 336
 
Changed:
<
<
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.
>
>
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 future versions of HIPE.
 
Changed:
<
<
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.
>
>
Contrary to earlier recommendations, I now recommend to specify that the latest (current) version of your plug-in is compatible with all future versions, by specifying an asterisk: *. If it it turns out that at some version of HIPE the plug-in does not work anymore, users can disable it manually and/or you can update the registry file to specify the new maximum. Experience shows this works better than specifying the current HIPE version as the maximum version, and updating it when new HIPE versions come out. Plug-ins tend to get blocked inadvertently.
  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.

Revision 252012-10-19 - DavideRizzo

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
Added:
>
>
<-- ANALYTICS CODE - DO NOT EDIT -->
<-- Google Analytics script BEGIN -->
<-- Google Analytics script END -->

<-- END OF ANALYTICS CODE -->
 

Plug-in Author Manual

Line: 396 to 399
 
<-- END OF COMMENT BOX CODE -->

Changed:
<
<
META FILEATTACHMENT attachment="demoHelpMenu_1.0.jar" attr="" comment="Plug-in demonstrating adding a Help menu item" date="1301057081" name="demoHelpMenu_1.0.jar" path="demoHelpMenu_1.0.jar" size="6601" stream="demoHelpMenu_1.0.jar" user="Main.PaulBalm" version="1"
>
>
META FILEATTACHMENT attr="" autoattached="1" comment="Plug-in demonstrating adding a Help menu item" date="1301057081" name="demoHelpMenu_1.0.jar" path="demoHelpMenu_1.0.jar" size="6601" user="Main.PaulBalm" version="1"
META FILEATTACHMENT attr="h" autoattached="1" comment="Script for Google Analytics" date="1350656841" name="GoogleAnalytics.txt" path="GoogleAnalytics.txt" size="549" user="Main.DavideRizzo" version="1"

Revision 242012-09-07 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Author Manual

Line: 195 to 195
  The compatibility information, minVersion, maxVersion, and also the updateURL will be explained later.
Changed:
<
<

Adding a license

>
>

Adding a license and/or release notes

  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.
Added:
>
>
For release notes, it works the same way: Add a file called RELEASE_NOTES.txt to the root-level of the plug-in. The contents of this file will be displayed on the Release Notes tab of the details panel of the plug-in.
 

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 plugin.py and the helpMenu.src.jar in this plug-in for the source code of this example.

Revision 232012-05-14 - DavideRizzo

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Author Manual

Line: 377 to 377
  -- PaulBalm - 27 Aug 2010
Added:
>
>

<-- COMMENT BOX CODE - DO NOT EDIT -->
blog comments powered by Disqus
<-- END OF COMMENT BOX CODE -->

 
META FILEATTACHMENT attachment="demoHelpMenu_1.0.jar" attr="" comment="Plug-in demonstrating adding a Help menu item" date="1301057081" name="demoHelpMenu_1.0.jar" path="demoHelpMenu_1.0.jar" size="6601" stream="demoHelpMenu_1.0.jar" user="Main.PaulBalm" version="1"

Revision 222012-01-17 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Author Manual

Line: 248 to 248
  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.
Added:
>
>
The custom installation is executed on the Swing Event Dispatch Thread (the "EDT"). Unless the custom installation specifically avoids this, HIPE will be blocked and not redrawn while the custom installation is in progress. If long operations are included in the custom installation process (meaning taking more than one or a few seconds), it is advisable to off-load this work to a background thread, for example using javax.swing.SwingWorker.
 

Uninstallation

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.

Revision 212011-11-15 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Author Manual

Line: 102 to 102
  For information on how to create a JAR file with your Java code, see the JAR Documentation.
Changed:
<
<

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

>
>

How to create a plug-in with a Task

 
Changed:
<
<
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 myTask.py.
  • In the same directory, create a file called plugin.py with the following contents (edit as needed):

### EDIT here
name='SmartTask'
taskFileName='myTask.py'
### 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 plugin.py 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 my.package.name import MyTask)
  • That's all.
>
>
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. If your Task is in Java, please refer to MyFirstJavaTask and if it's in Jython, see MyFirstJythonTask. Both these pages start by explaining how to write a task in their respective language, and both pages contain a section "Turning the task into a HIPE plug-in".
 

Combinations of the above

Revision 202011-10-21 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"
Changed:
<
<

Plug-in Developer Manual

>
>

Plug-in Author 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.

Revision 192011-10-17 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 102 to 102
  For information on how to create a JAR file with your Java code, see the JAR Documentation.
Added:
>
>

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 myTask.py.
  • In the same directory, create a file called plugin.py with the following contents (edit as needed):

### EDIT here
name='SmartTask'
taskFileName='myTask.py'
### 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 plugin.py 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 my.package.name import MyTask)
  • That's all.
 

Combinations of the above

Revision 182011-06-27 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 289 to 289
 
<-- 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. -->
Added:
>
>
<-- NOTE The value of the "about" attribute is not a description but the name of the plug-in! -->
 

Revision 172011-03-25 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 196 to 196
  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.
Added:
>
>

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 plugin.py 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.

Line: 366 to 370
 

-- PaulBalm - 27 Aug 2010

Added:
>
>
META FILEATTACHMENT attachment="demoHelpMenu_1.0.jar" attr="" comment="Plug-in demonstrating adding a Help menu item" date="1301057081" name="demoHelpMenu_1.0.jar" path="demoHelpMenu_1.0.jar" size="6601" stream="demoHelpMenu_1.0.jar" user="Main.PaulBalm" version="1"

Revision 162011-03-23 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 122 to 122
 

Slightly more advanced topics

Added:
>
>

Organizing your plugin.py into several shorter scripts

If your plugin.py growse large, it becomes difficult to maintain. You can organize the plugin.py into several files and call these from the plugin.py 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 + '/a.py')
execfile(basedir + '/b.py')
execfile(basedir + '/c.py')

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.

Revision 152011-03-09 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 12 to 12
 

Quick Guide: Creating Simple Plug-ins

Changed:
<
<
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.
>
>
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

Line: 209 to 210
  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.
Changed:
<
<
The second phase is called "custom installation". During this phase, a complete, stand-alone installation program can be executed. Often such programs are Java WebStart programs, but you can also include the installation program in the plug-in itself. If you want to include the custom installation in the plug-in, see the next section for details. If you want to use a WebStart installation program, see the section "Using a WebStart installer".

The third and final phase is called "configuration". This allows the plug-in developer to execute some steps after the custom installation. For example, if the custom installation 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 step. How, is described in the section "Configuring the plug-in post-installation".

While phase 1 is always executed, phase 2 and 3 are optional and independently optional: You can create a plug-in that does something during phase 2 but not during phase 3, and vice versa.

There is currently no mechanism to check for successful completion of the custom installation programs, executed during phase 2.

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

Changed:
<
<
This section explains how to run a custom program during phase 2 of the plug-in installation.

First, the plug-in must contain a file plugin.xml at the root-level of the jar or zip, with at least the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
   <installer className="MyCustomInstaller" />
</plugin>

And second, a .class file (a compiled Java file) containing the class MyCustomInstaller should be added to the plug-in, also at the root-level of the jar/zip.

The name of the class can be any legal class name except "Installer", because this used for the class that is executed in phase 3. The package must be the default package, i.e. no package.

The class must have either a regular main method, or it can implement the interface herschel.ia.gui.apps.plugin.Installer. If the latter is chosen, the method install(PluginEnv) will be called to execute the installer, which has the advantage that the installer gets access to several properties of the plug-in via the PluginEnv object that is passed as an argument.

>
>
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).
 
Changed:
<
<

Using a WebStart installer

To run a WebStart installer during phase 2 of the plug-in installation, the plug-in must contain a file plugin.xml at the root-level of the jar or zip, with at least the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
   <installer url="http://www.esa.int/webstartfile.jnlp" />
</plugin>

The URL should point to the JNLP file of the WebStart program, which is an XML file that tells Java WebStart where the JARs of the WebStart program are found and which class contains the main method, among other things. The JNLP file can also be used to pass properties to the WebStart program: If you need to pass special properties to the installer, if it is run from a plug-in installation process, then we recommend to create a separate JNLP file for this case. That is, one JNLP file for the normal, stand-alone installation of the program, and one JLNP file when the installation happens as part of the installation process of a plug-in. The second file can then contain some additional properties, to tailor the installation.

Configuring the plug-in post-installation

To perform some steps after completion of 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 2 (whether anything was actually done is irrelevant), the install(PluginEnv) method of this interface is called.

As said before, this can be used for example to add references to external JARs installed during phase 2. For this example you can use the method addJar of the PluginEnv class.

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

Uninstallation

Changed:
<
<
The Plug-ins panel in HIPE shows a button "Uninstall". Clicking this button will simply delete the plug-in directory (all versions). It undoes, in effect, phase 1 of all installations of a given plug-in.

There is no way to undo phases 2 and/or 3 of the installation process. No custom uninstaller can be configured.

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

Line: 361 to 320
 
    • An initialization script
    • A few user scripts (the scripts themselves are trivial)
    • Custom properties that are added to the HIPE configuration
Changed:
<
<
    • A custom installer for phase 3 ("configuration" -- see advanced topics). The source code for this installer is also included, this is for your convenience only.
>
>
    • 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

Revision 142011-03-09 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 196 to 196
 

The plug-in installation process

Changed:
<
<
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). Select the plug-in and click Browse.
>
>
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:
Changed:
<
<
  • add all JARs to the Java classpath and the Jython system path
>
>
  • 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
Line: 204 to 204
 
  • execute the initialization script, load
  • add the menu items for the user scripts
  • execute any registered PluginProcessors (see below)
Added:
>
>
 In this order.
Changed:
<
<
In general, the installation process of a plug-in consists of three steps or phases. For simple plug-ins, such as have been described until now, nothing is done during the second and third phase. Only the first phase, which is called "bootstrap", is executed. During this 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. Not 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.
>
>
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". During this phase, a complete, stand-alone installation program can be executed. Often such programs are Java WebStart programs, but you can also include the installation program in the plug-in itself. If you want to include the custom installation in the plug-in, see the next section for details. If you want to use a WebStart installation program, see the section "Using a WebStart installer".

Revision 132011-02-21 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 38 to 38
 
> mkdir pools
Changed:
<
<
> cp -r $HOME/.hcss/lstore/poolA
> cp -r $HOME/.hcss/lstore/poolB
>
>
> cp -r $HOME/.hcss/lstore/poolA pools
> cp -r $HOME/.hcss/lstore/poolB pools
 > jar cf $HOME/myplugin_0.1.jar pools

Revision 122011-01-20 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 328 to 328
  6.0.*

<-- This is where this version of the plug-in will be downloaded from -->
Changed:
<
<
https://www.mysite.com/example1_2.2.jar
>
>
https://www.mysite.com/example1_2.3.jar
 

Revision 112011-01-13 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Revision 102011-01-13 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 153 to 153
 
<-- Compatible with all 6.x releases (all builds from the 6.0 track) -->
6.0.*
Added:
>
>
https://www.mysite.com/registry.xml
 
Line: 164 to 166
  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.
Added:
>
>
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.

Line: 279 to 283
  The newInstance method uses the default constructor. If you need to use a different constructor, use the Class object.
Added:
>
>

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="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:em="http://www.mozilla.org/2004/em-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. -->
  <RDF:Description about="example1">
    <em:updates>
      <RDF:Seq>

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

            <em:minVersion>5.0.1760</em:minVersion>
            <em:maxVersion>6.0.*</em:maxVersion>

           <!-- This is where this version of the plug-in will be downloaded from -->
           <em:updateLink>https://www.mysite.com/example1_2.2.jar</em:updateLink>

          </RDF:Description>
        </RDF:li>

        <RDF:li>
          <RDF:Description>
            <em:version>2.3</em:version>

            <em:minVersion>6.0.1883</em:minVersion>
            <em:maxVersion>6.0.*</em:maxVersion>

           <!-- This is where this version of the plug-in will be downloaded from -->
           <em:updateLink>https://www.mysite.com/example1_2.2.jar</em:updateLink>

          </RDF:Description>
        </RDF:li>

      </RDF:Seq>
    </em:updates>

  </RDF:Description>
</RDF:RDF>

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.

 

Examples

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:

Revision 92011-01-12 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 116 to 115
 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:

Changed:
<
<
- 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.
>
>
  • 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

Added:
>
>

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.

Line: 130 to 141
 
<?xml version="1.0" encoding="UTF-8"?>
Changed:
<
<
>
>
  This plug-in provides tasks for analysis of data. http://www.esa.int herschel/ia/gui/apps/plugin/Extension.png custom.properties
Added:
>
>
<-- Compatible starting user release 5.0 (build 1760), not with earlier builds -->
5.0.1760
<-- Compatible with all 6.x releases (all builds from the 6.0 track) -->
6.0.*
 

Revision 82010-10-07 - DavideRizzo

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Changed:
<
<
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.
>
>
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.

Revision 72010-10-05 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 244 to 244
  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.
Added:
>
>

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.

 

Examples

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:

Revision 62010-09-21 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 73 to 73
 > jar cf $HOME/myplugin_0.1.jar plugin.py
Added:
>
>
This plugin.py script is similar in function to the __init__.py script that is contained in many of the Java packages in the HCSS. However, the __init__.py must have some obligatory lines of code, which are not required for the plugin.py 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:

Line: 83 to 85
 > jar cf $HOME/myplugin_0.1.jar jars
Added:
>
>
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:

META-INF/
META-INF/MANIFEST.MF
jars/
jars/filtering.jar
plugin.py

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.
Added:
>
>
 

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:

Revision 52010-09-14 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 103 to 103
  - a file or directory called work at the top-level of the file. HIPE uses this directory as an internal workspace.
Changed:
<
<

Slightly more advanced topics: Customizing your plug-in

>
>

Slightly more advanced topics

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.
Line: 131 to 133
  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.
Added:
>
>

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 plugin.py 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

Revision 42010-09-13 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Line: 207 to 207
  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.
Added:
>
>

Examples

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 3 ("configuration" -- 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.

Revision 32010-08-27 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Changed:
<
<
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.
>
>
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.

Plug-ins are available in HIPE starting version 5.0.

 
Changed:
<
<

Quick guide: Creating Simple Plug-ins

>
>

Quick Guide: Creating Simple Plug-ins

 
Changed:
<
<
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.
>
>
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

Changed:
<
<
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.
>
>
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", "2.3.4.5", 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:
Line: 22 to 24
  The options to jar we used here are cvf: c for "create", v for "verbose" and f fore filename.
Changed:
<
<
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.
>
>
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

Changed:
<
<
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.
>
>
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.
 
Changed:
<
<
Unix shell example: Assuming your LocalStores are in the default directory, {{$HOME/.hcss/lstore}} and you want to share {{poolA}} and {{poolB}}:
>
>
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
Line: 37 to 41
 > jar cf $HOME/myplugin_0.1.jar pools
Changed:
<
<
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.
>
>
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".

Changed:
<
<
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.
>
>
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:
Line: 53 to 61
 > jar cf $HOME/myplugin_0.1.jar scripts
Added:
>
>
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 plugin.py and it must be at the top or root-level of the jar or zip.

Unix shell example:

Line: 94 to 103
  - a file or directory called work at the top-level of the file. HIPE uses this directory as an internal workspace.
Changed:
<
<

Slightly more advanced topics

>
>

Slightly more advanced topics: 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>
   <description>This plug-in provides tasks for analysis of data.</description>
   <contributors_page>http://www.esa.int</contributors_page>
   <icon>herschel/ia/gui/apps/plugin/Extension.png</icon>
   <properties>custom.properties</properties>
</plugin>

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.

 
Changed:
<
<

Customizing your plug-in

>
>
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".
 
Changed:
<
<
the plugin.xml options
>
>
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.
 
Added:
>
>
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.
 
Changed:
<
<

Advanced: The plug-in installation process

>
>

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.

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). Select the plug-in and click Browse.

Starting the plug-in means:

  • add all JARs to the Java classpath and the Jython system path
  • 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 three steps or phases. For simple plug-ins, such as have been described until now, nothing is done during the second and third phase. Only the first phase, which is called "bootstrap", is executed. During this 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. Not 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". During this phase, a complete, stand-alone installation program can be executed. Often such programs are Java WebStart programs, but you can also include the installation program in the plug-in itself. If you want to include the custom installation in the plug-in, see the next section for details. If you want to use a WebStart installation program, see the section "Using a WebStart installer".

The third and final phase is called "configuration". This allows the plug-in developer to execute some steps after the custom installation. For example, if the custom installation 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 step. How, is described in the section "Configuring the plug-in post-installation".

While phase 1 is always executed, phase 2 and 3 are optional and independently optional: You can create a plug-in that does something during phase 2 but not during phase 3, and vice versa.

There is currently no mechanism to check for successful completion of the custom installation programs, executed during phase 2.

 

Using a custom installer

Changed:
<
<

Using a WebStart installer

>
>
This section explains how to run a custom program during phase 2 of the plug-in installation.

First, the plug-in must contain a file plugin.xml at the root-level of the jar or zip, with at least the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
   <installer className="MyCustomInstaller" />
</plugin>

And second, a .class file (a compiled Java file) containing the class MyCustomInstaller should be added to the plug-in, also at the root-level of the jar/zip.

The name of the class can be any legal class name except "Installer", because this used for the class that is executed in phase 3. The package must be the default package, i.e. no package.

The class must have either a regular main method, or it can implement the interface herschel.ia.gui.apps.plugin.Installer. If the latter is chosen, the method install(PluginEnv) will be called to execute the installer, which has the advantage that the installer gets access to several properties of the plug-in via the PluginEnv object that is passed as an argument.

Using a WebStart installer

To run a WebStart installer during phase 2 of the plug-in installation, the plug-in must contain a file plugin.xml at the root-level of the jar or zip, with at least the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
   <installer url="http://www.esa.int/webstartfile.jnlp" />
</plugin>

The URL should point to the JNLP file of the WebStart program, which is an XML file that tells Java WebStart where the JARs of the WebStart program are found and which class contains the main method, among other things. The JNLP file can also be used to pass properties to the WebStart program: If you need to pass special properties to the installer, if it is run from a plug-in installation process, then we recommend to create a separate JNLP file for this case. That is, one JNLP file for the normal, stand-alone installation of the program, and one JLNP file when the installation happens as part of the installation process of a plug-in. The second file can then contain some additional properties, to tailor the installation.

 

Configuring the plug-in post-installation

Changed:
<
<

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

>
>
To perform some steps after completion of 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 2 (whether anything was actually done is irrelevant), the install(PluginEnv) method of this interface is called.

As said before, this can be used for example to add references to external JARs installed during phase 2. For this example you can use the method addJar of the PluginEnv class.

Uninstallation

The Plug-ins panel in HIPE shows a button "Uninstall". Clicking this button will simply delete the plug-in directory (all versions). It undoes, in effect, phase 1 of all installations of a given plug-in.

There is no way to undo phases 2 and/or 3 of the installation process. No custom uninstaller can be configured.

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.

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

 
Changed:
<
<
Remove? Works automatically?
>
>

PluginRegistry and Plugin class

 
Added:
>
>
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.
 
Changed:
<
<

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

>
>
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.
 
Changed:
<
<

PluginRegistry

>
>

PluginProcessor

 
Changed:
<
<

PluginProcessor

>
>
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).
 
Added:
>
>
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

Revision 22010-08-27 - PaulBalm

Line: 1 to 1
 
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

Changed:
<
<
This manual describes first how to create plug-ins for HIPE. It ends with a description of the mechanism that HIPE component developers can use to become aware of plug-ins.
>
>
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

Changed:
<
<
Plug-ins can be created to do lots of fancy things, but most of the time people will want to use 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.
>
>
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

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

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

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

Changed:
<
<
- having a file called pools - having a file or directory called work
>
>
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

Revision 12010-08-27 - PaulBalm

Line: 1 to 1
Added:
>
>
META TOPICPARENT name="DpHipePlugins"

Plug-in Developer Manual

This manual describes first how to create plug-ins for HIPE. It ends with a description of 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 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.

How to create a plug-in with some pools

How to create a plug-in with some Jython code

How to create a plug-in with some Java code

What you must avoid / Invalid plug-ins

- having a file called pools - having a file or directory called work

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

 
This site is powered by the TWiki collaboration platform Powered by Perl