com.tplan.robot.scripting.commands

Class AbstractCombinedCommand

java.lang.Object

com.tplan.robot.scripting.commands.AbstractCommandHandler

com.tplan.robot.scripting.commands.AbstractCombinedCommand

All Implemented Interfaces:

com.tplan.robot.gui.GUIConstants, LocalizedPlugin, Plugin, Configurable, AdvancedCommandHandler, CommandHandler, EditorFriendlyCommandHandler, ContextualDescriptionCapable

public abstract class AbstractCombinedCommand
extends AbstractCommandHandler
implements EditorFriendlyCommandHandler, AdvancedCommandHandler

Abstract class for commands that combine functionality of two or more commands.

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

Field Summary

Fields inherited from class com.tplan.robot.scripting.commands.AbstractCommandHandler

CONTEXT_COMMAND_CALL_COMPILED_PARAMETER_MAP, CONTEXT_COMMAND_CALL_SOURCE_PARAMETER_MAP, PARAM_COUNT, PARAM_ONFAIL, PARAM_ONPASS, PARAM_WAIT

Fields inherited from interface com.tplan.robot.scripting.commands.EditorFriendlyCommandHandler

CATEGORY_ADMIN, CATEGORY_DESKTOP, CATEGORY_IMAGE_OPS, CATEGORY_IO, CATEGORY_REPORTING, CATEGORY_UNKNOWN

Fields inherited from interface com.tplan.robot.gui.GUIConstants

CFG_DEADLOCK_ENABLE, CFG_DEADLOCK_SHOW_MSG, CFG_DEADLOCK_TIMEOUT, CFG_OPEN_SCHEDULE, DEADLOCK_DEFAULT_TIMEOUT, DEFAULT_TPLAN_ROBOT_FILE_EXTENSION, EVENT_ADD_CUSTOM_ACTION_MSG, EVENT_ADD_STABLE_ACTION_MSG, EVENT_DISPLAY_HASHTABLE, EVENT_DISPLAY_PREFERENCES, EVENT_DOCUMENT_CHANGED, EVENT_MOUSE_MOVED, EVENT_REMOVE_CUSTOM_ACTION_MSG, EVENT_REMOVE_STABLE_ACTION_MSG, EVENT_SELECTION_CHANGED, EVENT_STATUSBAR_MSG, HELP_URL_JAPI, HELP_URL_SPEC, HELP_URLS, PROPERTY_EXIT_REQUESTED

Constructor Summary

Constructors

Constructor and Description
AbstractCombinedCommand()

Method Summary

Modifier and Type	Method and Description
void	checkVisualParameters(Map<String,CharSequence> parameters, TestScriptInterpret interpret) Check (compile) the map of parameters retrieved through the command editor window before they are used to build and/or update the command or Java method call.
abstract int	execute(List params, Map values, ScriptingContext context) Execute the command.
abstract List	getArguments(String command, ScriptingContext context) Get the list of supported arguments.
int	getCategory(StringBuilder customCategoryDescription) Get the category the command falls to.
abstract String[]	getCommandNames() Get command names.
abstract String	getContextArgument() Get the dummy command argument.
abstract List<String>	getOwnParameters()
List	getParameters(String command, ScriptingContext context) Get the list of supported parameters.
List	getParameterValues(String paramName, String command, ScriptingContext context) Get values of a particular parameter.
abstract String	getShortDescription(Map<String,String> parameters, TestScriptInterpret interpret) Get short description (up to 50 chars) of what the command does.
List<Preference>	getVisualParameters(LinkedHashMap<String,Object> parameters, TestScriptInterpret interpret) Get the list of visual parameters for construction of a dynamic command editor window.
boolean	hasCustomParameterComponent(LinkedHashMap<String,Object> parameters, TestScriptInterpret interpret, com.tplan.robot.gui.preferences.PreferencePanel[] panel) Specify whether the command provides a custom preference panel.
boolean	hasCustomPropertyDialog(LinkedHashMap<String,Object> parameters, TestScriptInterpret interpret, int offset, Action[] action) Specify whether the command provides a custom editor.
abstract boolean	hasFixedArgument(List<String> arguments) Defines whether the command uses a fixed argument (one-of-a-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.
abstract void	validateOwnParam(ScriptingContext context, String name, Object value, Map out)

Methods inherited from class com.tplan.robot.scripting.commands.AbstractCommandHandler

addCommandListener, canRunWithoutConnection, checkDependencies, compileParameters, executeFallBackCodeOrProcedure, fireCommandEvent, getCode, getContextAttributes, getContextShortcut, getDate, getDescription, getDescription, getDisplayName, getDisplayNameKey, getIcon, getImplementedInterface, getLowestSupportedVersion, getMaster, getMessageAfterInstall, getMessageBeforeInstall, getPreferences, getStablePopupMenuItems, getSupportContact, getUniqueId, getVendorHomePage, getVendorName, getVersion, isGlobalPrerequisity, removeCommandListener, requiresOriginalValues, requiresRestart, setConfiguration, setMaster, toLinkedMap, validateOnPassAndOnFail

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.tplan.robot.scripting.commands.CommandHandler

addCommandListener, canRunWithoutConnection, getContextAttributes, getContextShortcut, getStablePopupMenuItems, isGlobalPrerequisity, removeCommandListener

Constructor Detail

AbstractCombinedCommand

public AbstractCombinedCommand()

Method Detail

validate

public void validate(List params,
                     Map values,
                     Map variableContainer,
                     ScriptingContext context)
              throws SyntaxErrorException

Description copied from interface: CommandHandler

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.

Specified by:

validate in interface CommandHandler

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.

getOwnParameters

public abstract List<String> getOwnParameters()

validateOwnParam

public abstract void validateOwnParam(ScriptingContext context,
                                      String name,
                                      Object value,
                                      Map out)
                               throws SyntaxErrorException

Throws:

SyntaxErrorException

getContextArgument

public abstract String getContextArgument()

Description copied from interface: CommandHandler

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.

Specified by:

getContextArgument in interface CommandHandler

Overrides:

getContextArgument in class AbstractCommandHandler

Returns:

dummy context argument value.

getCommandNames

public abstract String[] getCommandNames()

Description copied from interface: CommandHandler

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.

Specified by:

getCommandNames in interface CommandHandler

Returns:

array of command names.

execute

public abstract int execute(List params,
                            Map values,
                            ScriptingContext context)
                     throws SyntaxErrorException,
                            IOException

Description copied from interface: CommandHandler

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.

Specified by:

execute in interface CommandHandler

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.

getArguments

public abstract List getArguments(String command,
                                  ScriptingContext context)

Description copied from interface: AdvancedCommandHandler

Get the list of supported arguments. For example, the Mouse command should return a list containing "click", "move" etc. Commands which have no argument and rely just on parameters (param=value) should return null.

Specified by:

getArguments in interface AdvancedCommandHandler

Parameters:

command - the current command.

context - a context.

Returns:

list of supported argument values.

getParameters

public List getParameters(String command,
                          ScriptingContext context)

Description copied from interface: AdvancedCommandHandler

Get the list of supported parameters. Command handlers are free to parse the current command and return a filtered list depending on what is already specified. Parameters in the list should be String instances. If they are other objects than String, they may or may not be handled well depending on what the GUI supports.

Specified by:

getParameters in interface AdvancedCommandHandler

Parameters:

command - the current conmmand text (complete).

context - a context.

Returns:

list of supported parameter names.

getParameterValues

public List getParameterValues(String paramName,
                               String command,
                               ScriptingContext context)

Description copied from interface: AdvancedCommandHandler

Get values of a particular parameter. This is to be used for parameters which have a fixed set of acceptable values. The command wizard typically displays the values as a list.

Specified by:

getParameterValues in interface AdvancedCommandHandler

Parameters:

paramName - parameter name.

command - the current conmmand text (complete).

context - a context.

Returns:

list of supported parameter values.

getVisualParameters

public List<Preference> getVisualParameters(LinkedHashMap<String,Object> parameters,
                                            TestScriptInterpret interpret)

Description copied from interface: EditorFriendlyCommandHandler

Get the list of visual parameters for construction of a dynamic command editor window.

This method will be called only after the EditorFriendlyCommandHandler.hasCustomPropertyDialog(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, int, javax.swing.Action[]) and EditorFriendlyCommandHandler.hasCustomParameterComponent(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, com.tplan.robot.gui.preferences.PreferencePanel[]) methods return false.

Specified by:

getVisualParameters in interface EditorFriendlyCommandHandler

Parameters:

parameters - input parameters parsed from the already existing command or preselected through the Command Wizard menu.

interpret - test script interpret owning the edited script.

Returns:

list of visual parameters. If the list is null and the command does not provide a custom component through the EditorFriendlyCommandHandler.hasCustomPropertyDialog(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, int, javax.swing.Action[]) and EditorFriendlyCommandHandler.hasCustomParameterComponent(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, com.tplan.robot.gui.preferences.PreferencePanel[]) methods, it will be considered as not editable through the GUI.

checkVisualParameters

public void checkVisualParameters(Map<String,CharSequence> parameters,
                                  TestScriptInterpret interpret)
                           throws IllegalArgumentException

Description copied from interface: EditorFriendlyCommandHandler

Check (compile) the map of parameters retrieved through the command editor window before they are used to build and/or update the command or Java method call. This method may be also used to remove or filter the parameters. This is especially useful if the command editor uses auxiliary settings which are not recognized by the command or method at runtime.

If the command handler extends the AbstractCommandHandler class, it may take advantage of the AbstractCommandHandler.compileParameters(java.util.Map, com.tplan.robot.scripting.interpret.TestScriptInterpret) method which converts a copy of the input map to the legacy parameter format and passes it to the CommandHandler.validate(java.util.List, java.util.Map, java.util.Map, com.tplan.robot.scripting.ScriptingContext) method to verify whether the parameters are recognized and their values are acceptable. This allows to avoid duplication of parameter parsing and compilation code.

Specified by:

checkVisualParameters in interface EditorFriendlyCommandHandler

Parameters:

parameters - map of parameters and their values. All values are in the format recognized by token parser (TokenParserImpl.getParser()) which may be used to convert them to native Java objects such as Number, Point, Rectangle etc.

interpret - test script interpret owning the edited script.

Throws:

IllegalArgumentException - when one or more parameters is not recognized or its value is invalid. The exception should contain a descriptive message because it will be displayed by the GUI.

hasFixedArgument

public abstract boolean hasFixedArgument(List<String> arguments)

Description copied from interface: EditorFriendlyCommandHandler

Defines whether the command uses a fixed argument (one-of-a-list). Examples of such commands are Mouse with the arguments of "click", "press" etc. or WaitFor ("match", "mismatch",...). If the command does use a fixed argument it is supposed to return true and populate the argument list with the argument values (if the list is not null).

Specified by:

hasFixedArgument in interface EditorFriendlyCommandHandler

Parameters:

arguments - optional output list for the argument values.

Returns:

true if the command uses fixed argument values, false if not.

hasCustomParameterComponent

public boolean hasCustomParameterComponent(LinkedHashMap<String,Object> parameters,
                                           TestScriptInterpret interpret,
                                           com.tplan.robot.gui.preferences.PreferencePanel[] panel)

Description copied from interface: EditorFriendlyCommandHandler

Specify whether the command provides a custom preference panel. If it does it is expected to return true and populate the first field of the panel array with an instance of the panel.

Specified by:

hasCustomParameterComponent in interface EditorFriendlyCommandHandler

Parameters:

parameters - map of parameters and their values. All values are in the format recognized by token parser (TokenParserImpl.getParser()) which may be used to convert them to native Java objects such as Number, Point, Rectangle etc.

interpret - test script interpret owning the edited script.

panel - output array of length=1 which should be populated inside the method with the custom panel instance if the method returns true.

Returns:

true if the command creates its own custom preference panel or false otherwise.

hasCustomPropertyDialog

public boolean hasCustomPropertyDialog(LinkedHashMap<String,Object> parameters,
                                       TestScriptInterpret interpret,
                                       int offset,
                                       Action[] action)

Description copied from interface: EditorFriendlyCommandHandler

Specify whether the command provides a custom editor. If it does it is expected to return true and populate the first field of the action array with an instance of an Action which opens up the dialog.

Even though the method is implemented to return false, it may be also used to preprocess parameters parsed from an existing command call before they reach the command editor window. The method may for example change the parameters or their values in the input map. As the argument map the real one rather than a copy, any data change will hold in there and it will be reflected in the GUI.

Specified by:

hasCustomPropertyDialog in interface EditorFriendlyCommandHandler

Parameters:

parameters - map of parameters and their values. All values are in the format recognized by token parser (TokenParserImpl.getParser()) which may be used to convert them to native Java objects such as Number, Point, Rectangle etc.

interpret - test script interpret owning the edited script.

offset - position in the edited script.

action - output array of length=1 which should be populated inside the method with an Action instance if the method returns true.

Returns:

true if the command creates its own dialog or false otherwise.

getCategory

public int getCategory(StringBuilder customCategoryDescription)

Description copied from interface: EditorFriendlyCommandHandler

Get the category the command falls to. The method may return one of the predefined CATEGORY_XXX constants defined by this class. Commands which do not fall into any specified category may return EditorFriendlyCommandHandler.CATEGORY_UNKNOWN or a code outside of the recognized constants and pass the desired category name through the argument string builder instance.

Specified by:

getCategory in interface EditorFriendlyCommandHandler

Parameters:

customCategoryDescription - string buffer for category name. It is only used if the returned value is other than the standard ones.

Returns:

category code.

getShortDescription

public abstract String getShortDescription(Map<String,String> parameters,
                                           TestScriptInterpret interpret)

Description copied from interface: EditorFriendlyCommandHandler

Get short description (up to 50 chars) of what the command does. This will be used for the list (menu) of available actions in the GUI.

Specified by:

getShortDescription in interface EditorFriendlyCommandHandler

Parameters:

parameters - map of parameters and their values. All values are in the format recognized by token parser (TokenParserImpl.getParser()) which may be used to convert them to native Java objects such as Number, Point, Rectangle etc.

interpret - test script interpret owning the edited script.

Returns:

short command description.