JNI之数组

Array Operations -- 数组操作

1.GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

Returns the number of elements in the array.

返回数据的长度。

参数：

env：JNI 接口指针。

array：Java 数组对象。

返回值：

数组的长度。

2.NewObjectArray

jobjectArray NewObjectArray(JNIEnv *env, jsize length,jclass elementClass, jobject initialElement);

Constructs a new array holding objects in class elementClass. All elements are initially set to initialElement.

构造新的数组，它将保存类 elementClass 中的对象。所有元素初始值均设为 initialElement。

参数：

env：JNI 接口指针。

length：数组大小。

elementClass：数组元素类。

initialElement：初始值。

返回值：

Java 数组对象。如果无法构造数组，则为 NULL。

抛出：

OutOfMemoryError：如果系统内存不足。

3.GetObjectArrayElement

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

Returns an element of an Object array.

返回 Object 数组的元素。

参数：

env：JNI 接口指针。

array：Java 数组。

index：数组下标。

返回值：

Java 对象。

抛出：

ArrayIndexOutOfBoundsException：如果 index 不是数组中的有效下标。

4.SetObjectArrayElement

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

Sets an element of an Object array.

设置 Object 数组的元素。

参数：

env：JNI 接口指针。

array：Java 数组。

index：数组下标。

value：新值。

抛出：

ArrayIndexOutOfBoundsException：如果 index 不是数组中的有效下标。

ArrayStoreException：如果 value 的类不是数组元素类的子类。

5.New<PrimitiveType>Array Routines

ArrayType New<PrimitiveType>Array(JNIEnv *env, jsize length);

A family of operations used to construct a new primitive array object. Table 4-8 describes the specific primitive array constructors. You should replace New<PrimitiveType>Array with one of the actual primitive array constructor routine names from the following table, and replace ArrayType with the corresponding array type for that routine.

用于构造新基本类型数组对象的一系列操作。表 4-8 说明了特定的基本类型数组构造函数。用户应把New<PrimitiveType>Array 替换为某个实际的基本类型数组构造函数例程名（见下表），然后将 ArrayType替换为该例程相应的数组类型。

参数：

env：JNI 接口指针。

length：数组长度。

返回值：

Java 数组。如果无法构造该数组，则为 NULL。

6.Get<PrimitiveType>ArrayElements Routines

NativeType *Get<PrimitiveType>ArrayElements(JNIEnv *env,ArrayType array, jboolean *isCopy);

A family of functions that returns the body of the primitive array. The result is valid until the corresponding Release<PrimitiveType>ArrayElements() function is called. Since the returned array may be a copy of the Java array, changes made to the returned array will not necessarily be reflected in the original array until Release<PrimitiveType>ArrayElements() is called.

If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.

The following table describes the specific primitive array element accessors. You should make the following substitutions:

• Replace Get<PrimitiveType>ArrayElements with one of the actual primitive element accessor routine names from the table.
• Replace ArrayType with the corresponding array type.
• Replace NativeType with the corresponding native type for that routine.

Regardless of how boolean arrays are represented in the Java VM, GetBooleanArrayElements() always returns a pointer to jbooleans, with each byte denoting an element (the unpacked representation). All arrays of other types are guaranteed to be contiguous in memory.

一组返回基本类型数组体的函数。结果在调用相应的 Release<PrimitiveType>ArrayElements()函数前将一直有效。由于返回的数组可能是 Java 数组的副本，因此对返回数组的更改不必在基本类型数组中反映出来，直到调用了Release<PrimitiveType>ArrayElements()。

如果 isCopy 不是 NULL，*isCopy 在复制完成后即被设为 JNI_TRUE。如果未复制，则设为 JNI_FALSE。

下表说明了特定的基本类型数组元素访问器。应进行下列替换；

• 将 Get<PrimitiveType>ArrayElements 替换为表中某个实际的基本类型元素访问器例程名。
• 将 ArrayType 替换为对应的数组类型。
• 将 NativeType 替换为该例程对应的本地类型。

不管布尔数组在 Java 虚拟机中如何表示，GetBooleanArrayElements() 将始终返回一个 jbooleans 类型的指针，其中每一字节代表一个元素（开包表示）。内存中将确保所有其它类型的数组为连续的。

参数：

env：JNI 接口指针。

array：Java 字符串对象。

isCopy：指向布尔值的指针。

返回值：

返回指向数组元素的指针，如果操作失败，则为 NULL。