com.tplan.robot.scripting.commands
Class AbstractCommandHandler

java.lang.Object
  com.tplan.robot.scripting.commands.AbstractCommandHandler

All Implemented Interfaces:

GUIConstants, Plugin, Configurable, CommandHandler

Direct Known Subclasses:

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

public abstract class AbstractCommandHandler
extends Object
implements CommandHandler, GUIConstants, Plugin, Configurable

Base class for command handlers which implement functionality of individual commands of the T-Plan Robot Enterprise proprietary scripting language.

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

Field Summary

protected static String	ALT
static String	CONTEXT_COMMAND_CALL_PARAMETER_MAP
protected static String	CONTEXT_COMPILE_SINGLE_COMMAND_MODE
protected static String	CONTEXT_LAST_WAIT_FACTOR
protected static String	CONTEXT_WAIT_FACTOR_ERR_MSG_SHOWN
protected static String	CTRL
static String	PARAM_COUNT
static String	PARAM_ONFAIL
static String	PARAM_ONPASS
static String	PARAM_WAIT
protected static String	SHIFT
protected static String	WINDOWS

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

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

Constructor Summary

AbstractCommandHandler()

Method Summary

void	addCommandListener(CommandListener listener) Add a CommandListener to the listener list.
boolean	canRunWithoutConnection() This method should return true if it can be executed even when the tool is not connected to a desktop.
void	checkDependencies(PluginManager manager) Check whether the current product installation contains all dependencies (other plugins) required to install this plugin.
protected static boolean	checkPauseAndStop(ScriptingContext ctx) Test whether the script is paused or stopped.
Map	compileParameters(Map paramsAndValues, TestScriptInterpret interpret)
protected ConfigureAction	createConfigureAction()
void	executeFallBackCodeOrProcedure(String code, String procedure, String[] procedureArgs, ScriptingContext ctx)
void	fireCommandEvent(Object source, ScriptingContext context, String actionCode, Object customObject)
protected static boolean	getBooleanSafely(UserConfiguration cfg, String parameter, boolean defaultValue) Retrieve a boolean parameter from user configuration in a safe, exception-free way.
String	getCode() Get plugin code.
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.
Date	getDate() Get plugin release date.
String	getDescription() Get plugin description to be displayed in the GUI.
String	getDisplayName() Get a generic display name.
Class	getImplementedInterface() Get Class of the exposed functional interface that this plugin implements.
protected static int	getIntegerSafely(UserConfiguration cfg, String parameter, int defaultValue) Retrieve an integer parameter from user configuration in a safe, exception-free way.
int[]	getLowestSupportedVersion() Get the lowest required version of T-Plan Robot Enterprise.
String	getMessageAfterInstall() Get text of a message to be displayed after installation of this plugin.
String	getMessageBeforeInstall() Get text of a message to be displayed before installation of this plugin.
List<Preference>	getPreferences() Get metadata of displayable/editable configurable parameters.
List	getStablePopupMenuItems() Get a list of stable actions.
String	getSupportContact() Get support contact.
String	getUniqueId() Get unique ID associated with the plugin.
String	getVendorHomePage() Get the vendor home page.
String	getVendorName() Get vendor (provider) name to be displayed in the GUI.
int[]	getVersion() Get plugin version in form of an integer array.
boolean	isGlobalPrerequisity(String command) This method should return true if the command needs to be executed prior to running part of a test script.
protected long	multiplyWaitTime(ScriptingContext context, long timeMs)
void	removeCommandListener(CommandListener listener) Removes a CommandListener from the listener list.
boolean	requiresRestart() Indicate whether installation of this plugin requires application restart.
void	setConfiguration(UserConfiguration cfg) If an object implementing this interface is a plugin (i.e.
void	validateOnPassAndOnFail(ScriptingContext repository, Map params)
protected void	wait(ScriptingContext context, int delay)

Methods inherited from class java.lang.Object

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

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

execute, getCommandNames, validate

Field Detail

PARAM_WAIT

public static final String PARAM_WAIT

See Also:

Constant Field Values

PARAM_COUNT

public static final String PARAM_COUNT

See Also:

Constant Field Values

PARAM_ONFAIL

public static final String PARAM_ONFAIL

See Also:

Constant Field Values

PARAM_ONPASS

public static final String PARAM_ONPASS

See Also:

Constant Field Values

SHIFT

protected static final String SHIFT

See Also:

Constant Field Values

CTRL

protected static final String CTRL

See Also:

Constant Field Values

ALT

protected static final String ALT

See Also:

Constant Field Values

WINDOWS

protected static final String WINDOWS

See Also:

Constant Field Values

CONTEXT_COMPILE_SINGLE_COMMAND_MODE

protected static final String CONTEXT_COMPILE_SINGLE_COMMAND_MODE

See Also:

Constant Field Values

CONTEXT_COMMAND_CALL_PARAMETER_MAP

public static final String CONTEXT_COMMAND_CALL_PARAMETER_MAP

See Also:

Constant Field Values

CONTEXT_WAIT_FACTOR_ERR_MSG_SHOWN

protected static final String CONTEXT_WAIT_FACTOR_ERR_MSG_SHOWN

See Also:

Constant Field Values

CONTEXT_LAST_WAIT_FACTOR

protected static final String CONTEXT_LAST_WAIT_FACTOR

See Also:

Constant Field Values

Constructor Detail

AbstractCommandHandler

public AbstractCommandHandler()

Method Detail

validateOnPassAndOnFail

public void validateOnPassAndOnFail(ScriptingContext repository,
                                    Map params)
                             throws SyntaxErrorException

Throws:

SyntaxErrorException

executeFallBackCodeOrProcedure

public void executeFallBackCodeOrProcedure(String code,
                                           String procedure,
                                           String[] procedureArgs,
                                           ScriptingContext ctx)

isGlobalPrerequisity

public boolean isGlobalPrerequisity(String command)

Description copied from interface: CommandHandler

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.

Specified by:

isGlobalPrerequisity in interface CommandHandler

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.

addCommandListener

public void addCommandListener(CommandListener listener)

Description copied from interface: CommandHandler

Add a CommandListener to the listener list.

Specified by:

addCommandListener in interface CommandHandler

Parameters:

listener - a CommandListener to be added.

removeCommandListener

public void removeCommandListener(CommandListener listener)

Description copied from interface: CommandHandler

Removes a CommandListener from the listener list.

Specified by:

removeCommandListener in interface CommandHandler

Parameters:

listener - the CommandListener to be removed

fireCommandEvent

public void fireCommandEvent(Object source,
                             ScriptingContext context,
                             String actionCode,
                             Object customObject)

getPreferences

public List<Preference> getPreferences()

Description copied from interface: Configurable

Get metadata of displayable/editable configurable parameters. This method should declare a list of metadata for all configurable parameters which may be editable in the GUI. If the returned list is not null and contains at least one parameter, it gets picked up by the Preferences dialog which creates a panel with GUI components allowing to edit the declared configuration parameters.

Specified by:

getPreferences in interface Configurable

Returns:

a list of metadata for all public editable configuration parameters.

setConfiguration

public void setConfiguration(UserConfiguration cfg)

Description copied from interface: Configurable

If an object implementing this interface is a plugin (i.e. implements also the Plugin interface) and is instantiated through a supported plugin factory, the Plugin Manager calls this method right after an instance of this object is created.

Custom objects which do not already have their configuration parameters in the default configuration file should take advantage of this method to store their configuration into the shared User Configuration instance. It is recommended to call the UserConfiguration.saveConfiguration() method in the end to save the configuration to the hard drive.

Objects wishing to be notified of changes of configuration parameters should implement the ConfigurationChangeListener interface and register with the UserConfiguration instance through the addConfigurationChangeListener() method.

Specified by:

setConfiguration in interface Configurable

Parameters:

cfg - global shared instance of user configuration preloaded with parameters from the default and user configuration files.

multiplyWaitTime

protected long multiplyWaitTime(ScriptingContext context,
                                long timeMs)

wait

protected void wait(ScriptingContext context,
                    int delay)

getStablePopupMenuItems

public List getStablePopupMenuItems()

Description copied from interface: CommandHandler

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.

Specified by:

getStablePopupMenuItems in interface CommandHandler

Returns:

list of stable context pop up menu actions.

getContextArgument

public 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

Returns:

dummy context argument value.

getContextAttributes

public Map getContextAttributes()

Get a map with context attributes.

Specified by:

getContextAttributes in interface CommandHandler

Returns:

A hash table containing complete list of supported parameters and their descriptions or list of values.

getContextShortcut

public KeyStroke getContextShortcut()

Description copied from interface: CommandHandler

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.

Specified by:

getContextShortcut in interface CommandHandler

Returns:

hot key invoking insertion of a command template into the GUI editor..

canRunWithoutConnection

public boolean canRunWithoutConnection()

This method should return true if it can be executed even when the tool is not connected to a desktop.

Specified by:

canRunWithoutConnection in interface CommandHandler

Returns:

this implementation always returns false. Commands which do not require a VNC connection for execution need to reimplement this method.

getCode

public String getCode()

Description copied from interface: Plugin

Get plugin code. This string serves as an identifier of the functionality delivered by the plugin. For example, desktop client plugins return protocol name like "RFB" or "RDP" as their code.

Plugin code is used by pluggable instance factories to identify a particular plugin. It may be used to replace internal plugins with third party code. For example if you develop a class which implements this and the com.tplan.robot.remoteclient.RemoteDesktop interfaces and the getCode() method returns "RFB", it will replace the internal implementation of the RFB (VNC) client.

Specified by:

getCode in interface Plugin

Returns:

plugin code (identifier). The name must not be null.

getVendorName

public String getVendorName()

Description copied from interface: Plugin

Get vendor (provider) name to be displayed in the GUI.

Specified by:

getVendorName in interface Plugin

Returns:

vendor name. May be null.

getSupportContact

public String getSupportContact()

Description copied from interface: Plugin

Get support contact. If the contact is a valid mail link like "mailto:<mailaddress>" or an HTTP link like "http://<link>", the application may follow it with appropriate program (mail client or web browser).

Specified by:

getSupportContact in interface Plugin

Returns:

support contact. May be null or a text to be displayed by the GUI or a valid URI.

getVersion

public int[] getVersion()

Description copied from interface: Plugin

Get plugin version in form of an integer array. Major version numbers are first. For example, version 1.2.3 should be represented as new int[] { 1, 2, 3 }.

Specified by:

getVersion in interface Plugin

Returns:

version number.

getImplementedInterface

public Class getImplementedInterface()

Description copied from interface: Plugin

Get Class of the exposed functional interface that this plugin implements. For example remote desktop clients return com.tplan.robot.remoteclient.RemoteDesktopClient.class.

Specified by:

getImplementedInterface in interface Plugin

Returns:

class instance of the implemented functional interface.

requiresRestart

public boolean requiresRestart()

Description copied from interface: Plugin

Indicate whether installation of this plugin requires application restart. If it returns true, users are asked to restart after plugin installation via GUI.

Specified by:

requiresRestart in interface Plugin

Returns:

true if installation of the plugin requires application restart, false otherwise.

getVendorHomePage

public String getVendorHomePage()

Description copied from interface: Plugin

Get the vendor home page. If the contact is a valid HTTP link like "http://<link>", the application may follow it with appropriate program (typically web browser).

Specified by:

getVendorHomePage in interface Plugin

Returns:

vendor home page URL.

getDate

public Date getDate()

Description copied from interface: Plugin

Get plugin release date.

Specified by:

getDate in interface Plugin

Returns:

plugin release date.

getLowestSupportedVersion

public int[] getLowestSupportedVersion()

Description copied from interface: Plugin

Get the lowest required version of T-Plan Robot Enterprise. If user attempts to install the plugin on a lower version, an error is reported.

Specified by:

getLowestSupportedVersion in interface Plugin

Returns:

the lowest T-Plan Robot Enterprise version supported by this plugin.

getMessageBeforeInstall

public String getMessageBeforeInstall()

Description copied from interface: Plugin

Get text of a message to be displayed before installation of this plugin. It may contain any relevant user information.

Specified by:

getMessageBeforeInstall in interface Plugin

Returns:

message to be displayed before installation.

getMessageAfterInstall

public String getMessageAfterInstall()

Description copied from interface: Plugin

Get text of a message to be displayed after installation of this plugin. It may contain any relevant user information.

Specified by:

getMessageAfterInstall in interface Plugin

Returns:

message to be displayed after installation.

getDisplayName

public String getDisplayName()

Get a generic display name.

Specified by:

getDisplayName in interface Plugin

Returns:

generic display name which is derived from the getCmdDisplayName() method.

getDescription

public String getDescription()

Description copied from interface: Plugin

Get plugin description to be displayed in the GUI.

Specified by:

getDescription in interface Plugin

Returns:

plugin description. May be null.

getUniqueId

public String getUniqueId()

Description copied from interface: Plugin

Get unique ID associated with the plugin. The plugin manager uses the ID together with the version string to identify whether a plugin is already installed and whether a newer version of the same plugin is available.

The unique ID in fact identifies a particular plugin delivered by a particular vendor. Plugin developers are recommended to choose an ID and keep it constant for all versions of one particular plugin. The ID is never displayed in the GUI so it doesn't have to be a readable text. To avoid conflicts with other vendors it is recommended to elaborate vendor or author name and feature description into the ID, for example "custom RFB client implemented by John Doe".

Specified by:

getUniqueId in interface Plugin

Returns:

unique plugin ID.

checkDependencies

public void checkDependencies(PluginManager manager)
                       throws DependencyMissingException

Description copied from interface: Plugin

Check whether the current product installation contains all dependencies (other plugins) required to install this plugin. This method is called before the plugin is installed and it should throw a DependencyMissingException if one or more dependencies are missing.

Specified by:

checkDependencies in interface Plugin

Parameters:

manager - shared instance of the plugin manager.

Throws:

DependencyMissingException - when one or more dependencies requested by this plugin is missing.

getIntegerSafely

protected static int getIntegerSafely(UserConfiguration cfg,
                                      String parameter,
                                      int defaultValue)

Retrieve an integer parameter from user configuration in a safe, exception-free way. If the parameter is missing or invalid, the method prints out an error message and returns the default value.

Parameters:

cfg - user configuration (may not be null).

parameter - parameter name.

defaultValue - default value to be returned in case of any failure.

Returns:

parameter value or the default one if loading fails.

getBooleanSafely

protected static boolean getBooleanSafely(UserConfiguration cfg,
                                          String parameter,
                                          boolean defaultValue)

Retrieve a boolean parameter from user configuration in a safe, exception-free way. If the parameter is missing or invalid, the method prints out an error message and returns the default value.

Parameters:

cfg - user configuration (may not be null).

parameter - parameter name.

defaultValue - default value to be returned in case of any failure.

Returns:

parameter value or the default one if loading fails.

compileParameters

public Map compileParameters(Map paramsAndValues,
                             TestScriptInterpret interpret)

createConfigureAction

protected ConfigureAction createConfigureAction()

checkPauseAndStop

protected static boolean checkPauseAndStop(ScriptingContext ctx)

Test whether the script is paused or stopped. This is to be used by commands which perform a series of steps, such as for example multiple mouse or key events. If the script is paused the method makes the current thread sleep until the script gets resumed.

Parameters:

ctx - a context. It must be an execution context or the method will not do anything.

Returns:

true if the script is stopped, false if not.