Java

バージョン 1.4 の JavaTM 2 SDK
で導入された JNI の拡張機能

JNI ドキュメント

JNI バージョン 1.4 では、JNI 呼び出しインタフェースの新しいエントリポイントのほか、java.nio パッケージのサポートが追加されました。また、JNI バージョン番号が上がったことに伴って JNI_OnLoad の解説が更新されました。

新しい呼び出しインタフェースルーチンによって、ネイティブコードが Java 仮想マシン (JVM) に「デーモン」スレッドを接続できます。これは、このスレッドがシャットダウン時に終了するのを JVM が待つべきではない場合に便利です。

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

3 つの新しい関数によって、直接バッファを JNI コードで作成、検査、および操作することができます。

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


バージョン番号の上昇

JNI のバージョン番号が上がりました。インクルードファイル jni.h では、新しい定数を定義しています。

    #define JNI_VERSION_1_4 0x00010004

GetVersion プロシージャは現在この値を返し、JNI_OnLoad プロシージャの仕様が改訂されています。

    jint JNI_OnLoad(JavaVM *vm, void *reserved);

      ネイティブライブラリがロードされると (たとえば System.loadLibrary を介して)、VM は JNI_OnLoad を呼び出します。
      JNI_OnLoad は、
      ネイティブライブラリが必要とする JNI を返さなければなりません。

      JDK 1.1 で利用できる関数に加え、J2SE 1.2で導入された JNI 関数を使用するには、
      ネイティブライブラリは 
      JNI_VERSION_1_2 を返す JNI_OnLoad 関数をエクスポートする必要があります。

      J2SE リリース 1.2 で利用できる関数に加え、J2SE リリース1.4で導入された JNI 関数を使用するには、
      ネイティブライブラリは 
      JNI_VERSION_1_4 を返す JNI_OnLoad 関数をエクスポートする必要があります。

      ネイティブライブラリが JNI_OnLoad 関数をエクスポートしないと、VM は
      ライブラリが JNI バージョン JNI_VERSION_1_1 のみを必要としていると見なします。
      VM が JNI_OnLoad で返されるバージョン番号を認識しないと、
      ネイティブライブラリをロードできません。

JNI 呼び出しインタフェースへの追加

AttachCurrentThreadAsDaemon

jint AttachCurrentThreadAsDaemon(JavaVM* vm, void** penv, void* args);

AttachCurrentThread とセマンティクスは同じですが、新しく作成されれた java.lang.Thread インスタンスは「デーモン」です。

スレッドがすでに AttachCurrentThread または AttachCurrentThreadAsDaemon を介して接続されている場合、このルーチンは penv でポイントされている値を現在のスレッドの JNIEnv に設定します。この場合、AttachCurrentThread もこのルーチンも、スレッドの「デーモン」に影響しません。

リンケージ

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

パラメータ

vm: 現在のスレッドが接続される仮想マシンインスタンス

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

args: JavaVMAttachArgs 構造体へのポインタ

戻り値

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

例外

なし


JNI インタフェースへの追加

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 オブジェクトの割り当てに失敗した場合


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


GetDirectBufferCapacity

jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);

指定された直接バッファ java.nio.Buffer に参照されるメモリ領域のバイト数で示したサイズをフェッチし、返します。

リンケージ

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

パラメータ

env: JNIEnv のインタフェースポインタ

buf: 直接バッファ java.nio.Buffer オブジェクト (null は不可)

戻り値

バッファに関連付けられたメモリ領域のサイズをバイト数で返します。指定されたオブジェクトが直接バッファの java.nio.Buffer オブジェクトでない場合、または、直接バッファへの JNI のアクセスがこの仮想マシンでサポートされていない場合は、-1 を返します。


Copyright © 2001 Sun Microsystems, Inc.All Rights Reserved.

コメントの送付先: jni@java.sun.com
Sun