QJniObject Class

• Class names need to be fully-qualified, for example: "java/lang/String".

• Method signatures are written as "(ArgumentsTypes)ReturnType", see JNI Types.

• All object types are returned as a QJniObject.

QJniObject provides convenience functions that will use the correct signature based on the provided template types. For functions that only return and take JNI types, the signature can be generate at compile time:

jint x = QJniObject::callMethod<jint>("getSize");
QJniObject::callMethod<void>("touch");
jint ret = jString1.callMethod<jint>("compareToIgnoreCase", jString2.object<jstring>());

These functions are variadic templates, and the compiler will deduce the template arguments from the actual argument types. In many situations, only the return type needs to be provided explicitly.

For functions that take other argument types, you need to supply the signature yourself. It is important that the signature matches the function you want to call. The example below demonstrates how to call different static functions:

// Java class
package org.qtproject.qt;
class TestClass
{
    static TestClass create() { ... }
    static String fromNumber(int x) { ... }
    static String[] stringArray(String s1, String s2) { ... }
}

The signature structure is "(ArgumentsTypes)ReturnType". Array types in the signature must have the [ prefix, and the fully-qualified Object type names must have the L prefix and the ; suffix. The signature for the create function is "()Lorg/qtproject/qt/TestClass;. The signatures for the second and third functions are "(I)Ljava/lang/String;" and "(Ljava/lang/String;Ljava/lang/String;)[Ljava/lang/String;", respectively.

We can call the create() function like this:

// C++ code
QJniObject testClass = QJniObject::callStaticObjectMethod("org/qtproject/qt/TestClass",
                                                          "create",
                                                          "()Lorg/qtproject/qt/TestClass;");

For the second and third function we can rely on QJniObject's template methods to create the implicit signature string, but we can also pass the signature string explicitly:

// C++ code
QJniObject stringNumber = QJniObject::callStaticObjectMethod("org/qtproject/qt/TestClass",
                                                             "fromNumber",
                                                             "(I)Ljava/lang/String;", 10);

For the implicit signature creation to work we need to specify the return type explicitly:

// C++ code
QJniObject string1 = QJniObject::fromString("String1");
QJniObject string2 = QJniObject::fromString("String2");
QJniObject stringArray = QJniObject::callStaticObjectMethod<jstringArray>(
                                                            "org/qtproject/qt/TestClass",
                                                            "stringArray"
                                                            string1.object<jstring>(),
                                                            string2.object<jstring>());

Note that while he first template parameter specifies the return type of the Java function, the method will still return a QJniObject.

After calling Java functions that might throw exceptions, it is important to check for, handle and clear out any exception before continuing. All QJniObject functions handle exceptions internally by reporting and clearing them, saving client code the need to handle exceptions.

Java native methods makes it possible to call native code from Java, this is done by creating a function declaration in Java and prefixing it with the native keyword. Before a native function can be called from Java, you need to map the Java native function to a native function in your code. Mapping functions can be done by calling QJniEnvironment::registerNativeMethods().

The example below demonstrates how this could be done.

Java implementation:

class FooJavaClass
{
    public static void foo(int x)
    {
        if (x < 100)
            callNativeOne(x);
        else
            callNativeTwo(x);
    }

private static native void callNativeOne(int x);
private static native void callNativeTwo(int x);

}

C++ Implementation:

static void fromJavaOne(JNIEnv *env, jobject thiz, jint x)
{
    Q_UNUSED(env);
    Q_UNUSED(thiz);
    qDebug() << x << "< 100";
}

static void fromJavaTwo(JNIEnv *env, jobject thiz, jint x)
{
    Q_UNUSED(env);
    Q_UNUSED(thiz);
    qDebug() << x << ">= 100";
}

void foo()
{
    // register the native methods first, ideally it better be done with the app start
    const JNINativeMethod methods[] =
                {{"callNativeOne", "(I)V", reinterpret_cast<void *>(fromJavaOne)},
                 {"callNativeTwo", "(I)V", reinterpret_cast<void *>(fromJavaTwo)}};
    QJniEnvironment env;
    env.registerNativeMethods("my/java/project/FooJavaClass", methods, 2);

    // Call the java method which will calls back to the C++ functions
    QJniObject::callStaticMethod<void>("my/java/project/FooJavaClass", "foo", "(I)V", 10);  // Output: 10 < 100
    QJniObject::callStaticMethod<void>("my/java/project/FooJavaClass", "foo", "(I)V", 100); // Output: 100 >= 100
}

Most objects received from Java will be local references and will only stay valid until you return from the native method. After that, the object becomes eligible for garbage collection. If your code creates many local references in a loop you should delete them manually with each iteration, otherwise you might run out of memory. For more information, see JNI Design Overview: Global and Local References. Local references created outside a native method scope must be deleted manually, since the garbage collector will not free them automatically because we are using AttachCurrentThread. For more information, see JNI tips: Local and global references.

If you want to keep a Java object alive you need to either create a new global reference to the object and release it when you are done, or construct a new QJniObject and let it manage the lifetime of the Java object.

Object Types▲

Primitive Types▲

Other▲

See also QJniEnvironment, object()

Constructs a new JNI object by calling the default constructor of clazz.

Constructs a new JNI object from clazz by calling the constructor with signature specifying the types of any subsequent arguments.

QJniEnvironment env;
jclass myClazz = env.findClass("org/qtproject/qt/TestClass");
QJniObject(myClazz, "(I)V", 3);

Constructs a new JNI object around the Java object object.

See Also▲