Writing a YAAC Plugin Extension

YAAC is designed to be easily extensible by creating a "plugin" that contains code needed for whatever additional functionality the programming user might desire.

A YAAC plugin follows the conventions established in the Java language for extending the Java Runtime Environment. The plugin consists of a standard Java archive (JAR) file, placed in either the plugins sub-directory of the YAAC installation directory or the plugindir sub-directory of the user's personal YAAC subdirectory (if YAAC is being installed on a multi-user system so that it can be shared between multiple YAAC users). The JAR file contains:

• a JAR manifest file containing (at a minimum) the entry "YAAC-Provider" specifying the fully package-qualified name of a class in the JAR file extending the org.ka2ddo.yaac.pluginapi.Provider abstract superclass.
• the compiled class file of the class mentioned in the manifest file.
• any other class files and other resources needed by the desired extension (such as properties files of localized translations of prompts and JavaHelp helpset files documenting how to use the plugin).

Any of the public methods and classes in the base YAAC jar file may be accessed by the plugin as needed to implement the desired functionality. The Javadoc documentation of the YAAC code is included in the YAACpluginSDK.zip file included with the YAAC binary distribution; the documentation can also be read directly from the source code in the source code distribution or a snapshot from the Subversion repository on SourceForge.

The plugin Provider specifies naming and describing the plugin, and provides the following methods that can be overridden on a per-plugin basis (the default implementation of each method defines no extension of the specified functionality, returning null or simply returning immediately with no functionality as appropriate to the method signature):

1. boolean runInitializersBefore(int version) - This allows any Provider-specific initialization to run before menus and drivers are loaded, and also permits the Provider to block usage of the plugin (for example, if the plugin provides services only available on Microsoft Windows, but YAAC is being executed on Mac OS X, this method should return false to specify the plugin cannot be used). Note that such implementations should ensure the Provider subclass does not depend on such platform-specific resources in order to load the Provider subclass or execute this method. The default implementation of this method compares the current plugin API version supported by core YAAC against the API version the plugin was compiled with, and returns true if the versions match and false if they do not.
2. String getImageIconPath() - return the plugin-specific pathname (relative to the root directory of the JAR file) of an icon image file to be associated with this plugin. By default, plugins do not have their own icons.
3. Provider.PortEntry[] getPortConnectorTypes() - return the names and Class objects of any new port drivers supplied by this plugin. The PortEntry structure contains the internal code name (displayed in the port editor GUI) and the Class object which can instantiate objects that are subclasses of the org.ka2ddo.yaac.io.PortConnector abstract superclass and implement a no-arguments constructor.
4. Map<String,String> getConfigurationPanels() - returns pairs of GUI panel names and implementing class names that should be added to the expert-mode Configuration dialog. The keys of the map are already-localized GUI panel names (typically by calling the YAAC.getMsg(String tagName) method); the corresponding values are the fully package-qualified names of classes implementing the corresponding configuration editing GUI (with zero-arg constructors), with an expected "*" character to be replaced with the string "gui" for standard Java deployments or some other string for a Java environment not using the standard Java AWT/Swing GUI (no others are currently supported).
5. Filter[] getFilters() - returns new concrete implementations of the abstract org.ka2ddo.yaac.filter.Filter class to allow selective viewing of incoming message traffic. These filters will be appended to the list of Filters already in core YAAC; packets received by YAAC must also be passed by these new filters to display a message. Each Filter implementation must declare a public static final String constant named CONFIG_GUI, whose value is the fully package-qualified name of a UI class for configuring this filter, with a one-argument constructor expecting an object of the class of the Filter itself (i.e., the Filter object to be managed). Like the configuration panel class names, these class names can include a "*" wildcard for substituting "gui" for the standard Java AWT/Swing UI or some other value for supporting other UI infrastructures.
6. AbstractMenuAction[] getMenuItems() - returns an array of additional menu actions (implemented as subclasses of the org.ka2ddo.yaac.pluginapi.AbstractMenuAction class) that should be added to the menus presented by YAAC's GUI. If a menu item whose hierarchical pre-localization tags for the menu entry name are the same as a menu entry previously defined (including one in the core YAAC distribution), the newer menu item will replace the previously defined one; this allows plugins to improve existing functionality as well as add new functionality. Elements of the array that extend the org.ka2ddo.yaac.pluginapi.AbstractPopupMenuAction class will not appear in the menu bar, but rather conditionally in popup menus triggered by right-clicking on a YAAC window.
7. String[] getAboutAttributions() - return an array of already-localized strings representing lines of text for attributions about this plugin that should be displayed in YAAC's Help->About dialog. The strings will be associated with the plugin name, version, author, and description defined in the Provider subclass's constructor, and any icon that may have been defined by the getImageIconPath() method. It is suggested that copyright and licensing information about the plugin and any libraries it uses should be specified here.
8. HelpSet getHelpSet() - return a JavaHelp HelpSet documenting the features provided by the plugin. A helpset consists of the following resource files:
   • a xxxHelp.hs file describing the setup of the help for this plugin (you can do thing by copying and pasting another plugin's .hs file).
   • a xxxHelpMap.jhm file that maps identifier code strings (like ResourceBundle keys) to paths to HTML files relative to the .jhm file's directory. The relative path to the .jhm file should be listed in the location attribute of the <mapref> tag in the .hs file.
   • a xxxHelpTOC.xml file (identified in the xxxHelp.hs file) listing the table of contents of the help for the plugin.
   • a xxxHelpIndex.xml file (identified in the xxxHelp.hs file) listing all the index entries for the plugin's help (plus duplicates of any entries in YAACHelpIndex.xml that are enclosing parent tags for plugin-specific tags).
   • a docs subdirectory containing the HTML files of the actual help documentation plus any supplemental image files referenced by the HTML files.
9. void runInitializersAfter() - do anything needed to finish setting up the plugin's functionality that needs to be done after all plugins have been loaded and the features defined by the above methods have been set up.
10. String[] consumeXMLPreferenceData(String nodeName, String lastNodeName, String key, String value) - do anything needed to restore configuration data to this plugin if the plugin saved configuration data in Java Preferences using the Preferences node object YAAC.getPreferences(), and wants such data to be copyable to other stations. To implement this, plugin authors should study the org.ka2ddo.yaac.io.ConfigImporter class's source code.

The sampleplugin source code provided with YAAC is a simple implementation to log in realtime to a plain text file certain APRS packets of interest. It overrides only the runInitializersAfter() method to conditionally register a class implementing the org.ka2ddo.yaac.ax25.TrackerListener interface (an instantiation of the Gang of 4's Observer design pattern) to report on events of interest to the plugin.