java 本地接口规范_《Java 本地接口规范》

对象操作

AllocObject

jobjectAllocObject(JNIEnv *env, jclass clazz);

分配新 Java 对象而不调用该对象的任何构造函数。返回该对象的引用。

clazz 参数务必不要引用数组类。

参数：

env：JNI 接口指针。

clazz：Java 类对象。

返回值：

返回 Java 对象。如果无法构造该对象，则返回NULL。

抛出：

InstantiationException：如果该类为一个接口或抽象类。

OutOfMemoryError：如果系统内存不足。

NewObject

NewObjectA

NewObjectV

jobjectNewObject(JNIEnv *env, jclass clazz,

jmethodID methodID, ...);

jobject NewObjectA(JNIEnv *env,jclass clazz,

jmethodID methodID, jvalue *args);

jobject NewObjectV(JNIEnv *env,jclass clazz,

jmethodID methodID, va_list args);

构造新 Java 对象。方法 ID指示应调用的构造函数方法。该 ID 必须通过调用 GetMethodID() 获得，且调用时的方法名必须为

，而返回类型必须为 void (V)。

clazz参数务必不要引用数组类。

NewObject

编程人员应将传递给构造函数的所有参数紧跟着放在 methodID 参数的后面。NewObject() 收到这些参数后，将把它们传给编程人员所要调用的 Java 方法。

NewObjectA

编程人员应将传递给构造函数的所有参数放在 jvalues 类型的数组 args 中，该数组紧跟着放在 methodID 参数的后面。NewObject() 收到数组中的这些参数后，将把它们传给编程人员所要调用的 Java 方法。

NewObjectV

编程人员应将传递给构造函数的所有参数放在va_list 类型的参数 args 中，该参数紧跟着放在 methodID 参数的后面。NewObject() 收到这些参数后，将把它们传给编程人员所要调用的 Java 方法。

参数：

env：JNI 接口指针。

clazz：Java 类对象。

methodID：构造函数的方法 ID。

NewObject 的其它参数：

传给构造函数的参数。

NewObjectA 的其它参数：

args：传给构造函数的参数数组。

NewObjectV 的其它参数：

args：传给构造函数的参数 va_list。

返回值：

返回 Java 对象，如果无法构造该对象，则返回NULL。

抛出：

InstantiationException：如果该类为接口或抽象类。

OutOfMemoryError：如果系统内存不足。

构造函数抛出的任何异常。

GetObjectClass

jclassGetObjectClass(JNIEnv *env, jobject obj);

返回对象的类。

参数：

env：JNI 接口指针。

obj：Java 对象(不能为 NULL)。

返回值：

返回 Java 类对象。

IsInstanceOf

jbooleanIsInstanceOf(JNIEnv *env, jobject obj,

jclass clazz);

测试对象是否为某个类的实例。

参数：

env：JNI 接口指针。

obj：Java 对象。

clazz：Java 类对象。

返回值：

如果可将 obj 强制转换为 clazz，则返回 JNI_TRUE。否则返回 JNI_FALSE。NULL 对象可强制转换为任何类。

IsSameObject

jbooleanIsSameObject(JNIEnv *env, jobject ref1,

jobject ref2);

测试两个引用是否引用同一 Java 对象。

参数：

env：JNI 接口指针。

ref1：Java 对象。

ref2：Java 对象。

返回值：

如果 ref1 和 ref2 引用同一 Java 对象或均为 NULL，则返回

JNI_TRUE。否则返回 JNI_FALSE。

访问对象的域

GetFieldID

jfieldIDGetFieldID(JNIEnv *env, jclass clazz,

const char *name, const char *sig);

返回类的实例(非静态)域的域 ID。该域由其名称及签名指定。访问器函数的GetField 及 SetField 系列使用域 ID 检索对象域。

GetFieldID() 将未初始化的类初始化。

GetFieldID() 不能用于获取数组的长度域。应使用GetArrayLength()。

参数：

env：JNI 接口指针。

clazz：Java 类对象。

name:0 终结的 UTF-8 字符串中的域名。

sig：0 终结的 UTF-8 字符串中的域签名。

返回值：

域 ID。如果操作失败，则返回NULL。

抛出：

NoSuchFieldError：如果找不到指定的域。

ExceptionInInitializerError：如果由于异常而导致类初始化程序失败。

OutOfMemoryError：如果系统内存不足。

GetField 例程

NativeTypeGetField(JNIEnv*env, jobject obj,

jfieldID fieldID);

该访问器例程系列返回对象的实例(非静态)域的值。要访问的域由通过调用GetFieldID() 而得到的域 ID 指定。

下表说明了 GetField 例程名及结果类型。应将 GetField 中的 type 替换为域的 Java 类型(或使用表中的某个实际例程名)，然后将NativeType 替换为该例程对应的本地类型。

表 4-1 GetField 访问器例程系列

GetField 例程名

本地类型

GetObjectField()

jobject

GetBooleanField()

jboolean

GetByteField()

jbyte

GetCharField()

jchar

GetShortField()

jshort

GetIntField()

jint

GetLongField()

jlong

GetFloatField()

jfloat

GetDoubleField()

jdouble

参数：

env：JNI 接口指针。

obj：Java 对象(不能为 NULL)。

fieldID：有效的域 ID。

返回值：

域的内容。

SetField 例程

voidSetField(JNIEnv *env, jobject obj, jfieldID fieldID,

NativeTypevalue);

该访问器例程系列设置对象的实例(非静态)域的值。要访问的域由通过调用SetFieldID() 而得到的域 ID 指定。

下表说明了 SetField 例程名及结果类型。应将 SetField 中的

type 替换为域的 Java 类型(或使用表中的某个实际例程名)，然后将NativeType 替换为该例程对应的本地类型。

表4-2 SetField 访问器例程系列

SetField 例程名

本地类型

SetObjectField()

jobject

SetBooleanField()

jboolean

SetByteField()

jbyte

SetCharField()

jchar

SetShortField()

jshort

SetIntField()

jint

SetLongField()

jlong

SetFloatField()

jfloat

SetDoubleField()

jdouble

参数：

env：JNI 接口指针。

obj：Java 对象(不能为 NULL)。

fieldID：有效的域 ID。

value：域的新值。

调用实例方法

GetMethodID

jmethodIDGetMethodID(JNIEnv *env, jclass clazz,

const char *name, const char *sig);

返回类或接口实例(非静态)方法的方法 ID。方法可在某个 clazz 的超类中定义，也可从 clazz 继承。该方法由其名称和签名决定。

GetMethodID() 可使未初始化的类初始化。

要获得构造函数的方法 ID，应将 作为方法名，同时将 void (V) 作为返回类型。

参数：

env：JNI 接口指针。

clazz：Java 类对象。

name：0 终结的 UTF-8 字符串中的方法名。

sig：0 终结的 UTF-8 字符串中的方法签名。

返回值：

方法 ID，如果找不到指定的方法，则为 NULL。

抛出：

NoSuchMethodError：如果找不到指定方法。

ExceptionInInitializerError：如果由于异常而导致类初始化程序失败。

OutOfMemoryError：如果系统内存不足。

CallMethod 例程

CallMethodA 例程

CallMethodV 例程

NativeTypeCallMethod(JNIEnv*env, jobject obj,

jmethodID methodID, ...);

NativeTypeCallMethodA(JNIEnv *env, jobject obj,

jmethodID methodID, jvalue *args);

NativeTypeCallMethodV(JNIEnv *env, jobject obj,

jmethodID methodID, va_list args);

这三个操作的方法用于从本地方法调用Java 实例方法。它们的差别仅在于向其所调用的方法传递参数时所用的机制。

这三个操作将根据所指定的方法 ID 调用 Java 对象的实例(非静态)方法。参数methodID 必须通过调用

GetMethodID() 来获得。

当这些函数用于调用私有方法和构造函数时，方法 ID 必须从 obj 的真实类派生而来，而不应从其某个超类派生。

CallMethod例程

编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。CallMethod 例程接受这些参数并将其传给编程人员所要调用的 Java 方法。

CallMethodA 例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。CallMethodA routine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。

CallMethodV例程

编程人员将方法的所有参数放在紧跟着在 methodID 参数之后的 va_list 类型参数变量中。CallMethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

下表根据结果类型说明了各个方法调用例程。用户应将CallMethod中的 type 替换为所调用方法的 Java 类型(或使用表中的实际方法调用例程名)，同时将

NativeType 替换为该例程相应的本地类型。

表 4-3 实例方法调用例程

CallMethod 例程名

本地类型

CallVoidMethod() CallVoidMethodA()

CallVoidMethodV()

void

CallObjectMethod() CallObjectMethodA()

CallObjectMethodV()

jobject

CallBooleanMethod() CallBooleanMethodA()

CallBooleanMethodV()

jboolean

CallByteMethod() CallByteMethodA()

CallByteMethodV()

jbyte

CallCharMethod() CallCharMethodA()

CallCharMethodV()

jchar

CallShortMethod() CallShortMethodA()

CallShortMethodV()

jshort

CallIntMethod() CallIntMethodA() CallIntMethodV()

jint

CallLongMethod() CallLongMethodA()

CallLongMethodV()

jlong

CallFloatMethod() CallFloatMethodA()

CallFloatMethodV()

jfloat

CallDoubleMethod() CallDoubleMethodA()

CallDoubleMethodV()

jdouble

参数：

env：JNI 接口指针。

obj：Java 对象。

methodID：方法 ID。

CallMethod例程的其它参数：

要传给 Java 方法的参数。

CallMethodA例程的其它参数：

args：参数数组。

CallMethodV例程的其它参数：

args：参数的 va_list。

返回值：

返回调用 Java 方法的结果。

抛出：

执行 Java 方法时抛出的异常。

CallNonvirtualMethod 例程

CallNonvirtualMethodA 例程

CallNonvirtualMethodV 例程

NativeTypeCallNonvirtualMethod(JNIEnv *env, jobject obj,

jclass clazz, jmethodID methodID, ...);

NativeTypeCallNonvirtualMethodA(JNIEnv *env, jobject obj,

jclass clazz, jmethodID methodID, jvalue *args);

NativeTypeCallNonvirtualMethodV(JNIEnv *env, jobject obj,

jclass clazz, jmethodID methodID, va_list args);

这些操作根据指定的类和方法 ID 调用某 Java 对象的实例(非静态)方法。参数 methodID 必须通过调用clazz类的GetMethodID() 获得。

CallNonvirtualMethod 和 CallMethod 例程系列并不相同。CallMethod 例程根据对象的类调用方法，而

CallNonvirtualMethod 例程则根据获得方法 ID 的(由 clazz 参数指定)类调用方法。方法 ID 必须从对象的真实类或其某个超类获得。

CallNonvirtualMethod例程

编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。CallNonvirtualMethod routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

CallNonvirtualMethodA例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。CallNonvirtualMethodAroutine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。

CallNonvirtualMethodV例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 va_list 类型参数 args 中。CallNonvirtualMethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

下表根据结果类型说明了各个方法调用例程。用户应将CallNonvirtualMethod中的 type 替换为所调用方法的 Java 类型(或使用表中的实际方法调用例程名)，同时将

NativeType 替换为该例程相应的本地类型。

表 4-4 CallNonvirtualMethod 例程

CallNonvirtualMethod 例程名

本地类型

CallNonvirtualVoidMethod() CallNonvirtualVoidMethodA()

CallNonvirtualVoidMethodV()

void

CallNonvirtualObjectMethod() CallNonvirtualObjectMethodA()

CallNonvirtualObjectMethodV()

jobject

CallNonvirtualBooleanMethod() CallNonvirtualBooleanMethodA()

CallNonvirtualBooleanMethodV()

jboolean

CallNonvirtualByteMethod() CallNonvirtualByteMethodA()

CallNonvirtualByteMethodV()

jbyte

CallNonvirtualCharMethod() CallNonvirtualCharMethodA()

CallNonvirtualCharMethodV()

jchar

CallNonvirtualShortMethod() CallNonvirtualShortMethodA()

CallNonvirtualShortMethodV()

jshort

CallNonvirtualIntMethod() CallNonvirtualIntMethodA()

CallNonvirtualIntMethodV()

jint

CallNonvirtualLongMethod() CallNonvirtualLongMethodA()

CallNonvirtualLongMethodV()

jlong

CallNonvirtualFloatMethod() CallNonvirtualFloatMethodA()

CallNonvirtualFloatMethodV()

jfloat

CallNonvirtualDoubleMethod() CallNonvirtualDoubleMethodA()

CallNonvirtualDoubleMethodV()

jdouble

参数：

env：JNI 接口指针。

clazz：Java 类。

obj: Java 对象。

methodID：方法 ID。

CallNonvirtualMethod例程的其它参数：

要传给 Java 方法的参数。

CallNonvirtualMethodA例程的其它参数：

args：参数数组。

CallNonvirtualMethodV例程的其它参数：

args：参数的 va_list。

返回值：

调用 Java 方法的结果。

抛出：

执行 Java 方法时所抛出的异常。

访问静态域

GetStaticFieldID

jfieldIDGetStaticFieldID(JNIEnv *env, jclass clazz,

const char *name, const char *sig);

返回类的静态域的域 ID。域由其名称和签名指定。GetStaticField 和 SetStaticField 访问器函数系列使用域 ID 检索静态域。

GetStaticFieldID() 将未初始化的类初始化。

参数：

env：JNI 接口指针。

clazz：Java 类对象。

name: 0 终结的 UTF-8 字符串中的静态域名。

sig：0 终结的 UTF-8 字符串中的域签名。

返回值：

域 ID。如果找不到指定的静态域，则为 NULL。

抛出：

NoSuchFieldError：如果找不到指定的静态域。

ExceptionInInitializerError：如果由于异常而导致类初始化程序失败。

OutOfMemoryError：如果系统内存不足。

GetStaticField 例程

NativeTypeGetStaticField(JNIEnv*env, jclass clazz,

jfieldID fieldID);

该访问器例程系列返回对象的静态域的值。要访问的域由通过调用GetStaticFieldID()而得到的域 ID 指定。

下表说明了 GetStaticField 例程名及结果类型。应将 GetStaticField 中的

type 替换为域的 Java 类型(或使用表中的某个实际例程名)，然后将NativeType 替换为该例程对应的本地类型。

表 4-5 GetStaticField 访问器例程系列

GetStaticField 例程名

本地类型

GetStaticObjectField()

jobject

GetStaticBooleanField()

jboolean

GetStaticByteField()

jbyte

GetStaticCharField()

jchar

GetStaticShortField()

jshort

GetStaticIntField()

jint

GetStaticLongField()

jlong

GetStaticFloatField()

jfloat

GetStaticDoubleField()

jdouble

参数：

env：JNI 接口指针。

clazz：Java 类对象。

fieldID：静态域 ID。

返回值：

静态域的内容。

SetStaticField 例程

voidSetStaticField(JNIEnv *env, jclass clazz,

jfieldID fieldID,NativeTypevalue);

该访问器例程系列设置对象的静态域的值。要访问的域由通过调用GetStaticFieldID()而得到的域 ID 指定。

下表说明了 SetStaticField 例程名及结果类型。应将 SetStaticField 中的

type 替换为域的 Java 类型(或使用表中的某个实际例程名)，然后将NativeType 替换为该例程对应的本地类型。

表4-6 SetStaticField 访问器例程系列

SetStaticField 例程名

本地类型

SetStaticObjectField()

jobject

SetStaticBooleanField()

jboolean

SetStaticByteField()

jbyte

SetStaticCharField()

jchar

SetStaticShortField()

jshort

SetStaticIntField()

jint

SetStaticLongField()

jlong

SetStaticFloatField()

jfloat

SetStaticDoubleField()

jdouble

参数：

env：JNI 接口指针。

clazz：Java 类对象。

fieldID：静态域 ID。

value：域的新值。

调用静态方法

GetStaticMethodID

jmethodIDGetStaticMethodID(JNIEnv *env, jclass clazz,

const char *name, const char *sig);

返回类的静态方法的方法 ID。方法由其名称和签名指定。

GetStaticMethodID() 将未初始化的类初始化。

参数：

env：JNI 接口指针。

clazz：Java 类对象。

name：0 终结 UTF-8 字符串中的静态方法名。

sig：0 终结 UTF-8 字符串中的方法签名。

返回值：

方法 ID，如果操作失败，则为 NULL。

抛出：

NoSuchMethodError：如果找不到指定的静态方法。

ExceptionInInitializerError：如果由于异常而导致类初始化程序失败。

OutOfMemoryError：如果系统内存不足。

CallStaticMethod 例程

CallStaticMethodA 例程

CallStaticMethodV 例程

NativeTypeCallStaticMethod(JNIEnv*env, jclass clazz,

jmethodID methodID, ...);

NativeTypeCallStaticMethodA(JNIEnv *env, jclass clazz,

jmethodID methodID, jvalue *args);

NativeTypeCallStaticMethodV(JNIEnv *env, jclass clazz,

jmethodID methodID, va_list args);

这些操作将根据指定的方法 ID 调用 Java 对象的静态方法。methodID 参数必须通过调用GetStaticMethodID() 得到。

方法 ID 必须从 clazz 派生，而不能从其超类派生。

CallStaticMethod例程

编程人员应将要传给方法的所有参数紧跟着放在 methodID 参数之后。 CallStaticMethod routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

CallStaticMethodA 例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 jvalues 类型数组 args 中。CallStaticMethodA routine 接受这些数组中的参数并将其传给编程人员所要调用的 Java 方法。

CallStaticMethodV例程

编程人员应将要传给方法的所有参数放在紧跟在 methodID 参数之后的 va_list 类型参数 args 中。CallStaticMethodV routine 接受这些参数并将其传给编程人员所要调用的 Java 方法。

下表根据结果类型说明了各个方法调用例程。用户应将CallStaticMethod中的

type 替换为所调用方法的 Java 类型(或使用表中的实际方法调用例程名)，同时将 NativeType 替换为该例程相应的本地类型。

表 4-7 CallStaticMethod 调用例程

CallStaticMethod 例程名

本地类型

CallStaticVoidMethod() CallStaticVoidMethodA()

CallStaticVoidMethodV()

void

CallStaticObjectMethod() CallStaticObjectMethodA()

CallStaticObjectMethodV()

jobject

CallStaticBooleanMethod() CallStaticBooleanMethodA()

CallStaticBooleanMethodV()

jboolean

CallStaticByteMethod() CallStaticByteMethodA()

CallStaticByteMethodV()

jbyte

CallStaticCharMethod() CallStaticCharMethodA()

CallStaticCharMethodV()

jchar

CallStaticShortMethod() CallStaticShortMethodA()

CallStaticShortMethodV()

jshort

CallStaticIntMethod() CallStaticIntMethodA()

CallStaticIntMethodV()

jint

CallStaticLongMethod() CallStaticLongMethodA()

CallStaticLongMethodV()

jlong

CallStaticFloatMethod() CallStaticFloatMethodA()

CallStaticFloatMethodV()

jfloat

CallStaticDoubleMethod() CallStaticDoubleMethodA()

CallStaticDoubleMethodV()

jdouble

参数：

env：JNI 接口指针。

clazz：Java 类对象。

methodID：静态方法 ID。

CallStaticMethod例程的其它参数：

要传给静态方法的参数。

CallStaticMethodA例程的其它参数：

args：参数数组。

CallStaticMethodV例程的其它参数：

args：参数的 va_list。

返回值：

返回调用静态 Java 方法的结果。

抛出：

执行 Java 方法时抛出的异常。