JSim Plugin Guide

JSim Plugin Developer's Guide

Introdution

This document describes how to write JSim plugins, code modules that extend JSim's functionality at run-time. Familiarity with both JSim and Java software engineering is assumed.

Contents:

• TODO

Plugin Basics

A JSim plugin is a Java archive (.jar file) that is loaded into jsim, jsbatch or jsserver at run-time to enhance functionality for some user purpose. For example, a user might wish to output model data in a format not currently provided by JSim. This format may be peculiar to a the user's current project, but of little value to the general JSim user community. Here a JSim plugin provides the advantages:

• the public JSim distribution is not weighed down with code specific to a single user;
• the user may implement the plugin without waiting for the JSim development team to allocate time for his particular project.

A plugin's type determines the sort of functionality the plugin will have within JSim. The example above is of the DataFormat type. A plugin's variant is a unique name for the plugin, within all available plugins of the same type. Suppose the example above was implemented via a plugin MyDataFormat.jar, with type DataFormat and variant "mine". Below, the plugin is loaded via the jsbatch -plugin switch, and accessed via the -ofmt switch:

jsbatch -f some.proj -plugin MyDataFormat.jar -ofmt mine

Note that -ofmt flag does not normally accept "mine" as a valid format. However, with the plugin "mine" becomes acceptable (and functional).

JSim has a client-server architecture, and plugins may enhance either the client or server operation. When (as by default) jsim or jsbatch is run using the local server, either type of plugin will be operational. When running the JSim applet or running jsim or jsbatch on a remote server, only client-side plugins will be operational. Remote server-side plugins must be installed via jsserver.

Creating a plugin

For each type of plugin, there is an associated JSim internal class which implements that functionality. For example, the JSim.data.DataFormat class implements the functionality of the plugin type DataFormat. The plugin .jar file must contain a new subclass of the internal class. In our example MyDataFormat extends JSim.data.DataFormat. The new subclass, along with supporting classes and resources are bundled into the plugin .jar. The manifest for a plugin .jar must have the following entries that allow JSim to recognize the plugin and use is appropriately. Values for each entry correspond to the above example:

JSimPluginType: DataFormat

JSimPluginVariant: mine

JSimPluginClass: MyDataFormat

The plugin classes may be compiled against the JSimClient and JSimServer distributed jar files found in $JSIMHOME/lib. A client-side plugin will need only JSimClient.jar, a server-side plugin will need both.

Details for plugin programming may be found in the JSim Public API .

See $JSIMHOME/doc/plugins in your JSim distribution for some examples of JSim plugins and how to build them (on a Macintosh, the doc directory is in the installation directory). More complete documentation for plugin programming may be found in the JSim Public API .