実験的エージェントオプション

native-image-agent ツールには、現在実験的なものもあり、将来のリリースで有効化される可能性があるが、変更または完全に削除される可能性もあるオプションがあります。これらのオプションはここで説明します。

定義済みクラスのサポート #

ネイティブイメージでは、すべてのクラスがイメージのビルド時に認識されている必要があります（「クローズドワールドの仮定」）。ただし、Java には実行時に新しいクラスをロードするためのサポートがあります。クラスのロードをエミュレートするため、エージェントは動的にロードされたクラスを追跡し、そのバイトコードを後でイメージビルダーが使用できるように保存するように指示できます。この機能は、experimental-class-define-support をエージェントのオプション文字列に追加することで有効にすることができます。たとえば、-agentlib:native-image-agent=config-output-dir=config,experimental-class-define-support のようになります。標準の構成ファイルとは別に、エージェントは構成の出力ディレクトリに agent-extracted-predefined-classes ディレクトリを作成し、そこで新しくロードされたクラスのバイトコードを継続的に書き込みます。その後、イメージビルダーは構成ディレクトリを使用できます。その際、追加の調整は必要ありません。クラスはイメージのビルド中にロードされますが、初期化されず、アプリケーションでは使用できません。実行時、追跡中に遭遇したクラスと同じ名前とバイトコードを持つクラスをロードしようとした場合、定義済みクラスがアプリケーションに提供されます。

既知の制限 #

ネイティブイメージは、1 つの実行で 1 つのクラスローダーだけで定義済みクラスを「ロード」できます。
定義済みクラスは、実行時に「ロード」されたときに初期化され、ビルド時には初期化できません。
エージェントは、Java 仮想マシンの組み込みクラスローダーのいずれかによってロードされていないクラス（一部の例外があります）をすべて収集します。つまり、クラスパスまたはモジュールパスから収集します。これには、カスタムクラスローダーによってロードされたクラスも含まれます。
名前やバイトコードに連続した、またはランダムな数字やタイムスタンプなど変化するデータを含むクラスは、通常実行時に定義済みのクラスと照合できません。このようなケースでは、そのようなクラスの生成方法を調整する必要があります。

起源を使用して構成を印刷 #

デバッグには、特定の構成エントリの起点を知ると便利です。experimental-configuration-with-origins をエージェントオプション文字列に指定すると、エージェントは構成ファイルを出力します。ここで構成エントリは、ツリー形式で起点となる呼び出しコンテキスト（スタックトレース）に分解されています。このオプションは config-output-dir=<path> と組み合わせて使用して、構成ファイルをどこに保存するかをエージェントに伝えます。エージェントオプションの文字列の例: -agentlib:native-image-agent=config-output-dir=config-with-origins/,experimental-configuration-with-origins

エージェントの出力から構成を省略 #

エージェントは、既存の構成ファイルにある追跡された構成エントリを省略できます。これらの既存の構成ファイルを指定する方法は 2 つあります。

クラスパスまたはモジュールパスから構成ファイルを使用します。experimental-omit-config-from-classpath をエージェントオプション文字列に追加すると、実行中のアプリケーションのクラスパスとモジュールパスが META-INF/native-image/**/*.json 構成ファイルに対してスキャンされます。
config-to-omit=<path> を使用して既存の構成ファイルディレクトリをエージェントに明確に示します。

エージェントを使用して条件付き構成を生成 #

エージェントはヒューリスティックを使用して、ユーザーが指定したクラスに対する到達可能性条件を使用して構成を生成できます。エージェントは構成の起源を追跡し、状態を自動的に推論しようとします。ユーザーのクラスはエージェントフィルターファイルを使用して指定されます（詳細については、エージェントの詳細を参照）。さらに、結果の構成は別のフィルターファイルを使用してさらにフィルター処理できます。

現在、この機能は次の 2 つのモードをサポートしています。

エージェントを使用して単一の実行で条件付き構成を生成します。
エージェントを使用した複数の実行から条件付き構成を生成し、最後に収集したデータをマージします。

エージェントの実行中に条件付き構成を生成 #

このモードを有効にするには、experimental-conditional-config-filter-file=<path> をエージェントのコマンドラインに追加します。<path> はエージェントフィルターファイルを指します。このフィルターによって含まれるとみなされるクラスは、ユーザーコードクラスとして指定されます。生成された構成をさらにフィルター処理するには、conditional-config-class-filter-file=<path> を使用できます。<path> はエージェントフィルターファイルへのパスです。

複数エージェントの実行から条件付き構成を生成 #

条件付き構成は、アプリケーションのさまざまなコードパスに到達する複数エージェントの実行から生成できます。各エージェントの実行によって、メタデータを含む構成が生成されます。native-image-configure を使用して、収集したデータをマージして条件付き構成を生成します。このモードでエージェントを実行するには、experimental-conditional-config-part をエージェントのコマンドラインに追加します。すべての実行が完了したら、起動によって条件付き構成を生成できます。

native-image-configure generate-conditional --user-code-filter=<path-to-filter-file> --class-name-filter=<path-to-filter-file> --input-dir=<path-to-agent-run-output-1> --input-dir=<path-to-agent-run-ouput-2> ... --output-dir=<path-to-resulting-conditional-config>

ここで

--user-code-filter=<path-to-filter-file>: ユーザーのクラスを指定するエージェントフィルターファイルへのパス
(オプション) --class-name-filter=<パスフィルターファイル>: 生成された構成をさらにフィルタリングするエージェントフィルターファイルへのパス

基礎ヒューリスティクス #

条件は、アプリケーションのコールツリーを使用して生成されます。ヒューリスティクスは次のように機能します

それぞれの固有メソッドに対して、メソッドに対応するコールツリー内のすべてのノードのリストを作成します
それぞれの固有メソッドに対して、メソッドがツリー内に複数のコールノードを持つ場合
- そのメソッドのすべてのコールノード全体で共通の構成を検索します
- メソッドのコールノードそれぞれに対して、これらの呼び出し全体で共通ではない構成を呼び出し元ノードに伝播します
反復がコールツリーの変更を生み出さなくなるまで、2. を繰り返します。
構成を含むノードごとに、メソッドのクラスを条件とする条件付き構成エントリを生成します。

このヒューリスティクスの主な目標は、メソッドが呼び出し元に応じて異なる構成エントリを作成する場所を見つけることです（たとえば、Class.forName呼び出しをラップするメソッドです）。これは、ヒューリスティクスが異なる依存関係を介して構成を生成するコードではうまく機能しないことを意味します（たとえば、同じメソッドがシステムプロパティに応じて異なるクラスパラメーターでClass.forNameを返す場合）。