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 インタフェースポインタの間で共用されます。

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
  };

バージョン情報

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 を返します。

JDK/JRE 1.6 では、GetVersion() は 0x00010006 を返します。

定数

JDK/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 

JDK/JRE 1.4 以降:

    #define JNI_VERSION_1_4 0x00010004

JDK/JRE 1.6 以降:

    #define JNI_VERSION_1_6 0x00010006

クラス操作

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: バッファー長。

戻り値:

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

例外:

ClassFormatError: クラスデータが有効なクラスを指定していない場合。

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

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

SecurityException: 呼び出し側が「java」パッケージツリー内にクラスを定義しようとした場合。

FindClass

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: システムがメモリー不足の場合。

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 を返します。

リンケージ:

導入されたバージョン:

JDK/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: ローカル参照。

EnsureLocalCapacity

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

少なくとも指定された数のローカル参照を現在のスレッドで作成できることを保証します。成功した場合は 0 を返します。それ以外の場合は負の数を返し、OutOfMemoryError をスローします。

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

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

リンケージ:

導入されたバージョン:

JDK/JRE 1.2

PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);

新しいローカル参照フレームを作成します。このフレームに最低限指定された数のローカル参照を作成できます。成功した場合は 0、失敗した場合は負の数と未処理の OutOfMemoryError を返します。

前回のローカルフレームで作成済みのローカル参照は、現在のローカルフレームでも引き続き有効です。

リンケージ:

導入されたバージョン:

JDK/JRE 1.2

PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);

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

前回のフレームへの参照を返す必要がない場合は、result として NULL を渡してください。

リンケージ:

導入されたバージョン:

JDK/JRE 1.2

NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);

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

リンケージ:

導入されたバージョン:

JDK/JRE 1.2

弱グローバル参照

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 がスローされます。

リンケージ:

導入されたバージョン:

JDK/JRE 1.2

DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

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

リンケージ:

導入されたバージョン:

JDK/JRE 1.2

オブジェクト操作

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

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

clazz 引数は配列クラスを参照できません。

リンケージ:

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

パラメータ:

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

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

戻り値:

Java オブジェクトを返すか、オブジェクトを構築できない場合は NULL を返します。

例外:

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

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

NewObject
NewObjectA
NewObjectV

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 引数は配列クラスを参照できません。

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 オブジェクトを返すか、オブジェクトを構築できない場合は NULL を返します。

例外:

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

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

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

GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);

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

リンケージ:

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

パラメータ:

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

obj: Java オブジェクト (NULL は不可)。

戻り値:

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

GetObjectRefType

jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);

obj 引数によって参照されるオブジェクトの型を返します。引数 obj は、ローカル参照、グローバル参照、弱グローバル参照のいずれかです。

リンケージ:

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

パラメータ:

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

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

vm: インタフェース取得元の仮想マシンインスタンス。

env: 現在のスレッドの JNI インタフェースポインタが配置される位置へのポインタ。

version: 要求された JNI バージョン。

戻り値:

関数 GetObjectRefType は、jobjectRefType として定義された次の列挙値の 1 つを返します。

引数 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

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 をそのルーチンに対応するネイティブ型と置き換える必要があります。

リンケージ:

パラメータ:

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 をそのルーチンに対応するネイティブ型と置き換える必要があります。

リンケージ:

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

パラメータ:

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

obj: Java オブジェクト (NULL は不可)。

fieldID: 有効なフィールド ID。

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

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

GetMethodID

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: システムがメモリー不足の場合。

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, 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 つからではなく、実クラス自体から取得する必要があります。

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 をそのルーチンに対応するネイティブ型と置き換える必要があります。

リンケージ:

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

パラメータ:

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

obj: Java オブジェクト。

methodID: メソッド ID。

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

Java メソッドに対する引数。

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

args: 引数の配列。

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

args: 引数の va_list。

戻り値:

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

例外:

Exceptions raised during the execution of the Java method.

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, 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 つから取得しなければなりません。

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 をそのルーチンに対応するネイティブ型と置き換える必要があります。

リンケージ:

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

パラメータ:

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

clazz: Java クラス。

obj: Java オブジェクト。

methodID: メソッド ID。

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

Java メソッドに対する引数。

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 フィールドの値を返します。アクセスすべきフィールドは、GetStaticFieldID() を呼び出すことによって取得されるフィールド ID で指定されます。

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

リンケージ:

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

パラメータ:

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

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

fieldID: static フィールド ID。

戻り値:

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

SetStatic<type>Field ルーチン

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

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

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

リンケージ:

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

パラメータ:

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() によって、まだ初期化されていないクラスが初期化されます。

リンケージ:

パラメータ:

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 つからではなく、それ自体から取得する必要があります。

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 をそのルーチンに対応するネイティブ型と置き換える必要があります。

リンケージ:

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

パラメータ:

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

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

methodID: static メソッド ID。

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

static メソッドの引数。

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

args: 引数の配列。

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

args: 引数の va_list。

戻り値:

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

例外:

Exceptions raised during the execution of the Java method.

文字列操作

NewString

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

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

リンケージ:

パラメータ:

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

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

len: Unicode 文字列の長さ。

戻り値:

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

例外:

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

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

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

リンケージ:

パラメータ:

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

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

戻り値:

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

GetStringChars

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 を返します。

ReleaseStringChars

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

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

リンケージ:

パラメータ:

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

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

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

NewStringUTF

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

変更後の UTF-8 エンコーディングによる文字配列から新しい java.lang.String オブジェクトを構築します。

リンケージ:

パラメータ:

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

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

戻り値:

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

例外:

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

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

文字列の長さを変更後の UTF-8 によるバイト数で返します。

リンケージ:

パラメータ:

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

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

戻り値:

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

GetStringUTFChars

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 を返します。

ReleaseStringUTFChars

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

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

リンケージ:

パラメータ:

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

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

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

GetStringRegion

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

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

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

リンケージ:

導入されたバージョン:

JDK/JRE 1.2

GetStringUTFRegion

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

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

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

リンケージ:

導入されたバージョン:

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):

リンケージ (ReleaseStingCritical):

導入されたバージョン:

JDK/JRE 1.2

配列操作

GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

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

リンケージ:

パラメータ:

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

array: Java 配列オブジェクト。

戻り値:

配列の長さを返します。

NewObjectArray

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

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

リンケージ:

パラメータ:

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

length: 配列サイズ。

elementClass: 配列要素のクラス。

initialElement: 初期化値。

戻り値:

Java 配列オブジェクトを返すか、配列を構築できない場合は NULL を返します。

例外:

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

GetObjectArrayElement

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

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

リンケージ:

パラメータ:

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

array: Java 配列。

index: 配列のインデックス。

戻り値:

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

例外:

ArrayIndexOutOfBoundsException: index が配列内の有効なインデックスを指定していない場合。

SetObjectArrayElement

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

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

リンケージ:

パラメータ:

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 をそのルーチンに対応する配列型と置き換える必要があります。

リンケージ:

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

パラメータ:

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

length: 配列長。

戻り値:

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 つの要素を表しています (アンパック表示)。その他の型の配列はすべて、メモリー内で必ず隣接するようになっています。

リンケージ:

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

パラメータ:

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

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

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

リンケージ:

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

パラメータ:

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

array: Java 配列オブジェクト。

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

mode: 解放モード。

Get<PrimitiveType>ArrayRegion ルーチン

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

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

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

リンケージ:

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

パラメータ:

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

array: Java 配列。

start: 開始インデックス。

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

buf: 転送先バッファー。

例外:

ArrayIndexOutOfBoundsException: 領域内のインデックスの 1 つでも有効ではない場合。

Set<PrimitiveType>ArrayRegion ルーチン

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

バッファーからのプリミティブ配列の領域を元の値に戻す関数のファミリです。

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

リンケージ:

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

パラメータ:

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

array: Java 配列。

start: 開始インデックス。

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

buf: 転送元バッファー。

例外:

ArrayIndexOutOfBoundsException: 領域内のインデックスの 1 つでも有効ではない場合。

GetPrimitiveArrayCritical
ReleasePrimitiveArrayCritical

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 かどうかをチェックする必要があります。

リンケージ (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);

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

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

リンケージ:

パラメータ:

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

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

戻り値:

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

モニターオペレーション

MonitorEnter

jint MonitorEnter(JNIEnv *env, jobject obj);

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

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」を返し、失敗した場合は負の値を返します。

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

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

ネイティブコードは、synchronized メソッドまたは monitorenter Java 仮想マシンの命令で入ったモニターから出るために MonitorExit を使用してはいけません。

リンケージ:

パラメータ:

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

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

戻り値:

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

例外:

IllegalMonitorStateException: 現在のスレッドがモニターを所有していない場合。

NIO のサポート

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

• NewDirectByteBuffer
• GetDirectBufferAddress
• GetDirectBufferCapacity

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

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 に変換します。

リンケージ:

導入されたバージョン:

JDK/JRE 1.2

ToReflectedMethod

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

ToReflectedField

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

Java VM インタフェース

GetJavaVM

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

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

リンケージ:

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

パラメータ:

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

vm: 結果が配置される位置へのポインタ。

戻り値:

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