【安卓开发】JNI常用接口 - 2

3、异常
抛出异常
jint Throw(JNIEnv *env, jthrowable obj);
引起将要被抛出的对象 java.lang.Throwable
参数：
env：JNI接口指针
obj：一个java.lang.Throwable对象
返回：
成功返回0，失败返回一个负数。

jint ThrowNew(JNIEnv *env, jclass clazz,const char *message);
用message中定义的消息，在特定的类中构造一个异常对象，并且引起异常。
参数：
env：JNI接口指针
clazz： java.lang.Throwable的子类
message：用于构建 java.lang.Throwable对象的消息，该字符串用modified UTF-8编码。
返回：
成功返回0，失败返回一个负数。

jthrowable ExceptionOccurred(JNIEnv *env);

void ExceptionDescribe(JNIEnv *env);

void ExceptionClear(JNIEnv *env);

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

jboolean ExceptionCheck(JNIEnv *env);

4、全局引用和局部引用

jobject NewGlobalRef(JNIEnv *env, jobject obj);
给对象obj创建一个全局引用，obj可以是全局或者局部引用。全局引用必须通过调用DeleteGlobalRef()被显式处理。
参数：
env：JNI接口指针
obj：全局或者局部引用
返回：
返回一个全局引用，当系统内存溢出时返回NULL

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);
通过globalRef删除全局引用
参数：
env：JNI接口指针
globalRef：全局引用

局部引用只在本地接口调用时的生命周期内有效，当本地方法返回时，它们会被自动释放。每个局部引用都会消耗一定的虚拟机资源，但编程是需要确保本地方法不过分配局部引用，尽管局部引用能够被自动销毁，但过度分配局部引用会导致虚拟机在执行本地方法时内存溢出。
void DeleteLocalRef(JNIEnv *env, jobject localRef);
通过localRef删除全局引用
参数：
env：JNI接口指针
localRef：全局引用

以下为JDK/JRE 1.2以上版本提供的用于管理局部引用的接口。

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);
确保在当前线程中能够至少有一个局部引用能按照给定的参数被创建。成功返回0，失败返回负数并抛出OutOfMemoryError异常。

在本地方法中，虚拟机自动确保至少有16个局部引用能够被创建。

为了能够兼容之前版本，虚拟机在既定的容量下分配局部引用。为了调试上的支持，当太多局部引用被创建时，虚拟机会提示警告。在JDK中，编程人员可以提供 -verbose:jni命令行选项来打开这些警告信息。如果没有局部引用能够在既定的容量下被创建，虚拟机将调用FatalError 。

jint PushLocalFrame(JNIEnv *env, jint capacity);
在能够被创建的局部引用中，创建一个新的局部引用帧。成功返回0，失败返回负数并抛出OutOfMemoryError异常。

需要注意的是，在当前的局部帧中，前面的局部帧创建的局部引用仍然是有效的。

jobject PopLocalFrame(JNIEnv *env, jobject result);
弹出当前的局部引用帧，释放所有的局部引用，返回在之前局部引用帧与给定result对象对应的局部引用。

如不需要返回任何引用，设置result为NULL

jobject NewLocalRef(JNIEnv *env, jobject ref);
创建一个引用自同个对象ref的局部引用。给定的ref可以是全局或者局部引用。如果ref为NULL，返回NULL。

5、弱全局引用
弱全局引用是一种特殊的全局引用，不像一般的全局引用，一个弱全局引用允许底层Java对象能够被垃圾回收。弱全局引用能够应用在任何全局或局部引用被使用的地方。当垃圾回收器运行的时候，如果对象只被弱引用所引用时，它将释放底层变量。一个弱全局引用指向一个被释放的对象相当于NULL。编程人员可以通过使用IsSameObject 对比弱引用和NULL来检测一个弱全局引用是否指向一个被释放的对象。
弱全局引用在JNI中是JAVA弱引用的一个简化版本，在JAVA2平台API中有效。

当本地方法正在运行时，垃圾回收器可能在工作，被弱全局引用所指向的对象可能在任何时候被释放。弱全局引用能够应用在任何全局引用所使用的地方，通常是不太适合那么做的，因为它们可能在不注意的时候变成NULL。

当IsSameObject 能够用来识别一个弱全局引用是不是指向一个被释放的对象，这并不阻止对象在被检测之后马上被释放。这就导致了，编程人员可能不依赖这个方法来识别一个弱全局引用是否能够在后续的JNI函数调用中被使用。

为了解决这个内在的限制，建议通过使用JNI函数NewLocalRef 或者 NewGlobalRef来用标准的（强）全局或局部引用指向相同的对象。如果这个对象已经被释放了这些函数会返回NULL。否则会返回一个强引用（这会确保对象不会被释放）。当不需要访问该对象时，新的引用必须显式被删除。

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);
创建一个新的弱全局引用。如果obj指向NULL，则返回NULL。如果VM内存溢出，将会抛出异常OutOfMemoryError。

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);
VM根据所给定的弱全局引用删除对应的资源