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.

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):

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). The default implementation of this plugin 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 file to be associated with this plugin.
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 localization tags that can be translated to localized GUI panel names with 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 GUI.
5. Filter[] getFilters() - returns new Filter interface implementations 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.
6. AbstractMenuAction[] getMenuItems() - returns an array of additional menu actions 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.
7. String[] getAboutAttributions() - return an array of 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.
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.