com.tplan.robot.scripting.commands
Interface CommandHandler

All Known Subinterfaces:

AdvancedCommandHandler

All Known Implementing Classes:

AbstractCommandHandler, AbstractFileResourceCommand, CompareToCommand, ConnectCommand, DisconnectCommand, EvalCommand, ExcelCommand, ExecCommand, ExitCommand, FileCommand, IncludeCommand, LogCommand, MouseCommand, PauseCommand, PressCommand, ReportCommand, RunCommand, ScreenshotCommand, ScriptCommand, SendMailCommand, StepCommand, StringCommand, TimerCommand, TypeCommand, TypeLineCommand, VariableCommand, WaitCommand, WaitforCommand, WarningCommand

public interface CommandHandler

Exposed functional interface of command handlers which deliver functionality of particular scripting language commands.

T-Plan Robot Enterprise, (C) 2009-2012 T-Plan Limited. All rights reserved.

Method Summary

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.