第4章: JNI関数

この章は、JNI関数のリファレンス・セクションです。 この章では、JNIの関数をすべて取り上げます。 また、JNI関数表の配置そのままに記載されています。

この用語の使用は、JNIプログラマの制限事項を説明するものでなければならないことに注意してください。 たとえば、あるJNI関数について、それがNULL以外のオブジェクトを受け取る必要があると説明されている場合、プログラマの責任において、そのJNI関数にNULLを渡さないようにしなければなりません。 それによって、JNI実装の際に、そのJNI関数におけるnullのポインタ・チェックを行う必要がなくなります。 明示的でないときにNULLを渡すと、予期しない例外や致命的なクラッシュが発生する可能性があります。

定義がNULLを返すことがあり、エラー時に例外をスローする関数は、エラーを示すためにNULLを返すだけで、例外をスローすることはできません。 たとえば、JNIの実装では、一時的に"メモリー不足"条件が発生すると見なすことがあり、OutOfMemoryErrorをスローしたくない場合があります。これは致命的な(JDK API java.lang.Error documentation: "合理的なアプリケーションがキャッチしようとすべきではない深刻な問題を示しています")と思われるためです。

この章の一部は、NetscapeのJRIドキュメントから転用されています。

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

• インタフェース関数表
• Constants
  • ブール値
  • リターン・コード
• バージョン情報
  • GetVersion
  • バージョン定数
• クラス操作
  • DefineClass
  • FindClass
  • GetSuperclass
  • IsAssignableFrom
• モジュールの操作
  • GetModule
• Exceptions
  • Throw
  • ThrowNew
  • ExceptionOccurred
  • ExceptionDescribe
  • ExceptionClear
  • FatalError
  • ExceptionCheck
• グローバル参照およびローカル参照
  • Global References
  • NewGlobalRef
  • DeleteGlobalRef
  • Local References
  • DeleteLocalRef
  • EnsureLocalCapacity
  • PushLocalFrame
  • PopLocalFrame
  • NewLocalRef
• 弱グローバル参照
  • NewWeakGlobalRef
  • DeleteWeakGlobalRef
• オブジェクト・オペレーション
  • AllocObject
  • NewObject、NewObjectA、NewObjectV
  • GetObjectClass
  • GetObjectRefType
  • IsInstanceOf
  • IsSameObject
• オブジェクトのフィールドへのアクセス
  • GetFieldID
  • Get<type>Fieldルーチン
  • Set<type>Fieldルーチン
• インスタンス・メソッドの呼び出し
  • GetMethodID
  • Call<type>Methodルーチン、Call<type>MethodAルーチン、Call<type>MethodVルーチン
  • CallNonvirtual<type>Methodルーチン、CallNonvirtual<type>MethodAルーチン、CallNonvirtual<type>MethodVルーチン
• staticフィールドへのアクセス
  • GetStaticFieldID
  • GetStatic<type>Fieldルーチン
  • SetStatic<type>Fieldルーチン
• staticメソッドの呼び出し
  • GetStaticMethodID
  • CallStatic<type>Methodルーチン、CallStatic<type>MethodAルーチン、CallStatic<type>MethodVルーチン
• 文字列操作
  • NewString
  • GetStringLength
  • GetStringChars
  • ReleaseStringChars
  • NewStringUTF
  • GetStringUTFLength
  • GetStringUTFChars
  • ReleaseStringUTFChars
  • GetStringRegion
  • GetStringUTFRegion
  • GetStringCritical、ReleaseStringCritical
• 配列操作
  • GetArrayLength
  • NewObjectArray
  • GetObjectArrayElement
  • SetObjectArrayElement
  • New<PrimitiveType>Arrayルーチン
  • Get<PrimitiveType>ArrayElementsルーチン
  • Release<PrimitiveType>ArrayElementsルーチン
  • Get<PrimitiveType>ArrayRegionルーチン
  • Set<PrimitiveType>ArrayRegionルーチン
  • GetPrimitiveArrayCritical、ReleasePrimitiveArrayCritical
• ネイティブ・メソッドの登録
  • RegisterNatives
  • UnregisterNatives
• モニター・オペレーション
  • MonitorEnter
  • MonitorExit
• NIOのサポート
  • NewDirectByteBuffer
  • GetDirectBufferAddress
  • GetDirectBufferCapacity
• リフレクションのサポート
  • FromReflectedMethod
  • FromReflectedField
  • ToReflectedMethod
  • ToReflectedField
• Java VMインタフェース
  • GetJavaVM

インタフェース関数表

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

typedef const struct JNINativeInterface *JNIEnv;

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

関数表は、すべてのJNIインタフェース・ポインタの間で共用されます。

const struct JNINativeInterface ... = {

    NULL,
    NULL,
    NULL,
    NULL,
    GetVersion,

    DefineClass,
    FindClass,

    FromReflectedMethod,
    FromReflectedField,
    ToReflectedMethod,

    GetSuperclass,
    IsAssignableFrom,

    ToReflectedField,

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

    PushLocalFrame,
    PopLocalFrame,

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

    AllocObject,
    NewObject,
    NewObjectV,
    NewObjectA,

    GetObjectClass,
    IsInstanceOf,

    GetMethodID,

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

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

    GetFieldID,

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

    GetStaticMethodID,

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

    GetStaticFieldID,

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

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

    NewString,

    GetStringLength,
    GetStringChars,
    ReleaseStringChars,

    NewStringUTF,
    GetStringUTFLength,
    GetStringUTFChars,
    ReleaseStringUTFChars,

    GetArrayLength,

    NewObjectArray,
    GetObjectArrayElement,
    SetObjectArrayElement,

    NewBooleanArray,
    NewByteArray,
    NewCharArray,
    NewShortArray,
    NewIntArray,
    NewLongArray,
    NewFloatArray,
    NewDoubleArray,

    GetBooleanArrayElements,
    GetByteArrayElements,
    GetCharArrayElements,
    GetShortArrayElements,
    GetIntArrayElements,
    GetLongArrayElements,
    GetFloatArrayElements,
    GetDoubleArrayElements,

    ReleaseBooleanArrayElements,
    ReleaseByteArrayElements,
    ReleaseCharArrayElements,
    ReleaseShortArrayElements,
    ReleaseIntArrayElements,
    ReleaseLongArrayElements,
    ReleaseFloatArrayElements,
    ReleaseDoubleArrayElements,

    GetBooleanArrayRegion,
    GetByteArrayRegion,
    GetCharArrayRegion,
    GetShortArrayRegion,
    GetIntArrayRegion,
    GetLongArrayRegion,
    GetFloatArrayRegion,
    GetDoubleArrayRegion,
    SetBooleanArrayRegion,
    SetByteArrayRegion,
    SetCharArrayRegion,
    SetShortArrayRegion,
    SetIntArrayRegion,
    SetLongArrayRegion,
    SetFloatArrayRegion,
    SetDoubleArrayRegion,

    RegisterNatives,
    UnregisterNatives,

    MonitorEnter,
    MonitorExit,

    GetJavaVM,

    GetStringRegion,
    GetStringUTFRegion,

    GetPrimitiveArrayCritical,
    ReleasePrimitiveArrayCritical,

    GetStringCritical,
    ReleaseStringCritical,

    NewWeakGlobalRef,
    DeleteWeakGlobalRef,

    ExceptionCheck,

    NewDirectByteBuffer,
    GetDirectBufferAddress,
    GetDirectBufferCapacity,

    GetObjectRefType,

    GetModule
  };

定数

JNI API全体で使用される一般的な定数がいくつかあります。

ブール値

#define JNI_FALSE 0
#define JNI_TRUE 1

リターン・コード

JNI関数の一般的な戻り値定数。

#define JNI_OK           0                 /* success */
#define JNI_ERR          (-1)              /* unknown error */
#define JNI_EDETACHED    (-2)              /* thread detached from the VM */
#define JNI_EVERSION     (-3)              /* JNI version error */
#define JNI_ENOMEM       (-4)              /* not enough memory */
#define JNI_EEXIST       (-5)              /* VM already created */
#define JNI_EINVAL       (-6)              /* invalid arguments */

バージョン情報

GetVersion

jint GetVersion(JNIEnv *env);

ネイティブ・メソッド・インタフェースのバージョンを返します。 次の表は、Java SEプラットフォーム(古いバージョンのJNIでは、Java SEプラットフォームの代わりにJDKリリースが使用されています)の各リリースに含まれるJNIのバージョンを示しています:

リンケージ:

JNIEnvインタフェース関数表のインデックス4。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

戻り値:

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

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

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

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

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

JDK/JRE 1.8では、GetVersion()がJNI_VERSION_1_8を返します。

JDK/JRE 9では、GetVersion()がJNI_VERSION_9を返します。

JDK/JRE 10では、GetVersion()がJNI_VERSION_10を返します。

バージョン定数

#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002
#define JNI_VERSION_1_4 0x00010004
#define JNI_VERSION_1_6 0x00010006
#define JNI_VERSION_1_8 0x00010008
#define JNI_VERSION_9   0x00090000
#define JNI_VERSION_10  0x000a0000

クラス操作

DefineClass

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

rawクラス・データのバッファからクラスをロードします。 rawクラス・データを含むバッファは、DefineClass呼出しが戻った後はVMによって参照されません。必要に応じて破棄しても構いません。

リンケージ:

JNIEnvインタフェース関数表のインデックス5。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

name: 定義されるクラス名またはインタフェース名。 文字列は変更後のUTF-8でエンコードされます。 この値はNULLであるか、クラス・ファイル・データ内でエンコードされた名前と一致する必要があります。

loader: 定義されたクラスに割り当てられるクラス・ローダー。 この値は、NULLであり、"nullのクラス・ローダー" (または"ブートストラップ・クラス・ローダー")を示す。

buf: .classファイル・データを含むバッファ。 NULLの値はClassFormatErrorを引き起こします。

bufLen: バッファ長。

戻り値:

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

例外:

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

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

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

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

FindClass

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

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

JDK 1.2以降、Javaセキュリティ・モデルでは、非システム・クラスがネイティブ・メソッドをロードして呼び出すことができます。 FindClassは、現在のネイティブ・メソッドに関連付けられたクラス・ローダー、つまりネイティブ・メソッドを宣言したクラスのクラス・ローダーを検出します。 ネイティブ・メソッドがシステム・クラスに属する場合、クラス・ローダーは検出されません。 それ以外の場合には、適切なクラス・ローダーが呼び出され、名前が付けられたクラスのロードおよびリンクを行います。

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

FindClassがライブラリ・ライフ・サイクル関数フックから呼び出された場合、クラス・ローダーは次のように決定されます:

• JNI_OnLoadとJNI_OnLoad_Lでは、ネイティブ・ライブラリをロードしているクラスのクラス・ローダーが使用されます
• JNI_OnUnloadとJNI_OnUnload_Lの場合、ClassLoader.getSystemClassLoaderが返すクラス・ローダーは(ロード時に使用されたクラス・ローダーが存在しなくなる可能性があるため)

name引数は、完全修飾クラス名または配列型シグネチャです。 たとえば、java.lang.Stringクラスの完全修飾クラス名は次のとおりです。

    "java/lang/String"

配列クラスjava.lang.Object[]の配列型シグニチャは次のとおりです。

    "[Ljava/lang/Object;"

リンケージ:

JNIEnvインタフェース関数表のインデックス6。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

name: 完全修飾クラス名は(つまり、"/"で区切られたパッケージ名の後にクラス名が続きます)です。 その名前が[(配列シグニチャ文字)で始まっている場合は、配列クラスを返します。 文字列は変更後のUTF-8でエンコードされます。 NULLの値により、NoClassDefFoundErrorが発生するか、クラッシュする可能性があります。

戻り値:

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

例外:

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

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

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

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

GetSuperclass

jclass GetSuperclass(JNIEnv *env, jclass clazz);

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

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

リンケージ:

JNIEnvインタフェース関数表のインデックス10。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

戻り値:

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

IsAssignableFrom

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

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

リンケージ:

JNIEnvインタフェース関数表のインデックス11。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

clazz1: 最初のクラス引数は、NULLであってはなりません。

clazz2: 2番目のクラス引数は、NULLであってはなりません。

戻り値:

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

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

モジュールの操作

GetModule

jobject GetModule(JNIEnv *env, jclass clazz);

クラスがメンバーであるモジュールのjava.lang.Moduleオブジェクトを返します。 クラスが名前付きモジュールにない場合、クラスのクラス・ローダーの名前のないモジュールが返されます。 クラスが配列型を表す場合、この関数は要素型のModuleオブジェクトを返します。 クラスがプリミティブ型またはvoidを表す場合は、java.baseモジュールのModuleオブジェクトが返されます。

リンケージ:

JNIEnvインタフェース関数表のインデックス233。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

戻り値:

クラスまたはインタフェースがメンバーであるモジュールを返します。

導入されたバージョン:

JDK/JRE 9

例外

Throw

jint Throw(JNIEnv *env, jthrowable obj);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

obj: java.lang.Throwableオブジェクトは、NULLであってはなりません。

戻り値:

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

例外:

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

ThrowNew

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

clazz: java.lang.Throwableのサブクラスは、NULLであってはなりません。

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

戻り値:

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

例外:

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

ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

戻り値:

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

ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

ExceptionClear

void ExceptionClear(JNIEnv *env);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

FatalError

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

msg: エラー・メッセージ。 文字列は変更後のUTF-8でエンコードされます。 NULL値の可能性があります。

ExceptionCheck

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

jboolean ExceptionCheck(JNIEnv *env);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

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

Global References

NewGlobalRef

jobject NewGlobalRef(JNIEnv *env, jobject obj);

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

リンケージ:

JNIEnvインタフェース関数表のインデックス21。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

obj: グローバル参照またはローカル参照。 NULLの値である可能性があります。この場合、この関数はNULLを返します。

戻り値:

指定されたobjの値がNULLだった場合、またはシステムのメモリーが不足している場合は、グローバル参照、またはNULLを返します。

DeleteGlobalRef

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);

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

リンケージ:

JNIEnvインタフェース関数表のインデックス22。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

globalRef: グローバル参照。 NULLの値である可能性があります。この場合、この関数は何もしません。

Local References

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

DeleteLocalRef

void DeleteLocalRef(JNIEnv *env, jobject localRef);

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

リンケージ:

JNIEnvインタフェース関数表のインデックス23。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

localRef: ローカル参照。 ここで渡されたNULL値の場合、関数は何も行いません。

注: 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を呼び出します。

一部のJava Virtual Machineの実装では、最大capacityを制限することがあります。これにより、関数がエラー(例:JNI_ERRまたはJNI_EINVAL)を返す可能性があります。 たとえば、HotSpot JVMの実装では、-XX:+MaxJNILocalCapacityフラグ(default : 65536)が使用されます。

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

capacity: 必要なローカル参照の最小数。 0以上にする必要があります。

戻り値:

成功時にJNI_OK。

導入されたバージョン:

JDK/JRE 1.2

PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);

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

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

EnsureLocalCapacityと同様に、Java Virtual Machineの実装によっては、関数がエラーを返す可能性がある最大capacityを制限することを選択することがあります。

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

capacity: 必要なローカル参照の最小数。 > 0でなければなりません。

戻り値:

成功時にJNI_OK。

導入されたバージョン:

JDK/JRE 1.2

PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

result: 前のローカル参照フレームに渡されるオブジェクトは、NULLであってもよい。

戻り値:

指定されたresultオブジェクトの前のローカル参照フレーム内のローカル参照を返します。指定されたresultオブジェクトがNULLだった場合はNULLを返します。

導入されたバージョン:

JDK/JRE 1.2

NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);

refと同じオブジェクトを参照する新しいローカル参照を作成します。 与えられたrefは、グローバル、ローカル参照、またはNULLであってもよい。 refがnullを参照している場合は、NULLを返します。

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

ref: 関数が新しいローカル参照を作成するオブジェクトへの参照。 NULL値の可能性があります。

戻り値:

refと同じオブジェクトを参照する新しいローカル参照を返します。

次の場合はNULLを返すことがあります:

• refはnullを参照
• システムのメモリーが不足しています
• refは弱いグローバル参照であり、既にガベージ・コレクションされています

導入されたバージョン:

JDK/JRE 1.2

弱グローバル参照

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

JNIの弱いグローバル参照は、Java SE Platform API (java.lang.refパッケージとそのクラス)の一部として利用可能な、Java Weak Referencesの簡略版です。

解説 (2001年6月に追加)

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

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

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

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

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

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

NewWeakGlobalRef

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

弱グローバル参照を新規作成します。 弱いグローバル参照は、指定されたオブジェクトのガベージ・コレクションを妨げません。 参照によって参照されるオブジェクトが解放されたかどうかをテストするためにIsSameObjectを使用できます。 objがnullを参照する場合、またはobjが弱いグローバル参照である場合、またはVMのメモリーが不足している場合は、NULLを返します。 VMがメモリーを使い果たしてしまった場合は、OutOfMemoryErrorがスローされます。

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

obj: ためのグローバルな弱参照を作成するオブジェクトです。

戻り値:

指定されたobjにグローバルな弱参照を返します。

次の場合はNULLを返すことがあります:

• objはnullを参照
• システムのメモリーが不足しています
• objは弱いグローバル参照であり、既にガベージ・コレクションされています

例外:

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

導入されたバージョン:

JDK/JRE 1.2

DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

obj: 削除するグローバルな弱参照。 この関数は、NULLを渡すと何もしません。

導入されたバージョン:

JDK/JRE 1.2

オブジェクト・オペレーション

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

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

注意: Java言語仕様、"ファイナライズの実装" (JLS§12.6.1) states : "オブジェクトoは、そのコンストラクタがObject onのコンストラクタを呼び出してその呼び出しが正常に完了するまで、ファイナライズ可能ではありません"。 AllocObject()はコンストラクタを呼び出さないため、この関数で作成されたオブジェクトはファイナライズに適格ではありません。

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトへの参照で、NULLであってはなりません。

戻り値:

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インタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトへの参照で、NULLであってはなりません。

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

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

コンストラクタの引数。

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

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

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

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

戻り値:

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

例外:

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

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

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

GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

obj: Javaオブジェクトは、NULLであってはなりません。

戻り値:

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

GetObjectRefType

jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

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

戻り値:

関数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インタフェース・ポインタは、NULLであってはなりません。

obj: Javaオブジェクト、場合によってはNULLの値。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

戻り値:

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

IsSameObject

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

ref1: Javaオブジェクトは、NULLです。

ref2: Javaオブジェクトは、NULLです。

戻り値:

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インタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

name: 0で終了する修正UTF-8文字列内のフィールド名は、NULLであってはなりません。

sig: 0で終了する修正UTF-8文字列のフィールド・シグネチャは、NULLであってはなりません。

戻り値:

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

リンケージ:

JNIEnvインタフェース関数表のインデックス:

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

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インタフェース・ポインタは、NULLであってはなりません。

obj: Javaオブジェクトは、NULLであってはなりません。

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

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

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

GetMethodID

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

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

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

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

リンケージ:

JNIEnvインタフェース関数表のインデックス33。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

name: 0で終了する修正UTF-8文字列のメソッド名は、NULLであってはなりません。

sig: 0で終了する変更UTF-8文字列のメソッド・シグネチャは、NULLであってはなりません。

戻り値:

メソッド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インタフェース・ポインタは、NULLであってはなりません。

obj: Javaオブジェクトは、NULLであってはなりません。

methodID: 有効なメソッドID。

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

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

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

args: 引数の配列。

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

args: 引数のva_list。

戻り値:

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

例外:

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

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

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

NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, 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ルーチンは、Java 8で導入された"デフォルトのインタフェース・メソッド"を呼び出すためのメカニズムです。

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インタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラスであり、NULLであってはなりません。

obj: Javaオブジェクトは、NULLであってはなりません。

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インタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

name: 0で終了する修正UTF-8文字列内の静的フィールド名は、NULLであってはなりません。

sig: 0で終了する修正UTF-8文字列のフィールド・シグネチャは、NULLであってはなりません。

戻り値:

フィールド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インタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

fieldID: 有効な静的フィールド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インタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

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

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

staticメソッドの呼び出し

GetStaticMethodID

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

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

name: 0で終了する変更されたUTF-8文字列内の静的メソッド名は、NULLであってはなりません。

sig: 0で終了する修正UTF-8文字列のメソッド・シグネチャは、NULLであってはなりません。

戻り値:

メソッド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インタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

methodID: 有効な静的メソッドID。

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

staticメソッドの引数。

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

args: 引数の配列。

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

args: 引数のva_list。

戻り値:

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

例外:

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

文字列操作

この仕様では、JVMがJava文字列を内部的にどのように表現するかについては想定していません。 これらの操作から返される文字列:

• GetStringChars()
• GetStringUTFChars()
• GetStringRegion()
• GetStringUTFRegion()
• GetStringCritical()

したがって、NULLで終了する必要はありません。 プログラマは、GetStringLength()またはGetStringUTFLength()を介してバッファ容量要件を決定することが期待されます。

NewString

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

unicodeChars: Unicode文字列を参照するポインタ。 NULLの値にすることができます。この場合、lenは0にする必要があります。

len: Unicode文字列の長さ。 0の場合もあります。

戻り値:

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

例外:

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

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

string: Java文字列オブジェクトは、NULLであってはなりません。

戻り値:

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

GetStringChars

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

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

string: Java文字列オブジェクトは、NULLであってはなりません。

isCopy: ブール値へのポインタは、NULLの値になります。

戻り値:

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

ReleaseStringChars

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

string: Java文字列オブジェクトは、NULLであってはなりません。

chars: GetStringChars()によって以前に返されたUnicode文字列へのポインタ。

NewStringUTF

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

bytes: 変更されたUTF-8文字列へのポインタは、NULLであってはなりません。

戻り値:

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

例外:

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

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

string: Java文字列オブジェクトは、NULLであってはなりません。

戻り値:

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

GetStringUTFChars

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

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

string: Java文字列オブジェクトは、NULLであってはなりません。

isCopy: ブール値へのポインタは、NULLの値になります。

戻り値:

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

ReleaseStringUTFChars

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

string: Java文字列オブジェクトは、NULLであってはなりません。

utf: 以前はGetStringUTFChars()によって返された、変更された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にコピーします。

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

str: Java文字列オブジェクトは、NULLであってはなりません。

start: コピーする文字列の最初のUnicode文字のインデックス。 ゼロ以上で、文字列の長さが("GetStringLength()")より小さい値でなければなりません。

len: コピーするUnicode文字の数。 ゼロ以上でなければならず、"start + len"は文字列の長さ("GetStringLength()")より小さくなければなりません。

buf: 文字列領域をコピーするUnicode文字バッファ。 lenが0より大きい場合は、NULLであってはなりません。

例外:

StringIndexOutOfBoundsException: インデックス・オーバーフロー。

導入されたバージョン:

JDK/JRE 1.2

GetStringUTFRegion

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

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

len引数には、「ユニコード文字」の数を指定します。 結果の変更されたUTF-8エンコード文字は、指定されたlen引き数よりも大きい場合があります。 GetStringUTFLength()を使用して、必要な文字バッファの最大サイズを判断できます。

この仕様では、結果の文字列のコピーをNULLで終了する必要はないので、この関数を使用する前に、strlen()を安全に実行するために、指定された文字バッファ(e.g. "memset()")をクリアすることをお勧めします。

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

str: Java文字列オブジェクトは、NULLであってはなりません。

start: コピーする文字列の最初のUnicode文字のインデックス。 ゼロ以上で、文字列の長さより小さくなければなりません。

len: コピーするUnicode文字の数。 0より大きくなければならず、"start + len"は文字列長("GetStringLength()")より小さくなければなりません。

buf: 文字列領域をコピーするUnicode文字バッファ。 lenが0より大きい場合は、NULLであってはなりません。

例外:

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

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

リンケージ(ReleaseStingCritical):

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

関連項目:

GetStringChars

ReleaseStringChars

導入されたバージョン:

JDK/JRE 1.2

配列操作

GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列オブジェクトは、NULLであってはなりません。

戻り値:

配列の長さを返します。

NewObjectArray

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

length: 配列サイズは、> = 0でなければなりません。

elementClass: 配列要素クラスであり、NULLであってはなりません。

initialElement: 初期値は、NULLの値であってもよい。

戻り値:

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

例外:

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

GetObjectArrayElement

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列は、NULLであってはなりません。

index: 配列インデックスは、>= 0で配列長が("GetArrayLength()")より小さい配列でなければなりません。

戻り値:

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

例外:

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

SetObjectArrayElement

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列は、NULLであってはなりません。

index: 配列インデックスは、>= 0で配列長が("GetArrayLength()")より小さい配列でなければなりません。

value: 新しい値は、NULL値です。

例外:

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

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

New<PrimitiveType>Arrayルーチン

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

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

リンケージ:

JNIEnvインタフェース関数表のインデックス。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

length: 配列の長さは> = 0でなければなりません。

戻り値:

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

例外:

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

Get<PrimitiveType>ArrayElementsルーチン

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

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

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

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

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

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

リンケージ:

JNIEnvインタフェース関数表のインデックス。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列オブジェクトは、NULLであってはなりません。

isCopy: ブール値へのポインタは、NULLの値になります。

戻り値:

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

例外:

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

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は次の表に示されているような影響を及ぼします。

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

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

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

リンケージ:

JNIEnvインタフェース関数表のインデックス。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列オブジェクトは、NULLであってはなりません。

elems: 以前のGet<PrimitiveType>ArrayElements呼び出しによって返された配列要素へのポインタ。

mode: リリース・モード: 0、JNI_COMMITまたはJNI_ABORT。

Get<PrimitiveType>ArrayRegionルーチン

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

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

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

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

リンケージ:

JNIEnvインタフェース関数表のインデックス。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列は、NULLであってはなりません。

start: 開始インデックスは0以上で、配列の長さ(GetArrayLength())より小さくなければなりません。

len: コピーする要素の数はゼロ以上でなければならず、"start + len"は配列の長さ("GetArrayLength()")より小さくなければなりません。

buf: 宛先バッファは、NULLであってはなりません。

例外:

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

リンケージ:

JNIEnvインタフェース関数表のインデックス。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列は、NULLであってはなりません。

start: 開始インデックスは0以上で、配列の長さ(GetArrayLength())より小さくなければなりません。

len: コピーする要素の数はゼロ以上でなければならず、"start + len"は配列の長さ("GetArrayLength()")より小さくなければなりません。

buf: ソース・バッファは、NULLであってはなりません。

例外:

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は一時的にガベージ・コレクションを無効にすることがあります。

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。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列は、NULLであってはなりません。

isCopy: ブール値へのポインタは、NULLの値になります。

戻り値:

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

例外:

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

導入されたバージョン:

JDK/JRE 1.2

ReleasePrimitiveArrayCritical

リンケージ:

JNIEnvインタフェース関数表のリンケージ・インデックス223。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

array: Java配列は、NULLであってはなりません。

carray: GetPrimitiveArrayCriticalによって返されるクリティカルな配列ポインタ。

mode: リリース・モード(プリミティブ配列のリリース・モードを参照してください): 0、JNI_COMMITまたはJNI_ABORT。 carrayがコピーでない場合は無視されます。

導入されたバージョン:

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インタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

methods: クラスのネイティブ・メソッドは、NULLであってはなりません。

nMethods: クラス内のネイティブ・メソッドの数はゼロより大きくなければなりません。

戻り値:

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

例外:

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

UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

clazz: Javaクラス・オブジェクトは、NULLであってはなりません。

戻り値:

成功すると"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インタフェース・ポインタは、NULLであってはなりません。

obj: 通常のJavaオブジェクトまたはクラス・オブジェクトは、NULLであってはなりません。

戻り値:

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

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

obj: 通常のJavaオブジェクトまたはクラス・オブジェクトは、NULLであってはなりません。

戻り値:

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

例外:

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

NIOのサポート

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

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

• 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: JNIインタフェース・ポインタは、NULLであってはなりません。

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: JNIインタフェース・ポインタは、NULLであってはなりません。

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: JNIインタフェース・ポインタは、NULLであってはなりません。

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。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

method: java.lang.reflect.Methodまたはjava.lang.reflect.Constructorオブジェクトは、NULLであってはなりません。

戻り値:

指定されたJavaリフレクション・メソッドに対応するJNIメソッドID。操作が失敗した場合はNULL。

導入されたバージョン:

JDK/JRE 1.2

FromReflectedField

jfieldID FromReflectedField(JNIEnv *env, jobject field);

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

field: java.lang.reflect.Fieldオブジェクトは、NULLであってはなりません。

戻り値:

指定されたJavaリフレクションfieldに対応するJNIフィールドID、または操作が失敗した場合はNULL。

導入されたバージョン:

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。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

cls: Javaクラス・オブジェクトは、NULLであってはなりません。

methodID: メソッドIDは、NULLであってはなりません。

isStatic: 指定されたmethodIDが静的メソッドであるかどうかを示します。

戻り値:

指定されたmethodIDに対応するjava.lang.reflect.Methodまたはjava.lang.reflect.Constructorのインスタンス、または操作が失敗した場合はNULLのインスタンスを返します。

導入されたバージョン:

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。

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

cls: Javaクラス・オブジェクトは、NULLであってはなりません。

fieldID: フィールドIDは、NULLであってはなりません。

isStatic: 指定されたfieldIDが静的フィールドであるかどうかを示します。

戻り値:

与えられたfieldIDに対応するjava.lang.reflect.Fieldのインスタンス、または操作が失敗した場合はNULLを返します。

導入されたバージョン:

JDK/JRE 1.2

Java VMインタフェース

GetJavaVM

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

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

リンケージ:

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

パラメータ:

env: JNIインタフェース・ポインタは、NULLであってはなりません。

vm: 結果を配置する場所へのポインタは、NULLであってはなりません。

戻り値:

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

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