JNI 最简单例程步骤详解

1、javah命令帮助信息

　　用法：javah [选项] <类>

　　zhengchuanyu@CLAY:~/Projects/helloworldJNI/src$ javah
　　Usage:
　　javah [options] <classes>
　　where [options] include:
　　　　-o <file> Output file (only one of -d or -o may be used) 　　（输出文件（ -d 或者 -o 参数只能使用其中的一个，并且必须在其他选项之前使用，否则出现不可预测的错误））
　　　　-d <dir> Output directory　　　　　　　　　　　　　　　 （输出目录）
　　　　-v -verbose Enable verbose output　　　　　　　　　　   （启用详细输出）
　　　　-h --help -? Print this message　　　　　　　　　　　　  （输出此帮助消息并退出）
　　　　-version Print version information　　　　　　　　　　　 （输出版本信息）
　　　　-jni Generate JNI-style header file (default)　　　　　　    （生成JNI样式的头文件（默认））
　　　　-force Always write output files　　　　　　　　　　　　 （强制始终写输出文件）
　　　　-classpath <path> Path from which to load classes　　　  （用于加载类的路径）
　　　　-cp <path> Path from which to load classes　　　　　　  （-cp <path> 要从其中装入类的路径）
　　　　-bootclasspath <path> Path from which to load bootstrap classes（从中加载引导类的路径）
　　<classes> are specified with their fully qualified names　　　　　　（classes 必须用完全限定名来指定）
　　(for example, java.lang.Object).

2、用javah产生一个.h文件

　　Java不是完善的，Java的不足除了体现在运行速度上要比传统的C++慢许多之外，Java无法直接造访到操作体系底层（如系统硬件等)，为此 Java使用native法子来扩大Java程序的功效。可以将native法子比作Java程序同Ｃ程序的接口，其实现步骤：

• １、在Java中声明native()方式，然后编译；
• ２、用javah发生一个.h文件；
• ３、写一个.cpp文件实现native导出方式，其中须要包括第二步发生的.h文件（注意其中又包孕了JDK带的jni.h文件）
• ４、将第三步的.cpp文件编译成动态链接库文件；
• ５、在Java中用System.loadLibrary()法子加载第四步发生的动态链接库文件，这个native()办法就可以在Java中被拜访了。

　　JAVA本地办法实用的情形

• 1.为了使用底层的主机平台的某个特性，而这个特性不能通过JAVA API拜访
• 2.为了拜访一个老的体系或者使用一个已有的库，而这个体系或这个库不是用JAVA编写的
• 3.为了加快程序的性能，而将一段时光敏感的代码作为本地方式实现。

　　首先写好JAVA文件

package com.clay.example;

public class HelloWorld {
    static {
        System.loadLibrary("Hello");
    }

    public native void DisplayHello();

    public static void main(String[] args) {
        new HelloWorld().DisplayHello();
    }

}

　　然后依据写好的文件编译成CLASS文件

　　命令：javac com/clay/example/HelloWorld.java

　　在 HelloWorld.java 所处目录的根目录执行 命令：javah -d ./jniDir/ -classpath ./ -jni -v com.clay.example.HelloWorld

　　然后依据头文件的内容编写 jni_helloworldImpl.cpp 文件

#include <jni.h>
#include "com_clay_example_HelloWorld.h"
#include <stdio.h>

JNIEXPORT void JNICALL Java_com_clay_example_HelloWorld_DisplayHello
(JNIEnv *env, jobject obj)
{
    printf("From jni_helloworldImpl : Hello World! 
");
}

　　最后编译最终的动态库文件，命令：g++ -shared -fPIC -I /opt/jdk1.8.0_221/include/ -I /opt/jdk1.8.0_221/include/linux/ jni_helloworldImpl.cpp -o libHello.so

　　执行命令：java -Djava.library.path=jniDir/ com.clay.example.HelloWorld，此命令需要在 HelloWorld.java 的根目录执行

　　-Djava.library.path=jniDir/ 是用来指定动态库的具体路径

3、JNI 例程

　　Java 本机接口（Java Native Interface (JNI)）是一个本机编程接口，它是 Java 软件开发工具箱（Java Software Development Kit (SDK)）的一部分。

　　JNI 允许 Java 代码使用以其它语言（譬如 C 和 C++）编写的代码和代码库。Invocation API（JNI 的一部分）可以用来将 Java 虚拟机（JVM）嵌入到本机应用程序中，从而允许程序员从本机代码内部调用 Java 代码。

　　本例程涉及 JNI 最常见的两个应用：从 Java 程序调用 C/C++，以及从 C/C++ 程序调用 Java 代码。我们将讨论 Java 本机接口的这两个基本部分以及可能出现的一些更高级的编程难题。

　　本例程将带您去了解使用 Java 本机接口的所有步骤。您将学习如何从 Java 应用程序内部调用本机 C/C++ 代码以及如何从本机 C/C++ 应用程序内部调用 Java 代码。

　　所有示例都是使用 Java、C 和 C++ 代码编写的，并可以移植到 Windows 和基于 UNIX 的平台上。要完全理解这些示例，您必须有一些 Java 语言编程经验。此外，您还需要一些 C 或 C++ 编程经验。严格来说，JNI 解决方案可以分成 Java 编程任务和 C/C++ 编程任务，由不同的程序员完成每项任务。然而，要完全理解 JNI 是如何在两种编程环境中工作的，您必须能够理解 Java 和 C/C++ 代码。

　　我们还将讲述一些高级主题，包括本机方法的异常处理和多线程。要充分理解本教程，您应该熟悉 Java 平台的安全性模型，并有一些多线程应用程序开发的经验。

　　这里将关于高级主题的节从较基本的循序渐进 JNI 简介中划分出来。现在，初级 Java 程序员可以先学习本教程的前两部分，掌握之后再开始学习高级主题。

　　要运行本教程中的示例，您需要下列工具与组件：

• Java 编译器：随 SDK 一起提供的 javac.exe。
• Java 虚拟机（JVM）：随 SDK 一起提供的 java.exe。
• 本机方法 C 文件生成器：随 SDK 一起提供的 javah.exe。
• 定义 JNI 的库文件和本机头文件。jni.h C 头文件、jvm.lib 和 jvm.dll 或 jvm.so 文件，这些文件都是随 SDK 一起提供的。
• 能够创建共享库的 C 和 C++ 编译器。最常见的两个 C 编译器是用于 Windows 的 Visual C++ 和用于基于 UNIX 系统的 cc。

　　虽然您可以使用自己喜欢的任何开发环境，但我们将在本教程中使用示例是用随 SDK 一起提供的标准工具和组件编写的。请参阅参考资料来下载 SDK、完整的源文件以及对于完成本教程不可缺少的其它工具。本教程具体地解释了 Sun 的 JNI 实现，该实现被认为是 JNI 解决方案的标准。本教程中没有讨论其它 JNI 实现的详细信息。

　　在 Java 2 SDK 中，JVM 和运行时支持位于名为 jvm.dll（Windows）或 libjvm.so（UNIX）的共享库文件中。在 Java 1.1 JDK 中，JVM 和运行时支持位于名为 javai.dll（Windows）或 libjava.so（UNIX）的共享库文件中。版本 1.1 的共享库包含运行时以及类库的一些本机方法，但在版本 1.2 中已经不包含运行时，并且本机方法被放在 java.dll 和 libjava.so 中。对于以下 Java 代码，这一变化很重要：

• 代码是用非 JNI 本机方法编写的（因为使用了 JDK 1.0 中旧的本机方法接口）
• 通过 JNI Invocation 接口使用了嵌入式 JVM

　　在两种情况下，在您的本机库能与版本 1.2 一起使用之前，都必须重新链接它们。注：这个变化应该不影响 JNI 程序员实现本机方法 — 只有通过 Invocation API调用 JVM 的 JNI 代码才会受到影响。

　　如果使用随 SDK/JDK 一起提供的 jni.h 文件，则头文件将使用 SDK/JDK 安装目录中的缺省 JVM（jvm.dll 或 libjvm.so）。支持 JNI 的 Java 平台的任何实现都会这么做，或允许您指定 JVM 共享库；然而，完成这方面操作的细节可能会因具体 Java 平台／JVM 实现而有所不同。实际上，许多 JVM 实现根本不支持 JNI。

用Java调用C/C++代码

　　当无法用 Java 语言编写整个应用程序时，JNI 允许您使用本机代码。在下列典型情况下，您可能决定使用本机代码：

• 希望用更低级、更快的编程语言去实现对时间有严格要求的代码。
• 希望从 Java 程序访问旧代码或代码库。
• 需要标准 Java 类库中不支持的依赖于平台的特性。

从 Java 代码调用 C/C++ 的六个步骤

　　从 Java 程序调用 C 或 C ++ 代码的过程由六个步骤组成。我们将在下面几页中深入讨论每个步骤，但还是先让我们迅速地浏览一下它们。

1. 编写 Java 代码。我们将从编写 Java 类开始，这些类执行三个任务：声明将要调用的本机方法；装入包含本机代码的共享库；然后调用该本机方法。
2. 编译 Java 代码。在使用 Java 类之前，必须成功地将它们编译成字节码。
3. 创建 C/C++ 头文件。C/C++ 头文件将声明想要调用的本机函数说明。然后，这个头文件与 C/C++ 函数实现（请参阅步骤 4）一起来创建共享库（请参阅步骤 5）。
4. 编写 C/C++ 代码。这一步实现 C 或 C++ 源代码文件中的函数。C/C++ 源文件必须包含步骤 3 中创建的头文件。
5. 创建共享库文件。从步骤 4 中创建的 C 源代码文件来创建共享库文件。
6. 运行 Java 程序。运行该代码，并查看它是否有用。我们还将讨论一些用于解决常见错误的技巧。

步骤 1：编写 Java 代码

　　我们从编写 Java 源代码文件开始，它将声明本机方法（或方法），装入包含本机代码的共享库，然后实际调用本机方法。

　　这里是名为 Sample1.java 的 Java 源代码文件的示例：

package com.clay.example;
public class Sample1 {
    public native int intMethod(int n);
    public native boolean booleanMethod(boolean bool);
    public native String stringMethod(String text);
    public native int intArrayMethod(int[] intArray);

    static {
        System.loadLibrary("Sample1");
    }

    public static void main(String[] args) {
        Sample1 sample1 = new Sample1();

        int square = sample1.intMethod(5);
        boolean bool = sample1.booleanMethod(true);
        String text = sample1.stringMethod("JAVA");
        int sum = sample1.intArrayMethod(new int[] {1, 1, 2, 3, 5, 8, 13});

        System.out.println("intMethod: " + square);
        System.out.println("booleanMethod: " + bool);
        System.out.println("stringMethod: " + text);
        System.out.println("intArrayMethod: " + sum);
    }
}

这段代码做了些什么？

　　首先，请注意对 native 关键字的使用，它只能随方法一起使用。native 关键字告诉 Java 编译器：方法是用 Java 类之外的本机代码实现的，但其声明却在 Java 中。只能在 Java 类中声明本机方法，而不能实现它（但是不能声明为抽象的方法，使用native关键字即可），所以本机方法不能拥有方法主体。

　　现在，让我们逐行研究一下代码：

• 　　从第 3 行到第 6 行，我们声明了四个 native 方法。
• 　　在第 8 - 10 行，我们装入了包含这些本机方法的实现的共享库文件。（到步骤 5 时，我们将创建该共享库文件。）
• 　　最终，从第 15 行到第 18 行，我们调用了本机方法。注：这个操作和调用非本机 Java 方法的操作没有差异。

注：基于 UNIX 的平台上的共享库文件通常含有前缀“lib”。在本例中，第 10 行可能是 System.loadLibrary("libSample1");。请一定要注意您在步骤 5：创建共享库文件中生成的共享库文件名。

步骤 2：编译 Java 代码

　　接下来，我们需要将 Java 代码编译成字节码。完成这一步的方法之一是使用随 SDK 一起提供的 Java 编译器 javac。用来将 Java 代码编译成字节码的命令是：

zhengchuanyu@CLAY:~/Projects/sample1/src/com/clay/example$ javac Sample1.java

步骤 3：创建 C/C++ 头文件

　　第三步是创建 C/C++ 头文件，它定义本机函数说明。完成这一步的方法之一是使用 javah.exe，它是随 SDK 一起提供的本机方法 C 存根生成器工具。这个工具被设计成用来创建头文件，该头文件为在 Java 源代码文件中所找到的每个 native 方法定义 C 风格的函数。这里使用的命令是：

　　javah -d build/jni/ -classpath src/ -jni -v com.clay.example.Sample1

　　（javah -d <path>(要生成的.h文件的目录) -classpath <path>(类所在的根目录) -jni -v(输出详细信息)）

生成的 .h 文件

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class com_clay_example_Sample1 */

#ifndef _Included_com_clay_example_Sample1
#define _Included_com_clay_example_Sample1
#ifdef __cplusplus
extern "C" {
#endif
/*
 * Class:     com_clay_example_Sample1
 * Method:    intMethod
 * Signature: (I)I
 */
JNIEXPORT jint JNICALL Java_com_clay_example_Sample1_intMethod
  (JNIEnv *, jobject, jint);

/*
 * Class:     com_clay_example_Sample1
 * Method:    booleanMethod
 * Signature: (Z)Z
 */
JNIEXPORT jboolean JNICALL Java_com_clay_example_Sample1_booleanMethod
  (JNIEnv *, jobject, jboolean);

/*
 * Class:     com_clay_example_Sample1
 * Method:    stringMethod
 * Signature: (Ljava/lang/String;)Ljava/lang/String;
 */
JNIEXPORT jstring JNICALL Java_com_clay_example_Sample1_stringMethod
  (JNIEnv *, jobject, jstring);

/*
 * Class:     com_clay_example_Sample1
 * Method:    intArrayMethod
 * Signature: ([I)I
 */
JNIEXPORT jint JNICALL Java_com_clay_example_Sample1_intArrayMethod
  (JNIEnv *, jobject, jintArray);

#ifdef __cplusplus
}
#endif
#endif

关于 C/C++ 头文件

　　正如您可能已经注意到的那样，Sample1.h 中的 C/C++ 函数说明和 Sample1.java 中的 Java native 方法声明有很大差异。JNIEXPORT 和 JNICALL 是用于导出函数的、依赖于编译器的指示符。返回类型是映射到 Java 类型的 C/C++ 类型。附录 A：JNI 类型中完整地说明了这些类型。

　　除了 Java 声明中的一般参数以外，所有这些函数的参数表中都有一个指向 JNIEnv 和 jobject 的指针。指向 JNIEnv 的指针实际上是一个指向函数指针表的指针。正如将要在步骤 4 中看到的，这些函数提供各种用来在 C 和 C++ 中操作 Java 数据的能力。

　　jobject 参数引用当前对象。因此，如果 C 或 C++ 代码需要引用 Java 函数，则这个 jobject 充当引用或指针，返回调用的 Java 对象。函数名本身是由前缀“Java_”加全限定类名，再加下划线和方法名构成的。

JNI类型

　　JNI 使用几种映射到 Java 类型的本机定义的 C 类型。这些类型可以分成两类：原始类型和伪类（pseudo-classes）。在 C 中，伪类作为结构实现，而在 C++ 中它们是真正的类。

　　Java 原始类型直接映射到 C 依赖于平台的类型，如下所示：

　　C 类型 jarray 表示通用数组。在 C 中，所有的数组类型实际上只是 jobject 的同义类型。但是，在 C++ 中，所有的数组类型都继承了 jarray，jarray 又依次继承了 jobject。下列表显示了 Java 数组类型是如何映射到 JNI C 数组类型的。

　　这里是一棵对象树，它显示了 JNI 伪类是如何相关的。

步骤 4：编写 C/C++ 代码

　　当谈到编写 C/C++ 函数实现时，有一点需要牢记：说明必须和 Sample1.h 的函数声明完全一样。我们将研究用于 C 实现和 C++ 实现的完整代码，然后讨论两者之间的差异。

C函数实现

#include "com_clay_example_Sample1.h"

#include <stdio.h>
#include <string.h>

JNIEXPORT jint JNICALL Java_com_clay_example_Sample1_intMethod
(JNIEnv *env, jobject obj, jint num) 
{
    return num * num;
}

JNIEXPORT jboolean JNICALL Java_com_clay_example_Sample1_booleanMethod
(JNIEnv *env, jobject obj, jboolean boolean) 
{
    return !boolean;
}

JNIEXPORT jstring JNICALL Java_com_clay_example_Sample1_stringMethod
(JNIEnv *env, jobject obj, jstring string) 
{
    const char *str = (*env)->GetStringUTFChars(env, string, 0);

    char cap[128];

    strcpy(cap, str);

    (*env)->ReleaseStringUTFChars(env, string, str);

    return (*env)->NewStringUTF(env, strupr(cap));
}

JNIEXPORT jint JNICALL Java_com_clay_example_Sample1_intArrayMethod
(JNIEnv *env, jobject obj, jintArray array) 
{
    int i, sum = 0;

    jsize len = (*env)->GetArrayLength(env, array);

    jint *body = (*env)->GetIntArrayElements(env, array, 0);

    for (i=0; i<len; i++)
    {   
        sum += body[i];
    }

    (*env)->ReleaseIntArrayElements(env, array, body, 0);

    return sum;
}

C++ 函数实现

以下是 jni_sample1.cpp（C++ 实现）

#include "com_clay_example_Sample1.h"

#include <string.h>

JNIEXPORT jint JNICALL Java_com_clay_example_Sample1_intMethod
(JNIEnv *env, jobject obj, jint num) {

   return num * num;
}

JNIEXPORT jboolean JNICALL Java_com_clay_example_Sample1_booleanMethod
(JNIEnv *env, jobject obj, jboolean boolean) {

   return !boolean;
}

JNIEXPORT jstring JNICALL Java_com_clay_example_Sample1_stringMethod
(JNIEnv *env, jobject obj, jstring string) {

    const char *str = env->GetStringUTFChars(string, 0);

    char cap[128];

    strcpy(cap, str);

    env->ReleaseStringUTFChars(string, str);

    return env->NewStringUTF(strupr(cap));
}

JNIEXPORT jint JNICALL Java_com_clay_example_Sample1_intArrayMethod
(JNIEnv *env, jobject obj, jintArray array) {

    int i, sum = 0;

    jsize len = env->GetArrayLength(array);

    jint *body = env->GetIntArrayElements(array, 0);

    for (i=0; i<len; i++)
    {   
        sum += body[i];
    }

    env->ReleaseIntArrayElements(array, body, 0);

    return sum;
}

C 和 C++ 函数实现的比较

　　唯一的差异在于用来访问 JNI 函数的方法。在 C 中，JNI 函数调用由“(*env)->”作前缀，目的是为了取出函数指针所引用的值。在 C++ 中，JNIEnv 类拥有处理函数指针查找的内联成员函数。下面将说明这个细微的差异，其中，这两行代码访问同一函数，但每种语言都有各自的语法。

　　C 语法：jsize len = (*env)->GetArrayLength(env,array);

　　C++ 语法：jsize len =env->GetArrayLength(array);

步骤 5：创建共享库文件

　　接下来，我们创建包含本机代码的共享库文件。大多数 C 和 C++ 编译器除了可以创建机器代码可执行文件以外，也可以创建共享库文件。用来创建共享库文件的命令取决于您使用的编译器。下面是在 Windows 和 Solaris 系统上执行的命令。

Linux：gcc -shared -fPIC -I /opt/jdk1.8.0_221/include/ -I /opt/jdk1.8.0_221/include/linux/ jni_sample1.c -o libSample1.so

步骤 6：运行 Java 程序

　　最后一步是运行 Java 程序，并确保代码正确工作。因为必须在 Java 虚拟机中执行所有 Java 代码，所以需要使用 Java 运行时环境。完成这一步的方法之一是使用 java，它是随 SDK 一起提供的 Java 解释器。所使用的命令是：

　　java -Djava.library.path=../build/jni/ com.clay.example.Sample1

　　当运行 Sample1.class 程序时，应该获得下列结果：

　　PROMPT>java Sample1

　　intMethod: 25

　　booleanMethod: false

　　stringMethod: JAVA

　　intArrayMethod: 33

　　PROMPT>

故障排除

　　当使用 JNI 从 Java 程序访问本机代码时，您会遇到许多问题。您会遇到的三个最常见的错误是：

• 　　无法找到动态链接。它所产生的错误消息是：java.lang.UnsatisfiedLinkError。这通常指无法找到共享库，或者无法找到共享库内特定的本机方法。
• 　　无法找到共享库文件。当用 System.loadLibrary(String libname) 方法（参数是文件名）装入库文件时，请确保文件名拼写正确以及没有指定扩展名。还有，确保库文件的位置在类路径中，从而确保 JVM 可以访问该库文件。
• 　　无法找到具有指定说明的方法。确保您的 C/C++ 函数实现拥有与头文件中的函数说明相同的说明。

　　从 Java 调用 C 或 C++ 本机代码（虽然不简单）是 Java 平台中一种良好集成的功能。虽然 JNI 支持 C 和 C++，但 C++ 接口更清晰一些并且通常比 C 接口更可取。

　　正如您已经看到的，调用 C 或 C++ 本机代码需要赋予函数特殊的名称，并创建共享库文件。当利用现有代码库时，更改代码通常是不可取的。要避免这一点，在 C++ 中，通常创建代理代码或代理类，它们有专门的 JNI 所需的命名函数。然后，这些函数可以调用底层库函数，这些库函数的说明和实现保持不变。