T-Plan Robot Enterprise 4.0
Build No. 4.0-20140924.1

com.tplan.robot.scripting.commands
Class AbstractCommandHandler

java.lang.Object
  extended by com.tplan.robot.scripting.commands.AbstractCommandHandler
All Implemented Interfaces:
com.tplan.robot.gui.GUIConstants, Plugin, Configurable, CommandHandler

public abstract class AbstractCommandHandler
extends java.lang.Object
implements CommandHandler, com.tplan.robot.gui.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-2014 T-Plan Limited. All rights reserved.


Field Summary
protected static java.lang.String ALT
           
static java.lang.String CONTEXT_COMMAND_CALL_COMPILED_PARAMETER_MAP
           
static java.lang.String CONTEXT_COMMAND_CALL_SOURCE_PARAMETER_MAP
           
protected static java.lang.String CONTEXT_COMPILE_SINGLE_COMMAND_MODE
           
protected static java.lang.String CONTEXT_LAST_WAIT_FACTOR
           
protected static java.lang.String CONTEXT_WAIT_FACTOR_ERR_MSG_SHOWN
           
protected static java.lang.String CTRL
           
static java.lang.String PARAM_COUNT
           
static java.lang.String PARAM_ONFAIL
           
static java.lang.String PARAM_ONPASS
           
static java.lang.String PARAM_WAIT
           
protected static java.lang.String SHIFT
           
protected static java.lang.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, PROPERTY_EXIT_REQUESTED
 
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.
 java.util.Map compileParameters(java.util.Map paramsAndValues, TestScriptInterpret interpret)
           
protected  com.tplan.robot.gui.preferences.ConfigureAction createConfigureAction()
           
 void executeFallBackCodeOrProcedure(java.lang.String code, java.lang.String procedure, java.lang.String[] procedureArgs, ScriptingContext ctx)
           
 void fireCommandEvent(java.lang.Object source, ScriptingContext context, java.lang.String actionCode, java.lang.Object customObject)
           
protected static boolean getBooleanSafely(UserConfiguration cfg, java.lang.String parameter, boolean defaultValue)
          Retrieve a boolean parameter from user configuration in a safe, exception-free way.
 java.lang.String getCode()
          Get plugin code.
 java.lang.String getContextArgument()
          Get the dummy command argument.
 java.util.Map getContextAttributes()
          Get a map with context attributes.
 javax.swing.KeyStroke getContextShortcut()
          Get preferred hot key for the GUI command wizard.
 java.util.Date getDate()
          Get plugin release date.
 java.lang.String getDescription()
          Get plugin description to be displayed in the GUI.
 java.lang.String getDisplayName()
          Get a generic display name.
 java.lang.Class getImplementedInterface()
          Get Class of the exposed functional interface that this plugin implements.
protected static int getIntegerSafely(UserConfiguration cfg, java.lang.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.
 java.lang.String getMessageAfterInstall()
          Get text of a message to be displayed after installation of this plugin.
 java.lang.String getMessageBeforeInstall()
          Get text of a message to be displayed before installation of this plugin.
 java.util.List<Preference> getPreferences()
          Get metadata of displayable/editable configurable parameters.
 java.util.List getStablePopupMenuItems()
          Get a list of stable actions.
 java.lang.String getSupportContact()
          Get support contact.
 java.lang.String getUniqueId()
          Get unique ID associated with the plugin.
 java.lang.String getVendorHomePage()
          Get the vendor home page.
 java.lang.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(java.lang.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)
           
protected  boolean reloadCommand(java.util.List args, java.util.Map values, ScriptingContext ctx)
          Reread a command and re-parse it's parameters.
 void removeCommandListener(CommandListener listener)
          Removes a CommandListener from the listener list.
 boolean requiresOriginalValues()
          Indicate whether the handler is interested in key-value pairs exactly as they are specified on the command line.
 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.
static java.util.LinkedHashMap<java.lang.String,java.lang.Object> toLinkedMap(java.lang.String command, java.util.List args, java.util.Map params)
          Convert the old fashioned set of command parameters in a List and a Map to a single LinkedHashMap instance.
 void validateOnPassAndOnFail(ScriptingContext repository, java.util.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 java.lang.String PARAM_WAIT
See Also:
Constant Field Values

PARAM_COUNT

public static final java.lang.String PARAM_COUNT
See Also:
Constant Field Values

PARAM_ONFAIL

public static final java.lang.String PARAM_ONFAIL
See Also:
Constant Field Values

PARAM_ONPASS

public static final java.lang.String PARAM_ONPASS
See Also:
Constant Field Values

SHIFT

protected static final java.lang.String SHIFT
See Also:
Constant Field Values

CTRL

protected static final java.lang.String CTRL
See Also:
Constant Field Values

ALT

protected static final java.lang.String ALT
See Also:
Constant Field Values

WINDOWS

protected static final java.lang.String WINDOWS
See Also:
Constant Field Values

CONTEXT_COMPILE_SINGLE_COMMAND_MODE

protected static final java.lang.String CONTEXT_COMPILE_SINGLE_COMMAND_MODE
See Also:
Constant Field Values

CONTEXT_COMMAND_CALL_COMPILED_PARAMETER_MAP

public static final java.lang.String CONTEXT_COMMAND_CALL_COMPILED_PARAMETER_MAP
See Also:
Constant Field Values

CONTEXT_COMMAND_CALL_SOURCE_PARAMETER_MAP

public static final java.lang.String CONTEXT_COMMAND_CALL_SOURCE_PARAMETER_MAP
See Also:
Constant Field Values

CONTEXT_WAIT_FACTOR_ERR_MSG_SHOWN

protected static final java.lang.String CONTEXT_WAIT_FACTOR_ERR_MSG_SHOWN
See Also:
Constant Field Values

CONTEXT_LAST_WAIT_FACTOR

protected static final java.lang.String CONTEXT_LAST_WAIT_FACTOR
See Also:
Constant Field Values
Constructor Detail

AbstractCommandHandler

public AbstractCommandHandler()
Method Detail

validateOnPassAndOnFail

public void validateOnPassAndOnFail(ScriptingContext repository,
                                    java.util.Map params)
                             throws SyntaxErrorException
Throws:
SyntaxErrorException

executeFallBackCodeOrProcedure

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

isGlobalPrerequisity

public boolean isGlobalPrerequisity(java.lang.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(java.lang.Object source,
                             ScriptingContext context,
                             java.lang.String actionCode,
                             java.lang.Object customObject)

getPreferences

public java.util.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 java.util.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 java.lang.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 java.util.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 javax.swing.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.util.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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,
                                      java.lang.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,
                                          java.lang.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.

toLinkedMap

public static java.util.LinkedHashMap<java.lang.String,java.lang.Object> toLinkedMap(java.lang.String command,
                                                                                     java.util.List args,
                                                                                     java.util.Map params)
Convert the old fashioned set of command parameters in a List and a Map to a single LinkedHashMap instance.

Parameters:
command - the command name.
args - the list of arguments.
params - the map of parameters and their values.
Returns:
the linked hash map with the command name in the first place and the command parameters.

compileParameters

public java.util.Map compileParameters(java.util.Map paramsAndValues,
                                       TestScriptInterpret interpret)

createConfigureAction

protected com.tplan.robot.gui.preferences.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.

reloadCommand

protected boolean reloadCommand(java.util.List args,
                                java.util.Map values,
                                ScriptingContext ctx)
Reread a command and re-parse it's parameters.

Parameters:
args - list for the argument(s) and parameter names.
values - map of parameters and their values.
ctx - the current context.
Returns:
true if the command was reloaded successfully or false otherwise.
Since:
3.5

requiresOriginalValues

public boolean requiresOriginalValues()
Indicate whether the handler is interested in key-value pairs exactly as they are specified on the command line. The parser is then expected to avoid any specific parsing, such as replacement of '\"' with '"' etc.

Returns:
true to receive values as they are specified, false to receive pre-formatted values.
Since:
3.5.1

T-Plan Robot Enterprise 4.0
Build No. 4.0-20140924.1