对象操作
AllocObject
jobjectAllocObject(JNIEnv *env, jclass clazz);
分配新 Java 对象而不调用该对象的任何构造函数。返回该对象的引用。
参数:
env:JNI 接口指针。
返回值:
返回 Java 对象。如果无法构造该对象,则返回NULL
。
抛出:
InstantiationException:如果该类为一个接口或抽象类。
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
)。
NewObject
编程人员应将传递给构造函数的所有参数紧跟着放在 methodID
参数的后面。NewObject()
收到这些参数后,将把它们传给编程人员所要调用的 Java 方法。
NewObjectA
编程人员应将传递给构造函数的所有参数放在 jvalues
类型的数组 args
中,该数组紧跟着放在
methodID
参数的后面。NewObject()
收到数组中的这些参数后,将把它们传给编程人员所要调用的 Java 方法。
NewObjectV
编程人员应将传递给构造函数的所有参数放在 va_list
类型的参数 args
中,该参数紧跟着放在
methodID
参数的后面。NewObject()
收到这些参数后,将把它们传给编程人员所要调用的 Java 方法。
参数:
env:JNI 接口指针。
NewObject 的其它参数:
传给构造函数的参数。
NewObjectA 的其它参数:
args:传给构造函数的参数数组。
NewObjectV 的其它参数:
args:传给构造函数的参数 va_list。
返回值:
返回 Java 对象,如果无法构造该对象,则返回NULL
。
抛出:
InstantiationException:如果该类为接口或抽象类。
GetObjectClass
jclassGetObjectClass(JNIEnv *env, jobject obj);
参数:
env:JNI 接口指针。
返回值:
返回 Java 类对象。
IsInstanceOf
jbooleanIsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);
参数:
env:JNI 接口指针。
返回值:
如果可将 obj
强制转换为 clazz
,则返回 JNI_TRUE
。否则返回
JNI_FALSE
。NULL
对象可强制转换为任何类。
IsSameObject
jbooleanIsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);
测试两个引用是否引用同一 Java 对象。
参数:
env:JNI 接口指针。
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 类对象。
返回值:
域 ID。如果操作失败,则返回NULL
。
抛出:
NoSuchFieldError:如果找不到指定的域。
ExceptionInInitializerError
:如果由于异常而导致类初始化程序失败。
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 访问器例程系列 |
|
参数:
env:JNI 接口指针。
返回值:
域的内容。
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 访问器例程系列 |
|
参数:
env:JNI 接口指针。
调用实例方法
GetMethodID
jmethodIDGetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
返回类或接口实例(非静态)方法的方法 ID。方法可在某个 clazz
的超类中定义,也可从 clazz
继承。该方法由其名称和签名决定。
GetMethodID()
可使未初始化的类初始化。
要获得构造函数的方法 ID,应将 <init>
作为方法名,同时将 void
(V
) 作为返回类型。
参数:
env:JNI 接口指针。
返回值:
方法 ID,如果找不到指定的方法,则为 NULL
。
抛出:
NoSuchMethodError:如果找不到指定方法。
ExceptionInInitializerError
:如果由于异常而导致类初始化程序失败。
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 实例方法调用例程 |
|
|
|
参数:
env:JNI 接口指针。
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 替换为该例程相应的本地类型。
参数:
env:JNI 接口指针。
clazz:
Java 类。
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 接口指针。
返回值:
域 ID。如果找不到指定的静态域,则为 NULL
。
抛出:
NoSuchFieldError:如果找不到指定的静态域。
ExceptionInInitializerError
:如果由于异常而导致类初始化程序失败。
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 访问器例程系列 |
|
参数:
env:JNI 接口指针。
返回值:
静态域的内容。
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 访问器例程系列 |
|
参数:
env:JNI 接口指针。
clazz:Java 类对象。
调用静态方法
GetStaticMethodID
jmethodIDGetStaticMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
GetStaticMethodID()
将未初始化的类初始化。
参数:
env:JNI 接口指针。
返回值:
方法 ID,如果操作失败,则为 NULL
。
抛出:
NoSuchMethodError:如果找不到指定的静态方法。
ExceptionInInitializerError
:如果由于异常而导致类初始化程序失败。
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()
得到。
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 替换为该例程相应的本地类型。
参数:
env:JNI 接口指针。
CallStatic<type>Method例程的其它参数:
要传给静态方法的参数。
CallStatic<type>MethodA例程的其它参数:
args:参数数组。
CallStatic<type>MethodV例程的其它参数:
args:参数的 va_list
。
返回值:
返回调用静态 Java 方法的结果。
抛出:
执行 Java 方法时抛出的异常。