Creating YajHFC plugins

Introduction

YajHFC plugins are basically just a way to dynamically load and initialize Java classes. Currently there is not really a stable and complete plugin API.

With a plugin, you can (and have to) use any of the classes YajHFC consists of.

For an example of a simple working plugin, please download the archive from http://download.yajhfc.de/misc/example-plugin-src.zip
or get the source code from the repository at https://github.com/jwolz/yajhfc-plugin-example

To try out a the compiled version, please download http://download.yajhfc.de/misc/example-plugin.jar

Loading and initializing a plugin

A plugin in its most basic form consists of a single class, used for initialization, packaged in a JAR file. The name of that class is set using a custom option called YajHFC-Plugin-InitClass in the JAR's manifest.

A working manifest for the JAR file could look like that:

Manifest-Version: 1.0
YajHFC-Plugin-InitClass: example.plugin.EntryPoint

That class itself must have a method public static boolean init(int startupMode), which is called to initialize the plugin. This method must return true if the plugin initialized successfully or false otherwise.

Thus, a simple init class could look like that:

package example.plugin;
public class EntryPoint {
  public static boolean init(int startupMode) {
    // Initialize plugin...
    return true;
  }
}

Adding a menu item

To add a menu item to the Extras menu, add a PluginUI instance to the PluginManager.pluginUIs list in your init method. In that instance, override the public JMenuItem[] createMenuItems() method and return an array of menu items that should be added.

Creating an options page and saving/loading options

To create an options page, also add a PluginUI instance to the PluginManager.pluginUIs list in your init method. In that instance, override the public PanelTreeNode createOptionsPanel(PanelTreeNode parent) method.

This method returns a tree node that will be displayed in the Options dialog. Please refer to example plugin for more details.

To save options, you can either create your own settings file or use the YajHFC one.

To use the YajHFC options file, create a subclass of AbstractFaxOptions and add the options as public fields. Then you can load the options by using options.loadFromProperties(Utils.getSettingsProperties()) and save them using the saveOptions method of your PluginUI instance:

public void saveOptions(Properties p) {
  options.storeToProperties(p);
}

Again, for a complete example, please take a look at the example plugin.

Accessing the HylaFAXClient

To access the HylaFAXClient class from gnu.hylafax to access the HylaFAX server, please use the HylaClientManager class like that:

HylaClientManager cliMan = ServerManager.getDefault().getCurrent().getClientManager();
// Get a HylaFAXClient instance by calling beginServerTransaction
HylaFAXClient hyfc = cliMan.beginServerTransaction(Launcher2.application.getFrame());
                    
try {
  // Do stuff with hyfc...
} finally {
  // Make sure that for each beginServerTransaction call
  // endServerTransaction is called *exactly* once
  cliMan.endServerTransaction();
}

Accessing the lists of faxes

To access the lists of faxes, please use the methods provided by the MainWin class.

For example, to get the table with the received faxes:

((MainWin)Launcher2.application).getTableByIndex(0)

To get the actual list of faxes (the table model) use the getRealModel method on the table (getTableModel returns a TableSorter which is used to sort the faxes when the user clicks a table header).

For a longer example, please also take a look at the example plugin.

Please also note that since I currently do not know of any third-party plugins, I will make no special effort to keep the "API" of YajHFC stable between different versions. So if you have created a plugin and would like to have some kind of stable API, please let me know.