Java Step Types

Purpose

This example demonstrates custom step types for calling methods in Java classes. The step types call compiled Java class files (.class) using the Java Native Interface (JNI) and permit the invocation of methods located within the classes.

Example File Location

<TestStand Public>\Examples\Custom Step Types\Java Step Types\Java Computer Motherboard Test.seq

Highlighted Features

Custom step types

Major API

Engine.UnloadAllModules

Prerequisites

Java Runtime Environment (JRE) version 6 update 16, which you can download from the Oracle website. The Java step types are likely compatible with earlier and later versions of the JRE but have not been tested in JRE versions other than version 6 update 16.

How to Use This Example

The example sequence file, Computer.seq, contains a SequenceFileLoad callback that TestStand automatically executes when you open the sequence file. The SequenceFileLoad callback copies the JavaCall.dll and JavaCall.uir files from the <TestStand Public>\Examples\Custom Step Types\Java Step Types directory to the <TestStand Public>\Components\StepTypes\Java directory. The Java step types call functions within JavaCall.dll, which must be located in a TestStand search directory for the step types to locate the DLL.

The Java step types support the creation and cleanup of the Java virtual machine (JVM) and the manipulation of objects that exist within the JVM through method calls. The step types support the use of all Java primitive types and strings, which you can use to pass data between TestStand and Java objects. The step types rely on JavaCall.dll, which is a LabWindows/CVI library, for TestStand to interface with Java. The library communicates with TestStand using an ActiveX interface and communicates with Java through the JNI.

Java uses the JNI to call compiled code written in C/C++ and to access Java code from C/C++. Refer to the Java Native Interface website for more information about JNI technology.

When you open <TestStand Public>\Examples\Custom Step Types\Java Step Types\Java Computer Motherboard Test.seq in the TestStand Sequence Editor, the Java step types appear in the following groups on the Insertion Palette:

• StartStop—Contains steps that start and destroy the JVM.
• Methods—Contains steps that call a particular Java method in a specified class.
• Static Methods—Contains steps that call a particular static class method in a specified class.

The CallStaticJavaMethod and CallJavaMethod steps consist of Numeric Limit Test, String Value Test, Pass Fail Test, and Action steps.

Use a Java step type to call JavaCall.dll, which extracts information about the step type from TestStand using ActiveX calls and then calls the appropriate method in the JVM using the JNI. For example, use the CallJavaMethod step to call the InvokeJavaMethod function JavaCall.dll, which calls the TestStand Engine to extract the class, method, and parameter information and instantiate the class within the existing JVM. The step identifies and calls the method with parameter values retrieved from TestStand. The JavaCall.dll file then passes the return value back to TestStand.

StartStop Steps

Use the StartJVM and DestroyJVM steps, located under the StartStop group on the Insertion Palette, in pairs around other Java steps to call methods for the contained steps. A typical sequence structure begins with a StartJVM step, which you place in the Setup step group, followed by a number of Methods or Static Methods steps, which you place in the Main step group. Place the DestroyJVM step in the Cleanup step group.

Configure the StartJVM step to provide the class path, which is the path of the Java classes to access. Select the StartJVM step in a sequence and click the Edit Java Class Path Location button on the Step Settings pane to launch the Set Class Path dialog box, in which you can specify the class path. You must include all Java classes that are accessed in the path. If you leave the path empty, the JVM cannot locate the user-written Java classes. Click Browse in the Set Class Path dialog box to launch the Select Paths dialog box, in which you can add directories that contain the Java classes to call.

Methods and Static Methods Steps

The Static Methods steps call static class methods and the Methods steps call other methods of the class. The Methods steps automatically load the appropriate class and create new instances of the class before making the call to the method. The Static Methods steps do not create new instances of the class before making the call.

Methods and Static Methods steps include the following steps:

• Numeric Limit Test—Used to call methods that return a numeric value, such as a byte, integer, short, long, float, or double. You can compare the value returned to a set of limits to determine whether the step passed.
• String Value Test—Used with a method that returns a string value. The step compares the returned value to the expected value.
• Pass/Fail Test—Used with Boolean return values.
• Action—Used with any type of return value.

You can configure Methods and Static Methods steps by selecting a step in the sequence and clicking the Edit Call or Edit Static Call button on the Step Settings pane to launch the Edit Java Call dialog box, in which you can configure the step to call the appropriate Java method.

Tips for Using the Java Step Types

Keep the following tips in mind when you use Java step types in TestStand:

• Before calling any Java methods, you must create the JVM. Call the StartJVM step before you call any of the Methods or Static Methods steps.
• The Methods steps automatically load the appropriate class and allocate an object of that type. The Static Methods steps load only the appropriate class. Neither step type automatically calls the constructor of the class. The example does contain a sample .
• Because Java is case-sensitive, the class name and method names must use the same case as the Java class file specifies.

Compatible Types

The following table shows how data types in TestStand are compatible with certain data types in Java. The Java step types automatically handle the conversion between types.

Computer Motherboard Example

When you open the Computer.seq example sequence file, the SequenceFileLoad callback copies the required files to the appropriate directories. When TestStand executes the Setup step group of the MainSequence, the sequence first obtains the TestStand directory and locates the Java classes to call. The StartJVM step automatically sets the class path and passes it to the JVM. TestStand then calls a static Java method called Start, which creates a new computer object by calling the constructor of the Computer class, to launch a dialog box. You can dismiss the dialog box, and TestStand reads the tests you select to fail from the Java class one call at a time because Java supports only calls by value semantics.

When the calls are complete, the steps in the Main step group call the Java methods. The steps supply a value to the methods that determine whether the test passes or fails. Depending on the supplied value, the method returns a result. If a single step fails, TestStand skips all remaining steps.

The step in the Cleanup step group destroys the JVM.

Limitations

The following are the known limitations of the Java step types:

• The step types currently do not support Java reference types, such as arrays and objects.
• You cannot access the same instantiated object multiple times. Each time a step calls a method on an object, a new object is created. Therefore, all states must be maintained in class variables as static members.
• The step types cannot directly call constructors. The example does contain a sample .
• The step types are not thread-safe. Do not use the step types with the Parallel and Batch process models.

Known Issues

Because you cannot unload the JVM once you load it in a process without exiting the process, the DestroyJVM step does not actually destroy the JVM. Instead, the DestroyJVM step only detaches the current thread, which indicates that the JVM is no longer referenced, so that the JVM can unload in future versions, if required. Refer to the DestroyJavaVM API documentation on the Oracle website for more information about this issue.

You cannot unload the JVM once you load it in a process, and you cannot unload JavaCall.dll when you call the Engine.UnloadAllModules method of the TestStand API. You can unload JavaCall.dll only by exiting the process by closing the sequence editor or user interface. Once you load a Java class file, you must restart the process by restarting the sequence editor or user interface to force the JVM to load any changed or recompiled versions of the Java class.

You cannot change the class search path once TestStand loads the JVM. When TestStand calls the StartJVM step with a given class path, you cannot change the class search path by calling the StartJVM step again with a new class path. You can change the class path only by exiting the process by closing the sequence editor or user interface. You must set the required class paths in the first StartJVM step.

Error Codes and Descriptions

You might receive some error codes when using this example.