JEXIT

The JEXIT function provides a means to interface with a method in an external Java class. Using this function, you can manipulate simple primitive types, simple objects, and complex objects.

There are two required text parameters for a JEXIT function. The first text parameter is the class name or key, depending on which meaning you use. The second text parameter is the method name. There are two optional text parameters for the data.

The first use of the JEXIT function creates an object that is based on the specified class name. Then, it invokes the named Java method, with any specified parameters, on that object. After the Java objects method is invoked, then JEXIT automatically destroys the Java object. If multiple invocations on the same Java object are required, then the predefined "<init>" function can be used in the second parameter of Meaning 1. The returned key from the "<init>" function now references a specific Java object and can then be used multiple times as the first parameter in Meaning 2 function calls.

The second use of the JEXIT function invokes the named Java method, with any specified parameters, on a specific Java object. The method is invoked by using the specified key. This method allows Java objects to be manipulated throughout the map's execution cycle. These Java objects are stored in the HCL® OneTest™ Data object pool and are referenced during map execution by using the specified key. The specified key can be returned from either a JEXIT meaning 1 or meaning 2 invocation, particularly when a non-scalar, complex Java object must be returned.

JEXIT is not supported on CICS, Batch, or MVS.

Prerequisites

To use JEXIT, do the following configuration steps, depending on the HCL® OneTest™ Data product you are using.

For HCL® OneTest™ Data with Command Server or HCL® OneTest™ Data with Launcher, either add the Java classes to your system class path or add the JAR files to the install_dir/dtx.ini file.

Add the JAR files to the jar statements under the [External Jar Files] section of the dtx.ini file. For each JAR file, uncomment a jar statement and add the fully qualified path and JAR file name, including the file extension. If a jar statement is already set to a value, add the JAR file to the next jar statement in the sequence. As an example, if the jar1 statement is set to a value, and the jar2 statement is not set to a value, add your JAR file to the jar2 statement.

For HCL® OneTest™ Data, on Windows operating systems, copy the JAR file to the classes folder in the path where version of application is installed. As an example, copy the JAR file to %MQSI_WORKPATH%\shared-classes. On UNIX operating systems, copy the JAR file to the $MQSI_WORKPATH/shared-classes.

If you are using Meaning 1, a public default constructor must be declared in the external Java class. If the default constructor is not available or needed, you can use the "<init>" method to instantiate the Java object, but only when there is a class constructor that is defined with one or two string-type parameters.

Syntax

JEXIT ("single-text-expression"
, "single-text-expression" , ["single-text-expression"] , ["single-text-expression"])

Returns

A single text item.

Meaning 1

JEXIT (class_name, method_name,
[input_to_the_function_or_key], [input_to_the_function_or_key])

Using this approach, you provide a Java class and method name, and two optional inputs to the function.

When JEXIT is used in a map rule, at run time this function instantiates a Java virtual machine (JVM). The JVM reads your .class or .jar file and creates an object that is based on the defined Java class. The method, along with any specified parameters, is then invoked on the object.

When the returned object is a complex object, a unique identifier (key) is created that can be used to reference the object in the object pool.

All JEXIT parameters are text strings. Class name and method name are the two required parameters. The two optional parameters are generally input data. At run time, the strings are converted to UTF-8 and passed to the Java method, and the output from Java method is a UTF-8 text string.

The following simple Java class objects are internally converted to strings and returned to the map:

java.lang.Void
java.lang.Short
java.lang.Number
java.lang.Long
java.lang.Integer
java.lang.Float
java.lang.Double
java.lang.Byte
java.lang.Boolean
java.lang.String
java.lang.Character

Meaning 2

JEXIT (key, method_name,
[input_to_the_function_or_key], [input_to_the_function_or_key])

The second use of JEXIT is similar to Meaning 1. The difference is that it assumes that you already have a key that references an object in the object pool. In this scenario, you use JEXIT to invoke a method on an object by using the key as the first required parameter instead of the class name.

Whenever the JEXIT function returns a key, the associated Java object must be deleted before the map completes processing. The object can be deleted by using the predefined JEXIT "<destroy>" method. Failure to invoke the "<destroy>" method results in a JVM memory leak. To prevent the JVM heap from getting fragmented, exhausted, or both, make sure that all object references returned from the JEXIT function are deleted. To delete those object references, use the JEXIT function in the following way:

JEXIT("key", "<destroy>")

Troubleshooting

To retrieve error messages for JEXIT, you can use the VALID and FAIL functions in your map rule. For example:

=VALID(JEXIT("key", "method_name",  "data" ), FAIL(LASTERRORMSG(  )  )  )