JNI基础 ⭐⭐

// 文件: HelloJNI.java
// 这是 Java 侧的入口类
public class HelloJNI {
 
    // 静态代码块，在类加载时执行
    // 加载名为 "hello" 的 Native 库（对应 libhello.so / hello.dll）
    static {
        System.loadLibrary("hello");
    }
 
    // 声明一个 native 方法，没有方法体
    // 具体实现在 C/C++ 侧
    public native String sayHello(String name);
 
    // 主函数：测试调用
    public static void main(String[] args) {
        HelloJNI jni = new HelloJNI();           // 创建实例
        String result = jni.sayHello("JNI");     // 调用 native 方法
        System.out.println(result);              // 输出结果
    }
}

# 使用 javac -h 命令编译并同时生成 JNI 头文件
# -h jni_headers 指定头文件输出目录
javac -h jni_headers HelloJNI.java

// 文件: hello.c
#include <jni.h>    // JNI 核心头文件，包含所有 JNI 类型和函数声明
#include <string.h> // C 字符串操作
#include <stdio.h>  // sprintf 等
 
// 函数名格式: Java_{包名}_{类名}_{方法名}
// 包名中的 '.' 替换为 '_'
// 参数1: JNIEnv* 指针 —— JNI 环境，提供所有 JNI 功能函数
// 参数2: jobject —— 调用此 native 方法的 Java 对象实例 (this)
// 参数3: jstring —— 对应 Java 侧的 String name 参数
JNIEXPORT jstring JNICALL
Java_HelloJNI_sayHello(JNIEnv *env, jobject thiz, jstring name) {
 
    // 将 Java 的 jstring 转换为 C 的 const char*
    // GetStringUTFChars 会分配内存，后续必须释放
    const char *c_name = (*env)->GetStringUTFChars(env, name, NULL);
 
    // 准备拼接结果字符串
    char buf[256];                                      // 缓冲区
    sprintf(buf, "Hello, %s from Native C!", c_name);   // 拼接
 
    // 释放之前获取的 C 字符串，避免内存泄漏
    (*env)->ReleaseStringUTFChars(env, name, c_name);
 
    // 将 C 字符串转换为 Java 的 jstring 并返回
    return (*env)->NewStringUTF(env, buf);
}

# Linux 示例：编译为 libhello.so
gcc -shared -fPIC \
    -I${JAVA_HOME}/include \
    -I${JAVA_HOME}/include/linux \
    -o libhello.so \
    hello.c
 
# 设置库搜索路径并运行
java -Djava.library.path=. HelloJNI
# 输出: Hello, JNI from Native C!

// 声明一个 native 方法：没有花括号 {}，直接以分号结尾
public native String getMessageFromNative();

public class NativeDemo {
 
    // 1. 最基本的 native 方法，无参无返回值
    public native void helloFromC();
 
    // 2. 带参数和返回值的 native 方法
    public native int addNumbers(int a, int b);
 
    // 3. 静态 native 方法（常用于工具类）
    public static native long currentTimestampNative();
 
    // 4. synchronized + native：进入 native 前自动持有 this 锁
    public synchronized native void threadSafeWrite(byte[] data);
 
    // 5. 带 Java 对象类型参数（JNI 层将以 jobject 接收）
    public native String processData(String input, int[] array);
 
    // ❌ 编译错误：native 与 abstract 不可共存
    // public abstract native void illegal();
 
    // ❌ 编译错误：native 与 strictfp 不可共存
    // public strictfp native double illegal2();
}

Java 类型        JNI 类型        C/C++ 实际类型
─────────────────────────────────────────────────
boolean     →   jboolean    →   unsigned char
int         →   jint        →   int32_t (通常为 int)
long        →   jlong       →   int64_t
float       →   jfloat      →   float
double      →   jdouble     →   double
String      →   jstring     →   jobject (需用 JNIEnv 函数操作)
int[]       →   jintArray   →   jarray  (需用 JNIEnv 函数操作)
Object      →   jobject     →   void*   (不透明指针)

public class NativeDemo {
 
    // 方式一：通过库名加载（推荐），JVM 自动拼接平台前后缀
    // Linux → libmynative.so | Windows → mynative.dll | macOS → libmynative.dylib
    static {
        System.loadLibrary("mynative");  // 从 java.library.path 中搜索
    }
 
    // 方式二：通过绝对路径加载
    // System.load("/opt/libs/libmynative.so");
 
    // 声明 native 方法
    public native int compute(int x, int y);
}

// 源码文件：NativeDemo.java
public class NativeDemo {
    public native int add(int a, int b);  // native 方法
    public int sub(int a, int b) {        // 普通 Java 方法（对比用）
        return a - b;
    }
}

// ==================== native 方法 ====================
public native int add(int, int);
    descriptor: (II)I
    flags: ACC_PUBLIC, ACC_NATIVE          ← 带有 ACC_NATIVE 标志
    // 注意：没有 Code 属性！没有字节码指令！
 
// ==================== 普通 Java 方法 ====================
public int sub(int, int);
    descriptor: (II)I
    flags: ACC_PUBLIC                      ← 仅 ACC_PUBLIC
    Code:                                  ← 拥有 Code 属性
      stack=2, locals=3, args_size=3
         0: iload_1                        // 加载参数 a
         1: iload_2                        // 加载参数 b
         2: isub                           // 执行减法
         3: ireturn                        // 返回结果

// ===== java.lang.Object =====
public class Object {
    // 返回对象的哈希码，底层依赖内存地址或随机数生成
    public native int hashCode();
    // 创建并返回此对象的浅拷贝
    protected native Object clone() throws CloneNotSupportedException;
    // 唤醒在此对象监视器上等待的单个线程
    public final native void notify();
    // 唤醒在此对象监视器上等待的所有线程
    public final native void notifyAll();
    // 返回运行时类信息
    public final native Class<?> getClass();
}
 
// ===== java.lang.Thread =====
public class Thread implements Runnable {
    // 真正启动一个操作系统线程（调用 pthread_create 或 CreateThread）
    private native void start0();
    // 当前线程让出 CPU 时间片
    public static native void yield();
    // 线程睡眠（底层调用 nanosleep/Sleep）
    private static native void sleep(long millis) throws InterruptedException;
    // 获取当前线程对象
    public static native Thread currentThread();
}
 
// ===== java.lang.System =====
public final class System {
    // 高性能数组复制（底层调用 memcpy/memmove）
    public static native void arraycopy(
        Object src, int srcPos,   // 源数组及起始索引
        Object dest, int destPos, // 目标数组及起始索引
        int length                // 复制长度
    );
    // 返回当前时间的纳秒值
    public static native long nanoTime();
}

┌─────────────────────────────────────────────┐
│              Thread 的栈区域                  │
├──────────────────────┬──────────────────────┤
│    JVM Stack         │  Native Method Stack │
│  (Java 方法栈帧)     │  (Native 方法栈帧)    │
├──────────────────────┼──────────────────────┤
│  ┌────────────────┐  │  ┌────────────────┐  │
│  │ main() 栈帧    │  │  │                │  │
│  ├────────────────┤  │  │  C/C++ 函数    │  │
│  │ compute() 栈帧 │──┼──▶  栈帧          │  │
│  │ (native调用)   │  │  │  (实际执行)     │  │
│  ├────────────────┤  │  ├────────────────┤  │
│  │ ...            │  │  │ ...            │  │
│  └────────────────┘  │  └────────────────┘  │
└──────────────────────┴──────────────────────┘

public class BadExample {
    // 声明了 native 方法，但没有 System.loadLibrary
    public native void doWork();
 
    public static void main(String[] args) {
        new BadExample().doWork();
        // 运行时抛出：java.lang.UnsatisfiedLinkError:
        // BadExample.doWork()V
    }
}

// Linux 上本地库文件为 libcrypto_jni.so
System.loadLibrary("crypto-jni");   // ❌ 横杠 '-' 不等于下划线 '_'
System.loadLibrary("crypto_jni");   // ✅ 正确

public abstract class Base {
    // ❌ 编译错误：Illegal combination of modifiers: 'abstract' and 'native'
    public abstract native void process();
}

// 文件：com/example/HelloJNI.java
package com.example;                          // 包名，影响后续生成的 C 函数名
 
public class HelloJNI {
 
    // 声明一个 native 方法，没有方法体，以分号结束
    // 它的真正实现将在 C/C++ 中完成
    public native String greetFromNative(int id);
 
    // 静态初始化块：在类加载时，加载名为 "hello" 的动态库
    // Linux 上实际加载 libhello.so，Windows 上加载 hello.dll
    static {
        System.loadLibrary("hello");          // 加载动态链接库
    }
 
    // 入口函数，用于测试
    public static void main(String[] args) {
        HelloJNI obj = new HelloJNI();        // 创建实例
        String msg = obj.greetFromNative(42); // 调用 native 方法
        System.out.println(msg);              // 打印 Native 层返回的字符串
    }
}

# 在项目根目录下执行
# -d out  指定 .class 文件输出目录
javac -d out com/example/HelloJNI.java

# 进入 .class 文件的根目录
cd out
 
# 使用 javah 生成头文件
# -jni       指定生成 JNI 风格的头文件（默认行为，可省略）
# -o         指定输出的头文件名（也可用 -d 指定输出目录）
# 最后一个参数是全限定类名（用点分隔，不是斜杠）
javah -jni -o com_example_HelloJNI.h com.example.HelloJNI

# -h jni_headers  指定头文件输出目录
# -d out          指定 .class 输出目录
# 最后是源文件路径
javac -h jni_headers -d out com/example/HelloJNI.java

/* 该文件由工具自动生成 —— 请勿手动编辑 */
/* DO NOT EDIT THIS FILE - it is machine generated */
 
#include <jni.h>   // JNI 核心头文件，定义了 JNIEnv、jclass、jstring 等类型
 
/* Header for class com_example_HelloJNI */
 
#ifndef _Included_com_example_HelloJNI          // 防止头文件重复包含
#define _Included_com_example_HelloJNI
 
#ifdef __cplusplus
extern "C" {                                     // C++ 编译器下使用 C 链接规范
#endif
 
/*
 * Class:     com_example_HelloJNI
 * Method:    greetFromNative
 * Signature: (I)Ljava/lang/String;              // JNI 方法签名（后文详述）
 */
JNIEXPORT jstring JNICALL                        // 返回值：jstring 对应 Java String
Java_com_example_HelloJNI_greetFromNative        // 函数名：Java_包名_类名_方法名
  (JNIEnv *env,                                  // 第一个参数：JNI 环境指针
   jobject thiz,                                 // 第二个参数：调用该方法的 Java 对象（this）
   jint id);                                     // 第三个参数：对应 Java 的 int 参数
 
#ifdef __cplusplus
}
#endif
 
#endif // _Included_com_example_HelloJNI

// Linux / macOS 下通常展开为：
// JNIEXPORT → __attribute__((visibility("default")))  确保符号导出
// JNICALL   → （空，无特殊调用约定）
 
// Windows 下通常展开为：
// JNIEXPORT → __declspec(dllexport)                    导出 DLL 符号
// JNICALL   → __stdcall                                调用约定

// 文件：hello.c
#include "com_example_HelloJNI.h"    // 引入自动生成的头文件
#include <stdio.h>                   // 标准 I/O
#include <string.h>                  // 字符串处理
#include <stdlib.h>                  // 内存分配
 
// 实现 native 方法：greetFromNative
// 函数签名必须与 .h 文件中的声明完全一致
JNIEXPORT jstring JNICALL
Java_com_example_HelloJNI_greetFromNative
  (JNIEnv *env,       // JNI 环境指针，用于调用 JNI 函数
   jobject thiz,      // 调用此方法的 Java 对象引用
   jint id)           // Java 传入的 int 参数
{
    // 在 Native 层构造一个字符串缓冲区
    char buf[128];                              // 分配栈上缓冲区
 
    // 使用 snprintf 格式化字符串，将 id 嵌入
    snprintf(buf, sizeof(buf),                  // 安全格式化，防止溢出
             "Hello from C! Your ID is %d", 
             (int)id);                          // jint 强转为 int
 
    // 调用 JNI 函数 NewStringUTF 将 C 字符串转为 Java String
    // JNIEnv 的函数通过 (*env)-> 方式调用（C 风格）
    return (*env)->NewStringUTF(env, buf);      // 返回 jstring 给 Java 层
}

// 文件：hello.cpp
#include "com_example_HelloJNI.h"     // 引入自动生成的头文件
#include <string>                     // C++ string
#include <sstream>                    // 字符串流
 
// extern "C" 已在 .h 文件中通过 #ifdef __cplusplus 处理
// 因此此处无需再次声明
 
JNIEXPORT jstring JNICALL
Java_com_example_HelloJNI_greetFromNative
  (JNIEnv *env,       // JNI 环境指针
   jobject thiz,      // Java this 引用
   jint id)           // Java int 参数
{
    // 使用 C++ 字符串流拼接消息
    std::ostringstream oss;                      // 创建字符串输出流
    oss << "Hello from C++! Your ID is " << id;  // 流式拼接
 
    std::string result = oss.str();              // 转为 std::string
 
    // C++ 中 JNIEnv 可直接用 -> 调用，无需 (*env)->
    return env->NewStringUTF(result.c_str());    // c_str() 获取 C 风格字符串
}

# 编译 C 代码为共享库 libhello.so
gcc -shared                        \  # 生成共享库
    -fPIC                          \  # 位置无关代码（Position-Independent Code）
    -o libhello.so                 \  # 输出文件名（lib前缀 + 库名 + .so）
    -I${JAVA_HOME}/include         \  # JNI 头文件目录（jni.h）
    -I${JAVA_HOME}/include/linux   \  # 平台相关的 jni_md.h
    -I./jni_headers                \  # 自动生成的头文件目录
    hello.c                           # 源文件

gcc -shared                        \
    -fPIC                          \
    -o libhello.dylib              \  # macOS 使用 .dylib 后缀
    -I${JAVA_HOME}/include         \
    -I${JAVA_HOME}/include/darwin  \  # macOS 平台头文件
    -I./jni_headers                \
    hello.c

# 使用 MinGW 或 MSVC
gcc -shared                        \
    -o hello.dll                   \  # Windows 使用 .dll 后缀，无 lib 前缀
    -I"%JAVA_HOME%\include"        \
    -I"%JAVA_HOME%\include\win32"  \  # Windows 平台头文件
    -I.\jni_headers                \
    hello.c

# CMakeLists.txt
cmake_minimum_required(VERSION 3.18.1)          # 最低 CMake 版本
project("hello")                                 # 项目名
 
add_library(
    hello                                        # 库名 → 生成 libhello.so
    SHARED                                       # 共享库类型
    hello.cpp                                    # 源文件
)
 
# 查找 Android NDK 自带的 log 库（用于 __android_log_print）
find_library(
    log-lib                                      # 变量名
    log                                          # 库名
)
 
# 将 log 库链接到我们的 hello 库
target_link_libraries(
    hello                                        # 目标库
    ${log-lib}                                   # 依赖库
)

# 运行时需要告诉 JVM 动态库的搜索路径
# -Djava.library.path 指定 .so/.dll 所在目录
java -Djava.library.path=. -cp out com.example.HelloJNI

# 查看 .so 中导出的符号，过滤 Java_ 开头的 JNI 函数
nm -D libhello.so | grep Java_
# 预期输出：
# 00000000000011a0 T Java_com_example_HelloJNI_greetFromNative
# T 表示该符号在 text（代码）段，已正确导出

# ===== 一站式 JNI 开发命令（Linux，JDK 11+）=====
 
# [1] 编译 Java + 生成 JNI 头文件（一步完成）
javac -h jni_headers -d out com/example/HelloJNI.java
 
# [2] 实现 Native 代码（hello.c / hello.cpp）—— 手动编写
 
# [3] 编译动态库
gcc -shared -fPIC \
    -I${JAVA_HOME}/include \
    -I${JAVA_HOME}/include/linux \
    -I./jni_headers \
    -o libhello.so hello.c
 
# [4] 运行
java -Djava.library.path=. -cp out com.example.HelloJNI
 
# ===== 输出：Hello from C! Your ID is 42 =====

/* ============================================
 * jni.h 中 JNIEnv 的核心结构定义（简化版）
 * ============================================ */
 
// 函数表结构体：包含 JNI 规范中所有可调用函数的指针
struct JNINativeInterface_ {
    void        *reserved0;                       // 保留字段
    void        *reserved1;                       // 保留字段
    void        *reserved2;                       // 保留字段
    void        *reserved3;                       // 保留字段
    jint        (*GetVersion)(JNIEnv *);          // 获取 JNI 版本号
    jclass      (*FindClass)(JNIEnv*, const char*); // 查找 Java 类
    jmethodID   (*GetMethodID)(JNIEnv*, jclass, const char*, const char*); // 获取方法 ID
    void        (*CallVoidMethod)(JNIEnv*, jobject, jmethodID, ...);       // 调用 void 方法
    jstring     (*NewStringUTF)(JNIEnv*, const char*);  // 创建 Java String
    // ... 超过 200 个函数指针 ...
};
 
// C 语言中: JNIEnv 就是一个指向函数表的指针
typedef const struct JNINativeInterface_ *JNIEnv;
 
// C++ 中: JNIEnv 是一个封装了函数表的结构体（提供成员函数语法糖）

/* ============================================
 * C 语言中的调用方式
 * 必须显式传入 env 本身作为第一个参数
 * ============================================ */
jclass cls = (*env)->FindClass(env, "com/example/MyClass");
//           ^^^^^^^                ^^^
//           先解引用得到函数表     再把 env 传入

/* ============================================
 * C++ 中的调用方式
 * JNIEnv 被封装为结构体，直接用 -> 调用成员函数
 * 内部已自动传递 this（即 env）
 * ============================================ */
jclass cls = env->FindClass("com/example/MyClass");
//           ^^^^
//           直接调用，语法更简洁

/* ============================================
 * ❌ 错误示范：跨线程传递 JNIEnv*
 * 这段代码会导致崩溃或不可预测的行为
 * ============================================ */
 
#include <jni.h>
#include <pthread.h>
#include <stdio.h>
 
// 全局变量，企图保存主线程的 JNIEnv*
static JNIEnv *g_env = NULL;  // ❌ 危险！
 
// 子线程的执行函数
void* child_thread_func(void* arg) {
    // ❌ 在子线程中使用主线程的 JNIEnv*
    // g_env 绑定的是主线程，此处属于非法跨线程访问
    jclass cls = (*g_env)->FindClass(g_env, "java/lang/String");
    // 可能的后果：
    // 1. 直接段错误 (Segmentation Fault / SIGSEGV)
    // 2. 局部引用表被错误线程污染，导致 GC 异常
    // 3. 线程安全检查触发 JVM 直接 abort
    // 4. 偶尔"侥幸"成功，但埋下定时炸弹
    return NULL;
}
 
// 由 Java 层调用的 Native 方法（运行在主线程）
JNIEXPORT void JNICALL
Java_com_example_NativeLib_startWork(JNIEnv *env, jobject thiz) {
    g_env = env;  // ❌ 把当前线程的 env 存到全局变量
 
    pthread_t tid;
    pthread_create(&tid, NULL, child_thread_func, NULL);  // 启动子线程
    pthread_join(tid, NULL);                               // 等待子线程结束
}

/* ============================================
 * ✅ 正确示范：Native 子线程安全获取 JNIEnv
 * ============================================ */
 
#include <jni.h>
#include <pthread.h>
#include <android/log.h>
 
#define TAG "JNI_DEMO"
#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
 
// 全局变量：保存 JavaVM 指针（进程级，可跨线程）
static JavaVM *g_jvm = NULL;
 
// ========== 第一步：在 JNI_OnLoad 中保存 JavaVM ==========
// JNI_OnLoad 在 System.loadLibrary() 时由 JVM 自动调用
// 此时 JVM 会把自身的 JavaVM* 传给我们
JNIEXPORT jint JNICALL
JNI_OnLoad(JavaVM *vm, void *reserved) {
    g_jvm = vm;                   // ✅ 保存到全局变量，后续任何线程都可使用
    LOGI("JNI_OnLoad: JavaVM* saved successfully");
    return JNI_VERSION_1_6;       // 返回需要的 JNI 版本
}
 
// ========== 第二步：子线程函数 ==========
void* child_thread_func(void* arg) {
    JNIEnv *env = NULL;           // 声明一个 JNIEnv 指针，稍后由 JVM 填充
 
    // 调用 AttachCurrentThread 将当前 Native 线程挂载到 JVM
    // 成功后 env 将指向该线程专属的 JNIEnv 实例
    jint result = (*g_jvm)->AttachCurrentThread(g_jvm, &env, NULL);
 
    if (result != JNI_OK) {       // 检查挂载是否成功
        LOGI("AttachCurrentThread failed, error code: %d", result);
        return NULL;              // 挂载失败，直接退出
    }
 
    LOGI("Child thread attached to JVM successfully");
 
    // ✅ 现在可以安全使用 env 了！
    // 查找 Java 类
    jclass cls = (*env)->FindClass(env, "java/lang/String");
    if (cls != NULL) {
        LOGI("FindClass succeeded in child thread!");
    }
 
    // ========== 第三步：用完必须 Detach！==========
    // 如果不 Detach，会导致：
    // 1. 局部引用表内存泄漏
    // 2. JVM 无法正确追踪线程状态
    // 3. JVM 关闭时可能死锁
    (*g_jvm)->DetachCurrentThread(g_jvm);
    LOGI("Child thread detached from JVM");
 
    return NULL;
}
 
// ========== Java 层调用入口 ==========
JNIEXPORT void JNICALL
Java_com_example_NativeLib_startWork(JNIEnv *env, jobject thiz) {
    // 主线程的 env 仅在此函数内使用，绝不存到全局
    pthread_t tid;
    pthread_create(&tid, NULL, child_thread_func, NULL); // 启动子线程
    // 注意：这里不 join，让子线程自由运行
}

/* ============================================
 * ✅ 通用工具函数：安全获取当前线程的 JNIEnv
 * ============================================ */
JNIEnv* GetEnvSafe() {
    JNIEnv *env = NULL;
 
    // GetEnv：尝试获取当前线程的 JNIEnv
    // 如果当前线程已经 Attach，直接返回 JNI_OK 和有效的 env
    // 如果当前线程未 Attach，返回 JNI_EDETACHED
    jint status = (*g_jvm)->GetEnv(g_jvm, (void**)&env, JNI_VERSION_1_6);
 
    if (status == JNI_EDETACHED) {
        // 当前线程尚未挂载到 JVM，执行挂载
        jint attachResult = (*g_jvm)->AttachCurrentThread(g_jvm, &env, NULL);
        if (attachResult != JNI_OK) {
            return NULL;          // 挂载失败
        }
        // ⚠️ 注意：此处 Attach 的线程，调用方有责任在适当时机 Detach
    }
 
    return env;                   // 返回当前线程的 JNIEnv*
}

/* ============================================
 * ✅ 高级技巧：利用 pthread_key 实现自动 Detach
 * 适用于 Android NDK 项目
 * ============================================ */
 
#include <jni.h>
#include <pthread.h>
 
static JavaVM *g_jvm = NULL;       // 全局 JavaVM 指针
static pthread_key_t g_thread_key; // POSIX 线程键
 
// 线程销毁时的回调函数
// 当关联了 g_thread_key 的线程退出时，系统自动调用此函数
static void thread_destructor(void *arg) {
    JNIEnv *env = (JNIEnv*)arg;    // arg 就是我们之前关联的 JNIEnv*
    if (env != NULL) {
        // 自动 Detach，无需手动调用
        (*g_jvm)->DetachCurrentThread(g_jvm);
    }
}
 
JNIEXPORT jint JNICALL
JNI_OnLoad(JavaVM *vm, void *reserved) {
    g_jvm = vm;
 
    // 创建 pthread_key，并注册析构函数
    // 当线程退出时，如果该 key 关联了非 NULL 值，
    // 系统会自动调用 thread_destructor
    pthread_key_create(&g_thread_key, thread_destructor);
 
    return JNI_VERSION_1_6;
}
 
// 安全获取 JNIEnv，并自动处理 Attach/Detach 生命周期
JNIEnv* GetEnvAutoManaged() {
    JNIEnv *env = NULL;
    jint status = (*g_jvm)->GetEnv(g_jvm, (void**)&env, JNI_VERSION_1_6);
 
    if (status == JNI_EDETACHED) {
        // 挂载当前线程
        if ((*g_jvm)->AttachCurrentThread(g_jvm, &env, NULL) == JNI_OK) {
            // 将 env 关联到 pthread_key
            // 线程退出时，thread_destructor 会被自动调用
            pthread_setspecific(g_thread_key, env);
        }
    }
 
    return env;
}

/* ============================================
 * jni.h 中通过条件编译区分 C/C++ 定义
 * ============================================ */
 
#if defined(__cplusplus)
// C++ 环境下：JNIEnv 是 _JNIEnv 结构体
// _JNIEnv 内部封装了 JNINativeInterface_ 的函数指针
// 并为每个函数提供了便捷的内联成员函数
typedef _JNIEnv JNIEnv;
// 所以 C++ 中 env 本身是结构体，env->FindClass("...") 直接调用
#else
// C 环境下：JNIEnv 是 JNINativeInterface_ 的指针
typedef const struct JNINativeInterface_ *JNIEnv;
// 所以 C 中 env 是指针的指针，需要 (*env)->FindClass(env, "...") 
#endif

// 总结调用方式对比：
// ┌──────────┬──────────────────────────────────────────────────┐
// │  语言    │  调用方式                                         │
// ├──────────┼──────────────────────────────────────────────────┤
// │  C       │  (*env)->FindClass(env, "com/example/MyClass")   │
// │  C++     │  env->FindClass("com/example/MyClass")           │
// └──────────┴──────────────────────────────────────────────────┘

// 文件: com/example/jni/NativeHelper.java
package com.example.jni; // 包名，将参与 JNI 函数名生成
 
public class NativeHelper {
 
    // 静态代码块：在类加载时，加载名为 "native-helper" 的本地库
    // 实际加载的文件：Linux 下为 libnative-helper.so，Windows 下为 native-helper.dll
    static {
        System.loadLibrary("native-helper");
    }
 
    // 声明一个无参的 native 方法，返回 String
    // JVM 将根据命名规则，在已加载的本地库中查找对应的 C/C++ 函数
    public native String getStringFromNative();
 
    // 声明一个带参数的 native 方法
    // 参数类型 int 在 JNI 中对应 jint
    public native int addNumbers(int a, int b);
 
    // 声明一个静态的 native 方法（注意：静态方法的 C 函数签名有所不同）
    public static native void printHello();
 
    // 测试入口
    public static void main(String[] args) {
        NativeHelper helper = new NativeHelper(); // 创建实例
        System.out.println(helper.getStringFromNative()); // 调用实例 native 方法
        System.out.println("3 + 7 = " + helper.addNumbers(3, 7)); // 调用带参 native 方法
        NativeHelper.printHello(); // 调用静态 native 方法
    }
}

# 使用 javac -h 同时编译 Java 源文件并生成 JNI 头文件
# -h jni_headers  : 指定头文件输出目录
# 编译后会在 jni_headers/ 下生成 com_example_jni_NativeHelper.h
javac -h jni_headers com/example/jni/NativeHelper.java

/* 文件: com_example_jni_NativeHelper.h (由 javac -h 自动生成，不要手动修改) */
 
#include <jni.h> // JNI 核心头文件
 
#ifndef _Included_com_example_jni_NativeHelper
#define _Included_com_example_jni_NativeHelper
 
#ifdef __cplusplus
extern "C" {       // 如果是 C++ 编译器，使用 C 链接规范，防止 name mangling
#endif
 
/*
 * Class:     com_example_jni_NativeHelper
 * Method:    getStringFromNative
 * Signature: ()Ljava/lang/String;
 */
// JNIEXPORT: 确保函数在共享库中可见（Linux 下展开为 __attribute__((visibility("default")))）
// JNICALL:   指定调用约定（Windows 下展开为 __stdcall，Linux 下通常为空）
// 函数名严格遵循: Java_包名_类名_方法名
JNIEXPORT jstring JNICALL Java_com_example_jni_NativeHelper_getStringFromNative
  (JNIEnv *, jobject); // JNIEnv*: JNI 环境指针; jobject: 调用该方法的 Java 对象(this)
 
/*
 * Class:     com_example_jni_NativeHelper
 * Method:    addNumbers
 * Signature: (II)I
 */
JNIEXPORT jint JNICALL Java_com_example_jni_NativeHelper_addNumbers
  (JNIEnv *, jobject, jint, jint); // 额外的 jint 参数对应 Java 的 int a, int b
 
/*
 * Class:     com_example_jni_NativeHelper
 * Method:    printHello
 * Signature: ()V
 */
JNIEXPORT void JNICALL Java_com_example_jni_NativeHelper_printHello
  (JNIEnv *, jclass); // 注意：静态方法第二个参数是 jclass（类引用），而非 jobject
 
#ifdef __cplusplus
}
#endif
 
#endif

// 文件: native_helper.c
#include <jni.h>    // JNI 类型定义和函数声明
#include <stdio.h>  // printf
#include "com_example_jni_NativeHelper.h" // javac -h 生成的头文件
 
// ============================================================
// 实现 getStringFromNative()
// 对应 Java: public native String getStringFromNative();
// ============================================================
JNIEXPORT jstring JNICALL Java_com_example_jni_NativeHelper_getStringFromNative
  (JNIEnv *env, jobject thiz) {
    // env   : JNI 环境指针，所有 JNI 函数调用都要通过它
    // thiz  : 调用此方法的 Java 对象引用（类似 Java 中的 this）
 
    // 使用 NewStringUTF 将 C 字符串（UTF-8）转换为 Java 的 String 对象
    return (*env)->NewStringUTF(env, "Hello from Native (C) via Static Registration!");
}
 
// ============================================================
// 实现 addNumbers(int a, int b)
// 对应 Java: public native int addNumbers(int a, int b);
// ============================================================
JNIEXPORT jint JNICALL Java_com_example_jni_NativeHelper_addNumbers
  (JNIEnv *env, jobject thiz, jint a, jint b) {
    // env   : JNI 环境指针
    // thiz  : 调用此方法的 Java 对象引用
    // a, b  : 对应 Java 传入的两个 int 参数，类型自动映射为 jint
    return a + b; // jint 本质就是 int32_t，可以直接运算
}
 
// ============================================================
// 实现 printHello() —— 静态方法
// 对应 Java: public static native void printHello();
// ============================================================
JNIEXPORT void JNICALL Java_com_example_jni_NativeHelper_printHello
  (JNIEnv *env, jclass clazz) {
    // env   : JNI 环境指针
    // clazz : 静态方法没有 this 对象，取而代之的是 jclass（即该类的 Class 引用）
    //         可以通过 clazz 访问该类的静态字段或调用静态方法
    printf("Hello from a static native method!\n"); // 直接使用 C 标准输出
}

// Java 方法名包含下划线
package com.my_app; // 包名也包含下划线！
 
public class Data_Parser {
    public native void parse_data();
}

// com.my_app → com_my_1app（注意 _app 中的 _ 被转义为 _1）
// Data_Parser → Data_1Parser
// parse_data → parse_1data
JNIEXPORT void JNICALL Java_com_my_1app_Data_1Parser_parse_1data
  (JNIEnv *env, jobject thiz) {
    // ...
}

// Java 类中存在两个重载的 native 方法
public class Calculator {
    public native int compute(int x);           // 重载版本 1
    public native int compute(int x, int y);    // 重载版本 2
}

// 重载版本 1：参数签名为 (I) → __I
// 注意：两个下划线 "__" 用于分隔方法名和参数签名
JNIEXPORT jint JNICALL Java_Calculator_compute__I
  (JNIEnv *env, jobject thiz, jint x) {
    return x * x; // 示例：计算平方
}
 
// 重载版本 2：参数签名为 (II) → __II
JNIEXPORT jint JNICALL Java_Calculator_compute__II
  (JNIEnv *env, jobject thiz, jint x, jint y) {
    return x + y; // 示例：计算加法
}

// 参数为 String 类型的重载
public native void process(String text);

// String 的签名: Ljava/lang/String; → Ljava_lang_String_2
// 完整函数名追加 __Ljava_lang_String_2
JNIEXPORT void JNICALL Java_MyClass_process__Ljava_lang_String_2
  (JNIEnv *env, jobject thiz, jstring text) {
    // ... 处理字符串
}

package org.open_source.utils;
 
public class Text_Helper {
    public native void format_text(String input);
}

// 这个函数名长达 70+ 个字符，可读性极差
JNIEXPORT void JNICALL Java_com_example_myapp_core_engine_NativeProcessor_processFrame(
    JNIEnv *env, jobject thiz, jbyteArray frame
);

/*
 * JNI_OnLoad - Native 库加载时 JVM 自动调用的入口函数
 *
 * 参数:
 *   vm  - 指向 JavaVM 结构体的指针，代表当前 JVM 实例
 *         一个进程中只有一个 JavaVM，可安全缓存
 *   reserved - 保留参数，目前未使用，传 NULL
 *
 * 返回值:
 *   必须返回当前 Native 代码所需的 JNI 版本号
 *   如果返回的版本 JVM 不支持，则库加载失败
 */
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved);

// 全局缓存 JavaVM 指针，后续其他线程可通过它获取 JNIEnv
static JavaVM *g_jvm = NULL;  // 全局变量，存储 JVM 实例指针
 
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) {
    g_jvm = vm;  // 缓存 JavaVM 指针到全局变量
    // ... 执行动态注册等初始化工作
    return JNI_VERSION_1_6;  // 返回所需的 JNI 版本
}
 
// 在其他 Native 线程中获取 JNIEnv 的工具函数
JNIEnv* getEnv() {
    JNIEnv *env = NULL;                        // 声明 JNIEnv 指针
    // 将当前线程附加到 JVM，获取该线程的 JNIEnv
    g_jvm->GetEnv((void**)&env, JNI_VERSION_1_6);
    return env;                                 // 返回当前线程的 JNIEnv
}

/*
 * JNINativeMethod 结构体定义（摘自 jni.h）
 * 每个实例描述一个 "Java方法 <-> Native函数" 的映射
 */
typedef struct {
    const char *name;       // Java 中 native 方法的名称（UTF-8 字符串）
    const char *signature;  // 方法的 JNI 签名（参数类型+返回类型）
    void       *fnPtr;      // 指向 C/C++ 实现函数的函数指针
} JNINativeMethod;

// Java: native int add(int a, int b);
// 签名: 两个 int 参数 -> 返回 int
"(II)I"
 
// Java: native String greet(String name, int age);
// 签名: 一个 String + 一个 int 参数 -> 返回 String
"(Ljava/lang/String;I)Ljava/lang/String;"
 
// Java: native void processArray(byte[] data, int offset, int length);
// 签名: byte数组 + int + int -> 返回 void
"([BII)V"
 
// Java: native long[] findAll(String pattern);
// 签名: 一个 String 参数 -> 返回 long 数组
"(Ljava/lang/String;)[J"

/*
 * RegisterNatives 函数原型
 *
 * 参数:
 *   clazz   - 目标 Java 类的 jclass 引用
 *   methods - JNINativeMethod 数组的首地址
 *   nMethods - 数组中元素的个数
 *
 * 返回值:
 *   成功返回 0 (JNI_OK)，失败返回负值
 */
jint RegisterNatives(JNIEnv *env, jclass clazz,
                     const JNINativeMethod *methods, jint nMethods);

package com.example.jni;  // 包路径
 
public class Calculator {
 
    // 加载 Native 库，触发 JNI_OnLoad
    static {
        System.loadLibrary("calculator");  // 对应 libcalculator.so
    }
 
    // 声明 native 方法（无需关心 Native 函数名）
    public native int add(int a, int b);          // 加法
    public native int subtract(int a, int b);     // 减法
    public native String describe(String operation, int result); // 描述
 
    // 测试入口
    public static void main(String[] args) {
        Calculator calc = new Calculator();                    // 创建实例
        System.out.println("3 + 5 = " + calc.add(3, 5));     // 调用加法
        System.out.println("9 - 4 = " + calc.subtract(9, 4)); // 调用减法
        System.out.println(calc.describe("addition", 8));      // 调用描述
    }
}

#include <jni.h>       // JNI 核心头文件
#include <string>      // C++ 字符串支持
#include <cstdlib>     // C 标准库
 
// ========== 第一部分：Native 函数实现 ==========
// 注意：函数名完全自由，不需要遵循 Java_xxx 命名规则
 
// 加法实现 —— 函数名随意取
static jint myAdd(JNIEnv *env, jobject thiz, jint a, jint b) {
    return a + b;  // 直接返回两数之和
}
 
// 减法实现
static jint mySubtract(JNIEnv *env, jobject thiz, jint a, jint b) {
    return a - b;  // 直接返回两数之差
}
 
// 描述实现 —— 涉及字符串操作
static jstring myDescribe(JNIEnv *env, jobject thiz, jstring operation, jint result) {
    // 将 Java String 转换为 C 风格字符串（UTF-8 编码）
    const char *op = env->GetStringUTFChars(operation, nullptr);
 
    // 拼接结果字符串
    std::string desc = "The result of ";  // 创建 C++ string
    desc += op;                            // 追加操作名称
    desc += " is ";                        // 追加连接词
    desc += std::to_string(result);        // 追加数字（转字符串）
 
    // 释放 JNI 分配的 UTF 字符串资源（必须释放，否则内存泄漏！）
    env->ReleaseStringUTFChars(operation, op);
 
    // 将 C++ string 转换回 Java String 并返回
    return env->NewStringUTF(desc.c_str());
}
 
// ========== 第二部分：构建映射表 ==========
// 每个元素描述一个 Java native 方法 <-> C/C++ 函数的绑定
 
static JNINativeMethod gMethods[] = {
    // { Java方法名,  JNI签名,          C/C++函数指针 }
    {
        "add",                      // Java 方法名: add
        "(II)I",                    // 签名: (int, int) -> int
        (void *) myAdd              // 绑定到 myAdd 函数
    },
    {
        "subtract",                 // Java 方法名: subtract
        "(II)I",                    // 签名: (int, int) -> int
        (void *) mySubtract         // 绑定到 mySubtract 函数
    },
    {
        "describe",                 // Java 方法名: describe
        "(Ljava/lang/String;I)Ljava/lang/String;",  // 签名: (String, int) -> String
        (void *) myDescribe         // 绑定到 myDescribe 函数
    }
};
 
// ========== 第三部分：JNI_OnLoad 入口 ==========
 
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) {
    JNIEnv *env = nullptr;  // 声明 JNIEnv 指针
 
    // 通过 JavaVM 获取当前线程的 JNIEnv
    // GetEnv 的第二个参数是请求的 JNI 版本
    jint result = vm->GetEnv((void **) &env, JNI_VERSION_1_6);
 
    // 检查获取是否成功
    if (result != JNI_OK) {
        return JNI_ERR;  // 获取失败，返回错误码，库加载将失败
    }
 
    // 通过全限定类名找到目标 Java 类
    // 注意：使用 '/' 而不是 '.' 分隔包名
    jclass clazz = env->FindClass("com/example/jni/Calculator");
 
    // 检查类是否找到
    if (clazz == nullptr) {
        return JNI_ERR;  // 类不存在，返回错误
    }
 
    // 核心步骤：调用 RegisterNatives 执行批量注册
    // 参数：目标类、映射表首地址、映射表元素个数
    jint regResult = env->RegisterNatives(
        clazz,                                   // 目标 Java 类
        gMethods,                                // JNINativeMethod 数组
        sizeof(gMethods) / sizeof(gMethods[0])   // 自动计算数组长度
    );
 
    // 检查注册是否成功
    if (regResult != JNI_OK) {
        return JNI_ERR;  // 注册失败
    }
 
    // 返回 JNI 版本号，告诉 JVM 我们使用的是 JNI 1.6
    return JNI_VERSION_1_6;
}

┌──────────────────────────────────────────────────┐
│         Method 对象 (JVM 内部表示)                 │
├──────────────────────────────────────────────────┤
│  name_index        : "add"                       │
│  signature_index   : "(II)I"                     │
│  access_flags      : ACC_NATIVE | ACC_PUBLIC     │
│  ...                                             │
│  ┌──────────────────────────────────────────┐    │
│  │ native_function: 0x0000000000000000  ──────── │──── 初始为 NULL
│  └──────────────────────────────────────────┘    │
│                      │                           │
│                      ▼  RegisterNatives() 后     │
│  ┌──────────────────────────────────────────┐    │
│  │ native_function: 0x00007F3A8C001234  ──────── │──── 指向 myAdd()
│  └──────────────────────────────────────────┘    │
└──────────────────────────────────────────────────┘

// RegisterNatives 简化版内部伪代码
jint RegisterNatives(JNIEnv *env, jclass clazz,
                     const JNINativeMethod *methods, jint nMethods) {
 
    // 遍历所有需要注册的方法
    for (int i = 0; i < nMethods; i++) {
        // 在目标 Java 类中查找匹配的 native 方法
        // 匹配条件：方法名 + 签名 完全一致
        Method *method = findMethod(clazz, methods[i].name, methods[i].signature);
 
        // 如果找不到对应的 Java native 方法
        if (method == NULL) {
            throwNoSuchMethodError();  // 抛出 NoSuchMethodError
            return JNI_ERR;            // 返回错误
        }
 
        // 检查该方法是否确实声明了 native 修饰符
        if (!isNative(method)) {
            throwNoSuchMethodError();  // 非 native 方法也不行
            return JNI_ERR;
        }
 
        // 核心操作：将函数指针直接写入 Method 对象的 native_function 字段
        method->native_function = methods[i].fnPtr;
    }
 
    return JNI_OK;  // 所有方法注册成功
}

#include <jni.h>  // JNI 核心头文件
 
// ===== Calculator 类的 Native 方法 =====
static jint calc_add(JNIEnv *env, jobject thiz, jint a, jint b) {
    return a + b;  // 加法实现
}
 
static JNINativeMethod gCalcMethods[] = {
    {"add", "(II)I", (void *) calc_add}  // 绑定 add 方法
};
 
// 注册 Calculator 类的所有 native 方法
static int registerCalculator(JNIEnv *env) {
    jclass clazz = env->FindClass("com/example/Calculator");  // 查找类
    if (clazz == nullptr) return JNI_ERR;                      // 类不存在则失败
    return env->RegisterNatives(clazz, gCalcMethods,           // 执行注册
                                sizeof(gCalcMethods) / sizeof(gCalcMethods[0]));
}
 
// ===== Logger 类的 Native 方法 =====
static void logger_log(JNIEnv *env, jobject thiz, jstring msg) {
    // ... 日志实现
}
 
static JNINativeMethod gLoggerMethods[] = {
    {"log", "(Ljava/lang/String;)V", (void *) logger_log}  // 绑定 log 方法
};
 
// 注册 Logger 类的所有 native 方法
static int registerLogger(JNIEnv *env) {
    jclass clazz = env->FindClass("com/example/Logger");  // 查找类
    if (clazz == nullptr) return JNI_ERR;                   // 类不存在则失败
    return env->RegisterNatives(clazz, gLoggerMethods,      // 执行注册
                                sizeof(gLoggerMethods) / sizeof(gLoggerMethods[0]));
}
 
// ===== 统一入口 =====
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) {
    JNIEnv *env = nullptr;                                // 声明 JNIEnv 指针
    if (vm->GetEnv((void **) &env, JNI_VERSION_1_6) != JNI_OK) {
        return JNI_ERR;                                    // 获取 JNIEnv 失败
    }
 
    // 按模块依次注册，任何一个失败则整体失败
    if (registerCalculator(env) != JNI_OK) return JNI_ERR;  // 注册 Calculator
    if (registerLogger(env) != JNI_OK) return JNI_ERR;      // 注册 Logger
 
    return JNI_VERSION_1_6;  // 全部成功，返回 JNI 版本
}

// static 关键字使函数符号不会出现在 .so 的导出表中
// 逆向工程师无法通过符号表直接定位这些函数
static jint mySecretAdd(JNIEnv *env, jobject thiz, jint a, jint b) {
    return a + b;  // 实现对外不可见
}

// 高性能版本：使用 NEON/SSE 指令集加速
static jint add_fast(JNIEnv *env, jobject thiz, jint a, jint b) {
    // ... SIMD 优化的实现
    return a + b;
}
 
// 兼容版本：纯 C 实现，兼容性最好
static jint add_compat(JNIEnv *env, jobject thiz, jint a, jint b) {
    return a + b;  // 普通实现
}
 
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) {
    JNIEnv *env = nullptr;                                         // 声明 JNIEnv
    vm->GetEnv((void **) &env, JNI_VERSION_1_6);                  // 获取 JNIEnv
 
    // 根据 CPU 特性选择不同的实现
    bool hasNeon = checkNeonSupport();                              // 检测硬件特性
 
    JNINativeMethod methods[] = {
        {
            "add",                                                  // Java 方法名
            "(II)I",                                                // 签名
            hasNeon ? (void *) add_fast : (void *) add_compat      // 条件选择！
        }
    };
 
    jclass clazz = env->FindClass("com/example/Calculator");       // 查找类
    env->RegisterNatives(clazz, methods, 1);                       // 注册
 
    return JNI_VERSION_1_6;                                        // 返回版本
}

// 解除 Calculator 类上所有 native 方法的绑定
// 之后调用这些方法将触发 UnsatisfiedLinkError
env->UnregisterNatives(clazz);

JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) {
    JNIEnv *env = nullptr;
    vm->GetEnv((void **) &env, JNI_VERSION_1_6);
    jclass clazz = env->FindClass("com.example.MyClass");  // 注意这里
    JNINativeMethod methods[] = {
        {"getData", "()[B", (void *) native_getData}
    };
    env->RegisterNatives(clazz, methods, 1);
    return JNI_VERSION_1_6;
}

// ======== JNIEnv 的线程绑定模型 ========
 
// Thread-A 启动时，JVM 为其分配独立的 JNIEnv
// Thread-A: env_A -> [JNI Function Table]  (共享同一张函数表)
//                          ↑
// Thread-B: env_B ---------┘               (指针不同，表相同)
 
// ❌ 错误示范：将 Thread-A 的 env 传给 Thread-B
// void* threadFunc(void* arg) {
//     JNIEnv* env = (JNIEnv*)arg;  // 来自主线程的 env，未定义行为！
//     env->FindClass("...");        // 崩溃或数据损坏
// }
 
// ✅ 正确做法：子线程通过 JavaVM 获取自己的 JNIEnv
// JavaVM* gJvm;  // 全局缓存，JNI_OnLoad 中保存
// void* threadFunc(void* arg) {
//     JNIEnv* env = NULL;
//     gJvm->AttachCurrentThread(&env, NULL);  // 获取本线程的 env
//     env->FindClass("...");                   // 安全调用
//     gJvm->DetachCurrentThread();             // 用完必须 Detach
// }