JNI に関するヒント

JNI（Java Native Interface）では、マネージコード（Java または Kotlin プログラミング言語で記述されたコード）からコンパイルするバイトコードが、C / C++ で記述された Android のネイティブコードと連携するためのインターフェース仕様が定義されています。JNI はベンダーに依存せず、動的な共有ライブラリからコードをロードすることができます。場合によっては、扱いにくいこともありますが、かなり効率的です。

注: Android は Kotlin を Java プログラミング言語と同様の方法で ART 対応のバイトコードにコンパイルします。そのため、このページで紹介している JNI アーキテクチャおよび関連コストに関するガイダンスは、Kotlin および Java プログラミング言語の両方に適用できます。詳細については、Kotlin と Android に関する説明をご覧ください。

まだ JNI に慣れ親しんでいない方は、JNI の仕組みや利用できる機能について、まず、Java Native Interface 仕様をご覧ください。仕様を一読しただけではわかりにくい要素もあるため、以下で説明する実践的なヒントをご活用ください。

グローバル JNI 参照を閲覧し、それらが生成され削除される位置を確認するには、Android Studio 3.2 以降で、Memory Profiler の [JNI heap] ビューを使用します。

一般的なヒント

JNI レイヤのフットプリントは最小限に抑えるようにします。その際、いくつかの点について考慮する必要があります。JNI ソリューションで、以下のガイドラインに準拠するようにしてください（以下のヒントは、重要度の高い順に記載されています）。

JNI レイヤ全体でリソースのマーシャリングを最小限に抑える。JNI レイヤ全体でのマーシャリングにかかるコストは少なくありません。インターフェースを設計する際は、マーシャリングの必要があるデータの量と、データをマーシャリングする頻度を最小限に抑えるようにしてください。
可能な限り、マネージプログラミング言語で記述したコードと C++ で記述したコードとの間で非同期通信を行わないようにする。これにより、JNI インターフェースの管理が容易になります。一般に、非同期アップデートを UI と同じ言語に維持することで、非同期 UI アップデートをシンプルにすることができます。たとえば、Java コード内の UI スレッドから JNI 経由で C++ 関数を呼び出すよりも、2 つのスレッド間のコールバックを Java プログラミング言語で行い、1 つのスレッドで C++ のブロッキング呼び出しを実行してから、その呼び出しが終了した時点で UI スレッドに通知するほうが良いでしょう。
JNI とやりとりする必要があるスレッドの数を最小限に抑える。Java 言語と C++ 言語の両方でスレッドプールを利用する必要がある場合、JNI 通信はプールオーナー間だけで行うようにし、個々のワーカースレッド間では行わないようにしてください。
インターフェースのコードを、見つけやすいように C++ と Java のソースコードのなるべく上の方に配置すると、将来のリファクタリングが容易になる。必要に応じて、JNI 自動生成ライブラリを使用することをおすすめします。

JavaVM と JNIEnv

JNI では 2 つの主要なデータ構造（「JavaVM」と「JNIEnv」）が定義されています。基本的に、これらはどちらも関数テーブルへのポインタのポインタです（C++ バージョンでは、関数テーブルへのポインタと、テーブルを介して間接的に呼び出される各 JNI 関数のメンバー関数へのポインタを持つクラスです）。JavaVM の「Invocation（呼び出し）インターフェース」関数を使用すると、JavaVM の作成と破棄を行うことができます。理論上は、各プロセスで複数の JavaVM を設定できますが、Android で設定できるのは 1 つだけです。

JNIEnv はほとんどの JNI 関数を提供します。ネイティブ関数はすべて、最初の引数として JNIEnv を受け取ります。

JNIEnv は、スレッドローカルストレージ用です。そのため、スレッド間で JNIEnv を共有することはできません。コードが JNIEnv を取得する方法がほかになければ、JavaVM を共有し、GetEnv を使用してスレッドの JNIEnv を検出するようにしてください（JNIEnv を取得する方法がほかにある場合は、下記の AttachCurrentThread をご覧ください）。

JNIEnv と JavaVM の宣言方法は、C 言語の場合と C++ 言語の場合で異なります。"jni.h" インクルードファイルは、C と C++ のいずれにインクルードするのかに応じて typedef が異なります。そのため、両方の言語でインクルードされるヘッダーファイル内に JNIEnv 引数を含めることはおすすめしません（つまり、ヘッダーファイルに #ifdef __cplusplus が必要で、そのヘッダーに JNIEnv を参照するものが 1 つでもあれば、おそらく追加の作業が必要になるでしょう）。

スレッド

すべてのスレッドは、カーネルによってスケジュール設定される Linux スレッドです。スレッドは通常、Thread.start() を使用してマネージコードから開始されますが、他の場所で作成して JavaVM にアタッチすることも可能です。たとえば、pthread_create() や std::thread を使用して開始したスレッドを、AttachCurrentThread() 関数や AttachCurrentThreadAsDaemon() 関数を使用してアタッチすることができます。スレッドがアタッチされるまで、JNIEnv がないため、JNI 呼び出しを行うことはできません。

通常は、Thread.start() を使用して、Java コードに呼び出す必要のあるスレッドを作成することをおすすめします。そうすることで、十分なスタック領域を確保し、正しい ThreadGroup 内に位置し、Java コードと同じ ClassLoader を使用できるようになります。また、デバッグしやすいようにスレッド名を設定する場合も、ネイティブコードからより Java で設定する方が簡単です（pthread_t または thread_t を使用している場合は pthread_setname_np() をご覧ください。std::thread を使用していて、pthread_t を必要とする場合は std::thread::native_handle() をご覧ください）。

ネイティブに作成されたスレッドをアタッチすると、java.lang.Thread オブジェクトが作成されて「メイン」の ThreadGroup に追加され、デバッガから認識できるようになります。すでにアタッチされているスレッドに対して AttachCurrentThread() を呼び出しても、何の処理も行われません（no-op）。

Android は、ネイティブコードを実行しているスレッドを停止しません。ガベージコレクションが進行中の場合や、デバッガが停止リクエストを発行した場合、Android は、次回 JNI を呼び出したときにスレッドを一時停止します。

JNI 経由でアタッチされたスレッドは、終了する前に DetachCurrentThread() を呼び出す必要があります。これを直接コーディングするのが難しい場合、Android 2.0（Eclair）以降では、pthread_key_create() を使用して、スレッドが終了する前に呼び出されるデストラクタ関数を定義し、そこから DetachCurrentThread() を呼び出すことができます（作成したキーを pthread_setspecific() で使用して、JNIEnv をスレッドローカルストレージに保存します。これにより、JNIEnv が引数としてデストラクタに渡されます）。

jclass、jmethodID、jfieldID

ネイティブコードからオブジェクトのフィールドにアクセスする場合は、以下のように行います。

FindClass で、クラスのクラスオブジェクト参照を取得します。
GetFieldID で、フィールドのフィールド ID を取得します。
適切な方法（GetIntField など）で、フィールドのコンテンツを取得します。

同様に、メソッドを呼び出すには、クラスオブジェクト参照を取得して、メソッド ID を取得します。ID は、内部のランタイムデータ構造体への単なるポインタであることがほとんどです。ID を調べるために文字列の比較を数回行わなければならないこともありますが、いったん ID を取得すると、実際のフィールドの取得やメソッドの呼び出しを非常にすばやく行えるようになります。

パフォーマンスが重要な場合は、値を 1 回調べてその結果をネイティブコード内にキャッシュすることをおすすめします。プロセスごとに 1 つの JavaVM という制限があるため、このデータは静的なローカル構造体に保存するのが妥当でしょう。

クラス参照、フィールド ID、メソッド ID は、クラスがアンロードされるまで有効であることが保証されます。クラスがアンロードされるのは、クラスローダーに関連付けられているすべてのクラスに対してガベージコレクションが可能な場合に限られます。この状況は Android ではまれにしか起こりませんが、あり得ないことではありません。ただし、jclass はクラス参照であるため、NewGlobalRef 呼び出しを使用して保護する必要があります（次のセクションを参照）。

クラスのロード時に ID がキャッシュされ、そのクラスがアンロードされ再度ロードされたときにも自動的に再度キャッシュされるようにするには、ID の正しい初期化方法として、該当するクラスに次のようなコードを追加してください。

Kotlin

    companion object {
        /*
         * We use a static class initializer to allow the native code to cache some
         * field offsets. This native function looks up and caches interesting
         * class/field/method IDs. Throws on failure.
         */
        private external fun nativeInit()

        init {
            nativeInit()
        }
    }

Java

        /*
         * We use a class initializer to allow the native code to cache some
         * field offsets. This native function looks up and caches interesting
         * class/field/method IDs. Throws on failure.
         */
        private static native void nativeInit();

        static {
            nativeInit();
        }

C / C++ コード内に ID のルックアップを実行する nativeClassInit メソッドを作成します。このコードは、クラスの初期化時に 1 回実行されます。クラスのアンロードと再ロードが行われると再び実行されます。

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

ネイティブメソッドに渡されるすべての引数と、JNI 関数から返されるほぼすべてのオブジェクトは、「ローカル参照」です。つまり、その有効期間は、現在のスレッド内で現在のネイティブメソッドが存在する間に限られます。ネイティブメソッドが終了して戻った後は、オブジェクト自体がそのまま残っていても、参照は無効になります。

これは、jobject のすべてのサブクラス（jclass、jstring、jarray など）に適用されます（拡張 JNI チェックが有効な場合、参照の誤用のほとんどがランタイムによって警告されます）。

非ローカル参照を取得するには、NewGlobalRef 関数と NewWeakGlobalRef 関数を使用する必要があります。

参照を長く保持したい場合は、「グローバル」参照を使用する必要があります。NewGlobalRef 関数は、ローカル参照を引数として受け取り、グローバル参照を返します。グローバル参照は、DeleteGlobalRef を呼び出すまで有効であることが保証されます。

このパターンは、FindClass から返された jclass をキャッシュする場合によく使用されます。たとえば、次のようになります。

jclass localClass = env->FindClass("MyClass");
    jclass globalClass = reinterpret_cast<jclass>(env->NewGlobalRef(localClass));

すべての JNI メソッドは、ローカル参照とグローバル参照の両方を引数として使用できます。同じオブジェクトへの参照が異なる値を持つことも可能です。たとえば、同じオブジェクトに対して NewGlobalRef を連続して呼び出した場合に、戻り値が異なることがあります。2 つの参照が同じオブジェクトを参照しているかどうかを確認するには、IsSameObject 関数を使用する必要があります。ネイティブコード内で == を使用して参照を比較しないでください。

重要なのは、ネイティブコード内ではオブジェクト参照が不変や一意であると想定してはならないということです。オブジェクトを表す 32 ビット値は、同一メソッドであっても呼び出しごとに異なる可能性があります。また、2 つの異なるオブジェクトを連続して呼び出したときに、同じ 32 ビット値になることもあります。jobject の値をキーとして使用しないでください。

プログラマーは、ローカル参照を「過度に割り当てない」ようにする必要があります。たとえば、オブジェクトの配列を読み込むときなど、多数のローカル参照を作成する場合は、JNI に任せず DeleteLocalRef を使用して参照を手動で解放してください。実装では、16 個のローカル参照を作成するためにスロットを予約することしか要求されていないので、もっと必要な場合にはローカル参照を適宜削除するか、EnsureLocalCapacity / PushLocalFrame を使用してスロットを追加予約する必要があります。

なお、jfieldID と jmethodID はオブジェクト参照ではなく不透明型であるため、NewGlobalRef には渡さないようにしてください。また、GetStringUTFChars や GetByteArrayElements などの関数から返される生データへのポインタもオブジェクトではありません（生データへのポインタはスレッド間で渡すことが可能で、対応する Release 呼び出しが実行されるまで有効です）。

注意すべき特殊な状況について言及しておきます。AttachCurrentThread を使用してネイティブスレッドをアタッチした場合、実行中のコードは、スレッドがデタッチされるまでローカル参照を自動的に解放しません。作成したローカル参照はすべて、手動で削除する必要があります。一般に、ローカル参照をループで作成するネイティブコードでは、まず間違いなく手動による削除が必要になります。

グローバル参照は気を付けて使用してください。グローバル参照の使用を避けられないこともありますが、デバッグするのが難しく、メモリの（不正な）動作の診断が困難になることもあります。他の条件がすべて同じであれば、グローバル参照を少なくすることをおすすめします。

UTF-8 文字列と UTF-16 文字列

Java プログラミング言語は UTF-16 を使用します。利便性を考慮し、JNI には Modified UTF-8 でも動作するメソッドが用意されています。Modified UTF-8 エンコーディングは、\u0000 を 0x00 ではなく 0xc0 0x80 としてエンコードするため、C 言語コードで便利です。メリットは、C 言語スタイルのゼロ終端文字列を使用できることで、標準の libc 文字列関数で使用するのに適しています。デメリットは、JNI に渡した UTF-8 データがすべて正しく動作すると期待できない点です。

可能な場合、通常は UTF-16 文字列の方が高速に処理できます。Android では現在、GetStringChars ではコピーは不要ですが、GetStringUTFChars では割り当てと UTF-8 への変換が必要になります。なお、UTF-16 文字列はゼロ終端ではありません。\u0000 が許可されるため、文字列長と jchar ポインタを保持する必要があります。

Get で取得した文字列は、必ず Release で解放するようにしてください。文字列関数は jchar* または jbyte* を返します。いずれも、ローカル参照ではなく、プリミティブデータをポイントする C 言語スタイルのポインタです。そのため、Release が呼び出されるまで有効であることが保証されます。つまり、ネイティブメソッドが終了して戻った後も自動的に解放されることはありません。

NewStringUTF に渡すデータは Modified UTF-8 形式にする必要があります。よくあるミスとして、ファイルやネットワークストリームから文字データを読み取った後、フィルタリングすることなく NewStringUTF に渡す、といったことがあります。データが有効な MUTF-8（あるいは、互換サブセットである 7 ビット ASCII）であることが判明している場合を除き、無効な文字を削除したり、適切な Modified UTF-8 形式に変換したりする必要があります。そうしないと、UTF-16 変換が予期しない結果をもたらす可能性があります。CheckJNI（エミュレータではデフォルトで有効になっています）は、文字列をスキャンし、無効な入力を受け取ると VM を中断します。

プリミティブ配列

JNI には、配列オブジェクトのコンテンツにアクセスするための関数が用意されています。オブジェクト配列の場合、一度に 1 つずつ、エントリにアクセスする必要があるのに対し、プリミティブ配列の場合、C 言語で宣言されているかのように直接読み取りと書き込みを行うことができます。

VM 実装に制約を加えることなく、インターフェースの効率性を可能な限り高めるため、Get<PrimitiveType>ArrayElements ファミリーの呼び出しでは、ランタイムに、実際の要素へのポインタを返させるか、メモリを割り当ててコピーを作成させるかのいずれかを許可します。どちらの場合でも、返された生データへのポインタは、対応する Release 呼び出しが発行されるまで有効であることが保証されます（つまり、データがコピーされなかった場合、配列オブジェクトは固定され、ヒープのコンパクト化の一環として再配置することができなくなります）。Get で取得した配列は、必ず Release で解放する必要があります。また、Get 呼び出しが失敗した場合でも、コードが後で Release によって null ポインタを解放しないようにする必要があります。

isCopy 引数に非 null ポインタを渡すことにより、データがコピーされたかどうかを判断できます。ただし、これが役に立つことはほとんどありません。

Release 呼び出しは、mode 引数を受け取ります。この引数には、以下の 3 つの値のいずれかを指定できます。ランタイムが実行するアクションは、実際のデータへのポインタが返された場合と、データのコピーが返された場合で異なります。

0
- ポインタ: 配列オブジェクトの固定が解除されます。
- コピー: データがコピーバックされます。コピーを格納していたバッファが解放されます。
JNI_COMMIT
- ポインタ: 何も行われません。
- コピー: データがコピーバックされます。コピーを格納していたバッファは解放されません。
JNI_ABORT
- ポインタ: 配列オブジェクトの固定が解除されます。それまでの書き込みは中止されません。
- コピー: コピーを格納していたバッファが解放されます。コピーに対する変更はすべて失われます。

isCopy フラグをチェックする理由の 1 つは、配列に変更を加えた後に JNI_COMMIT を指定して Release を呼び出す必要があるかどうかを確認することです。配列の変更と、配列のコンテンツを使用するコードの実行を交互に行う場合、no-op（何もしない）コミットをスキップできる場合があります。このフラグをチェックする理由としてもう 1 つ考えられるのは、JNI_ABORT の処理を効率化するということです。たとえば、配列を取得してそこで変更を加え、その断片を他の関数に渡した後、変更を破棄したくなる場合があります。JNI が新しいコピーを作成することがわかっていれば、「編集可能」なコピーをもう 1 つ作成する必要はなく、JNI からオリジナルが渡されるなら、独自のコピーを作成する必要があります。

「*isCopy が false であれば Release 呼び出しをスキップできる」と考えるのは、よくあるミスです（サンプルコードでたびたび見られます）。これは誤りです。コピーバッファが割り当てられていない場合、オリジナルのメモリは固定され、ガベージコレクタによって移動することはできません。

また、JNI_COMMIT フラグを指定しても配列は解放されないため、最終的には別のフラグを指定して Release を再度呼び出す必要があります。

配列領域（Region）の呼び出し

データをコピーするだけの場合は、Get<Type>ArrayElements や GetStringChars などに代わる非常に便利な方法があります。次のようなコードがあるとします。

    jbyte* data = env->GetByteArrayElements(array, NULL);
        if (data != NULL) {
            memcpy(buffer, data, len);
            env->ReleaseByteArrayElements(array, data, JNI_ABORT);
        }

このコードは、配列を取得し、その配列から最初の len バイトの要素をコピーして、配列を解放します。Get 呼び出しは、実装に応じて、配列のコンテンツを固定するかコピーします。このコードは、データのコピー（おそらく 2 回目）を行ってから Release を呼び出しています。ここでは、JNI_ABORT を指定することで、3 回目のコピーが行われないようにしています。

次のコードなら同じ処理をもっと簡単に達成できます。

    env->GetByteArrayRegion(array, 0, len, buffer);

この方法には次のようなメリットがあります。

JNI 呼び出しが 2 回ではなく 1 回で済むため、オーバーヘッドを削減できます。
配列要素を固定したり複数回コピーしたりする必要がありません。
プログラミングエラーによるリスクを軽減できます。問題が発生した後に Release を呼び出し忘れた場合のリスクが存在しないからです。

同様に、Set<Type>ArrayRegion 呼び出しを使用すると、データを配列にコピーすることができ、GetStringRegion または GetStringUTFRegion を使用すると、String から文字をコピーすることができます。

例外

例外の保留中は、ほとんどの JNI 関数を呼び出すことができません。コード内で関数の戻り値や ExceptionCheck、ExceptionOccurred から例外を認識して戻るか、例外をクリアして処理する必要があります。

例外の保留中に呼び出すことができる JNI 関数は以下に限られます。

DeleteGlobalRef
DeleteLocalRef
DeleteWeakGlobalRef
ExceptionCheck
ExceptionClear
ExceptionDescribe
ExceptionOccurred
MonitorExit
PopLocalFrame
PushLocalFrame
Release<PrimitiveType>ArrayElements
ReleasePrimitiveArrayCritical
ReleaseStringChars
ReleaseStringCritical
ReleaseStringUTFChars

JNI 呼び出しの多くは例外をスローできますが、多くの場合、もっと簡単にエラーをチェックする方法が用意されています。たとえば、NewString から null 以外の値が返された場合、例外をチェックする必要はありません。ただし、CallObjectMethod などの関数を使用してメソッドを呼び出した場合は、例外がスローされると戻り値が有効にならないため、例外をチェックする必要があります。

解釈されたコードから例外がスローされても、ネイティブスタックフレームは巻き戻されません。また、Android は現在のところ、C++ 例外をサポートしていません。JNI の Throw 命令と ThrowNew 命令は、現在のスレッド内で例外ポインタを設定するだけです。ネイティブコードからマネージコードに戻り次第、例外が認識され適切に処理されます。

ネイティブコードは、ExceptionCheck または ExceptionOccurred を呼び出すことによって例外を「キャッチ」し、ExceptionClear を使用して例外をクリアすることができます。従来どおり、例外を処理せずに破棄すると、問題が発生することがあります。

Throwable オブジェクト自体を操作するための組み込み関数はないため、たとえば、Throwable クラスを見つけるのに必要な例外文字列を取得したい場合は、getMessage "()Ljava/lang/String;" のメソッド ID をルックアップして呼び出します。この結果が null 以外の場合は、GetStringUTFChars を使用して、printf(3) や同等の関数に渡すことができる文字列を取得します。

拡張チェック機能

JNI ではエラーのチェックをほとんど行いません。エラーはたいてい、クラッシュを引き起こします。Android には CheckJNI と呼ばれるモードも用意されています。このモードでは、標準の実装を呼び出す前に、JavaVM および JNIEnv 関数テーブルポインタが、一連の拡張されたチェックを実行する関数テーブルに切り替えられます。

追加されたチェックには以下のものがあります。

配列: 負のサイズの配列を割り当てようとしている。
不正なポインタ: 不正な jarray、jclass、jobject、jstring を JNI 呼び出しに渡している、または、NULL 非許容の引数で NULL ポインタを JNI 呼び出しに渡している。
クラス名: 「java/lang/String」スタイルのクラス名以外を JNI 呼び出しに渡している。
クリティカルな呼び出し: 「クリティカル」な Get とそれに対応する Release との間で JNI 呼び出しを行っている。
直接バイトバッファ: 正しくない引数を NewDirectByteBuffer に渡している。
例外: 保留中の例外があるときに JNI 呼び出しを行っている。
JNIEnv*: 不適切なスレッドから JNIEnv* を使用している。
jfieldID: null の jfieldID を使用している。jfieldID を使用してフィールドに不適切な型の値を設定している（たとえば、文字列フィールドに StringBuilder を割り当てようとしている）。静的フィールド用の jfieldID を使用して、インスタンスフィールドを設定している（あるいはその逆）。あるクラスの jfieldID を別のクラスのインスタンスで使用している。
jmethodID: Call*Method JNI 呼び出しを行う際に、不適切なタイプの jmethodID を使用している（正しくない戻り値型、静的 / 非静的の不一致、「this」に対する不適切な型（非静的呼び出しの場合）、不適切なクラス（静的呼び出しの場合）など）。
参照: 不適切なタイプの参照に対して DeleteGlobalRef / DeleteLocalRef を使用している。
Release のモード: Release 呼び出しに対して正しくないモード（0、JNI_ABORT、JNI_COMMIT 以外のモード）を渡している。
型安全性: ネイティブメソッドから互換性のない型を返している（たとえば、String を返すように宣言されているメソッドから StringBuilder を返している）。
UTF-8: JNI 呼び出しに対して無効な Modified UTF-8 バイトシーケンスを渡している。

（メソッドおよびフィールドへのアクセスが可能かどうかは、今でもチェックされていません。アクセスの制限はネイティブコードには適用されません。）

CheckJNI を有効にする方法はいくつかあります。

エミュレータを使用する場合、CheckJNI はデフォルトで有効になっています。

ユーザーに root 権限のあるデバイスでは、以下の一連のコマンドを使用することにより、CheckJNI を有効にしてランタイムを再起動できます。

adb shell stop
    adb shell setprop dalvik.vm.checkjni true
    adb shell start

いずれの場合でも、ランタイムの起動時に、logcat に次のようなメッセージが出力されます。

D AndroidRuntime: CheckJNI is ON

通常のデバイスでは、次のコマンドを使用できます。

adb shell setprop debug.checkjni 1

このコマンドを実行しても、すでに実行中のアプリでは CheckJNI は有効になりませんが、その後に起動したアプリでは CheckJNI が有効になります（プロパティを他の値に変更するか、再起動すると、CheckJNI が再び無効になります）。この場合、次回アプリを起動したときに、logcat に次のようなメッセージが出力されます。

D Late-enabling CheckJNI

アプリのマニフェストで android:debuggable 属性を設定して、アプリレベルで CheckJNI を有効にすることも可能です。ビルドタイプによっては、Android ビルドツールがこの処理を自動的に行います。

ネイティブライブラリ

標準の System.loadLibrary を使用して、共有ライブラリからネイティブコードをロードできます。

実は、古いバージョンの Android には Package Manager にバグがあり、それが原因でネイティブライブラリのインストールやアップデートの信頼性が低下していました。この問題や他のネイティブライブラリのロードに関する問題については、ReLinker プロジェクトから対応策が提供されています。

System.loadLibrary（または ReLinker.loadLibrary）は、静的クラスイニシャライザから呼び出します。引数は「装飾されていない」ライブラリ名であるため、libfubar.so をロードするには "fubar" を渡します。

ネイティブメソッドを持つクラスが 1 つだけの場合、そのクラスの静的イニシャライザ内で System.loadLibrary 呼び出しを行うことは理にかなっています。ただし、そのようなクラスが 1 つだけでない場合は、Application から呼び出しを行うことをおすすめします。そうすれば、ライブラリは必ず、しかも常に早い段階でロードされます。

ランタイムがネイティブメソッドを見つける方法には、RegisterNatives を使用して、ネイティブメソッドを明示的に登録する方法と、dlsym を使用して、ランタイムに動的にルックアップさせる方法の 2 つがあります。RegisterNatives のメリットとしては、シンボルが存在するか事前にチェックできる点があります。さらに、JNI_OnLoad 以外をエクスポートしないようにすれば、共有ライブラリのサイズが小さくなり高速化が可能になります。ランタイムに関数をルックアップさせる場合のメリットとしては、記述するコードを多少減らせる点があります。

RegisterNatives を使用する際は、以下のように設定します。

JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void* reserved) 関数を指定します。
JNI_OnLoad で、RegisterNatives を使用してすべてのネイティブメソッドを登録します。
ライブラリから JNI_OnLoad だけがエクスポートされるように、-fvisibility=hidden を指定してビルドします。これにより、コードがコンパクトになり高速化され、アプリにロードされる他のライブラリとの競合の可能性も回避できます（ただし、ネイティブコード内でアプリがクラッシュした場合に生成されるスタックトレースの情報は、あまり役に立ちません）。

静的イニシャライザは次のようになります。

Kotlin

    companion object {
        init {
            System.loadLibrary("fubar")
        }
    }

Java

    static {
        System.loadLibrary("fubar");
    }

C++ で記述した場合、JNI_OnLoad 関数は次のようになります。

JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void* reserved) {
        JNIEnv* env;
        if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
            return JNI_ERR;
        }

        // Find your class. JNI_OnLoad is called from the correct class loader context for this to work.
        jclass c = env->FindClass("com/example/app/package/MyClass");
        if (c == nullptr) return JNI_ERR;

        // Register your class' native methods.
        static const JNINativeMethod methods[] = {
            {"nativeFoo", "()V", reinterpret_cast<void*>(nativeFoo)},
            {"nativeBar", "(Ljava/lang/String;I)Z", reinterpret_cast<void*>(nativeBar)},
        };
        int rc = env->RegisterNatives(c, methods, sizeof(methods)/sizeof(JNINativeMethod));
        if (rc != JNI_OK) return rc;

        return JNI_VERSION_1_6;
    }

代わりにネイティブメソッドの「discovery」を使用する場合は、特定の方法でネイティブメソッドに名前を付ける必要があります（詳細については、JNI 仕様をご覧ください）。メソッドシグネチャが誤っていても、メソッドが実際に初めて呼び出されるまで、そのことを知る方法はありません。

FindClass 呼び出しを JNI_OnLoad から行うと、共有ライブラリのロードに使用されたクラスローダーのコンテキスト内でクラスが解決されます。他のコンテキストから呼び出された場合、FindClass は、Java スタックの最上部にあるメソッドに関連付けられているクラスローダーを使用します。あるいは、アタッチ直後のネイティブスレッドからの呼び出しであるために、そのようなローダーがない場合は、「システム」クラスローダーを使用します。システムクラスローダーはアプリのクラスを認識しないため、そのコンテキスト内では FindClass を使用してアプリ独自のクラスをルックアップすることはできません。クラスのルックアップとキャッシュを行う場所として JNI_OnLoad が都合がいいのはそのためです。有効な jclass があれば、アタッチされているどのスレッドからでも使用できるからです。

64 ビットに関する注意事項

64 ビットポインタを使用するアーキテクチャをサポートするには、ネイティブ構造体へのポインタを Java のフィールドに格納する際に、int フィールドではなく long フィールドを使用します。

サポートされていない機能と後方互換性

JNI 1.6 の機能はすべてサポートされています。ただし、以下の例外があります。

DefineClass は実装されていません。Android は Java のバイトコードやクラスファイルを使用しないため、バイナリクラスデータを渡すことはできません。

古い Android リリースとの後方互換性を維持する際は、以下の点に注意する必要があります。

ネイティブ関数の動的ルックアップ
Android 2.0（Eclair）までは、メソッド名の検索時に「$」文字が「_00024」に正しく変換されていませんでした。この問題を回避するには、明示的な登録を使用するか、ネイティブメソッドを内部クラスから移動する必要があります。
スレッドのデタッチ
Android 2.0（Eclair）までは、「終了前にスレッドをデタッチしているか」のチェックを回避するために pthread_key_create デストラクタ関数を使用することはできませんでした。（ランタイムも pthread キーのデストラクタ関数を使用し、どちらが先に呼び出されるかわからないため）。
弱いグローバル参照
Android 2.2（Froyo）までは、弱いグローバル参照は実装されていませんでした。古いバージョンでは、弱いグローバル参照を使用しようとすると明確に拒否されます。Android プラットフォームバージョン定数を使用して、弱いグローバル参照がサポートされているかどうかをテストできます。
Android 4.0（Ice Cream Sandwich）までは、弱いグローバル参照を渡すことができるのは、NewLocalRef、NewGlobalRef、DeleteWeakGlobalRef に限られていました（この仕様の場合、プログラマーは、弱いグローバル参照を使用してなんらかの処理を行う前に、処理が制限されないよう、弱いグローバル参照へのハード参照を作成することが強く推奨されます）。
Android 4.0（Ice Cream Sandwich）以降では、弱いグローバル参照を他の JNI 参照と同じように使用できます。
ローカル参照
Android 4.0（Ice Cream Sandwich）までは、ローカル参照は実際には、直接ポインタでした。Ice Cream Sandwich において、より効率的なガベージコレクタをサポートするために必要な間接参照が追加されましたが、これは、以前のリリースでは JNI の多くのバグを検出できないことを意味しています。詳細については、ICS における JNI ローカル参照の変更点をご覧ください。

Android 8.0 より前のバージョンの Android では、バージョンごとに、ローカル参照の数に上限があります。Android 8.0 以降では、Android がサポートするローカル参照の数に制限はありません。
GetObjectRefType による参照タイプの判定
Android 4.0（Ice Cream Sandwich）までは、直接ポインタが使用されていたため（上記を参照）、GetObjectRefType を正しく実装することができませんでした。その代わり、弱いグローバル参照テーブル、引数、ローカル参照テーブル、グローバル参照テーブルを順番に調べるヒューリスティックが使用されていました。そのため、直接ポインタを初めて検出すると、そのときにたまたま調べていたタイプが参照タイプとして報告されます。たとえば、あるグローバル jclass に対して GetObjectRefType を呼び出したときに、それがたまたま静的ネイティブメソッドに暗黙的引数として渡された jclass と同じだった場合、JNIGlobalRefType ではなく JNILocalRefType を取得することになります。

よくある質問: `UnsatisfiedLinkError` エラーが発生します。なぜですか？

ネイティブコードの処理中に、次のようなエラーメッセージが表示されることがよくあります。

java.lang.UnsatisfiedLinkError: Library foo not found

このエラーメッセージは、ライブラリが見つからなかった場合や、ライブラリは存在しているが dlopen(3) によって開くことができなかった場合に表示されます。エラーの詳細については、例外の詳細メッセージで確認できます。

「ライブラリが見つからない」例外が発生する理由としては、主に以下のようなものがあります。

ライブラリが存在しない、あるいは、アプリからアクセスできない。ライブラリの存在の有無とパーミッションを調べるには adb shell ls -l <path> を使用します。
ライブラリの構築に NDK が使用されていない。この場合、デバイス上に存在しない関数やライブラリに対する依存関係が発生する可能性があります。

別のクラスの UnsatisfiedLinkError エラーとして、以下のようなメッセージが表示されることがあります。

java.lang.UnsatisfiedLinkError: myfunc
            at Foo.myfunc(Native Method)
            at Foo.main(Foo.java:10)

logcat には、次のようなメッセージが出力されます。

W/dalvikvm(  880): No implementation found for native LFoo;.myfunc ()V

このメッセージは、ランタイムが一致するメソッドを見つけようとしたが見つからなかったことを示しています。このエラーが発生する一般的な理由には以下のようなものがあります。

ライブラリがロードされていない。logcat の出力に、ライブラリのロードに関するメッセージがないかチェックします。
名前またはシグネチャの不一致により、メソッドが見つからない。この場合の主な原因は以下のとおりです。
- メソッドのルックアップが遅いために、extern "C" と適切な可視性（JNIEXPORT）を指定して C++ 関数を宣言することができない。Ice Cream Sandwich より前のバージョンでは、JNIEXPORT マクロに誤りがあったため、新しい GCC と古い jni.h を併用することができませんでした。arm-eabi-nm を使用すると、ライブラリ内と同じようにシンボルを参照できます。シンボルがマングリングされているように見える場合（たとえば、Java_Foo_myfunc ではなく _Z15Java_Foo_myfuncP7_JNIEnvP7_jclass のようになっている場合）や、シンボル型が大文字の「T」ではなく小文字の「t」になっている場合は、宣言を調整する必要があります。
- 明示的な登録で、メソッドシグネチャの入力時に軽微なエラーが発生する。登録の呼び出しに渡す内容と、ログファイル内のシグネチャが適合しているか確認してください。「B」は byte を示し、「Z」は boolean を示します。シグネチャ内のクラス名コンポーネントは、「L」で始まり「;」で終わります。パッケージ名とクラス名の区切りには「/」を使用し、内部クラス名の区切りには「$」を使用します（例: Ljava/util/Map$Entry;）。

javah を使用して JNI ヘッダーを自動生成すると、一部の問題の発生を回避できる場合があります。

よくある質問: `FindClass` でクラスを見つけられませんでした。なぜですか？

（ここで示すアドバイスのほとんどは、GetMethodID や GetStaticMethodID を使用してメソッドを検出できない場合や、GetFieldID や GetStaticFieldID を使用してフィールドを検出できない場合にも当てはまります。）

クラス名文字列の形式が正しいか確認してください。JNI クラス名は、パッケージ名で始まり、スラッシュで区切ります（例: java/lang/String）。配列クラスをルックアップする場合は、適切な数の角かっこで開始して、「L」と「;」でクラスをラップする必要があります。たとえば、1 次元配列の String の場合、[Ljava/lang/String; のように指定します。内部クラスをルックアップする場合は、「.」ではなく「$」を使用します。一般に、クラスの内部名を見つける場合、.class ファイルに対して javap を使用することをおすすめします。

コード圧縮を有効にしている場合は、保持するコードについて設定する必要があります。適切な保持ルールを設定することが重要です。そうしないと、JNI からしか使用されていないクラス、メソッド、フィールドがコード圧縮ツールによって削除される可能性があります。

クラス名に問題がなければ、クラスローダーに問題がある可能性があります。FindClass は、コードに関連付けられているクラスローダー内でクラスの検索を開始して、コールスタックを調べます。たとえば、次のようになります。

    Foo.myfunc(Native Method)
        Foo.main(Foo.java:10)

最初のメソッドは Foo.myfunc です。FindClass は、Foo クラスに関連付けられている ClassLoader オブジェクトを見つけて使用します。

通常はこれで間に合いますが、スレッドを自分で作成した場合（pthread_create を呼び出した後、AttachCurrentThread を使用してスレッドをアタッチした場合など）は、問題が生じることがあります。この時点では、アプリからのスタックフレームはありません。このスレッドから FindClass を呼び出した場合、アプリに関連付けられているクラスローダーではなく「システム」クラスローダー内で JavaVM が起動するため、アプリ固有のクラスを見つけようとしても失敗します。

この問題に対しては、次のような対応策があります。

FindClass のルックアップを JNI_OnLoad 内で 1 回実行し、後で使用するクラス参照をキャッシュします。JNI_OnLoad 実行の一環として行われる FindClass 呼び出しの場合、System.loadLibrary を呼び出した関数に関連付けられているクラスローダーが使用されます（これは、ライブラリ初期化を簡単にするために規定された特別ルールです）。アプリコードがライブラリをロードしている場合、FindClass は適切なクラスローダーを使用します。
Class 引数を受け取るネイティブメソッドを宣言し、Foo.class を渡すことにより、クラスのインスタンスを必要とする関数にクラスのインスタンスを渡します。
ClassLoader オブジェクトへの参照をどこか便利な場所にキャッシュして、直接 loadClass 呼び出しを発行します。この方法には多少の手間がかかります。

マネージコードとネイティブコードの両方から生データの大きなバッファにアクセスしなければならない状況に置かれることがあります。ビットマップや音のサンプルの操作などではよくあることです。このような状況に対する基本的なアプローチは 2 つあります。

1 つ目のアプローチとしては、データを byte[] に格納します。これにより、マネージコードから高速にアクセスできるようになります。しかし、ネイティブコードからは、データをコピーせずにアクセスできるという保証はありません。実装によっては、GetByteArrayElements や GetPrimitiveArrayCritical がマネージヒープ内の生データへの実際のポインタを返すこともあれば、ネイティブヒープにバッファを割り当て、そこにデータをコピーすることもあります。

もう 1 つのアプローチでは、データを直接バイトバッファに格納します。直接バイトバッファは、java.nio.ByteBuffer.allocateDirect か、JNI の NewDirectByteBuffer 関数を使用して作成します。通常のバイトバッファとは異なり、このストレージはマネージヒープ上には割り当てられず、常にネイティブコードから直接アクセスできます（アドレスは GetDirectBufferAddress を使用して取得します）。ただし、直接バイトバッファアクセスの実装方法によっては、マネージコードからのデータアクセスが非常に低速になることがあります。

どちらのアプローチを選択するのかは、以下の 2 つの要因によって決まります。

データアクセスが多いのは、Java で記述されたコードなのか、C / C++ で記述されたコードなのか。
最終的にデータをシステム API に渡す場合、どの形式にする必要があるのか（たとえば、最終的に byte[] を受け取る関数にデータを渡す場合、直接 ByteBuffer 内で処理を行うことはおすすめしません）。

どちらのアプローチが優れているか明確でない場合は、直接バイトバッファを使用してください。直接バイトバッファのサポートは JNI に直接組み込まれており、将来のリリースでパフォーマンスが向上していくと考えられます。

JNI に関するヒント

一般的なヒント

JavaVM と JNIEnv

スレッド

jclass、jmethodID、jfieldID

Kotlin

Java

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

UTF-8 文字列と UTF-16 文字列

プリミティブ配列

配列領域（Region）の呼び出し

例外

拡張チェック機能

ネイティブ ライブラリ

Kotlin

Java

64 ビットに関する注意事項

サポートされていない機能と後方互換性

よくある質問: UnsatisfiedLinkError エラーが発生します。なぜですか？

よくある質問: FindClass でクラスを見つけられませんでした。なぜですか？

よくある質問: 生データをネイティブ コードと共有するにはどのようにすればよいですか？

ネイティブライブラリ

よくある質問: `UnsatisfiedLinkError` エラーが発生します。なぜですか？

よくある質問: `FindClass` でクラスを見つけられませんでした。なぜですか？

よくある質問: 生データをネイティブコードと共有するにはどのようにすればよいですか？