Writing PAMGUARD Plug-ins

ARCHIVING PLUG-INS INTO A JAR FILE FOR DISTRIBUTION

To make an external PAMGUARD plug-in available to PAMGUARD users it is necessary to archive the class files and support files (including help files, graphics, sound files, etc.) into a java archive (jar) file.

Prior to archiving, the developer must add a class to the project package which implements one of two interfaces: PamModel.PamPlug-inInterface (for standard plug-in modules) or Acquisition.DaqSystemInterface (for data acquisition modules such as sound cards, file streams, etc.).   Override all of the Interface’s inherited methods, returning appropriate values as specified in the Javadoc comments.   Create a String object to hold the jar file name.  This parameter does not need to be initialized to anything specific; the value will be set by PAMGUARD via the inherited setter method.  The code could be as simple as

String jarFile;
@Override
public void setJarFile(String jarFile) {
this.jarFile = jarFile;
}

It is strongly recommended that help files be included with the plug-in.  PAMGUARD uses Oracle’s JavaHelp 2.0 system (complete details can be found here).  Each page in the help file is an HTML document.  Create individual HTML pages (with links and images) to describe the setup and operation of the plug-in, and save all files in the same package folder that your java program is in.  Once the pages are completed, create the helpset and support files (map, TOC, index, etc.).  Programs like jhelpdev can greatly simplify the process of creating these files.  Note:

  1. To have the help files added to an existing category (i.e. Classifiers, Detectors, etc.) in the PAMGUARDhelp table of contents, the top-level  tag text attribute in the plug-in’s TOC xml file must match the category name exactly.  Some category names have a space character at the end.  If in doubt, check the PAMGUARDTOC.xml file found in src/help for a list of the TOC entries.
  2. If the top-level tag text attribute in the plug-in’s TOC xml file does not match any of the category names in the table of contents, the item is simply appended to the bottom of the list.
  3. To match the existing table of contents look-and-feel, each tag in the plug-in’s TOC xml file should have image=”topic” added as an attribute.  Copy the image.gif file found in src/help to the plug-in package folder.  Ensure the line is in the plug-in’s map.jhm file.

Specify the name of the helpset file in the plug-in interface class.  Look through the interface Javadoc documentation for the correct format to use.

Follow these steps to bundle all files together into a single jar, ready for distribution.  Note the following are specific to the Eclipse IDE.  Other IDE’s will have similar functionality:

  1. Right-click on the project name in the Package Explorer view and select Export
  2. In the Export window, click on the Java folder and highlight JAR file.  Hit Next
  3. In the window frame on the left, make sure the package and all necessary subfolders are selected to export (sometimes subfolders created by JavaHelp - such as JavaHelpSearch – are not included in the export list by default).  Click on the box beside “Export generated class files and resources” and “Export Java source files and resources”.  Enter the name of the exported jar file in the text box under “Select the export destination”.  You can click on the box beside “Compress the contents of the JAR file”, though this is optional.  The default values for the remainder of the windows can be used.  Hit Finish to export the package to the location specified.

To test the jar file, move it to the plugins subfolder in the PAMGUARD installation folder.  If there is no plugins folder, create one.  When PAMGUARD is started, it should find the jar file and use the information in the interface class to dynamically load the code.

Final note: if plug-in development has been done in the core Pamguard code and then exported to a jar, the *.class files may still exist in the Pamguard project’s bin subfolder.  If testing the plug-in jar in the IDE, first look through the bin subfolder and delete any plug-in *.class files that are stored.  If PAMGUARD finds the classes in both the bin folder and the jar file, it is unclear which would get loaded at runtime.  The class files are replaced in the bin folder every time a build is completed.