Java Objects in Scripts
Java is a strongly-typed language. Each element of data must be described by one of the valid Java data types, including boolean, byte, char, double, float, integer, long, null and short.
Note: The boolean value is passed as "1" (true), or "0" (false). The Java special null type can have only one value, the null reference.
Java is strictly "pass-by-value." The parameters and argument expressions are passed by their values in Java. Although objects are addressed through reference variables, the variables themselves are passed by the value of the reference. An explanation of the terms that demonstrates the distinction between pass-by-value, and pass-by-reference:
• Pass-by-value means that the parameter or argument is evaluated and the value is copied into a location on the stack that is used to hold the formal parameter value during method execution.
• Pass-by-reference means that the formal parameter is a pointer (alias, reference) to the actual parameter.
JavaVM Objects
A JavaVM object represents a reference to a Java Virtual Machine (JVM). You may create multiple JavaVM objects, but they all reference the same loaded JVM instance. Each JavaVM object, however, maintains its own classloader and classpath. These classloaders delegate to the system classloader.
A JavaVM object supports two primary operations:
• Creating instances of Java classes - To create a new Java object, use the new keyword on a JavaVM instance. Assuming the required setup has been completed (described later), the following example creates an instance of the HelloWorld class:
Dim jhello As JavaObject
Set jhello = jvm.New HelloWorld()
The empty parentheses indicate that the no-argument constructor is used. To call a constructor that takes arguments, include them inside the parentheses. EZscript will automatically select the best matching constructor (if one exists) and invoke it with the provided arguments.
• Invoking static Java methods - To call a static Java method without creating an object instance, use the callStaticMethod method on the JavaVM object.
This method requires at least one argument: the fully qualified name of the static method to invoke (for example, "java.util.Calendar.getInstance"). If the method requires arguments, supply them after the method name.
Example: Printing the Current Date and Time
The following example retrieves the current date and time using Java’s Calendar class and prints it. When running under exptest (an interactive EZscript test and debugging environment), print is used; when running in a process, replace print with LogMessage.
Dim jvm As JavaVM
Set jvm = New JavaVM
Dim calendar As JavaObject
Set calendar = jvm.callStaticMethod("java.util.Calendar.getInstance")
Dim dateobj As JavaObject
Set dateobj = calendar.getTime()
print("Calendar value: " & dateobj.toString())
This example demonstrates how to invoke a static Java method, work with returned Java objects, and call instance methods from EZscript.
Class Objects
The scripting language supports Java class objects from within a transformation. The Java object can be used to call any method available to the object from within its underlying Java class. You can pass parameters in the method calls and any value returned from the method call can be used within the transformation.
Note: For the Java objects to work correctly, open the DataConnect.ini file (available in c:\Program Files\Actian\dc-rcp-64-bit-<DataConnect_version>\ folder) in a Text Editor and add -Ddi.custom.classpath=c:\dev\test\javaobjecttests\JavaObjectTest-<userversion>-SNAPSHOT.jar as shown, pointing to the jar containing your java objects:
-vm
C:\Program Files\Actian\dc-rcp-64-bit-<DataConnect_version>\di-standalone-engine-<DataConnect_version>\jre\bin\javaw
-vmargs
-Ddi.custom.classpath=c:\dev\test\javaobjecttests\JavaObjectTest-<userversion>-SNAPSHOT.jar
-Dosgi.requiredJavaVersion=1.8
-Xms256m
-Xmx2048m
Class Loading Hierarchy
When a request is made to load a Java class for the object in an EZscript expression, the Actian DataConnect engine locates the class according to the following class loading hierarchy:
1. Core jar files located in the <installdir>\runtime\di9\jars folder.
Note: Do not add add custom code to the <installdir>\runtime\di9\jars folder. Custom code is not supported in this location.
2. The JVM classpath this is provided in the Execution tab of the run-time configuration for the project that contains the EZscript expression.
3. Project attachment .jar files in the project that contains the EZscript expression.
If the engine is unable to locate the class, it reports a "Class not found" exception.
Note: If you change the context class loader in the custom classes that are called from EZscript, then you must cache and restore the custom classloader before the control is returned to EZscript.
Example
This is an example of embedded Java objects within scripting. To use this within expressions, create and declare the Java object in a TransformationStarted event. To see this example in action, copy and paste it into a TransformationStarted execute action.
'Declare and create the JVM object
'Javavm is DJExpression Language's java virtual machine object.
Dim jvm as javavm
'-Djava.class.path=" specifies path to location of class file(s) to be accessed using the Java object.
jvm = new javavm("-Djava.class.path=.")
'Declare and create the Java object. Javaobject is the Java object.
'HelloWorld()" calls java constructor for HelloWorld class
Dim jhello as javaobject
jhello = jvm.new HelloWorld()
'Call sayHello() method in HelloWorld.class
jhello.sayHello()
'Call getHelloString( ) method in HelloWorld class and assign Value returned to variable result
result = jhello.getHelloString()
LogMessage("Info","This is from getHelloString: " & result)
'call and pass a string to getHelloString( ) method in HelloWorld
'class and assign value returned to variable result
result = jhello.getHelloString("from jni")
LogMessage("Info","This is from getHelloString(from jni): " & result)
'call and pass an integer to getHelloString( ) method in HelloWorld
'class and assign value returned to variable result
result = jhello.getHelloString(10)
LogMessage("Info","This is from getHelloString(10): " & result)
'destroy the java object
jhello = nothing
This is the contents of the HelloWorld.java file used to create the HelloWorld.class file:
public class HelloWorld
{
public static void main(String[] args)
{
HelloWorld h = new HelloWorld();
System.out.println("HelloString is " + h.getHelloString());
h.sayHello();
HelloWorld h2 = new HelloWorld("This is the second constructor");
}
public HelloWorld () {}
public HelloWorld (String s)
{
hellostring = s;
}
public void sayHello()
{
System.out.println(hellostring);
}
public String getHelloString()
{
return "Hello from a String method";
}
public String getHelloString(String u)
{
return "getHelloString says '" + u + "'";
}
private String hellostring = "Hello from the HelloWorld class";
}