本地方法（JNI）——从java 程序中调用C函数

【0】README

1） 本文部分文字描述 转自 core java volume 2 ， 旨在理解 本地方法——从java 程序中调用C函数 的基础知识 ；
2） for source code, please visit https://github.com/pacosonTang/core-java-volume/tree/master/coreJavaAdvanced/chapter12/javaCassFuncOfC

【1】本地方法相关

1）本地代码定义： 原则上说， 100% 纯 java 的解决方案是非常好的， 但有时你也会想要编写或使用其他语言的代码， 这种代码就称为本地代码；
2）我们建议只有在必需的时候才使用本地代码， 特别是在以下三种情况的时候（cases）：

• c1）你的应用需要访问的系统特性和设备通过java 平台无法实现；
• c2）你已经有了大量的测试过 和 调试过的 用另一种语言编写的代码， 并且知道如何将其导出到所有的目标平台上；
• c3）通过基准测试， 你发现所编写的 java 代码比用另一种语言编写的等价代码要慢很多；

3）java 本地接口（JNI）： java 平台有一个用于和本地C 代码进行交互操作的 API， 称为java 本地接口（JNI）；

---

【2】从java 程序中调用C函数

1） 关键字native： java 使用 native 表示本地方法；

class HelloNative
{  
   public static native void greeting();
}

2）本地方法： 既可以是静态的，也可以是非静态的；
3）为了实现本地代码： 需要编写一个C 函数，你必须完全按照 java 虚拟机预期的那样来命名这个函数。 其规则是（rules）：

• r1）使用完整的java 方法名：

  如 HelloNative.greeting; 如果属于某个包还要添加包名， 如 com.corejava.HelloNative.greeting；

• r2）用下划线替换掉所有的句号， 并加上 Java_前缀， 如：

  Java_com_corejava_HelloNative_greeting；

• r3）如果类名含有非 ASCII 字母或数字：

  如：’_’, ‘$’ 或是 大于 ‘\u007F’ 的 unicode 字符，用_0xxxx 来替代它们， xxxx 是该字符的unicode 值的 4个十六进制数序列；

Attention）

• A1）如果你重载本地方法， 也就是说， 你用相同的名字提供多个本地方法， 那么你必须在名称后面附加两个下划线， 后面再加上已编码的参数类型；
• A2） 看个荔枝：　如果你有一个本地方法　greeting 和 本地方法 greeting(int repeat)， 那么第一个称为 Java_HelloNative_greeting__， 第二个称为 Java_HelloNative_greeting_I；
• A3）javah程序：没有人完成这些手工操作， javah 自动生成函数名；

4）java程序调用C函数的实现steps:

• （javah导出类的头文件可能抛出异常——java.lang.IllegalArgumentException: Not a valid class name， for solution, please visit http://blog.csdn.net/pacosonswjtu/article/details/50615988）

• step1）用 javah 生成函数名：

• 

• 

• 对以上代码的分析（Analysis）：

  • A1） 这个头文件包含了函数 Java_HelloNative_greeting 的声明；
  • A2） 字符串 JNIEXPORT 和 JNICALL 是在头文件 jni.h 中定义的， 他们为那些来自动态装载库的导出函数标明了 依赖于编译器的说明符；

• step2）现在，需要将 函数原型从头文件中 复制到源文件中， 并且给出函数的实现代码（新建 HelloNative.c）；
  

• step3） 将本地C 代码编译到一个动态装载库中， 具体方法依赖于编译器；

  • step3.1） Linux 下的 GNU C 编译器：

    使用如下命令：(1) gcc -fPIC -I jdk/include -I jdk/include/linux -shared -o libHelloNative.so HelloNative.c 或
    (2.1) gcc -c -I /usr/java/jdk1.7/include/ -I /usr/java/jdk1.7/include/linux/ HelloNative.c
    (2.2) gcc -shared -fPIC -o HelloNative.so HelloNative.o

  • step3.2）使用windows 下的微软编译器：

    命令是： cl -I jdk/include -I >jdk/include/win32 -LD HelloNative.c -FeHelloNative.dll

  • step3.3）通过cygwin 环境下 将本地C 代码编译到动态装载库中：

    gcc -mno-cygwin -D __int64=”long long” -I jdk/include/win32 -shared -Wl, –add-stdcall-alias -o HelloNative.dll HelloNative.c

• step4） 最后，我们要在程序中添加 一个对 System.loadLibrary 方法的调用。为了确保虚拟机第一次使用该类之前就会装载这个库， 需要使用 静态初始化代码块。 如下所示：
  

Attention）如果运行在 Linux 下， 必须把当前目录添加到库路径中。

• A1）实现的方式可以是通过设置 LD_LIBRARY_PATH 环境变量：

  export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH

• A2）或者是设置 java.library.path 系统属性：

  java -Djava.library.path=. HelloNativeTest

Conclusion） 总之，遵循下面的steps就可以将一个本地方法链接到 java 程序中：

• step1）在 java类中声明一个本地方法；

  package com.corejava.chapter12;
  
  public class HelloNative
  {  
     public static native void greeting();
  }
  

• step2） 运行javah 以获得包含该方法的 C 声明的头文件；

• step2.1）编译文件： javac com/corejava/chapter12/HelloNative.java

• step2.2）javah生成该类的头文件： javah com.corejava.chapter12.HelloNative
  

step3） 用 C 实现该本地方法：

• step3.1）将 相应的方法原型（返回类型，方法名，参数列表） copy 到 .c 文件中，并实现该方法）：

#include "com_corejava_chapter12_HelloNative.h"
#include <stdio.h>
JNIEXPORT void JNICALL Java_com_corejava_chapter12_HelloNative_greeting(JNIEnv * env, jclass) 
{
 printf("hello world ! this greeting is from native method by C");
}

• 

• step3.2）在linux环境下， 将本地C 代码编译到动态装载库中

  gcc -c -I /usr/java/jdk1.7/include/ -I /usr/java/jdk1.7/include/linux/ HelloNative.c
  gcc -shared -fPIC -o libHelloNative.so HelloNative.o

• step4）将代码置于 共享类库中；
  

• 

• step5） 在 java 程序中 加载该类库（java类中的main调用C函数）
  

  • Warning） 这里运行可能出错，throw exception ： java.lang.UnsatisfiedLinkError: no yourClassName in java.library.path ， 这也就是 为什么本文先打印出了 java.library.path， 然后将 libHelloNative.so 添加到该共享库中的原因；当然了， for detailed spec , you can also refer to http://blog.csdn.net/pacosonswjtu/article/details/50618033

Conclusion） 最后的工作目录文件列表如下：