目次 | 前へ | 次へ

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

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

clazzObject クラスを指定する場合、または 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 を返します。

  • 最初と 2 番目のクラス引数が同じ Java クラスを表している。
  • 最初のクラスが 2 番目のクラスのサブクラスである。
  • 最初のクラスがそのインタフェースとして 2 番目のクラスを持っている。

例外

Throw

jint Throw(JNIEnv *env, jthrowable obj);

java.lang.Throwable オブジェクトのスローを発生させます。

リンケージ:

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

パラメータ:

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

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

戻り値:

成功すると「0」を返し、失敗すると負の値を返します。

例外:

java.lang.Throwable object obj.

ThrowNew

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

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

リンケージ:

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

パラメータ:

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

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

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

戻り値:

成功すると「0」を返し、失敗すると負の値を返します。

例外:

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

ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);

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

リンケージ:

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

パラメータ:

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

戻り値:

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

ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);

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

リンケージ:

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

パラメータ:

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

ExceptionClear

void ExceptionClear(JNIEnv *env);

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

リンケージ:

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

パラメータ:

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

FatalError

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

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

リンケージ:

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

パラメータ:

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

msg: エラーメッセージ。文字列は変更後の UTF-8 でエンコードされます。

ExceptionCheck

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

jboolean ExceptionCheck(JNIEnv *env);

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

リンケージ:

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

導入されたバージョン:

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

注:

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

JDK/JRE 1.2 では、ローカル参照の有効期間を管理するための関数セットが追加されました。その関数は次の 4 つです。

EnsureLocalCapacity

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

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

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

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

リンケージ:

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

導入されたバージョン:

JDK/JRE 1.2

PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);

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

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

リンケージ:

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

導入されたバージョン:

JDK/JRE 1.2

PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);

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

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

リンケージ:

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

導入されたバージョン:

JDK/JRE 1.2

NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);

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

リンケージ:

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

導入されたバージョン:

JDK/JRE 1.2

弱グローバル参照

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

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

解説    (2001 年 6 月に追加)

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

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

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

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

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

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

NewWeakGlobalRef

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

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

リンケージ:

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

導入されたバージョン:

JDK/JRE 1.2

DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

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

リンケージ:

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

導入されたバージョン:

JDK/JRE 1.2

オブジェクト操作

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

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

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

リンケージ:

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

パラメータ:

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

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

戻り値:

Java オブジェクトを返すか、オブジェクトを構築できない場合は 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 引数の直後の jvaluesargs 配列内に置きます。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 つを返します。

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

IsInstanceOf

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

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

リンケージ:

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

パラメータ:

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

obj: Java オブジェクト。

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

戻り値:

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

IsSameObject

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

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

リンケージ:

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

パラメータ:

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

ref1: Java オブジェクト。

ref2: Java オブジェクト。

戻り値:

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

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

GetFieldID

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

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

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

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

リンケージ:

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

パラメータ:

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

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

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

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

戻り値:

フィールド ID を返すか、処理が失敗した場合は NULL を返します。

例外:

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

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

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

Get<type>Field ルーチン

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

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

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

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

リンケージ:

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

パラメータ:

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

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

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

戻り値:

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

Set<type>Field ルーチン

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

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

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

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

リンケージ:

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

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

パラメータ:

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

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

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

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

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

GetMethodID

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

クラスまたはインタフェースのインスタンス (非 static) メソッドを表すメソッド ID を返します。このメソッドは、clazz のスーパークラスのいずれかで定義し、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 引数の直後の jvaluesargs 配列内に置きます。Call<type>MethodA ルーチンは、この配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

Call<type>MethodV ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の va_list 型の args 引数に入れます。Call<type>MethodV ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

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

表 4-3a インスタンスメソッド呼び出しルーチン
Call<type>Method 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 インタフェース関数テーブルのインデックス:

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

61
63
62

CallObjectMethod()
CallObjectMethodA()
CallObjectMethodV()

34
36
35

CallBooleanMethod()
CallBooleanMethodA()
CallBooleanMethodV()

37
39
38

CallByteMethod()
CallByteMethodA()
CallByteMethodV()

40
42
41

CallCharMethod()
CallCharMethodA()
CallCharMethodV()

43
45
44

CallShortMethod()
CallShortMethodA()
CallShortMethodV()

46
48
47

CallIntMethod()
CallIntMethodA()
CallIntMethodV()

49
51
50

CallLongMethod()
CallLongMethodA()
CallLongMethodV()

52
54
53

CallFloatMethod()
CallFloatMethodA()
CallFloatMethodV()

55
57
56

CallDoubleMethod()
CallDoubleMethodA()
CallDoubleMethodV()

58
60
59

パラメータ:

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

obj: Java オブジェクト。

methodID: メソッド ID。

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

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 引数の直後の jvaluesargs 配列内に置きます。CallNonvirtual<type>MethodA ルーチンは、この配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

CallNonvirtual<type>MethodV ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の va_list 型の args 引数に入れます。CallNonvirtualMethodV ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

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

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

リンケージ:

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

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

パラメータ:

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

clazz: Java クラス。

obj: Java オブジェクト。

methodID: メソッド ID。

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

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

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

リンケージ:

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

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

パラメータ:

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

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

fieldID: static フィールド ID。

戻り値:

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

SetStatic<type>Field ルーチン

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

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

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

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

リンケージ:

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

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

パラメータ:

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

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

fieldID: static フィールド ID。

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

static メソッドの呼び出し

GetStaticMethodID

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

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

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

リンケージ:

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

パラメータ:

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

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

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

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

戻り値:

メソッド ID を返すか、処理が失敗した場合は NULL を返します。

例外:

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

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

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

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

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

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

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

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

メソッド ID は、clazz のスーパークラスの 1 つからではなく、それ自体から取得する必要があります。

CallStatic<type>Method ルーチン

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

CallStatic<type>MethodA ルーチン

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

CallStatic<type>MethodV ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数の直後の va_list 型の args 引数に入れます。CallStaticMethodV ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

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

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

リンケージ:

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

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

パラメータ:

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

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

methodID: static メソッド ID。

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

static メソッドの引数。

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

args: 引数の配列。

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

args: 引数の va_list

戻り値:

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

例外:

Exceptions raised during the execution of the Java method.

文字列操作

NewString

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

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

リンケージ:

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

パラメータ:

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

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

len: Unicode 文字列の長さ。

戻り値:

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

例外:

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

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

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

リンケージ:

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

パラメータ:

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

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

戻り値:

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

GetStringChars

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

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

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

リンケージ:

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

パラメータ:

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

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

isCopy: ブール値を指すポインタ。

戻り値:

Unicode 文字列を参照するポインタを返すか、処理が失敗した場合は NULL を返します。

ReleaseStringChars

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

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

リンケージ:

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

パラメータ:

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

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

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

NewStringUTF

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

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

リンケージ:

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

パラメータ:

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

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

戻り値:

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

例外:

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

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

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

リンケージ:

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

パラメータ:

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

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

戻り値:

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

GetStringUTFChars

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

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

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

リンケージ:

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

パラメータ:

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

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

isCopy: ブール値を指すポインタ。

戻り値:

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

ReleaseStringUTFChars

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

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

リンケージ:

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

パラメータ:

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

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

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

注:

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

GetStringRegion

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

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

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

リンケージ:

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

導入されたバージョン:

JDK/JRE 1.2

GetStringUTFRegion

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

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

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

リンケージ:

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

導入されたバージョン:

JDK/JRE 1.2

GetStringCritical
ReleaseStringCritical

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

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

Get/ReleaseStringCritical の制限は、Get/ReleasePrimitiveArrayCritical の制限に似ています。

リンケージ (GetStringCritical):

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

リンケージ (ReleaseStingCritical):

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

導入されたバージョン:

JDK/JRE 1.2

配列操作

GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

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

リンケージ:

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

パラメータ:

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

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

戻り値:

配列の長さを返します。

NewObjectArray

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

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

リンケージ:

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

パラメータ:

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

length: 配列サイズ。

elementClass: 配列要素のクラス。

initialElement: 初期化値。

戻り値:

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

例外:

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

GetObjectArrayElement

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

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

リンケージ:

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

パラメータ:

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

array: Java 配列。

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

戻り値:

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

例外:

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

SetObjectArrayElement

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

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

リンケージ:

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

パラメータ:

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

array: Java 配列。

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

value: 新しい値。

例外:

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

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

New<PrimitiveType>Array ルーチン

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

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

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

リンケージ:

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

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

パラメータ:

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

length: 配列長。

戻り値:

Java 配列を返すか、配列を構築できない場合は NULL を返します。

Get<PrimitiveType>ArrayElements ルーチン

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

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

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

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

  • Get<PrimitiveType>ArrayElements を、表の実際のプリミティブ要素アクセス用ルーチン名の 1 つと置き換える。
  • ArrayType を対応する配列型と置き換える。
  • NativeType を、そのルーチンに対応するネイティブ型と置き換える。

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

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

リンケージ:

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

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

パラメータ:

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

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

isCopy: ブール値を指すポインタ。

戻り値:

配列要素を参照するポインタを返すか、処理が失敗した場合は NULL を返します。

Release<PrimitiveType>ArrayElements ルーチン

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

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

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

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

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

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

  • Release<PrimitiveType>ArrayElements を、表 4-11 に示されている実際のプリミティブ配列処置機能ルーチン名のいずれかと置き換える。
  • ArrayType を対応する配列型と置き換える。
  • NativeType を、そのルーチンに対応するネイティブ型と置き換える。

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

リンケージ:

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

表 4-11b 配列ルーチンの Release<PrimitiveType>ArrayElements ファミリ
Release<PrimitiveType>ArrayElements ルーチン
索引
ReleaseBooleanArrayElements()
191
ReleaseByteArrayElements()
192
ReleaseCharArrayElements()
193
ReleaseShortArrayElements()
194
ReleaseIntArrayElements()
195
ReleaseLongArrayElements()
196
ReleaseFloatArrayElements()
197
ReleaseDoubleArrayElements()
198

パラメータ:

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

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

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

mode: 解放モード。

Get<PrimitiveType>ArrayRegion ルーチン

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

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

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

  • Get<PrimitiveType>ArrayRegion を、表 4-12 に示されている実際のプリミティブ要素アクセス用ルーチン名のいずれかと置き換える。
  • ArrayType を対応する配列型と置き換える。
  • NativeType を、そのルーチンに対応するネイティブ型と置き換える。

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

リンケージ:

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

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

パラメータ:

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

array: Java 配列。

start: 開始インデックス。

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

buf: 転送先バッファー。

例外:

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

Set<PrimitiveType>ArrayRegion ルーチン

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

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

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

  • Set<PrimitiveType>ArrayRegion を、表の実際のプリミティブ要素アクセス用ルーチン名の 1 つと置き換える。
  • ArrayType を対応する配列型と置き換える。
  • NativeType を、そのルーチンに対応するネイティブ型と置き換える。
    表 4-13a 配列アクセス機能ルーチンの Set<PrimitiveType>ArrayRegion ファミリ
    Set<PrimitiveType>ArrayRegion ルーチン
    配列型
    ネイティブ型
    SetBooleanArrayRegion()
    jbooleanArray
    jboolean
    SetByteArrayRegion()
    jbyteArray
    jbyte
    SetCharArrayRegion()
    jcharArray
    jchar
    SetShortArrayRegion()
    jshortArray
    jshort
    SetIntArrayRegion()
    jintArray
    jint
    SetLongArrayRegion()
    jlongArray
    jlong
    SetFloatArrayRegion()
    jfloatArray
    jfloat
    SetDoubleArrayRegion()
    jdoubleArray
    jdouble

リンケージ:

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

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

パラメータ:

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

array: Java 配列。

start: 開始インデックス。

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

buf: 転送元バッファー。

例外:

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

注:

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

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

GetPrimitiveArrayCritical
ReleasePrimitiveArrayCritical

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

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

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

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

GetPrimtiveArrayCriticalReleasePrimitiveArrayCritical の複数のペアを入れ子にすることができます。たとえば、

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

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

リンケージ (GetPrimitiveArrayCritical):

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

リンケージ (ReleasePrimitiveArrayCritical):

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

導入されたバージョン:

JDK/JRE 1.2

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

RegisterNatives

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

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

typedef struct { 

    char *name; 

    char *signature; 

    void *fnPtr; 

} JNINativeMethod; 

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

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

リンケージ:

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

パラメータ:

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

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

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

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

戻り値:

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

例外:

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

UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);

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

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

リンケージ:

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

パラメータ:

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

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

戻り値:

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

モニターオペレーション

MonitorEnter

jint MonitorEnter(JNIEnv *env, jobject obj);

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

obj によって参照されるオブジェクトに関連するモニターに入ります。obj 参照は NULL にはできません。

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

MonitorEnter JNI 関数呼び出しで入ったモニターから、monitorexit Java 仮想マシンの命令または synchronized メソッドの戻り値を使用して出ることはできません。MonitorEnter JNI 関数呼び出しと monitorenter Java 仮想マシンの命令が、同じオブジェクトに関連付けられたモニターと競合することがあります。

デッドロックを回避するには、DetachCurrentThread 呼び出しを使用して JNI モニターを暗黙的に解放しないかぎり、MonitorEnter JNI 関数呼び出しで入ったモニターから出る場合は MonitorExit JNI 呼び出しを使用する必要があります。

リンケージ:

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

パラメータ:

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

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

戻り値:

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

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

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

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

リンケージ:

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

パラメータ:

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

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

戻り値:

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

例外:

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

NIO のサポート

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

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

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

リンケージ:

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

導入されたバージョン:

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 フィールドを参照している場合は isStaticJNI_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 フィールドを参照している場合は isStaticJNI_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」を返し、失敗した場合は負の値を返します。

 


目次 | 前へ | 次へ

Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.