CommandHandler (T-Plan Robot Enterprise 8.1.2 Code Documentation)

All Known Subinterfaces:: AdvancedCommandHandler

All Known Implementing Classes:: AbstractCombinedCommand, AbstractCommandHandler

public interface CommandHandler

Interface of a single command defined in the T-Plan Robot Enterprise Scripting Language Specification.

To achieve the very basic functionality you may create a new command by implementing this and the Plugin interfaces. It is however recommended to extend the AbstractCommandHandler class which provides the basic framework. You should also implement other optional interfaces which allow the command to be handled by the GUI tools properly:

Optional command handler interfaces
Interface	Description
`AdvancedCommandHandler`	Declares the arguments, parameters and eventual parameter values supported by the command. This data is used by code completion tools.
`EditorFriendlyCommandHandler`	Allows to create an editor (the "Command Property Window") for the command. Commands can either declare the list of parameters and their properties and let the Robot framework create the window dynamically or supply their own custom editors.
`ContextualDescriptionCapable`	Allows the command to customize the icon and description displayed in the alternative script views such as the graph or tree one.
`Configurable` `ConfigurationChangeListener`	Allows the command to store user preferences and get notified of their changes.
`ScriptListener`	Get notified of script events such as compile (validation), start, stop, pause, resume etc.
`TimeoutDrivenCommand`	Commands relying internally on the Waitfor command may specify their own default timeout value.
`CustomCapabilities`	Commands have to declare whether they need a test environment connection in order to execute. This interface allows to declare it dynamically, i.e. it may be subject to the current status, the command arguments or parameters.

Commands which internally combine/call two or more other existing commands may extend the AbstractCombinedCommand class. It provides basic framework allowing to merge the command parameters. A typical example is the Click command which performs a Waitfor followed by a Mouse click.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addCommandListener(CommandListener listener)` Add a `CommandListener` to the listener list.
`boolean`	`canRunWithoutConnection()` This method should return true if the command can be executed while the tool is not connected to any local or remote desktop.
`int`	`execute(List params, Map values, ScriptingContext context)` Execute the command.
`String[]`	`getCommandNames()` Get command names.
`String`	`getContextArgument()` Get the dummy command argument.
`Map`	`getContextAttributes()` Get a map with context attributes.
`KeyStroke`	`getContextShortcut()` Get preferred hot key for the GUI command wizard.
`List`	`getStablePopupMenuItems()` Get a list of stable actions.
`boolean`	`isGlobalPrerequisity(String command)` This method should return true if the command needs to be executed prior to running part of a test script.
`void`	`removeCommandListener(CommandListener listener)` Removes a `CommandListener` from the listener list.
`void`	`validate(List params, Map values, Map variableContainer, ScriptingContext context)` Validate if the command complies with the command syntax.The command is already pre-parsed to a list of parameter names and a map of [name, value] pairs.

- Method Detail
  - validate
```
void validate(List params,
              Map values,
              Map variableContainer,
              ScriptingContext context)
       throws SyntaxErrorException
```
    Validate if the command complies with the command syntax.The command is already pre-parsed to a list of parameter names and a map of [name, value] pairs.
    
    Parameters:
    
    params - a list of parameters.
    
    values - a map of [param, value] pairs resulted from parsing of the command.
    
    variableContainer - output map for values.
    
    context - execution context.
    
    Throws:
    
    SyntaxErrorException - when the command doesn't meet the required syntax.
  - getCommandNames
```
String[] getCommandNames()
```
    Get command names. A command name is the first word in a script line, e.g. "Type" or "Press". Though most commands have just one name, you may use this method to define any number of command aliases. You may even use one class to implement more commands if you want. In such a case you need to define more command names and implement a different behavior for each command.
    Please note that command name parsing is NOT case sensitive. You don't have to define the names as e.g. { "MyCommand", "mycommand" }. Script parser will always parse the command name in a script and convert it to upper case using the String.toUpperCase(). Such a command name will be then used to look for a command implementation in the command table.
    
    Returns:
    
    array of command names.
  - isGlobalPrerequisity
```
boolean isGlobalPrerequisity(String command)
```
    This method should return true if the command needs to be executed prior to running part of a test script.
    Imagine a following situation. User creates a script:
    Var PATH=/usr/java Type {PATH}/bin/java Press Enter
    User then selects just the last two commands to be executed. It would of course fail because the PATH variable is not defined. If this method returns true, the command will be executed before running selected commands are executed.
    
    Parameters:
    
    command - a command with parameters to be processed.
    
    Returns:
    
    true if the command needs to be executed prior to running of part of the script, false othewise.
  - execute
```
int execute(List params,
            Map values,
            ScriptingContext context)
     throws SyntaxErrorException,
            IOException
```
    Execute the command.
    Argument context will contain all necessary objects that the command may possibly use, for example the com.tplan.robot.gui.FrameBufferPanel and com.tplan.robot.api.rfb.RfbModule instances etc. If the command e.g. needs to send some key events to the RFB server, you should save the reference to the RfbModuleImpl instance and use its methods to fire the required key events.
    
    Parameters:
    
    params - a list of parameters.
    
    values - a map of [param, value] pairs resulted from parsing of the command.
    
    context - execution context.
    
    Returns:
    
    command exit code.
    
    Throws:
    
    SyntaxErrorException - when the command doesn't meet the required syntax.
    
    IOException - an instance of I/O exception may be thrown if an error occurs in communication with the underlying desktop client.
  - addCommandListener
```
void addCommandListener(CommandListener listener)
```
    Add a CommandListener to the listener list.
    
    Parameters:
    
    listener - a CommandListener to be added.
  - removeCommandListener
```
void removeCommandListener(CommandListener listener)
```
    Removes a CommandListener from the listener list.
    
    Parameters:
    
    listener - the CommandListener to be removed
  - getStablePopupMenuItems
```
List getStablePopupMenuItems()
```
    Get a list of stable actions. They will be used to build up a pop up menu displayed on a right mouse click onto the commend in the editor. Though it is not explicitly declared, the list must contain javax.swing.Action instances.
    
    Returns:
    
    list of stable context pop up menu actions.
  - getContextArgument
```
String getContextArgument()
```
    Get the dummy command argument. It is inserted as argument value to commands generated through the command wizard in GUI. It is usually a short description of the expected argument value and the user is expected to rewrite it with a real value. If the command has no argument (just parameters in form of param=value), the method should return null.
    
    Returns:
    
    dummy context argument value.
  - getContextAttributes
```
Map getContextAttributes()
```
    Get a map with context attributes.
    This method is used to create a context menu which contains all parameters supported by the command. Method should return a map where parameter name is a key (String) and corresponding value is a text to be displayed as a hint for the parameter value.
    A good example is the the Press command. It supports parameters count and wait. The hash table generated by this method should then contain e.g. these two entries: 1. Key: "count", Value: "number" 2. Key: "wait", Value: "time in ms"
    When user types Press in the editor and invokes the completion wizard, the list of these two parameters gets displayed. When user selects one of them, the editor then creates a parameter like count=<number> or wait=<time in ms> and inserts it into the edited line.
    
    Returns:
    
    A hash table containing complete list of supported parameters and their descriptions or list of values.
  - getContextShortcut
```
KeyStroke getContextShortcut()
```
    Get preferred hot key for the GUI command wizard. When such a key is pressed in the editor, the GUI inserts the command template into the editor document. The key returned by this method is just a recommendation and the GUI may decide to assign another one to the command, for example when there is a conflict with another existing one.
    
    Returns:
    
    hot key invoking insertion of a command template into the GUI editor..
  - canRunWithoutConnection
```
boolean canRunWithoutConnection()
```
    This method should return true if the command can be executed while the tool is not connected to any local or remote desktop.
    
    Returns:
    
    true if no desktop connection is necessary for execution of this command, false otherwise.

Interface CommandHandler

Method Summary

Method Detail

validate

getCommandNames

isGlobalPrerequisity

execute

addCommandListener

removeCommandListener

getStablePopupMenuItems

getContextArgument

getContextAttributes

getContextShortcut

canRunWithoutConnection