T-Plan Robot Enterprise 5.0.1
Build No. 5.0.1-20190308.1

com.tplan.robot
Class ApplicationSupport

java.lang.Object
  extended by com.tplan.robot.ApplicationSupport
All Implemented Interfaces:
ConfigurationChangeListener, java.util.EventListener

public final class ApplicationSupport
extends java.lang.Object
implements ConfigurationChangeListener

Main class and entry point of the application. It is responsible for initialization of global objects, localization and multithreading support, parsing of the input CLI options and startup of the program.

When an instance of this class is created, the following tasks are carried out:

The class is also owner of global objects and services which are used widely across all project classes. They are:


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


Field Summary
static java.lang.String APPLICATION_BASE_PACKAGE
          Base Java package name ("com.tplan.robot").
static java.lang.String APPLICATION_BUILD
          Build identifier (value: "5.0.1-20190308.1").
static java.lang.String[][] APPLICATION_CLI_OPTIONS
          Array of application CLI options.
static java.lang.String APPLICATION_CONFIG_DIR
           
static java.lang.String APPLICATION_CONFIG_FILE
           Configuration file path.
static java.lang.String APPLICATION_DOC_DIR_NAME
          Name of the online docs/ subdirectory containing this product documentation (value: "v4.4ee").
static java.lang.String APPLICATION_DOC_HOME_PAGE
          Online document home page URL.
static boolean APPLICATION_ENABLE_TPP
          Name for the log file directory in the system temporary path.
static java.lang.String APPLICATION_HELP_HOME_PAGE
          Root folder of the online product help.
static java.lang.String APPLICATION_HELP_SET_DIR
          Root folder of the installed help files.
static java.lang.String APPLICATION_HELP_SET_FILE
          Name of the application JavaHelp help set file (*.hs).
static java.lang.String APPLICATION_HOME_PAGE
          Application home page URL.
static java.lang.String APPLICATION_LEGACY_CONFIG_FILE
          Legacy v1.x configuration file path.
static java.lang.String APPLICATION_LICENSE_FILE
          Application license file name.
static java.lang.String APPLICATION_LOG_FILE_DIR_NAME
          Name for the log file directory in the system temporary path.
static java.lang.String APPLICATION_NAME
          Product name.
static java.lang.String APPLICATION_NAME_SHORT
          Short product name (since 4.4.2).
static java.lang.String APPLICATION_RESOURCE_BUNDLE_PREFIX
          Prefix of resource bundle names (property files with software messages, value: "Messages").
static java.lang.String APPLICATION_RESOURCE_ENTERPRISE_BUNDLE_PREFIX
          Prefix of enterprise resource bundle names (property files with software messages, value: "Bundle").
static java.lang.String APPLICATION_SUPPORT_CONTACT
          Application support page URL.
static java.lang.String APPLICATION_SUPPORT_EMAIL
          Application support E-mail.
static java.lang.String APPLICATION_TUTORIAL_HOME_PAGE
          Online tutorial home page URL.
static java.lang.String APPLICATION_VERSION
          Version identifier (value: "5.0.1").
static java.lang.Object lc
           
static java.lang.String VENDOR_HOME_PAGE
          Vendor home page.
static java.lang.String VENDOR_NAME
          Vendor name.
 
Constructor Summary
ApplicationSupport()
          Constructor.
 
Method Summary
 void addLicenseListener(LicenseListener listener)
          Add a listener interested in license usage notifications.
 void configurationChanged(ConfigurationChangeEvent evt)
          Implementation of the ConfigurationChangeListener interface.
 AutomatedRunnable createAutomatedRunnable(JavaTestScript testScript, java.lang.String threadId, java.lang.String[] argv, java.io.PrintStream logStream, boolean exitOnFinish)
          Create an automated runnable prepared to execute a compiled Java test script.
 AutomatedRunnable createAutomatedRunnable(Schedule schedule, java.lang.String threadId, java.lang.String[] argv, java.io.PrintStream logStream, boolean exitOnFinish)
          Create an automated runnable prepared to execute a schedule (test suite).
 AutomatedRunnable createAutomatedRunnable(java.lang.String threadId, java.lang.String[] argv, java.io.PrintStream logStream, boolean exitOnFinish)
          Create an automated testing thread.
static java.util.List<java.util.Locale> getAvailableLocales()
          Get the list of supported locales (resource bundles aka language packs).
static java.io.InputStream getImageAsStream(java.lang.String name)
          Get input stream of an image from the image repository.
static javax.swing.ImageIcon getImageIcon(java.lang.String name)
          Get an icon from the image repository.
static java.lang.String[] getInputArguments()
          Get the input CLI arguments.
static java.util.Locale getLocale()
          Get the locale that this program was originally started in.
static java.lang.String getOnlineHelpHome()
          Get URL of the online help home folder.
static java.lang.String getOnlineHelpPage(java.lang.String relativePath)
          Get URL of an online help topic.
static java.lang.String getProperty(java.lang.String name)
          Get a build property.
static com.tplan.robot.l10n.CustomPropertyResourceBundle getResourceBundle()
          Get the resource bundle.
static ApplicationSupport getSharedInstance()
           
static java.lang.String getString(java.lang.String key)
          Get a string from the resource bundle.
static java.lang.String getString(java.lang.String key, java.lang.Object... messageFormatArgs)
          Get a string from the resource bundle and populate its MessageFormat parameters.
static boolean isGUIMode()
          Test if the tool is running in the GUI mode.
static boolean isStartedAsService()
          Indicate whether the process was started in the service mode, i.e.
static void loadConfiguration()
           
static void logFine(java.lang.String msg)
          Log a message into the log stream, level "FINE".
static void logInfo(java.lang.String msg)
          Log a message into the log stream, level "INFO".
static void logSevere(java.lang.String msg)
          Log a message into the log stream, level "SEVERE".
static void main(java.lang.String[] argv)
          Main application method.
 boolean parseParameters(java.lang.String[] argv, java.util.Map clientParams, java.util.Map scriptVariables, java.util.Map options, java.util.Map guiParams, java.util.Map scriptingParams, boolean postValidate)
          Parse CLI options which were used to start the application.
 boolean parseParameters(java.lang.String[] argv, java.util.Map clientParams, java.util.Map scriptVariables, java.util.Map options, java.util.Map guiParams, java.util.Map scriptingParams, boolean postValidate, java.lang.StringBuilder err)
           
 void removeLicenseListener(LicenseListener listener)
          Remove an object from the list of license listeners.
static void setLocale(java.util.Locale locale)
          Set the current locale.
static void setResourceBundle(com.tplan.robot.l10n.CustomPropertyResourceBundle r)
          Set the resource bundle.
static void updateLookAndFeel()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

APPLICATION_VERSION

public static final java.lang.String APPLICATION_VERSION

Version identifier (value: "5.0.1"). See the T-Plan Robot Enterprise roadmap for information on builds, releases and versioning.

The variable is manually updated before each release. Please avoid changing the variable name or moving it to another class because it's value is parsed by the building scripts.

See Also:
Constant Field Values

APPLICATION_BUILD

public static final java.lang.String APPLICATION_BUILD

Build identifier (value: "5.0.1-20190308.1"). See the T-Plan Robot Enterprise roadmap for information on builds, releases and versioning.

The variable is manually updated before each release. Please avoid changing the variable name or moving it to another class because it's value is parsed by the building scripts.

See Also:
Constant Field Values

APPLICATION_DOC_DIR_NAME

public static final java.lang.String APPLICATION_DOC_DIR_NAME
Name of the online docs/ subdirectory containing this product documentation (value: "v4.4ee").

See Also:
Constant Field Values

APPLICATION_HELP_HOME_PAGE

public static final java.lang.String APPLICATION_HELP_HOME_PAGE
Root folder of the online product help.

Since:
4.4.1

APPLICATION_NAME

public static final java.lang.String APPLICATION_NAME
Product name.


APPLICATION_NAME_SHORT

public static final java.lang.String APPLICATION_NAME_SHORT
Short product name (since 4.4.2).


APPLICATION_HOME_PAGE

public static final java.lang.String APPLICATION_HOME_PAGE
Application home page URL. It gets displayed in several places throughout the application. It is also used as home page link by all internal plugins.


VENDOR_NAME

public static final java.lang.String VENDOR_NAME
Vendor name.

Since:
3.3.1

VENDOR_HOME_PAGE

public static final java.lang.String VENDOR_HOME_PAGE
Vendor home page.

Since:
3.3.1

APPLICATION_DOC_HOME_PAGE

public static final java.lang.String APPLICATION_DOC_HOME_PAGE
Online document home page URL.

Since:
3.3.1

APPLICATION_TUTORIAL_HOME_PAGE

public static final java.lang.String APPLICATION_TUTORIAL_HOME_PAGE
Online tutorial home page URL.

Since:
3.3.1

APPLICATION_SUPPORT_CONTACT

public static final java.lang.String APPLICATION_SUPPORT_CONTACT
Application support page URL. It gets displayed in several places throughout the application. It is also used as support contact by all internal plugins.


APPLICATION_SUPPORT_EMAIL

public static final java.lang.String APPLICATION_SUPPORT_EMAIL
Application support E-mail. It gets displayed in several places throughout the application.

Since:
3.0

APPLICATION_LOG_FILE_DIR_NAME

public static final java.lang.String APPLICATION_LOG_FILE_DIR_NAME
Name for the log file directory in the system temporary path.

Since:
3.5.1

APPLICATION_ENABLE_TPP

public static final boolean APPLICATION_ENABLE_TPP
Name for the log file directory in the system temporary path.

Since:
4.4.1

APPLICATION_LICENSE_FILE

public static final java.lang.String APPLICATION_LICENSE_FILE
Application license file name. It must be bundled with the code in the same folder as this class.

See Also:
Constant Field Values

APPLICATION_RESOURCE_BUNDLE_PREFIX

public static final java.lang.String APPLICATION_RESOURCE_BUNDLE_PREFIX
Prefix of resource bundle names (property files with software messages, value: "Messages"). Default value is "Messages". When the application starts, it looks for all property files starting with this prefix, for example Messages_en.properties or Messages_de_DE.properties. A valid name of resource bundle is [prefix]_[lang]_[country].properties or [prefix]_[lang].properties.

See Also:
Constant Field Values

APPLICATION_RESOURCE_ENTERPRISE_BUNDLE_PREFIX

public static final java.lang.String APPLICATION_RESOURCE_ENTERPRISE_BUNDLE_PREFIX
Prefix of enterprise resource bundle names (property files with software messages, value: "Bundle"). Default value is "Messages". When the application starts, it looks for all property files starting with this prefix, for example Messages_en.properties or Messages_de_DE.properties. A valid name of resource bundle is [prefix]_[lang]_[country].properties or [prefix]_[lang].properties.

See Also:
Constant Field Values

APPLICATION_CONFIG_FILE

public static java.lang.String APPLICATION_CONFIG_FILE

Configuration file path. The application loads the file upon startup.

Since release 4.0 the field is not final to enable functionality of the --cfg CLI option. At the programmatic level it may be customized prior to the first call of this class' constructor. A subsequent change of this field will not cause the process to reload the configuration but it will make it save the preferences to the new location.


APPLICATION_CONFIG_DIR

public static java.lang.String APPLICATION_CONFIG_DIR

APPLICATION_LEGACY_CONFIG_FILE

public static final java.lang.String APPLICATION_LEGACY_CONFIG_FILE
Legacy v1.x configuration file path. We parse it if it exists and map int onto the new configuration keys.


APPLICATION_BASE_PACKAGE

public static final java.lang.String APPLICATION_BASE_PACKAGE
Base Java package name ("com.tplan.robot"). This variable is parsed by the build scripts and used as a path prefix. If the code gets refactored and the base package name is changed, update value of this variable and rebuild the documentation to update the content.

See Also:
Constant Field Values

APPLICATION_HELP_SET_FILE

public static final java.lang.String APPLICATION_HELP_SET_FILE
Name of the application JavaHelp help set file (*.hs).

See Also:
Constant Field Values

APPLICATION_HELP_SET_DIR

public static final java.lang.String APPLICATION_HELP_SET_DIR
Root folder of the installed help files.

See Also:
Constant Field Values

APPLICATION_CLI_OPTIONS

public static final java.lang.String[][] APPLICATION_CLI_OPTIONS

Array of application CLI options. These are the public options described in the documentation.

These options are processed by the private method parseParameters() of this class.

Apart from the official options there's a smaller list of debug flags which can be passed through CLI using the -D parameter of the java command. Each such a flag switches on one hidden feature, typically a debugging output of certain module. To obtain a list of these hidden flags run the application with the --hidden CLI option.


lc

public static java.lang.Object lc
Constructor Detail

ApplicationSupport

public ApplicationSupport()
Constructor.

Method Detail

isGUIMode

public static boolean isGUIMode()
Test if the tool is running in the GUI mode.

Returns:
the method returns true if the GUI has been initialized.
Since:
4.0.2

isStartedAsService

public static boolean isStartedAsService()
Indicate whether the process was started in the service mode, i.e. with the --service CLI option.

Returns:
true if the process runs as a service or false otherwise.
Since:
4.3

getProperty

public static java.lang.String getProperty(java.lang.String name)
Get a build property.

Parameters:
name - property name.
Returns:
the property value.

getSharedInstance

public static ApplicationSupport getSharedInstance()

main

public static void main(java.lang.String[] argv)
                 throws java.lang.Exception
Main application method. It creates an instance of this class, an automation thread (a AutomatedRunnable instance) and starts it.

Parameters:
argv - array of application parameters
Throws:
java.lang.Exception
See Also:
AutomatedRunnable

addLicenseListener

public void addLicenseListener(LicenseListener listener)
Add a listener interested in license usage notifications. See the LicenseListener interface for details.

Parameters:
listener - a license listener. If the listener is already registered, it is not added again to avoid duplicate registrations of the same object.

removeLicenseListener

public void removeLicenseListener(LicenseListener listener)
Remove an object from the list of license listeners. If the argument object is not registered in the list, the method should do nothing.

Parameters:
listener - an object implementing the LicenseListener interface.

getLocale

public static java.util.Locale getLocale()
Get the locale that this program was originally started in.

Returns:
program locale.

getInputArguments

public static java.lang.String[] getInputArguments()
Get the input CLI arguments.

Returns:
CLI arguments.

updateLookAndFeel

public static void updateLookAndFeel()

createAutomatedRunnable

public AutomatedRunnable createAutomatedRunnable(JavaTestScript testScript,
                                                 java.lang.String threadId,
                                                 java.lang.String[] argv,
                                                 java.io.PrintStream logStream,
                                                 boolean exitOnFinish)

Create an automated runnable prepared to execute a compiled Java test script. The method can be also used to display the product GUI.

Only one runnable can be executed at one moment in GUI mode. There's no limitation in CLI mode and this method can be used in a Java program to create a larger number of independent automated testing threads. See the AutomatedRunnable interface documentation for an example.

IMPORTANT: The runnable is stateful and not thread safe. Do not use a single instance repeatedly or in multiple threads. Always create a new instance for each execution process.

Parameters:
testScript - a Java test script to execute in the runnable run() method. The argument may be null provided that the thread is set to run in GUI mode (i.e. the argv[] array doesn't contain the -n/--nodisplay parameter). When such a thread is started it just displays the product GUI.
threadId - a unique string (name) identifying the process, e.g. "my automated task #1". The name is currently not used in any way except to name the thread. Users may take advantage of the name to identify their threads in custom Java programs through methods of java.lang.Thread and java.lang.ThreadGroup.
argv - a string array with CLI options. The parameters are provided the same way as if the product is started from command line. To obtain a complete list of available options see the T-Plan Robot Enterprise CLI Options document and T-Plan Robot Enterprise documentation or run the application with the --help option. Options followed by a value should be specified as two strings in the array, for example new String[] { "--connect", "localhost:1", "--password", "welcome" }.
logStream - a stream for logs from the test script execution. All messages printed out into console in CLI mode will be written to the logStream. To print the logs into the console window use System.out as value. A null value of this argument will suppress all log messages.
exitOnFinish - indicates whether the process should terminate the Java process using System.exit(exitCode) after the automated task gets finished. Third party applications should use the value of false to prevent termination of their Java VM.
Returns:
a new automated testing thread ready to be started.

createAutomatedRunnable

public AutomatedRunnable createAutomatedRunnable(Schedule schedule,
                                                 java.lang.String threadId,
                                                 java.lang.String[] argv,
                                                 java.io.PrintStream logStream,
                                                 boolean exitOnFinish)

Create an automated runnable prepared to execute a schedule (test suite). The method can be also used to display the product GUI.

Only one runnable can be executed at one moment in GUI mode. There's no limitation in CLI mode and this method can be used in a Java program to create a larger number of independent automated testing threads. See the AutomatedRunnable interface documentation for an example.

IMPORTANT: The runnable is stateful and not thread safe. Do not use a single instance repeatedly or in multiple threads. Always create a new instance for each execution process.

Parameters:
schedule - a schedule.
threadId - a unique string (name) identifying the process, e.g. "my automated task #1". The name is currently not used in any way except to name the thread. Users may take advantage of the name to identify their threads in custom Java programs through methods of java.lang.Thread and java.lang.ThreadGroup.
argv - a string array with CLI options. The parameters are provided the same way as if the product is started from command line. To obtain a complete list of available options see the T-Plan Robot Enterprise CLI Options document and T-Plan Robot Enterprise documentation or run the application with the --help option. Options followed by a value should be specified as two strings in the array, for example new String[] { "--connect", "localhost:1", "--password", "welcome" }.
logStream - a stream for logs from the test script execution. All messages printed out into console in CLI mode will be written to the logStream. To print the logs into the console window use System.out as value. A null value of this argument will suppress all log messages.
exitOnFinish - indicates whether the process should terminate the Java process using System.exit(exitCode) after the automated task gets finished. Third party applications should use the value of false to prevent termination of their Java VM.
Returns:
a new automated testing thread ready to be started.
Since:
4.0

createAutomatedRunnable

public AutomatedRunnable createAutomatedRunnable(java.lang.String threadId,
                                                 java.lang.String[] argv,
                                                 java.io.PrintStream logStream,
                                                 boolean exitOnFinish)

Create an automated testing thread. If a test script in the proprietary scripting language is passed among the argv parameters through the -r/--run option, it will be executed.

Only one thread can be created in GUI mode. There's no limitation in CLI mode and this method can be used in a Java program to create a larger number of independent automated testing threads. See the AutomatedRunnable interface documentation for an example.

IMPORTANT: The runnable is stateful and not thread safe. Do not use a single instance repeatedly or in multiple threads. Always create a new instance for each execution process.

Parameters:
threadId - a unique string (name) identifying the process, e.g. "my automated task #1". The name is currently not used in any way except to name the thread. Users may take advantage of the name to identify their threads in custom Java programs through methods of java.lang.Thread and java.lang.ThreadGroup.
argv - a string array with CLI options. The parameters are provided the same way as if the product is started from command line. To obtain a complete list of available options see the T-Plan Robot Enterprise CLI Options document or run the application with the --help option. Options followed by a value should be specified as two strings in the array, for example new String[] { "--connect", "localhost:1", "--password", "welcome" }.
logStream - a stream for logs from the test script execution. All messages printed out into console in CLI mode will be written to the logStream. To print the logs into the console window use System.out as value. A null value of this argument will suppress all log messages.
exitOnFinish - indicates whether the process should terminate the Java process using System.exit(exitCode) after the automated task gets finished. Third party applications should use the value of false to prevent termination of their Java VM.
Returns:
a new automated testing thread ready to be started.

logSevere

public static void logSevere(java.lang.String msg)
Log a message into the log stream, level "SEVERE".

Parameters:
msg - a log message.

logInfo

public static void logInfo(java.lang.String msg)
Log a message into the log stream, level "INFO".

Parameters:
msg - a log message.

logFine

public static void logFine(java.lang.String msg)
Log a message into the log stream, level "FINE".

Parameters:
msg - a log message.

parseParameters

public boolean parseParameters(java.lang.String[] argv,
                               java.util.Map clientParams,
                               java.util.Map scriptVariables,
                               java.util.Map options,
                               java.util.Map guiParams,
                               java.util.Map scriptingParams,
                               boolean postValidate)
Parse CLI options which were used to start the application.

Parameters:
argv - a string array with CLI options. To obtain a complete list of available options see the T-Plan Robot Enterprise CLI Options document or run the application with the --help option.
clientParams - a table to store client specific parameters resulting from parsing of the options, e.g. host name, port, password etc.
scriptVariables - a table to store script variables passed through the -v CLI option.
options - a table to store overridden user options passed through the -o CLI option.
guiParams - a table to store GUI specific parameters resulting from parsing of the options.
scriptingParams - a table to store scripting specific parameters resulting from parsing of the options, e.g. disabling of output (option --nooutput).
postValidate - whether to perform post validation of the parameters.
Returns:
true if the program is running in the CLI mode or false for the GUI mode.

parseParameters

public boolean parseParameters(java.lang.String[] argv,
                               java.util.Map clientParams,
                               java.util.Map scriptVariables,
                               java.util.Map options,
                               java.util.Map guiParams,
                               java.util.Map scriptingParams,
                               boolean postValidate,
                               java.lang.StringBuilder err)

configurationChanged

public void configurationChanged(ConfigurationChangeEvent evt)
Implementation of the ConfigurationChangeListener interface. Whenever the user configuration changes, the method reloads preferences used by this class.

Specified by:
configurationChanged in interface ConfigurationChangeListener
Parameters:
evt - a ConfigurationChangeEvent which describes the change of user configuration.

loadConfiguration

public static void loadConfiguration()
                              throws java.util.MissingResourceException
Throws:
java.util.MissingResourceException

getResourceBundle

public static com.tplan.robot.l10n.CustomPropertyResourceBundle getResourceBundle()

Get the resource bundle. It is an object with all software messages. This class is exclusive owner of the bundle and all other classes are supposed to access it through this static method.

The method is null-safe meaning that it loads the resource bundle on the first call.

Returns:
application resource bundle with all software messages.

getString

public static java.lang.String getString(java.lang.String key)
Get a string from the resource bundle. This is just a convenience method calling getResourceBundle().getString(key).

Parameters:
key - a message key.
Returns:
message from the resource bundle associated with the given key.

getString

public static java.lang.String getString(java.lang.String key,
                                         java.lang.Object... messageFormatArgs)
Get a string from the resource bundle and populate its MessageFormat parameters.

Parameters:
key - a message key.
messageFormatArgs - message format arguments.
Returns:
message from the resource bundle associated with the given key and processed with MessageFormat.
Since:
4.4.1

setResourceBundle

public static void setResourceBundle(com.tplan.robot.l10n.CustomPropertyResourceBundle r)
Set the resource bundle. It is an object with all software messages. This class is exclusive owner of the bundle and all other classes are supposed to access it through the getResourceBundle() static method.

Parameters:
r - a new resource bundle.

setLocale

public static void setLocale(java.util.Locale locale)
Set the current locale.

Parameters:
locale - the new locale.
Since:
4.4.1

getImageIcon

public static javax.swing.ImageIcon getImageIcon(java.lang.String name)
Get an icon from the image repository.

Parameters:
name - image file name, for example "ok15.gif".
Returns:
a new image icon.

getImageAsStream

public static java.io.InputStream getImageAsStream(java.lang.String name)
Get input stream of an image from the image repository.

Parameters:
name - image file name, for example "ok15.gif".
Returns:
input file with the image data.

getOnlineHelpHome

public static java.lang.String getOnlineHelpHome()
Get URL of the online help home folder. The method respects the product configuration and returns the language-specific folder if the current locale is supported (there's a language file packaged inside the JAR) and localized help is enabled. Otherwise it returns value of the APPLICATION_HELP_HOME_PAGE variable.

Returns:
online product help home folder.
Since:
4.4.1

getOnlineHelpPage

public static java.lang.String getOnlineHelpPage(java.lang.String relativePath)
Get URL of an online help topic. If the product is configured to support localized online help the resulting URL may be subject to the current locale. See getOnlineHelpHome().

Parameters:
relativePath - relative help path with regard to the help home, for example "install/install.html" for the Release Notes document.
Returns:
the help page URL like (HTTP).
Since:
4.4.1

getAvailableLocales

public static java.util.List<java.util.Locale> getAvailableLocales()
Get the list of supported locales (resource bundles aka language packs).

Returns:
the list of installed locales.
Since:
4.4.1

T-Plan Robot Enterprise 5.0.1
Build No. 5.0.1-20190308.1