对象操作

 

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() 获得，且调用时的方法名必须为 <init>，而返回类型必须为 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。该域由其名称及签名指定。访问器函数的Get<type>Field 及 Set<type>Field 系列使用域 ID 检索对象域。

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

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

参数：

env：JNI 接口指针。

clazz：Java 类对象。

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

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

返回值：

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

抛出：

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

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

OutOfMemoryError：如果系统内存不足。

 

Get<type>Field 例程

NativeTypeGet<type>Field(JNIEnv*env, jobject obj,
jfieldID fieldID);

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

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

表 4-1 Get<type>Field 访问器例程系列
Get<type>Field 例程名	本地类型
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。

返回值：

域的内容。

 

Set<type>Field 例程

voidSet<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);

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

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

表4-2 Set<type>Field 访问器例程系列
Set<type>Field 例程名	本地类型
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，应将 <init> 作为方法名，同时将 void (V) 作为返回类型。

参数：

env：JNI 接口指针。

clazz：Java 类对象。

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

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

返回值：

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

抛出：

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

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

OutOfMemoryError：如果系统内存不足。

 

Call<type>Method 例程
Call<type>MethodA 例程
Call<type>MethodV 例程

NativeTypeCall<type>Method(JNIEnv*env, jobject obj,
jmethodID methodID, ...);

NativeTypeCall<type>MethodA(JNIEnv *env, jobject obj,
jmethodID methodID, jvalue *args);

NativeTypeCall<type>MethodV(JNIEnv *env, jobject obj,
jmethodID methodID, va_list args);

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

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

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

Call<type>Method例程

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

Call<type>MethodA 例程

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

Call<type>MethodV例程

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

下表根据结果类型说明了各个方法调用例程。用户应将Call<type>Method 中的 type 替换为所调用方法的 Java 类型（或使用表中的实际方法调用例程名），同时将 NativeType 替换为该例程相应的本地类型。

表 4-3 实例方法调用例程
Call<type>Method 例程名	本地类型
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。

Call<type>Method例程的其它参数：

要传给 Java 方法的参数。

Call<type>MethodA例程的其它参数：

args：参数数组。

Call<type>MethodV例程的其它参数：

args：参数的 va_list。

返回值：

返回调用 Java 方法的结果。

抛出：

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

 

CallNonvirtual<type>Method 例程
CallNonvirtual<type>MethodA 例程
CallNonvirtual<type>MethodV 例程

NativeTypeCallNonvirtual<type>Method(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, ...);

NativeTypeCallNonvirtual<type>MethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, jvalue *args);

NativeTypeCallNonvirtual<type>MethodV(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, va_list args);

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

CallNonvirtual<type>Method 和 Call<type>Method 例程系列并不相同。Call<type>Method 例程根据对象的类调用方法，而 CallNonvirtual<type>Method 例程则根据获得方法 ID 的（由 clazz 参数指定）类调用方法。方法 ID 必须从对象的真实类或其某个超类获得。

CallNonvirtual<type>Method例程

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

CallNonvirtual<type>MethodA例程

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

CallNonvirtual<type>MethodV例程

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

下表根据结果类型说明了各个方法调用例程。用户应将CallNonvirtual<type>Method 中的 type 替换为所调用方法的 Java 类型（或使用表中的实际方法调用例程名），同时将 NativeType 替换为该例程相应的本地类型。

表 4-4 CallNonvirtual<type>Method 例程
CallNonvirtual<type>Method 例程名	本地类型
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。

CallNonvirtual<type>Method例程的其它参数：

要传给 Java 方法的参数。

CallNonvirtual<type>MethodA例程的其它参数：

args：参数数组。

CallNonvirtual<type>MethodV例程的其它参数：

args：参数的 va_list。

返回值：

调用 Java 方法的结果。

抛出：

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

访问静态域

 

GetStaticFieldID

jfieldIDGetStaticFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

返回类的静态域的域 ID。域由其名称和签名指定。GetStatic<type>Field 和 SetStatic<type>Field 访问器函数系列使用域 ID 检索静态域。

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

参数：

env：JNI 接口指针。

clazz：Java 类对象。

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

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

返回值：

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

抛出：

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

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

OutOfMemoryError：如果系统内存不足。

 

GetStatic<type>Field 例程

NativeTypeGetStatic<type>Field(JNIEnv*env, jclass clazz,
jfieldID fieldID);

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

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

表 4-5 GetStatic<type>Field 访问器例程系列
GetStatic<type>Field 例程名	本地类型
GetStaticObjectField()	jobject
GetStaticBooleanField()	jboolean
GetStaticByteField()	jbyte
GetStaticCharField()	jchar
GetStaticShortField()	jshort
GetStaticIntField()	jint
GetStaticLongField()	jlong
GetStaticFloatField()	jfloat
GetStaticDoubleField()	jdouble

参数：

env：JNI 接口指针。

clazz：Java 类对象。

fieldID：静态域 ID。

返回值：

静态域的内容。

 

SetStatic<type>Field 例程

voidSetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID, NativeType value);

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

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

表4-6 SetStatic<type>Field 访问器例程系列
SetStatic<type>Field 例程名	本地类型
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：如果系统内存不足。

 

CallStatic<type>Method 例程
CallStatic<type>MethodA 例程
CallStatic<type>MethodV 例程

NativeTypeCallStatic<type>Method(JNIEnv*env, jclass clazz,
jmethodID methodID, ...);

NativeTypeCallStatic<type>MethodA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

NativeTypeCallStatic<type>MethodV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

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

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

CallStatic<type>Method例程

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

CallStatic<type>MethodA 例程

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

CallStatic<type>MethodV例程

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

下表根据结果类型说明了各个方法调用例程。用户应将CallStatic<type>Method 中的 type 替换为所调用方法的 Java 类型（或使用表中的实际方法调用例程名），同时将 NativeType 替换为该例程相应的本地类型。

表 4-7 CallStatic<type>Method 调用例程
CallStatic<type>Method 例程名	本地类型
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。

CallStatic<type>Method例程的其它参数：

要传给静态方法的参数。

CallStatic<type>MethodA例程的其它参数：

args：参数数组。

CallStatic<type>MethodV例程的其它参数：

args：参数的 va_list。

返回值：

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

抛出：

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