converter

Conversion to Java

The Java Converter converts TPR scripts (.tpr) to Java scripts (.java). It is intended to allow easy transition from the TPR script format to pure Java. The tool also enables to convert part of the TPR code to Java, for example where a special functionality unsupported by the TPR format is required, and plug in the resulting Java code back to the TPR scripts using the Include/Run command calls. To perform a conversion open a TPR script and perform one of the following actions:

  1. Right click the TPR code in the script editor and select Export to Java in the context menu.
  2. Right click the script editor tab displaying the script file name and select Export to Java in the context menu.
  3. Press Ctrl+J or select File->Export to Java in the main window menu.

The conversion process opens the Java Converter Window:

The first screen identifies the TPR script source. It is possible to choose between the current script editor content (which may contain unsaved code changes) or the script file.











The second screen identifies the target Java class.

  1. The Target Path field defines the target Java source code location. It is preset to the Java source location of the project the script belongs to (<project_home>/src). It is recommended to leave this setting in order to take the full advantage of the T-Plan Robot Enterprise project support.
  2. The Class Name field contains the target Java class name. It must start with a letter and it may contain just letters (US/ASCII) and digits. It is a common convention that the name starts with a capital letter.
    The field gets by default populated with a class name derived from the source script file name. It is recommended to keep this name because it supports the class identification where the script is referred to by other scripts. See the third screen legend for details.
  3. The Package field defines the target Java package name. The package consists of one or more dot (period) separated names containing letters and digits. From the file point of view the package names will be translated into subdirectories under the target path.
    Though it is possible to leave the field empty and put the resulting Java classes directly into the target path (so called 'default package'), it is not recommended because the files can not be then referred to from other classes located outside of this directory. This is a Java limitation. If you are going to convert multiple scripts which call each other it is recommended to keep them in the same package. This supports automatic script mapping of the Include/Run references.
  4. The Target File field shows the full path of the the target Java class file. The button at the right allows optional selecting of an existing Java class to overwrite (this will refresh the Class Name and Package fields).
  5. The bottom most warning field is by default invisible and displays warnings and/or errors.




The third screen deals with dependencies. A dependency is another script which is being called by the converted script through the Include/Run commands. This screen is visible only if there is at least one dependency.

  1. The dependency table shows the list of the direct and indirect dependencies. The direct dependency means that the converted script calls another script. The indirect dependency means that the converted script calls another script which references yet another script (and so on).
    The dependency controls below the table work with the currently selected dependency:
  2. The File field is read only and shows the dependency file name.
  3. The Action drop down and the Class Name field allow to set up two modes:
    • The "Convert to a new Java class" option will make the converter convert the dependency to a new Java class specified by the Class Name field. The field gets by default populated with a class name derived from the dependecy script file name. This option is suitable when the dependency hasn't been converted yet.
    • The "Map to an existing Java class" option will map the dependency onto the specified Java class. This mode is typically used when the dependency has been already converted to Java or the dependency is being delivered in form of a precompiled JAR file on the T-Plan Robot Enterprise class path.
    The wizard by default searches the target path for already converted scripts and populates the table accordingly. The mapping is successful under the following conditions:
    1. The script class source code (the .java file) is present in the target path (any package except for the default/root one).
    2. The script class can be compiled successfully (it contains no syntax errors).
    3. The script class contains a valid ClassInfo annotation which is being generated by the converter. It contains information about the source TPR script (file path,  CRC check sum at the time of conversion) and the converter (version). These annotations are used only for conversion purposes and they may be optionally removed from the scripts  after the conversion is finished.
       
    If the converter fails to map the existing dependencies or the dependencies are being plugged in in another form (for example as a standalone JAR file on the application class path) it is necessary to provide the mapping manually by entering the fully qualified Java class name (<package>.<classname>) into the Class Name field.
  4. The Error Field shows any errors detected for the selected options. The most common error messages:

Selected Action

Message Fragment

Recommended Steps

Convert to a new Java class

The target Java file ... exists and will be overwritten

This is just a warning that the dependency conversion will overwrite the already existing Java file.

Map to an existing Java class

The [...] file seems to have been modified after its conversion...

The TPR script has been modified after it was converted to Java and it is assumed that the Java version is out of date. If you are sure that you haven't made any changes to the TPR script code it's safe to ignore the warning. Otherwise it is recommended to reset the Action field to "Convert to a new Java class" to force the dependency reconversion.

There are multiple Java classes...This warning informs that the source TPR script was converted more than once into two or more different Java classes. The auto mapper will select the best matching class by the CRC match and the earliest Java class file modification time stamp. It is recommended to cancel the process, delete all duplicit classes except for the right one and resume the conversion process.

The [...] class doesn't exist or can't be instantiated.

The class entered into the Class Name field is not available or is available as .java which can't be compiled for syntax errors. It is recommended to cancel the conversion process and fix the class (if it exists as .java) or put the JAR containing the class onto the T-Plan Robot Enterprise class path (for external scripts delivered as an add-on).


The fourth screen is a confirmation one. There are one or two options allowing to open the resulting Java class (classes) in the script editor. To start the conversion process select Next.

The last screen shows the conversion progress and results. If processing of the source TPR file or any of the dependencies fails for some reason the window provides the instructions on how to resolve it.

A typical fail scenario is that the script (or any of the dependencies) gets converted to .java but fails to compile for syntax errors. This is possible due to the fact that some of the TPR script constructions can not be converted to Java. The general steps are to fix the resulting Java code manually and repeat the conversion process if it did not finish conversion of all planned files. A non-exhaustive list of known limitations:

    • Regular expressions may fail to convert correctly for ambiguity of curly braces ('{}') which are used by the TPR language for variable calls (if the variable exists) or as regular characters (if the expression enclosed by the curly braces doesn't correspond to an existing variable).