Writing PAMGUARD Plug-ins

ARCHIVING PLUG-INS INTO A JAR FILE FOR DISTRIBUTION

Even if the plugin is intended as an External module, it is easiest to develop it as a Core module.  In other words, create a new package in the PAMGuard code base to hold all of the new classes, and add a reference to the package classes in PamModel.  This way, dependencies do not need to be explicitly managed and debugging is simplified.  All development should be done within the new package, and the core PAMGuard classes should not be changed (if modifications are necessary, please contact the PAMGuard development team first).

To make an external PAMGUARD plug-in available to PAMGUARD users once development is complete, 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.PamPluginInterface (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.  Remember to rename/delete the package in the PAMGuard code first, to ensure that you are really testing the jar file contents and not the original 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 (even if the original package has been deleted).  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.  Also, remember to remove references to the new module from the PamModel class, as this will be taken care of by the jar file.