本地方法（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