目次 | 前の項目 | 次の項目 Java Native Interface 仕様

JNI 関数

第 4 章

この章は、JNI の関数のリファレンスです。この章では、JNI の関数をすべて取り上げます。また、JNI 関数テーブルの配置そのままに記載されています。

「しなければならない」(または「する必要がある」) という表現は、JNI プログラマに対する制約を表していることに注意してください。たとえば、ある JNI 関数について、それが null 以外のオブジェクトを受け取ら「なければならない」と説明されている場合、プログラマの責任において、その JNI 関数に null を渡さないようにしなければならないという意味になります。それによって、JNI 実装の際に、その JNI 関数における null のポインタチェックを行う必要がなくなります。

この章の一部は Netscape の JRI ドキュメントから改作したものです。

参照資料は、関数を用途によってグループ化しています。参照セクションは、次の機能分野から構成されています。

インタフェース関数テーブル

各関数には、JNIEnv 引数を介し、固定オフセットでアクセスすることが可能です。JNIEnv 型は、すべての JNI 関数のポインタを格納する構造体を指すポインタです。これは次のように定義されます。 

typedef const struct JNINativeInterface *JNIEnv;

VM は、コード例 4-1 に示されているように関数テーブルを初期化します。最初の 3 エントリは、将来の COM との互換性のために予約されていることに注意してください。さらに、関数テーブルの始めの近辺にいくつかの追加の null エントリを予約してあります。したがって、たとえば、これから現われる、クラス関連の JNI 演算は、表の終わりではなく FindClass のあとに追加することができます。

関数テーブルは、すべての JNI インタフェースポインタの間で共用されることに注意してください。

コード例 4-1
const struct JNINativeInterface ... = { = {

null,
null,
null,
null,
GetVersion,

DefineClass,
FindClass,

FromReflectedMethod,
FromReflectedField,
ToReflectedMethod,

GetSuperclass,
IsAssignableFrom,

ToReflectedField, 

Throw,
ThrowNew,
ExceptionOccurred,
ExceptionDescribe,
ExceptionClear,
FatalError,

PushLocalFrame, 
PopLocalFrame, 

NewGlobalRef,
DeleteGlobalRef,
DeleteLocalRef,
IsSameObject,
NewLocalRef, 
EnsureLocalCapacity, 

AllocObject,
NewObject,
NewObjectV,
NewObjectA,

GetObjectClass,
IsInstanceOf,

GetMethodID,

CallObjectMethod,
CallObjectMethodV,
CallObjectMethodA,
CallBooleanMethod,
CallBooleanMethodV,
CallBooleanMethodA,
CallByteMethod,
CallByteMethodV,
CallByteMethodA,
CallCharMethod,
CallCharMethodV,
CallCharMethodA,
CallShortMethod,
CallShortMethodV,
CallShortMethodA,
CallIntMethod,
CallIntMethodV,
CallIntMethodA,
CallLongMethod,
CallLongMethodV,
CallLongMethodA,
CallFloatMethod,
CallFloatMethodV,
CallFloatMethodA,
CallDoubleMethod,
CallDoubleMethodV,
CallDoubleMethodA,
CallVoidMethod,
CallVoidMethodV,
CallVoidMethodA,

CallNonvirtualObjectMethod,
CallNonvirtualObjectMethodV,
CallNonvirtualObjectMethodA,
CallNonvirtualBooleanMethod,
CallNonvirtualBooleanMethodV,
CallNonvirtualBooleanMethodA,
CallNonvirtualByteMethod,
CallNonvirtualByteMethodV,
CallNonvirtualByteMethodA,
CallNonvirtualCharMethod,
CallNonvirtualCharMethodV,
CallNonvirtualCharMethodA,
CallNonvirtualShortMethod,
CallNonvirtualShortMethodV,
CallNonvirtualShortMethodA,
CallNonvirtualIntMethod,
CallNonvirtualIntMethodV,
CallNonvirtualIntMethodA,
CallNonvirtualLongMethod,
CallNonvirtualLongMethodV,
CallNonvirtualLongMethodA,
CallNonvirtualFloatMethod,
CallNonvirtualFloatMethodV,
CallNonvirtualFloatMethodA,
CallNonvirtualDoubleMethod,
CallNonvirtualDoubleMethodV,
CallNonvirtualDoubleMethodA,
CallNonvirtualVoidMethod,
CallNonvirtualVoidMethodV,
CallNonvirtualVoidMethodA,

GetFieldID,

GetObjectField,
GetBooleanField,
GetByteField,
GetCharField,
GetShortField,
GetIntField,
GetLongField,
GetFloatField,
GetDoubleField,
SetObjectField,
SetBooleanField,
SetByteField,
SetCharField,
SetShortField,
SetIntField,
SetLongField,
SetFloatField,
SetDoubleField,

GetStaticMethodID,

CallStaticObjectMethod,
CallStaticObjectMethodV,
CallStaticObjectMethodA,
CallStaticBooleanMethod,
CallStaticBooleanMethodV,
CallStaticBooleanMethodA,
CallStaticByteMethod,
CallStaticByteMethodV,
CallStaticByteMethodA,
CallStaticCharMethod,
CallStaticCharMethodV,
CallStaticCharMethodA,
CallStaticShortMethod,
CallStaticShortMethodV,
CallStaticShortMethodA,
CallStaticIntMethod,
CallStaticIntMethodV,
CallStaticIntMethodA,
CallStaticLongMethod,
CallStaticLongMethodV,
CallStaticLongMethodA,
CallStaticFloatMethod,
CallStaticFloatMethodV,
CallStaticFloatMethodA,
CallStaticDoubleMethod,
CallStaticDoubleMethodV,
CallStaticDoubleMethodA,
CallStaticVoidMethod,
CallStaticVoidMethodV,
CallStaticVoidMethodA,

GetStaticFieldID,

GetStaticObjectField,
GetStaticBooleanField,
GetStaticByteField,
GetStaticCharField,
GetStaticShortField,
GetStaticIntField,
GetStaticLongField,
GetStaticFloatField,
GetStaticDoubleField,

SetStaticObjectField,
SetStaticBooleanField,
SetStaticByteField,
SetStaticCharField,
SetStaticShortField,
SetStaticIntField,
SetStaticLongField,
SetStaticFloatField,
SetStaticDoubleField,

NewString,

GetStringLength,
GetStringChars,
ReleaseStringChars,
 
NewStringUTF,
GetStringUTFLength,
GetStringUTFChars,
ReleaseStringUTFChars,
 
GetArrayLength,
  
NewObjectArray,
GetObjectArrayElement,
SetObjectArrayElement,
 
NewBooleanArray,
NewByteArray,
NewCharArray,
NewShortArray,
NewIntArray,
NewLongArray,
NewFloatArray,
NewDoubleArray,
 
GetBooleanArrayElements,
GetByteArrayElements,
GetCharArrayElements,
GetShortArrayElements,
GetIntArrayElements,
GetLongArrayElements,
GetFloatArrayElements,
GetDoubleArrayElements,
 
ReleaseBooleanArrayElements,
ReleaseByteArrayElements,
ReleaseCharArrayElements,
ReleaseShortArrayElements,
ReleaseIntArrayElements,
ReleaseLongArrayElements,
ReleaseFloatArrayElements,
ReleaseDoubleArrayElements,
 
GetBooleanArrayRegion,
GetByteArrayRegion,
GetCharArrayRegion,
GetShortArrayRegion,
GetIntArrayRegion,
GetLongArrayRegion,
GetFloatArrayRegion,
GetDoubleArrayRegion,
SetBooleanArrayRegion,
SetByteArrayRegion,
SetCharArrayRegion,
SetShortArrayRegion,
SetIntArrayRegion,
SetLongArrayRegion,
SetFloatArrayRegion,
SetDoubleArrayRegion,
 
RegisterNatives,
UnregisterNatives,
 
MonitorEnter,
MonitorExit,
 
GetJavaVM,

GetStringRegion,
GetStringUTFRegion,

GetPrimitiveArrayCritical,
ReleasePrimitiveArrayCritical,

GetStringCritical,
ReleaseStringCritical,

NewWeakGlobalRef,
DeleteWeakGlobalRef,

ExceptionCheck,

NewDirectByteBuffer,
GetDirectBufferAddress,
GetDirectBufferCapacity
};

バージョン情報

GetVersion

jint GetVersion(JNIEnv *env);

ネイティブメソッドインタフェースのバージョンを返します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 4

パラメータ:

env: JNI インタフェースポインタ

戻り値:

メジャーバージョン番号を高位の 16 ビットで、マイナーバージョン番号を下位の 16 ビットで返します。

JDK/JRE 1.1 では、GetVersion() が 0x00010001 を返します。

JDK/JRE 1.2 では、GetVersion() が 0x00010002 を返します。

JDK/JRE 1.4 では、GetVersion() が 0x00010004 を返します。

定数

SDK/JRE 1.2 以降:
#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002

/* Error codes */
#define JNI_EDETACHED    (-2)              /* thread detached from the VM */
#define JNI_EVERSION     (-3)              /* JNI version error
SDK/JRE 1.4 以降: 
    #define JNI_VERSION_1_4 0x00010004

クラス操作

DefineClass

jclass DefineClass(JNIEnv *env, const char *name, jobject loader,
const jbyte *buf, jsize bufLen);

raw クラスデータのバッファからクラスをロードします。raw クラスデータを含むバッファは、DefineClass 呼び出しから返された後に VM で参照されないため、必要に応じて破棄できます。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 5

パラメータ:

env: JNI インタフェースポインタ

name: 定義されるクラスまたはインタフェースの名前。文字列は変更後の UTF-8 に符号化されます。

loader: 定義されたクラスに割り当てられるクラスローダ

buf: .class ファイルデータを含むバッファ

bufLen: バッファ長

戻り値:

クラスオブジェクトを返します。エラーが発生した場合は null を返します。

例外:

ClassFormatError: クラスデータが有効なクラスを指定しなかった場合

ClassCircularityError: クラスまたはインタフェースが、それ自体のスーパークラスまたはスーパーインタフェースになる場合

OutOfMemoryError: システムがメモリ不足の場合

FindClass

jclass FindClass(JNIEnv *env, const char *name);

この関数は、局所的に定義されたクラスをロードします。また、指定された名前を持つクラスに対して CLASSPATH 環境変数が指定するディレクトリおよび ZIP ファイルを検索します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 6

パラメータ:

env: JNI インタフェースポインタ

name: 完全修飾クラス名 (「/」で区切ったあとにクラス名を付けたパッケージ名)。その名前が「[」(配列シグニチャー文字) で開始されている場合は、配列クラスを返します。文字列は変更後の UTF-8 に符号化されます。

戻り値:

完全修飾名からクラスオブジェクトを返します。クラスが見つからない場合は、null を返します。

例外:

ClassFormatError: クラスデータが有効なクラスを指定しなかった場合

ClassCircularityError: クラスまたはインタフェースが、それ自体のスーパークラスまたはスーパーインタフェースになる場合

NoClassDefFoundError: 要求されたクラスまたはインタフェースに対する定義が見つからなかった場合

OutOfMemoryError: システムがメモリ不足の場合

SDK/JRE 1.2 以降:

JDK 1.1 では、FindClass は CLASSPATH 内のローカルクラスだけを検索しました。検索されたクラスは、クラスローダを持っていませんでした。

Java セキュリティモデルは拡張され、システムクラス以外のクラスによるネイティブメソッドのロードおよび呼び出しが可能になりました。Java 2 プラットフォームでは、FindClass が、現在のネイティブメソッドと関連付けられているクラスローダを検出します。ネイティブコードがシステムクラスに属する場合、クラスローダは検出されま せん。それ以外の場合には、適切なクラスローダが呼び出され、名前が付けられたクラスのロードおよびリンクを行います。

FindClass が呼び出しインタフェースによって呼び出された場合、現在のネイティブメソッドまたはそれに関連付けられたクラスローダは存在しません。この場合、ClassLoader.getBaseClassLoader の結果が使用されます。これは、仮想マシンがアプリケーション用に作成するクラスローダです。java.class.path プロパティにリストされたクラスを検索できます。

GetSuperclass

jclass GetSuperclass(JNIEnv *env, jclass clazz);

clazz がクラス Object 以外のクラスを表す場合、この関数は、clazz によって指定されたクラスのスーパークラスを表すオブジェクトを返します。

clazz がクラス Object を指定する場合、または、clazz がインタフェースを表す場合は、この関数は null を返します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 10

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

戻り値:

clazz によって表されるクラスのスーパークラスまたは null を返します。

IsAssignableFrom

jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1,
jclass clazz2);

clazz1 のオブジェクトが安全に clazz2 へキャストされるかどうかを決定します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 11

パラメータ:

env: JNI インタフェースポインタ

clazz1: 最初のクラス引数

clazz2: 2 番目のクラス引数

戻り値:

次のいずれかが真の場合に JNI_TRUE を返します。

例外

Throw

jint Throw(JNIEnv *env, jthrowable obj);

java.lang.Throwable オブジェクトがスローされます。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 13

パラメータ:

env: JNI インタフェースポインタ

obj: java.lang.Throwable オブジェクト

戻り値:

成功の場合は「0」を返し、失敗の場合は負の値を返します。

例外:

java.lang.Throwable object obj

ThrowNew

jint ThrowNew(JNIEnv *env, jclass clazz,
const char *message);

message によって指定されたメッセージを使用して、指定されたクラスから例外オブジェクトを構築し、その例外がスローされるようにします。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 14

パラメータ:

env: JNI インタフェースポインタ

clazz: java.lang.Throwable のサブクラス

message: java.lang.Throwable オブジェクトの構築に使用するメッセージ文字列は変更後の UTF-8 に符号化されます。

戻り値:

成功の場合は「0」を返し、失敗の場合は負の値を返します。

例外:

新しく構築された java.lang.Throwable オ ブジェクト

ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);

例外がスローされるかどうかを決定します。例外は、ネイティブコードが ExceptionClear() を呼び出すか、または Java コードがその例外を処理するまでスローされた状態を続けます。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 15

パラメータ:

env: JNI インタフェースポインタ

戻り値:

現在スローされている例外オブジェクトを返します。現在、スローされている例外がない場合は、null を返します。

ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);

stderr など、例外およびスタックのバックトレースをシステムエラーのレポーティングチャネルにプリントします。これは、デバッグのために提供されている便利な ルーチンです。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 16

パラメータ:

env: JNI インタフェースポインタ

ExceptionClear

void ExceptionClear(JNIEnv *env);

現在スローされている例外があればそれをクリアします。現在スローされている例外がない場合は、このルーチンは影響を 及ぼしません。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 17

パラメータ:

env: JNI インタフェースポインタ

FatalError

void FatalError(JNIEnv *env, const char *msg);

致命的エラーを発生させます。VM による回復は期待されません。この関数は値を返しません。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 18

パラメータ:

env: JNI インタフェースポインタ

msg: エラーメッセージ文字列は変更後の UTF-8 に符号化されます。

ExceptionCheck

例外オブジェクトへのローカル参照を作成せずに、未処理の例外を確認するための便利な関数を以下に示します。

jboolean ExceptionCheck(JNIEnv *env);

未処理の例外がある場合は JNI_TRUE を、ない場合は JNI_FALSE を返します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 228
導入されたバージョン:

SDK/JRE 1.2

グローバル参照およびローカル参照

グローバル参照

NewGlobalRef

jobject NewGlobalRef(JNIEnv *env, jobject obj);

obj 引数によって参照されたオブジェクトの新しいグローバル参照を作成します。obj 引数は、グローバル参照またはローカル参照のどちらでも構いません。グローバル参照は、DeleteGlobalRef() を呼び出すことによって、必ず明示的に処理しておく必要があります。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 21

パラメータ:

env: JNI インタフェースポインタ

obj: グローバル参照またはローカル参照

戻り値:

グローバル参照を返します。システムがメモリ不足の場合は null を返します。

DeleteGlobalRef

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);

globalRef によって示されたグローバル参照を削除します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 22

パラメータ:

env: JNI インタフェースポインタ

globalRef: グローバル参照

ローカル参照

ローカル参照は、ネイティブメソッドの呼び出し期間中有効です。ローカル参照は、ネイティブメソッドが復帰すると自動的に解放されます。各ローカル 参照は、Java 仮想マシンのリソースをいくらか消費します。プログラマは、ネイティブメソッドがローカル参照を過剰に割り当てないように確認する必要があります。ローカ ル参照は、ネイティブメソッドが Java に復帰すると自動的に解放されますが、ローカル参照を過剰に割り当てると、ネイティブメソッドの実行中に VM がメモリを使い果たしてしまう可能性があります。

DeleteLocalRef

void DeleteLocalRef(JNIEnv *env, jobject localRef);

localRef によって示されたローカル参照を削除します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 23

パラメータ:

env: JNI インタフェースポインタ

localRef: ローカル参照

注:

JDK/JRE 1.1 は、上記の DeleteLocalRef関数を提供したため、プログラマは手 動でローカル参照を削除することができます。たとえば、ネイティブコードがオブジェクトの潜在的に大きな配列を繰り返しにより処理し、反復ごとに 1 つの要素を使用する場合、次の反復で新しいローカル参照が作成される前に、もう使用されない配列要素へのローカル参照を削除するのは良い方法です。

JDK/JRE 1.2 以降では、ローカル参照の有効期間の管理用に関数のセットが追加されました。追加された 4 つの関数は以下のとおりです。

EnsureLocalCapacity

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

現在のスレッドで最低限指定された数のローカル参照を作成できることを保証します。関数が正常に実行された場合には、0 が返されます。それ以外の場合には、負の数が返され OutOfMemoryError がスローされます。

ネイティブメソッドに入る前に、VM は自動的に最低 16 のローカル参照の作成を保証します。

下位互換性のために VM は、保証された容量以上にローカル参照を割り当てます(デバッグのサポートとして、VM がユーザに対し、ローカル参照の作成数が多すぎるという内容の警告を発する場合がある。JDK では、プログラマは -verbose:jni コマンド行オプションを供給し、これらのメッセージを有効にすることができる)。保証された容量を超えてしまい、これ以上ローカル参照を作成できない場 合、VM は、FatalError を呼び出します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 26
導入されたバージョン:

SDK/JRE 1.2

PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);

新しいローカル参照フレームを作成します。このフレームに最低限指定された数のローカル参照を作成できます。正常に実行された場合には、0 が返されます。失敗した場合には、負の数が返され、OutOfMemoryError がスローされます。

前回のローカルフレームで作成済みのローカル参照は、現在のローカルフレームでも依然として有効です。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 19
導入されたバージョン:

JDK/JRE 1.2

PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);

現在のローカル参照フレームを無効にし、すべてのローカル参照を解放します。そして指定された result オブジェクトに対する前回のローカル参照フレームのローカル参照を返します。

前回のフレームに参照を返す必要のない場合には、result として null を渡します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 20
導入されたバージョン:

JDK/JRE 1.2

NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);

ref と同じオブジェクトを参照する新しいローカル参照を作成します。渡された ref は、グローバル参照またはローカル参照である可能性があります。ref が null を参照している場合には、null が返されます。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 25
導入されたバージョン:

JDK/JRE 1.2

弱グローバル参照

弱グローバル参照は、特別な種類のグローバル参照です。通常のグローバル参照と異なり、弱グローバル参照を使用すると、配下の Java オブジェクトをガベージコレクトすることができます。弱グローバル参照は、グローバルまたはローカル参照が使用されている状況ならどこででも使用できま す。ガベージコレクタを実行すると、配下のオブジェクトが弱参照によってだけ参照されている場合、そのオブジェクトが解放されます。解放されたオブジェク トを参照する弱グローバル参照は、機能的に null と同等です。プログラマは、IsSameObject を使用して弱参照と null とを比較することにより、弱グローバル参照が解放されたオブジェクトを参照しているかどうか確認できます。

JNI の弱グローバル参照は、Java 2 プラットフォーム API (java.lang.ref およびそのクラス) の一部として入手可能な Java 弱参照の簡易版です。

解説     (2001年6月に追加)

ガベージコレクションはネイティブメソッドの実行中に発生するため、弱グローバル参照で参照されているオブジェクトはいつでも解放できます。弱 グローバル 参照は、グローバル参照が使用されているところならどこでも使用できますが、そのように使用すると予告なしで null と機能的に同等になる場合があるので、一般的には不適切です。

IsSameObject は弱グローバル参照が解放されたオブジェクトを参照しているかどうかを判別するのに使用できますが、オブジェクトがその直後に解放されるのを防止するわけ ではありません。そのため、プログラマはこの検査に基づいて、その後の JNI 呼び出しで弱グローバル参照が (null 参 照以外で) 使用されているかどうかを判別することはできません。

この継承制限を解消するため、JNI 関数 NewLocalRef または NewGlobalRef を使用して同一のオブジェクトへの標準 (強い) ローカル参照またはグローバル参照を取得し、この強い参照を使用して該当するオブジェクトにアクセスすることをお勧めします。オブジェクトが解放されてい る場合、この関数は null を返します。その他の場合、強い参照を返します (強い参照はオブジェクトが解放されるのを防止する)。オブジェクトへの直接アクセスが不要になったときは、オブジェクトを解放できるように、新しい参照 を明示的に削除する必要があります。

弱グローバル参照は、他の種類の弱い参照 (SoftReference クラスまたは WeakReference クラスの Java オブジェクト) よりも弱い参照です。特定のオブジェクトへの弱いグローバル参照は、そのオブジェクトを参照する SoftReference オブジェクトまたは WeakReference オブジェクトが参照を解除するまで、機能的に null と同等にはなりません。

弱グローバル参照は、ファイナライズを必要とするオブジェクトへのJava の内部参照よりも弱い参照です。弱グローバル参照 は、参照先のオブジェクトのファイナライザが存在する場合、それが完了するまで、null と機能的に同等にはなりません。

弱グローバル参照と PhantomReference との相互動作は未定義です。特に、Java VM の実装は、PhantomReference のあとに弱グローバル参照を処理する場合があり、PhantomReference オブジェクトでも参照されているオブジェクトを保持するために弱グローバル参照を使用することが可能な場合があります。弱グローバル参照をこのような未定 義の方法で使用するのは避けるべきです。

NewWeakGlobalRef

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

弱グローバル参照を新規作成します。obj が null を参照している場合、または VM がメモリを使い果たしてしまった場合は、null が返されます。VM がメモリを使い果たしてしまった場合、OutOfMemoryError がスローされます。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 226
導入されたバージョン:

JDK/JRE 1.2

DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

渡された弱グローバル参照に必要な VM リソースを削除します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 227
導入されたバージョン:

JDK/JRE 1.2

オブジェクト操作

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

オブジェクト用としてコンストラクタを呼び出さずに、新しい Java オブジェクトを割り当てます。オブジェクトに対する参照を返します。

clazz 引数は、配列クラスを参照してはなりません。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 27

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

戻り値:

Java オブジェクトを返します。Java オブジェクトが構築できなかった場合は、null を返します。

例外:

InstantiationException: クラスがインタフェースまたは abstract クラスの場合

OutOfMemoryError: システムがメモリ不足の場合

NewObject
NewObjectA
NewObjectV

jobject NewObject(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);

jobject NewObjectA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

jobject NewObjectV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

Java オブジェクトを構築します。メソッド ID は、呼び出すべきコンストラクタメソッドを表しています。この ID は、メソッド名として <init> を、また戻り値の型として void (V) を使用して GetMethodID() を呼び出すことによって取得しなければなりません。

clazz 引数は、配列クラスを参照してはなりません。

NewObject

プログラマは、コンストラクタに渡す引数をすべて、methodID 引数のすぐあとに置きます。NewObject() は、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 28

NewObjectA

プログラマは、コンストラクタに渡す引数をすべて、methodID 引数のすぐあとに続く jvalues の args 配列内に置きます。NewObjectA() はこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 30

NewObjectV

プログラマは、コンストラクタに渡す引数をすべて、methodID 引数のすぐあとに続く型 va_list の args 引数内に置きます。NewObjectV() はこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 29

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

methodID: コンストラクタのメソッド ID

NewObject に必要な追加パラメータ:

コンストラクタの引数

NewObjectA に必要な追加パラメータ:

args: コンストラクタの引数の配列

NewObjectV に必要な追加パラメータ:

args: コンストラクタの引数の va_list

戻り値:

Java オブジェクトを返します。Java オブジェクトが構築できなかった場合は、null を返します。

例外:

InstantiationException: クラスがインタフェースまたは abstract クラスの場合

OutOfMemoryError: システムがメモリ不足の場合

コンストラクタによってスローされるすべての例外

GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);

オブジェクトのクラスを返します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 31

パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト (null であってはならない)

戻り値:

Java クラスオブジェクトを返します。

IsInstanceOf

jboolean IsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);

オブジェクトがクラスのインスタンスであるかどうかをチェックします。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 32

パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト

clazz: Java クラスオブジェクト

戻り値:

obj を clazz にキャストすることができる場合は、JNI_TRUE を返します。そうでない場合は、JNI_FALSE を返します。null オブジェクトは、どのクラスにもキャストすることができます。

IsSameObject

jboolean IsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);

2 つの参照が同じ Java オブジェクトを参照するかどうかをテストします。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 24

パラメータ:

env: JNI インタフェースポインタ

ref1: Java オブジェクト

ref2: Java オブジェクト

戻り値:

ref1 と ref2 が同じ Java オブジェクトを参照する場合、または、両方が null である場合は、JNI_TRUE を返します。それ以外の場合は、JNI_FALSE を返します。

オブジェクトのフィールドへのアクセス

GetFieldID

jfieldID GetFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

クラスのインスタンス (非 static) フィールドを表すフィールド ID を返します。このフィールドは、その名前とシグニチャーで指定します。アクセス用関数の Get<type>Field ファミリと Set<type>Field ファミリは、フィールド ID を使用してオブジェクトフィールドを取り出します。

GetFieldID() によって、まだ初期化されていないクラスが初期化されます。

配列の長さフィールドを得るために GetFieldID() を使用することはできません。代わりに、 GetArrayLength() を使用してください。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 94

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

name: 0 で終了する変更後の UTF-8 文字列内のフィールド名

sig: 0 で終了する変更後の UTF-8 文字列内のフィールドシグニチャー

戻り値:

フィールド ID を返します。 演算が失敗した場合は null を返します。

例外:

NoSuchFieldError: 指定されたフィールドが見つからない場合

ExceptionInInitializerError: 例外のため、クラス初期化が失敗した場合

OutOfMemoryError: システムがメモリ不足の場合

Get<type>Field ルーチン

NativeType Get<type>Field(JNIEnv *env, jobject obj,
jfieldID fieldID);

このアクセス用ルーチンのファミリは、オブジェクトのインスタンス (非 static) フィールドの値を返します。アクセスすべきフィールドは、 GetFieldID() を呼び出すことによって得られるフィールド ID を使用して指定します。

次の表には、Get<type>Field ルーチン名と結果の型が示されています。Get<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際のルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-1a アクセス用ルーチンの Get<type>Field ファミリ
Get<type>Field ルーチン名
ネイティブ型
GetObjectField()
jobject
GetBooleanField()
jboolean
GetByteField()
jbyte
GetCharField()
jchar
GetShortField()
jshort
GetIntField()
jint
GetLongField()
jlong
GetFloatField()
jfloat
GetDoubleField()
jdouble

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス

表 4-1b アクセス用ルーチンの Get<type>Field ファミリ
Get<type>Field ルーチン名
索引
GetObjectField()
95
GetBooleanField()
96
GetByteField()
97
GetCharField()
98
GetShortField()
99
GetIntField()
100
GetLongField()
101
GetFloatField()
102
GetDoubleField()
103

パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト (null であってはならない)

fieldID: 有効フィールド ID

戻り値:

フィールドの内容を返します。

Set<type>Field ルーチン

void Set<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);

このアクセス用ルーチンのファミリは、オブジェクトのインスタンス (非 static) フィールドの値を設定します。アクセスすべきフィールドは、 GetFieldID() を呼び出すことによって得られるフィールド ID を使用して指定します。

次の表には、Set<type>Field ルーチン名と値の型が示されています。Set<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際のルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-2a アクセス用ルーチンの Set<type>Field ファミリ
Set<type>Field ルーチン
ネイティブ型
SetObjectField()
jobject
SetBooleanField()
jboolean
SetByteField()
jbyte
SetCharField()
jchar
SetShortField()
jshort
SetIntField()
jint
SetLongField()
jlong
SetFloatField()
jfloat
SetDoubleField()
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-2b アクセス用ルーチンの Set<type>Field ファミリ
Set<type>Field ルーチン
索引
SetObjectField()
104
SetBooleanField()
105
SetByteField()
106
SetCharField()
107
SetShortField()
108
SetIntField()
109
SetLongField()
110
SetFloatField()
111
SetDoubleField()
112
パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト (null であってはならない)

fieldID: 有効フィールド ID

value: そのフィールドの新しい値

インスタンスメソッドの呼び出し

GetMethodID

jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

クラスまたはインタフェースのインスタンス (非 static) メソッドを表すメソッド ID を返します。このメソッドは、clazz のスーパークラスの 1 つの中で定義し、clazz によって継承できます。このメソッドは、その名前およびシグニチャーによって決定されます。

GetMethodID() によって、まだ初期化されていないクラスが初期化されます。

コンストラクタのメソッド ID を取得するには、メソッド名として <init> を指定し、戻り値の型として void (V) を指定します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 33

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

name: 0 で終了する変更後の UTF-8 文字列内のメソッド名

sig: 0 で終了する変更後の UTF-8 文字列内のメソッドシグニチャー

戻り値:

メソッド ID を返します。指定されたメソッドが見つからなかった場合は、null を返します。

例外:

NoSuchMethodError: 指定されたメソッドが見つからない場合

ExceptionInInitializerError: 例外のため、クラス初期化が失敗した場合

OutOfMemoryError: システムがメモリ不足の場合

Call<type>Method ルーチン
Call<type>MethodA ルーチン
Call<type>MethodV ルーチン

NativeType Call<type>Method(JNIEnv *env, jobject obj,
jmethodID methodID, ...);

NativeType Call<type>MethodA(JNIEnv *env, jobject obj,
jmethodID methodID, jvalue *args);

NativeType Call<type>MethodV(JNIEnv *env, jobject obj,
jmethodID methodID, va_list args);

これら 3 種類の演算ファミリは、ネイティブメソッドから Java インスタンスメソッドを呼び出す際に使用されます。これら 3 種類のファミリは、呼び出したメソッドにパラメータを渡す機構が異なるだけです。

これらの演算ファミリは、指定されたメソッド ID に従って、Java オブジェクト上のインスタンス (非 static) メソッドを呼び出します。methodID 引数は、GetMethodID() を呼び出すことによって取得する必要があります。

これらの関数を private メソッドやコンストラクタを呼び出すために使用する場合は、メソッド ID を obj の実クラスのスーパークラスの 1 つからではなく、実クラス自体から導き出す必要があります。

Call<type>Method ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに置きます。Call<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

Call<type>MethodA ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに続く jvalues の args 配列内に置きます。Call<type>MethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

Call<type>MethodV ルーチン

プログラマは、そのメソッドに渡す引数をすべて、methodID 引数のすぐあとに続く型 va_list の args 引数内に置きます。Call<type>MethodV ルーチンは、引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

次の表には、メソッド呼び出しルーチンの各々がその結果の型に応じて示されています。Call<type>Method 内の type を、呼び出しているメソッドの Java 型と置き換え (または、表の実際のメソッド呼び出しルーチン名の 1 つを使用する)、かつ NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-3a インスタンスメソッドを呼び出すルーチン
Call<type>Method ルーチン名
ネイティブ型
CallVoidMethod()
CallVoidMethodA()
CallVoidMethodV()
void
CallObjectMethod()
CallObjectMethodA()
CallObjectMethodV()
jobject
CallBooleanMethod()
CallBooleanMethodA()
CallBooleanMethodV()
jboolean
CallByteMethod()
CallByteMethodA()
CallByteMethodV()
jbyte
CallCharMethod()
CallCharMethodA()
CallCharMethodV()
jchar
CallShortMethod()
CallShortMethodA()
CallShortMethodV()
jshort
CallIntMethod()
CallIntMethodA()
CallIntMethodV()
jint
CallLongMethod()
CallLongMethodA()
CallLongMethodV()
jlong
CallFloatMethod()
CallFloatMethodA()
CallFloatMethodV()
jfloat
CallDoubleMethod()
CallDoubleMethodA()
CallDoubleMethodV()
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-3b インスタンスメソッドを呼び出すルーチン
Call<type>Method ルーチン名
索引
CallVoidMethod()
CallVoidMethodA()
CallVoidMethodV()

61
63
62
CallObjectMethod()
CallObjectMethodA()
CallObjectMethodV()

34
36
35
CallBooleanMethod()
CallBooleanMethodA()
CallBooleanMethodV()

37
39
38
CallByteMethod()
CallByteMethodA()
CallByteMethodV()

40
42
41
CallCharMethod()
CallCharMethodA()
CallCharMethodV()

43
45
44
CallShortMethod()
CallShortMethodA()
CallShortMethodV()

46
48
47
CallIntMethod()
CallIntMethodA()
CallIntMethodV()

49
51
50
CallLongMethod()
CallLongMethodA()
CallLongMethodV()

52
54
53
CallFloatMethod()
CallFloatMethodA()
CallFloatMethodV()

55
57
56
CallDoubleMethod()
CallDoubleMethodA()
CallDoubleMethodV()

58
60
59
パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト

methodID: メソッド ID

Call<type>Method ルーチンに必要な追加パラメータ:

メソッドに対する引数

Call<type>MethodA ルーチンに必要な追加パラメータ:

args: 引数の配列

Call<type>MethodV ルーチンに必要な追加パラメータ:

args: 引数の va_list

戻り値:

Java メソッドを呼び出した結果を返します。

例外:

Java メソッドを実行している間に発生した例外

CallNonvirtual<type>Method ルーチン
CallNonvirtual<type>MethodA ルーチン
CallNonvirtual<type>MethodV ルーチン

NativeType CallNonvirtual<type>Method(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, ...);

NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, jvalue *args);

NativeType CallNonvirtual<type>MethodV(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, va_list args);

これらの演算ファミリは、指定されたクラスおよびメソッド ID に従って、Java オブジェクト上のインスタンス (非 static) メソッドを呼び出します。methodID 引数は、クラス clazz に対して GetMethodID() を呼び出すことによって取得する必要があります。

CallNonvirtual<type>Method ルーチンファミリと Call<type>Method ルーチンファミリとは異なります。Call<type>Method ルーチンは、オブジェクトのクラスに基づいてメソッドを呼び出しますが、CallNonvirtual<type>Method ルーチンは、メソッド ID を取得できるクラス (clazz パラメータによって指定) に基づいてメソッドを呼び出します。メソッド ID は、このオブジェクトの実クラスまたはその実クラスのスーパークラスの 1 つから取得しなければなりません。

CallNonvirtual<type>Method ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに置きます。CallNonvirtual<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

CallNonvirtual<type>MethodA ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに続く jvalues の args 配列内に置きます。CallNonvirtual<type>MethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

CallNonvirtual<type>MethodV ルーチン

プログラマは、そのメソッドに渡す引数をすべて、methodID 引数のすぐあとに続く型 va_list の args 引数内に置きます。CallNonvirtualMethodV ルーチンはこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

次の表には、メソッド呼び出しルーチンの各々がその結果の型に応じて示されています。CallNonvirtual<type>Method 内の type をメソッドの Java 型と置き換えるか、あるいは表の実際のメソッド呼び出しルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-4a CallNonvirtual<type>Method ルーチン
CallNonvirtual<type>Method ルーチン名
ネイティブ型
CallNonvirtualVoidMethod()
CallNonvirtualVoidMethodA()
CallNonvirtualVoidMethodV()
void
CallNonvirtualObjectMethod()
CallNonvirtualObjectMethodA()
CallNonvirtualObjectMethodV()
jobject
CallNonvirtualBooleanMethod()
CallNonvirtualBooleanMethodA()
CallNonvirtualBooleanMethodV()
jboolean
CallNonvirtualByteMethod()
CallNonvirtualByteMethodA()
CallNonvirtualByteMethodV()
jbyte
CallNonvirtualCharMethod()
CallNonvirtualCharMethodA()
CallNonvirtualCharMethodV()
jchar
CallNonvirtualShortMethod()
CallNonvirtualShortMethodA()
CallNonvirtualShortMethodV()
jshort
CallNonvirtualIntMethod()
CallNonvirtualIntMethodA()
CallNonvirtualIntMethodV()
jint
CallNonvirtualLongMethod()
CallNonvirtualLongMethodA()
CallNonvirtualLongMethodV()
jlong
CallNonvirtualFloatMethod()
CallNonvirtualFloatMethodA()
CallNonvirtualFloatMethodV()
jfloat
CallNonvirtualDoubleMethod()
CallNonvirtualDoubleMethodA()
CallNonvirtualDoubleMethodV()
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-4b CallNonvirtual<type>Method ルーチン
CallNonvirtual<type>Method ルーチン名
索引
CallNonvirtualVoidMethod()
CallNonvirtualVoidMethodA()
CallNonvirtualVoidMethodV()
91
93
92
CallNonvirtualObjectMethod()
CallNonvirtualObjectMethodA()
CallNonvirtualObjectMethodV()
64
66
65
CallNonvirtualBooleanMethod()
CallNonvirtualBooleanMethodA()
CallNonvirtualBooleanMethodV()
67
69
68
CallNonvirtualByteMethod()
CallNonvirtualByteMethodA()
CallNonvirtualByteMethodV()
70
72
71
CallNonvirtualCharMethod()
CallNonvirtualCharMethodA()
CallNonvirtualCharMethodV()
73
75
74
CallNonvirtualShortMethod()
CallNonvirtualShortMethodA()
CallNonvirtualShortMethodV()
76
78
77
CallNonvirtualIntMethod()
CallNonvirtualIntMethodA()
CallNonvirtualIntMethodV()
79
81
80
CallNonvirtualLongMethod()
CallNonvirtualLongMethodA()
CallNonvirtualLongMethodV()
82
84
83
CallNonvirtualFloatMethod()
CallNonvirtualFloatMethodA()
CallNonvirtualFloatMethodV()
85
87
86
CallNonvirtualDoubleMethod()
CallNonvirtualDoubleMethodA()
CallNonvirtualDoubleMethodV()
88
90
89
パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラス

obj: Java オブジェクト

methodID: メソッド ID

CallNonvirtual<type>Method ルーチンに必要な追加パラメータ:

メソッドに対する引数

CallNonvirtual<type>MethodA ルーチンに必要な追加パラメータ:

args: 引数の配列

CallNonvirtual<type>MethodV ルーチンに必要な追加パラメータ:

args: 引数の va_list

戻り値:

Java メソッドを呼び出した結果を返します。

例外:

Java メソッドを実行している間に発生した例外

static フィールドへのアクセス

GetStaticFieldID

jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

クラスの static フィールドを表すフィールド ID を返します。このフィールドは、その名前とシグニチャーで指定します。アクセス用関数の GetStatic<type>Field ファミリと SetStatic<type>Field ファミリは、フィールド ID を使用して static フィールドを取り出します。

GetStaticFieldID() によって、まだ初期化されていないクラスが初期化されます。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 144

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

name: 0 で終了する変更後の UTF-8 文字列内の static フィールド

sig: 0 で終了する変更後の UTF-8 文字列内のフィールドシグニチャー

戻り値:

フィールド ID を返します。 指定された static フィールドが見つからなかった場合は、null を返します。

例外:

NoSuchFieldError: 指定された static フィールドが見つからない場合

ExceptionInInitializerError: 例外のため、クラス初期化が失敗した場合

OutOfMemoryError: システムがメモリ不足の場合

GetStatic<type>Field ルーチン

NativeType GetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID);

このアクセス用ルーチンのファミリは、オブジェクトの static フィールドを返します。アクセスするフィールドは、フィールド ID で指定します。 フィールド ID は、GetStaticFieldID() を呼び出すことによって取得することができます。

次の表には、 get ルーチン名のファミリと結果の型が示されています。GetStatic<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際の static フィールドアクセス用ルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-5a アクセス用ルーチンの GetStatic<type>Field ファミリ
GetStatic<type>Field ルーチン名
ネイティブ型
GetStaticObjectField()
jobject
GetStaticBooleanField()
jboolean
GetStaticByteField()
jbyte
GetStaticCharField()
jchar
GetStaticShortField()
jshort
GetStaticIntField()
jint
GetStaticLongField()
jlong
GetStaticFloatField()
jfloat
GetStaticDoubleField()
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-5b アクセス用ルーチンの GetStatic<type>Field ファミリ
GetStatic<type>Field ルーチン名
索引
GetStaticObjectField()
145
GetStaticBooleanField()
146
GetStaticByteField()
147
GetStaticCharField()
148
GetStaticShortField()
149
GetStaticIntField()
150
GetStaticLongField()
151
GetStaticFloatField()
152
GetStaticDoubleField()
153
パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

fieldID: static フィールド ID

戻り値:

static フィールドの内容を返します。

SetStatic<type>Field ルーチン

void SetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID, NativeType value);

このアクセス用ルーチンのファミリは、オブジェクトの static フィールドの値を設定します。アクセスするフィールドは、フィールド ID で指定します。 フィールド ID は、GetStaticFieldID() を呼び出すことによって取得することができます。

次の表には、セットルーチン名と値の型が示されています。SetStatic<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際のセット static フィールドルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-6a アクセス用ルーチンの SetStatic<type>Field ファミリ
SetStatic<type>Field ルーチン名
ネイティブ型
SetStaticObjectField()
jobject
SetStaticBooleanField()
jboolean
SetStaticByteField()
jbyte
SetStaticCharField()
jchar
SetStaticShortField()
jshort
SetStaticIntField()
jint
SetStaticLongField()
jlong
SetStaticFloatField()
jfloat
SetStaticDoubleField()
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-6b アクセス用ルーチンの SetStatic<type>Field ファミリ
SetStatic<type>Field ルーチン名
索引
SetStaticObjectField()
154
SetStaticBooleanField()
155
SetStaticByteField()
156
SetStaticCharField()
157
SetStaticShortField()
158
SetStaticIntField()
159
SetStaticLongField()
160
SetStaticFloatField()
161
SetStaticDoubleField()
162
パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

fieldID: static フィールド ID

value: そのフィールドの新しい値

static メソッドの呼び出し

GetStaticMethodID

jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

クラスの static メソッドを表すメソッド ID を返します。このメソッドは、その名前とシグニチャーで指定します。

GetStaticMethodID() によって、まだ初期化されていないクラスが初期化されます。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 113
パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

name: 0 で終了する変更後の UTF-8 文字列内の static メソッド名

sig: 0 で終了する変更後の UTF-8 文字列内のメソッドシグニチャー

戻り値:

メソッド ID を返します。演算が失敗した場合は null を返します。

例外:

NoSuchMethodError: 指定された static メソッドが見つからない場合

ExceptionInInitializerError: 例外のため、クラス初期化が失敗した場合

OutOfMemoryError: システムがメモリ不足の場合

CallStatic<type>Method ルーチン
CallStatic<type>MethodA ルーチン
CallStatic<type>MethodV ルーチン

NativeType CallStatic<type>Method(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);

NativeType CallStatic<type>MethodA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

NativeType CallStatic<type>MethodV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

この演算ファミリは、指定されたメソッド ID に従って、Java オブジェクト上の static メソッドを呼び出します。methodID 引数は、GetStaticMethodID() を呼び出すことによって取得する必要があります。

メソッド ID は、clazz のスーパークラスの 1 つからではなく、clazz 自体から導き出す必要があります。

CallStatic<type>Method ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに置きます。CallStatic<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

CallStatic<type>MethodA ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに続く jvalues の args 配列内に置きます。CallStaticMethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

CallStatic<type>MethodV ルーチン

プログラマは、そのメソッドに渡す引数をすべて、methodID 引数のすぐあとに続く型 va_list の args 引数内に置きます。CallStaticMethodV はこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

次の表には、メソッド呼び出しルーチンが各々その結果の型によって示されています。CallStatic<type>Method 内の type をメソッドの Java 型または表の実際のメソッド呼び出しルーチン名の 1 つと置き換えるか、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-7a CallStatic<type>Method を呼び出すルーチン
CallStatic<type>Method ルーチン名
ネイティブ型
CallStaticVoidMethod()
CallStaticVoidMethodA()
CallStaticVoidMethodV()
void
CallStaticObjectMethod()
CallStaticObjectMethodA()
CallStaticObjectMethodV()
jobject
CallStaticBooleanMethod()
CallStaticBooleanMethodA()
CallStaticBooleanMethodV()
jboolean
CallStaticByteMethod()
CallStaticByteMethodA()
CallStaticByteMethodV()
jbyte
CallStaticCharMethod()
CallStaticCharMethodA()
CallStaticCharMethodV()
jchar
CallStaticShortMethod()
CallStaticShortMethodA()
CallStaticShortMethodV()
jshort
CallStaticIntMethod()
CallStaticIntMethodA()
CallStaticIntMethodV()
jint
CallStaticLongMethod()
CallStaticLongMethodA()
CallStaticLongMethodV()
jlong
CallStaticFloatMethod()
CallStaticFloatMethodA()
CallStaticFloatMethodV()
jfloat
CallStaticDoubleMethod()
CallStaticDoubleMethodA()
CallStaticDoubleMethodV()
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-7b CallStatic<type>Method を呼び出すルーチン
CallStatic<type>Method ルーチン名
索引
CallStaticVoidMethod()
CallStaticVoidMethodA()
CallStaticVoidMethodV()
141
143
142
CallStaticObjectMethod()
CallStaticObjectMethodA()
CallStaticObjectMethodV()
114
116
115
CallStaticBooleanMethod()
CallStaticBooleanMethodA()
CallStaticBooleanMethodV()
117
119
118
CallStaticByteMethod()
CallStaticByteMethodA()
CallStaticByteMethodV()
120
122
121
CallStaticCharMethod()
CallStaticCharMethodA()
CallStaticCharMethodV()
123
125
124
CallStaticShortMethod()
CallStaticShortMethodA()
CallStaticShortMethodV()
126
128
127
CallStaticIntMethod()
CallStaticIntMethodA()
CallStaticIntMethodV()
129
131
130
CallStaticLongMethod()
CallStaticLongMethodA()
CallStaticLongMethodV()
132
134
133
CallStaticFloatMethod()
CallStaticFloatMethodA()
CallStaticFloatMethodV()
135
137
136
CallStaticDoubleMethod()
CallStaticDoubleMethodA()
CallStaticDoubleMethodV()
138
140
139
パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

methodID: static メソッド ID

CallStatic<type>Method ルーチンに必要な追加パラメータ:

static メソッドの引数

CallStatic<type>MethodA ルーチンに必要な追加パラメータ:

args: 引数の配列

CallStatic<type>MethodV ルーチンに必要な追加パラメータ:

args: 引数の va_list

戻り値:

static Java メソッドを呼び出した結果を返します。

例外:

Java メソッドを実行している間に発生した例外

文字列操作

NewString

jstring NewString(JNIEnv *env, const jchar *unicodeChars,
jsize len);

Unicode 文字配列から新しい java.lang.String オブジェクトを構築します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 163
パラメータ:

env: JNI インタフェースポインタ

unicodeChars: Unicode 文字列を参照するポインタ

len: Unicode 文字列の長さ

戻り値:

Java 文字列オブジェクトを返します。 文字列が構築できない場合は null を返します。

例外:

OutOfMemoryError: システムがメモリ不足の場合

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

Java 文字列の長さ (Unicode 文字のカウント) を返します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 164
パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

戻り値:

Java 文字列の長さを返します。

GetStringChars

const jchar * GetStringChars(JNIEnv *env, jstring string,
jboolean *isCopy);

文字列の Unicode 文字の配列を参照するポインタを返します。このポインタは、ReleaseStringchars() が呼び出されるまで有効です。

isCopy が null ではない場合にコピーが作成されると、*isCopy は JNI_TRUE に設定されます。コピーが作成されない場合は、JNI_FALSE に設定されます。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 165
パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

isCopy: ブール値に対するポインタ

戻り値:

Unicode 文字列を参照するポインタを返します。演算が失敗した場合は null を返します。

ReleaseStringChars

void ReleaseStringChars(JNIEnv *env, jstring string,
const jchar *chars);

ネイティブコードが chars へのアクセスをもはや必要としていないことを VM に知らせます。chars 引数は、GetStringChars() を使用してstring から取得することができるポインタです。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 166
パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

chars: Unicode 文字列を参照するポインタ

NewStringUTF

jstring NewStringUTF(JNIEnv *env, const char *bytes);

変更後の UTF-8 文字の配列から新しい java.lang.String オブジェクトを構築します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 167
パラメータ:

env: JNI インタフェースポインタ

bytes: 変更後の UTF-8 文字列を参照するポインタ

戻り値:

Java 文字列オブジェクトを返します。 文字列が構築できない場合は null を返します。

例外:

OutOfMemoryError: システムがメモリ不足の場合

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

変更後の UTF-8 で表現した文字列の長さをバイトで返します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 168
パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

戻り値:

文字列の UTF-8 長を返します。

GetStringUTFChars

const jbyte* GetStringUTFChars(JNIEnv *env, jstring string,
jboolean *isCopy);

変更後の UTF-8 で文字列を表すバイト配列を参照するポインタを返します。この配列は、ReleaseStringUTFChars() によって解放されるまで有効です。

isCopy が null ではない場合にコピーが作成されると、*isCopy は JNI_TRUE に設定されます。コピーが作成されない場合は、JNI_FALSE に設定されます。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 169
パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

isCopy: ブール値に対するポインタ

戻り値:

変更後の UTF-8 文字列を参照するポインタを返します。演算が失敗した場合は null を返します。

ReleaseStringUTFChars

void ReleaseStringUTFChars(JNIEnv *env, jstring string,
const char *utf);

ネイティブコードが utf へのアクセスをもはや必要としていないことを VM に知らせます。utf 引数は、GetStringUTFChars() を使用して string から取得することができるポインタです。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 170
パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

utf: 変更後の UTF-8 文字列を参照するポインタ

注:

SKD/JRE 1.1 では、プログラマはユーザが提供するバッファのプリミティブ配列要素を取得できました。JDK/JRE 1.2 以降のバージョンでは、ネイティブコードを使用して、ユーザが提供するバッファの Unicode (UTF-16) または変更後の UTF-8 エンコーディングされた文字を取得することができます。以下の関数を参照してください。

GetStringRegion

void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf);

オフセット start で始まる len 個の Unicode 文字を、与えられたバッファ buf にコピーします。

StringIndexOutOfBoundsException をインデックスオーバーフロー時にスローします。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 220
導入されたバージョン:

JDK/JRE 1.2

GetStringUTFRegion

< void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);

オフセット start で始まる len 個の Unicode 文字を変更後の UTF-8 エンコーディングに変換し、その結果を与えられたバッファ buf に置きます。

StringIndexOutOfBoundsException をインデックスオーバーフロー時にスローします。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 221
導入されたバージョン:

JDK/JRE 1.2

GetStringCritical
ReleaseStringCritical

const jchar * GetStringCritical(JNIEnv *env, jstring string, jboolean *isCopy);
void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar *carray);

上の 2 つの関数のセマンティクスは、既存の Get/ReleaseStringChars 関数に似ています。可能な場合には、VM は文字列要素へのポインタを返します。そうでない場合、コピーが作成されます。ただし、これら の関数の使用方法に関して重要な制限があります。Get/ReleaseStringCritical の呼び出しによって囲まれるコードセグメントにおいて、ネイティブコードは任意の JNI 呼び出しを行なったり、現在のスレッドにブロックさせてはなりません。

Get/ReleaseStringCritical の制限は、Get/ReleasePrimitiveArrayCritical の制限と類似しています。

リンケージ (GetStringCritical）:
JNIEnv インタフェース関数テーブルのインデックス 224
リンケージ (ReleaseStingCritical）:
JNIEnv インタフェース関数テーブルのインデックス 225
導入されたバージョン:

JDK/JRE 1.2

配列操作

GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

配列内の要素の数を返します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 171
パラメータ:

env: JNI インタフェースポインタ

array: Java 配列オブジェクト

戻り値:

配列の長さを返します。

NewObjectArray

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

クラス elementClass にオブジェクトを持つ新しい配列を構築します。要素はすべて、最初に initialElement に設定されます。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 172
パラメータ:

env: JNI インタフェースポインタ

length: 配列サイズ

elementClass: 配列要素クラス

initialElement: 初期化値

戻り値:

Java 配列オブジェクトを返します。 Java 配列が構築できなかった場合は null を返します。

例外:

OutOfMemoryError: システムがメモリ不足の場合

GetObjectArrayElement

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

Object 配列の要素を返します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 173
パラメータ:

env: JNI インタフェースポインタ

array: Java 配列

index: 配列添字

戻り値:

Java オブジェクトを返します。

例外:

ArrayIndexOutOfBoundsException: index が配列内に有効な添字の値を指定しなかった場合

SetObjectArrayElement

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

Object 配列の要素を設定します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 174
パラメータ:

env: JNI インタフェースポインタ

array: Java 配列

index: 配列添字

value: 新しい値

例外:

ArrayIndexOutOfBoundsException: index が配列内に有効な添字の値を指定しなかった場合

ArrayStoreException: value のクラスが、配列の要素クラスのサブクラスではない場合

New<PrimitiveType>Array ルーチン

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

新しいプリミティブ配列オブジェクトを構築するために使用される演算のファミリ。表 4-8 には、特定のプリミティブ配列コンストラクタが示されています。New<PrimitiveType>Array を、次の表の実際のプリミティブ配列コンストラクタルーチン名の 1 つと置き換え、ArrayType をそのルーチンに対応する配列型と置き換える必要があります。

表 4-8a 配列コンストラクタの New<PrimitiveType>Array ファミリ
New<PrimitiveType>Array ルーチン
配列型
NewBooleanArray()
jbooleanArray
NewByteArray()
jbyteArray
NewCharArray()
jcharArray
NewShortArray()
jshortArray
NewIntArray()
jintArray
NewLongArray()
jlongArray
NewFloatArray()
jfloatArray
NewDoubleArray()
jdoubleArray

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-8b 配列コンストラクタの New<PrimitiveType>Array ファミリ
New<PrimitiveType>Array ルーチン
索引
NewBooleanArray()
175
NewByteArray()
176
NewCharArray()
177
NewShortArray()
178
NewIntArray()
179
NewLongArray()
180
NewFloatArray()
181
NewDoubleArray()
182
パラメータ:

env: JNI インタフェースポインタ

length: 配列長

戻り値:

Java 配列を返します。Java 配列が構築できなかった場合は null を返します。

Get<PrimitiveType>ArrayElements ルーチン

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

プリミティブ配列の本体を返す関数のファミリです。その結果は、対応する Release<PrimitiveType>ArrayElements() 関数が呼び出されるまで有効です。返された配列は Java 配列のコピーである場合もあるため、その返された配列に加えられている変更は、Release<PrimitiveType>ArrayElements() が呼び出されるまでは、必ずしも元の array に反映されているとは限りません。

isCopy が null ではない場合にコピーが作成されると、*isCopy は JNI_TRUE に設定されます。コピーが作成されない場合は、JNI_FALSE に設定されます。

次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。

Java VM 内でブール配列がどのように表されているかにかかわらず、GetBooleanArrayElements() は常に jbooleans を参照するポインタを返してきます。 各バイトが 1 つの要素を表しています (アンパック表示)。その他の型の配列はすべて、メモリ内で必ず隣接するようになっています。

表 4-9a アクセス用ルーチンの Get<PrimitiveType>ArrayElements ファミリ
Get<PrimitiveType>ArrayElements ルーチン
配列型
ネイティブ型
GetBooleanArrayElements()
jbooleanArray
jboolean
GetByteArrayElements()
jbyteArray
jbyte
GetCharArrayElements()
jcharArray
jchar
GetShortArrayElements()
jshortArray
jshort
GetIntArrayElements()
jintArray
jint
GetLongArrayElements()
jlongArray
jlong
GetFloatArrayElements()
jfloatArray
jfloat
GetDoubleArrayElements()
jdoubleArray
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-9b アクセス用ルーチンの Get<PrimitiveType>ArrayElements ファミリ
Get<PrimitiveType>ArrayElements ルーチン
索引
GetBooleanArrayElements()
183
GetByteArrayElements()
184
GetCharArrayElements()
185
GetShortArrayElements()
186
GetIntArrayElements()
187
GetLongArrayElements()
188
GetFloatArrayElements()
189
GetDoubleArrayElements()
190
パラメータ:

env: JNI インタフェースポインタ

array: Java 文字列オブジェクト

isCopy: ブール値に対するポインタ

戻り値:

配列要素を参照するポインタを返します。演算が失敗した場合は、null を返します。

Release<PrimitiveType>ArrayElements ルーチン

void Release<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, NativeType *elems, jint mode);

ネイティブコードが elems へのアクセスをもはや必要としていないことを VM に知らせる関数のファミリです。elems 引数は、対応する Get<PrimitiveType>ArrayElements() 関数を使用して、array から導き出されるポインタです。必要に応じて、この関数は、 elems に施された変更をすべて元の配列にコピーし直します。

mode 引数は、配列バッファの解放方法に関する情報を提供します。 mode は、elems が array 内の要素のコピーではない場合は、影響を及ぼしません。mode が array 内の要素のコピーである場合は、次の表に示されているような影響を及ぼします。

表 4-10 プリミティブ配列解放モード
mode
動作
0
内容をコピーバックし、elems バッファを解放する
JNI_COMMIT
内容をコピーバックするが、elems バッファを解放しない
JNI_ABORT
変更の可能性があってもその変更をコピーバックせずに、バッファを解放する

多くの場合、プログラマは、ピン配列とコピー配列の両方に対して一貫した動作を保証するために、「0�を mode 引数に渡します。0 以外を渡す場合は、プログラマはメモリを十分に注意して管理する必要があります。

次の表には、プリミティブ配列処置機能のファミリを構成する特定のルーチンが示されています。次の置換を行う必要があ ります。

表 4-11a アクセス用ルーチンの Release<PrimitiveType>ArrayElements ファミリ
Release<PrimitiveType>ArrayElements ルーチン
配列型
ネイティブ型
ReleaseBooleanArrayElements()
jbooleanArray
jboolean
ReleaseByteArrayElements()
jbyteArray
jbyte
ReleaseCharArrayElements()
jcharArray
jchar
ReleaseShortArrayElements()
jshortArray
jshort
ReleaseIntArrayElements()
jintArray
jint
ReleaseLongArrayElements()
jlongArray
jlong
ReleaseFloatArrayElements()
jfloatArray
jfloat
ReleaseDoubleArrayElements()
jdoubleArray
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-11b アクセス用ルーチンの Release<PrimitiveType>ArrayElements ファミリ
Release<PrimitiveType>ArrayElements ルーチン
索引
ReleaseBooleanArrayElements()
191
ReleaseByteArrayElements()
192
ReleaseCharArrayElements()
193
ReleaseShortArrayElements()
194
ReleaseIntArrayElements()
195
ReleaseLongArrayElements()
196
ReleaseFloatArrayElements()
197
ReleaseDoubleArrayElements()
198
パラメータ:

env: JNI インタフェースポインタ

array: Java 配列オブジェクト

elems: 配列要素を参照するポインタ

mode: 解放モード

Get<PrimitiveType>ArrayRegion ルーチン

void Get<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, NativeType *buf);

プリミティブ配列の領域をバッファにコピーする機能のファミリです。

次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。

表 4-12a 配列アクセス用ルーチンの Get<PrimitiveType>ArrayRegion ファミリ
Get<PrimitiveType>ArrayRegion ルーチン
配列型
ネイティブ型
GetBooleanArrayRegion()
jbooleanArray
jboolean
GetByteArrayRegion()
jbyteArray
jbyte
GetCharArrayRegion()
jcharArray
jchar
GetShortArrayRegion()
jshortArray
jhort
GetIntArrayRegion()
jintArray
jint
GetLongArrayRegion()
jlongArray
jlong
GetFloatArrayRegion()
jfloatArray
jloat
GetDoubleArrayRegion()
jdoubleArray
jdouble

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-12b 配列アクセス用ルーチンの Get<PrimitiveType>ArrayRegion ファミリ
Get<PrimitiveType>ArrayRegion ルーチン
索引
GetBooleanArrayRegion()
199
GetByteArrayRegion()
200
GetCharArrayRegion()
201
GetShortArrayRegion()
202
GetIntArrayRegion()
203
GetLongArrayRegion()
204
GetFloatArrayRegion()
205
GetDoubleArrayRegion()
206
パラメータ:

env: JNI インタフェースポインタ

array: Java 配列

start: 開始添字

len: コピー対象の要素の数

buf: 転送先バッファ

例外:

ArrayIndexOutOfBoundsException: 領域内の添字の 1 つでも有効ではない場合

Set<PrimitiveType>ArrayRegion ルーチン

void Set<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, NativeType *buf);

バッファからのプリミティブ配列の領域をコピーバックする機能のファミリです。

次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス

表 4-13b 配列アクセス用ルーチンの Set<PrimitiveType>ArrayRegion ファミリ
Set<PrimitiveType>ArrayRegion ルーチン
索引
SetBooleanArrayRegion()
207
SetByteArrayRegion()
208
SetCharArrayRegion()
209
SetShortArrayRegion()
210
SetIntArrayRegion()
211
SetLongArrayRegion()
212
SetFloatArrayRegion()
213
SetDoubleArrayRegion()
214

パラメータ:

env: JNI インタフェースポインタ

array: Java 配列

start: 開始添字

len: コピー対象の要素の数

buf: 転送元バッファ

例外:

ArrayIndexOutOfBoundsException: 領域内の添字の 1 つでも有効ではない場合

注:

JDK/JRE 1.1 では、プログラマは Get/ReleaseArrayElements 関数を使用して、プリミティブ配列要素へのポインタを取得できました。VM がピニングをサポートしている場合、元のデータへのポインタが返されました。 サポートしていない場合には、コピーが作成されました。

JDK/JRE 1.3 に導入された新しい関数を使用すると、VM がピニングをサポートしていない場合でも、ネイティブコードは配列要素への直接ポインタを取得することができます。

GetPrimitiveArrayCritical
ReleasePrimitiveArrayCritical

void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);

上の 2 つの関数のセマンティクスは、既存の Get/ReleaseArrayElements 関数と非常によく似ています。可能な場合は、VM はプリミティブ配列へのポインタを返します。そうでない場合は、コピーが作成されます。た だし、これらの関数の使用方法に関して重要な制限があります。

GetPrimitiveArrayCritical を呼び出したあと、ReleasePrimitiveArrayCritical を呼び出す前に、ネイティブコードを特定の期間実行しないようにします。この 1 組の関数内部のコードは「クリティカルリージョン」で実行されているものとして扱う必要があります。クリティカルリージョン内部においてネイティブコード は、ほかの JNI 関数を呼び出してはならず、現在のスレッドにほかの Java スレッドをブロックして待機させることを可能にするどのシステムコールも呼び出してはなりません。たとえば、現在のスレッドは、ほかの Java スレッドが記述したストリーム上の read を呼び出してはなりません。

これらの制限は、VM がピニングをサポートしない場合でも、ネイティブコードが配列のコピーされていないバージョンを取得する可能性を高めます。たとえば、 ネイティブ コードが GetPrimitiveArrayCritical によって取得された配列へのポインタを保持している場合、VM は一時的にガベージコレクションを無効にすることがあります。

GetPrimtiveArrayCritical および ReleasePrimitiveArrayCritical の複数の組み合わせは、入れ子にすることができます。次に例を示します。 

  jint len = (*env)->GetArrayLength(env, arr1); 
  jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0);
  jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0);
  /* We need to check in case the VM tried to make a copy. */
  if (a1 == NULL || a2 == NULL) {
    ... /* out of memory exception thrown */
  }
  memcpy(a1, a2, len);
  (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0);
  (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);

VM が内部的に異なる形式で配列を表す場合、GetPrimitiveArrayCritical はまだ配列のコピーを作成する可能性があります。そのため、起こり得るメモリ不足の状況に対応して null に対する戻り値をチェックする必要があります。

リンケージ (GetPrimitiveArrayCritical):

JNIEnv インタフェース関数テーブルのリンケージインデックス 222

リンケージ (ReleasePrimitiveArrayCritical):

JNIEnv インタフェース関数テーブルのリンケージインデックス 223

導入されたバージョン:

JDK/JRE 1.2

ネイティブメ ソッドの登録

RegisterNatives

jint RegisterNatives(JNIEnv *env, jclass clazz,
const JNINativeMethod *methods, jint nMethods);

clazz 引数によって指定されたクラスでネイティブメソッドを登録します。methods パラメータは、そのネイティブメソッドの名前、シグニチャー、関数ポインタを含む JNINativeMethod 構造体の配列を指定します。JNINativeMethod 構造体の name フィールドと signature フィールドは、変更された UTF-8 文字列を参照するポインタです。nMethods パラメータは、配列内のネイティブメソッドの数を指定します。JNINativeMethod 構造体は次のように定義されます。 

typedef struct { 

char *name; 

char *signature; 

void *fnPtr; 

} JNINativeMethod;

関数ポインタは、形式上、次のシグニチャーを備えている必要があります。 

ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 215

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

methods: クラス内のネイティブメソッド

nMethods: そのクラス内のネイティブメソッドの数

戻り値:

成功の場合は「0」を、失敗の場合は負の値を返します。

例外:

NoSuchMethodError: 指定されたメソッドが見つからなかった場合、または、そのメソッドがネイティブではなかった場合

UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);

あるクラスのネイティブメソッドの登録を抹消します。そのクラスは、そのネイティブメソッド機能にリンクされる前また は再登録される前の状態に戻ります。

この関数は、通常のネイティブコードでは使用するべきではありません。その代わりに、特別なプログラムにネイティブラ イブラリを再ロードしたり再リンクしたりする方法を提供します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 216
パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

戻り値:

成功の場合は「0」を、失敗の場合は負の値を返します。

モニター操作

MonitorEnter

jint MonitorEnter(JNIEnv *env, jobject obj);

obj によって参照される基底の Java オブジェクトに関連するモニターに入ります。

Java オブジェクトは、それぞれ、関連するモニターを持っています。現在のスレッドがすでに obj に関連するモニターを持つ場合は、このスレッドがモニターに入った回数を表すモニター内のカウンタが増加されます。obj に関連するモニターがどのスレッドにも所有されていない場合は、現在のスレッドがそのモニターの所有者となり、このモニターのエントリカウントを 1 に設定します。別のスレッドがすでに obj に関連するモニターを所有している場合、現在のスレッドはモニターが解放されるのを待ち、再度、所有権を獲得しようとします。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 217
パラメータ:

env: JNI インタフェースポインタ

obj: 通常の Java オブジェクトまたはクラスオブジェクト

戻り値:

成功の場合は「0」を、失敗の場合は負の値を返します。

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

現在のスレッドは、obj によって参照された基底の Java オブジェクトに関連するモニターの所有者でなければなりません。このスレッドは、このモニターに入った回数を表すカウンタを減少させます。カウンタの値が ゼロになると、現在のスレッドはモニターを解放します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 218
パラメータ:

env: JNI インタフェースポインタ

obj: 通常の Java オブジェクトまたはクラスオブジェクト

戻り値:

成功の場合は「0」を、失敗の場合は負の値を返します。

NIO のサポート

NIO 関連のエントリポイントにより、ネイティブコードが java.nio「直接バッファ」にアクセスできます。 直接バッファのコンテンツは、通常のガベージコレクトされたヒープの外側の、ネイティブメモリ内に格納することができます。直接バッファについての詳細 は、「New I/O API」および java.nio.ByteBuffer クラスの仕様を参照してください。

JDK/JRE 1.4 で導入された 3 つの新しい関数によって、直接バッファを JNI コードで作成、検査、および操作することができます。

Java 仮想マシンの各実装ではこれらの関数をサポートする必要がありますが、すべての実装が直接バッファへの JNI のアクセスをサポートする必要はありません。JVM がこのようなアクセスをサポートしない場合は、NewDirectByteBuffer および GetDirectBufferAddress 関数は常に null を返し、GetDirectBufferCapacity 関数は常に -1 を返します。JVM がこのようなアクセスをサポートする場合、各関数は適切な値を返すように実装される必要があります。

NewDirectByteBuffer

jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);

メモリアドレス address から始まる capacity バイトまでのメモリブロックを参照して、直接バッファ java.nio.ByteBuffer を割り当てて返します。

この関数を呼び出して、Java レベルのコードに最終的なバイトバッファのオブジェクトを返すネイティブコードは、そのバッファが、読み込みと、適切な場合には書き出しのアクセスが可能 な、有効なメモリ領域を参照する必要があります。Java コードから無効なメモリ位置にアクセスしようとすると、視覚効果のない任意の値を返すか、指定されていない例外が発生します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 229


パラメータ:

env: JNIEnv のインタフェースポインタ

address: メモリ領域の開始アドレス (null は不可)

capacity: メモリ領域のバイト数で示したサイズ (正の数であること)


戻り値:

新規にインスタンス化された java.nio.ByteBuffer オブジェクトのローカル参照を返します。例外が発生したり、この仮想マシンが、直接バッファへの JNI のアクセスをサポートしていない場合は、null を返します。


例外:

OutOfMemoryError: ByteBuffer オブジェクトの割り当てに失敗した場合

導入されたバージョン:

JDK/JRE 1.4

GetDirectBufferAddress

void* GetDirectBufferAddress(JNIEnv* env, jobject buf);

指定された直接バッファ java.nio.Buffer に参照されるメモリ領域の開始アドレスをフェッチし、返します。

この関数によって、ネイティブコードは、Java コードがバッファオブジェクトを介してアクセスできるメモリ領域と同じメモリ領域にアクセスできるようになります。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 230


パラメータ:

env: JNIEnv のインタフェースポインタ

buf: 直接バッファ java.nio.Buffer オブジェクト (null は不可)


戻り値:

バッファに参照されるメモリ領域の開始アドレスを返します。メモリ領域が未定義の場合、指定されたオブジェクトが直接バッファの java.nio.Buffer オブジェクトでない場合、または、直接バッファへの JNI のアクセスがこの仮想マシンでサポートされていない場合は、null を返します。

導入されたバージョン:

JDK/JRE 1.4

GetDirectBufferCapacity

jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);

指定された直接バッファ java.nio.Buffer に参照されるメモリ領域のバイト数で示したサイズをフェッチし、返します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 231


パラメータ:

env: JNIEnv のインタフェースポインタ

buf: 直接バッファ java.nio.Buffer オブジェクト (null は不可)


戻り値:

バッファに関連付けられたメモリ領域のサイズをバイト数で返します。指定されたオブジェクトが直接バッファの java.nio.Buffer オブジェクトでない場合、または、直接バッファへの JNI のアクセスがこの仮想マシンでサポートされていない場合は、-1 を返します。

導入されたバージョン:

JDK/JRE 1.4

リフレクショ ンのサポート

プログラマは、メソッドまたはフィールドの名前および型を把握している場合、JNI を使用して Java メソッドの呼び出しまたは Java フィールドへのアクセスを行うことができます。Java Core Reflection API を使用すると、プログラマは実行時に Java クラスの内部を調査することができます。JNI は、JNI で使用されるフィールドとメソッド ID および Java Core Reflection API で使用されるメソッドオブジェクトの間の変換関数のセットを提供します。

FromReflectedMethod

jmethodID FromReflectedMethod(JNIEnv *env, jobject method);

java.lang.reflect.Method または java.lang.reflect.Constructor オブジェクトをメソッド ID に変換します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 7

導入されたバージョン:

JDK/JRE 1.2

FromReflectedField

jfieldID FromReflectedField(JNIEnv *env, jobject field);

java.lang.reflect.Field をフィールド ID に変換します。

リンケージ:
JNIEnv インタフェース関数テーブルのインデックス 8
導入されたバージョン:

JDK/JRE 1.2

ToReflectedMethod

jobject ToReflectedMethod(JNIEnv *env, jclass cls,
   jmethodID methodID);

cls から取得したメソッド ID を java.lang.reflect.Method または java.lang.reflect.Constructor オブジェクトに変換します。

変換に失敗した場合には、OutOfMemoryError をスローし、0 を返します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 9

導入されたバージョン:

JDK/JRE 1.2

ToReflectedField

jobject ToReflectedField(JNIEnv *env, jclass cls,
   jfieldID fieldID);

cls から取得したフィールド ID を java.lang.reflect.Field オブジェクトに変換します。

変換に失敗した場合には、OutOfMemoryError をスローし、0 を返します。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 12

導入されたバージョン:

JDK/JRE 1.2

Java VM インタフェース

GetJavaVM

jint GetJavaVM(JNIEnv *env, JavaVM **vm);

現在のスレッドに関連する Java VM インタフェース (呼び出し API で使用) を返します。その結果は、2 番目の引数 vm で示された位置に置かれます。

リンケージ:

JNIEnv インタフェース関数テーブルのインデックス 219

パラメータ:

env: JNI インタフェースポインタ

vm: 結果を返すポインタ

戻り値:

成功の場合は「0」を、失敗の場合は負の値を返します。

 

目次 | 前の項目 | 次の項目

 

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.