Android JNI 学习(四)：接口方法表 & Base Api & Exception Api

时间：2021-09-17 21:37:49

本文我们来总结一下JNI 提供的功能列表及相关的函数表。

注意：请注意使用术语“必须”来描述对JNI程序员的限制。例如，当您看到某个JNI函数必须接收非NULL对象时，您有责任确保不将NULL传递给该JNI函数。因此，JNI实现不需要在该JNI函数中执行NULL指针检查。

一、接口方法表

可以通过JNIEnv参数以固定偏移量访问每个函数。JNIEnv的类型是一个指向存储所有JNI函数指针的结构。它的定义如下：

typedef const struct JNINativeInterface * JNIEnv;

VM初始化功能表，如下面的代码所示 。请注意，前三个条目是保留用于将来与COM的兼容性的。此外，我们NULL在函数表的开头附近保留了许多附加条目，因此，例如，可以在FindClass之后而不是在表的末尾添加与类相关的未来JNI操作。

const struct JNINativeInterface ... = {

    NULL,

    NULL,

    NULL,

    NULL,

    GetVersion,

    DefineClass,

    FindClass,

    FromReflectedMethod,

    FromReflectedField,

    ToReflectedMethod,

    GetSuperclass,

    IsAssignableFrom,

    ToReflectedField,

    Throw,

    ThrowNew,

    ExceptionOccurred,

    ExceptionDescribe,

    ExceptionClear,

    FatalError,

    PushLocalFrame,

    PopLocalFrame,

    NewGlobalRef,

    DeleteGlobalRef,

    DeleteLocalRef,

    IsSameObject,

    NewLocalRef,

    EnsureLocalCapacity,

    AllocObject,

    NewObject,

    NewObjectV,

    NewObjectA,

    GetObjectClass,

    IsInstanceOf,

    GetMethodID,

    CallObjectMethod,

    CallObjectMethodV,

    CallObjectMethodA,

    CallBooleanMethod,

    CallBooleanMethodV,

    CallBooleanMethodA,

    CallByteMethod,

    CallByteMethodV,

    CallByteMethodA,

    CallCharMethod,

    CallCharMethodV,

    CallCharMethodA,

    CallShortMethod,

    CallShortMethodV,

    CallShortMethodA,

    CallIntMethod,

    CallIntMethodV,

    CallIntMethodA,

    CallLongMethod,

    CallLongMethodV,

    CallLongMethodA,

    CallFloatMethod,

    CallFloatMethodV,

    CallFloatMethodA,

    CallDoubleMethod,

    CallDoubleMethodV,

    CallDoubleMethodA,

    CallVoidMethod,

    CallVoidMethodV,

    CallVoidMethodA,

    CallNonvirtualObjectMethod,

    CallNonvirtualObjectMethodV,

    CallNonvirtualObjectMethodA,

    CallNonvirtualBooleanMethod,

    CallNonvirtualBooleanMethodV,

    CallNonvirtualBooleanMethodA,

    CallNonvirtualByteMethod,

    CallNonvirtualByteMethodV,

    CallNonvirtualByteMethodA,

    CallNonvirtualCharMethod,

    CallNonvirtualCharMethodV,

    CallNonvirtualCharMethodA,

    CallNonvirtualShortMethod,

    CallNonvirtualShortMethodV,

    CallNonvirtualShortMethodA,

    CallNonvirtualIntMethod,

    CallNonvirtualIntMethodV,

    CallNonvirtualIntMethodA,

    CallNonvirtualLongMethod,

    CallNonvirtualLongMethodV,

    CallNonvirtualLongMethodA,

    CallNonvirtualFloatMethod,

    CallNonvirtualFloatMethodV,

    CallNonvirtualFloatMethodA,

    CallNonvirtualDoubleMethod,

    CallNonvirtualDoubleMethodV,

    CallNonvirtualDoubleMethodA,

    CallNonvirtualVoidMethod,

    CallNonvirtualVoidMethodV,

    CallNonvirtualVoidMethodA,

    GetFieldID,

    GetObjectField,

    GetBooleanField,

    GetByteField,

    GetCharField,

    GetShortField,

    GetIntField,

    GetLongField,

    GetFloatField,

    GetDoubleField,

    SetObjectField,

    SetBooleanField,

    SetByteField,

    SetCharField,

    SetShortField,

    SetIntField,

    SetLongField,

    SetFloatField,

    SetDoubleField,

    GetStaticMethodID,

    CallStaticObjectMethod,

    CallStaticObjectMethodV,

    CallStaticObjectMethodA,

    CallStaticBooleanMethod,

    CallStaticBooleanMethodV,

    CallStaticBooleanMethodA,

    CallStaticByteMethod,

    CallStaticByteMethodV,

    CallStaticByteMethodA,

    CallStaticCharMethod,

    CallStaticCharMethodV,

    CallStaticCharMethodA,

    CallStaticShortMethod,

    CallStaticShortMethodV,

    CallStaticShortMethodA,

    CallStaticIntMethod,

    CallStaticIntMethodV,

    CallStaticIntMethodA,

    CallStaticLongMethod,

    CallStaticLongMethodV,

    CallStaticLongMethodA,

    CallStaticFloatMethod,

    CallStaticFloatMethodV,

    CallStaticFloatMethodA,

    CallStaticDoubleMethod,

    CallStaticDoubleMethodV,

    CallStaticDoubleMethodA,

    CallStaticVoidMethod,

    CallStaticVoidMethodV,

    CallStaticVoidMethodA,

    GetStaticFieldID,

    GetStaticObjectField,

    GetStaticBooleanField,

    GetStaticByteField,

    GetStaticCharField,

    GetStaticShortField,

    GetStaticIntField,

    GetStaticLongField,

    GetStaticFloatField,

    GetStaticDoubleField,

    SetStaticObjectField,

    SetStaticBooleanField,

    SetStaticByteField,

    SetStaticCharField,

    SetStaticShortField,

    SetStaticIntField,

    SetStaticLongField,

    SetStaticFloatField,

    SetStaticDoubleField,

    NewString,

    GetStringLength,

    GetStringChars,

    ReleaseStringChars,

    NewStringUTF,

    GetStringUTFLength,

    GetStringUTFChars,

    ReleaseStringUTFChars,

    GetArrayLength,

    NewObjectArray,

    GetObjectArrayElement,

    SetObjectArrayElement,

    NewBooleanArray,

    NewByteArray,

    NewCharArray,

    NewShortArray,

    NewIntArray,

    NewLongArray,

    NewFloatArray,

    NewDoubleArray,

    GetBooleanArrayElements,

    GetByteArrayElements,

    GetCharArrayElements,

    GetShortArrayElements,

    GetIntArrayElements,

    GetLongArrayElements,

    GetFloatArrayElements,

    GetDoubleArrayElements,

    ReleaseBooleanArrayElements,

    ReleaseByteArrayElements,

    ReleaseCharArrayElements,

    ReleaseShortArrayElements,

    ReleaseIntArrayElements,

    ReleaseLongArrayElements,

    ReleaseFloatArrayElements,

    ReleaseDoubleArrayElements,

    GetBooleanArrayRegion,

    GetByteArrayRegion,

    GetCharArrayRegion,

    GetShortArrayRegion,

    GetIntArrayRegion,

    GetLongArrayRegion,

    GetFloatArrayRegion,

    GetDoubleArrayRegion,

    SetBooleanArrayRegion,

    SetByteArrayRegion,

    SetCharArrayRegion,

    SetShortArrayRegion,

    SetIntArrayRegion,

    SetLongArrayRegion,

    SetFloatArrayRegion,

    SetDoubleArrayRegion,

    RegisterNatives,

    UnregisterNatives,

    MonitorEnter,

    MonitorExit,

    GetJavaVM,

    GetStringRegion,

    GetStringUTFRegion,

    GetPrimitiveArrayCritical,

    ReleasePrimitiveArrayCritical,

    GetStringCritical,

    ReleaseStringCritical,

    NewWeakGlobalRef,

    DeleteWeakGlobalRef,

    ExceptionCheck,

    NewDirectByteBuffer,

    GetDirectBufferAddress,

    GetDirectBufferCapacity,

    GetObjectRefType

  };

请注意，函数表可以在所有JNI接口指针之间共享。

二、JNI 接口基本方法（JNI Base Api）

1. GetVersion (获取版本信息)

jint GetVersion(JNIEnv *env);

返回JNI的版本号。

参数:

env: jni接口指针

返回值:

返回一个值,其中高位为major版本号返回,低位为minor版本号。

在 JDK/JRE 1.1中返回 0x00010001

在 JDK/JRE 1.2中返回 0x00010002

在 JDK/JRE 1.4中返回 0x00010004

在 JDK/JRE 1.6中返回 0x00010006

常量:

SINCE JDK/JRE 1.2:

#define JNI_VERSION_1_1 0x00010001

#define JNI_VERSION_1_2 0x00010002

/* Error codes */

#define JNI_EDETACHED (-2) /* thread detached from the VM */

#define JNI_EVERSION (-3) /* JNI version error

SINCE JDK/JRE 1.4:

#define JNI_VERSION_1_4 0x00010004

SINCE JDK/JRE 1.6:

#define JNI_VERSION_1_6 0x00010006

使用实例:

jint version = env->GetVersion();

2. FindClass(发现Java类)

jclass FindClass(JNIEnv *env, const char *name);

在JDK 1.1发行版中,这个函数加载本地定义的类(locally-defined class), 它搜索在由环境变量 CLASSPATH 目录下的子目录和zip文件中搜索指定的类名。

从JDK 1.2发行版之后,Java安全模型允许非本地系统类也可以加载和调用本地方法。FindClass 函数会使用与当前本地方法关联的ClassLoader, 并用它来加载本地方法指定的class。如果本地方法属于系统类(system class),则没有ClassLoader会被调用。否则,将使用正确的ClassLoader来加载(load)和链接(link)指定名称的类。

从JDK 1.2发行版之后,当通过 Invocation 接口来调用 FindClass 函数,将没有当前的本地方法或与之关联的ClassLoader。这种情况下,会使用 ClassLoader.getSystemClassLoader 来替代。这个ClassLoader 是虚拟机用来创建应用(applications)的,它有能力定位到 java.class.path 参数下的所有类。

第二个 name 参数,使用全称类名或数组类型签名(array type signature)。例如,String类的全称类名为:

"java/lang/String"

而Object数组类型的使用:

"[Ljava/lang/Object;"

注意:一定要注意分隔符不是 . 而是 / ,不要写错了。

参数:

env:JNI接口指针 
name:全称的类名(包名以 / 作为分隔符, 然后紧跟着类名),如果名字以 [开头(数组签名标识符),则返回一个数组的类,这个字符串也是MUTF-8。

返回值:

指定名称的类的对象(a class object),或者在没有找到对应类时返回 NULL

抛出异常:

ClassFormatError :如果class内容不是一个有效的class文件。

ClassCircularityError:如果class或interface是它自己的父类或父接口,造成循环层级关系。

OutOfMemoryError:如果系统在载入的过程中内存不足。

NoClassDefFoundError:如果指定的类或接口没有被找到。(当name传null或超长时也会抛出这个异常)

使用实例:

// Start thread which receives commands from the SA.

jclass threadClass = env->FindClass("java/lang/Thread");

if (threadClass == NULL) stop("Unable to find class java/lang/Thread");

jstring threadName = env->NewStringUTF("Serviceability Agent Command Thread");

if (threadName == NULL) stop("Unable to allocate debug thread name");

jmethodID ctor = env->GetMethodID(threadClass, "<init>", "(Ljava/lang/String;)V");

if (ctor == NULL) stop("Unable to find appropriate constructor for java/lang/Thread");

// Allocate thread object

jthread thr = (jthread) env->NewObject(threadClass, ctor, threadName);  

以上代码来之 openJDK 源码 中的 /hotspot/agent/src/share/native/jvmdi/sa.cpp

3. GetSuperclass (获取父类)

jclass GetSuperclass(JNIEnv *env, jclass clazz);

只要传入的 clazz 参数不是 java/lang/Object 则返回该类的父类。

如果传入的 clazz 参数是 java/lang/Object 则返回NULL,因为它没有父类。当传入的是一个接口,而不是类时,也返回 NULL 。

参数:

env:JNI接口指针 
clazz: Java类对象(java class object)

返回值:

返回传入的 clazz 的父类,或 NULL .

使用实例:

jclass clazz = env->GetObjectClass(thiz);

clazz = env->GetSuperclass(clazz);

jfieldID __state = env->GetFieldID(clazz, "__state", "J");  

以上代码来至:https://github.com/liucheng98/mesos-0.22.0/blob/5cfd2c36c0e8361fa2e2d9b6f191a738d22a9cfd/src/java/jni/org_apache_mesos_state_LogState.cpp

4. IsAssignableFrom (检查类是否能转型)

jboolean IsAssignableFrom(JNIEnv *env, jclass class1, jclass clazz2);

检查 clazz1 的对象是否能被安全的转型(cast)为 clazz2

参数:

env:JNI接口指针 
clazz1:第一个class参数(需要转型的类) 
clazz2:第二个class参数(转型的目标类)

返回值:

如果是以下情况则返回 JNI_TRUE :

clazz1 和 clazz2 指向同一个java类 
clazz1 是 clazz2 的子类。(向上转型是安全的) 
clazz1 是 clazz2(接口)的实现类。(也属于向上转型)

使用实例:

jclass listInterface = env->FindClass("java/util/List")

jclass arrayListClass = env->FindClass("java/util/ArrayList")

jboolean isSafe = env->IsAssignableFrom(arrayListClass, listInterface);

// isSafe: true;

isSafe = env->IsAssignableFrom(listInterface, arrayListClass);

// isSafe: false;

三、 JNI 异常方法 (JNI Exception)

1. Throw （抛出异常）

jint Throw(JNIEnv *env, jthrowable obj);  

触发一个 java.lang.Throwable 对象的异常被抛出。

参数:

env:JNI接口指针 
obj: java.lang.Throwable 对象

返回值:

成功则返回0, 失败时返回赋值

抛出异常:

抛出 java.lang.Throwable 对象

使用实例:

jthrowable exception = env->ExceptionOccurred();

if (exception) {

env->ExceptionClear();

detach_internal(env, this_obj);

env->Throw(exception);

return;

}  

以上代码来至 OpenJDK 源码 /hotspot/agent/src/os/solaris/proc/saproc.cpp

2. ThrowNew （构造一个异常对象并抛出）

jint ThrowNew(JNIEnv *env, jclass clazz, const char *message);

Exception对象的构造器函数,message为异常的错误消息,clazz为异常的类。

参数:

env:JNI接口指针 
clazz: java.lang.Throwable 的子类 
message: 用于创建 java.lang.Throwable 对象时传入的错误消息。这个是字符串是MUTF-8编码。

返回值: 

成功则返回0, 失败时返回赋值

抛出异常: 

抛出刚构造出来的 java.lang.Throwable 对象

使用实例:

env->ThrowNew(env->FindClass("sun/jvm/hotspot/debugger/DebuggerException"), errMsg);

3. ExceptionOccurred （检查是否有异常被抛出）

jthrowable ExceptionOccurred(JNIEnv *env);

检查是否有异常被抛出。这个异常在本地方法调用 ExceptionClear() 方法或被Java代码处理这个异常之前都会保持在被抛出状态。

参数:

env:JNI接口指针

返回值:

返回过程中抛出的异常,或没有异常被抛出时返回 NULL 。

使用实例:

jthrowable exception = env->ExceptionOccurred();

if (exception) {

env->ExceptionClear();

detach_internal(env, this_obj);

env->Throw(exception);

return;

}

以上代码来至 OpenJDK 源码 /hotspot/agent/src/os/solaris/proc/saproc.cpp

4. ​ExceptionDescribe （打印异常的stack trace）

void ExceptionDescribe(JNIEnv *env);  

打印一个异常的stack trace到系统的错误输出,例如 stderr 这是为了调试提供便利。

参数:

env:JNI接口指针

使用实例:

jthrowable exc = safe_ExceptionOccurred(env);

if (exc) {

env->DeleteLocalRef(exc);

env->ExceptionDescribe();

env->ExceptionClear();

}  

以上代码来至:OpenJDK 源码中的 /jdk/src/windows/native/sun/windows/awt_Object.cpp

5. ExceptionClear （清理所有即将抛出的异常）

void ExceptionClear(JNIEnv *env);

清理任何即将抛出的异常。如果没有异常被抛出,则不起任何作用。

参数:

env:JNI接口指针

使用实例:

jthrowable exc = safe_ExceptionOccurred(env);

if (exc) {

env->DeleteLocalRef(exc);

env->ExceptionDescribe();

env->ExceptionClear();

}  

以上代码来至:OpenJDK 源码中的 /jdk/src/windows/native/sun/windows/awt_Object.cpp

6. FatalError （抛出一个严重的错误）

void FatalError(JNIEnv *env, const char *msg);

抛出一个严重错误,并不希望虚拟机恢复。

参数:

env:JNI接口指针 
msg : 错误消息,这个字符串为MUTF-8编码

使用实例:

env->CallVoidMethod(currentThread, setThreadName, threadName) ;

if( env->ExceptionCheck() ) {

env->ExceptionDescribe() ;

env->FatalError("setting thread name failed: could not start reading thread");

return 0L ;

}  

以上代码来至:https://github.com/tnarnold/netsnmpj/blob/3153c3e9297dd7de7db9d1a65c97f77937ae147b/netsnmpj-preliminary/native/nativeThread.cc

7. ExceptionCheck （快速检查是否有异常被抛出）

jboolean ExceptionCheck(JNIEnv *env);

这是一个快速函数用于检查是否有被抛出的异常,而不创建一个这个异常的局部引用。

参数:

env:JNI接口指针

返回值: 

有一个即将被抛出的异常时返回 JNI_TURE ,没有则返回 JNI_FALSE

使用实例:

env->CallVoidMethod(thread, runId);

if (env->ExceptionCheck()) {

env->ExceptionDescribe();

env->ExceptionClear();

// handle exception

}  

以上代码来至:OpenJDK 源码中的 /jdk/src/windows/native/sun/windows/awt_Toolkit.cpp

相关文章