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.
- Create the Tool using the ToolFactory according to the session
information.
- Initialize the Tool using a String (the String comes from the session and must
be parsed by the Tool itself).
- 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.
- Run the tool.
- 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!).
- 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.
- ToolConfigurationView (required if the user should be able to configure the Tool)
- ToolIconView (optional)
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.
Sample Driver code:
String configurationString;
Map inputMap;
Tool tool = ToolFactory.createToolByName("edu.ksu.cis.bandera.tool.sample.SampleTool");
tool.setConfiguration(configurationString);
tool.setInputMap(inputMap);
tool.run();
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:
- SootCompilerTool (to compile Java class files into Jimple)
- EclipseProjectTool (to collect Java source/class from an Eclipse project)
- SimpleProjectTool (to collect Java source from the filesystem)
- JavaCompilerTool (to compile Java source into Java class files)
- J2BTool (to convert Jimple to BIR)
- SlicerTool (to slice the model)
- BogorTool (to model check the BIR using Bogor)
- SootWriterTool (to write out IR to file)
- BirWriterTool (to write out IR to file)
- CounterExampleMappingTool (to map BIR back to Jimple for the CE)
- CounterExampleWriterTool (to write out CE to file)
- CounterExampleGUITool (to start the CE GUI)
Things to add to this guide:
- Lifecycle information
- External resources that are not specified in the interface
- Create a SampleTool
- Create a SampleRemoteTool