Writing Script Commands

Content:

1. Introduction
2. Setup
3. Command Description
4. Implementation Details

1. Introduction

This document describes how to write your own script command in Java and plug it into the TPR language of the T-Plan Robot Enterprise automated tool.

This is a step-by-step guide based on a real Java command example. For details on the architecture and the plugin framework in general view plugins.

2. Setup

Download the example command source code and extract it to your hard drive:

http://t-plan.ltd.uk/releases/robot/plugins/filecheck.zip

Set up the Java project under your favourite Java IDE. The steps for NetBeans:

  1. Select File->New Project
  2. Select Java Project with Existing Sources in the Java category and click Next
  3. Set the project folder to the filecheck/ one. Set the project name to filecheck and click Next
  4. Add the src/ folder to the Source Package Folders list and click Finish
  5. Right click the filecheck tree node in the project view and select Properties in the pop up menu
  6. Select Libraries, click Add JAR/Folder and add the robot.jar file from your Robot install folder. Close with OK.
  7. Right click the filecheck tree node and select Clean and Build. The project must compile without errors.

Once compiled the command is ready to be used. It is not necessary to package the classes to a JAR file. Robot can work with the class path as well. This makes it easy to develop the command on the fly. If you change the command Java code and rebuild the project you only have to restart Robot to pick up the changes.

To plug the command into Robot:

  1. Open the Robot GUI and select Tools->Plugins
  2. Select the Available Plugins tab. Click the Add JAR, ZIP Or Classpath button and add the path containing the compiled classes (filecheck/build/classes).
  3. Select the FileCheck Command plugin and click Install. The command will be ready to use after Robot restart.

3. Command Description

The example contains a single command called Filecheck. It accepts a mandatory file path plus two other optional parameters. The goal is to check existence of the file and expose its attributes such as the size, last modification time and type (file/directory) to the calling script.

The command has a typical syntax of:

Filecheck file="<path>" timeformat="<date|time>" list="<true|false>"

where

file is mandatory and specifies the file to be checked.

timeformat is optional and may be either "date" or "time". If the parameter is "date" or is not specified the command will save the last file modification time as regular human readable date. If the parameter is "time" it will be a number of milliseconds elapsed since the 1 of January 1970 (the native Java time). This parameter is an example of enumerated ("one of") type.

list is an optional boolean value of "true" or "false". If it is set to "true" and the argument file is a directory the command will list all files it contains. The default value is "false" (do NOT list).

The command returns the exit code of 0 (pass) if the file exists or 1 (fail) otherwise. The calling script may check the result by testing of the _EXIT_CODE variable.

When the file exists the command populates the FNAME, FSIZE, FTIME and FDIR  variables with the file name, size, last modification time and a flag indicating whether the file is a directory ("true") or a file ("false"). If the file is a directory and the "list=true" parameter is specified the command populates also the FCOUNT variable with the number of files in the directory and creates numbered variables (FNAME_1, FNAME_2, FSIZE_1, FSIZE_2, ...) for each file.

For example, a check of the "C:\Program Files (x86)\Java" folder may create a set of variables like:

4. Implementation Details

The example contains a single com.tplan.samples.FileCheckCommand class:

  • The class implements the Plugin interface to enable discovery and installation through the Robot's Plugin Manager window.
  • The CommandHandler interface specifies the minimum functionality for a scripting command. When implemented the command may be typed manually into the script but there is no user friendly support in the GUI. This example defines all methods from the scratch. You may avoid some of the overhead by extending the AbstractCommandHandlerclass instead.
    • The getStablePopupMenuItems() method allows to inject actions (menu items) into the command right click menu. The example demonstrates this functionality on the "Show last checked file" action.

  • Implementation of the AdvancedCommandHandler and EditorFriendlyCommandHandler interfaces ensures that the parameters supported by the command are declared properly to enable these GUI features:
    • The command appears in the "green plus" menu of the script editor:

    • Right click the command in the editor and select Properties to open the command editor:

TIPS & TICKS:

  • See the comments in the FileCheckCommand class for more details.
  • The command may optionally implement the Configurable interface to declare any preferences it wishes to be stored to the user configuration file. Commands implementing the interface and returning a non-empty parameter list from the getPreferences() method are automatically exposed in the Edit->Preferences window. To load user preference values in your command use UserConfiguration.getInstance().
  • Writing of new commands is expensive because there are many methods to be implemented. It is easier to put your custom functionality into a Java script and call it from a TPR script using the Run command. See the Java Scripts And TPR chapter of our dev guide for details and an example. The advantage of this solution is that Java scripts don't have to be installed and they may be shipped within your Robot project. This makes the solution independent from the Robot configuration.
  • Should you have any question please contact the T-Plan Support team.