Difference: DpHipePluginsDeveloperManual (14 vs. 15)

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

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