Bandera 1.0 Tool Developer Guidelines

by Todd Wallentine tcw AT cis ksu edu
$Revision: 1.2 $ - $Date: 2003/08/06 15:30:48 $

The Tool Developer Guidelines attempt to provide developers of tools for Bandera 1.0 some assistance in implementing the proper classes and interfaces.

The first thing a tool developer will need to decide is if their tool will be disconnectable. If it is a remote tool or one that can be stopped and restarted, this should be the case. For simple tools (especially those that are expected to be short running), there is no need to implement the disconnection API. However, if the tool developer wants to have the ability to disconnect, they should implement the DisconnectableTool interface. Otherwise, the tool developer should simply implement the Tool interface.

The Driver is one component that makes use of the Tool interfaces. The Driver provides a way to run the tools using a configuration (a session). The Driver is also responsible for mapping inputs and outputs together so that the individual tools get the input they need and can pass their output on to other tools.

The Tool is the main component. The implementation of this interface will be what is run when a Driver requests to run this type of tool. The usage of the Tool from the Driver's perspective follows.
  1. Create the Tool using the ToolFactory according to the session information.
  2. Initialize the Tool using a String (the String comes from the session and must be parsed by the Tool itself).
  3. Pass a Map of input to the Tool which is created based upon the current state of the system and the list of parameters provided by the Tool.
  4. Run the tool.
  5. If the user requests it, stop the tool from running (this is the rude way to do this since it doesn't save the current state!).
  6. When the tool returns from the run method, get the output Map (and integrate it with the current state of the system).
The Tool interface uses the abstract factory method pattern (GoF book) by forcing the Tool implementor to define the factory methods for the creation of the ToolConfigurationView and the ToolIconView.

The other interfaces associated with a Tool are list below.
The String used to set and get the configuration information is used to externalize configuration information for the Tool. Only the Tool implementor can decide the format and function of this configuration information. The Driver will simply nest this String data into the session to be used later. One option for this String format is XML.

The ToolConfigurationView should provide a GUI view of the Tool's configuration information. Some tools will not have any type of configuration information and some will have extensive configuration information. For example, the SootCompilerTool has not configuration information so there will be no ToolConfigurationView associated with it. On the other hand, the BogorTool has a great deal of configuration information and will require a very extensive ToolConfigurationView.

The ToolIconView should provide the main Bandera GUI information about the Tool so that it can be displayed to the user of Bandera. This will include icons, tool tip text, and a name to be displayed. If no ToolIconView is provided, Bandera will use a default name and icons. If the active icon is not provided, the default icon will be used while the tool is running. If the disabled icon is not provided, the default icon will be used while the tool is disabled. The active icon will likely be an animated icon or some icon that denotes that the tool is currently running. The disabled icon will likely be a greyed out version of the default icon.

Tool API Object Diagram

Sample Driver code:
String configurationString;
Map inputMap;
Tool tool = ToolFactory.createToolByName("edu.ksu.cis.bandera.tool.sample.SampleTool");
Map om = tool.getOutputMap();

Bandera 1.0 will make use of a common version of Soot since that will be the intermediate representation between many of the components in the system. The standard for this will be Soot 2.0. If a different version is necessary, a developer should make a feature request in the Bandera project in order to get this version changed. The request should include specific reasons to upgrade. The group of known developers can then discuss the issue and come to a consensus and possibly define the new standard version.

Tool API Javadocs

Tools that will be implemented:

Things to add to this guide: