java jni 入门7 - 访问数组元素

参考：《Java核心技术 卷II：高级特性》第12章 本地方法

###############################################################

Java编程语言的所有数组类型都有相对应的C语言类型

Java数组类型和C数组类型之间的对应关系
Java数组类型	C数组类型	Java数组类型	C数组类型
boolean[]	jbooleanArray	long[]	jlongArray
byte[]	jbyteArray	float[]	jfloatArray
char[]	jcharArray	double[]	jdoubleArray
int[]	jintArray	Object[]	jobjectArray
short[]	jshortArray

注意：在C中，所有这些数组类型实际上都是jobject的同义类型。然而，在C++中它们被安排在如下继承层次结构中。jarray类型表示一个通用数组。

jobject	jarray	jobjectArray
		jbooleanArray
		jbyteArray
		jcharArray
		jshortArray
		jintArray
		jlongArray
		jfloatArray
		jdoubleArray

GetArrayLength函数返回数组的长度。

jarray array = ...;
jsize length  = (*env)->GetArrayLength(env, array);

如何访问数组元素取决于数组中存储的是对象还是原始类型的数据(bool , char或数值类型)。可以通过GetObjectArrayElement和SetObjectArrayElement方法访问对象数组的元素。

jobjectArray array = . . . ;
int i, j;
jobject x = (*env)->GetObjectArrayElement(env, array, i);
(*env)->SetObjectArray(env, array, j, x);

这个方法虽然简单，但是效率明显底下，你可能想要直接访问数组元素，特别是进行向量或矩阵计算时更加明显。

GetXxxArrayElements函数返回一个指向数组起始元素的C指针。与普通的字符串一样，当你不再需要该指针时，必须记得要调用ReleaseXxxArrayElement函数通知虚拟机。这里，类型Xxx必须是原始类型，也就是，不能是Object。这样就可以直接读写数组元素了。

另一方面，由于指针可能会指向一个副本，只有调用相应的ReleaseXxxArrayElements函数时，所做的改变才能保证在原始数组里得到反映。

注意，通过把一个指向jboolean变量的指针作为第三个参数传递给GetXxxArrayElements方法，可以发现一个数组是否是副本。如果是副本则该变量被JNI_TRUE填充。如果你对这个信息不感兴趣，传一个空指针即可。

下面是对double类型数组中的所有元素乘以一个常量的代码。获取一个Java数组的C指针a，并用a[i]访问每个变量：

jdoubleArray array_a = " . . .";
double scaleFactor = ...;
double *a = (*env)->GetDoubleArrayElements(env, array_a, NULL);
for (i=0; i<(*env)->GetArrayLength(env, array_a); i++)
       a[i] = a[i] * scaleFactor;
(*env)->ReleaseDoubleArrayElements(env, array_a, a, 0);

虚拟机是否确实需要对数组进行拷贝取决于它是如何分配数组和如何进行垃圾回收的。有些“拷贝”型的垃圾回收器例行地移动对象，并更新对象引用。该策略与将数组锁定在特定位置是不兼容的，因为回收器不能更新本地代码中的指针值。

如果要访问一个大数组的多个元素，可以用GetXxxArrayRegion和SetXxxArrayRegion方法，它能把一定范围内的元素从Java数组复制到C数组中或从C数组复制到Java数组中。

可以用NewXxxArray函数在本地方法中创建新的Java数组。要创建新的对象数组，需要指定长度 ， 数组元素的类型和所有元素的初始值（典型的是NULL）。例如：

jclass class_Employee = (*env)->FindClass(env, "Employee");
jobjectArray array_e = (*env)->NewObjectArray(env, 100, class_Employee, NULL);

其中，原始类型的数组要简单一些，只需提供数组长度：

jdoubleArray array_d = (*env)->NewObjectArray(env, 100);

该数组被0填充

####################################################################

操作Java数组函数详解：

jsize GetArrayLength(JNIEnv *env, jarray array)

返回数组中的元素个数

jobject GetObjectArrayElement(JNIEnv *env, jobjectArray array, jsize index)

返回数组元素的值

void SetObjectArrayElement(JNIEnv *env, jobjectArray array, jsize index, jobject value)

将数组元素设为新值

Xxx* GetXxxArrayElements(JNIEnv *env, jarray array, jboolean *isCopy)

产生一个指向Java数组元素的C指针。域类型Xxx是Boolean , Byte , Char , Short , Int , Long , Float 或 Double之一。指针不再使用时，该指针必须传递给Release
XxxArrayElements。如果进行了复制， isCopy可以是NULL或者指向JNI_TRUE填充的jboolean；否则，指向JNI_False填充的jboolean。

void ReleaseXxxArrayElements(JNIEnv *env, jarray array, Xxx elems[], jint mode)

通知虚拟机通过GetXxxArrayElements获得的一个指针已经不再需要了。Mode是0（更新数组元素后释放elems缓存），JNI_COMMIT（更新数组元素后不释放elems缓存）或JNI_ABORT（不更新数组元素便释放elems缓存）之一。

void GetXxxArrayRegion(JNIEnv *env, jarray array, jint start, jint length, Xxx elems[])

将Java数组的元素复制到C数组中。域类型Xxx是Boolean , Byte , Char , Short , Int , Long , Float或Double之一。

void SetXxxArrayRegion(JNIEnv *env, jarray array, jint start, jint length, Xxx elems[])

将C数组的元素复制到Java数组中。域类型Xxx是Boolean , Byte , Char , Short , Int , Long , Float或Double之一。