| Contents | Prev | Next | Index | The Java Native Interface Programmer's Guide and Specification |
This
chapter specifies the JNI functions. We will use the term "must" to describe
the restrictions placed on JNI programmers. For example, when a certain JNI
function must receive a non-NULL object, it is the programmer's
responsibility not to pass NULL to that function. As a result,
a JNI implementation does not need to check for possibly receiving NULL
pointers in that function. If the programmer passes NULL to that
function, the resulting behavior is undefined.
We will begin with a summary of JNI functions. The main body of the chapter contains the detailed specifications of all JNI functions.
The JNI functions fall into one of four categories depending on where they are defined and what they are used for. First of all, a virtual machine implementation exports a set of native functions. These functions are part of the invocation interface. They can be used to accomplish tasks such as creating a virtual machine instance in a native application. Second, the JavaVM interface represents a virtual machine instance. The JavaVM interface provides functions that allow, for example, native threads to attach to a virtual machine instance. Third, a native library that implements native methods may export special handler functions that are called when a virtual machine implementation loads and unloads the native library. Finally, the JNIEnv interface supports JNI features such as creating objects, accessing fields, and calling methods.
A virtual machine implementation directly exports the following three functions as part of the invocation interface:
JNI_GetDefaultJavaVMInitArgs JNI_CreateJavaVM JNI_GetCreatedJavaVMs
The JNI_GetDefaultJavaVMInitArgs function provides the values of default initialization arguments used to create a virtual machine instance. The information is specific to the virtual machine implementation in JDK release 1.1. This function is no longer useful in Java 2 SDK release 1.2 but is still supported for backward compatibility.
The JNI_CreateJavaVM function creates a virtual machine instance according to a given set of initialization arguments. You specify initialization arguments in JDK release 1.1 by setting the fields of a C structure. Java 2 SDK release 1.2 supports a more flexible way to specify the initialization arguments but still supports the same JDK 1.1 style initialization structure for backward compatibility.
The JNI_GetCreatedJavaVMs function returns all virtual machine instances that have been created in the current process. A particular JNI implementation need not be able to create more than one virtual machine instance in the same process. Neither JDK release 1.1 nor Java 2 SDK release 1.2 supports the creation of more than one virtual machine instance in the same process.
A native application that embeds a virtual machine instance can invoke any of these functions. The native application may either link against the virtual machine library that exports these functions, or use native dynamic linking mechanisms to load the virtual machine library and locate any of the exported functions at run time.
The JavaVM interface is a pointer to a pointer to a function table. The first three entries in the function table are reserved for future compatibility with the Microsoft COM interface and are set to NULL. The remaining four entries are part of the invocation interface:
DestroyJavaVM AttachCurrentThread DetachCurrentThread GetEnv
Unlike the JNIEnv interface pointer, which is specific to a single thread, a JavaVM interface pointer represents an entire virtual machine instance and is valid for all threads in the virtual machine instance.
The DestroyJavaVM function unloads the virtual machine instance denoted by the JavaVM interface pointer. The AttachCurrentThread function sets up the current native thread to run as part of a virtual machine instance. Once a thread is attached to the virtual machine instance, it can then make JNI function calls to perform such tasks as accessing objects and invoking methods. The Detach-CurrentThread function informs a virtual machine instance that the current thread no longer needs to issue JNI function calls, allowing the virtual machine implementation to perform cleanups and free resources.
The GetEnv function is new in Java 2 SDK release 1.2. It can serve two purposes. First, it can be used to check whether the current thread is attached to a virtual machine instance. Second, it can be used to obtain other interfaces, such as the JNIEnv interface, from the JavaVM interface pointer.
Java 2 SDK release 1.2 allows the programmer to export additional handler functions to be invoked when a virtual machine implementation loads and unloads a native library. When the virtual machine implementation loads a native library, it searches for and invokes the exported function entry JNI_OnLoad. When the virtual machine implementation unloads a native library, it searches for and invokes the exported function entry JNI_OnUnload.
The JNIEnv interface supports the core features of the JNI. Virtual machine implementations pass a JNIEnv interface pointer as the first argument to each native method. Native code may also obtain a JNIEnv interface pointer by calling the GetEnv function on a JavaVM interface pointer. Although a JNIEnv interface pointer is valid only in a particular thread, the JavaVM interface pointer is valid for all threads in a virtual machine instance.
A JNIEnv interface pointer is a pointer to a pointer to a function table. The first three entries in the function table are reserved for future compatibility with Microsoft COM interface and are set to NULL. The fourth entry in the function table is reserved for future use and is also set to NULL.
The remainder of this chapter will cover all the entries in the JNIEnv interface in detail. For now we give a high-level overview.
GetVersion returns the version of the JNIEnv interface.
DefineClass defines a class or interface type from a native byte array representing the raw class file data.
FindClass returns a reference to a class or interface type of a given name.
GetSuperclass returns the superclass of a given class or interface.
IsAssignableFrom checks if an instance of one class or interface can be assigned to an instance of another class or interface, and is useful for runtime type checking.
Throw and ThrowNew raise an exception in the current thread.
ExceptionOccurred and ExceptionCheck check for pending exceptions in the current thread. ExceptionCheck is new in Java 2 SDK release 1.2.
ExceptionDescribe prints a diagnostic message about the pending exception.
ExceptionClear clears the pending exception.
FatalError prints a message and terminates the current virtual machine instance.
NewGlobalRef creates a global reference, DeleteGlobalRef deletes one.
NewWeakGlobalRef and DeleteWeak-Global-Ref manage weak global references. Both are new in Java 2 SDK release 1.2.
DeleteLocalRef reclaims the virtual machine resource needed for a local reference.
NewLocalRef is new in Java 2 SDK release 1.2.
EnsureLocalCapacity reserves space in the current thread for a fixed number of local references to be created. EnsureLocalCapacity is new in Java 2 SDK release 1.2.
PushLocalFrame and PopLocalFrame create a nested scope for local references. Both functions are new in Java 2 SDK release 1.2.
AllocObject allocates an uninitialized object.
NewObject allocates an object and runs one of its constructors.
GetObjectClass returns the class of a given instance.
IsInstanceOf checks if a given object is an instance of a given class or interface.
IsSameObject checks if two references refer to the same object.
GetFieldID performs a symbolic lookup on a given class and returns the field ID of a named instance field.
Get<Type>Field and Set<Type>Field families access instance fields.
GetStaticFieldID performs a symbolic lookup on a given class or interface and returns the field ID of a named static field.
GetStatic<Type>Field and SetStatic<Type>Field families access static fields.
GetMethodID performs a symbolic lookup on a given class or interface and returns the method ID of an instance method or a constructor.
Call<Type>Method family invoke instance methods.
CallNonvirtual<Type>Method family invoke either instance methods of a superclass or constructors.
GetStaticMethodID performs a symbolic lookup on a given class and returns the method ID of a static method.
CallStatic<Type>Method family invoke static methods.
NewString creates a java.lang.String object representing a native Unicode string.
NewStringUTF creates a java.lang.String object representing a native UTF-8 string.
GetStringLength returns the number of Unicode characters in a string represented by a java.lang.String object.
GetStringLengthUTF returns the number of UTF-8 bytes needed to encode all characters in a string represented by a given java.lang.String object.
GetStringChars and ReleaseStringChars access the content of a java.lang.String object as a pointer to a Unicode string.
GetStringUTFChars and ReleaseStringUTFChars access the content of a java.lang.String objectas a pointer to a UTF-8 string.
GetStringCritical and ReleaseStringCritical access the content of a java.lang.String object with minimum overhead. Both functions are new in Java 2 SDK release 1.2.
GetStringRegion and GetStringUTFRegion copy the contents of a java.lang.String object into a native buffer. Both functions are new in Java 2 SDK release 1.2.
GetArrayLength returns the number of elements in an array.
NewObjectArray creates an array of objects, whereas functions of the New<Type>Array family create arrays of primitive types.
GetObjectArrayElement and SetObjectArrayElement allow native code to access arrays of reference types.
Get<Type>ArrayElements and Release<Type>Array-Elements families access all the elements in arrays of primitive types.
Get<Type>ArrayRegion and Set<Type>ArrayRegion families copy multiple elements in or out of arrays of primitive types.
GetPrimitiveArrayCritical and ReleasePrimitiveArrayCritical ac-cess elements in an array of primitive types with minimum overhead. Both functions are new in Java 2 SDK release 1.2.
RegisterNatives and UnregisterNatives allow native code to eagerly link and unlink native methods.
MonitorEnter and MonitorExit synchronize on the monitor associated with objects.
GetJavaVM returns the JavaVM interface pointer for the current virtual machine instance.
FromReflectedField converts instances of java.lang.reflect.Field in the Java Core Reflection API into field IDs. FromReflectedField is new in Java 2 SDK release 1.2.
FromReflectedMethod converts instances of java.lang.reflect.Method or instances of java.lang.reflect.Constructor into method IDs. From-ReflectedMethod is new in Java 2 SDK release 1.2.
ToReflectedField and ToReflectedMethod carry out the conversions in the 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 JNIEnv interface. A future version of the JNI specification could introduce a new interface, say a JNIEnv2 interface, that is different from the current version of the JNIEnv. A future virtual machine implementation can maintain backward compatibility 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 method Foo.f using a native function Java_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:
/* possible implementation of Foo.f using a hypothetical
* future version (JNI_VERSION_2_0) of the JNI interface */
JNIEnv2 *g_env;
JNIEXPORT jint JNICALL
JNIOnLoad(JavaVM *vm, void *reserved)
{
jint res;
/* cache JNIEnv2 interface pointer in global variable */
res = (*vm)->GetEnv(vm, (void **)&g_env, JNI_VERSION_2_0);
if (res < 0) {
return res;
}
return JNI_VERSION_2_0; /* the required JNI version */
}
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 JNIEnv2 interface different from the JNIEnv interface in a number of ways. The JNIEnv2 interface need not be thread-local, and thus can be cached in a global variable. The JNIEnv2 interface need not be passed as the first argument to the Java_Foo_f native function. The name encoding convention (§11.3) of native method implementation functions such as Java_Foo_f need not be changed. Virtual machine implementations rely on the return value of the JNI_OnLoad handler to determine the argument passing convention of native method implementation functions in a given native library.
This section contains the complete specification of the JNI functions. For each function, we provide information on the following:
JNIEnv and JavaVM interface function tables
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.
The clazz argument must not refer to an array class. Use the New<Type>Array family of functions to allocate array objects.
Use NewObject, NewObjectV, or NewObjectA to allocate an object and execute one of its contructors.
Linkage Index 27 in the JNIEnv interface function table.
Parameters env: the JNIEnv 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, or NULL if the object cannot be allocated. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions InstantiationException: if the class is an interface or an abstract class.
OutOfMemoryError: if the system runs out of memory.
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 thread has an associated java.lang.Thread instance. An attached native thread may issue JNI function calls. The native thread remains attached to the virtual machine instance until it calls DetachCurrentThread to detach itself.
Trying to attach a thread that is already attached simply sets the value pointed to by penv to the JNIEnv of the current thread.
A native thread cannot be attached simultaneously to two Java virtual machine instances.
In JDK release 1.1, the second argument receives a JNIEnv interface pointer. The third argument is reserved, and should be set to NULL. The default java.lang.Thread constructor automatically generates a thread name (for example, "Thread-123") for the associated java.lang.Thread instance. The java.lang.Thread instance belongs to the default thread 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, the third argument may point to the following structure:
typedef struct {
jint version;
char *name;
jobject group;
} JavaVMAttachArgs;
The version field specifies the version of the JNIEnv interface passed back through the second argument. The valid versions accepted by Java 2 SDK release 1.2 are JNI_VERSION_1_1 and JNI_VERSION_1_2.
If the name field is not NULL, it points to a UTF-8 string specifying the name of the associated java.lang.Thread instance. If the name field is NULL, the default java.lang.Thread constructor generates a thread name (for example, "Thread-123") for the associated java.lang.Thread instance.
If the group field is not NULL, it specifies a global reference of a thread group to which the newly created java.lang.Thread instance is added. If the group field is NULL, the java.lang.Thread instance is added to the default thread 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 be attached.
penv: a pointer to the location in which the JNIEnv interface pointer for the current thread will be placed.
args: reserved (in JDK release 1.1) or a pointer to a JavaVM-AttachArgs structure (in Java 2 SDK release 1.2).
Return Values Returns zero on success; otherwise, returns a negative number.
Exceptions None.
Prototype <NativeType> Call<Type>Method(JNIEnv *env,
jobject obj, jmethodID methodID, ...);
Description Invokes an instance method, specified using a method ID, on an object.
Programmers place all arguments that are to be passed to the method immediately following the methodID argument. The Call<Type>Method function accepts these arguments and passes them to the method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
CallVoidMethod |
61 |
CallObjectMethod |
34 |
CallBooleanMethod |
37 |
CallByteMethod |
40 |
CallCharMethod |
43 |
CallShortMethod |
46 |
CallIntMethod |
49 |
CallLongMethod |
52 |
CallFloatMethod |
55 |
CallDoubleMethod |
58 |
Parameters env: the JNIEnv interface pointer.
obj: a reference to the object on which the method is invoked.
methodID: method ID denoting the method to be 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.
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 jvalues that immediately follows the methodID argument. The Call<Type>MethodA routine accepts the arguments in this array, and, in turn, passes them to the method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
CallVoidMethodA |
63 |
CallObjectMethodA |
36 |
CallBooleanMethodA |
39 |
CallByteMethodA |
42 |
CallCharMethodA |
45 |
CallShortMethodA |
48 |
CallIntMethodA |
51 |
CallLongMethodA |
54 |
CallFloatMethodA |
57 |
CallDoubleMethodA |
60 |
Parameters env: the JNIEnv interface pointer.
obj: a reference to the object on which the method is invoked.
methodID: method ID denoting the method to be 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.
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 type va_list that immediately follows the methodID argument. The Call<Type>MethodV routine accepts the arguments, and, in turn, passes them to the method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
CallVoidMethodV |
62 |
CallObjectMethodV |
35 |
CallBooleanMethodV |
38 |
CallByteMethodV |
41 |
CallCharMethodV |
44 |
CallShortMethodV |
47 |
CallIntMethodV |
50 |
CallLongMethodV |
53 |
CallFloatMethodV |
56 |
CallDoubleMethodV |
59 |
Parameters env: the JNIEnv interface pointer.
obj: a reference to an object on which the method is invoked.
methodID: method ID of the method to be invoked.
args: a va_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.
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 and the Call<Type>Method family of functions are different. Call<Type>Method functions invoke the method based on the real class of the object, while CallNonvirtual<Type>Method routines invoke the method based on the class, designated by the clazz parameter, from which the method ID is obtained. The clazz parameter must refer to the real class of the object or from one of its superclasses.
Programmers place all arguments that are to be passed to the method immediately following the methodID argument. The CallNonvirtual<Type>Method routine accepts these arguments and passes them to the method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class from which the method ID is derived.
obj: a reference to the object on which the method is invoked.
methodID: a method ID that is valid with the class reference clazz.
Additional arguments: 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.
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.
The CallNonvirtual<Type>MethodA families of functions and the Call<Type>MethodA families of functions are different. Call<Type>MethodA functions invoke the method based on the real class of the object, while CallNonvirtual<Type>MethodA routines invoke the method based on the class, designated by the clazz parameter, from which the method ID is obtained. The clazz parameter must refer to the real class of the object or from one of its superclasses.
Programmers place all arguments to the method in an args array of jvalues that immediately follows the methodID argument. The CallNonvirtual<Type>MethodA routine accepts the arguments in this array, and, in turn, passes them to the method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class from which the method ID is derived.
obj: a reference to the object on which the method is invoked.
methodID: a method ID that is valid with the class reference clazz.
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.
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 be obtained by calling GetMethodID on the class clazz.
The CallNonvirtual<Type>MethodV families of functions and the Call<Type>MethodV families of functions are different. Call<Type>MethodV functions invoke the method based on the real class of the object, while CallNonvirtual<Type>MethodV routines invoke the method based on the class, designated by the clazz parameter, from which the method ID is obtained. The clazz parameter must refer to the real class of the object or from one of its superclasses.
Programmers place all arguments to the method in an args argument of type va_list that immediately follows the methodID argument. The CallNonvirtual<Type>MethodV routine accepts the arguments, and, in turn, passes them to the method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class from which the method ID is derived.
obj: a reference to the object on which the method is invoked.
methodID: a method ID that is valid with the class reference clazz.
args: a va_list 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.
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 in clazz, although it may be defined in one of the superclasses of clazz.
Programmers should place all arguments that are to be passed to the method immediately following the methodID argument. The CallStatic<Type>Method routine accepts these arguments and passes them to the static method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class object on which the static method is called.
methodID: the static method ID of the method to be called.
Additional arguments: 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.
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 in clazz, although it may be defined in one of the superclasses of clazz.
Programmers should place all arguments to the method in an args array of jvalues that immediately follows the methodID argument. The CallStatic<Type>MethodA routine accepts the arguments in this array, and, in turn, passes them to the static method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class object on which the static 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.
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 in clazz, although it may be defined in one of the superclasses of clazz.
Programmers should place all arguments to the method in an args argument of type va_list that immediately follows the methodID argument. The CallStatic<Type>MethodV routine accepts the arguments, and, in turn, passes them to the static method that the programmer wishes to invoke.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class object on which the static method is called.
methodID: the static method ID of the method to be called.
args: a va_list 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.
Prototype jclass DefineClass(JNIEnv *env, const char *name,
jobject loader, const jbyte *buf,
jsize bufLen);
Description Creates a java.lang.Class instance from a buffer of raw class data representing a class or interface. The format of the raw class data is specified by The JavaTM Virtual Machine Specification.
This function is slightly more general than the java.lang.ClassLoader.defineClass method. This function can define classes or interfaces with the null class loader. The java.lang.ClassLoader.define-Class method is an instance method and thus requires a java.lang.ClassLoader instance.
Linkage Index 5 in the JNIEnv interface function table.
Parameters env: the JNIEnv 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, or NULL if an exception occurs. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions ClassFormatError: if the class data does not specify a valid class or interface.
NoClassDefFoundError: if the class data does not specify the named class or interface to be defined.
ClassCircularityError: if a class or interface would be its own superclass or superinterface.
OutOfMemoryError: if the system runs out of memory.
Prototype void DeleteGlobalRef(JNIEnv *env, jobject gref);
Description Deletes the global reference pointed to by gref. The gref argument must be a global reference, or NULL. 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 the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
gref: the global reference to be deleted.
Exceptions None.
Prototype void DeleteLocalRef(JNIEnv *env, jobject lref);
Description Deletes the local reference pointed to by lref. The lref argument 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 topmost local reference frame is a no-op. Each native method invocation creates a new local reference frame. The PushLocalFrame function (added in Java 2 SDK release 1.2) also creates a new local reference frame.
Linkage Index 23 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
lref: the local reference to be deleted.
Exceptions None.
Prototype void DeleteWeakGlobalRef(JNIEnv *env,
jobject wref);
Description Deletes a weak global reference. The wref argument must be a weak global reference. The same weak global reference must not be deleted more than once.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 227 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
wref: the weak global reference to be deleted.
Exceptions None.
Prototype jint DestroyJavaVM(JavaVM *vm);
Description Unloads a virtual machine instance and reclaims its resources. The system blocks until the current thread is the only remaining user thread before it attempts to unload the virtual machine instance. This restriction exists because an attached thread may be holding system resources such as locks, windows, and so on. Virtual machine implementations cannot automatically free these resources. By restricting the main thread to be the only running thread when the virtual machine instance is unloaded, the burden of releasing system resources held by arbitrary threads is on the programmer.
The support for DestroyJavaVM was not complete in JDK release 1.1; only the main thread may call DestroyJavaVM. The virtual machine implementation blocks until the main thread is the only user-level thread and returns a negative error code.
Java 2 SDK release 1.2 still does not support unloading virtual machine instances. There is a slight relaxation to the use of DestroyJavaVM, however; any thread may call DestroyJavaVM. The virtual machine implementation blocks until the current thread is the only user thread before it returns an error code.
Linkage Index 3 in the JavaVM interface function table.
Parameters vm: the virtual machine instance that will be destroyed.
Return Values Returns zero on success; otherwise, returns a negative number.
Exceptions None.
Prototype jint DetachCurrentThread(JavaVM *vm);
Description Detaches the current thread from a virtual machine instance. All monitors held by this thread are released. All threads waiting for this thread to die (i.e., performing a Thread.join on this thread) are notified.
In JDK release 1.1, the main thread cannot be detached from a virtual machine instance. Instead, it must call DestroyJavaVM to unload the entire virtual machine instance.
In Java 2 SDK release 1.2, the main thread may be detached from a virtual machine instance.
Linkage Index 5 in the JavaVM interface function table.
Parameters vm: the virtual machine instance from which the current thread will be detached.
Return Values Returns zero on success; otherwise, returns a negative number.
Exceptions None.
Prototype jint EnsureLocalCapacity(JNIEnv *env,
jint capacity);
Description Ensures that at least a given number of local references can be created in the current thread.
Before it enters a native method, the virtual machine implementation ensures that at least sixteen local references can be created in the current thread.
Allocating more local references than the ensured capacity may or may not lead to an immediate failure depending on whether the virtual machine implementation has enough memory available. The virtual machine implementation calls FatalError if it is unable to provide the memory for additional local references beyond the ensured capacity.
For debugging support, a virtual machine implementation may give the user warnings when the user creates more local references than the ensured capacity. In Java 2 SDK release 1.2, the programmer can supply the -verbose:jni command line option to turn on these warning messages.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 26 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
capacity: the number of local references that will be created.
Return Values Returns zero on success; otherwise, returns a negative number and throws an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jboolean ExceptionCheck(JNIEnv *env);
Description Determines if an exception has been thrown. The exception stays thrown until either the native code calls ExceptionClear, or the caller of the native method handles the exception.
The difference between this function and ExceptionOccurred is that this function returns a jboolean to indicate whether there is a pending exception, whereas ExceptionOccurred returns a local reference to the pending exception, or returns NULL if there is no pending exception.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 228 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
Return Values Returns the JNI_TRUE if there is a pending exception, or JNI_FALSE if there is no pending exception.
Exceptions None.
Prototype void ExceptionClear(JNIEnv *env);
Description Clears any pending exception that is currently being thrown in the current thread. If no exception is currently being thrown, this function has no effect. This function has no effect on exceptions pending on other threads.
ExceptionDescribe also has the side effect of clearing the pending exception.
Linkage Index 17 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
Exceptions None.
Prototype void ExceptionDescribe(JNIEnv *env);
Description Prints the pending exception and a backtrace of the stack to the system error-reporting channel System.out.err. This is a convenience routine provided for debugging.
This function has the side effect of clearing the pending exception.
Linkage Index 16 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
Exceptions None.
Prototype jthrowable ExceptionOccurred(JNIEnv *env);
Description Determines if an exception is pending in the current thread. The exception stays pending until either the native code calls ExceptionClear, or the caller of the native method handles the exception.
The difference between this function and ExceptionCheck (added in Java 2 SDK release 1.2) is that ExceptionCheck returns a jboolean to indicate whether there is a pending exception, whereas this function returns a local reference to the pending exception, or returns NULL if there is no pending exception.
Linkage Index 15 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
Return Values Returns the exception object that is pending in the current thread, or NULL if no exception is pending.
Exceptions None.
Prototype void FatalError(JNIEnv *env, const char *msg);
Description Raises a fatal error and does not expect the virtual machine implementation to recover. Prints the message in a system debugging channel, such as stderr, and terminates the virtual machine instance.
This function does not return.
Linkage Index 18 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
msg: an error message.
Exceptions None.
Prototype jclass FindClass(JNIEnv *env, const char *name);
Description Returns a reference to the named class or interface. This function was introduced in JDK release 1.1, and has been extended in Java 2 SDK release 1.2. In JDK release 1.1, this function loads a locally defined class or interface. It searches the directories and zip files specified by the CLASSPATH environment variable for the class or interface with the specified name.
In Java 2 SDK release 1.2, FindClass locates the class loader associated with the current native method. If the native code belongs to the null loader, then it uses the bootstrap class loader to load the named class or interface. Otherwise, it invokes the ClassLoader.loadClass method in the corresponding class loader to load the named class or interface.
FindClass initializes the class or interface it returns.
The name argument is a class descriptor (§12.3.2). For example, the descriptor for the java.lang.String class is:
"java/lang/String"
The descriptor of the array class java.lang.Object[] is:
"[Ljava/lang/Object;"
Linkage Index 6 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
name: the descriptor of the class or interface to be returned.
Return Values Returns a local reference to the named class or interface, or NULL if the class or interface cannot be loaded. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions ClassFormatError: if the class data does not specify a valid class or interface.
ClassCircularityError: if a class or interface would be its own superclass or superinterface.
NoClassDefFoundError: if no definition for a requested class or interface can be found.
OutOfMemoryError: if the system runs out of memory.
ExceptionInInitializerError: if class or interface initialization fails.
Prototype jfieldID FromReflectedField(JNIEnv *env,
jobject field);
Description Converts a java.lang.reflect.Field instance to a field ID.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 8 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
field: a reference to a java.lang.reflect.Field instance.
Return Values Returns the field ID corresponding to the given instance of java.lang.reflect.Field, or NULL if an exception occurs. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jmethodID FromReflectedMethod(JNIEnv *env,
jobject method);
Description Converts a java.lang.reflect.Method instance or a java.lang.reflect.Constructor instance to a method ID.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 7 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
method: a reference to a java.lang.reflect.Method object or a reference to a java.lang.reflect.Constructor object.
Return Values Returns a method ID that corresponds to a given instance of the java.lang.reflect.Method class or a given instance of the java.lang.reflect.Constructor class, or NULL if an exception occurs. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jsize GetArrayLength(JNIEnv *env, jarray array);
Description Returns the number of elements in a given array. The array argument may denote an array of any element types, including primitive types such as int or double, or referencs types such as the subclasses of java.lang.Object or other array types.
Linkage Index 171 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
array: a reference to the array object whose length is to be determined.
Return Values Returns the length of the array.
Exceptions None.
Prototype <NativeType> *Get<Type>ArrayElements(JNIEnv *env,
<ArrayType> array, jboolean *isCopy);
Forms This family of functions consists of eight members.
Description Returns the body of the primitive array. The result is valid until the corresponding Release<Type>ArrayElements function is called. Since the returned array may be a copy of the original array, changes made to the returned array will not necessarily be reflected in the original array until a corresponding Release<Type>ArrayElements is called.
If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; if no copy is made, it is set to JNI_FALSE.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
array: a reference to the primitive array whose elements are to be accessed.
isCopy: a pointer to a jboolean indicating whether a function returned a pointer to a copy of the array elements or a direct pointer to the original array elements.
Return Values Returns a pointer to the array elements, or NULL if an exception occurs. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype void Get<Type>ArrayRegion(JNIEnv *env,
<ArrayType> array, jsize start,
jsize len, <NativeType> *buf);
Forms This family of functions consists of eight members.
Description Copies a region of a primitive array into a buffer. The array reference and buf buffer must not be NULL.
Linkage Indices in the JNIEnv interface function table.
|
GetBooleanArrayRegion |
199 |
|
GetByteArrayRegion |
200 |
|
GetCharArrayRegion |
201 |
|
GetShortArrayRegion |
202 |
|
GetIntArrayRegion |
203 |
|
GetLongArrayRegion |
204 |
|
GetFloatArrayRegion |
205 |
|
GetDoubleArrayRegion |
206 |
Parameters env: the JNIEnv interface pointer.
array: a reference to an array whose elements are to be copied.
start: the starting index of the array elements to be copied.
len: the number of elements to be copied.
buf: the destination buffer.
Exceptions ArrayIndexOutOfBoundsException: if one of the indices in the region is not valid.
Prototype <NativeType> Get<Type>Field(JNIEnv *env,
jobject obj, jfieldID fieldID);
Forms This family of functions consists of nine members.
GetObjectField |
jobject |
GetBooleanField |
jboolean |
GetByteField |
jbyte |
GetCharField |
jchar |
GetShortField |
jshort |
GetIntField |
jint |
GetLongField |
jlong |
GetFloatField |
jfloat |
GetDoubleField |
jdouble |
Description Returns the value of a field of an instance. The field to access is specified by a field ID. The field ID must be valid in the class of the obj reference. The obj reference must not be NULL.
Linkage Indices in the JNIEnv interface function table.
GetObjectField |
95 |
GetBooleanField |
96 |
GetByteField |
97 |
GetCharField |
98 |
GetShortField |
99 |
GetIntField |
100 |
GetLongField |
101 |
GetFloatField |
102 |
GetDoubleField |
103 |
Parameters env: the JNIEnv interface pointer.
obj: a reference to the instance whose field are to be accessed.
fieldID: a field ID of the given instance.
Return Values Returns the value of the field.
Exceptions None.
Prototype jint GetEnv(JavaVM *vm, void **penv,
jint interface_id);
Description If the current thread is not attached to the given virtual machine instance, sets *penv to NULL, and returns JNI_EDETACHED. If the specified interface is not supported, sets *penv to NULL, and returns JNI_EVERSION. Otherwise, sets *env to the appropriate interface, and returns JNI_OK.
Java 2 SDK release 1.2 supports two valid interface versions: JNI_VERSION_1_1 and JNI_VERSION_1_2. In both cases, GetEnv sets *penv to a 1.2 version of the JNIEnv interface pointer.
This function is added in Java 2 SDK release 1.2.
Linkage Index 6 in the JavaVM interface function table.
Parameters vm: a virtual machine instance.
penv: a location for storing an interface pointer.
interface_id: an interface version number.
Return Values Returns JNI_OK on success, JNI_EDETACHED when the current thread is not attached, and JNI_EVERSION when the specified interface is not supported.
Exceptions None.
Prototype jfieldID GetFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
Description Returns the field ID for an instance field of a class. The field is specified by its name and descriptor. The Get<Type>Field and Set<Type>Field families of accessor functions use field IDs to retrieve instance fields. The field must be accessible from the class referred to by clazz. The actual field, however, may be defined in one of clazz's superclasses. The clazz reference must not be NULL.
GetFieldID causes an uninitialized class to be initialized.
GetFieldID cannot be used to obtain the length of an array. Use GetArrayLength instead.
Linkage Index 94 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class object from which the field ID will be derived.
name: the field name in a 0-terminated UTF-8 string.
sig: the field descriptor in a 0-terminated UTF-8 string.
Return Values Returns a field ID, or NULL if the operation fails. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions NoSuchFieldError: if the specified field cannot be found.
ExceptionInInitializerError: if the class initializer fails due to an exception.
OutOfMemoryError: if the system runs out of memory.
Prototype jint GetJavaVM(JNIEnv *env, JavaVM **vm);
Description Returns the JavaVM interface pointer to which the current thread is attached. The result is placed at the location pointed to by the second argument.
Linkage Index 219 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
vm: a pointer to where the result should be placed.
Return Values Returns zero on success; otherwise, returns a negative value. Returns a negative number if and only if an invocation of this function has thrown an exception.
Exceptions None.
Prototype jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
Description Returns the method ID for an instance method of a class or interface. The method may be defined in one of the clazz's superclasses or superinterfaces and inherited by clazz. The method is determined by its name and descriptor. The clazz reference must not be NULL.
GetMethodID causes an uninitialized class or interface to be initialized.
To obtain the method ID of a constructor, supply "<init>" as the method name and "V" as the return type. For example, the following code segment obtains the method ID for the String(char []) constructor:
jmethodID cid = (*env)->GetMethodID(env,
Class_java_lang_String, "<init>", "([C)V");
Linkage Index 33 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class or interface object from which the method ID will be derived.
name: the method name in a 0-terminated UTF-8 string.
sig: the method descriptor in a 0-terminated UTF-8 string.
Return Values Returns a method ID, or NULL if the operation fails. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions NoSuchMethodError: if the specified method cannot be found.
ExceptionInInitializerError: if the class or interface static initializer fails due to an exception.
OutOfMemoryError: if the system runs out of memory.
Prototype jobject GetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index);
Description Returns an element of a java.lang.Object array. The array reference must not be NULL.
Linkage Index 173 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
array: a reference to the java.lang.Object array from which the element will be accessed.
index: the array index.
Return Values Returns a local reference to the element.
Exceptions ArrayIndexOutOfBoundsException: if index does not specify a valid index in the array.
Prototype jclass GetObjectClass(JNIEnv *env, jobject obj);
Description Returns the class of an object. The obj reference must not be NULL.
Linkage Index 31 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
obj: a reference to the object whose class will be obtained.
Return Values Returns a local reference to the class of the given object.
Exceptions None.
Prototype void * GetPrimitiveArrayCritical(JNIEnv *env,
jarray array, jboolean *isCopy);
Description Returns a pointer to the body of a primitive array. The result is valid until the corresponding ReleasePrimitiveArray-Critical function is called.
It is important to treat the code inside this pair of functions as running in a "critical region." Inside a critical region, native code must not call other JNI functions, nor may the native code make any system call that may cause the current thread to block and wait for another thread in the virtual machine instance.
These restrictions make it more likely that native code will obtain an uncopied version of the array, even if the virtual machine implementation does not support pinning. For example, a virtual machine implementation may temporarily disable garbage collection when native code is holding a pointer to an array obtained via GetPrimitiveArrayCritical.
Multiple pairs of Get/ReleasePrimitiveArrayCritical calls may be overlapped:
jint len = (*env)->GetArrayLength(env, arr1);
jbyte *a1 = (*env)->
GetPrimitiveArrayCritical(env, arr1 0);
if (a1 == NULL) {
... /* out of memory error */
}
jbyte *a2 = (*env)->
GetPrimitiveArrayCritical(env, arr2, 0);
if (a2 == NULL) {
... /* out of memory error */
}
memcpy(a1, a2, len);
(*env)->ReleasePrimitiveArrayCritical(
env, arr2, a2, 0);
(*env)->ReleasePrimitiveArrayCritical(
env, arr1, a1, 0);
GetPrimitiveArrayCritical might still make a copy of the array if the virtual machine implementation internally represents arrays in a different format (noncontiguously, for example). Therefore, it is important to check its return value against NULL for possible out-of-memory situations.
If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 222 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
array: a reference to the array whose elements are to be accessed.
isCopy: a pointer to a jboolean.
Return Values Returns a pointer to the array elements, or NULL if the operation fails. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jfieldID GetStaticFieldID(JNIEnv *env,
jclass clazz, const char *name,
const char *sig);
Description Returns the field ID for a static field of a class or interface. The field may be defined in the class or interface referred to by clazz or in one of its superclass or superinterfaces. The clazz reference must not be NULL. The field is specified by its name and descriptor. The GetStatic<Type>Field and SetStatic<Type>Field families of accessor functions use static field IDs to retrieve static fields.
GetStaticFieldID causes an uninitialized class or interface to be initialized.
Linkage Index 144 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class or interface object whose static field is to be accessed.
name: the static field name in a 0-terminated UTF-8 string.
sig: the field descriptor in a 0-terminated UTF-8 string.
Return Values Returns a field ID, or NULL if the operation fails. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions NoSuchFieldError: if the specified static field cannot be found.
ExceptionInInitializerError: if the class or interface static initializer fails due to an exception.
OutOfMemoryError: if the system runs out of memory.
Prototype <NativeType> GetStatic<Type>Field(JNIEnv *env,
jclass clazz, jfieldID fieldID);
Forms This family of functions consists of nine members.
Description This family of accessor routines returns the value of a static field of a class or interface. The clazz reference must not be NULL. The field to access is specified by a field ID, which is obtained by calling GetStaticFieldID.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class or interface object whose static field is to be accessed.
fieldID: the ID of the static field to be accessed.
Return Values Returns the value of the static field.
Exceptions None.
Prototype jmethodID GetStaticMethodID(JNIEnv *env,
jclass clazz, const char *name,
const char *sig);
Description Returns the method ID for a static method of a class. The method is specified by its name and descriptor. The method may be defined in the class referred to by clazz or in one of its superclasses. The clazz reference must not be NULL.
GetStaticMethodID causes an uninitialized class to be initialized.
Linkage Index 113 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class object whose static method is to be called.
name: the static method name in a 0-terminated UTF-8 string.
sig: the method descriptor in a 0-terminated UTF-8 string.
Return Values Returns a method ID, or NULL if the operation fails. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions NoSuchMethodError: if the specified static method cannot be found.
ExceptionInInitializerError: if the class initializer fails due to an exception.
OutOfMemoryError: if the system runs out of memory.
Prototype const jchar * GetStringChars(JNIEnv *env,
jstring string, jboolean *isCopy);
Description Returns a pointer to the array of Unicode characters of the string. This pointer is valid until ReleaseStringchars is called.
If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.
Linkage Index 165 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
string: a reference to the string object whose elements are to be accessed.
isCopy: a pointer to a jboolean indicating whether a copy of the string is returned.
Return Values Returns a pointer to a Unicode string, or NULL if the operation fails. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype const jchar * GetStringCritical(JNIEnv *env,
jstring string, jboolean *isCopy);
Description Returns a pointer to the contents of a jstring reference. The semantics of this function is similar to the GetStringChars function. If possible, the virtual machine implementation returns a pointer to the elements of the given string; otherwise, a copy is made. The pointer is valid until ReleaseStringCritical is called.
If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; if no copy is made, it is set to JNI_FALSE.
There are significant restrictions on how this function--and the corresponding ReleaseStringCritical function--can be used. In a code segment enclosed by GetStringCritical and ReleaseStringCritical calls, native code must not issue arbitrary JNI calls or cause the current thread to block and wait for another thread in the virtual machine instance.
The restrictions on GetStringCritical are the same as those on GetPrimitiveArrayCritical.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 224 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
string: a reference to the string object whose elements are to be accessed.
isCopy: a pointer to a jboolean indicating whether a copy has been made.
Return Values Returns a pointer to a Unicode string, or NULL if the operation fails. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jsize GetStringLength(JNIEnv *env, jstring string);
Description Returns the number of Unicode characters that constitute a string. The given string reference must not be NULL.
Linkage Index 164 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
string: a reference to the string object whose length is to be determined.
Return Values Returns the length of the string.
Exceptions None.
Prototype void GetStringRegion(JNIEnv *env, jstring str,
jsize start, jsize len, jchar *buf);
Description Copies len number of Unicode characters, beginning at offset start. Copies the characters to the given buffer buf.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 220 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
str: a reference to the string object to be copied.
start: the offset within the string at which to start the copy.
len: the number of Unicode characters to copy.
buf: a pointer to a buffer to hold the Unicode characters.
Exceptions StringIndexOutOfBoundsException: if an index overflow error occurs.
Prototype const jbyte * GetStringUTFChars(JNIEnv *env,
jstring string, jboolean *isCopy);
Description Returns a pointer to an array of UTF-8 characters of the string. This array is valid until it is released by ReleaseStringUTFChars.
If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; if no copy is made, it is set to JNI_FALSE.
Linkage Index 169 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
string: a reference to the string object whose elements are to be accessed.
isCopy: a pointer to a jboolean indicating whether a copy has been made.
Return Values Returns a pointer to a UTF-8 string, or NULL if the operation fails. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jsize GetStringUTFLength(JNIEnv *env,
jstring string);
Description Returns the number of bytes needed to represent a string in the UTF-8 format. The length does not include the trailing zero character. The given string reference must not be NULL.
Linkage Index 168 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
string: a reference to the string object whose UTF-8 length is to be determined.
Return Values Returns the UTF-8 length of the string.
Exceptions None.
Prototype void GetStringUTFRegion(JNIEnv *env, jstring str,
jsize start, jsize len, char *buf);
Description Translates len number of Unicode characters into UTF-8 format. The function begins the translation at offset start and places the result in the given buffer buf. The str reference and buf buffer must not be NULL.
Note that the len argument denotes the number to Unicode characters to be converted, not the number of UTF-8 characters to be copied.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 221 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
str: a reference to the string object to be copied.
start: the offset within the string at which to start the copy.
len: the number of Unicode characters to copy.
buf: a pointer to a buffer to hold the UTF-8 characters.
Exceptions StringIndexOutOfBoundsException: if an index overflow error occurs.
Prototype jclass GetSuperclass(JNIEnv *env, jclass clazz);
Description Returns the superclass of the given class. If clazz represents any class other than the class java.lang.Object, then this function returns a reference to the superclass of the class specified by clazz.
If clazz represents the class java.lang.Object, or if clazz represents an interface, this function returns NULL.
Linkage Index 10 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to a class object whose superclass is to be determined.
Return Values Returns the superclass of the class represented by clazz, or NULL.
Exceptions None.
Prototype jint GetVersion(JNIEnv *env);
Description Returns the version of the JNIEnv interface. In JDK release 1.1, GetVersion returns 0x00010001. In Java 2 SDK release 1.2, GetVersion returns 0x00010002. A virtual machine implementation that supports both the 1.1 and 1.2 versions of the JNI provides only one JNIEnv interface whose version is 0x00010002.
Linkage Index 4 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
Return Values Returns the version of the JNIEnv interface.
Exceptions None.
Prototype jboolean IsAssignableFrom(JNIEnv *env,
jclass clazz1, jclass clazz2);
Description Determines whether an object of class or interface clazz1 can be safely cast to class or interface clazz2. Both clazz1 and clazz2 must not be NULL.
Linkage Index 11 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz1: the first class or interface argument.
clazz2: the second class or interface argument.
Return Values Returns JNI_TRUE if any of the following is true:
X and Y, and IsAssignableFrom(env, X, Y) is JNI_TRUE.
Otherwise, this function returns JNI_FALSE.
Exceptions None.
Prototype jboolean IsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);
Description Tests whether an object is an instance of a class or interface. The clazz reference must not be NULL.
Linkage Index 32 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
obj: a reference to an object.
clazz: a reference to a class or interface.
Return Values Returns JNI_TRUE if obj can be cast to clazz, if obj denotes a null object, or if obj is a weak global reference to an already-collected object; otherwise, returns JNI_FALSE.
Exceptions None.
Prototype jboolean IsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);
Description Tests whether two references refer to the same object. A NULL reference refers to the null object.
In Java 2 SDK release 1.2, this function can also be used to check whether the object referred to by a weak global reference is alive.
Linkage Index 24 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
ref1: a reference to an object.
ref2: a reference to an object.
Return Values Returns JNI_TRUE if ref1 and ref2 refer to the same object; otherwise, returns JNI_FALSE.
In Java 2 SDK release 1.2, as long as a weak global reference wref refers to a live object, IsSameObject(env, wref, NULL) returns JNI_FALSE. After the object referred to by wref is garbage collected, the IsSameObject(env, wref, NULL) call returns JNI_TRUE.
Exceptions None.
Prototype jint JNI_CreateJavaVM(JavaVM **pvm, void **penv,
void *vm_args);
Description Loads and initializes a virtual machine instance. Once the virtual machine instance is initialized, the current thread is called the main thread. In addition, this function sets the env argument to the JNIEnv interface pointer of the main thread.
JDK release 1.1 and Java 2 SDK release 1.2 do not support creating more than one virtual machine instance in a single process.
In JDK release 1.1, the second argument to JNI_CreateJavaVM is always an address of a JNIEnv pointer. The third argument is a pointer to an initialization structure, JDK1_1InitArgs, that is specific to the JDK release 1.1. The version field in vm_args must be set to 0x00010001.
The JDK1_1InitArgs structure is not designed to be portable on all virtual machine implementations. It reflects the requirements of the JDK release 1.1 implementation:
typedef struct JDK1_1InitArgs {
/* Java VM version */
jint version;
/* System properties. */
char **properties;
/* whether to check the source files are
* newer than compiled class files.
*/
jint checkSource;
/* maximum native stack size of
* java.lang.Thread threads.
*/
jint nativeStackSize;
/* maximum java.lang.Thread stack size. */
jint javaStackSize;
/* initial heap size. */
jint minHeapSize;
/* maximum heap size. */
jint maxHeapSize;
/* which byte code should be verified:
* 0 -- none,
* 1 -- remotely loaded code,
* 2 -- all code.
*/
jint verifyMode;
/* local directory path for class loading. */
const char *classpath;
/* a hook for a function that redirects
* all VM messages.
*/
jint (*vfprintf)(FILE *fp,
const char *format,
va_list args);
/* a VM exit hook. */
void (*exit)(jint code);
/* a VM abort hook. */
void (*abort)();
/* whether to enable class GC. */
jint enableClassGC;
/* whether GC messages will appear. */
jint enableVerboseGC;
/* whether asynchronous GC is allowed. */
jint disableAsyncGC;
/* Three reserved fields. */
jint reserved0;
jint reserved1;
jint reserved2;
} JDK1_1InitArgs;
Java 2 SDK release 1.2 preserves backward compatibility with JDK release 1.1. If the initialization argument points to a JDK1_1InitArgs structure, JNI_CreateJavaVM still works as it did in JDK release 1.1.
In addition, Java 2 SDK release 1.2 introduces a generic virtual machine initialization structure that will work with Java 2 SDK release 1.2 as well as future virtual machine implementations. The JNI_CreateJavaVM accepts as the third argument a Java-VMInitArgs structure. Unlike JDK1_1InitArgs, which contains a fixed set of options, JavaVMInitArgs uses symbolic name/value pairs to encode arbitrary virtual machine start-up options. JavaVMInitArgs is defined as follows:
typedef struct JavaVMInitArgs {
jint version;
jint nOptions;
JavaVMOption *options;
jboolean ignoreUnrecognized;
} JavaVMInitArgs;
The version field must be set to JNI_VERSION_1_2. (In contrast, the version field in JDK1_1InitArgs must be set to JNI_VERSION_1_1.) The options field is an array of the following type:
typedef struct JavaVMOption {
char *optionString;
void *extraInfo;
} JavaVMOption;
The size of the array is denoted by the nOptions field in JavaVMInitArgs. If ignoreUnrecognized is JNI_TRUE, JNI_CreateJavaVM ignores all unrecognized option strings that begin with "-X" or "_". If ignoreUnrecognized is JNI_FALSE, JNI_CreateJavaVM returns JNI_ERR as soon as it encounters any unrecognized option strings. All Java virtual machine implementations must recognize the following set of standard options:
In addition, virtual machine implementations may support their own set of implementation-dependent option strings. Implementation-dependent option strings must begin with "-X" or an underscore ("_"). For example, Java 2 SDK release 1.2 supports -Xms and -Xmx options to allow programmers to specify the initial and maximum heap size. Options that begin with "-X" can be specified at the "java" command line.
Here is the example code that creates a virtual machine instance in Java 2 SDK release 1.2:
JavaVMInitArgs vm_args;
JavaVMOption options[4];
/* disable JIT */
options[0].optionString =
"-Djava.compiler=NONE";
/* user classes */
options[1].optionString =
"-Djava.class.path=c:\\myclasses";
/* native lib path */
options[2].optionString =
"-Djava.library.path=c:\\mylibs";
/* print JNI msgs */
options[3].optionString = "-verbose:jni";
vm_args.version = JNI_VERSION_1_2;
vm_args.options = options;
vm_args.nOptions = 4;
vm_args.ignoreUnrecognized = TRUE;
res = JNI_CreateJavaVM(&vm, (void **)&env,
&vm_args);
if (res < 0) {
... /* error occurred
}
Linkage Exported from the native library that implements the Java virtual machine.
Parameters pvm: pointer to the location where the resulting JavaVM interface pointer will be placed.
penv: pointer to the location where the JNIEnv interface pointer for the main thread will be placed.
args: Java virtual machine initialization arguments.
Return Values Returns zero on success; otherwise, returns a negative number.
Exceptions None.
Prototype jint JNI_GetCreatedJavaVMs(JavaVM **vmBuf,
jsize bufLen, jsize *nVMs);
Description Returns pointers to all the virtual machine instances that have been created. This function writes the pointers to the virtual machine instances into the buffer vmBuf in the order that they were created. At most, it writes bufLen number of entries. Finally, it returns the total number of created virtual machine instances in *nVMs.
JDK release 1.1 and Java 2 SDK release 1.2 do not support creating more than one virtual machine instance in a single process.
Linkage Exported from the native library that implements the Java virtual machine.
Parameters vmBuf: pointer to the buffer where the pointer to virtual machine instance will be placed.
bufLen: the length of the buffer.
nVMs: a pointer to an integer.
Return Values Returns zero on success; otherwise, returns a negative number.
Exceptions None.
Prototype jint JNI_GetDefaultJavaVMInitArgs(void *vm_args);
Description Returns a default configuration for the Java virtual machine implementation. Before calling this function, native code must set the version field in vm_args to 0x00010001.
In JDK release 1.1, this function takes as argument a pointer to the JDK1_1InitArgs structure and upon successful return initializes that structure. You must set the version field in JDK1_1InitArgs to 0x00010001 before calling this function. The specification for the JNI_CreateJavaVM function describes the internals of the JDK1_1InitArgs structure.
The new virtual machine initialization structure in Java 2 SDK release 1.2 no longer requires programmers to call JNI_GetDefaultJavaVMInitArgs. This function is still supported but no longer useful in Java 2 SDK release 1.2.
Linkage Exported from the native library that implements the Java virtual machine.
Parameters vm_args: a pointer to a VM-specific initialization structure into which the default arguments are filled.
Return Values Returns zero if the requested version is supported; otherwise, returns a negative number if the requested version is not supported.
Exceptions None.
Prototype jint JNI_OnLoad(JavaVM *vm, void *reserved);
Description Performs initialization operations for a given native library and returns the JNI version required by the native library. The virtual machine implementation calls JNI_OnLoad when the native library is loaded, for example, through a call to System.load-Library. JNI_OnLoad must return the JNIEnv interface version required by the native library.
System.loadLibrary triggers the execution of this function. The JNI_OnLoad function returns the JNI version number required by the native library. If the native library does not export a JNI_OnLoad function, the virtual machine implementation assumes that the library only requires JNI version JNI_VERSION_1_1. If the virtual machine implementation does not recognize the version number returned by JNI_OnLoad, then the native library cannot be loaded.
Support for the JNI_OnLoad hook is added in Java 2 SDK 1.2.
Linkage Exported from native libraries that contain native method implementation.
Parameters vm: the pointer to the Java virtual machine instance that loaded the native library.
reserved: not currently used. This parameter is set to NULL and reserved for use in the future.
Return Values Returns the JNIEnv interface version number that the native library needs.
Exceptions None.
Prototype void JNI_OnUnload(JavaVM *vm, void *reserved);
Description Performs cleanup operations for a native library. The virtual machine implementation calls JNI_OnUnload when the class loader containing the native library is garbage collected. This function can be used to perform cleanup operations. Because this function is called in an unknown context (such as from a finalizer), the programmer should be conservative when using Java virtual machine services and refrain from making arbitrary JNI function calls.
Support for the JNI_OnUnload hook is added in Java 2 SDK 1.2.
Linkage Exported from native libraries that contain native method implementation.
Parameters vm: the pointer to the Java virtual machine instance.
reserved: Not currently used. This parameter is set to NULL and reserved for possible use in the future.
Exceptions None.
Prototype jint MonitorEnter(JNIEnv *env, jobject obj);
Description Enters the monitor associated with the object referred to by obj. The obj reference must not be NULL.
Each object has a monitor associated with it. If the current thread already owns the monitor associated with obj, it increments a counter in the monitor indicating the number of times this thread has entered the monitor. If the monitor associated with obj is not owned by any thread, the current thread becomes the owner of the monitor, setting the entry count of this monitor to 1. If another thread already owns the monitor associated with obj, the current thread waits until the monitor is released, then tries again to gain ownership.
A monitor entered through a MonitorEnter JNI function call cannot be exited using the monitorexit Java virtual machine instruction or a synchronized method return. A MonitorEnter JNI function call and a monitorenter Java virtual machine instruction may race to enter the monitor associated with the same object.
Linkage Index 217 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
obj: a reference to an object whose associated monitor will be entered.
Return Values Returns zero on success; otherwise, returns a negative value. Returns a negative number if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jint MonitorExit(JNIEnv *env, jobject obj);
Description Exits the monitor associated with the given object. The current thread must be the owner of the monitor associated with the object referred to by obj. The obj reference must not be NULL.
The thread decrements the counter indicating the number of times it has entered this monitor. If the value of the counter becomes zero, the current thread releases the monitor.
Native code must not use MonitorExit to exit a monitor entered through a synchronized method or a monitorenter Java virtual machine instruction.
Linkage Index 218 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
obj: a reference to an object whose associated monitor will be exited.
Return Values Returns zero on success; otherwise, returns a negative value. Returns a negative number if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
IllegalMonitorStateException: if the current thread does not own the monitor.
Prototype jobject NewGlobalRef(JNIEnv *env, jobject obj);
Description Creates a new global reference to the object referred to by the obj argument. The obj argument may be a global, weak global, or local reference. Global references must be explicitly disposed of by calling DeleteGlobalRef.
Linkage Index 21 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
obj: a global or local reference.
Return Values Returns a global reference. The result is NULL if the system runs out of memory, if the given argument is NULL, or if the given reference is a weak global reference referring to an object that has already been garbage collected.
Exceptions None.
Prototype jobject NewLocalRef(JNIEnv *env, jobject ref);
Description Creates a new local reference that refers to the same object as ref. The given ref may be a global, weak global, or local reference.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 25 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
ref: a reference to the object for which the function creates a new local reference.
Return Values Returns a local reference. The result is NULL if the system runs out of memory, if the given argument is NULL, or if the given reference is a weak global reference referring to an object that has already been garbage collected.
Exceptions None.
Prototype jobject NewObject(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);
Description Constructs a new object. The method ID indicates which constructor method to invoke. This ID may be obtained by calling GetMethodID with "<init>" as the method name and "V" as the return type. The constructor must be defined in the class referred to by clazz, not one of its superclasses.
The clazz argument must not refer to an array class.
Programmers place all arguments that are to be passed to the constructor immediately following the methodID argument. NewObject accepts these arguments and passes them to the constructor that the programmer wishes to invoke.
Linkage Index 28 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class object whose instance is to be created.
methodID: the method ID of the constructor to be executed in the newly created instance.
Additional arguments: arguments to be passed to the constructor.
Return Values Returns a local reference to an object, or NULL if the object cannot be constructed. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions InstantiationException: if the class is an interface or an abstract class.
OutOfMemoryError: if the system runs out of memory.
Any exceptions thrown by the constructor.
Prototype jobject NewObjectA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);
Description Constructs a new object. The method ID indicates which constructor method to invoke.This ID may be obtained by calling GetMethodID with "<init>" as the method name and "V" as the return type. The constructor must be defined in the class referred to by clazz, not one of its superclasses.
The clazz argument must not refer to an array class.
Programmers place all arguments that are to be passed to the constructor in an args array of jvalues that immediately follows the methodID argument. NewObjectA accepts the arguments in this array, and, in turn, passes them to the constructor that the programmer wishes to invoke.
Linkage Index 30 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class object whose instance is to be created.
methodID: the method ID of the constructor to be executed in the newly created instance.
args: an array of arguments to be passed to the constructor.
Return Values Returns a local reference to an object, or NULL if the object cannot be constructed. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions InstantiationException: if the class is an interface or an abstract class.
OutOfMemoryError: if the system runs out of memory.
Any exceptions thrown by the constructor.
Prototype jobject NewObjectV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);
Description Constructs a new object. The method ID indicates which constructor method to invoke. This ID may be obtained by calling GetMethodID with "<init>" as the method name and "V" as the return type. The constructor must be defined in the class referred to by clazz, not one of its superclasses.
The clazz argument must not refer to an array class.
Programmers place all arguments that are to be passed to the constructor in an args argument of type va_list that immediately follows the methodID argument. NewObjectV accepts these arguments, and, in turn, passes them to the constructor that the programmer wishes to invoke.
Linkage Index 29 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to the class object whose instance is to be created.
methodID: the method ID of the constructor to be executed in the newly created instance.
args: a va_list of arguments to be passed to the constructor.
Return Values Returns a local reference to an object, or NULL if the object cannot be constructed. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions InstantiationException: if the class is an interface or an abstract class.
OutOfMemoryError: if the system runs out of memory.
Any exceptions thrown by the constructor.
Prototype jarray NewObjectArray(JNIEnv *env, jsize length,
jclass elementType, jobject initialElement);
Description Constructs a new array holding objects in class or interface elementType. All elements are initially set to initialElement. The length argument can be zero. The elementType reference must not be NULL.
Linkage Index 172 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
length: the number of elements in the array to be created.
elementType: class or interface of the elements in the array.
initialElement: a reference to initialization value object. This value can be NULL.
Return Values Returns a local reference to an array object, or NULL if the array cannot be constructed. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype <ArrayType> New<Type>Array(JNIEnv *env,
jsize length);
Forms This family of functions consists of eight members.
Description Constructs a new array of primitive element types. All elements in the newly constructed array are initialized to zero.
Linkage Indices in the JNIEnv interface function table.
NewBooleanArray |
175 |
NewByteArray |
176 |
NewCharArray |
177 |
NewShortArray |
178 |
NewIntArray |
179 |
NewLongArray |
180 |
NewFloatArray |
181 |
NewDoubleArray |
182 |
Parameters env: the JNIEnv interface pointer.
length: the number of elements in the array to be created.
Return Values Returns a local reference to a primitive array, or NULL if the array cannot be constructed. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jstring NewString(JNIEnv *env,
const jchar *uchars, jsize len);
Description Constructs a java.lang.String object from the given Unicode characters.
Linkage Index 163 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
uchars: pointer to the Unicode sequence that makes up the string.
len: length of the Unicode string.
Return Values Returns a local reference to a string object, or NULL if the string cannot be constructed. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jstring NewStringUTF(JNIEnv *env,
const char *bytes);
Description Constructs a new java.lang.String object from an array of UTF-8 characters. The UTF-8 characters pointed to by bytes are 0-terminated.
Linkage Index 167 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer, or NULL if the string cannot be constructed.
bytes: the pointer to the sequence of UTF-8 characters that makes up the string.
Return Values Returns a local reference to a string object, or NULL if the string cannot be constructed. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);
Description Creates a new weak global reference to the object referenced to by obj. Weak global references are a special kind of global reference. Unlike normal global references, a weak global reference allows the underlying object to be garbage collected. You can use weak global references in any situation where you would otherwise use global or local references. When the garbage collector runs, it frees the underlying object if the object is only referred to by weak references. A weak global reference pointing to a freed object is functionally equivalent to the NULL reference. Programmers can detect whether a weak global reference points to a freed object by using the function IsSame-Object to compare the weak reference against NULL.
Weak global references in JNI are a simplified version of the Java weak references (java.lang.ref) API, available as part of Java 2 SDK release 1.2. The JNI weak global references are weaker than all four types of weak references in the Java weak references API.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 226 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
obj: the object for which the weak global reference will be created.
Return Values Returns NULL if obj refers to null, if obj is a weak global reference to a garbage-collected object, or if the virtual machine implementation runs out of memory.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jobject PopLocalFrame(JNIEnv *env, jobject result);
Description Pops the current (top-most) local reference frame from the stack. In addition, this function frees all the local references contained in the frame and returns a local reference in the previous local reference frame for the given result object.
Pass NULL in the result parameter if you do not need to return a reference to the previous frame.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 20 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
result: an object to be passed to the previous local reference frame.
Return Values Returns a local reference in the previous local reference frame that refers to the same object as the second argument.
Exceptions None.
Prototype jint PushLocalFrame(JNIEnv *env, jint capacity);
Description Creates a new local reference frame in which at least the specified number of local references can be created. All the local references created in the new frame will be freed when PopLocalFrame is called.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 19 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
capacity: the maximum number of local references that will be created in the local reference frame.
Return Values Returns zero on success; otherwise, returns a negative number and throws OutOfMemoryError. Returns a negative number if and only if an invocation of this function has thrown an exception.
Exceptions OutOfMemoryError: if the system runs out of memory.
Prototype jint RegisterNatives(JNIEnv *env, jclass clazz,
const JNINativeMethod *methods, jint nMethods);
Description Registers native methods with the class specified by the clazz argument. The methods parameter specifies an array of JNI-NativeMethod structures that contains the names, descriptors, and function pointers of the native methods. The nMethods parameter specifies the number of native methods in the array. The JNINativeMethod structure is defined as follows:
typedef struct {
char *name;
char *signature;
void *fnPtr;
} JNINativeMethod;
The fnPtr fields in the JNINativeMethod structures must be valid function pointer that implements the native method.
Linkage Index 215 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to a class object in which the native methods will be registered.
methods: native methods to be registered.
nMethods: the number of native methods to be registered.
Return Values Returns zero on success; otherwise, returns a negative value. Returns a negative number if and only if an invocation of this function has thrown an exception.
Exceptions NoSuchMethodError: if a specified method cannot be found or if the method is not native.
Prototype void Release<Type>ArrayElements(JNIEnv *env,
<ArrayType> array, <NativeType> *elems,
jint mode);
Forms This family of functions consists of eight members.
Description Informs the virtual machine implementation that native code no longer needs access to primitive array elements, derived using the corresponding Get<Type>ArrayElements function. If necessary, this function copies back all changes made to elems to the original array.
The mode argument provides information on how the array buffer should be released. The mode argument has no effect if elems is not a copy of the elements in array. Otherwise, mode has the following impact, as shown in the following table:
|
|
copy back and free the elems buffer |
|
|
copy back but do not free the elems buffer |
|
|
free the buffer without copying back the possible changes in the elems buffer |
In most cases, programmers pass 0 to the mode argument to ensure consistent behavior for both pinned and copied arrays. The other options give the programmer more control over memory management and should be used with extreme care.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
array: a reference to an array object.
elems: a pointer to array elements.
mode: the release mode.
Exceptions None.
Prototype void ReleasePrimitiveArrayCritical(JNIEnv *env,
jarray array, void *carray, jint mode);
Description Informs the virtual machine implementation that native code no longer needs access to carray, the result of a previous GetPrimitiveArray-Critical call. If necessary, this function copies back all changes made to carray to the original array.
The mode argument provides information on how the array buffer should be released. The mode argument has no effect if carray is not a copy of the elements in array. Otherwise, mode has the following impact, as shown in the following table:
|
|
copy back and free the carray buffer |
|
|
copy back but do not free the carray buffer |
|
|
free the buffer without copying back the possible changes in the carray buffer |
In most cases, programmers pass 0 to the mode argument to ensure consistent behavior for copied arrays. The other options give the programmer more control over memory management and should be used with extreme care.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 223 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
array: a reference to an array object.
carray: a pointer to array elements.
mode: the release mode.
Exceptions None.
Prototype void ReleaseStringChars(JNIEnv *env,
jstring string, const jchar *chars);
Description Informs the virtual machine implementation that native code no longer needs access to chars. The chars argument is a pointer obtained from string using GetStringChars.
Linkage Index 166 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
string: a reference to a string object.
chars: a pointer to a Unicode string.
Exceptions None.
Prototype void ReleaseStringCritical(JNIEnv *env,
jstring string, const jchar *carray);
Description Informs the virtual machine implementation that native code no longer needs access to carray. The carray argument is a pointer obtained from string using GetStringCritical.
In a code segment enclosed by GetStringCritical and ReleaseStringCritical calls, native code must not issue arbitrary JNI calls or cause the current thread to block and wait for another thread in the virtual machine instance.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 225 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
string: a reference to a string object.
chars: a pointer to a Unicode string.
Exceptions None.
Prototype void ReleaseStringUTFChars(JNIEnv *env,
jstring string, const char *utf);
Description Informs the virtual machine implementation that native code no longer needs access to the native string utf. The utf argument is a pointer derived from string using GetStringUTFChars.
Linkage Index 169 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
string: a reference to a string object.
utf: a pointer to a UTF-8 string.
Exceptions None.
Prototype void Set<Type>ArrayRegion(JNIEnv *env,
<ArrayType> array, jsize start,
jsize len, <NativeType> *buf);
Forms This family of functions consists of eight members.
Description Copies back a region of a primitive array from a buffer. The array reference and buf buffer must not be NULL.
Linkage Indices in the JNIEnv interface function table.
|
SetBooleanArrayRegion |
207 |
|
SetByteArrayRegion |
208 |
|
SetCharArrayRegion |
209 |
|
SetShortArrayRegion |
210 |
|
SetIntArrayRegion |
211 |
|
SetLongArrayRegion |
212 |
|
SetFloatArrayRegion |
213 |
|
SetDoubleArrayRegion |
214 |
Parameters env: the JNIEnv interface pointer.
array: a reference to a primitive array to which the elements are copied.
start: the starting index in the primitive array.
len: the number of elements to be copied.
buf: the source buffer.
Exceptions ArrayIndexOutOfBoundsException: if one of the indices in the region is not valid.
Prototype void Set<Type>Field(JNIEnv *env, jobject obj,
jfieldID fieldID, <NativeType> value);
Forms This family of functions consists of nine members.
SetObjectField |
jobject |
SetBooleanField |
jboolean |
SetByteField |
jbyte |
SetCharField |
jchar |
SetShortField |
jshort |
SetIntField |
jint |
SetLongField |
jlong |
SetFloatField |
jfloat |
SetDoubleField |
jdouble |
Description Sets the value of an instance field of an object. The obj reference must not be NULL.
Linkage Indices in the JNIEnv interface function table.
SetObjectField |
104 |
SetBooleanField |
105 |
SetByteField |
106 |
SetCharField |
107 |
SetShortField |
108 |
SetIntField |
109 |
SetLongField |
110 |
SetFloatField |
111 |
SetDoubleField |
112 |
Parameters env: the JNIEnv interface pointer.
obj: a reference to an object.
fieldID: a field ID.
value: the new value of the field.
Exceptions None.
Prototype void SetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index,
jobject value);
Description Sets an element of an Object array. The array reference must not be NULL.
Linkage Index 174 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
array: a reference to an array whose element will be accessed.
index: index of the array element to be accessed.
value: the new value of the array element.
Exceptions ArrayIndexOutOfBoundsException: if index does not specify a valid index in the array.
ArrayStoreException: if the class of value is not a subclass of the element class of the array.
Prototype void SetStatic<Type>Field(JNIEnv *env,
jclass clazz, jfieldID fieldID, <NativeType> value);
Forms This family of functions consists of nine members.
Description Sets the value of a static field of a class or interface. The field to access is specified by a field ID.
Linkage Indices in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to a class or interface whose static field will be accessed.
fieldID: an ID denoting the static field to be accessed.
value: the new value of the field.
Exceptions None.
Prototype jint Throw(JNIEnv *env, jthrowable obj);
Description Causes a java.lang.Throwable object to be thrown. A thrown exception will be pending in the current thread, but does not immediately disrupt native code execution.
Linkage Index 13 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
obj: a java.lang.Throwable object.
Return Values Returns zero on success; otherwise, returns a negative value.
Exceptions The given java.lang.Throwable object.
Prototype jint ThrowNew(JNIEnv *env, jclass clazz,
const char *message);
Description Constructs an exception object from the specified class with the message specified by message and causes that exception to be thrown.
Linkage Index 14 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a subclass of java.lang.Throwable.
message: the message used to construct the java.lang.Throwable object.
Return Values Returns zero on success; otherwise, returns a negative value if the specified exception cannot be thrown.
Exceptions The newly constructed java.lang.Throwable object, or any exception that occurs in constructing this object.
Prototype jobject ToReflectedField(JNIEnv *env, jclass cls,
jfieldID fieldID, jboolean isStatic);
Description Converts a field ID derived from cls to an instance of the java.lang.reflect.Field class.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 12 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
cls: a reference to a class or interface.
fieldID: a JNI field ID.
isStatic: whether the field ID denotes a static field.
Return Values Returns an instance of the java.lang.reflect.Field class; otherwise, returns NULL. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutofMemoryError: if the system runs out of memory.
Prototype jobject ToReflectedMethod(JNIEnv *env, jclass cls,
jmethodID methodID, jboolean isStatic);
Description Converts a method ID derived from cls to an instance of the java.lang.reflect.Method class or to an instance of the java.lang.reflect.Constructor class.
This function was introduced in Java 2 SDK release 1.2.
Linkage Index 9 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
cls: a reference to a class or interface.
methodID: a method ID.
isStatic: whether the method ID refers to a static method.
Return Values Returns an instance of the java.lang.reflect.Method class or an instance of the java.lang.reflect.Constructor class; otherwise, returns NULL. Returns NULL if and only if an invocation of this function has thrown an exception.
Exceptions OutofMemoryError: if the system runs out of memory.
Prototype jint UnregisterNatives(JNIEnv *env, jclass clazz);
Description Unregisters native methods of a class. The class goes back to the state before it was linked or registered with its native method functions.
This function should not be used in normal native code. Instead, it provides special programs a way to reload and relink native libraries.
Linkage Index 216 in the JNIEnv interface function table.
Parameters env: the JNIEnv interface pointer.
clazz: a reference to a class object whose native methods are to be unregistered.
Return Values Returns zero on success; otherwise, returns a negative value.
Exceptions None.
| Contents | Prev | Next | Index | The Java Native Interface Programmer's Guide and Specification |
Copyright © 2002 Sun Microsystems, Inc.
All rights reserved
Please send any comments or corrections to jni@java.sun.com