Java Native Interface (JNI) は、Javaプラットフォームにおいて、Javaで記述されたプログラムと、他のプログラミング言語(たとえばCやC++など)で書かれた、実際のCPU上で動作するコード(ネイティブコード)とを連携するためのインタフェース仕様である。Java言語からネイティブコードを利用するためのABIと、逆にネイティブコードからJavaバイトコードを動作させるためにバーチャルマシン (VM) を利用するためのAPIの2つから成る。

JNIを使うことで、Java言語のVMで動作させるには処理速度の面で不利とされる計算量の多いプログラムを部分的にネイティブコードに置き換えて高速化したり、標準Javaクラスライブラリからはアクセスできないオペレーティングシステムあるいはハードウェアの機能を利用するプログラムを、あたかも通常のJavaクラスのメソッドのように呼び出したりできるようになる。逆に、Javaクラスライブラリによって実装されている高水準の機能を、C/C++などで書かれた下位層から利用することもできるようになる。JNIはJava言語以外のJava VM上で動作する言語 (AltJava) からも利用可能である。

JNIによる、Java VMからのネイティブコードの呼び出しは、VMの実行環境の一貫性を保つために、通常のJavaプログラムの実行時とは異なる例外的なメモリ管理や排他制御を必要とする場合があり、しばしばプログラムの実行速度の低下を招くことがある。そのため、単純にJNIを利用することで必ずしもアプリケーション性能を改善できるというわけではない。また、ネイティブコードを含むバイナリはプロセッサアーキテクチャやオペレーティングシステムに依存してしまうことになるため、Javaのみで記述されたプログラムと比べて再利用や再配布の面で難がある。

JDK 1.0ではJNIの前身となるNative Method Interface (NMI) が実装されていたが、ネイティブコードとJavaコードとが明確に分離されていなかった。JDK 1.1でJNIが実装され、NMIはJNIで置き換えられた。

## Javaからのネイティブコード呼び出し

以下ではC/C++言語によるネイティブコードの記述例を用いて説明する。なおJNI関連のシンボル定義や関数宣言を含むヘッダーファイルは、Java Development Kit (JDK) に付属している。

JNIフレームワークでは、ネイティブ関数はC/C++のソースファイル (拡張子は.cもしくは.cppなど) に分離して実装する。Java VMは、`JNIEnv`へのポインタ、コンテキストとしてJavaクラスもしくはクラスインスタンスを間接参照するポインタである`jobject`、そしてJavaメソッドで定義されたすべてのJava引数を通して、ネイティブな関数を起動する。JNI関数は以下のようなC言語形式関数となる。C++のシグネチャは使えない。

`JNIEnv`はJava VMへのインタフェースを含む構造体`JNINativeInterface`へのポインタである。これはJava VMとの相互作用および、Javaオブジェクトとの連携に必要な全ての関数ポインタを含んでいる。JNI関数の例としては、ネイティブ配列とJava配列の相互変換、ネイティブ文字列とJava文字列の相互変換、オブジェクトのインスタンス化、例外の送出などが挙げられる。基本的には、Javaコードでできることは全て`JNIEnv`を用いて行うことができる。

以下の例ではJava文字列をネイティブな文字列に変換し、C/C++の標準ライブラリを利用して標準出力に出力する。

上記のようにしてCまたはC++で記述した関数が myjni ライブラリモジュールに実装されていると仮定し、Javaプログラムから呼び出す例を示す。C/C++側の実装関数とJava側のメソッドバインディングは実行時に動的に解決される。

オブジェクト指向言語であるC++に対しては、Cよりも多少洗練されたJNI APIが提供される。C++ではJavaのように、オブジェクトのメソッド(メンバー関数)という概念と、メソッド呼び出しのセマンティクス(意味)を表現するシンタックス(構文)を持つため、C++のJNIコードはCのそれに比べて構文的に多少簡潔である。

Cでは`env`パラメータは`(*env)->`でデリファレンスされ、さらに`env`パラメータは明示的に`JNIEnv`のメソッドに渡されなければならない。

C++では`env`パラメータは`env->`でデリファレンスされるが、`env`パラメータはオブジェクトのメソッド呼び出しセマンティクスの一部として暗黙的に渡される。

以降のコード例では、断りがない限りC++を前提とするものとする。

## データ型のマッピング

一部のネイティブデータ型とJavaデータ型はそれぞれ相互変換をすることができる。オブジェクトや配列、文字列などの合成型のために、ネイティブコードは`JNIEnv`のメソッド呼び出しにおいて、明示的なデータの変換を行う必要がある。

以下の表ではJavaとネイティブ間のデータ型のマッピングを示す。C/C++の型は<jni.h>ヘッダーにてtypedefにより定義されたエイリアスであり、実装は処理系依存である。

| C/C++データ型 | Javaデータ型 | 説明 | 型シグネチャ |
| --- | --- | --- | --- |
| jboolean | boolean | 符号無し8ビット整数型(論理型) | Z |
| jbyte | byte | 符号付き8ビット整数型 | B |
| jchar | char | 符号無し16ビット整数型(文字型) | C |
| jshort | short | 符号付き16ビット整数型 | S |
| jint | int | 符号付き32ビット整数型 | I |
| jlong | long | 符号付き64ビット整数型 | J |
| jfloat | float | 32ビット単精度浮動小数点数 | F |
| jdouble | double | 64ビット倍精度浮動小数点数 | D |
| void | void | `java.lang.Void` | V |
| jobject | Object | `java.lang.Object`インスタンス | Ljava/lang/Object; |
| jstring | String | `java.lang.String`インスタンス | Ljava/lang/String; |
| jthrowable | Throwable | `java.lang.Throwable`インスタンス | Ljava/lang/Throwable; |
| jclass | Class | `java.lang.Class`インスタンス | Ljava/lang/Class; |

JNIでJavaの型を識別する概念として、「型シグネチャ」が定義されている。

"L fully-qualified-class ;"というシグネチャは名前によって一意に識別されるJavaクラスを意味する。
例えば文字列`"Ljava/lang/String;"`はクラス`java.lang.String`を意味する。また、接頭辞`[`はその型の配列を意味する。例えば、`[I`はJavaにおける`int`型の配列すなわち`int[]`に相当する。

表中の対応する型同士は暗黙的に相互変換可能である。実際の変換はJNIレイヤーが担う。プログラマーは型キャスト無しで、Javaの`int`型と同様に`jint`を使用することができる。`jint`型からJavaの`int`型への変換も同様である。

なお、`jstring`はJavaの`String`型への間接参照であり、C/C++のポインタ型`char*`とは無関係である。

このことはJava配列についても同様である。例えば`jintArray`はJavaの`int[]`型への間接参照であり、C/C++のポインタ型`int*`とは無関係である。

配列の全ての要素の合計を得る例を用いて以下に示す。

Javaの`null`はC/C++の`NULL`ポインタにマッピングされる。

`String`型インスタンスや`Class`型インスタンスなどのJavaオブジェクト参照を`Object`型変数に代入可能であるように、`jstring`や`jclass`などの「JNIオブジェクト参照」もまた`jobject`型変数に代入可能である。

なお、Javaの文字型および文字列型の内部表現はUTF-16であり、`jstring`に対してGetStringChars()関数を使用することで、UTF-16形式の文字列バッファへのポインタ`jchar*`を得ることができる(ただしゼロ終端ではなく、文字列の長さは別途GetStringLength()関数で取得する)。バッファへのポインタが不要になった場合はReleaseStringChars()関数で解放する必要がある。また、NewString()関数を用いることで、UTF-16バッファから`jstring`を生成することができる。`jchar`はUTF-16を表現できるデータ型であることが保証されるため、C++11で追加された`char16_t`など、UTF-16用データ型との相互変換が可能である。

## JNIEnv

JNIのAPI関数の多くはJava VM環境変数として、JNIEnvへのポインタを受け取る。

しかしながら、Javaからnativeメソッドを呼び出す際に、C/C++実装側の関数に第1引数として渡ってくるJNIEnvは、そのnativeメソッド呼び出しの間のみ有効となる。つまりスタックフレームの制御フローがJava側に戻ると無効になる。

またJNIEnvはスレッド間で共有できない。そのため、Java VMに関連付けられていないC/C++スレッド上でJNIEnvを取得するためには、以下のようにAttachCurrentThread()関数を使用してスレッドをVMにアタッチする必要がある。スレッドでJNIEnvが必要なくなったとき、あるいはスレッドを終了する際にDetachCurrentThread()関数を使用してスレッドをVMからデタッチする。

すでにJava VMに関連付けられているC/C++スレッド上でJNIEnvを取得するためには、GetEnv()関数を呼び出すだけでよい。

## Javaクラスへのアクセス

JNIを経由することで、C/C++からJavaのクラスを利用することもできる。

C/C++からJNI関数を用いてJavaクラスをインスタンス化したり、メソッドを呼び出したり、フィールドを読み書きしたりするためには、まずJavaクラス (`jclass`) およびメソッドID (`jmethodID`) あるいはフィールドID (`jfieldID`) を探索・取得する必要があるが、その際に前述の「型シグネチャ」の文字列が識別子として使用される。

以下は`java.lang.Math`クラスの静的フィールドを取得し、静的メソッドを呼び出す例である。

FindClass()関数で取得した`jclass`はJavaクラスへのJNIオブジェクト参照である。クラス、フィールド、メソッドの型シグネチャをもとに、リフレクションの要領でC/C++からアクセスすることができる。クラス、フィールド、メソッドを繰り返し利用する場合は、探索にかかる時間を節約するためにキャッシュしておく。

## ローカル参照とグローバル参照

特に断りがない限り、JNIのAPI関数が返却するJNIオブジェクト参照は、Javaオブジェクトへの「ローカル参照」を表すポインタである。これはJavaの参照型ローカル変数に相当する。ローカル参照はスタックフレームの制御フローがJava側に返る際に自動的に削除され、Javaオブジェクトはガベージコレクションの管理対象となるが、DeleteLocalRef()関数を使って手動で削除することもできる。

JNIオブジェクト参照を長期間保持する場合は、「グローバル参照」を使わなければならない。

具体的には、C/C++側の静的変数(グローバル変数)などのヒープ領域に`jobject`を格納する場合や、スレッド間で`jobject`を共有する場合に、ローカル参照ではなくグローバル参照を用いる。NewGlobalRef()関数を呼び出すことで、ローカル参照からグローバル参照を生成することができる。

Javaのスレッドから呼ばれたC関数内でローカル参照を作成した場合、スタックフレームの制御フローがJava側に戻った時点でローカル参照は自動解放される。また、C/C++のスレッド上でローカル参照を作成した場合、スレッドがJVMからデタッチされた時点でローカル参照は自動解放される。一方、グローバル参照は自動解放されず、DeleteGlobalRef()関数で明示的に削除する必要がある。

グローバル参照はヒープメモリが許す限り自由に作成可能だが、ローカル参照の同時利用可能個数には上限がある。JNI仕様で保証されているのは少なくとも16個ということだけであり、JVMのスタック容量に依存する。

JNI参照はJavaのヒープに対する直接のポインタではなく、メモリコンパクションによるJavaオブジェクトのアドレス移動の影響を受けない。2つのJNI参照が同じJavaオブジェクトを参照しているかどうかを調べるには、IsSameObject()関数を使用する。

JNIのローカル参照またはグローバル参照が残っている間は、参照先のJavaオブジェクトはGCルートから到達可能であり、ガベージコレクションの対象とはならないため、これらを削除し忘れるとメモリリークしてしまう。