edu.ksu.cis.bandera.tool
Interface Tool

All Superinterfaces:
edu.ksu.cis.bandera.util.Observable
All Known Subinterfaces:
DisconnectableTool

public interface Tool
extends edu.ksu.cis.bandera.util.Observable

The Tool interface is the basic way of interfacing with the Bandera tool suite. This interface will be implemented by tool providers and will be used to perform actions upon a given set of inputs and return some form of output (optional). The Tool will be used in 4 different situations. First, it will be created. This is done with the ToolFactory whose implementation is provided by the Bandera framework (meaning that a tool developer needs not be concerned with Tool creation).
Tool t = ToolFactory.createToolByName("edu.ksu.cis.bandera.tool.sample.SampleTool");
The second situation is when the Tool is being configured. Some tools will have configuration information that can be stored in a session and used again later. If this is the case, the getConfiguration and setConfiguration must be implemented.
String configurationString = "-a -T -m1000"; t.setConfiguration(configurationString);
String configurationString = t.getConfiguration(); ... write the configuration out to a file ...
The third situation is when the user wants to configure the Tool via a user interface (probably a GUI). The environment will call the configure method which will block until the user has completed the configuration.
t.configure();
The fourth situation is actually running the tool. In this case, the environment will add the set of inputs, call the run method, wait for it to complete, and then grab the outputs from the tool. Please note, the environment will handle all the mapping of inputs and outputs.
Map inputMap = ...; t.setInputMap(inputMap); t.run(); Map outputMap = t.getOutputMap();

Version:
$Revision: 1.2 $ - $Date: 2003/08/06 15:30:47 $
Author:
Todd Wallentine tcw AT cis ksu edu

Method Summary
 java.lang.String getConfiguration()
          Get the current configuration for this Tool.
 java.util.List getInputParameterList()
          Get the List of input parameters that should be provided before a run of this Tool.
 java.util.Map getOutputMap()
          Get the outputs from this Tool.
 java.util.List getOutputParameterList()
          Get the List of output parameters that result from a run of this Tool.
 edu.ksu.cis.bandera.tool.ToolConfigurationView getToolConfigurationView()
          Get the ToolConfigurationView that can be used to configure a Tool.
 edu.ksu.cis.bandera.tool.ToolIconView getToolIconView()
          Get the ToolIconView that can be used by the Bandera GUI framework.
 void quit()
          Quit the current run of the tool.
 void run()
          Run the currently configured tool.
 void setConfiguration(java.lang.String configurationString)
          Set the current configuration for this Tool.
 void setInputMap(java.util.Map inputMap)
          Set the inputs for this tool.
 
Methods inherited from interface edu.ksu.cis.bandera.util.Observable
addObserver, countObservers, deleteObserver, deleteObservers, resumeObservers, suspendObservers
 

Method Detail

run

public void run()
         throws java.lang.Exception
Run the currently configured tool.

Throws:
java.lang.Exception - An Exception should be thrown when an error occurs during the run of the system.

quit

public void quit()
          throws java.lang.Exception
Quit the current run of the tool. This is a very rude and destructive manner of stopping the tool. A better method is provided in the DisconnectableTool interface which will save the state of the tool in such a way as it can be restarted.

Throws:
java.lang.Exception - An Exception should be thrown when an error occurs while attempting to quit.

setInputMap

public void setInputMap(java.util.Map inputMap)
                 throws java.lang.Exception
Set the inputs for this tool. This Map provides a map from parameters (as returned when calling getInputParameterList()) to their values as stored in the current run of the system (Driver).

Parameters:
inputMap - The map of input values for this tool where the keys are String values mapped to Object values. The keys should be known by the Tool and are directly associated with those values from a call to getInputParameterList().
Throws:
java.lang.Exception - An Exception should be thrown when the input Map does not conform to the required format for the Tool. This might be caused by the keys not being available or the values for the keys being of the wrong type.

getOutputMap

public java.util.Map getOutputMap()
Get the outputs from this Tool. This Map provides a map from output parameters (as returned when calling getOutputParameterList()) to their values as stored in the current run of the system (Driver).

Returns:
The map of output values for this tool where the keys are String values mapped to Object values. The keys should be known by the Tool and are directly associated with those values from a call to getOutputParameterList(). This will be null when getOutputParameterList() returns a null value.

getInputParameterList

public java.util.List getInputParameterList()
Get the List of input parameters that should be provided before a run of this Tool. The List should consist of String values that can be used to map inputs and outputs by the Driver.

Returns:
List A List of input parameters in the form of String values. This might be null which indicates no inputs are available.

getOutputParameterList

public java.util.List getOutputParameterList()
Get the List of output parameters that result from a run of this Tool. The List should consist of String values that can be used to map inputs and outputs by the Driver.

Returns:
A List of output parameters in the form of String values. This might be null which indicates no outputs are available.

setConfiguration

public void setConfiguration(java.lang.String configurationString)
                      throws java.lang.Exception
Set the current configuration for this Tool. The configuration provides the common run-time configuration that the Tool will use to make decision on how and what to run. This might be command line arguments, some binary format, or possibly some XML fragment. The format is determined by the implementor of the Tool.

Parameters:
configurationString - The String that represents the tool's configuration.
Throws:
java.lang.Exception - An Exception should be thrown when the format for the configuration is incorrect or some value in the configuration is incorrect.

getConfiguration

public java.lang.String getConfiguration()
Get the current configuration for this Tool. The configuration provides the common run-time configuration that the Tool will use to make decision on how and what to run. This might be command line arguments, some binary format, or possibly some XML fragment. The format is determined by the implementor of the Tool.

Returns:
The current configuration for this instance of the Tool. This might be null or an empty String.

getToolConfigurationView

public edu.ksu.cis.bandera.tool.ToolConfigurationView getToolConfigurationView()
Get the ToolConfigurationView that can be used to configure a Tool. This should be a GUI object that can be used by the user to change the settings of a Tool's configuration. The valid types include Eclipse SWT objects, Eclipse Workbench Editors/Views, and Java Swing/AWT components.

Returns:
A GUI widget that can be used by the user to configure a Tool. This might be null which means no configuration information is configurable for this Tool.

getToolIconView

public edu.ksu.cis.bandera.tool.ToolIconView getToolIconView()
Get the ToolIconView that can be used by the Bandera GUI framework.

Returns:
A ToolIconView that provides GUI and text specs to be used in the GUI presentation to the user.