Qore jni Module  1.2.0
Qore jni Module

Table of Contents

jni Module Introduction

The jni module allows for Java APIs to be used in Qore as if the Java APIs were Qore APIs. The module provides a high-level binding and mapping of Java functionality in Qore as well as run-time data translations back and forth between Java and Qore data.

This module is released under the MIT license (see COPYING.MIT in the source distribution for more information). The module is tagged as such in the module's header (meaning it can be loaded unconditionally regardless of how the Qore library was initialized).

To use the module in a Qore script, use the %requires directive as follows:

%requires jni

Helper Qore classes provided by this module:

Class Description
JavaArray a convenience class for using Java Arrays in Qore
QoreInvocationHandler a convenience class for executing Qore-language callbacks from Java

Helper Qore functions provided by this module:

Function Description
get_version() Returns the version of the JNI API
implement_interface() Creates a Java object that implements given interface using an invocation handler
invoke() Invokes a method with the given arguments
invoke_nonvirtual() Invokes a method with the given arguments in a non-virtual way; meaning that even if the object provided is a child class, the method given in the first argument is executed
load_class() Loads a Java class with given name and returns a java::lang::Class object
new_array() Creates a JavaArray object of the given type and size
set_save_object_callback() Sets the object lifecycle management callback; see Managing the Lifecycle of Qore objects from Java for more information

Examples

JMS Example:
#!/usr/bin/env qore
%new-style
%require-types
%strict-args
%enable-all-warnings
%requires jni
%requires QUnit
%requires Util
# import Java classes to our script
%module-cmd(jni) import javax.naming.InitialContext
%module-cmd(jni) import javax.jms.*
# add environment variable $GLASSFISH_JAR to the dynamic classpath (if set)
%module-cmd(jni) add-classpath $GLASSFISH_JAR
%exec-class Main
public class Main inherits QUnit::Test {
private {
Counter c(1);
auto data;
const TextMsg = "Hello, world!";
}
constructor() : Test("JMS test", "1.0", \ARGV) {
addTestCase("base test", \testJms());
# Return for compatibility with test harness that checks return value.
set_return_value(main());
}
testJms() {
# these properties are the default; included here to provide an example for connecting to a remote server
Properties props();
props.setProperty("java.naming.factory.initial", "com.sun.enterprise.naming.SerialInitContextFactory");
props.setProperty("org.omg.CORBA.ORBInitialHost", "localhost");
props.setProperty("org.omg.CORBA.ORBInitialPort", "3700");
InitialContext ctx(props);
Connection connection = cast<ConnectionFactory>(ctx.lookup("jms/__defaultConnectionFactory")).createConnection();
Session session = connection.createSession(Session::CLIENT_ACKNOWLEDGE);
Destination queue = cast<Destination>(ctx.lookup("abc"));
MessageProducer producer = session.createProducer(queue);
MessageConsumer consumer = session.createConsumer(queue);
# in order to implement the MessageListener interface for the callback, we have to use implement_interface() as follows:
ClassLoader loader = connection.getClass().getClassLoader();
consumer.setMessageListener(cast<MessageListener>(implement_interface(loader, new QoreInvocationHandler(\messageCallback()), Class::forName("javax.jms.MessageListener", True, loader))));
connection.start();
TextMessage message = session.createTextMessage();
message.setText(TextMsg);
producer.send(message);
# wait for message to be received
c.waitForZero();
assertEq(TextMsg, data);
# unset the listener and exit
consumer.setMessageListener(NOTHING);
}
# JMS message callback for the MessageListener interface
messageCallback(Method method, *list args) {
TextMessage msg = args[0];
# ignore redeliveries
if (msg.getJMSRedelivered())
return;
data = msg.getText();
msg.acknowledge();
if (m_options.verbose)
printf("*** JMS message received: %y (id: %y)\n", msg.getText(), msg.getJMSMessageID());
c.dec();
}
}

JVM Initialization

The JVM is initialized when the module is loaded. It is possible to disable JIT when the module is loaded, however the module is loaded an initialized before module parse commands are processed, therefore to tell the module to disable JIT, the following environment variable must be set to 1:

  • QORE_JNI_DISABLE_JIT=1

Importing Java APIs

To import Java APIs into the Qore program; any of the following jni-module-specific parse directives can be used, each of which also causes the jni module to be loaded and initialized:

  • %module-cmd(jni) import java.namespace.path.*
    imports the given wilcard path or class into the Qore program
  • %module-cmd(jni) add-classpath filesystem/path:another/path
    adds the given paths to the runtime dynamic classpath; supports environment variable substitution
  • %module-cmd(jni) add-relative-classpath ../relative/path
    adds the given paths as relative to the current program to the runtime dynamic classpath

All classes in java.lang.* are imported implicitly. Referencing an imported class in Qore code causes a Qore class to be generated dynamically that presents the Java class. Instantiating a Qore class based on a Java class also instantiates an internal Java object that is attached to the Qore object. Calling methods on the object will cause the same Java methods to be called with any arguments provided.

See also
Java Class and Package Mapping for more information

Defining Classes at Parse Time

The jni module also supports defining classes at parse time with the following jni-module-specific parse directives:

  • %module-cmd(jni) define-class <name> <base 64 byte code>
    defines the given class with <name> as the Java internal name for the class (ex: my/package/MyClassName)
  • %module-cmd(jni) define-pending-class <name> <base 64 byte code>
    adds the given class and byte code as a pending class to be defined when required by a define-class directive; this should be used for inner classes and has been implemented to allow circular dependencies in such classes to be resolved; <name> is the Java internal name for the inner class (ex: my/package/MyClassName$1)

Setting Java System Properties at Parse Time

The jni module also supports setting Java system properties at parse time with the following jni-module-specific parse directive:

  • %module-cmd(jni) set-property <propname> <value>
    sets the given property at parse time

JNI Module Compatibility Options

This module supports the following compatibility option: "compat-types" which, when enabled, will disable the following type conversions:

  • Java byte[] to binary; instead this will converted to list<int>
  • Java java.util.Map to hash; instead this will be converted directly

This option can be set globally for all Program objects with set_module_option("jni", "compat-type", True) or locally for the current Program container with the set-compat-type module parse option like: module-cmd(jni) set-compat-type true or module-cmd(jni) set-compat-type false to override the global setting.

Type Conversions Between Qore and Java

The jni module uses reflection to automatically map Java classes to Qore classes. This class mapping and Qore class creation happens at parse time (when importing Java APIs into Qore) and also at runtime (if a new class is encountered that has not already been mapped).

There are two types of conversions:

Qore to Java Defined Type Conversions

The following table describes type conversions for Java types when the jni module must convert a Qore value to the declared type:

Qore to Specific Java Type Conversions

Target Java Type Source Qore Type
boolean any; conversions are made like with boolean()
byte any; conversions are made like with int()
char any; conversions are made like with int()
short any; conversions are made like with int()
int any; conversions are made like with int()
long any; conversions are made like with int()
float any; conversions are made like with float()
double any; conversions are made like with float()

For other types, default conversions are used.

Qore to Java Default Type Conversions

The following table describes type conversions for Java types when the jni module must convert a Qore value to the declared type:

Qore to Java Default Type Conversions

Source Qore Type Target Java Type
bool boolean
int int (note: precision is lost here)
float double
string java.lang.String
date java.time.ZonedDateTime or org.qore.jni.QoreRelativeTime
number java.math.BigDecimal
binary byte[]
NOTHING and NULL void
list java Arrays of the list type; if no list type can be found, then the Array type is java.lang.Object
hash org.qore.jni.Hash (extends java.util.LinkedHashMap), however any type implementing java.util.Map that has a constructor that takes no arguments and a compatibule put() method will be constructed / converted automatically to the desired type
code (closure or call reference) org.qore.jni.QoreClosure
JavaArray java.lang.Array
object to the Java class if the Qore object is an instantiation of java.lang.Object, otherwise org.qore.jni.QoreObject
all jni objects direct conversion
Note
  • Qore 64-bit integers are automatically converted to 32-bit Java integers; to get a Java long value; use:
    new Long(val)
  • see Java Arrays for more information about conversions between Qore lists and Java arrays

Java to Qore Type Conversions

Java to Qore Type Conversions

Source Java Type Target Qore Type
boolean bool
byte int
byte[] binary (see also JNI Module Compatibility Options)
char int
short int
int int
long int
float float
double double
java.lang.String string
java.time.ZonedDateTime date (absolute date)
org.qore.jni.QoreRelativeTime date (relative date)
java.math.BigDecimal number
java.lang.AbstractArray and arrays list
java.util.Map hash (see also JNI Module Compatibility Options)
@ref org.qore.jni.QoreClosure code
org.qore.jni.QoreClosureMarker code
all other objects direct conversion
Note
see Java Arrays for more information about conversions between Qore lists and Java arrays

Java Arrays

Arrays are mapped directly to and from Qore lists. When converting from a Qore list to a Java array, the list is scanned, and if it can be mapped to a single Java type, then an array of that type is created. Otherwise, an array of java.lang.Object is created and the Qore values are mapped directly to Java values.

Qore lists are passed by value and Java arrays are objects (which, like Qore objects, are passed with a copy of a reference to the object). To get similar functionality in Qore, you can use the JavaArray class supplied with the jni module, which is automatically converted to a Java array object like a list, but is also passed with a copy of a reference to the object in Qore.

Java Arrays as Variable Arguments

When a Java method declares variable arguments, such arguments must be generally given as a single array value (so a Qore list or JavaArray object). Consider the following example:

StringBuilder stringBuilder("");
lang::Class stringBuilderClass = lang::Class::forName("java.lang.StringBuilder");
Method stringBuilderAppendLong = stringBuilderClass.getMethod("append", (Long::TYPE,));
stringBuilderAppendLong.invoke(stringBuilder, (20,));
printf("%y\n", stringBuilder.toString());

In the above example, the java.lang.Class.getMethod() and the java.lang.Method.invoke() methods both take a variable number of arguments after the first argument. In the mapped Qore class, these must be given as a Qore list (as in the above example) or a JavaArray object.

If the last argument of a Java method has an array type, then the arguments in Qore can also be given in the flat argument list, and the final array argument will be created automatically for the call.

Because of this, the example above also works as follows:

StringBuilder stringBuilder("");
lang::Class stringBuilderClass = lang::Class::forName("java.lang.StringBuilder");
Method stringBuilderAppendLong = stringBuilderClass.getMethod("append", Long::TYPE);
stringBuilderAppendLong.invoke(stringBuilder, 20);
printf("%y\n", stringBuilder.toString());

Java Class and Package Mapping

Java Package to Qore Namespace Mapping

The jni module maps Java packages to Qore namespaces. Therefore in Java java.lang.String can be referred to as java::lang::String in Qore as in the following example:

java::lang::String str();

The jni module attempts to create Qore classes that match the source Java class as closely as possible to maximize the usefulness of Java APIs in Qore.

When creating Qore class methods from the corresponding Java source method, types are mapped according to Java to Qore Type Conversions. Because Qore has fewer types than Java, this can lead to method signature collissions in the generated Qore class.

In such cases, only the first method returned by the internal call to java.lang.Class.getDeclaredMethods() is mapped.

To call an unmapped method, use reflection to get a java.lang.Method object and make the call using java.lang.Method.invoke() as in the folllowing example:

StringBuilder stringBuilder("");
Method stringBuilderAppendLong = stringBuilderClass.getMethod("append", Long::TYPE);
stringBuilderAppendLong.invoke(stringBuilder, 20);
printf("%y\n", stringBuilder.toString());

Java Inner Classes

Java inner classes are mapped as Qore classes by appending "__" to the outer class's name and then appending the name of the inner class.

For example:

class Outer {
public Outer() {
}
public class Inner {
public Inner() {
}
}
}

The inner class would be created as "Outer__Inner" in Qore.

Subclassing Java Classes

When subclassing Java classes in Qore, the Qore class code is not executed by Java when dispatching method calls in Java itself. This means that overriding Java methods in Qore is only valid for code executed from Qore.

To override a Java method when called from Java, you must subclass the class in Java as well and import the child class into your Qore program.

One exception to this limitation is with interfaces; programmers can use the QoreInvocationHandler class to execute Qore-language callbacks based on Java interfaces; see the documentation for QoreInvocationHandler for more information.

Java Class Fields to Qore Class Mappings

Java fields are mapped to different Qore class members according to the Java type according to the following table.

Java Field to Qore Class Member Mappings

Java Qore Qore Example
static final \td Qore class constants
MyClass::myField
static (non-final) Qore static class members
obj.myField
all others normal Qore class members
obj.myField

For example:

System::out.println("testing...");
Note
Java field values are only stored in Java; they are not mirrored in Qore. Java field values are accessed with the class's memberGate() method; updating a Java object's field value in Qore will not cause the field value to be updated in Java. To update the field's value in Java, use java::lang::reflect::Field::set().

Java Access Mapping

Java access modifiers are mapped directly to Qore access modifiers as in the following table.

Java to Qore Access Mappings

Java Qore
public public
protected private (or private:hierarchy)
private private:internal

Java Classloader

There is a global classloader for all Java objects reachable without special classpath. For all other objects, each Qore Program container has its own custom classloader provided by the jni module that supports a dynamic classpath.

The Qore Program-specific dynamic classpath can be set with the import commands as documented in Importing Java APIs.

Explicit class loaders can also be used as in Java as in the following example:

softlist urls = (new URL("file:///my/dir/my-api.jar"));
URLClassLoader classLoader(urls);
Class myClass = classLoader.loadClass("MyClass");

Java Exceptions in Qore

If a org.qore.jni.QoreException exception is thrown, then it is mapped directly to a Qore exception.

Other Java exceptions are mapped to the Qore ExceptionInfo hash as follows:

  • err: always "JNI-ERROR"
  • desc: the full Java class name of the exception class; ex: "java.lang.RuntimeException"
  • arg: the exception object itself as a Qore object wrappingg the Java object

Exception locations including call stack locations reflect the actual Java source location(s), and in such cases the lang attribute will be "Java".

Using the jni Module From Java

Java code can use the jni module and Java classes based on Qore code by calling org.qore.jni.QoreJavaApi.initQore() to initialize the Qore library and the jni module with an existing JVM session. This requires the platform-dependent qore library to be found in a directory set in the java.library.path or by setting the QORE_LIBRARY environment variable to the absolute path of the qore library.

If neither of these are set, then calling org.qore.jni.QoreJavaApi.initQore() will result in a java.lang.UnsatisfiedLinkError exception being raised.

All Java classes for Qore support are located in the qore-jni.jar file.

Example Java source:

import org.qore.lang.qunit.*;
class MyTest {
public static void main(String[] args) throws Throwable {
Test test = new Test("MyTest", "1.0");
test.addTestCase("test", () -> doTest(test));
test.main();
}
private static void doTest(Test test) throws Throwable {
test.assertTrue(true);
}
}

Example compilation command: 

    javac -cp qore-jni.jar MyTest.java

Example run command: 

    java -Djava.library.path=/usr/local/lib -cp qore-jni.jar:. MyTest

Managing the Lifecycle of Qore objects from Java

Qore's deterministic garbage collection approach and reliance on destructors means that Qore objects created by Java must have their lifecycles managed externally.

Java objects wrapping Qore objects (such as org.qore.jni.QoreObject and org.qore.jni.QoreObjectWrapper) hold only weak references to Qore objects.

Java methods in the jni module that explicitly save strong references to Qore objects are as follows:

The strong reference to any Qore object returned by the preceding methods is managed in one of two ways described in the following sections.

Default Qore Object Lifecycle Management

By default, Qore objects are saved in thread-local data, so the lifecycle of the object is automatically limited to the existence of the thread.

The thread-local hash key name used to save the list of objects created is determined by the value of the "_jni_save" thread-local key, if set. If no such key is set, then "_jni_save" is used instead as the literal key for saving the list of objects.

Explicit Qore Object Lifecycle Management

The lifecycle of Qore objects can be managed explicitly by using the set_save_object_callback() function to set a callback that is called every time a Qore object is created using the Java API.

This callback must take a single object argument as in the following example:

hash<string, object> object_cache;
code callback = sub (object obj) {
# save object in object cache, so it doesn't go out of scope
object_cache{obj.uniqueHash()} = obj;
}
set_save_object_callback(callback);

jni Module Release Notes

jni Module Version 1.2

  • fixed crashes handling deleted Qore program contexts (issue 4262)
  • fixed crashes handling Java lambdas wrapping Qore closures and call references (issue 4261)
  • fixed importing AWT classes in headless mode (issue 4231)
  • fixed method calls for methods that return base types where a caller context is required (for Reflection access control, for example) (issue 4093)
  • fixed a memory leak (or an assertion crash in debug mode) for a duplicate member error when importing Java classes in Qore (issue 4029)
  • added support for converting Qore closures / call references to a Java object (issue 3995)

jni Module Version 1.1.3

jni Module Version 1.1.2

  • use java.util.List<?> instead of java.util.ArrayList<?> as the base class for list conversions (issue 3873)
  • added the org.qore.jni.Hash class to use when passing Qore hashes to Java to make it easier to work with Qore hash data (issue 3868)
  • fixed a crash in Qore Program setup when initiated from a Qore thread with no Java context thread (issue 3862)
  • fixed a crash in method invocation due to incorrect detection of the Java thread context (issue 3794)
  • fixed a bug in SmtpClient.sendMessage()

jni Module Version 1.1.1

jni Module Version 1.1

jni Module Version 1.0.1

  • fixed setting the class loader context when calling Qore code from Java threads (issue 3585)

jni Module Version 1.0

  • initial public release
Jni::org::qore::jni::set_save_object_callback
set_save_object_callback(*code save_object_callback)
Sets the "save object" callback for Qore objects created from Java code.
Jni::org::qore::jni::implement_interface
Jni::java::lang::Object implement_interface(Jni::org::qore::jni::QoreInvocationHandler invocationHandler, Jni::java::lang::Class cls)
Creates a Java object that implements given interface using an invocation handler.