The Java Native InterfaceProgrammer’s Guide and Specification phần 7 pps

JNI FUNCTIONS CallMethodLinkage Indices in theJNIEnv interface function table.. JNI FUNCTIONS CallMethodALinkage Indices in theJNIEnv interface function table.. JNI FUNCTIONS CallMethodV

JNI FUNCTIONS The JNIEnv Interface

Reflection Support

the Java Core Reflection API into field IDs.FromReflectedFieldis new inJava 2 SDK release 1.2

instances of java.lang.reflect.Constructor into method IDs

opposite direction Both functions are new in Java 2 SDK release 1.2

The flexibility of an interface pointer makes it easy to evolve (§11.5.2) the

JNIEnvinterface A future version of the JNI specification could introduce a new

interface, say aJNIEnv2interface, that is different from the current version of the

compat-ibility by simultaneously supporting both JNIEnv and JNIEnv2 interfaces The

return value of the JNI_OnLoad handler of a native library informs the virtual

machine implementation about the version of the JNI interface expected by the

native library For example, a native library can presently implement a native

methodFoo.f using a native functionJava_Foo_f as follows:

JNIEXPORT void JNICALL Java_Foo_f(JNIEnv *env, jobject this, jint arg) {

(*env)-> /* some call to the JNIEnv interface */

}

In the future, the same native method may also be implemented as follows:

Specification of JNI Functions JNI FUNCTIONS

JNIEXPORT void JNICALL Java_Foo_f(jobject this, jint arg) {

(*g_env)-> /* some call to the JNIEnv2 interface */ }

To highlight interface evolution, we have made the hypothetical future

variable The JNIEnv2interface need not be passed as the first argument to the

method implementation functions such asJava_Foo_fneed not be changed tual machine implementations rely on the return value of theJNI_OnLoadhandler

Vir-to determine the argument passing convention of native method implementationfunctions in a given native library

13.2 Specification of JNI Functions

This section contains the complete specification of the JNI functions For eachfunction, we provide information on the following:

• function prototypes

• a detailed description, including the parameters, return values, and possible

exceptions

• linkage information, including 0-based index for all entries in theJNIEnvand

JavaVM interface function tables

JNI FUNCTIONS AllocObject

AllocObject

Prototype jobject AllocObject(JNIEnv *env, jclass clazz);

Description Allocates a new object without invoking any of the constructors

for the object Returns a local reference to the object

New<Type>Array family of functions to allocate array objects.

object and execute one of its contructors

Linkage Index 27 in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

clazz: a reference to the class of the object to be allocated

Return Values Returns a local reference to the newly allocated object, orNULL

if the object cannot be allocated ReturnsNULLif and only if aninvocation of this function has thrown an exception

Exceptions InstantiationException: if the class is an interface or an

abstract class

AttachCurrentThread JNI FUNCTIONS

AttachCurrentThread

Prototype jint AttachCurrentThread(JavaVM *vm, void **penv,

void *args);

Description Attaches the current thread to a given virtual machine instance

Once attached to the virtual machine instance, a native threadhas an associated java.lang.Thread instance An attachednative thread may issue JNI function calls The native threadremains attached to the virtual machine instance until it calls

DetachCurrentThread to detach itself

Trying to attach a thread that is already attached simply sets thevalue pointed to bypenv to theJNIEnv of the current thread

A native thread cannot be attached simultaneously to two Javavirtual machine instances

In JDK release 1.1, the second argument receives a JNIEnv

interface pointer The third argument is reserved, and should beset to NULL The default java.lang.Thread constructor auto-matically generates a thread name (for example, "Thread-123")for the associated java.lang.Thread instance The

group "main" created by the virtual machine implementation

In Java 2 SDK release 1.2, the third argument may be set to

NULL to preserve the release 1.1 behavior Alternatively, thethird argument may point to the following structure:

typedef struct { jint version;

char *name;

JNI FUNCTIONS AttachCurrentThread

tor generates a thread name (for example, "Thread-123") forthe associated java.lang.Thread instance

If thegroupfield is notNULL, it specifies a global reference of athread group to which the newly created java.lang.Thread

instance is added If the group field is NULL, the

group "main" created by the virtual machine implementation

Linkage Index 4 in the JavaVM interface function table

Parameters vm: the virtual machine instance to which the current thread will

Call<Type>Method JNI FUNCTIONS

Call<Type>Method

Prototype <NativeType> Call<Type>Method(JNIEnv *env,

jobject obj, jmethodID methodID, );

Forms This family of functions consists of ten members

Description Invokes an instance method, specified using a method ID, on an

JNI FUNCTIONS Call<Type>Method

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

obj: a reference to the object on which the method is invoked

Additional arguments: arguments to be passed to the method

Return Values The result of calling the method

Exceptions Any exception raised during the execution of the method

Call<Type>MethodA JNI FUNCTIONS

Call<Type>MethodA

Prototype <NativeType> Call<Type>MethodA(JNIEnv *env,

jobject obj, jmethodID methodID, jvalue *args);

Forms This family of functions consists of ten members

Description Invokes an instance method, specified using a method ID, on an

object

Programmers place all arguments to the method in an array of

Call<Type>MethodA routine accepts the arguments in thisarray, and, in turn, passes them to the method that the program-mer wishes to invoke

JNI FUNCTIONS Call<Type>MethodA

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

obj: a reference to the object on which the method is invoked

args: an array of arguments to be passed to the method

Return Values Returns the result of calling the method

Exceptions Any exception raised during the execution of the method

Call<Type>MethodV JNI FUNCTIONS

Call<Type>MethodV

Prototype <NativeType> Call<Type>MethodV(JNIEnv *env,

jobject obj, jmethodID methodID, va_list args);

Forms This family of functions consists of ten members

Description Invokes an instance method, specified using a method ID, on an

object

Programmers place all arguments to the method in an args

argument of typeva_listthat immediately follows the odID argument The Call<Type>MethodV routine accepts thearguments, and, in turn, passes them to the method that the pro-grammer wishes to invoke

JNI FUNCTIONS Call<Type>MethodV

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

obj: a reference to an object on which the method is invoked

args: ava_list of arguments passed to the invoked method

Return Values Returns the result of calling the method

Exceptions Any exception raised during the execution of the method

CallNonvirtual<Type>Method JNI FUNCTIONS

CallNonvirtual<Type>Method

Prototype <NativeType> CallNonvirtual<Type>Method(

JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, );

Forms This family of functions consists of ten members

Descriptions Invokes an instance method, specified using a class and a

method ID, on an object

The CallNonvirtual<Type>Method family of functions andthe Call<Type>Method family of functions are different

Call<Type>Method functions invoke the method based on thereal class of the object, while CallNonvirtual<Type>Method

routines invoke the method based on the class, designated by

JNI FUNCTIONS CallNonvirtual<Type>Method

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

derived

obj: a reference to the object on which the method is invoked

clazz.Additional arguments: arguments to be passed to the method

Return Values Returns the result of calling the method

CallNonvirtual<Type>MethodA JNI FUNCTIONS

CallNonvirtual<Type>MethodA

Prototype <NativeType> CallNonvirtual<Type>MethodA(

JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, jvalue *args);

Forms This family of functions consists of ten members

Description Invokes an instance method, specified using a class and a

method ID, on an object

TheCallNonvirtual<Type>MethodA families of functions andthe Call<Type>MethodA families of functions are different

Call<Type>MethodAfunctions invoke the method based on thereal class of the object, whileCallNonvirtual<Type>MethodA

routines invoke the method based on the class, designated by

JNI FUNCTIONS CallNonvirtual<Type>MethodA

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

derived

obj: a reference to the object on which the method is invoked

clazz

args: an array of arguments to be passed to the method

Return Values Returns the result of calling the method

CallNonvirtual<Type>MethodV JNI FUNCTIONS

CallNonvirtual<Type>MethodV

Prototype <NativeType> CallNonvirtual<Type>MethodV(

JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, va_list args);

Forms This family of functions consists of ten members

Description Invokes an instance method, specified using a class and a

method ID, on an object The methodID argument must beobtained by callingGetMethodID on the classclazz

TheCallNonvirtual<Type>MethodV families of functions andthe Call<Type>MethodV families of functions are different

Call<Type>MethodVfunctions invoke the method based on thereal class of the object, whileCallNonvirtual<Type>MethodV

JNI FUNCTIONS CallNonvirtual<Type>MethodV

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

derived

obj: a reference to the object on which the method is invoked

clazz

args: ava_list of arguments to be passed to the method

Return Values Returns the result of calling the method

CallStatic<Type>Method JNI FUNCTIONS

CallStatic<Type>Method

Prototype <NativeType> CallStatic<Type>Method(

JNIEnv *env, jclass clazz, jmethodID methodID, );

Forms This family of functions consists of ten members

Description Invokes a static method, specified using a method ID, on a

class The method must be accessible inclazz, although it may

be defined in one of the superclasses ofclazz.Programmers should place all arguments that are to be passed tothe method immediately following themethodIDargument The

CallStatic<Type>Methodroutine accepts these arguments andpasses them to the static method that the programmer wishes to

JNI FUNCTIONS CallStatic<Type>Method

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

method is called

methodID: the static method ID of the method to be called

Additional arguments: arguments to be passed to the staticmethod

Return Values Returns the result of calling the static method

CallStatic<Type>MethodA JNI FUNCTIONS

CallStatic<Type>MethodA

Prototype <NativeType> CallStatic<Type>MethodA(

JNIEnv *env, jclass clazz, jmethodID methodID, jvalue *args);

Forms This family of functions consists of ten members

Description Invokes a static method, specified using a method ID, on a

class The method must be accessible inclazz, although it may

be defined in one of the superclasses ofclazz.Programmers should place all arguments to the method in an

argsarray ofjvaluesthat immediately follows themethodID

argument TheCallStatic<Type>MethodAroutine accepts thearguments in this array, and, in turn, passes them to the static

JNI FUNCTIONS CallStatic<Type>MethodA

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

method is called

methodID: the static method ID of the method to be called

args: an array of arguments to be passed to the static method

Return Values Returns the result of calling the static method

Exceptions Any exception raised during the execution of the method

CallStatic<Type>MethodV JNI FUNCTIONS

CallStatic<Type>MethodV

Prototype <NativeType> CallStatic<Type>MethodV(

JNIEnv *env, jclass clazz, jmethodID methodID, va_list args);

Forms This family of functions consists of ten members

Description Invokes a static method, specified using a method ID, on a

class The method must be accessible inclazz, although it may

be defined in one of the superclasses ofclazz.Programmers should place all arguments to the method in an

args argument of type va_list that immediately follows the

accepts the arguments, and, in turn, passes them to the static

JNI FUNCTIONS CallStatic<Type>MethodV

Linkage Indices in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

method is called

methodID: the static method ID of the method to be called

args: ava_listof arguments to be passed to the static method

Return Values Returns the result of calling the static method

Exceptions Any exception raised during the execution of the method

DefineClass JNI FUNCTIONS

DefineClass

Prototype jclass DefineClass(JNIEnv *env, const char *name,

jobject loader, const jbyte *buf, jsize bufLen);

Description Creates ajava.lang.Classinstance from a buffer of raw class

data representing a class or interface The format of the raw

class data is specified by The Java™ Virtual Machine

Specifica-tion.

This function is slightly more general than the

can define classes or interfaces with thenullclass loader The

method and thus requires ajava.lang.ClassLoader instance

Linkage Index 5 in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

name: the name of the class or interface to be defined

loader: a class loader assigned to the defined class or interface

buf: buffer containing the raw class file data

bufLen: buffer length

Return Values Returns a local reference to the newly defined class or interface

object, orNULLif an exception occurs ReturnsNULLif and only

if an invocation of this function has thrown an exception

JNI FUNCTIONS DeleteGlobalRef

DeleteGlobalRef

Prototype void DeleteGlobalRef(JNIEnv *env, jobject gref);

Description Deletes the global reference pointed to bygref Thegref

argu-ment must be a global reference, orNULL The same non-NULL

global reference must not be deleted more than once Deleting a

NULL global reference is a no-op

Linkage Index 22 in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

gref: the global reference to be deleted

Exceptions None

DeleteLocalRef JNI FUNCTIONS

DeleteLocalRef Prototype void DeleteLocalRef(JNIEnv *env, jobject lref);

Description Deletes the local reference pointed to bylref Thelref

argu-ment must be a local reference, or NULL The same non-NULL

local reference must not be deleted more than once Deleting a

NULL local reference is a no-op

Deleting a local reference that does not belong to the topmostlocal reference frame is a no-op Each native method invocationcreates a new local reference frame The PushLocalFrame

function (added in Java 2 SDK release 1.2) also creates a newlocal reference frame

Linkage Index 23 in theJNIEnv interface function table

Parameters env: theJNIEnv interface pointer

lref: the local reference to be deleted

Exceptions None