Calling a Java Method from Native Code

http://journals.ecs.soton.ac.uk/java/tutorial/native1.1/implementing/method.html

Calling Java Methods

The following table summarizes the encoding for the Java type signatures:

Java VM Type Signatures

Signature	Java Type
Z	boolean
B	byte
C	char
S	short
I	int
J	long
F	float
D	double
L fully-qualified-class ;	fully-qualified-class
[ type	type[]
( arg-types ) ret-type	method type

For example, the

Prompt.getLine

method has the signature:


whereas the

Callbacks.main

method has the signature:

Array types are indicated by a leading square bracket ([) followed by the type of the array elements.

Using

javap

to Generate Method Signatures

To eliminate the mistakes in deriving method signatures by hand, you can use the

javap

tool to print out method signatures. For example, by running:


you can obtain the following output:

The "-s" flag informs

javap

to output signatures rather than normal Java types. The "-p" flag causes private members to be included.

Calling Java Methods Using Method IDs

In JNI, you pass the method ID to the actual method invocation function. This makes it possible to first obtain the method ID, which is a relatively expensive operation, and then use the method ID many times at later points to invoke the same method.

It is important to keep in mind that a method ID is valid only as long as the class from which it is derived is not unloaded. Once the class is unloaded, the method ID becomes invalid. So if you want to cache the method ID, make sure to keep a live reference to the Java class from which the method ID is derived. As long as the reference to the Java class (the

jclass

value) exists, the native code keeps a live reference to the class. The section Local and Global References explains how to keep a live reference even after the native method returns and the

jclass

value goes out of scope.

Passing Arguments to Java Methods

The JNI provides several ways to pass arguments to a Java method. Most often, you pass the arguments following the method ID. There are also two variations of method invocation functions that take arguments in an alternative format. For example, the

CallVoidMethodV

function receives the arguments in a

va_list

, and the

CallVoidMethodA

function expects the arguments in an array of

jvalue

union types:


Besides

CallVoidMethod

function, the JNI also supports instance method invocation functions with other return types, such as

CallBooleanMethod

,

CallIntMethod

, and so on. The return type of the method invocation function must match with the Java method you wish to invoke.

Calling Static Methods

You can call static Java method from your native code by following these steps:

Obtain the method ID using

GetStaticMethodID

, as opposed to

GetMethodID

.

Pass the class, method ID, and arguments to the family of static method invocation functions:

CallStaticVoidMethod

,

CallStaticBooleanMethod

, and so on.

If you compare instance method invocation functions to static method invocation functions, you will notice that instance method invocation functions receive the object, rather than the class, as the second argument following the JNIEnv argument. For example, if we add a static method

into

Callback.java

, we can call it from

Java_Callback_nativeMethod

using:

JNIEXPORT void JNICALL
Java_Callbacks_nativeMethod(JNIEnv *env, jobject obj, jint depth)
{
jclass cls = (*env)->GetObjectClass(env, obj);
jmethodID mid = (*env)->GetStaticMethodID(env, cls, "incDepth", "(I)I");
if (mid == 0)
return;
depth = (*env)->CallStaticIntMethod(env, cls, mid, depth);

Calling Instance Methods of a Superclass

You can call instance methods defined in a superclass that have been overridden in the class to which the object belongs. The JNI provides a set of

CallNonvirtual<type>Method

functions for this purpose. To call instance methods from the superclass that defined them, you do the following:

Obtain the method ID from the superclass using

GetMethodID

, as opposed to

GetStaticMethodID)

.

Pass the object, superclass, method Id, and arguments to the family of nonvirtual invocation functions:

CallNonvirtualVoidMethod

,

CallNonvirtualBooleanMethod

, and so on.

It is rare that you will need to invoke the instance methods of a superclass. This facility is similar to calling a superclass method, say

f

, using:

in Java.