本篇將介紹在JNI編程中如何傳遞參數和返回值。
首先要強調的是,native方法不但可以傳遞Java 的基本類型做參數,還可以傳遞更復雜的類型,比如String,數組,甚 至自定義的類。這一切都可以在jni.h中找到答案。
1. Java基本類型的傳遞
用過Java的人都知道,Java中的基本類型包括boolean,byte ,char,short,int,long,float,double 這樣幾種,如果你用這幾種類型做native方法的參數,當你通過javah -jni生成.h文件的時候,只要看一下生成的.h文件,就會一清二楚,這些類型分別對應的類型是 jboolean,jbyte,jchar,jshort,jint,jlong,jfloat,jdouble 。這幾種類型幾乎都可以當成對應的C++類型來用,所以沒什麼好說的。
2. String參數的傳遞
Java的String和C++的string是不能對等起來的,所以處理起來比較麻煩。先看一個例子,
class Prompt {
// native method that prints a prompt and reads a line
private native String getLine(String prompt);
public static void main(String args[]) {
Prompt p = new Prompt();
String input = p.getLine(“Type a line: “);
System.out.println(“User typed: ” + input);
}
static {
System.loadLibrary(“Prompt”);
}
}
在這個例子中,我們要實現一個native方法
String getLine(String prompt);
讀入一個String參數,返回一個String值。
通過執行javah -jni得到的頭文件是這樣的
#include <jni.h>
#ifndef _Included_Prompt
#define _Included_Prompt
#ifdef __cplusplus
extern “C” {
#endif
JNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *env, jobject this, jstring prompt);
#ifdef __cplusplus
}
#endif
#endif
jstring是JNI中對應於String的類型,但是和基本類型不同的是,jstring不能直接當作C++的string用。如果你用
cout << prompt << endl;
編譯器肯定會扔給你一個錯誤信息的。
其實要處理jstring有很多種方式,這裏只講一種我認爲最簡單的方式,看下面這個例子,
#include “Prompt.h”
#include <iostream>
JNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *env, jobject obj, jstring prompt)
{
const char* str;
str = env->GetStringUTFChars(prompt, false);
if(str == NULL) {
return NULL; /* OutOfMemoryError already thrown */
}
std ::cout << str << std::endl;
env->ReleaseStringUTFChars(prompt, str);
char* tmpstr = “return string succeeded”;
jstring rtstr = env->NewStringUTF(tmpstr);
return rtstr;
}
在上面的例子中,作爲參數的prompt不能直接被C++程序使用,先做了如下轉換
str = env->GetStringUTFChars(prompt, false);
將jstring類型變成一個char*類型。
返回的時候,要生成一個jstring類型的對象,也必須通過如下命令,
jstring rtstr = env->NewStringUTF(tmpstr);
這裏用到的GetStringUTFChars和NewStringUTF都是JNI提供的處理String類型的函數,還有其他的函數這裏就不一 一列舉了。
3. 數組類型的傳遞
和String一樣,JNI爲Java基本類型的數組提供了j*Array類型,比如int[]對應的就是jintArray。來看一個傳遞int 數組的例子,Java程序就不寫了,
JNIEXPORT jint JNICALL Java_IntArray_sumArray(JNIEnv *env, jobject obj, jintArray arr)
{
jint *carr;
carr = env->GetIntArrayElements(arr, false);
if(carr == NULL) {
return 0; /* exception occurred */
}
jint sum = 0;
for(int i=0; i<10; i++) {
sum += carr[i];
}
env->ReleaseIntArrayElements(arr, carr, 0);
return sum;
}
這個例子中的GetIntArrayElements和ReleaseIntArrayElements函數就是JNI提供用於處理int數組的函 數。如果試圖用arr[i]的方式去訪問jintArray類型,毫無疑問會出錯。JNI還提供了另一對函數GetIntArrayRegion和 ReleaseIntArrayRegion訪問int數組,就不介紹了,對於其他基本類型的數組,方法類似。
4. 二維數組和String數組
在JNI中,二維數組和String數組都被視爲object數組,因爲數組和String被視爲object。仍然用一個例子來說明,這次是一個 二維int數組,作爲返回值。
JNIEXPORT jobjectArray JNICALL Java_ObjectArrayTest_initInt2DArray(JNIEnv *env, jclass cls, int size)
{
jobjectArray result;
jclass intArrCls = env->FindClass(“[I");
result = env->NewObjectArray(size, intArrCls, NULL);
for (int i = 0; i < size; i++) {
jint tmp[256]; /* make sure it is large enough! */
jintArray iarr = env->NewIntArray(size);
for(int j = 0; j < size; j++) {
tmp[j] = i + j;
}
env->SetIntArrayRegion(iarr, 0, size, tmp);
env->SetObjectArrayElement(result, i, iarr);
env->DeleteLocalRef(iarr);
}
return result;
}
上面代碼中的第三行,
jobjectArray result;
因爲要返回值,所以需要新建一個jobjectArray對象。
jclass intArrCls = env->FindClass(“[I");
是創建一個jclass的引用,因爲result的元素是一維int數組的引用,所以intArrCls必須是一維int數組的引用,這一點是如何保證的 呢?注意FindClass的參數"[I",JNI就是通過它來確定引用的類型的,I表示是int類型,[標識是數組。對於其他的類型,都有相應的表示方 法,
Z boolean
B byte
C char
S short
I int
J long
F float
D double
String是通過“Ljava/lang /String;”表示的,那相應的,String數組就應該是 “[Ljava/lang/String;”。
還是回到代碼,
result = env->NewObjectArray(size, intArrCls, NULL);
的作用是爲result分配空間。
jintArray iarr = env->NewIntArray(size);
是爲一維int數組iarr分配空間。
env->SetIntArrayRegion(iarr, 0, size, tmp);
是爲iarr賦值。
env->SetObjectArrayElement(result, i, iarr);
是爲result的第i個元素賦值。
通過上面這些步驟,我們就創建了一個二維int數組,並賦值完畢,這樣就可以做爲參數返回了。
如果瞭解了上面介紹的這些內容,基本上大部分的任務都可以對付了。雖然在操作數組類型,尤其是二維數組和String數組的時候,比起在單獨的語言 中編程要麻煩,但既然我們享受了跨語言編程的好處,必然要付出一定的代價。
有一點要補充的是,本文所用到的函數調用方式都是針對C++的,如果要在C中使用,所有的env->都要被替換成(*env)->,而 且後面的函數中需要增加一個參數env,具體請看一下jni.h的代碼。另外還有些省略的內容,可以參考JNI的文檔:Java Native Interface 6.0 Specification,在JDK 的文檔裏就可以找到。如果要進行更深入的JNI編程,需要仔細閱讀這個文 檔。接下來的高級篇,也會討論更深入的話題。
關於JNI編程更深入的話題,包括:在native方法中訪問Java類的域和方法,將Java中自定義的類作爲參數和返回值傳遞等等。瞭解這些內 容,將會對JNI編程有更深入的理解,寫出的程序也更清晰,易用性更好。
1. 在一般的Java類中定義native方法
在前兩篇的例子中,都是將native方法放在main方法的Java類中,實際上,完全可以在任何類中定義native方法。這樣,對於外部來 說,這個類和其他的Java類沒有任何區別。
2. 訪問Java類的域和方法
native方法雖然是native的,但畢竟是方法,那麼就應該同其他方法一樣,能夠訪問類的私有域和方法。實際上,JNI的確可以做到這一點, 我們通過幾個例子來說明,
public class ClassA {
String str_ = "abcde";
int number_;
public native void nativeMethod();
private void javaMethod() {
System.out.println("call java method succeeded");
}
static {
System.loadLibrary("ClassA");
}
}
在這個例子中,我們在一個沒有main方法的Java類中定義了native方法。我們將演示如何在nativeMethod()中訪問域 str_,number_和方法javaMethod(),nativeMethod()的C++實現如下,
JNIEXPORT void JNICALL Java_testclass_ClassCallDLL_nativeMethod(JNIEnv *env, jobject obj) {
// access field
jclass cls = env->GetObjectClass(obj);
jfieldID fid = env->GetFieldID(cls, "str_", "Ljava/lang/String;");
jstring jstr = (jstring)env->GetObjectField(obj, fid);
const char *str = env->GetStringUTFChars(jstr, false);
if(std::string(str) == "abcde")
std::cout << "access field succeeded" << std::endl;
jint i = 2468;
fid = env->GetFieldID(cls, "number_", "I");
env->SetIntField(obj, fid, i);
// access method
jmethodID mid = env->GetMethodID(cls, "javaMethod", "()V");
env->CallVoidMethod(obj, mid);
}
上面的代碼中,通過如下兩行代碼獲得str_的值,
jfieldID fid = env->GetFieldID(cls, "str_", "Ljava/lang/String;");
jstring jstr = (jstring)env->GetObjectField(obj, fid);
第一行代碼獲得str_的id,在GetFieldID函數的調用中需要指定str_的類型,第二行代碼通過str_的id獲得它的值,當然我們讀 到的是一個jstring類型,不能直接顯示,需要轉化爲char*類型。
接下來我們看如何給Java類的域賦值,看下面兩行代碼,
fid = env->GetFieldID(cls, "number_", "I");
env->SetIntField(obj, fid, i);
第一行代碼同前面一樣,獲得number_的id,第二行我們通過SetIntField函數將i的值賦給number_,其他類似的函數可以參考 JDK的文檔。
訪問javaMethod()的過程同訪問域類似,
jmethodID mid = env->GetMethodID(cls, "javaMethod", "()V");
env->CallVoidMethod(obj, mid);
需要強調的是,在GetMethodID中,我們需要指定javaMethod方法的類型,域的類型很容易理解,方法的類型如何定義呢,在上面的例 子中,我們用的是()V,V表示返回值爲空,()表示參數爲空。如果是更復雜的函數類型如何表示?看一個例子,
long f (int n, String s, int[] arr);
這個函數的類型符號是(ILjava/lang/String;[I)J,I表示int類型,Ljava/lang/String;表示String類 型,[I表示int數組,J表示long。這些都可以在文檔中查到。
3. 在native方法中使用用戶定義的類
JNI不僅能使用Java的基礎類型,還能使用用戶定義的類,這樣靈活性就大多了。大體上使用自定義的類和使用Java的基礎類(比如 String)沒有太大的區別,關鍵的一點是,如果要使用自定義類,首先要能訪問類的構造函數,看下面這一段代碼,我們在native方法中使用了自定義 的Java類ClassB,
jclass cls = env->FindClass("Ltestclass/ClassB;");
jmethodID id = env->GetMethodID(cls, "<init>", "(D)V");
jdouble dd = 0.033;
jvalue args[1];
args[0].d = dd;
jobject obj = env->NewObjectA(cls, id, args);
首先要創建一個自定義類的引用,通過FindClass函數來完成,參數同前面介紹的創建String對象的引用類似,只不過類名稱變成自定義類的 名稱。然後通過GetMethodID函數獲得這個類的構造函數,注意這裏方法的名稱是”<init>”,它表示這是一個構造函數。
jobject obj = env->NewObjectA(cls, id, args);
生成了一個ClassB的對象,args是ClassB的構造函數的參數,它是一個jvalue*類型。
通過以上介紹的三部分內容,native方法已經看起來完全像Java自己的方法了,至少主要功能上齊備了,只是實現上稍麻煩。而瞭解了這 些,JNI編程的水平也更上一層樓。下面要討論的話題也是一個重要內容,至少如果沒有它,我們的程序只能停留在演示階段,不具有實用價值。
4. 異常處理
在C++和Java的編程中,異常處理都是一個重要的內容。但是在JNI中,麻煩就來了,native方法是通過C++實現的,如果在native 方法中發生了異常,如何傳導到Java呢?
JNI提供了實現這種功能的機制。我們可以通過下面這段代碼拋出一個Java可以接收的異常,
jclass errCls;
env->ExceptionDescribe();
env->ExceptionClear();
errCls = env->FindClass(“java/lang/IllegalArgumentException”);
env->ThrowNew(errCls, “thrown from C++ code”);
如果要拋出其他類型的異常,替換掉FindClass的參數即可。這樣,在Java中就可以接收到native方法中拋出的異常。