JNI异常处理 ⭐⭐

// Java 侧：一个会抛出异常的方法
public class DataParser {
    // 当输入为 null 时会抛出 NullPointerException
    public int parse(String input) {
        return Integer.parseInt(input); // 若 input 非法，抛 NumberFormatException
    }
}

// Native 侧：调用上述 Java 方法
extern "C" JNIEXPORT void JNICALL
Java_com_example_DataParser_nativeProcess(JNIEnv *env, jobject thiz) {
 
    // 获取 DataParser 类的 Class 引用
    jclass clazz = env->GetObjectClass(thiz);
 
    // 获取 parse 方法的 ID：方法名 "parse"，签名 "(Ljava/lang/String;)I"
    jmethodID parseMethod = env->GetMethodID(clazz, "parse", "(Ljava/lang/String;)I");
 
    // 构造一个非法字符串 "abc"，它无法被 parseInt 解析
    jstring badInput = env->NewStringUTF("abc");
 
    // 调用 Java 的 parse("abc")，此处会触发 NumberFormatException
    jint result = env->CallIntMethod(thiz, parseMethod, badInput);
 
    // ⚠️ 关键：虽然上一行已经触发了 Java 异常，
    // 但这一行代码仍然会被执行！C/C++ 不会自动中断！
    // 此时 result 的值是未定义的（通常为 0）
    printf("result = %d\n", result);  // 这行仍然会执行
 
    // 如果继续调用其他 JNI 函数（非异常处理类），行为是未定义的！
    // env->CallVoidMethod(thiz, someOtherMethod);  // ❌ 危险！
}

✅ 允许调用的 JNI 函数（异常状态下）：
┌──────────────────────────────────────────────┐
│  ExceptionCheck()      — 检查是否有待处理异常  │
│  ExceptionOccurred()   — 获取异常对象引用      │
│  ExceptionDescribe()   — 打印异常堆栈到 stderr │
│  ExceptionClear()      — 清除待处理异常        │
│  DeleteLocalRef()      — 删除本地引用          │
│  DeleteGlobalRef()     — 删除全局引用          │
│  MonitorExit()         — 退出同步监视器        │
│  ReleaseStringChars()  — 释放字符串字符资源     │
│  ReleaseStringUTFChars()                      │
│  ReleasePrimitiveArrayCritical()              │
│  ReleaseStringCritical()                      │
└──────────────────────────────────────────────┘

// ❌ 错误示例：连续调用 JNI 函数却不检查异常
extern "C" JNIEXPORT jstring JNICALL
Java_com_example_Demo_nativeBadExample(JNIEnv *env, jobject thiz) {
 
    // 第 1 步：查找一个不存在的类 —— 会触发 NoClassDefFoundError
    jclass clazz = env->FindClass("com/example/NonExistent");
    // 此时 clazz == NULL，且 pending exception 已设置
 
    // 第 2 步：用 NULL 的 clazz 继续获取方法 ID —— 未定义行为！
    jmethodID mid = env->GetMethodID(clazz, "foo", "()V");
    // 💥 此处可能直接导致 JVM 崩溃（segfault）
 
    // 第 3 步：即使没崩溃，继续调用也是错上加错
    env->CallVoidMethod(thiz, mid);
 
    // 返回一个字符串（但已经不可能正常到达这里了）
    return env->NewStringUTF("done");
}

// ✅ 正确思路：每个可能失败的 JNI 调用后都检查异常
extern "C" JNIEXPORT jstring JNICALL
Java_com_example_Demo_nativeGoodExample(JNIEnv *env, jobject thiz) {
 
    // 第 1 步：查找类
    jclass clazz = env->FindClass("com/example/NonExistent");
    // 立即检查：如果失败，提前返回，让异常传播回 Java
    if (clazz == NULL) {
        // pending exception 已存在，直接 return 即可
        // JVM 回到 Java 层后会自动抛出 NoClassDefFoundError
        return NULL;
    }
 
    // 第 2 步：安全地获取方法 ID（此时 clazz 一定有效）
    jmethodID mid = env->GetMethodID(clazz, "foo", "()V");
    // 再次检查
    if (mid == NULL) {
        return NULL; // NoSuchMethodError 会传播回 Java
    }
 
    // 第 3 步：安全调用
    env->CallVoidMethod(thiz, mid);
    // 检查调用是否触发了异常
    if (env->ExceptionCheck()) {
        return NULL; // 异常传播回 Java
    }
 
    // 一切正常，返回结果
    return env->NewStringUTF("done");
}

// Java 层：一个可能抛出异常的方法
public class DataProcessor {
    // 当 index 越界时，此方法会抛出 ArrayIndexOutOfBoundsException
    public int getElement(int[] array, int index) {
        return array[index]; // 越界时自动抛出异常
    }
}

// Native 层：调用 Java 方法但没有做异常检查（错误示范）
extern "C" JNIEXPORT void JNICALL
Java_com_example_NativeLib_process(JNIEnv *env, jobject thiz) {
 
    // 获取 DataProcessor 类引用
    jclass cls = env->FindClass("com/example/DataProcessor");
 
    // 获取 getElement 方法ID
    jmethodID mid = env->GetMethodID(cls, "getElement", "([II)I");
 
    // 构造一个长度为3的 int 数组
    jintArray arr = env->NewIntArray(3);
 
    // 创建 DataProcessor 实例
    jmethodID constructor = env->GetMethodID(cls, "<init>", "()V");
    jobject obj = env->NewObject(cls, constructor);
 
    // ⚠️ 故意传入越界索引 99，Java 层会抛出异常
    jint result = env->CallIntMethod(obj, mid, arr, 99);
 
    // ❌ 危险！此处代码会继续执行，result 的值是未定义的
    // JVM 内部已经有一个 pending exception，但 C++ 毫不知情
    printf("result = %d\n", result);  // 输出垃圾值
 
    // ❌ 如果继续调用其他 JNI 函数，行为未定义，可能导致 JVM 崩溃
    jstring str = env->NewStringUTF("hello");  // 在有 pending exception 时调用，非常危险
}

// JNI 函数签名
jboolean ExceptionCheck(JNIEnv *env);
// 返回值：JNI_TRUE (1) 表示有 pending exception
//         JNI_FALSE (0) 表示没有异常

extern "C" JNIEXPORT void JNICALL
Java_com_example_NativeLib_safeProcess(JNIEnv *env, jobject thiz) {
 
    // 获取类引用
    jclass cls = env->FindClass("com/example/DataProcessor");
 
    // 检查 FindClass 是否成功（类不存在时会产生异常）
    if (env->ExceptionCheck()) {
        // 发现异常，提前返回，让异常自然传播回 Java 层
        return;
    }
 
    // 获取方法ID
    jmethodID mid = env->GetMethodID(cls, "getElement", "([II)I");
 
    // 检查 GetMethodID 是否成功（方法不存在时会产生异常）
    if (env->ExceptionCheck()) {
        return; // 方法签名错误或方法不存在
    }
 
    // 创建数组和对象（省略部分代码...）
    jmethodID ctor = env->GetMethodID(cls, "<init>", "()V");
    jobject obj = env->NewObject(cls, ctor);
    jintArray arr = env->NewIntArray(3);
 
    // 调用可能抛出异常的 Java 方法
    jint result = env->CallIntMethod(obj, mid, arr, 99);
 
    // ✅ 关键：立即检查是否有异常
    if (env->ExceptionCheck()) {
        // 有异常发生！不要使用 result 的值
        // 此处可以选择：
        //   1. 直接 return，让异常传播回 Java
        //   2. 调用 ExceptionClear() 清除异常，然后做自定义处理
        return;
    }
 
    // 只有在没有异常时才安全使用 result
    printf("result = %d\n", result);
}

// JNI 函数签名
jthrowable ExceptionOccurred(JNIEnv *env);
// 返回值：如果有 pending exception，返回该异常对象的 local reference
//         如果没有异常，返回 NULL

extern "C" JNIEXPORT void JNICALL
Java_com_example_NativeLib_detailedProcess(JNIEnv *env, jobject thiz) {
 
    jclass cls = env->FindClass("com/example/DataProcessor");
    jmethodID mid = env->GetMethodID(cls, "getElement", "([II)I");
    jmethodID ctor = env->GetMethodID(cls, "<init>", "()V");
    jobject obj = env->NewObject(cls, ctor);
    jintArray arr = env->NewIntArray(3);
 
    // 调用可能抛出异常的方法
    jint result = env->CallIntMethod(obj, mid, arr, 99);
 
    // ✅ 使用 ExceptionOccurred 获取异常对象
    jthrowable exception = env->ExceptionOccurred();
 
    // 判断是否有异常（非 NULL 表示有异常）
    if (exception != NULL) {
 
        // ⚠️ 重要：在操作异常对象之前，必须先清除 pending 状态
        // 否则后续的 JNI 调用（如 GetObjectClass）行为未定义
        env->ExceptionClear();
 
        // 现在可以安全地分析这个异常对象了
        jclass exceptionClass = env->GetObjectClass(exception);
 
        // 获取异常类的名称
        jclass classClass = env->FindClass("java/lang/Class");
        jmethodID getNameMid = env->GetMethodID(classClass, "getName", "()Ljava/lang/String;");
        jstring className = (jstring) env->CallObjectMethod(exceptionClass, getNameMid);
 
        // 将 jstring 转换为 C 字符串以便打印
        const char *classNameStr = env->GetStringUTFChars(className, NULL);
 
        // 打印异常类型名称
        printf("Caught exception: %s\n", classNameStr);
        // 输出：Caught exception: java.lang.ArrayIndexOutOfBoundsException
 
        // 释放字符串资源
        env->ReleaseStringUTFChars(className, classNameStr);
 
        // 释放本地引用（良好习惯）
        env->DeleteLocalRef(exception);
        env->DeleteLocalRef(exceptionClass);
        env->DeleteLocalRef(classClass);
        env->DeleteLocalRef(className);
 
        // 异常已被处理，不会传播回 Java 层
        return;
    }
 
    // 无异常，安全使用结果
    printf("result = %d\n", result);
}

// 1. 所有 Call*Method 系列 —— 调用的 Java 方法可能抛出任何异常
env->CallVoidMethod(obj, mid);           // ← 必须检查
env->CallIntMethod(obj, mid);            // ← 必须检查
env->CallObjectMethod(obj, mid);         // ← 必须检查
env->CallStaticVoidMethod(cls, mid);     // ← 必须检查
 
// 2. 类/方法/字段查找 —— 找不到时会抛出 NoSuchMethodError 等
env->FindClass("com/example/Foo");       // ← 必须检查
env->GetMethodID(cls, "bar", "()V");     // ← 必须检查
env->GetFieldID(cls, "count", "I");      // ← 必须检查
 
// 3. 对象创建 —— 构造函数可能抛出异常，或内存不足
env->NewObject(cls, ctor);              // ← 必须检查
env->NewStringUTF("hello");             // ← 必须检查（OutOfMemoryError）
 
// 4. 数组访问 —— 可能越界
env->GetIntArrayRegion(arr, 0, len, buf); // ← 必须检查
 
// 5. Monitor 操作 —— 可能失败
env->MonitorEnter(obj);                  // ← 必须检查
env->MonitorExit(obj);                   // ← 必须检查

// 1. 引用管理函数
env->NewLocalRef(obj);          // ✅ 安全，无需检查
env->DeleteLocalRef(obj);       // ✅ 安全
env->NewGlobalRef(obj);         // ✅ 返回 NULL 表示失败，但不抛异常
env->DeleteGlobalRef(gref);     // ✅ 安全
 
// 2. 异常处理函数自身
env->ExceptionCheck();          // ✅ 安全
env->ExceptionOccurred();       // ✅ 安全
env->ExceptionClear();          // ✅ 安全
env->ExceptionDescribe();       // ✅ 安全
 
// 3. 基本类型的直接访问
env->GetArrayLength(arr);       // ✅ 安全
env->GetStringUTFLength(str);   // ✅ 安全
 
// 4. 版本查询
env->GetVersion();              // ✅ 安全

// ===== jni_utils.h =====
 
// 宏定义：检查异常并在发现异常时跳转到 error 标签
// 适用于需要统一资源清理的函数
#define JNI_CHECK_EXCEPTION_GOTO(env, label) \
    do { \
        if ((env)->ExceptionCheck()) { \
            goto label; \
        } \
    } while(0)
 
// 宏定义：检查异常并直接返回指定值
// 适用于简单的提前返回场景
#define JNI_CHECK_EXCEPTION_RETURN(env, retval) \
    do { \
        if ((env)->ExceptionCheck()) { \
            return (retval); \
        } \
    } while(0)
 
// 宏定义：检查异常并返回 void
#define JNI_CHECK_EXCEPTION_RETURN_VOID(env) \
    do { \
        if ((env)->ExceptionCheck()) { \
            return; \
        } \
    } while(0)

extern "C" JNIEXPORT jstring JNICALL
Java_com_example_NativeLib_getUserInfo(JNIEnv *env, jobject thiz, jint userId) {
 
    // 查找 UserService 类
    jclass cls = env->FindClass("com/example/UserService");
    JNI_CHECK_EXCEPTION_RETURN(env, NULL);  // 异常时返回 NULL
 
    // 获取静态方法 getUserName 的 ID
    jmethodID mid = env->GetStaticMethodID(cls, "getUserName",
                                            "(I)Ljava/lang/String;");
    JNI_CHECK_EXCEPTION_RETURN(env, NULL);  // 异常时返回 NULL
 
    // 调用 Java 静态方法
    jstring name = (jstring) env->CallStaticObjectMethod(cls, mid, userId);
    JNI_CHECK_EXCEPTION_RETURN(env, NULL);  // 异常时返回 NULL
 
    // 一切正常，返回结果
    return name;
}

extern "C" JNIEXPORT void JNICALL
Java_com_example_NativeLib_processFile(JNIEnv *env, jobject thiz, jstring path) {
 
    // 声明所有需要清理的资源
    const char *nativePath = NULL;    // 需要 ReleaseStringUTFChars
    jclass cls = NULL;                // local reference
    FILE *file = NULL;                // 需要 fclose
 
    // 将 Java 字符串转换为 C 字符串
    nativePath = env->GetStringUTFChars(path, NULL);
    if (nativePath == NULL) {
        // GetStringUTFChars 返回 NULL 说明内存分配失败（有 pending OOM）
        goto cleanup;
    }
 
    // 打开本地文件
    file = fopen(nativePath, "r");
    if (file == NULL) {
        // 文件打开失败，抛出 Java 异常（ThrowNew 将在后续章节讲解）
        jclass ioExCls = env->FindClass("java/io/IOException");
        env->ThrowNew(ioExCls, "Failed to open file");
        goto cleanup;
    }
 
    // 查找处理类
    cls = env->FindClass("com/example/FileProcessor");
    JNI_CHECK_EXCEPTION_GOTO(env, cleanup);  // 异常时跳转清理
 
    // ... 更多业务逻辑 ...
 
cleanup:
    // ✅ 统一资源清理，无论是否发生异常都会执行
    if (nativePath != NULL) {
        env->ReleaseStringUTFChars(path, nativePath);  // 释放字符串
    }
    if (file != NULL) {
        fclose(file);  // 关闭文件句柄
    }
    // local reference (cls) 会在函数返回时自动释放
}

// ❌ 错误：FindClass 可能失败，cls 为 NULL 且有 pending exception
jclass cls = env->FindClass("com/nonexistent/Class");
// 直接用 cls 调用 GetMethodID，此时 cls 是 NULL，行为未定义
jmethodID mid = env->GetMethodID(cls, "foo", "()V");  // 💥 crash!

// ⚠️ 在循环中反复调用 ExceptionOccurred 却不释放引用
for (int i = 0; i < 1000; i++) {
    env->CallVoidMethod(obj, mid, i);
 
    // 每次调用都创建一个 local reference
    jthrowable ex = env->ExceptionOccurred();  // 可能创建 local ref
    if (ex != NULL) {
        env->ExceptionClear();
        env->DeleteLocalRef(ex);  // ✅ 必须释放！否则 local ref table 溢出
        continue;
    }
    // 即使 ex == NULL，ExceptionOccurred 在无异常时不创建引用，这是安全的
}

// ❌ 错误：把 ExceptionCheck 的返回值当对象用
jthrowable ex = (jthrowable) env->ExceptionCheck();  // 编译可能通过但逻辑完全错误！
 
// ❌ 错误：把 ExceptionOccurred 的返回值当布尔值直接比较
if (env->ExceptionOccurred() == JNI_TRUE) {  // 类型不匹配！
    // ...
}
 
// ✅ 正确用法
if (env->ExceptionCheck()) { /* ... */ }            // 布尔判断
jthrowable ex = env->ExceptionOccurred();            // 对象判断
if (ex != NULL) { /* ... */ }

env->CallVoidMethod(obj, mid);
jclass cls = env->FindClass("java/lang/String");
jmethodID toStringMid = env->GetMethodID(cls, "toString", "()Ljava/lang/String;");

// JNI 函数签名
// 功能：清除当前线程上的 pending exception
// 调用后，线程恢复到"无异常"状态，后续 JNI 调用可正常执行
void ExceptionClear(JNIEnv *env);

// ✅ 异常挂起期间允许调用的 JNI 函数（安全列表）
ExceptionCheck()          // 检查异常是否存在
ExceptionOccurred()       // 获取异常对象引用
ExceptionDescribe()       // 将异常堆栈打印到 stderr
ExceptionClear()          // 清除异常
DeleteLocalRef()          // 释放本地引用
DeleteGlobalRef()         // 释放全局引用
MonitorExit()             // 释放监视器锁（如果之前进入了的话）
ReleaseStringChars()      // 释放字符串资源
ReleaseStringUTFChars()   // 释放 UTF 字符串资源
ReleasePrimitiveArrayCritical() // 释放数组关键区资源
ReleaseStringCritical()   // 释放字符串关键区资源

// native 方法：安全地读取 Java 对象的某个字段值
jint safeGetFieldValue(JNIEnv *env, jobject obj) {
 
    // 获取类引用
    jclass cls = (*env)->GetObjectClass(env, obj);
 
    // 获取方法 ID：getValue()
    jmethodID mid = (*env)->GetMethodID(env, cls, "getValue", "()I");
 
    // 调用 Java 方法——这里可能抛出异常
    // 例如 getValue() 内部可能抛出 IllegalStateException
    jint result = (*env)->CallIntMethod(env, obj, mid);
 
    // 🔍 关键步骤：检查是否有 pending exception
    if ((*env)->ExceptionCheck(env)) {
 
        // 📝 可选：打印异常信息到 stderr，方便调试
        (*env)->ExceptionDescribe(env);
 
        // ✅ 清除异常——从此刻起，JNI 调用恢复正常
        (*env)->ExceptionClear(env);
 
        // 🔧 本地处理：返回一个默认的错误值
        // 调用者通过返回值判断是否出错
        return -1;
    }
 
    // 正常路径：返回实际值
    return result;
}

// 等价的 Java 代码
int safeGetFieldValue(MyObject obj) {
    try {
        return obj.getValue();          // 可能抛异常
    } catch (Exception e) {
        e.printStackTrace();            // ExceptionDescribe
        return -1;                      // 返回默认错误值
    }
}

// native 方法：将底层异常转换为自定义异常
void processData(JNIEnv *env, jobject obj, jbyteArray data) {
 
    // 获取类和方法
    jclass cls = (*env)->GetObjectClass(env, obj);
    jmethodID mid = (*env)->GetMethodID(env, cls, "parseInternal", "([B)V");
 
    // 调用 Java 的 parseInternal 方法
    (*env)->CallVoidMethod(env, obj, mid, data);
 
    // 检查是否发生了异常
    if ((*env)->ExceptionCheck(env)) {
 
        // 获取异常对象（用于提取信息）
        jthrowable originalException = (*env)->ExceptionOccurred(env);
 
        // ⚠️ 必须先清除异常！否则无法调用后续 JNI 函数
        (*env)->ExceptionClear(env);
 
        // --- 此时线程已无 pending exception，可自由调用 JNI ---
 
        // 从原始异常中提取 message
        jclass throwableCls = (*env)->FindClass(env, "java/lang/Throwable");
        jmethodID getMsgMid = (*env)->GetMethodID(
            env, throwableCls, "getMessage", "()Ljava/lang/String;");
        jstring msgObj = (jstring)(*env)->CallObjectMethod(
            env, originalException, getMsgMid);
 
        // 将 jstring 转为 C 字符串
        const char *msgChars = (*env)->GetStringUTFChars(env, msgObj, NULL);
 
        // 构造新的错误信息
        char buffer[256];
        snprintf(buffer, sizeof(buffer),
                 "Data processing failed: %s", msgChars); // 拼接错误信息
 
        // 释放字符串资源
        (*env)->ReleaseStringUTFChars(env, msgObj, msgChars);
 
        // 抛出一个新的自定义异常（异常转换完成）
        jclass customExCls = (*env)->FindClass(
            env, "com/example/DataProcessingException");
        (*env)->ThrowNew(env, customExCls, buffer);
 
        // 释放本地引用
        (*env)->DeleteLocalRef(env, originalException);
        (*env)->DeleteLocalRef(env, msgObj);
        (*env)->DeleteLocalRef(env, throwableCls);
        (*env)->DeleteLocalRef(env, customExCls);
 
        // 函数返回后，Java 层将收到 DataProcessingException
        return;
    }
 
    // 正常逻辑继续...
}

// ❌ 错误示范：清除了异常，却假设后续操作一定成功
void riskyFunction(JNIEnv *env, jobject obj) {
 
    (*env)->CallVoidMethod(env, obj, someMethod);
 
    if ((*env)->ExceptionCheck(env)) {
        (*env)->ExceptionClear(env);  // 清除了第一个异常
    }
 
    // 危险！FindClass 自身也可能失败（如类不存在）
    // 必须对每一步都做异常/NULL 检查
    jclass cls = (*env)->FindClass(env, "com/nonexistent/MyClass");
    // cls 可能为 NULL，且可能又产生了新的 pending exception
 
    jmethodID mid = (*env)->GetMethodID(env, cls, "foo", "()V");
    // 如果 cls == NULL，这里将直接崩溃（JVM crash）！
}

// ✅ 正确示范：每一步都做防御性检查
void safeFunction(JNIEnv *env, jobject obj) {
 
    (*env)->CallVoidMethod(env, obj, someMethod);
 
    // 第一次检查
    if ((*env)->ExceptionCheck(env)) {
        (*env)->ExceptionClear(env);
        // 记录日志或做相应处理
    }
 
    // FindClass 后立刻检查
    jclass cls = (*env)->FindClass(env, "com/example/MyClass");
    if (cls == NULL) {
        // FindClass 失败时会自动设置 pending exception
        // 可以选择清除并处理，或直接返回让 Java 层捕获
        return;
    }
 
    // GetMethodID 后也要检查
    jmethodID mid = (*env)->GetMethodID(env, cls, "foo", "()V");
    if (mid == NULL) {
        return; // NoSuchMethodError 已被挂起
    }
 
    // 一切就绪，安全调用
    (*env)->CallVoidMethod(env, obj, mid);
}

// ❌ 错误：pending exception 存在时直接 ThrowNew
void badExceptionSwap(JNIEnv *env, jobject obj) {
 
    (*env)->CallVoidMethod(env, obj, riskyMethod);
 
    if ((*env)->ExceptionCheck(env)) {
        // 没有调用 ExceptionClear！
        // 此时 pending exception 仍然存在
 
        jclass exCls = (*env)->FindClass(env, "java/lang/RuntimeException");
        // ⚠️ FindClass 在 pending exception 下行为未定义
 
        (*env)->ThrowNew(env, exCls, "new error");
        // ⚠️ ThrowNew 在已有 pending exception 时的行为也未定义
        // 不同 JVM 表现不同：可能覆盖、可能忽略、可能崩溃
    }
}

// ExceptionDescribe 的隐含行为（不同 JVM 实现可能不同）
void debugAndClear(JNIEnv *env) {
 
    if ((*env)->ExceptionCheck(env)) {
 
        // 打印异常堆栈到 stderr
        // ⚠️ 注意：某些 JVM 实现中，ExceptionDescribe 会自动清除异常
        // 但 JNI 规范并未保证这一点！
        (*env)->ExceptionDescribe(env);
 
        // ✅ 最佳实践：总是显式调用 ExceptionClear
        // 即使 ExceptionDescribe 可能已经清除了，再调用一次也是安全的
        // （对已经无异常的线程调用 ExceptionClear 不会产生副作用）
        (*env)->ExceptionClear(env);
    }
}

// ====== JVM 内部线程结构（简化概念模型）======
//
// ┌─────────────────────────────────────────┐
// │           JavaThread (线程对象)           │
// ├─────────────────────────────────────────┤
// │  JNIEnv* env          →  JNI 函数表指针  │
// │  oop pending_exception → NULL (无异常)   │  ← ExceptionClear 将此置为 NULL
// │  oop pending_exception → ExceptionObj   │  ← 异常挂起时指向异常对象
// │  ...                                     │
// └─────────────────────────────────────────┘
//
// ExceptionClear 的伪代码实现：
// void JNIEnv::ExceptionClear() {
//     Thread* current = Thread::current();
//     current->set_pending_exception(NULL);  // 简单地将指针置空
// }

(*env)->CallVoidMethod(env, obj, mid);
jclass cls = (*env)->FindClass(env, "java/lang/RuntimeException");
(*env)->ThrowNew(env, cls, "error");

(*env)->CallVoidMethod(env, obj, mid);
if ((*env)->ExceptionCheck(env)) {
    (*env)->ExceptionClear(env);
}

(*env)->CallVoidMethod(env, obj, mid);
if ((*env)->ExceptionCheck(env)) {
    (*env)->ExceptionDescribe(env);
    (*env)->ExceptionClear(env);
    jclass cls = (*env)->FindClass(env, "com/example/MyException");
    if (cls != NULL) {
        (*env)->ThrowNew(env, cls, "Wrapped error");
    }
    return;
}

(*env)->CallVoidMethod(env, obj, mid);
(*env)->ExceptionClear(env);
(*env)->ExceptionDescribe(env);

/*
 * 参数说明：
 *   env    - JNI 环境指针，所有 JNI 调用的入口
 *   clazz  - 要抛出的异常类的 jclass 引用（必须是 Throwable 的子类）
 *   message - 异常携带的描述信息（UTF-8 编码的 C 字符串）
 *
 * 返回值：
 *   0      - 成功（异常已被挂起到当前线程）
 *   负数    - 失败（通常因为找不到对应的构造函数）
 */
jint ThrowNew(JNIEnv *env, jclass clazz, const char *message);

public class FileProcessor {
 
    // 加载本地库
    static {
        System.loadLibrary("fileprocessor"); // 加载 libfileprocessor.so
    }
 
    // native 方法：处理指定路径的文件
    public native void processFile(String filePath);
 
    public static void main(String[] args) {
        FileProcessor processor = new FileProcessor(); // 创建实例
        try {
            processor.processFile(null); // 故意传 null 触发异常
        } catch (IllegalArgumentException e) {
            // 捕获从 Native 层抛出的异常
            System.out.println("捕获异常: " + e.getMessage());
        }
    }
}

#include <jni.h>        // JNI 核心头文件
#include <stdio.h>      // 标准 I/O
#include <string.h>     // 字符串操作
 
/**
 * 对应 Java 方法: FileProcessor.processFile(String)
 * 参数:
 *   env      - JNI 环境指针
 *   thiz     - 调用该方法的 Java 对象 (this)
 *   filePath - Java 传入的文件路径字符串
 */
JNIEXPORT void JNICALL
Java_FileProcessor_processFile(JNIEnv *env, jobject thiz, jstring filePath) {
 
    // ========== 第一步：参数校验 ==========
 
    // 检查 filePath 是否为 null
    if (filePath == NULL) {
        // 查找 IllegalArgumentException 类
        jclass exClass = (*env)->FindClass(env, "java/lang/IllegalArgumentException");
        // FindClass 可能失败（类不存在），但标准异常类一定存在，此处简化处理
        if (exClass != NULL) {
            // 抛出异常，附带错误消息
            (*env)->ThrowNew(env, exClass, "filePath must not be null");
            // 释放局部引用（良好习惯，虽然函数即将返回）
            (*env)->DeleteLocalRef(env, exClass);
        }
        // ⚠️ 关键：必须显式 return！ThrowNew 不会中断 C 代码执行
        return;
    }
 
    // ========== 第二步：获取 C 字符串 ==========
 
    // 将 Java String 转换为 C 风格的 UTF-8 字符串
    const char *path = (*env)->GetStringUTFChars(env, filePath, NULL);
    // 检查转换是否成功（内存不足时可能返回 NULL）
    if (path == NULL) {
        // GetStringUTFChars 失败时 JVM 已自动抛出 OutOfMemoryError
        // 无需手动抛出，直接返回即可
        return;
    }
 
    // ========== 第三步：业务逻辑 ==========
 
    printf("Processing file: %s\n", path); // 模拟文件处理
 
    // ========== 第四步：释放资源 ==========
 
    // 释放 GetStringUTFChars 分配的内存，防止内存泄漏
    (*env)->ReleaseStringUTFChars(env, filePath, path);
}

/*
 * 参数说明：
 *   env - JNI 环境指针
 *   obj - 一个已存在的 Throwable 对象引用
 *
 * 返回值：
 *   0    - 成功
 *   负数  - 失败
 */
jint Throw(JNIEnv *env, jthrowable obj);

/**
 * 辅助函数：抛出带 cause 的异常
 * 参数:
 *   env       - JNI 环境指针
 *   className - 异常类的全限定名（用 '/' 分隔）
 *   message   - 错误描述
 *   cause     - 原始异常（可为 NULL）
 */
void throwChainedException(JNIEnv *env,
                           const char *className,
                           const char *message,
                           jthrowable cause) {
 
    // 查找目标异常类
    jclass exClass = (*env)->FindClass(env, className);
    if (exClass == NULL) {
        return; // FindClass 失败，JVM 已挂起 NoClassDefFoundError
    }
 
    // 查找构造函数: ExceptionClass(String message, Throwable cause)
    // 签名 "(Ljava/lang/String;Ljava/lang/Throwable;)V" 对应两个参数的构造器
    jmethodID constructor = (*env)->GetMethodID(
        env,
        exClass,
        "<init>",                                          // 构造函数在 JNI 中的名称
        "(Ljava/lang/String;Ljava/lang/Throwable;)V"      // 方法签名
    );
    if (constructor == NULL) {
        (*env)->DeleteLocalRef(env, exClass);  // 清理局部引用
        return; // GetMethodID 失败，JVM 已挂起 NoSuchMethodError
    }
 
    // 创建 Java 字符串作为 message 参数
    jstring jMessage = (*env)->NewStringUTF(env, message);
    if (jMessage == NULL) {
        (*env)->DeleteLocalRef(env, exClass);  // 清理局部引用
        return; // 内存不足，JVM 已挂起 OutOfMemoryError
    }
 
    // 调用构造函数创建异常对象实例
    jthrowable exObj = (jthrowable)(*env)->NewObject(
        env,
        exClass,
        constructor,
        jMessage,   // 第一个参数: String message
        cause       // 第二个参数: Throwable cause
    );
 
    if (exObj != NULL) {
        // 使用 Throw 抛出已构造好的异常对象
        (*env)->Throw(env, exObj);
        (*env)->DeleteLocalRef(env, exObj);    // 清理局部引用
    }
 
    // 清理所有局部引用
    (*env)->DeleteLocalRef(env, jMessage);
    (*env)->DeleteLocalRef(env, exClass);
}

#include <jni.h>   // JNI 核心头文件
 
// ===================== 异常抛出工具函数集 =====================
 
/**
 * 通用异常抛出函数
 * 参数:
 *   env       - JNI 环境指针
 *   className - 异常类全限定名 (使用 '/' 而非 '.')
 *   message   - 错误描述信息
 * 返回值:
 *   0 表示成功，-1 表示失败
 */
static int throwException(JNIEnv *env, const char *className, const char *message) {
    // 查找异常类
    jclass exClass = (*env)->FindClass(env, className);
    if (exClass == NULL) {
        // 如果连异常类都找不到，说明情况很严重
        // FindClass 失败会自动挂起 NoClassDefFoundError
        return -1;
    }
    // 调用 ThrowNew 抛出异常
    int result = (*env)->ThrowNew(env, exClass, message);
    // 删除局部引用，避免引用表溢出
    (*env)->DeleteLocalRef(env, exClass);
    // 返回结果（0=成功）
    return result;
}
 
/**
 * 抛出 IllegalArgumentException
 * 最常用的参数校验异常
 */
static int throwIllegalArgumentException(JNIEnv *env, const char *message) {
    return throwException(env, "java/lang/IllegalArgumentException", message);
}
 
/**
 * 抛出 IllegalStateException
 * 用于对象状态不正确的场景（如资源已关闭后再次操作）
 */
static int throwIllegalStateException(JNIEnv *env, const char *message) {
    return throwException(env, "java/lang/IllegalStateException", message);
}
 
/**
 * 抛出 IOException
 * 用于文件/网络等 I/O 操作失败
 */
static int throwIOException(JNIEnv *env, const char *message) {
    return throwException(env, "java/io/IOException", message);
}
 
/**
 * 抛出 RuntimeException
 * 用于不可恢复的运行时错误
 */
static int throwRuntimeException(JNIEnv *env, const char *message) {
    return throwException(env, "java/lang/RuntimeException", message);
}
 
/**
 * 抛出 NullPointerException
 * 用于必要参数为 null 的场景
 */
static int throwNullPointerException(JNIEnv *env, const char *message) {
    return throwException(env, "java/lang/NullPointerException", message);
}
 
/**
 * 抛出 UnsupportedOperationException
 * 用于功能未实现或不支持的场景
 */
static int throwUnsupportedOperationException(JNIEnv *env, const char *message) {
    return throwException(env, "java/lang/UnsupportedOperationException", message);
}

JNIEXPORT jbyteArray JNICALL
Java_FileProcessor_readFile(JNIEnv *env, jobject thiz, jstring filePath) {
 
    // ===== 参数校验 =====
    if (filePath == NULL) {
        // 一行代码完成异常抛出，代码简洁清晰
        throwNullPointerException(env, "filePath must not be null");
        return NULL; // ⚠️ 别忘了 return！
    }
 
    // 获取 C 字符串
    const char *path = (*env)->GetStringUTFChars(env, filePath, NULL);
    if (path == NULL) {
        return NULL; // OOM 已由 JVM 自动处理
    }
 
    // ===== 打开文件 =====
    FILE *file = fopen(path, "rb"); // 以二进制只读模式打开
    if (file == NULL) {
        // 文件打开失败，抛出 IOException，并附带具体路径信息
        char errorMsg[512];                                    // 错误消息缓冲区
        snprintf(errorMsg, sizeof(errorMsg),                   // 安全格式化
                 "Cannot open file: %s", path);
        throwIOException(env, errorMsg);                       // 抛出 IOException
        (*env)->ReleaseStringUTFChars(env, filePath, path);    // 释放字符串资源
        return NULL;                                           // 必须 return
    }
 
    // ===== 读取文件大小 =====
    fseek(file, 0, SEEK_END);         // 移动到文件末尾
    long fileSize = ftell(file);       // 获取当前位置（即文件大小）
    fseek(file, 0, SEEK_SET);         // 重置到文件开头
 
    // 校验文件大小（例如限制 100MB）
    if (fileSize > 100 * 1024 * 1024) {
        throwIllegalArgumentException(env, "File size exceeds 100MB limit");
        fclose(file);                                          // 关闭文件
        (*env)->ReleaseStringUTFChars(env, filePath, path);    // 释放字符串
        return NULL;                                           // 必须 return
    }
 
    // ===== 分配 byte 数组并读取 =====
    jbyteArray result = (*env)->NewByteArray(env, (jsize)fileSize);
    if (result == NULL) {
        fclose(file);                                          // 关闭文件
        (*env)->ReleaseStringUTFChars(env, filePath, path);    // 释放字符串
        return NULL; // NewByteArray 失败 JVM 自动抛出 OOM
    }
 
    // 获取 byte 数组的原始指针
    jbyte *buffer = (*env)->GetByteArrayElements(env, result, NULL);
    if (buffer == NULL) {
        fclose(file);
        (*env)->ReleaseStringUTFChars(env, filePath, path);
        return NULL; // OOM
    }
 
    // 一次性读取整个文件内容到缓冲区
    size_t bytesRead = fread(buffer, 1, (size_t)fileSize, file);
    if (bytesRead != (size_t)fileSize) {
        throwIOException(env, "Failed to read complete file");
        // 即使要抛异常，也必须先释放所有已获取的资源！
        (*env)->ReleaseByteArrayElements(env, result, buffer, JNI_ABORT);
        fclose(file);
        (*env)->ReleaseStringUTFChars(env, filePath, path);
        return NULL;
    }
 
    // ===== 清理资源 =====
    (*env)->ReleaseByteArrayElements(env, result, buffer, 0);  // 提交修改并释放
    fclose(file);                                               // 关闭文件句柄
    (*env)->ReleaseStringUTFChars(env, filePath, path);         // 释放字符串内存
 
    return result; // 返回包含文件内容的 byte 数组
}

JNIEXPORT void JNICALL
Java_Demo_dangerousMethod(JNIEnv *env, jobject thiz, jstring input) {
    if (input == NULL) {
        // 抛出异常
        throwNullPointerException(env, "input is null");
        // ⚠️ 没有 return！C 代码继续往下执行！
    }
 
    // 💥 当 input == NULL 时，下面这行会导致段错误 (SIGSEGV)
    // 因为 GetStringUTFChars 不允许传入 NULL
    const char *str = (*env)->GetStringUTFChars(env, input, NULL);
 
    // ... 后续操作
    (*env)->ReleaseStringUTFChars(env, input, str);
}

 input == NULL
      │
      ▼
 ThrowNew() ──→ 异常已挂起（Pending），但 C 代码不知道也不关心
      │
      ▼
 GetStringUTFChars(NULL) ──→ 💥 SIGSEGV / JVM Crash
      │
      ✖  程序崩溃，Java 层的 try-catch 根本没机会执行

JNIEXPORT void JNICALL
Java_Demo_safeMethod(JNIEnv *env, jobject thiz, jstring input) {
    // 参数校验：null 检查
    if (input == NULL) {
        throwNullPointerException(env, "input is null");
        return;  // ✅ 立即返回，阻止后续代码执行
    }
 
    // 此处 input 一定非 NULL，可以安全使用
    const char *str = (*env)->GetStringUTFChars(env, input, NULL);
    if (str == NULL) {
        return;  // ✅ OOM 已自动挂起，直接返回
    }
 
    printf("Input: %s\n", str); // 安全地使用字符串
 
    // 释放资源
    (*env)->ReleaseStringUTFChars(env, input, str);
    // 函数正常结束，无异常挂起
}

package com.example;
 
// 自定义业务异常
public class NativeProcessingException extends Exception {
 
    private int errorCode; // 错误码字段
 
    // ThrowNew 需要的构造函数（接受 String 参数）
    public NativeProcessingException(String message) {
        super(message);       // 调用父类构造器
        this.errorCode = -1;  // 默认错误码
    }
 
    // 带错误码的构造函数（ThrowNew 无法直接使用，需要用 Throw）
    public NativeProcessingException(String message, int errorCode) {
        super(message);              // 调用父类构造器
        this.errorCode = errorCode;  // 设置错误码
    }
 
    public int getErrorCode() {
        return errorCode; // 获取错误码
    }
}

/**
 * 方式一：使用 ThrowNew（简单，但只能传 message）
 */
static void throwProcessingException(JNIEnv *env, const char *message) {
    // 注意：包名中的 '.' 要替换为 '/'
    jclass exClass = (*env)->FindClass(env, "com/example/NativeProcessingException");
    if (exClass != NULL) {
        (*env)->ThrowNew(env, exClass, message);       // 调用 String 构造器
        (*env)->DeleteLocalRef(env, exClass);           // 清理引用
    }
}
 
/**
 * 方式二：使用 Throw（复杂，但可以传 errorCode）
 */
static void throwProcessingExceptionWithCode(JNIEnv *env,
                                              const char *message,
                                              int errorCode) {
    // 查找自定义异常类
    jclass exClass = (*env)->FindClass(env, "com/example/NativeProcessingException");
    if (exClass == NULL) return;  // 类找不到，JVM 已挂起异常
 
    // 查找 (String, int) 构造函数
    // 签名: (Ljava/lang/String;I)V  ← String + int + void 返回
    jmethodID ctor = (*env)->GetMethodID(
        env, exClass, "<init>", "(Ljava/lang/String;I)V"
    );
    if (ctor == NULL) {
        (*env)->DeleteLocalRef(env, exClass);
        return;  // 构造函数不存在
    }
 
    // 创建 Java 字符串
    jstring jMsg = (*env)->NewStringUTF(env, message);
    if (jMsg == NULL) {
        (*env)->DeleteLocalRef(env, exClass);
        return;  // OOM
    }
 
    // 调用构造函数，创建异常对象实例
    jthrowable exObj = (jthrowable)(*env)->NewObject(
        env, exClass, ctor, jMsg, (jint)errorCode
    );
    if (exObj != NULL) {
        (*env)->Throw(env, exObj);              // 抛出异常对象
        (*env)->DeleteLocalRef(env, exObj);     // 清理引用
    }
 
    // 清理局部引用
    (*env)->DeleteLocalRef(env, jMsg);
    (*env)->DeleteLocalRef(env, exClass);
}

/*
 * 参数：
 *   env - JNI 环境指针
 *   msg - 致命错误描述（会输出到 stderr）
 *
 * 注意：此函数不会返回！JVM 会直接终止进程。
 */
void FatalError(JNIEnv *env, const char *msg);

JNIEXPORT void JNICALL
Java_Demo_criticalInit(JNIEnv *env, jobject thiz) {
 
    // 分配关键的全局资源
    void *criticalResource = malloc(CRITICAL_SIZE);
    if (criticalResource == NULL) {
        // 关键资源分配失败，系统无法继续运行
        // 抛普通异常没有意义，因为上层即使 catch 了也无法恢复
        (*env)->FatalError(env,
            "FATAL: Cannot allocate critical resource. JVM must terminate.");
        // ⚠️ 代码永远不会执行到这里
    }
 
    // ... 正常初始化逻辑
}

JNIEXPORT jstring JNICALL
Java_Demo_processInput(JNIEnv *env, jobject thiz, jstring input) {
    if (input == NULL) {
        jclass exClass = (*env)->FindClass(env, "java/lang/NullPointerException");
        (*env)->ThrowNew(env, exClass, "input cannot be null");
        (*env)->DeleteLocalRef(env, exClass);
    }
    const char *str = (*env)->GetStringUTFChars(env, input, NULL);
    jstring result = (*env)->NewStringUTF(env, str);
    (*env)->ReleaseStringUTFChars(env, input, str);
    return result;
}

// ❌ 危险写法：连续调用，不做中间检查
JNIEXPORT void JNICALL Java_com_example_Demo_badExample(JNIEnv *env, jobject thiz) {
    // 假如这一步就找不到类，cls 为 NULL
    jclass cls = env->FindClass("com/example/NonExistent");
    // 用 NULL 的 cls 继续调用 → JVM 崩溃！
    jmethodID mid = env->GetMethodID(cls, "doSomething", "()V");
    // 即便侥幸没崩溃，这里也会产生不可预测的行为
    env->CallVoidMethod(thiz, mid);
}

// ✅ 正确写法：每步调用后都进行检查
JNIEXPORT void JNICALL Java_com_example_Demo_goodExample(JNIEnv *env, jobject thiz) {
    // 第一步：查找类
    jclass cls = env->FindClass("com/example/MyHelper");
    // 立即检查：FindClass 失败会返回 NULL 并设置 pending exception
    if (cls == NULL) {
        // 异常已由 JVM 设置（ClassNotFoundException），直接返回
        // 控制权交还 Java 层后，Java 会自动抛出该异常
        return;
    }
 
    // 第二步：获取方法 ID
    jmethodID mid = env->GetMethodID(cls, "process", "(I)V");
    // 立即检查：GetMethodID 失败会返回 NULL 并设置 pending exception
    if (mid == NULL) {
        return; // NoSuchMethodError 已挂起
    }
 
    // 第三步：调用 Java 方法
    env->CallVoidMethod(thiz, mid, 42);
    // 调用后检查：Java 方法内部可能抛出异常
    if (env->ExceptionCheck()) {
        // 根据业务需求决定：是直接返回让 Java 处理，还是在此清除并处理
        return;
    }
}

JNIEXPORT jint JNICALL Java_com_example_Parser_parseConfig(JNIEnv *env, jobject thiz, jstring path) {
    // 将 Java 字符串转为 C 字符串
    const char *nativePath = env->GetStringUTFChars(path, NULL);
    // 检查转换是否成功（内存不足时为 NULL）
    if (nativePath == NULL) {
        // OutOfMemoryError 已挂起 → 不可恢复，直接返回
        return -1;
    }
 
    // 调用 Java 层的文件读取方法
    jclass fileCls = env->FindClass("com/example/FileReader");
    if (fileCls == NULL) return -1; // ClassNotFoundException → 不可恢复
 
    jmethodID readMid = env->GetStaticMethodID(fileCls, "readAll", "(Ljava/lang/String;)Ljava/lang/String;");
    if (readMid == NULL) return -1; // NoSuchMethodError → 不可恢复
 
    jstring content = (jstring) env->CallStaticObjectMethod(fileCls, readMid, path);
 
    // 这里需要判断：Java 方法可能抛出 FileNotFoundException
    if (env->ExceptionCheck()) {
        // 获取异常对象以判断类型
        jthrowable ex = env->ExceptionOccurred();
        // 清除异常状态，以便后续调用 JNI 函数
        env->ExceptionClear();
 
        // 判断异常是否为 FileNotFoundException（可恢复）
        jclass fnfCls = env->FindClass("java/io/FileNotFoundException");
        if (fnfCls != NULL && env->IsInstanceOf(ex, fnfCls)) {
            // ✅ 可恢复：文件不存在，使用默认配置
            env->DeleteLocalRef(ex);       // 释放异常对象的本地引用
            env->DeleteLocalRef(fnfCls);   // 释放类引用
            env->ReleaseStringUTFChars(path, nativePath); // 释放字符串
            return 0; // 返回默认值，表示使用内置配置
        }
 
        // ❌ 其他异常不可恢复：重新抛出
        env->Throw(ex);                    // 将原始异常重新设为 pending
        env->DeleteLocalRef(fnfCls);       // 清理
        env->ReleaseStringUTFChars(path, nativePath);
        return -1;
    }
 
    // 正常路径：解析内容...
    env->ReleaseStringUTFChars(path, nativePath);
    return 1; // 解析成功
}

// =============================================
// jni_utils.h - JNI 异常处理工具集
// =============================================
 
#ifndef JNI_UTILS_H
#define JNI_UTILS_H
 
#include <jni.h>
#include <android/log.h>
 
// 日志输出宏
#define LOG_TAG "JNI_UTILS"
#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
 
/**
 * 检查是否有 pending exception，若有则打印并清除。
 * 返回值：JNI_TRUE 表示有异常被清除，JNI_FALSE 表示无异常。
 * 适用场景：异常可恢复，需要继续执行 Native 逻辑。
 */
static inline jboolean jni_check_and_clear_exception(JNIEnv *env) {
    // 检查当前是否有挂起的异常
    if (env->ExceptionCheck()) {
        // 将异常堆栈打印到 logcat（调试用）
        env->ExceptionDescribe();
        // 清除异常状态
        env->ExceptionClear();
        // 返回 true 表示确实有异常被处理
        return JNI_TRUE;
    }
    // 无异常
    return JNI_FALSE;
}
 
/**
 * 安全地查找类，找不到时返回 NULL。
 * 调用方需自行检查返回值。
 */
static inline jclass jni_find_class(JNIEnv *env, const char *className) {
    // 调用 FindClass
    jclass cls = env->FindClass(className);
    // 若失败，打印错误信息并清除异常
    if (cls == NULL) {
        LOGE("FindClass failed: %s", className);
        // 注意：这里选择"不清除"异常，让上层决定如何处理
        // 如果需要清除，可调用 jni_check_and_clear_exception(env);
    }
    return cls;
}
 
/**
 * 抛出指定类型的 Java 异常。
 * 封装了 FindClass + ThrowNew 的组合操作。
 * 返回值：0 表示成功，-1 表示抛出失败（极端情况）。
 */
static inline int jni_throw(JNIEnv *env, const char *exceptionClass, const char *message) {
    // 先查找异常类
    jclass cls = env->FindClass(exceptionClass);
    // 若异常类本身都找不到（极端情况），记录错误
    if (cls == NULL) {
        LOGE("Cannot find exception class: %s", exceptionClass);
        return -1; // FindClass 已设置 ClassNotFoundException
    }
    // 抛出异常
    int ret = env->ThrowNew(cls, message);
    // 释放本地引用
    env->DeleteLocalRef(cls);
    return ret;
}
 
/**
 * 便捷方法：抛出 IllegalArgumentException
 */
static inline int jni_throw_illegal_arg(JNIEnv *env, const char *message) {
    return jni_throw(env, "java/lang/IllegalArgumentException", message);
}
 
/**
 * 便捷方法：抛出 RuntimeException
 */
static inline int jni_throw_runtime(JNIEnv *env, const char *message) {
    return jni_throw(env, "java/lang/RuntimeException", message);
}
 
/**
 * 便捷方法：抛出 NullPointerException
 */
static inline int jni_throw_npe(JNIEnv *env, const char *message) {
    return jni_throw(env, "java/lang/NullPointerException", message);
}
 
#endif // JNI_UTILS_H

#include "jni_utils.h"
 
JNIEXPORT void JNICALL Java_com_example_Demo_processData(JNIEnv *env, jobject thiz, jbyteArray data) {
    // ① 参数校验：空指针防御
    if (data == NULL) {
        // 使用工具函数抛出 NullPointerException
        jni_throw_npe(env, "Input data array must not be null");
        return;
    }
 
    // ② 获取数组长度
    jsize len = env->GetArrayLength(data);
    // 业务校验：长度必须 > 0
    if (len <= 0) {
        jni_throw_illegal_arg(env, "Data array must not be empty");
        return;
    }
 
    // ③ 获取数组元素指针
    jbyte *buf = env->GetByteArrayElements(data, NULL);
    if (buf == NULL) {
        // OOM 已由 JVM 挂起，直接返回
        return;
    }
 
    // ④ 执行 Native 处理逻辑（如解码、加密等）
    int result = native_process(buf, len); // 假设这是一个纯 C 函数
 
    // ⑤ 释放数组元素（0 表示将修改拷贝回 Java 数组）
    env->ReleaseByteArrayElements(data, buf, 0);
 
    // ⑥ 根据 Native 结果决定是否抛异常
    if (result != 0) {
        jni_throw_runtime(env, "Native processing failed with error code");
        return;
    }
}

JNIEXPORT jstring JNICALL Java_com_example_Crypto_encrypt(
    JNIEnv *env, jobject thiz, jstring input, jbyteArray key) {
 
    // ======= 资源指针预初始化为 NULL =======
    const char *inputChars = NULL;    // 输入字符串的 C 指针
    jbyte *keyBytes = NULL;           // 密钥数组的 C 指针
    jstring result = NULL;            // 返回值
    char *outputBuf = NULL;           // Native 分配的输出缓冲区
 
    // ======= 参数校验 =======
    if (input == NULL || key == NULL) {
        jni_throw_npe(env, "Input and key must not be null");
        goto cleanup; // 跳到统一清理
    }
 
    // ======= 获取资源 =======
    // 获取输入字符串
    inputChars = env->GetStringUTFChars(input, NULL);
    if (inputChars == NULL) {
        goto cleanup; // OOM 已挂起
    }
 
    // 获取密钥字节
    keyBytes = env->GetByteArrayElements(key, NULL);
    if (keyBytes == NULL) {
        goto cleanup; // OOM 已挂起
    }
 
    // 获取密钥长度
    jsize keyLen = env->GetArrayLength(key);
 
    // ======= 核心业务逻辑 =======
    // 分配输出缓冲区（字符串长度 + 加密填充）
    size_t inputLen = strlen(inputChars);
    outputBuf = (char *) malloc(inputLen + 32); // 预留填充空间
    if (outputBuf == NULL) {
        jni_throw_runtime(env, "Failed to allocate output buffer");
        goto cleanup;
    }
 
    // 调用纯 C 加密函数
    int encryptResult = do_encrypt(
        (const unsigned char *) inputChars, inputLen,
        (const unsigned char *) keyBytes, keyLen,
        (unsigned char *) outputBuf
    );
 
    if (encryptResult < 0) {
        jni_throw_runtime(env, "Encryption failed");
        goto cleanup;
    }
 
    // 将结果转为 Java String
    result = env->NewStringUTF(outputBuf);
    // NewStringUTF 失败时 result 为 NULL，异常已挂起，会在 cleanup 后返回 NULL
 
// ======= 统一清理出口 =======
cleanup:
    // 释放 Native 堆内存
    if (outputBuf != NULL) {
        free(outputBuf);
    }
    // 释放 JNI 字符串资源
    if (inputChars != NULL) {
        env->ReleaseStringUTFChars(input, inputChars);
    }
    // 释放 JNI 数组资源（JNI_ABORT 表示不拷贝回 Java，因为密钥只读）
    if (keyBytes != NULL) {
        env->ReleaseByteArrayElements(key, keyBytes, JNI_ABORT);
    }
 
    return result; // 正常返回加密结果，或异常时返回 NULL
}

// =============================================
// C++ RAII 封装：自动释放 JNI 字符串
// =============================================
class JniStringGuard {
public:
    // 构造：获取 C 字符串
    JniStringGuard(JNIEnv *env, jstring jstr)
        : env_(env), jstr_(jstr), cstr_(nullptr) {
        if (jstr != nullptr) {
            // 获取 UTF 字符串指针
            cstr_ = env->GetStringUTFChars(jstr, nullptr);
        }
    }
 
    // 析构：自动释放
    ~JniStringGuard() {
        if (cstr_ != nullptr) {
            // RAII 保证：无论正常退出还是异常退出，都会释放
            env_->ReleaseStringUTFChars(jstr_, cstr_);
        }
    }
 
    // 获取 C 字符串（可能为 NULL）
    const char *c_str() const { return cstr_; }
 
    // 判断是否有效
    bool valid() const { return cstr_ != nullptr; }
 
    // 禁止拷贝
    JniStringGuard(const JniStringGuard &) = delete;
    JniStringGuard &operator=(const JniStringGuard &) = delete;
 
private:
    JNIEnv *env_;        // JNI 环境指针
    jstring jstr_;       // Java 字符串引用
    const char *cstr_;   // C 字符串指针
};
 
// 使用示例
JNIEXPORT void JNICALL Java_com_example_Demo_raii(JNIEnv *env, jobject thiz, jstring name) {
    // 构造时获取，离开作用域时自动释放
    JniStringGuard nameGuard(env, name);
    if (!nameGuard.valid()) {
        return; // OOM 已挂起
    }
 
    // 直接使用，不用担心忘记释放
    LOGI("Name = %s", nameGuard.c_str());
 
    // ... 即使中间有 return，析构也会被调用 ...
} // ← ~JniStringGuard() 在此自动调用，释放字符串

// 在 Native 线程中回调 Java 的标准模式
void native_thread_callback(JavaVM *jvm, jobject globalCallback) {
    JNIEnv *env = NULL;
    // 将当前线程附加到 JVM
    int attached = jvm->AttachCurrentThread(&env, NULL);
    if (attached != JNI_OK) {
        return; // 附加失败，无法操作 JNI
    }
 
    // 获取回调方法
    jclass cls = env->GetObjectClass(globalCallback);
    jmethodID onResult = env->GetMethodID(cls, "onResult", "(I)V");
    if (onResult != NULL) {
        // 调用 Java 回调
        env->CallVoidMethod(globalCallback, onResult, 42);
        // ⚠️ 关键：必须在此检查异常
        if (env->ExceptionCheck()) {
            // 打印异常信息到日志
            env->ExceptionDescribe();
            // 清除异常（否则后续 JNI 调用会出问题）
            env->ExceptionClear();
            // 可选：通过其他机制通知主线程发生了错误
        }
    }
 
    // 清理本地引用
    env->DeleteLocalRef(cls);
    // 分离线程
    jvm->DetachCurrentThread();
}

JNIEXPORT void JNICALL Java_com_example_App_load(JNIEnv *env, jobject thiz, jstring path) {
    const char *cPath = env->GetStringUTFChars(path, NULL);
    if (cPath == NULL) return;
 
    jclass cls = env->FindClass("com/example/Loader");
    if (cls == NULL) return;  // ← 注意这行
 
    jmethodID mid = env->GetMethodID(cls, "load", "(Ljava/lang/String;)V");
    if (mid == NULL) return;  // ← 注意这行
 
    env->CallVoidMethod(thiz, mid, path);
    env->ReleaseStringUTFChars(path, cPath);
}

// ============================================================
// JNI 异常安全函数模板 (Exception-Safe JNI Function Template)
// ============================================================
 
// ---- 辅助宏：检查异常并跳转到清理代码 ----
#define JNI_CHECK_EXCEPTION_GOTO(env, label)    \
    do {                                         \
        if ((*(env))->ExceptionCheck(env)) {     \
            goto label;                          \
        }                                        \
    } while(0)
 
// ---- 辅助函数：统一抛出异常 ----
static void jni_throw(JNIEnv *env,              // JNI 环境指针
                      const char *class_name,    // 异常类全限定名
                      const char *message)       // 异常信息
{
    // 查找异常类（此时可能已有 Pending Exception，需先清除）
    jclass cls = (*env)->FindClass(env, class_name);
    if (cls != NULL) {                           // FindClass 成功
        (*env)->ThrowNew(env, cls, message);     // 设置新的 Pending Exception
        (*env)->DeleteLocalRef(env, cls);        // 释放局部引用
    }
    // 如果 FindClass 失败，JVM 会自动设置 NoClassDefFoundError
}
 
// ---- 主函数示例 ----
JNIEXPORT jstring JNICALL
Java_com_example_NativeLib_processData(JNIEnv *env,
                                       jobject thiz,
                                       jstring input)
{
    // ========== 1. 变量声明区（所有资源指针初始化为 NULL） ==========
    const char *c_input   = NULL;                // 持有 GetStringUTFChars 的资源
    jclass     cls_util   = NULL;                // Java 工具类引用
    jmethodID  mid_parse  = NULL;                // 方法 ID（不需释放）
    jstring    result     = NULL;                // 返回值
 
    // ========== 2. 参数校验区 ==========
    if (input == NULL) {                         // 防御性检查空参数
        jni_throw(env,                           // 抛出空指针异常
                  "java/lang/NullPointerException",
                  "input must not be null");
        return NULL;                             // 立即返回！
    }
 
    // ========== 3. 资源获取区 ==========
    c_input = (*env)->GetStringUTFChars(env,     // 获取 C 字符串
                                        input,
                                        NULL);
    if (c_input == NULL) {                       // 获取失败 → OOM 已挂起
        goto cleanup;                            // 跳转统一清理
    }
 
    // ========== 4. 业务逻辑区（每步 JNI 调用后检查异常） ==========
    cls_util = (*env)->FindClass(env,            // 查找 Java 工具类
                                 "com/example/DataUtil");
    JNI_CHECK_EXCEPTION_GOTO(env, cleanup);      // 异常？→ 清理
 
    mid_parse = (*env)->GetStaticMethodID(env,   // 获取静态方法 ID
                                          cls_util,
                                          "parse",
                                          "(Ljava/lang/String;)Ljava/lang/String;");
    JNI_CHECK_EXCEPTION_GOTO(env, cleanup);      // 异常？→ 清理
 
    result = (jstring)(*env)->CallStaticObjectMethod(env,   // 调用 Java 方法
                                                      cls_util,
                                                      mid_parse,
                                                      input);
    JNI_CHECK_EXCEPTION_GOTO(env, cleanup);      // 异常？→ 清理
 
    // ========== 5. 统一清理区 ==========
cleanup:
    if (c_input != NULL) {                       // 释放 C 字符串资源
        (*env)->ReleaseStringUTFChars(env,
                                      input,
                                      c_input);
    }
    if (cls_util != NULL) {                      // 释放局部引用
        (*env)->DeleteLocalRef(env, cls_util);
    }
    // mid_parse 是 jmethodID，无需释放
    // 如果有 Pending Exception，返回 NULL，JVM 会在回到 Java 层后处理
    return result;                               // 正常 or 异常路径统一返回
}