在Windows中实现Java本地方法

在Windows 中实现Java 本地方法David WendtWebSphere DevelopmentResearch Triangle Park, NC1999 年5 月摘要本文为在 32 位 Windows 平台上实现 Java 本地方法提供了实用的示例步骤和准则这些示例包括传递和返回常用的数据类型本文中的示例使用 Sun Microsystems 公司创建的 Java Development Kit (JDK) 版本 1.1.6 和 Java 本地接口 (JNI) 规范用 C 语言编写的本地代码是用 Microsoft Visual C++ 编译器编译生成的简介本文提供调用本地 C 代码的 Java 代码示例包括传递和返回某些常用的数据类型本地方法包含在特定于平台的可执行文件中就本文中的示例而言本地方法包含在 Windows 32 位动态链接库 (DLL) 中不过我要提醒您对 Java 外部的调用通常不能移植到其他平台上在 applet 中还可能引发安全异常实现本地代码将使您的 Java 应用程序无法通过 100% 纯 Java 测试但是如果必须执行本地调用则要考虑几个准则1. 将您的所有本地方法都封装在单个类中这个类调用单个 DLL对于每种目标操作系统都可以用特定于适当平台的版本替换这个 DLL这样就可以将本地代码的影响减至最小并有助于将以后所需的移植问题包含在内2. 本地方法要简单尽量将您的 DLL 对任何第三方包括 Microsoft运行时 DLL 的依赖减到最小使您的本地方法尽量独立以将加载您的 DLL 和应用程序所需的开销减到最小如果需要运行时DLL必须随应用程序一起提供它们Java 调用 C对于调用 C 函数的 Java 方法必须在 Java 类中声明一个本地方法在本部分的所有示例中我们将创建一个名为 MyNative 的类并逐步在其中加入新的功能这强调了一种思想即将本地方法集中在单个类中以便将以后所需的移植工作减到最少示例 1 -- 传递参数在第一个示例中我们将三个常用参数类型传递给本地函数String int 和 boolean本例说明在本地 C 代码中如何引用这些参数public class MyNative{public void showParms( String s, int i, boolean b ){showParms0( s, i , b );}private native void showParms0( String s, int i, boolean b );static{System.loadLibrary( "MyNative" );}}请注意本地方法被声明为专用的并创建了一个包装方法用于公用目的这进一步将本地方法同代码的其余部分隔离开来从而允许针对所需的平台对它进行优化static 子句加载包含本地方法实现的 DLL下一步是生成 C 代码来实现 showParms0 方法此方法的 C 函数原型是通过对 .class 文件使用 javah 实用程序来创建的而 .class 文件是通过编译 MyNative.java 文件生成的这个实用程序可在 JDK 中找到下面是 javah 的用法javac MyNative.java将 .java 编译为 .classjavah -jniMyNative生成 .h 文件这将生成一个 MyNative.h 文件其中包含一个本地方法原型如下所示/** Class: MyNative* Method: showParms0* Signature: (Ljava/lang/String;IZ)V*/JNIEXPORT void JNICALL Java_MyNative_showParms0(JNIEnv *, jobject, jstring, jint, jboolean);第一个参数是调用 JNI 方法时使用的 JNI Environment 指针第二个参数是指向在此 Java 代码中实例化的 Java 对象 MyNative 的一个句柄其他参数是方法本身的参数请注意MyNative.h 包括头文件 jni.h jni.h 包含 JNI API 和变量类型包括jobject jstringjint jboolean等等的原型和其他声明本地方法是在文件 MyNative.c 中用 C 语言实现的#include <stdio.h>#include "MyNative.h"JNIEXPORT void JNICALL Java_MyNative_showParms0(JNIEnv *env, jobject obj, jstring s, jint i, jboolean b){const char* szStr = (*env)->GetStringUTFChars( env, s, 0 );printf( "String = [%s]\n", szStr );printf( "int = %d\n", i );printf( "boolean = %s\n", (b==JNI_TRUE ? "true" : "false") );(*env)->ReleaseStringUTFChars( env, s, szStr );}JNI API GetStringUTFChars用来根据 Java 字符串或 jstring 参数创建 C 字符串这是必需的因为在本地代码中不能直接读取 Java 字符串而必须将其转换为 C 字符串或 Unicode有关转换 Java 字符串的详细信息请参阅标题为 NLS Strings and JNI 的一篇论文但是jboolean 和 jint 值可以直接使用MyNative.dll 是通过编译 C 源文件创建的下面的编译语句使用 Microsoft Visual C++ 编译器cl -Ic:\jdk1.1.6\include -Ic:\jdk1.1.6\include\win32 -LD MyNative.c-FeMyNative.dll其中 c:\jdk1.1.6 是 JDK 的安装路径MyNative.dll 已创建好现在就可将其用于 MyNative 类了可以这样测试这个本地方法在 MyNative 类中创建一个 main 方法来调用 showParms 方法如下所示public static void main( String[] args ){MyNative obj =new MyNative();obj.showParms( "Hello", 23, true );obj.showParms( "World", 34, false );}当运行这个 Java 应用程序时请确保 MyNative.dll 位于 Windows 的 PATH 环境变量所指定的路径中或当前目录下当执行此 Java 程序时如果未找到这个 DLL您可能会看到以下的消息java MyNativeCan't find class MyNative这是因为 static 子句无法加载这个 DLL所以在初始化 MyNative 类时引发异常Java 解释器处理这个异常并报告一个一般错误指出找不到这个类如果用 -verbose 命令行选项运行解释器您将看到它因找不到这个 DLL 而加载 UnsatisfiedLinkError 异常如果此 Java 程序完成运行就会输出以下内容java MyNativeString = [Hello]int = 23boolean = trueString = [World]int= 34boolean = false示例 2 -- 返回一个值本例将说明如何在本地方法中实现返回代码将这个方法添加到 MyNative 类中这个类现在变为以下形式public class MyNative{public void showParms( String s, int i, boolean b ){showParms0( s, i , b );}public int hypotenuse( int a, int b ){return hyptenuse0( a, b );}private native void showParms0( String s, int i, boolean b );private native int hypotenuse0( int a, int b );static{System.loadLibrary( "MyNative" );}/* 测试本地方法 */public static void main( String[] args )MyNative obj =new MyNative();System.out.println( obj.hypotenuse(3,4) );System.out.println( obj.hypotenuse(9,12) );}}公用的 hypotenuse 方法调用本地方法 hypotenuse0 来根据传递的参数计算值并将结果作为一个整数返回这个新本地方法的原型是使用 javah 生成的请注意每次运行这个实用程序时它将自动覆盖当前目录中的 MyNative.h按以下方式执行 javahjavah -jni MyNative生成的 MyNative.h 现在包含 hypotenuse0 原型如下所示/** Class: MyNative* Method: hypotenuse0* Signature: (II)I*/JNIEXPORT jint JNICALL Java_MyNative_hypotenuse0(JNIEnv *, jobject, jint, jint);该方法是在 MyNative.c 源文件中实现的如下所示#include <stdio.h>#include <math.h>#include "MyNative.h"JNIEXPORT void JNICALL Java_MyNative_showParms0(JNIEnv *env, jobject obj, jstring s, jint i, jboolean b){const char* szStr = (*env)->GetStringUTFChars( env, s, 0 );printf( "String = [%s]\n", szStr );printf( "int = %d\n", i );printf( "boolean = %s\n", (b==JNI_TRUE ? "true" : "false") );(*env)->ReleaseStringUTFChars( env, s, szStr );}JNIEXPORT jint JNICALL Java_MyNative_hypotenuse0(JNIEnv *env, jobject obj, jint a, jint b)int rtn = (int)sqrt( (double)( (a*a) + (b*b) ) );return (jint)rtn;}再次请注意jint 和 int 值是可互换的使用相同的编译语句重新编译这个 DLLcl -Ic:\jdk1.1.6\include -Ic:\jdk1.1.6\include\win32 -LD MyNative.c-FeMyNative.dll现在执行 java MyNative 将输出 5 和 15 作为斜边的值示例 3 -- 静态方法您可能在上面的示例中已经注意到实例化的 MyNative 对象是没必要的实用方法通常不需要实际的对象通常都将它们创建为静态方法本例说明如何用一个静态方法实现上面的示例更改 MyNative.java 中的方法签名以使它们成为静态方法public static int hypotenuse( int a, int b ){return hypotenuse0(a,b);}...private static native int hypotenuse0( int a, int b );现在运行 javah 为 hypotenuse0 创建一个新原型生成的原型如下所示/** Class: MyNative* Method: hypotenuse0* Signature: (II)I*/JNIEXPORT jint JNICALL Java_MyNative_hypotenuse0(JNIEnv *, jclass, jint, jint);C 源代码中的方法签名变了但代码还保持原样JNIEXPORT jint JNICALL Java_MyNative_hypotenuse0(JNIEnv *env, jclass cls, jint a, jint b){int rtn = (int)sqrt( (double)( (a*a) + (b*b) ) );return (jint)rtn;}本质上jobject 参数已变为 jclass 参数此参数是指向 MyNative.class 的一个句柄main 方法可更改为以下形式public static void main( String[] args ){System.out.println( MyNative.hypotenuse( 3, 4 ) );System.out.println( MyNative.hypotenuse( 9, 12 ) );}因为方法是静态的所以调用它不需要实例化 MyNative 对象本文后面的示例将使用静态方法示例 4 -- 传递数组本例说明如何传递数组型参数本例使用一个基本类型boolean并将更改数组元素下一个示例将访问 String非基本类型数组将下面的方法添加到 MyNative.java 源代码中public static void setArray( boolean[] ba ){for( int i=0; i < ba.length; i++ )ba[i] = true;setArray0( ba );}...private static native void setArray0( boolean[] ba );在本例中布尔型数组被初始化为 true本地方法将把特定的元素设置为 false同时在 Java 源代码中我们可以更改 main 以使其包含测试代码boolean[] ba = new boolean[5];MyNative.setArray( ba );for( int i=0; i < ba.length; i++ )System.out.println( ba[i] );在编译源代码并执行 javah 以后MyNative.h 头文件包含以下的原型/** Class: MyNative* Method: setArray0* Signature: ([Z)V*/JNIEXPORT void JNICALL Java_MyNative_setArray0(JNIEnv *, jclass, jbooleanArray);请注意布尔型数组是作为单个名为 jbooleanArray 的类型创建的基本类型有它们自已的数组类型如 jintArray 和 jcharArray非基本类型的数组使用 jobjectArray 类型下一个示例中包括一个 jobjectArray这个布尔数组的数组元素是通过 JNI 方法 GetBooleanArrayElements 来访问的针对每种基本类型都有等价的方法这个本地方法是如下实现的JNIEXPORT void JNICALL Java_MyNative_setArray0(JNIEnv *env, jclass cls, jbooleanArray ba){jboolean* pba = (*env)->GetBooleanArrayElements( env, ba, 0 );jsize len = (*env)->GetArrayLength(env, ba);int i=0;// 更改偶数数组元素for( i=0; i < len; i+=2 )pba[i] =JNI_FALSE;(*env)->ReleaseBooleanArrayElements( env, ba, pba, 0 );}指向布尔型数组的指针可以使用 GetBooleanArrayElements 获得数组大小可以用 GetArrayLength 方法获得使用 ReleaseBooleanArrayElements 方法释放数组现在就可以读取和修改数组元素的值了jsize 声明等价于 jint要查看它的定义请参阅 JDK 的 include 目录下的 jni.h 头文件示例 5 -- 传递 Java String 数组本例将通过最常用的非基本类型Java String说明如何访问非基本对象的数组字符串数组被传递给本地方法而本地方法只是将它们显示到控制台上 MyNative 类定义中添加了以下几个方法public static void showStrings( String[] sa ){showStrings0( sa );private static void showStrings0( String[] sa );并在 main 方法中添加了两行进行测试String[] sa = new String[] { "Hello,", "world!", "JNI", "is", "fun." };MyNative.showStrings( sa );本地方法分别访问每个元素其实现如下所示JNIEXPORT void JNICALL Java_MyNative_showStrings0(JNIEnv *env, jclass cls, jobjectArray sa){int len = (*env)->GetArrayLength( env, sa );int i=0;for( i=0; i < len; i++ ){jobject obj = (*env)->GetObjectArrayElement(env, sa, i);jstring str =(jstring)obj;const char* szStr = (*env)->GetStringUTFChars( env, str, 0 );printf( "%s ", szStr );(*env)->ReleaseStringUTFChars( env, str, szStr );}printf( "\n" );}数组元素可以通过 GetObjectArrayElement 访问在本例中我们知道返回值是 jstring 类型所以可以安全地将它从 jobject 类型转换为 jstring 类型字符串是通过前面讨论过的方法打印的有关在 Windows 中处理 Java 字符串的信息请参阅标题为 NLS Strings and JNI 的一篇论文示例 6 -- 返回 Java String 数组最后一个示例说明如何在本地代码中创建一个字符串数组并将它返回给 Java 调用者MyNative.java 中添加了以下几个方法public static String[] getStrings(){return getStrings0();}private static native String[] getStrings0();更改 main 以使 showStrings 将 getStrings 的输出显示出来MyNative.showStrings( MyNative.getStrings() );实现的本地方法返回五个字符串JNIEXPORT jobjectArray JNICALL Java_MyNative_getStrings0(JNIEnv *env, jclass cls){jstring str;jobjectArray args = 0;jsize len = 5;char* sa[] ={ "Hello,", "world!", "JNI", "is", "fun" };int i=0;args = (*env)->NewObjectArray(env, len, (*env)->FindClass(env, "java/lang/String"), 0);for( i=0; i < len; i++ ){str = (*env)->NewStringUTF( env, sa[i] );(*env)->SetObjectArrayElement(env, args, i, str);}return args;}字符串数组是通过调用 NewObjectArray 创建的同时传递了 String 类和数组长度两个参数Java String 是使用 NewStringUTF 创建的String 元素是使用 SetObjectArrayElement 存入数组中的调试现在您已经为您的应用程序创建了一个本地 DLL但在调试时还要牢记以下几点如果使用 Java 调试器 java_g.exe则还需要创建 DLL 的一个调试版本这只是表示必须创建同名但带有一个 _g 后缀的 DLL 版本就 MyNative.dll 而言使用 java_g.exe 要求在 Windows 的 PATH 环境指定的路径中有一个 MyNative_g.dll 文件在大多数情况下这个 DLL 可以通过将原文件重命名或复制为其名称带缀 _g 的文件现在Java 调试器不允许您进入本地代码但您可以在 Java 环境外使用 C 调试器如 Microsoft Visual C++调试本地方法首先将源文件导入一个项目中将编译设置调整为在编译时将 include 目录包括在内c:\jdk1.1.6\include;c:\jdk1.1.6\include\win32将配置设置为以调试模式编译 DLL在 Project Settings 中的 Debug 下将可执行文件设置为 java.exe或者 java_g.exe但要确保您生成了一个 _g.dll 文件程序参数包括包含 main 的类名如果在 DLL 中设置了断点则当调用本地方法时执行将在适当的地方停止下面是设置一个 Visual C++ 6.0 项目来调试本地方法的步骤1. 在 Visual C++ 中创建一个 Win32 DLL 项目并将 .c 和 .h 文件添加到这个项目中2. 在 Tools 下拉式菜单的 Options 设置下设置 JDK 的 include 目录下面的对话框显示了这些目录3. 选择 Build 下拉式菜单下的 Build MyNative.dll 来建立这个项目确保将项目的活动配置设置为调试这通常是缺省值4. 在 Project Settings 下设置 Debug 选项卡来调用适当的 Java 解释器如下所示当执行这个程序时忽略在 java.exe 中找不到任何调试信息的消息当调用本地方法时在 C 代码中设置的任何断点将在适当的地方停止 Java 程序的执行其他信息JNI 方法和 C++上面这些示例说明了如何在 C 源文件中使用 JNI 方法如果使用 C++则请将相应方法的格式从(*env)->JNIMethod( env, .... );更改为env->JNIMethod( ... );在 C++ 中JNI 函数被看作是 JNIEnv 类的成员方法字符串和国家语言支持本文中使用的技术用 UTF 方法来转换字符串使用这些方法只是为了方便起见如果应用程序需要国家语言支持 (NLS)则不能使用这些方法有关在 Windows 和 NLS 环境中处理 Java 字符串正确方法请参标题为 NLS Strings and JNI 的一篇论文小结本文提供的示例用最常用的数据类据如 jint 和 jstring说明了如何实现本地方法并讨论了 Windows 特定的几个问题如显示字符串本文提供的示例并未包括全部 JNI JNI 还包括其他参数类型如 jfloat jdouble jshort jbyte 和 jfieldID以及用来处理这些类型的方法有关这个主题的详细信息请参阅 Sun Microsystems 提供的 Java 本地接口规范作者简介David Wendt 是 IBM WebSphere Studio 的一名程序员该工作室位于北卡罗莱纳州的 Research Triangle Park可以通过 wendt@ 与他联系。