Java Native Interface Specification Contents 翻译

https://docs.oracle.com/en/java/javase/12/docs/specs/jni/index.html

Google翻译

第1章：简介

本章介绍Java Native Interface（JNI）。 JNI是本机编程接口。 它允许在Java虚拟机（VM）内运行的Java代码与用其他编程语言（如C，C ++和汇编语言）编写的应用程序和库进行互操作。

JNI最重要的好处是它对底层Java VM的实现没有任何限制。 因此，Java VM供应商可以添加对JNI的支持，而不会影响VM的其他部分。 程序员可以编写一个本机应用程序或库的版本，并期望它可以与支持JNI的所有Java VM一起使用。

本章包含以下主题：

• Java本机接口概述
• 历史背景
  • JDK 1.0本机方法接口
  • Java运行时接口
  • 原始本机接口和Java / COM接口
• 目标
• Java本地接口方法
• 编程到JNI
• 变化

Java本机接口概述

虽然您可以完全使用Java编写应用程序，但有些情况下Java本身并不能满足您的应用程序的需求。 当应用程序不能完全用Java编写时，程序员使用JNI编写Java本机方法来处理这些情况。

以下示例说明何时需要使用Java本机方法：

• 标准Java类库不支持应用程序所需的与平台相关的功能。
• 您已经有一个用另一种语言编写的库，并希望通过JNI使其可以访问Java代码。
• 您希望在较低级别的语言（如汇编语言）中实现一小部分时间关键代码。

通过JNI编程，您可以使用本机方法：

• 创建，检查和更新Java对象（包括数组和字符串）。
• 调用Java方法。
• 捕获并抛出异常。
• 加载类并获取类信息。
• 执行运行时类型检查。

您还可以将JNI与Invocation API一起使用，以使任意本机应用程序能够嵌入Java VM。 这使程序员可以轻松地使其现有应用程序支持Java，而无需与VM源代码链接。

历史背景

来自不同供应商的VM提供不同的本机方法接口。 这些不同的接口迫使程序员在给定平台上生成，维护和分发多个版本的本机方法库。

我们简要介绍一些本机方法接口，例如：

• JDK 1.0本机方法接口
• Netscape的Java运行时接口
• Microsoft的原始本机接口和Java / COM接口

JDK 1.0本机方法接口

JDK 1.0附带了本机方法接口。 不幸的是，这个接口不适合其他Java VM采用有两个主要原因。

首先，本机代码访问Java对象中的字段作为C结构的成员。 但是，Java语言规范没有定义如何在内存中布置对象。 如果Java VM在内存中以不同方式布局对象，则程序员必须重新编译本机方法库。

其次，JDK 1.0的本机方法接口依赖于保守的垃圾收集器。 例如，不受限制地使用unhand宏使得必须保守地扫描本机堆栈。

Netscape的Java运行时接口

Netscape提出了Java运行时接口（JRI），它是Java虚拟机中提供的服务的通用接口。 JRI的设计考虑了可移植性 - 它对底层Java VM中的实现细节做了很少的假设。 JRI解决了广泛的问题，包括本机方法，调试，反射，嵌入（调用）等。

原始本机接口和Java / COM接口

Microsoft Java VM支持两种本机方法接口。 在低级别，它提供了有效的原始本机接口（RNI）。 RNI提供了与JDK本机方法接口的高度源级向后兼容性，尽管它有一个主要区别。 本机代码必须使用RNI函数与垃圾收集器明确交互，而不是依赖于保守的垃圾收集。

在更高级别，Microsoft的Java / COM接口为Java VM提供了与语言无关的标准二进制接口。 Java代码可以像使用Java对象一样使用COM对象。 Java类也可以作为COM类公开给系统的其余部分。

目标

我们相信，统一，经过深思熟虑的标准界面为每个人提供以下好处：

• 每个VM供应商都可以支持更大的本机代码。
• 工具构建器不必维护不同类型的本机方法接口。
• 应用程序编程人员将能够编写一个版本的本机代码，该版本将在不同的VM上运行。

实现标准本机方法接口的最佳方法是让所有参与Java VM的人都参与进来。因此，我们在Java许可证持有者之间组织了一系列关于统一本机方法接口设计的讨论。从讨论中可以清楚地看出，标准本机方法接口必须满足以下要求：

• 二进制兼容性 - 主要目标是在给定平台上的所有Java VM实现中本机方法库的二进制兼容性。程序员应该只为给定的平台维护其本机方法库的一个版本。
• 效率 - 为了支持时间关键代码，本机方法接口必须施加很少的开销。确保VM独立性（以及二进制兼容性）的所有已知技术都带有一定量的开销。我们必须以某种方式在效率和VM独立性之间达成妥协。
• 功能 - 接口必须公开足够的Java VM内部，以允许本机方法完成有用的任务。

Java本地接口方法

我们希望采用现有方法之一作为标准接口，因为这会给必须在不同VM中学习多个接口的程序员带来最小的负担。不幸的是，没有现成的解决方案可以完全满足我们的目标。

Netscape的JRI最接近我们想象的可移植本机方法接口，并被用作我们设计的起点。熟悉JRI的读者会注意到API命名约定，方法和字段ID的使用，本地和全局引用的使用等方面的相似之处。尽管我们尽最大努力，但JNI与JRI不是二进制兼容的，尽管VM可以同时支持JRI和JNI。

微软的RNI是对JDK 1.0的改进，因为它解决了使用非保守垃圾收集器的本机方法的问题。但是，RNI不适合作为独立于VM的本机方法接口。与JDK一样，RNI本机方法将Java对象作为C结构访问，导致两个问题：

• RNI将内部Java对象的布局暴露给本机代码。
• 直接访问Java对象作为C结构使得无法有效地合并“写入障碍”，这在高级垃圾收集算法中是必需的。

作为二进制标准，COM确保跨不同VM的完全二进制兼容性。调用COM方法只需要间接调用，这几乎不会产生任何开销。此外，COM对象在解决版本问题方面比动态链接库有了很大的改进。

但是，使用COM作为标准Java本机方法接口受到以下几个因素的阻碍：

• 首先，Java / COM接口缺少某些所需的功能，例如访问私有字段和引发一般异常。
• 其次，Java / COM接口自动为Java对象提供标准的IUnknown和IDispatch COM接口，以便本机代码可以访问公共方法和字段。遗憾的是，IDispatch接口不处理重载的Java方法，并且在匹配方法名称时不区分大小写。此外，通过IDispatch接口公开的所有Java方法都被包装以执行动态类型检查和强制。这是因为IDispatch接口在设计时考虑了弱类型语言（例如Basic）。
• 第三，COM不是处理单独的低级功能，而是旨在允许软件组件（包括完整的应用程序）协同工作。我们认为将所有Java类或低级本机方法视为软件组件是不合适的。
• 第四，由于缺乏对UNIX平台的支持，因此立即采用COM受到阻碍。

虽然Java对象不作为COM对象公开给本机代码，但JNI接口本身与COM二进制兼容。 JNI使用与COM相同的跳转表结构和调用约定。这意味着，只要跨平台支持COM，JNI就可以成为Java VM的COM接口。

JNI不被认为是给定Java VM支持的唯一本机方法接口。标准接口使程序员受益，他们希望将本机代码库加载到不同的Java VM中。在某些情况下，程序员可能必须使用较低级别的VM特定接口来实现最高效率。在其他情况下，程序员可能使用更高级别的界面来构建软件组件。实际上，随着Java环境和组件软件技术的日趋成熟，本机方法将逐渐失去意义。

编程到JNI

本机方法程序员应该编程到JNI。 对JNI进行编程可以使您免于未知，例如最终用户可能正在运行的供应商的VM。 通过遵循JNI标准，您将为本机库提供在给定Java VM中运行的最佳机会。

如果要实现Java VM，则应实现JNI。 JNI已经过时间测试，并确保不对您的VM实施施加任何开销或限制，包括对象表示，垃圾收集方案等。 如果您遇到我们可能忽略的任何问题，请将您的反馈发送给我们。

第2章：设计概述

本章重点介绍JNI中的主要设计问题。 本节中的大多数设计问题都与本机方法有关。 第5章：Invocation API中介绍了Invocation API的设计。

本章包含以下主题：

• JNI接口函数和指针
• 编译，加载和链接本机方法
  • 解析本机方法名称
  • 本机方法参数
• 引用Java对象
  • 全局和局部引用
  • 实现本地引用
• 访问Java对象
  • 访问原始数组
  • 访问字段和方法
• Java例外
  • 例外和错误代码
  • 异步异常
  • 异常处理

JNI接口函数和指针

本机代码通过调用JNI函数来访问Java VM功能。 JNI函数可通过接口指针获得。 接口指针是指向指针的指针。 该指针指向一个指针数组，每个指针指向一个接口函数。 每个接口函数都在数组内的预定义偏移处。 下图是接口指针，说明了接口指针的组织。

JNI接口的组织方式类似于C ++虚函数表或COM接口。使用接口表而不是硬连接函数条目的优点是JNI名称空间与本机代码分离。 VM可以轻松提供多个版本的JNI功能表。例如，VM可能支持两个JNI功能表：

• 一个进行彻底的非法参数检查，适合调试;
• 另一个执行JNI规范所要求的最小量的检查，因此更有效。

JNI接口指针仅在当前线程中有效。因此，本机方法不能将接口指针从一个线程传递到另一个线程。实现JNI的VM可以在JNI接口指针指向的区域中分配和存储线程本地数据。

本机方法接收JNI接口指针作为参数。当VM从同一Java线程多次调用本机方法时，保证将VM传递给本机方法。但是，可以从不同的Java线程调用本机方法，因此可以接收不同的JNI接口指针。

编译，加载和链接本机方法

由于Java VM是多线程的，因此本机库也应该与多线程感知的本机编译器一起编译和链接。 例如，-mt标志应该用于使用Sun Studio编译器编译的C++代码。 对于符合GNU gcc编译器的代码，应使用标志-D_REENTRANT或-D_POSIX_C_SOURCE。 有关更多信息，请参阅本机编译器文档。

本机方法使用System.loadLibrary方法加载。 在以下示例中，类初始化方法加载特定于平台的本机库，其中定义了本机方法f：

package pkg;

class Cls {
    native double f(int i, String s);
    static {
        System.loadLibrary("pkg_Cls");
    }
}

System.loadLibrary的参数是程序员任意选择的库名。 系统遵循标准但特定于平台的方法将库名称转换为本机库名称。 例如，Solaris系统将名称pkg_Cls转换为libpkg_Cls.so，而Win32系统将相同的pkg_Cls名称转换为pkg_Cls.dll。

程序员可以使用单个库来存储任意数量的类所需的所有本机方法，只要这些类要使用相同的类加载器加载即可。 VM在内部维护每个类加载器的加载本机库列表。 供应商应选择本地库名称，以尽量减少名称冲突的可能性。

库和版本管理的调用API部分详细介绍了对动态和静态链接库及其各自生命周期管理“加载”和“卸载”函数挂钩的支持。

解析本机方法名称

动态链接器根据其名称解析条目。 本机方法名称由以下组件连接在一起：

• 前缀Java_
• 一个完全限定的类名的别名（mangled name）
• 下划线（“_”）分隔符
• 一个方法名称的别名
• 对于重载的本机方法，两个下划线（“__”）后跟参数签名的别名

VM检查驻留在本机库中的方法的方法名称匹配。 VM首先查找短名称; 也就是说，没有参数签名的名称。 然后它查找长名称，这是带有参数签名的名称。 只有当本机方法使用另一个本机方法重载时，程序员才需要使用长名称。 但是，如果本机方法与非本地方法具有相同的名称，则这不是问题。 非本地方法（Java方法）不驻留在本机库中。

在以下示例中，不必使用长名称链接本机方法g，因为其他方法g不是本机方法，因此不在本机库中。

class Cls1 {
    int g(int i);
    native int g(double d);
}

我们采用了一种简单的别名方案，以确保所有Unicode字符都转换为有效的C函数名称。 我们使用下划线（“_”）字符代替完全限定类名中的斜杠（“/”）。 由于名称或类型描述符从不以数字开头，因此我们可以使用_0，...，_9作为转义序列，如下表所示：

Unicode字符转换

转义序列	表示
_0xxxx	Unicode字符xxxx，表示ASCII字母数字以外的字符（[A-Za-z0-9]）。 请注意，使用小写，例如_0abcd而不是_0ABCD。
_1	字符"_"
_2	签名中的字符";"
_3	签名中的字符"["

本机方法和接口API都遵循给定平台上的标准库调用约定。 例如，UNIX系统使用C调用约定，而Win32系统使用__stdcall。

本机方法参数

JNI接口指针是本机方法的第一个参数。 JNI接口指针的类型为JNIEnv。 第二个参数根据本机方法是静态方法还是非静态方法而有所不同。 非静态本机方法的第二个参数是对该对象的引用。 静态本机方法的第二个参数是对其Java类的引用。

其余参数对应于常规Java方法参数。 本机方法调用通过返回值将其结果传递回调用例程。 第3章：JNI类型和数据结构描述了Java和C类型之间的映射。

以下代码示例说明如何使用C函数实现本机方法f。 本机方法f声明如下：

package pkg;

class Cls {
    native double f(int i, String s);
    // ...
}

具有别名Java_pkg_Cls_f_ILjava_lang_String_2的C函数实现本机方法f：

jdouble Java_pkg_Cls_f__ILjava_lang_String_2 (
     JNIEnv *env,        /* interface pointer */
     jobject obj,        /* "this" pointer */
     jint i,             /* argument #1 */
     jstring s)          /* argument #2 */
{
     /* Obtain a C-copy of the Java string */
     const char *str = (*env)->GetStringUTFChars(env, s, );

     /* process the string */
     ...

     /* Now we are done with str */
     (*env)->ReleaseStringUTFChars(env, s, str);

     return ...
}

请注意，我们总是使用接口指针env操作Java对象。 使用C ++，您可以编写稍微更简洁的代码版本，如以下代码示例所示：

extern "C" /* specify the C calling convention */

jdouble Java_pkg_Cls_f__ILjava_lang_String_2 (

     JNIEnv *env,        /* interface pointer */
     jobject obj,        /* "this" pointer */
     jint i,             /* argument #1 */
     jstring s)          /* argument #2 */

{
     const char *str = env->GetStringUTFChars(s, );

     // ...

     env->ReleaseStringUTFChars(s, str);

     // return ...
}

使用C ++，额外的间接级别和接口指针参数从源代码中消失。 但是，底层机制与C完全相同。在C++中，JNI函数被定义为内联成员函数，它们扩展为C对应函数。

引用Java对象

原始类型（如整数，字符等）在Java和本机代码之间复制。 另一方面，任意Java对象都通过引用传递。 VM必须跟踪已传递给本机代码的所有对象，以便垃圾收集器不会释放这些对象。 反过来，本机代码必须有一种方法来通知VM它不再需要这些对象。 此外，垃圾收集器必须能够移动本机代码引用的对象。

全局和局部引用

JNI将本机代码使用的对象引用分为两类：本地引用和全局引用。本地引用在本机方法调用的持续时间内有效，并在本机方法返回后自动释放。全局引用在显式释放之前仍然有效。

对象作为本地引用传递给本机方法。 JNI函数返回的所有Java对象都是本地引用。 JNI允许程序员从本地引用创建全局引用。期望Java对象接受全局和本地引用的JNI函数。本机方法可以返回对VM的本地或全局引用作为其结果。

在大多数情况下，程序员应该依赖VM在本机方法返回后释放所有本地引用。但是，有时程序员应该明确地释放本地引用。例如，考虑以下情况：

• 本机方法访问大型Java对象，从而创建对Java对象的本地引用。然后，本机方法在返回调用方之前执行其他计算。对大型Java对象的本地引用将阻止对象被垃圾回收，即使该对象不再用于计算的其余部分。
• 本机方法会创建大量本地引用，但并非所有引用都同时使用。由于VM需要一定的空间来跟踪本地引用，因此创建太多本地引用可能会导致系统内存不足。例如，本机方法循环遍历大量对象，将元素作为本地引用检索，并在每次迭代时对一个元素进行操作。在每次迭代之后，程序员不再需要对数组元素的本地引用。

JNI允许程序员在本机方法中的任何点手动删除本地引用。为了确保程序员可以手动释放本地引用，不允许JNI函数创建额外的本地引用，除了它们作为结果返回的引用。

本地引用仅在创建它们的线程中有效。本机代码不能将本地引用从一个线程传递到另一个线程。

实现本地引用

为了实现本地引用，Java VM为从Java到本机方法的每次控制转换创建了一个注册表。 注册表将不可移动的本地引用映射到Java对象，并防止对象被垃圾回收。 传递给本机方法的所有Java对象（包括那些作为JNI函数调用结果返回的对象）都会自动添加到注册表中。 在本机方法返回后删除注册表，允许其所有条目被垃圾回收。

有不同的方法来实现注册表，例如使用表，链表或哈希表。 虽然引用计数可用于避免注册表中的重复条目，但JNI实现没有义务检测和折叠重复条目。

请注意，通过保守扫描本机堆栈，无法忠实地实现本地引用。 本机代码可以将本地引用存储到全局或堆数据结构中。

访问Java对象

JNI在全局和本地引用上提供了一组丰富的访问器函数。 这意味着无论VM如何在内部表示Java对象，相同的本机方法实现都可以工作。 这是JNI可以被各种VM实现支持的关键原因。

通过不透明引用使用访问器函数的开销高于直接访问C数据结构的开销。 我们相信，在大多数情况下，Java程序员使用本机方法来执行非常重要的任务，这些任务会掩盖此接口的开销。

访问原始数组

对于包含许多基本数据类型的大型Java对象（例如整数数组和字符串），此开销是不可接受的。 （考虑用于执行向量和矩阵计算的本机方法。）迭代Java数组并使用函数调用检索每个元素是非常低效的。

一种解决方案引入了“pinning”的概念，以便本机方法可以要求VM确定数组的内容。然后，本机方法接收指向元素的直接指针。然而，这种方法有两个前提：

• 垃圾收集器必须支持pinning。
• VM必须在内存中连续布局原始数组。虽然这是大多数原始数组最自然的实现，但是布尔数组可以实现为打包或解包。因此，依赖于布尔数组的确切布局的本机代码将不可移植。

我们采取妥协方案，克服上述两个问题。

首先，我们提供了一组函数来复制Java数组的一段和本机内存缓冲区之间的原始数组元素。如果本机方法只需要访问大型数组中的少量元素，请使用这些函数。

其次，程序员可以使用另一组函数来检索数组元素的固定版本。请记住，这些功能可能需要Java VM执行存储分配和复制。这些函数实际上是否复制数组取决于VM实现，如下所示：

• 如果垃圾收集器支持固定，并且数组的布局与本机方法的预期相同，则不需要复制。
• 否则，将数组复制到不可移动的内存块（例如，在C堆中）并执行必要的格式转换。返回指向副本的指针。

最后，该接口提供了通知VM本机代码不再需要访问数组元素的功能。当您调用这些函数时，系统会取消数组，或者将原始数组与其不可移动的副本进行协调并释放副本。

我们的方法提供灵活性垃圾收集器算法可以针对每个给定阵列单独决定复制或固定。例如，垃圾收集器可以复制小对象，但可以固定较大的对象。

JNI实现必须确保在多个线程中运行的本机方法可以同时访问同一个数组。例如，JNI可以为每个固定数组保留一个内部计数器，这样一个线程就不会取消固定另一个线程固定的数组。请注意，JNI不需要锁定原始数组以供本机方法独占访问。同时从不同的线程更新Java数组会导致不确定的结果。

访问字段和方法

JNI允许本机代码访问字段并调用Java对象的方法。 JNI通过其符号名称和类型签名来标识方法和字段。 两步过程会从字段名称和签名中分析出定位字段或方法的成本。 例如，要在类cls中调用方法f，本机代码首先获取方法ID，如下所示：

jmethodID mid = env->GetMethodID(cls, "f", "(ILjava/lang/String;)D");

然后，本机代码可以重复使用方法ID，而无需查找方法，如下所示：

jdouble result = env->CallDoubleMethod(obj, mid, , str);

字段或方法ID不会阻止VM卸载已从中派生ID的类。 卸载类后，方法或字段ID变为无效。 因此，如果它打算长时间使用方法或字段ID，本机代码必须确保：

• 保持对基础类的实时引用，或
• 重新计算方法或字段ID。

JNI不对内部如何实现字段和方法ID施加任何限制。

报告编程错误

JNI不检查编程错误，例如传入NULL指针或非法参数类型。非法参数类型包括使用普通Java对象而不是Java类对象。由于以下原因，JNI不检查这些编程错误：

• 强制JNI函数检查所有可能的错误条件会降低正常（正确）本机方法的性能。
• 在许多情况下，没有足够的运行时类型信息来执行此类检查。

大多数C库函数不能防止编程错误。例如，printf（）函数在收到无效地址时通常会导致运行时错误，而不是返回错误代码。强制C库函数检查所有可能的错误条件可能会导致重复此类检查 - 一次在用户代码中，然后再次在库中。

程序员不得将非法指针或错误类型的参数传递给JNI函数。这样做可能会导致任意后果，包括系统状态损坏或VM崩溃。

Java异常

JNI允许本机方法引发任意Java异常。 本机代码也可以处理未完成的Java异常。 未处理的Java异常会传播回VM。

异常和错误代码

某些JNI函数使用Java异常机制来报告错误情况。在大多数情况下，JNI函数通过返回错误代码并抛出Java异常来报告错误情况。错误代码通常是一个特殊的返回值（例如NULL），它超出了正常返回值的范围。因此，程序员可以：

• 快速检查上次JNI调用的返回值，以确定是否发生了错误，并且
• 调用一个函数ExceptionOccurred()来获取包含错误条件的更详细描述的异常对象。

有两种情况，程序员需要检查异常，而无法首先检查错误代码：

• 调用Java方法的JNI函数返回Java方法的结果。程序员必须调用ExceptionOccurred()来检查在执行Java方法期间可能发生的异常。
• 某些JNI数组访问函数不返回错误代码，但可能抛出ArrayIndexOutOfBoundsException或ArrayStoreException。

在所有其他情况下，非错误返回值可确保不会抛出任何异常。

异步异常

一个线程可能通过调用Thread.stop()方法在另一个线程中引发异步异常，该方法自Java 2 SDK 1.2版以来已被弃用。强烈建议程序员不要使用Thread.stop()，因为它通常会导致不确定的应用程序状态。

此外，JVM可能在当前线程中产生异常而不是JNI API调用的直接结果，但是由于各种JVM内部错误，例如：VirtualMachineError，如*Error或OutOfMemoryError。这些也称为异步异常。

异步异常不会立即影响当前线程中本机代码的执行，直到：

• 本机代码调用可能引发同步异常的JNI函数之一，或
• 本机代码使用ExceptionOccurred()显式检查同步和异步异常。

请注意，只有那些可能引发同步异常的JNI函数才会检查异步异常。

本机方法应在必要的位置插入ExceptionOccurred()检查，例如在任何长时间运行的代码中，而不进行其他异常检查（这可能包括紧密循环）。这可确保当前线程在合理的时间内响应异步异常。但是，由于它们的异步性质，在调用之前进行异常检查并不能保证在检查和调用之间不会引发异步异常。

异常处理

有两种方法可以处理本机代码中的异常：

本机方法可以选择立即返回，从而导致在启动本机方法调用的Java代码中抛出异常。
本机代码可以通过调用ExceptionClear()来清除异常，然后执行自己的异常处理代码。
引发异常后，本机代码必须首先清除异常，然后再进行其他JNI调用。 当存在挂起的异常时，可以安全调用的JNI函数是：

ExceptionOccurred()
ExceptionDescribe()
ExceptionClear()
ExceptionCheck()
ReleaseStringChars()
ReleaseStringUTFChars()
ReleaseStringCritical()
Release<Type>ArrayElements()
ReleasePrimitiveArrayCritical()
DeleteLocalRef()
DeleteGlobalRef()
DeleteWeakGlobalRef()
MonitorExit()
PushLocalFrame()
PopLocalFrame()
DetachCurrentThread()

第3章. JNI类型和数据结构

本章讨论JNI如何将Java类型映射到本机C类型。

本章包含以下主题：

• 基本类型
• 引用类型
• 字段和方法ID
• 值类型
• 输入签名
• 修改的UTF-8字符串

基本类型

下表描述Java基本类型及其机器相关的本地等价物。

Primitive Types and Native Equivalents

Java Type	Native Type	Description
boolean	jboolean	unsigned 8 bits
byte	jbyte	signed 8 bits
char	jchar	unsigned 16 bits
short	jshort	signed 16 bits
int	jint	signed 32 bits
long	jlong	signed 64 bits
float	jfloat	32 bits
double	jdouble	64 bits
void	void	not applicable

为方便起见，提供以下定义。

#define JNI_TRUE   1
#define JNI_FALSE  0

jsize整数类型用于描述基数索引和大小：

typedef jint jsize;

引用类型

JNI包含许多与不同类型的Java对象相对应的引用类型。 JNI引用类型按以下层次结构组织：

• jobject
  • jclass (java.lang.Class objects)
  • jstring (java.lang.String objects)
  • jarray (arrays)
    • jobjectArray (object arrays)
    • jbooleanArray (boolean arrays)
    • jbyteArray (byte arrays)
    • jcharArray (char arrays)
    • jshortArray (short arrays)
    • jintArray (int arrays)
    • jlongArray (long arrays)
    • jfloatArray (float arrays)
    • jdoubleArray (double arrays)
  • jthrowable (java.lang.Throwable objects)

在C中，所有其他JNI引用类型都定义为与jobject相同。 例如：

typedef jobject jclass;

在C++中，JNI引入了一组虚拟类来强制执行子类型关系。 例如：

class _jobject {};
class _jclass : public _jobject {};
// ...
typedef _jobject *jobject;
typedef _jclass *jclass;

字段和方法ID

方法和字段ID是常规C指针类型：

struct _jfieldID;              /* opaque structure */
typedef struct _jfieldID *jfieldID;   /* field IDs */

struct _jmethodID;              /* opaque structure */
typedef struct _jmethodID *jmethodID; /* method IDs */

值类型

jvalue 联合体用作参数数组中的元素类型。 声明如下：

typedef union jvalue {
    jboolean z;
    jbyte    b;
    jchar    c;
    jshort   s;
    jint     i;
    jlong    j;
    jfloat   f;
    jdouble  d;
    jobject  l;
} jvalue;

类型签名

JNI使用Java VM的类型签名表示。 下表显示了这些类型签名。

Java VM Type Signatures

类型签名	Java 类型
Z	boolean
B	byte
C	char
S	short
I	int
J	long
F	float
D	double
L fully-qualified-class ;	fully-qualified-class
[ type	type[]
( arg-types ) ret-type	method type

例如，Java方法：

long f (int n, String s, int[] arr);

具有以下类型签名：

(ILjava/lang/String;[I)J

修改的UTF-8字符串

JNI使用修改的UTF-8字符串来表示各种字符串类型。修改后的UTF-8字符串与Java VM使用的字符串相同。对已修改的UTF-8字符串进行编码，以便只包含非空ASCII字符的字符序列可以使用每个字符仅使用一个字节来表示，但可以表示所有Unicode字符。

范围\ u0001到\ u007F中的所有字符都由单个字节表示，如下所示：

• 0xxxxxxx

字节中的七位数据给出了所表示字符的值。

空字符（'\ u0000'）和'\ u0080'到'\ u07FF'范围内的字符由一对字节x和y表示：

• x：110xxxxx
• y：10yyyyyy

字节表示具有值（（x＆0x1f）<< 6）+（y和0x3f）的字符。

'\ u0800'到'\ uFFFF'范围内的字符由3个字节x，y和z表示：

• x：1110xxxx
• y：10yyyyyy
• z：10zzzzzz

具有值（（x＆0xf）<< 12）+（（y＆0x3f）<< 6）+（z＆0x3f）的字符由字节表示。

代码点高于U + FFFF的字符（所谓的补充字符）通过分别编码其UTF-16表示的两个代理代码单元来表示。每个代理代码单元由三个字节表示。这意味着，补充字符由六个字节u，v，w，x，y和z表示：

• u：11101101
• v：1010vvvv
• w：10wwwwww
• x：11101101
• y：1011yyyy
• z：10zzzzzz

值为0x10000 +（（v＆0x0f）<< 16）+（（w＆0x3f）<< 10）+（y＆0x0f）<< 6）+（z＆0x3f）的字符由六个字节表示。

多字节字符的字节以big-endian（高字节优先）顺序存储在类文件中。

此格式与标准UTF-8格式有两点不同。首先，使用双字节格式而不是单字节格式对空字符（char）0进行编码。这意味着修改后的UTF-8字符串永远不会嵌入空值。其次，仅使用标准UTF-8的单字节，双字节和三字节格式。 Java VM无法识别标准UTF-8的四字节格式;它使用自己的两倍三字节格式。

有关标准UTF-8格式的更多信息，请参见Unicode Encoding Forms of The Unicode Standard, Version 4.0的第3.9章。

第4章. JNI函数

本章作为JNI函数的参考部分。它提供了所有JNI功能的完整列表。它还提供了JNI函数表的确切布局。

请注意使用术语“必须”来描述对JNI程序员的限制。例如，当您看到某个JNI函数必须接收非NULL对象时，您有责任确保不将NULL传递给该JNI函数。因此，JNI实现不需要在该JNI函数中执行NULL指针检查。如果不允许显式传递，则传递NULL可能会导致意外异常或致命崩溃。

定义可能都返回NULL并在出错时抛出异常的函数可能只选择返回NULL来指示错误，但不抛出任何异常。例如，JNI实现可能会暂时考虑“内存不足”状态，并且可能不希望抛出OutOfMemoryError，因为这看起来很致命（JDK API java.lang.Error文档：“表示合理的应用程序不应该出现严重问题试着抓住“）。

本章的一部分改编自Netscape的JRI文档。

参考材料按其用法分组。参考部分由以下功能区域组成：

https://docs.oracle.com/en/java/javase/12/docs/specs/jni/functions.html

第5章. Invocation API

Invocation API允许软件供应商将Java VM加载到任意本机应用程序中。 供应商可以提供支持Java的应用程序，而无需链接Java VM源代码。

https://docs.oracle.com/en/java/javase/12/docs/specs/jni/invocation.html