目次|前|次 |
この章は、JNI関数のリファレンス・セクションです。この章では、JNIの関数をすべて取り上げます。また、JNI関数表の配置そのままに記載されています。
「必要がある」という言い方は、JNIプログラマに対する制限を示しています。たとえば、あるJNI関数について、それがNULL以外のオブジェクトを受け取る必要があると説明されている場合、プログラマの責任において、そのJNI関数にNULLを渡さないようにしなければなりません。それによって、JNI実装の際に、そのJNI関数におけるnullのポインタ・チェックを行う必要がなくなります。
この章の一部は、NetscapeのJRIドキュメントから転用されています。
参照資料では、関数を用途によってグループ化しています。参照セクションは、次の機能分野から構成されています。
各関数は、JNIEnv引数を介して、固定オフセットからアクセスできます。JNIEnv型は、すべてのJNI関数のポインタを格納する構造体を指すポインタです。これは次のように定義されます。
typedef const struct JNINativeInterface *JNIEnv;
VMは、次のコード例に示されているように、関数表を初期化します。最初の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
: システムがメモリー不足の場合。
SecurityException
: 呼出し側が「java」パッケージ・ツリー内にクラスを定義しようとした場合。
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では、上記のDeleteLocalRef
関数が用意されているため、プログラマは手動でローカル参照を削除できます。たとえば、ネイティブ・コードがオブジェクトの潜在的に大きな配列を繰返しにより処理し、反復ごとに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オブジェクトを返すか、オブジェクトを構築できない場合はNULL
を返します。
InstantiationException
: クラスがインタフェースまたは抽象クラスの場合。
OutOfMemoryError
: システムがメモリー不足の場合。
jobject NewObject(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);
jobject NewObjectA(JNIEnv *env, jclass clazz,
jmethodID methodID, const 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オブジェクトを返すか、オブジェクトを構築できない場合はNULL
を返します。
InstantiationException
: クラスがインタフェースまたは抽象クラスの場合。
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をそのルーチンに対応するネイティブ型と置き換える必要があります。
Get<type>Fieldルーチン名 | ネイティブ型 |
---|---|
GetObjectField()
|
jobject |
GetBooleanField()
|
jboolean |
GetByteField()
|
jbyte |
GetCharField()
|
jchar |
GetShortField()
|
jshort |
GetIntField()
|
jint |
GetLongField()
|
jlong |
GetFloatField()
|
jfloat |
GetDoubleField()
|
jdouble |
JNIEnvインタフェース関数表のインデックス:
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。
フィールドの内容を返します。
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をそのルーチンに対応するネイティブ型と置き換える必要があります。
Set<type>Fieldルーチン | ネイティブ型 |
---|---|
SetObjectField()
|
jobject |
SetBooleanField()
|
jboolean |
SetByteField()
|
jbyte |
SetCharField()
|
jchar |
SetShortField()
|
jshort |
SetIntField()
|
jint |
SetLongField()
|
jlong |
SetFloatField()
|
jfloat |
SetDoubleField()
|
jdouble |
JNIEnvインタフェース関数表のインデックス。
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
: フィールドの新しい値。
jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);
クラスまたはインタフェースのインスタンス(非static)メソッドを表すメソッドIDを返します。このメソッドは、clazz
のスーパー・クラスのいずれかで定義し、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, const 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をそのルーチンに対応するネイティブ型と置き換える必要があります。
Call<type>Method Routineルーチン名 | ネイティブ型 |
---|---|
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インタフェース関数表のインデックス:
Call<type>Method Routineルーチン名 | 索引 |
---|---|
CallVoidMethod() CallVoidMethodA() CallVoidMethodV()
|
61 |
CallObjectMethod() CallObjectMethodA() CallObjectMethodV()
|
34 |
CallBooleanMethod() CallBooleanMethodA() CallBooleanMethodV()
|
37 |
CallByteMethod() CallByteMethodA() CallByteMethodV()
|
40 |
CallCharMethod() CallCharMethodA() CallCharMethodV()
|
43 |
CallShortMethod() CallShortMethodA() CallShortMethodV()
|
46 |
CallIntMethod() CallIntMethodA() CallIntMethodV()
|
49 |
CallLongMethod() CallLongMethodA() CallLongMethodV()
|
52 |
CallFloatMethod() CallFloatMethodA() CallFloatMethodV()
|
55 |
CallDoubleMethod() CallDoubleMethodA() CallDoubleMethodV()
|
58 |
env
: JNIインタフェース・ポインタ。
obj
: Javaオブジェクト。
methodID
: メソッドID。
Javaメソッドに対する引数。
args
: 引数の配列。
args
: 引数のva_list。
Javaメソッドを呼び出した結果を返します。
Javaメソッドを実行している間に発生した例外。
NativeType CallNonvirtual<type>Method(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, ...);
NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, const 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をそのルーチンに対応するネイティブ型と置き換える必要があります。
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インタフェース関数表のインデックス。
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。
Javaメソッドに対する引数。
args
: 引数の配列。
args
: 引数のva_list
。
Javaメソッドを呼び出した結果を返します。
Javaメソッドを実行している間に発生した例外。
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フィールドの値を返します。アクセスすべきフィールドは、GetStaticFieldID()
を呼び出すことによって取得されるフィールドIDで指定されます。
次の表には、getルーチン名のファミリと結果の型が示されています。GetStatic<type>Field内のtypeをフィールドのJava型と置き換えるか、または表の実際のstaticフィールド・アクセス用ルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
GetStatic<type>Fieldルーチン名 | ネイティブ型 |
---|---|
GetStaticObjectField ()
|
jobject |
GetStaticBooleanField ()
|
jboolean |
GetStaticByteField ()
|
jbyte |
GetStaticCharField ()
|
jchar |
GetStaticShortField ()
|
jshort |
GetStaticIntField ()
|
jint |
GetStaticLongField ()
|
jlong |
GetStaticFloatField ()
|
jfloat |
GetStaticDoubleField ()
|
jdouble |
JNIEnvインタフェース関数表のインデックス。
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フィールドの内容を返します。
void
SetStatic<type>Field(JNIEnv *env, jclass clazz,
NativeType
jfieldID fieldID,value);
このアクセス用ルーチンのファミリは、オブジェクトのstaticフィールドの値を設定します。アクセスすべきフィールドは、GetStaticFieldID()
を呼び出すことによって取得されるフィールドIDで指定されます。
次の表には、セット・ルーチン名と値の型が示されています。SetStatic<type>Field内のtypeをフィールドのJava型と置き換えるか、または表の実際のセットstaticフィールド・ルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
SetStatic<type>Fieldルーチン名 | NativeType |
---|---|
SetStaticObjectField ()
|
jobject |
SetStaticBooleanField ()
|
jboolean |
SetStaticByteField ()
|
jbyte |
SetStaticCharField ()
|
jchar |
SetStaticShortField ()
|
jshort |
SetStaticIntField ()
|
jint |
SetStaticLongField ()
|
jlong |
SetStaticFloatField ()
|
jfloat |
SetStaticDoubleField ()
|
jdouble |
JNIEnvインタフェース関数表のインデックス。
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
: フィールドの新しい値。
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つからではなく、それ自体から取得する必要があります。
プログラマは、メソッドに渡す引数をすべて、methodID
引数の直後に置きます。CallStatic<type>Methodルーチンは、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
プログラマは、メソッドに渡す引数をすべて、methodID
引数の直後のjvalues
のargs
配列内に置きます。CallStaticMethodAルーチンは、この配列内の引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
プログラマは、メソッドに渡す引数をすべて、methodID
引数の直後のva_list
型のargs
引数に入れます。CallStaticMethodVルーチンは、これらの引数を受け取り、プログラマが呼び出したいJavaメソッドに渡します。
次の表には、メソッド呼出しルーチンがそれぞれその結果の型によって示されています。CallStatic<type>Method内のtypeをメソッドのJava型と置き換えるか、または表の実際のメソッド呼出しルーチン名の1つを使用し、かつNativeTypeをそのルーチンに対応するネイティブ型と置き換える必要があります。
CallStatic<type>Methodルーチン名 | ネイティブ型 |
---|---|
CallStaticVoidMethod () CallStaticVoidMethodA () CallStaticVoidMethod V()
|
void |
CallStaticObjectMethod () CallStaticObjectMethod A() CallStaticObjectMethod V()
|
jobject |
CallStaticBooleanMethod () CallStaticBooleanMethod A() CallStaticBooleanMethod V()
|
jboolean |
CallStaticByteMethod () CallStaticByteMethod A() CallStaticByteMethod V()
|
jbyte |
CallStaticCharMethod () CallStaticCharMethod A() CallStaticCharMethod V()
|
jchar |
CallStaticShortMethod () CallStaticShortMethod A() CallStaticShortMethod V()
|
jshort |
CallStaticIntMethod () CallStaticIntMethod A() CallStaticIntMethod V()
|
jint |
CallStaticLongMethod () CallStaticLongMethod A() CallStaticLongMethod V()
|
jlong |
CallStaticFloatMethod () CallStaticFloatMethod A() CallStaticFloatMethod V()
|
jfloat |
CallStaticDoubleMethod () CallStaticDoubleMethod A() CallStaticDoubleMethod V()
|
jdouble |
JNIEnvインタフェース関数表のインデックス。
CallStatic<type>Methodルーチン名 | 索引 |
---|---|
CallStaticVoidMethod () CallStaticVoidMethodA () CallStaticVoidMethod V()
|
141 143 142 |
CallStaticObjectMethod () CallStaticObjectMethod A() CallStaticObjectMethod V()
|
114 116 115 |
CallStaticBooleanMethod () CallStaticBooleanMethod A() CallStaticBooleanMethod V()
|
117 119 118 |
CallStaticByteMethod () CallStaticByteMethod A() CallStaticByteMethod V()
|
120 122 121 |
CallStaticCharMethod () CallStaticCharMethod A() CallStaticCharMethod V()
|
123 125 124 |
CallStaticShortMethod () CallStaticShortMethod A() CallStaticShortMethod V()
|
126 128 127 |
CallStaticIntMethod () CallStaticIntMethod A() CallStaticIntMethod V()
|
129 131 130 |
CallStaticLongMethod () CallStaticLongMethod A() CallStaticLongMethod V()
|
132 134 133 |
CallStaticFloatMethod () CallStaticFloatMethod A() CallStaticFloatMethod V()
|
135 137 136 |
CallStaticDoubleMethod () CallStaticDoubleMethod A() CallStaticDoubleMethod V()
|
138 140 139 |
env
: JNIインタフェース・ポインタ。
clazz
: Javaクラス・オブジェクト。
methodID
: staticメソッドID。
staticメソッドの引数。
args
: 引数の配列。
args
: 引数のva_list
。
static Javaメソッドを呼び出した結果を返します。
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);
新しいプリミティブ配列オブジェクトを構築するために使用される演算のファミリ。次の表には、特定のプリミティブ配列コンストラクタが示されています。New<PrimitiveType>Arrayを、この表の実際のプリミティブ配列コンストラクタ・ルーチン名の1つと置き換え、ArrayTypeをそのルーチンに対応する配列型と置き換える必要があります。
New<PrimitiveType>Arrayルーチン | 配列型 |
---|---|
NewBooleanArray()
|
jbooleanArray |
NewByteArray()
|
jbyteArray |
NewCharArray()
|
jcharArray |
NewShortArray()
|
jshortArray |
NewIntArray()
|
jintArray |
NewLongArray()
|
jlongArray |
NewFloatArray()
|
jfloatArray |
NewDoubleArray()
|
jdoubleArray |
JNIEnvインタフェース関数表のインデックス。
New<PrimitiveType>Arrayルーチン | 索引 |
---|---|
NewBooleanArray()
|
175 |
NewByteArray()
|
176 |
NewCharArray()
|
177 |
NewShortArray()
|
178 |
NewIntArray()
|
179 |
NewLongArray()
|
180 |
NewFloatArray()
|
181 |
NewDoubleArray()
|
182 |
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つの要素を表しています(アンパック表示)。その他の型の配列はすべて、メモリー内で必ず隣接するようになっています。
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インタフェース関数表のインデックス。
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
を返します。
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
は次の表に示されているような影響を及ぼします。
モード | アクション |
---|---|
0
|
内容を元の配列にコピーし直し、elems バッファを解放する
|
JNI_COMMIT
|
内容を元の配列にコピーし直すが、elems バッファを解放しない
|
JNI_ABORT
|
変更の可能性があってもその内容を元に戻さず、バッファを解放する |
ほとんどの場合、プログラマは、ピン配列とコピー配列の両方に対して一貫した動作を保証するために、「0」をmode
引数に渡します。0以外を渡す場合は、プログラマはメモリーを十分に注意して管理する必要があります。
次の表には、プリミティブ配列処置機能のファミリを構成する特定のルーチンが示されています。次の置換を行う必要があります。
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インタフェース関数表のインデックス。
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
: 解放モード。
void Get<PrimitiveType>ArrayRegion(JNIEnv *env,
ArrayType array,
NativeType
jsize start, jsize len,*buf);
プリミティブ配列の領域をバッファにコピーする関数のファミリです。
次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。
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インタフェース関数表のインデックス。
<table border="1" summary= "Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines"GetBooleanArrayRegion()
GetByteArrayRegion()
GetCharArrayRegion()
GetShortArrayRegion()
GetIntArrayRegion()
GetLongArrayRegion()
GetFloatArrayRegion()
GetDoubleArrayRegion()
env
: JNIインタフェース・ポインタ。
array
: Java配列。
start
: 開始インデックス。
len
: コピー対象の要素の数。
buf
: 転送先バッファ。
ArrayIndexOutOfBoundsException
: 領域内のインデックスの1つでも有効ではない場合。
void
Set<PrimitiveType>ArrayRegion(JNIEnv *env,
ArrayType array,
const NativeType
jsize start, jsize len,*buf);
バッファからのプリミティブ配列の領域を元の値に戻す関数のファミリです。
次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。
SetBooleanArrayRegion()
SetByteArrayRegion()
SetCharArrayRegion()
SetShortArrayRegion()
SetIntArrayRegion()
SetLongArrayRegion()
SetFloatArrayRegion()
SetDoubleArrayRegion()
JNIEnvインタフェース関数表のインデックス。
<table border="1" summary= "Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines"SetBooleanArrayRegion()
SetByteArrayRegion()
SetCharArrayRegion()
SetShortArrayRegion()
SetIntArrayRegion()
SetLongArrayRegion()
SetFloatArrayRegion()
SetDoubleArrayRegion()
パラメータ:
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<PrimitiveType>ArrayElements
関数と非常によく似ています。可能な場合は、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
かどうかをチェックする必要があります。
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
構造体は次のように定義されます。
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
: 指定されたメソッドが見つからない場合、または、そのメソッドがネイティブではない場合。
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仮想マシンの命令が、同じオブジェクトに関連付けられたモニターと競合することがあります。
デッドロックを回避するには、DetachCurrentThread
呼出しを使用してJNIモニターを暗黙的に解放しないかぎり、MonitorEnter
JNI関数呼出しで入ったモニターから出る場合はMonitorExit
JNI呼出しを使用する必要があります。
env
: JNIインタフェース・ポインタ。
obj
: 通常のJavaオブジェクトまたはクラス・オブジェクト。
成功した場合は「0」を返し、失敗した場合は負の値を返します。
jint MonitorExit(JNIEnv *env, jobject obj);
現在のスレッドは、obj
によって参照されたベースとなるJavaオブジェクトに関連するモニターの所有者でなければなりません。このスレッドは、このモニターに入った回数を表すカウンタを減少させます。カウンタの値がゼロになると、現在のスレッドはモニターを解放します。
ネイティブ・コードは、synchronizedメソッドまたはmonitorenter
Java仮想マシンの命令で入ったモニターから出るためにMonitorExit
を使用してはいけません。
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がこのようなアクセスをサポートする場合、これら3つの関数は適切な値を返すように実装される必要があります。
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は不可)
バッファに関連付けられたメモリー領域の容量を返します。指定されたオブジェクトが直接のjava.nio.Bufferでない場合、オブジェクトが未整列ビュー・バッファであり、かつプロセッサ・アーキテクチャが未整列アクセスをサポートしていない場合、または直接バッファへのJNIのアクセスがこの仮想マシンによってサポートされていない場合は-1を返します。
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に変換します。
JNIEnvインタフェース関数表のインデックス8。
JDK/JRE 1.2
jobject ToReflectedMethod(JNIEnv *env, jclass cls,
jmethodID methodID, jboolean isStatic);
cls
から取得したメソッドIDをjava.lang.reflect.Method
またはjava.lang.reflect.Constructor
オブジェクトに変換します。そのメソッドIDがstaticフィールドを参照している場合はisStatic
をJNI_TRUE
に、それ以外の場合はJNI_FALSE
に設定する必要があります。
失敗した場合はOutOfMemoryError
をスローし、0を返します。
JNIEnvインタフェース関数表のインデックス9。
JDK/JRE 1.2
jobject ToReflectedField(JNIEnv *env, jclass cls,
jfieldID fieldID, jboolean isStatic);
cls
から取得したフィールドIDをjava.lang.reflect.Field
オブジェクトに変換します。fieldID
がstaticフィールドを参照している場合はisStatic
をJNI_TRUE
に、それ以外の場合はJNI_FALSE
に設定する必要があります。
失敗した場合は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」を返し、失敗した場合は負の値を返します。
目次|前|次 |