| 目次 | 前の項目 | 次の項目 | Java Native Interface 仕様 |
この章は、JNI 関数のリファレンスです。この章では、JNI の関数をすべて取り上げます。また、JNI 関数テーブルの配置そのままに記載されています。
「～しなければならない」(または「～する必要がある」) という表現は、JNI プログラマに対する制約を表しています。たとえば、ある JNI 関数について、それが null 以外のオブジェクトを受け取ら「なければならない」と説明されている場合、プログラマの責任において、その JNI 関数に null を渡さないようにしなければならないという意味です。それによって、JNI 実装の際に、その JNI 関数における null のポインタチェックを行う必要がなくなります。
この章の一部は Netscape の JRI ドキュメントを改作したものです。
参照資料では、関数を用途によってグループ化しています。参照セクションは、次の機能分野から構成されています。
各関数は、「JNIEnv」引数を介して、固定オフセットからアクセスできます。「JNIEnv」型は、すべての JNI 関数のポインタを格納する構造体を指すポインタです。これは次のように定義されます。
VM は、コード例 4-1 に示されているように、関数テーブルを初期化します。最初の 3 エントリは、将来の COM との互換性のために予約されていることに注意してください。さらに、関数テーブルの始めの近辺にいくつかの追加の null エントリを予約してあります。したがって、たとえば、これから現われる、クラス関連の JNI 演算は、表の終わりではなく FindClass のあとに追加することができます。
関数テーブルは、すべての JNI インタフェースポインタの間で共用されます。
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,
GetObjectRefType
};
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 を返します。
JDK/JRE 1.6 では、GetVersion() は 0x00010006 を返します。
#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
#define JNI_VERSION_1_4 0x00010004
#define JNI_VERSION_1_6 0x00010006
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: バッファー長
Java クラスオブジェクトを返します。エラーが発生した場合は NULL を返します。
ClassFormatError: クラスデータが有効なクラスを指定しなかった場合
ClassCircularityError: クラスまたはインタフェースが、それ自体のスーパークラスまたはスーパーインタフェースになる場合
OutOfMemoryError: システムがメモリ不足の場合
jclass FindClass(JNIEnv *env, const char *name);
JDK リリース 1.1 では、この関数はローカルに定義されたクラスをロードします。また、指定された名前を持つクラスに対して CLASSPATH 環境変数が指定するディレクトリおよび ZIP ファイルを検索します。
Java 2 SDK リリース 1.2 以降、Java セキュリティーモデルにより、システムクラス以外のクラスでもネイティブメソッドのロードと呼び出しが可能になりました。FindClass は、現在のネイティブメソッドに関連付けられたクラスローダー、つまりネイティブメソッドを宣言したクラスのクラスローダーを検出します。ネイティブメソッドがシステムクラスに属する場合、クラスローダーは検出されません。それ以外の場合には、適切なクラスローダが呼び出され、名前が付けられたクラスのロードおよびリンクを行います。
Java 2 SDK リリース 1.2 以降、FindClass が呼び出しインタフェースによって呼び出された場合、現在のネイティブメソッドまたはそれに関連付けられたクラスローダーは存在しません。この場合、ClassLoader.getSystemClassLoader の結果が使用されます。これは、仮想マシンがアプリケーション用に作成するクラスローダです。java.class.path プロパティーにリストされたクラスを検索できます。
name 引数は、完全修飾クラス名または配列型シグニチャーです。たとえば、java.lang.String クラスの完全修飾クラス名は次のとおりです。
"java/lang/String"
配列クラス java.lang.Object[] の配列型シグニチャーは次のとおりです。
"[Ljava/lang/Object;"
JNIEnv インタフェース関数テーブルのインデックス 6。
env:JNI インタフェースポインタ
name: 完全修飾クラス名 (「/」で区切ったあとにクラス名を付けたパッケージ名)。その名前が「[」(配列シグニチャー文字) で始まっている場合は、配列クラスを返します。文字列は変更後の UTF-8 でエンコードされます。
完全修飾名からクラスオブジェクトを返します。クラスが見つからない場合は、NULL を返します。
ClassFormatError: クラスデータが有効なクラスを指定しなかった場合
ClassCircularityError: クラスまたはインタフェースが、それ自体のスーパークラスまたはスーパーインタフェースになる場合
NoClassDefFoundError: 要求されたクラスまたはインタフェースに対する定義が見つからなかった場合
OutOfMemoryError: システムがメモリ不足の場合
jclass GetSuperclass(JNIEnv *env, jclass clazz);
clazz が Object クラス以外のクラスを表す場合、この関数は、clazz によって指定されたクラスのスーパークラスを表すオブジェクトを返します。
clazz が Object クラスを指定する場合、または clazz がインタフェースを表す場合は、この関数は NULL を返します。
JNIEnv インタフェース関数テーブルのインデックス 10.
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
clazz によって表されるクラスのスーパークラス、または NULL を返します。
jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1,
jclass clazz2);
clazz1 のオブジェクトが安全に clazz2 へキャストされるかどうかを決定します。
JNIEnv インタフェース関数テーブルのインデックス 11。
env:JNI インタフェースポインタ
clazz1: 最初のクラス引数
clazz2:2 番目のクラス引数
次のいずれかが真の場合に JNI_TRUE を返します。
jint Throw(JNIEnv *env, jthrowable obj);
java.lang.Throwable オブジェクトがスローされます。
JNIEnv インタフェース関数テーブルのインデックス 13。
env:JNI インタフェースポインタ
obj:java.lang.Throwable オブジェクト
成功すると「0」を返し、失敗すると負の値を返します。
java.lang.Throwable object obj.
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 オブジェクト。
jthrowable ExceptionOccurred(JNIEnv *env);
例外がスローされるかどうかを決定します。例外は、ネイティブコードが ExceptionClear() を呼び出すか、または Java コードがその例外を処理するまでスローされた状態を続けます。
JNIEnv インタフェース関数テーブルのインデックス 15。
env:JNI インタフェースポインタ
現在スローされている例外オブジェクトを返します。現在スローされている例外がない場合は、NULL を返します。
void ExceptionDescribe(JNIEnv *env);
stderr など、例外およびスタックのバックトレースをシステムエラー報告チャネルに出力します。これは、デバッグのために提供されている便利なルーチンです。
JNIEnv インタフェース関数テーブルのインデックス 16。
env:JNI インタフェースポインタ
void ExceptionClear(JNIEnv *env);
現在スローされている例外があればそれをクリアします。現在スローされている例外がない場合は、このルーチンは影響を及ぼしません。
JNIEnv インタフェース関数テーブルのインデックス 17。
env:JNI インタフェースポインタ
void FatalError(JNIEnv *env, const char *msg);
致命的エラーを発生させます。VM の回復は期待できません。この関数は値を返しません。
JNIEnv インタフェース関数テーブルのインデックス 18。
env:JNI インタフェースポインタ
msg: エラーメッセージ文字列は変更後の UTF-8 でエンコードされます。
jboolean ExceptionCheck(JNIEnv *env);
未処理の例外がある場合は
JNI_TRUEを、ない場合はJNI_FALSEを返します。
JDK/JRE 1.2
jobject NewGlobalRef(JNIEnv *env, jobject obj);
obj 引数によって参照されたオブジェクトの新しいグローバル参照を作成します。obj 引数は、グローバル参照またはローカル参照のどちらでも構いません。グローバル参照は、DeleteGlobalRef() を呼び出すことによって、必ず明示的に処理しておく必要があります。
JNIEnv インタフェース関数テーブルのインデックス 21。
env:JNI インタフェースポインタ
obj: グローバル参照またはローカル参照
グローバル参照を返します。システムがメモリ不足の場合は NULL を返します。
void DeleteGlobalRef(JNIEnv *env, jobject globalRef);
globalRef によって示されたグローバル参照を削除します。
JNIEnv インタフェース関数テーブルのインデックス 22。
env:JNI インタフェースポインタ
globalRef: グローバル参照
ローカル参照は、ネイティブメソッドの呼び出し期間中有効です。ローカル参照は、ネイティブメソッドが復帰すると自動的に解放されます。各ローカル参照は、Java 仮想マシンのリソースをいくらか消費します。プログラマは、ネイティブメソッドがローカル参照を過剰に割り当てないように確認する必要があります。ローカル参照は、ネイティブメソッドが Java に復帰すると自動的に解放されますが、ローカル参照を過剰に割り当てると、ネイティブメソッドの実行中に VM がメモリを使い果たしてしまう可能性があります。
void DeleteLocalRef(JNIEnv *env, jobject localRef);
localRef によって示されたローカル参照を削除します。
JNIEnv インタフェース関数テーブルのインデックス 23。
env:JNI インタフェースポインタ
localRef: ローカル参照
注:JDK/JRE 1.1 では、上記の JDK/JRE 1.2 では、ローカル参照の有効期間を管理するための関数セットが追加されました。その関数は次の4つです。 |
jint EnsureLocalCapacity(JNIEnv *env, jint capacity);
現在のスレッドで最低限指定された数のローカル参照を作成できることを保証します。関数が正常に実行された場合には、0 が返されます。それ以外の場合には、負の数が返され OutOfMemoryError がスローされます。
ネイティブメソッドに入る前に、VM は自動的に最低 16 のローカル参照の作成を保証します。
下位互換性のために VM は、保証された容量以上にローカル参照を割り当てます。(デバッグのサポートとして、VM がユーザーに対し、ローカル参照の作成数が多すぎるという内容の警告を発する場合があります。JDK では、プログラマは -verbose:jni コマンド行オプションを使用して、これらのメッセージを有効にすることができます)。保証された容量を超えてしまい、これ以上ローカル参照を作成できない場合、VM は、FatalError を呼び出します。
JDK/JRE 1.2
jint PushLocalFrame(JNIEnv *env, jint capacity);
新しいローカル参照フレームを作成します。このフレームに最低限指定された数のローカル参照を作成できます。正常に実行された場合には、0 が返されます。失敗した場合には、負の数が返され、OutOfMemoryError がスローされます。
前回のローカルフレームで作成済みのローカル参照は、現在のローカルフレームでも依然として有効です。
JDK/JRE 1.2
jobject PopLocalFrame(JNIEnv *env, jobject result);
現在のローカル参照フレームを無効にし、すべてのローカル参照を解放します。そして指定された result オブジェクトに対する前回のローカル参照フレームのローカル参照を返します。
前回のフレームに参照を返す必要のない場合には、result として null を渡します。
JDK/JRE 1.2
jobject NewLocalRef(JNIEnv *env, jobject ref);
ref と同じオブジェクトを参照する新しいローカル参照を作成します。渡された ref は、グローバル参照またはローカル参照である可能性があります。ref が null を参照している場合には、null が返されます。
JDK/JRE 1.2
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 オブジェクトでも参照されているオブジェクトを保持するために弱グローバル参照を使用することが可能な場合があります。弱グローバル参照をこのような未定義の方法で使用するのは避けるべきです。
jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);
弱グローバル参照を新規作成します。obj が null を参照している場合、または VM がメモリを使い果たしてしまった場合は、null が返されます。VM がメモリを使い果たしてしまった場合、OutOfMemoryError がスローされます。
JDK/JRE 1.2
void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);
渡された弱グローバル参照に必要な VM リソースを削除します。
jobject AllocObject(JNIEnv *env, jclass clazz);
オブジェクト用としてコンストラクタを呼び出さずに、新しい Java オブジェクトを割り当てます。オブジェクトに対する参照を返します。
clazz 引数は配列クラスを参照できません。
JNIEnv インタフェース関数テーブルのインデックス 27。
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
Java オブジェクトを返します。Java オブジェクトが構築できなかった場合は、NULL を返します。
InstantiationException: クラスがインタフェースまたは abstract クラスの場合
OutOfMemoryError: システムがメモリ不足の場合
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 引数は配列クラスを参照できません。
プログラマは、コンストラクタに渡す引数をすべて、methodID 引数の直後に置きます。NewObject() は、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
JNIEnv インタフェース関数テーブルのインデックス 28。
プログラマは、コンストラクタに渡す引数をすべて、methodID 引数の直後の jvalues の args 配列内に置きます。NewObjectA() はこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
JNIEnv インタフェース関数テーブルのインデックス 30。
プログラマは、コンストラクタに渡す引数をすべて、methodID 引数の直後の va_list 型の args 引数内に置きます。NewObjectV() はこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
JNIEnv インタフェース関数テーブルのインデックス 29。
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
methodID: コンストラクタのメソッド ID
コンストラクタの引数。
args: コンストラクタの引数の配列
args: コンストラクタの引数の va_list
Java オブジェクトを返します。Java オブジェクトが構築できなかった場合は、NULL を返します。
InstantiationException: クラスがインタフェースまたは abstract クラスの場合
OutOfMemoryError: システムがメモリ不足の場合
コンストラクタによってスローされるすべての例外。
jclass GetObjectClass(JNIEnv *env, jobject obj);
オブジェクトのクラスを返します。
JNIEnv インタフェース関数テーブルのインデックス 31。
env:JNI インタフェースポインタ
obj:Java オブジェクト (null であってはならない)
Java クラスオブジェクトを返します。
jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);
obj 引数によって参照されるオブジェクトの型を返します。引数 obj は、ローカル参照、グローバル参照、弱グローバル参照のいずれかです。
JNIEnv インタフェース関数テーブルのインデックス 232。
env:JNI インタフェースポインタ
obj: ローカル参照、グローバル参照、または弱グローバル参照。
vm: インタフェース取得元の仮想マシンインスタンス。
env: 現在のスレッドの JNI インタフェースポインタの配置位置を参照するポインタ。
version: 要求された JNI バージョン。
関数 GetObjectRefType は、 jobjectRefType として定義された次の列挙値の 1 つを返します。
JNIInvalidRefType = 0,
JNILocalRefType = 1,
JNIGlobalRefType = 2,
JNIWeakGlobalRefType = 3
引数 obj が弱グローバル参照型の場合、戻り値は JNIWeakGlobalRefType になります。
引数 obj がグローバル参照型の場合、戻り値は JNIGlobalRefType になります。
引数 obj がローカル参照型の場合、戻り値は JNILocalRefType になります。
引数 obj が有効な参照でない場合、この関数の戻り値は JNIInvalidRefType になります。
無効な参照とは、有効なハンドルでない参照です。つまり、obj ポインタアドレスは、いずれかの Ref 作成関数から割り当てられたメモリー内の位置や JNI 関数から返されたメモリー内の位置を指示していない参照です。
したがって、NULL は無効な参照となり、GetObjectRefType(env,NULL) は JNIInvalidRefType を返します。
他方、null を指示する参照である null 参照は、その null 参照が最初に作成されたときの参照の型を返します。
GetObjectRefType は、削除された参照では使用できません。
参照は通常、VM で参照割り当てサービスによる再使用の可能性があるメモリーデータ構造のポインタとして実装されます。したがって、参照を削除すると GetObjectRefType の戻り値が指定できません。
JDK/JRE 1.6
jboolean IsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);
オブジェクトがクラスのインスタンスであるかどうかをチェックします。
JNIEnv インタフェース関数テーブルのインデックス 32。
env:JNI インタフェースポインタ
obj:Java オブジェクト
clazz:Java クラスオブジェクト
obj を clazz にキャストできる場合は、JNI_TRUE を返します。そうでない場合は、JNI_FALSE を返します。null オブジェクトは、どのクラスにもキャストすることができます。
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 を返します。
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: システムがメモリ不足の場合
NativeType Get<type>Field(JNIEnv *env, jobject obj,
jfieldID fieldID);
このアクセス用ルーチンのファミリは、オブジェクトのインスタンス (非 static) フィールドの値を返します。アクセスすべきフィールドは、 GetFieldID() を呼び出すことによって得られるフィールド ID を使用して指定します。
次の表には、Get<type>Field ルーチン名と結果の型が示されています。Get<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際のルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。
env:JNI インタフェースポインタ
obj:Java オブジェクト (null であってはならない)
fieldID: 有効フィールド ID
フィールドの内容を返します。
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 をそのルーチンに対応するネイティブ型と置き換える必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
obj:Java オブジェクト (null であってはならない)
fieldID: 有効フィールド ID
value: そのフィールドの新しい値
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: システムがメモリ不足の場合
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 つからではなく、実クラス自体から取得する必要があります。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後に置きます。Call<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の jvalues の args 配列内に置きます。Call<type>MethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の va_list 型の args 引数に入れます。Call<type>MethodV ルーチンは、引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
次の表には、メソッド呼び出しルーチンの各々がその結果の型に応じて示されています。Call<type>Method 内の type を、呼び出しているメソッドの Java 型と置き換え (または、表の実際のメソッド呼び出しルーチン名の 1 つを使用する)、かつ NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。
JNIEnv インタフェース関数テーブルのインデックス:
env:JNI インタフェースポインタ
obj:Java オブジェクト
methodID: メソッド ID
Java メソッドに対する引数
args: 引数の配列
args: 引数の va_list
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 つから取得しなければなりません。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後に置きます。CallNonvirtual<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の jvalues の args 配列内に置きます。CallNonvirtual<type>MethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の va_list 型の args 引数に入れます。CallNonvirtualMethodV ルーチンはこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
次の表には、メソッド呼び出しルーチンの各々がその結果の型に応じて示されています。CallNonvirtual<type>Method 内の type をメソッドの Java 型と置き換えるか、あるいは表の実際のメソッド呼び出しルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
clazz: Java クラス。
obj:Java オブジェクト
methodID: メソッド ID
Java メソッドに対する引数
args: 引数の配列
args: 引数の va_list
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: システムがメモリ不足の場合
NativeType GetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID);
このアクセス用ルーチンのファミリは、オブジェクトの static フィールドの値を返します。アクセスするフィールドは、フィールド ID で指定します。 フィールド ID は、GetStaticFieldID() を呼び出すことによって取得することができます。
次の表には、get ルーチン名のファミリと結果の型が示されています。GetStatic<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際の static フィールドアクセス用ルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
fieldID:static フィールド ID
static フィールドの内容を返します。
void SetStatic<type>Field(JNIEnv *env, jclass clazz, NativeType
jfieldID fieldID, value);
このアクセス用ルーチンのファミリは、オブジェクトの static フィールドの値を設定します。アクセスするフィールドは、フィールド ID で指定します。 フィールド ID は、GetStaticFieldID() を呼び出すことによって取得することができます。
次の表には、セットルーチン名と値の型が示されています。SetStatic<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際のセット static フィールドルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
fieldID:static フィールド ID
value: そのフィールドの新しい値
jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
クラスの static メソッドを表すメソッド ID を返します。このメソッドは、その名前とシグニチャーで指定します。
GetStaticMethodID() によって、まだ初期化されていないクラスが初期化されます。
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
name:0 で終了する変更後の UTF-8 文字列内の static メソッド名。
sig:0 で終了する変更後の UTF-8 文字列内のメソッドシグニチャー。
メソッド ID を返します。演算が失敗した場合は NULL を返します。
NoSuchMethodError: 指定された static メソッドが見つからない場合
ExceptionInInitializerError: 例外のため、クラス初期化が失敗した場合
OutOfMemoryError: システムがメモリ不足の場合
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 そのものから取得する必要があります。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後に置きます。CallStatic<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の jvalues の args 配列内に置きます。CallStaticMethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の va_list 型の args 引数に入れます。CallStaticMethodV はこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。
次の表には、メソッド呼び出しルーチンが各々その結果の型によって示されています。CallStatic<type>Method 内の type をメソッドの Java 型または表の実際のメソッド呼び出しルーチン名の 1 つと置き換えるか、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
methodID:static メソッド ID
static メソッドの引数。
args: 引数の配列
args: 引数の va_list
static Java メソッドを呼び出した結果を返します。
jstring NewString(JNIEnv *env, const jchar *unicodeChars,
jsize len);
Unicode 文字配列から新しい java.lang.String オブジェクトを構築します。
env:JNI インタフェースポインタ
unicodeChars:Unicode 文字列を参照するポインタ
len:Unicode 文字列の長さ
Java 文字列オブジェクトを返します。文字列が構築できない場合は NULL を返します。
OutOfMemoryError: システムがメモリ不足の場合
jsize GetStringLength(JNIEnv *env, jstring string);
Java 文字列の長さ (Unicode 文字のカウント) を返します。
env:JNI インタフェースポインタ
string:Java 文字列オブジェクト
Java 文字列の長さを返します。
const jchar * GetStringChars(JNIEnv *env, jstring string,
jboolean *isCopy);
文字列の Unicode 文字の配列を参照するポインタを返します。このポインタは、ReleaseStringchars() が呼び出されるまで有効です。
isCopy が NULL でない場合にコピーが作成されると、*isCopy は JNI_TRUE に設定されます。コピーが作成されない場合は、JNI_FALSE に設定されます。
env:JNI インタフェースポインタ
string:Java 文字列オブジェクト
isCopy: ブール値に対するポインタ
Unicode 文字列を参照するポインタを返します。演算が失敗した場合は NULL を返します。
void ReleaseStringChars(JNIEnv *env, jstring string,
const jchar *chars);
ネイティブコードが chars にアクセスする必要がなくなったことを VM に知らせます。chars 引数は、GetStringChars() を使用してstring から取得することができるポインタです。
env:JNI インタフェースポインタ
string:Java 文字列オブジェクト
chars:Unicode 文字列を参照するポインタ
jstring NewStringUTF(JNIEnv *env, const char *bytes);
変更後の UTF-8 エンコーディングによる文字配列から新しい java.lang.String オブジェクトを構築します。
env:JNI インタフェースポインタ
bytes: 変更後の UTF-8 文字列を参照するポインタ。
Java 文字列オブジェクトを返します。文字列が構築できない場合は NULL を返します。
OutOfMemoryError: システムがメモリ不足の場合
jsize GetStringUTFLength(JNIEnv *env, jstring string);
文字列の長さを変更後の UTF-8 によるバイト数で返します。
env:JNI インタフェースポインタ
string:Java 文字列オブジェクト
文字列の UTF-8 長を返します。
const char * GetStringUTFChars(JNIEnv *env, jstring string,
jboolean *isCopy);
変更後の UTF-8 エンコーディングによる文字列を表すバイト配列を参照するポインタを返します。この配列は、ReleaseStringUTFChars() によって解放されるまで有効です。
isCopy が NULL でない場合にコピーが作成されると、*isCopy は JNI_TRUE に設定されます。コピーが作成されない場合は、JNI_FALSE に設定されます。
env:JNI インタフェースポインタ
string:Java 文字列オブジェクト
isCopy: ブール値に対するポインタ
変更後の UTF-8 文字列を参照するポインタを返します。演算に失敗した場合は、NULL を返します。
void ReleaseStringUTFChars(JNIEnv *env, jstring string,
const char *utf);
ネイティブコードが utf にアクセスする必要がなくなったことを VM に知らせます。utf 引数は、GetStringUTFChars() を使用して string から取得するポインタです。
env:JNI インタフェースポインタ
string:Java 文字列オブジェクト
utf: 変更後の UTF-8 文字列を参照するポインタ。
注:JDK/JRE 1.1 では、プログラマはユーザーが提供するバッファーのプリミティブ配列要素を取得できました。JDK/JRE 1.2 では、ネイティブコードを使用して、ユーザーが提供するバッファーから Unicode (UTF-16) または変更後の UTF-8 エンコーディングによる文字を取得できる関数セットを追加されました。このあとの例を参照してください。 |
void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf);
オフセット start で始まる len 個の Unicode 文字を、与えられたバッファー buf にコピーします。
StringIndexOutOfBoundsException をインデックスオーバーフロー時にスローします。
JDK/JRE 1.2
< Void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);
オフセット start で始まる len 個の Unicode 文字を変更後の UTF-8 エンコーディングに変換し、その結果を、指定されたバッファー buf に置きます。
StringIndexOutOfBoundsException をインデックスオーバーフロー時にスローします。
JDK/JRE 1.2
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 の制限と類似しています。
JDK/JRE 1.2
jsize GetArrayLength(JNIEnv *env, jarray array);
配列内の要素の数を返します。
env:JNI インタフェースポインタ
array:Java 配列オブジェクト
配列の長さを返します。
jobjectArray NewObjectArray(JNIEnv *env, jsize length,
jclass elementClass, jobject initialElement);
クラス elementClass にオブジェクトを持つ新しい配列を構築します。要素はすべて、最初に initialElement に設定されます。
env:JNI インタフェースポインタ
length: 配列サイズ
elementClass: 配列要素クラス
initialElement: 初期化値
Java 配列オブジェクトを返します。配列が構築できなかった場合は null を返します。
OutOfMemoryError: システムがメモリ不足の場合
jobject GetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index);
Object 配列の要素を返します。
env:JNI インタフェースポインタ
array:Java 配列
index: 配列添字
Java オブジェクトを返します。
ArrayIndexOutOfBoundsException:index が配列内に有効な添字の値を指定しなかった場合
void SetObjectArrayElement(JNIEnv *env, jobjectArray array,
jsize index, jobject value);
Object 配列の要素を設定します。
env:JNI インタフェースポインタ
array:Java 配列
index: 配列添字
value: 新しい値
ArrayIndexOutOfBoundsException:index が配列内に有効な添字の値を指定しなかった場合
ArrayStoreException:value のクラスが、配列の要素クラスのサブクラスではない場合
ArrayType New<PrimitiveType>Array(JNIEnv *env, jsize length);
新しいプリミティブ配列オブジェクトを構築するために使用される演算のファミリ。表 4-8 には、特定のプリミティブ配列コンストラクタが示されています。New<PrimitiveType>Array を、次の表の実際のプリミティブ配列コンストラクタルーチン名の 1 つと置き換え、ArrayType をそのルーチンに対応する配列型と置き換える必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
length: 配列長
Java 配列を返します。配列が構築できなかった場合は null を返します。
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 つの要素を表しています (アンパック表示)。その他の型の配列はすべて、メモリ内で必ず隣接するようになっています。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
array:Java 文字列オブジェクト
isCopy: ブール値に対するポインタ
配列要素を参照するポインタを返します。演算が失敗した場合は、NULL を返します。
void Release<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, NativeType *elems, jint mode);
ネイティブコードが elems にアクセスする必要がないことを VM に知らせる関数のファミリです。elems 引数は、対応する Get<PrimitiveType>ArrayElements() 関数を使用して、array から取得されるポインタです。必要に応じて、この関数は、 elems に施された変更をすべて元の配列にコピーし直します。
mode 引数は、配列バッファーの解放方法に関する情報を提供します。elems が array 内の要素のコピーでない場合、mode は影響を及ぼしません。mode が array 内の要素のコピーである場合は、次の表に示されているような影響を及ぼします。
|
mode
|
動作
|
|---|---|
0
|
内容を元の値に戻し、
elems バッファーを解放する
|
JNI_COMMIT
|
内容を元の値に戻すが、
elems バッファーを解放しない
|
JNI_ABORT
|
変更の可能性があってもその内容を元に戻さず、バッファーを解放する
|
多くの場合、プログラマは、ピン配列とコピー配列の両方に対して一貫した動作を保証するために、「0｣ を mode 引数に渡します。0 以外を渡す場合は、プログラマはメモリを十分に注意して管理する必要があります。
次の表には、プリミティブ配列処置機能のファミリを構成する特定のルーチンが示されています。次の置換を行う必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
array:Java 配列オブジェクト
elems: 配列要素を参照するポインタ
mode: 解放モード
void Get<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,NativeType
jsize start, jsize len, *buf);
プリミティブ配列の領域をバッファーにコピーする関数のファミリです。
次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
env:JNI インタフェースポインタ
array:Java 配列
start: 開始添字
len: コピー対象の要素の数
buf: 転送先バッファー
ArrayIndexOutOfBoundsException: 領域内の添字の 1 つでも有効ではない場合
void Set<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array, NativeType
jsize start, jsize len, *buf);
バッファーからのプリミティブ配列の領域を元の値に戻す関数のファミリです。
次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。
JNIEnv インタフェース関数テーブルのインデックス。
パラメータ:
env:JNI インタフェースポインタ
array:Java 配列
start: 開始添字
len: コピー対象の要素の数
buf: 転送元バッファー
ArrayIndexOutOfBoundsException: 領域内の添字の 1 つでも有効ではない場合
注:JDK/JRE 1.1 では、プログラマは JDK/JRE 1.3 の時点で導入された新しい関数を使用すると、VM がピニングをサポートしていない場合でも、ネイティブコードは配列要素への直接ポインタを取得することができます。 |
void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);
この 2 つの関数のセマンティクスは、既存の Get/Release
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 に対する戻り値をチェックする必要があります。
JNIEnv インタフェース関数テーブルのリンケージインデックス 222。
JNIEnv インタフェース関数テーブルのリンケージインデックス 223。
JDK/JRE 1.2
jint RegisterNatives(JNIEnv *env, jclass clazz,
const JNINativeMethod *methods, jint nMethods);
clazz 引数によって指定されたクラスにネイティブメソッドを登録します。methods パラメータは、そのネイティブメソッドの名前、シグニチャー、関数ポインタを含む JNINativeMethod 構造体の配列を指定します。JNINativeMethod 構造体の name および signature フィールドは、変更後の UTF-8 文字列を参照するポインタです。nMethods パラメータは、配列内のネイティブメソッドの数を指定します。JNINativeMethod 構造体は次のように定義されます。
関数ポインタは、形式上、次のシグニチャーを備えている必要があります。
JNIEnv インタフェース関数テーブルのインデックス 215。
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
methods: クラス内のネイティブメソッド
nMethods: そのクラス内のネイティブメソッドの数
成功の場合は「0」を、失敗の場合は負の値を返します。
NoSuchMethodError: 指定されたメソッドが見つからなかった場合、または、そのメソッドがネイティブではなかった場合
jint UnregisterNatives(JNIEnv *env, jclass clazz);
あるクラスのネイティブメソッドの登録を解除します。そのクラスは、そのネイティブメソッド機能にリンクされる前または再登録される前の状態に戻ります。
この関数は、通常のネイティブコードでは使用するべきではありません。その代わりに、特別なプログラムにネイティブライブラリを再ロードしたり再リンクしたりする方法を提供します。
env:JNI インタフェースポインタ
clazz:Java クラスオブジェクト
成功の場合は「0」を、失敗の場合は負の値を返します。
jint MonitorEnter(JNIEnv *env, jobject obj);
obj によって参照される基底の Java オブジェクトに関連するモニターに入ります。
obj 参照は null にはできません。
Java オブジェクトはそれぞれ、関連するモニターを持っています。現在のスレッドがすでに obj に関連するモニターを持つ場合は、このスレッドがモニターに入った回数を表すモニター内のカウンタが増加されます。obj に関連するモニターがどのスレッドにも所有されていない場合は、現在のスレッドがそのモニターの所有者となり、このモニターのエントリカウントを 1 に設定します。別のスレッドがすでに obj に関連するモニターを所有している場合、現在のスレッドはモニターが解放されるのを待ち、再度、所有権を獲得しようとします。
MonitorEnter JNI 関数呼び出しで入ったモニターから出る場合、monitorexit Java 仮想マシンの命令または synchronized メソッドの戻り値は使用できません。MonitorEnter JNI 関数呼び出しと monitorenter Java 仮想マシンの命令は、同じオブジェクトと関連するモニターに入ろうと競合する場合があります。
デッドロックを避けるため、MonitorEnter JNI 機能呼び出しで入ったモニターから出る場合は、DetachCurrentThread 呼び出しを使用して JNI モニターを暗黙的に解放しないかぎり、必ず MonitorExit JNI 呼び出しを使用します。
env:JNI インタフェースポインタ
obj: 通常の Java オブジェクトまたはクラスオブジェクト
成功の場合は「0」を、失敗の場合は負の値を返します。
jint MonitorExit(JNIEnv *env, jobject obj);
現在のスレッドは、obj によって参照された基底の Java オブジェクトに関連するモニターの所有者でなければなりません。このスレッドは、このモニターに入った回数を表すカウンタを減少させます。カウンタの値がゼロになると、現在のスレッドはモニターを解放します。
ネイティブコードは、MonitorExit を使用して、synchronized メソッドまたは monitorenter Java仮想マシンの命令で入ったモニターから出てはいけません。
env:JNI インタフェースポインタ
obj: 通常の Java オブジェクトまたはクラスオブジェクト
成功の場合は「0」を、失敗の場合は負の値を返します。
IllegalMonitorStateException: 現在のスレッドがモニターの所有者でない場合。
NIO 関連のエントリポイントにより、ネイティブコードが java.nio「直接バッファー」にアクセスできます。直接バッファーのコンテンツは、通常のガベージコレクトされたヒープの外側の、ネイティブメモリ内に格納することができます。直接バッファーについての詳細は、「New I/O API」および java.nio.ByteBuffer クラスの仕様を参照してください。
Java 仮想マシンの各実装ではこれらの関数をサポートする必要がありますが、すべての実装が直接バッファーへの JNI のアクセスをサポートする必要はありません。JVM がこのようなアクセスをサポートしない場合は、NewDirectByteBuffer および GetDirectBufferAddress 関数は常に null を返し、GetDirectBufferCapacity 関数は常に -1 を返します。JVM がこのようなアクセスをサポートする場合、各関数は適切な値を返すように実装される必要があります。
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
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
jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);
指定された直接バッファー java.nio.Buffer に参照されるメモリ領域のバイト数で示したサイズをフェッチし、返します。
JNIEnv インタフェース関数テーブルのインデックス 231。
env:JNIEnv のインタフェースポインタ
buf: 直接バッファー java.nio.Buffer オブジェクト (null は不可)
バッファーに関連付けられたメモリ領域のサイズをバイト数で返します。-1 を返すのは、指定されたオブジェクトが直接の java.nio.Buffer でない場合、オブジェクトが未整列ビューバッファーでありプロセッサアーキテクチャーが未整列アクセスをサポートしていない場合、あるいは JNI の直接バッファーへのアクセスがこの仮想マシンでサポートされていない場合です。
JDK/JRE 1.4
プログラマは、メソッドまたはフィールドの名前および型を把握している場合、JNI を使用して Java メソッドの呼び出しまたは Java フィールドへのアクセスを行うことができます。Java Core Reflection API を使用すると、プログラマは実行時に Java クラスの内部を調査することができます。JNI は、JNI で使用されるフィールドとメソッド ID および Java Core Reflection API で使用されるメソッドオブジェクトの間の変換関数のセットを提供します。
jmethodID FromReflectedMethod(JNIEnv *env, jobject method);
java.lang.reflect.Method または java.lang.reflect.Constructor オブジェクトをメソッド ID に変換します。
JNIEnv インタフェース関数テーブルのインデックス 7。
JDK/JRE 1.2
jfieldID FromReflectedField(JNIEnv *env, jobject field);
java.lang.reflect.Field をフィールド ID に変換します。
JDK/JRE 1.2
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
jobject ToReflectedField(JNIEnv *env, jclass cls,
jfieldID fieldID);
cls から取得したフィールド ID を java.lang.reflect.Field オブジェクトに変換します。
変換に失敗した場合には、OutOfMemoryError をスローし、0 を返します。
JNIEnv インタフェース関数テーブルのインデックス 12。
JDK/JRE 1.2
jint GetJavaVM(JNIEnv *env, JavaVM **vm);
現在のスレッドに関連する Java VM インタフェース (呼び出し API で使用) を返します。その結果は、2 番目の引数 vm で示された位置に置かれます。
JNIEnv インタフェース関数テーブルのインデックス 219。
env:JNI インタフェースポインタ
vm: 結果を返すポインタ
成功の場合は「0」を、失敗の場合は負の値を返します。
| 目次 | 前の項目 | 次の項目 |
Copyright © 2005 Sun Microsystems, Inc. All rights reserved.