java.lang.instrument (Java Platform SE 8)

インタフェースのサマリー
インタフェース	説明
ClassFileTransformer	クラス・ファイルを変換するために、このインタフェースの実装を提供するエージェント。
Instrumentation	このクラスは、Javaプログラミング言語コードを計測するためのサービスを提供します。

クラスのサマリー
クラス	説明
ClassDefinition	このクラスは、`Instrumentation.redefineClasses`メソッドに対するパラメータ・ブロックとして機能します。

例外のサマリー
例外	説明
IllegalClassFormatException	入力パラメータが無効な場合に`ClassFileTransformer.transform`の実装によってスローされます。
UnmodifiableClassException	指定されたクラスの1つを変更できない場合、`Instrumentation.redefineClasses`の実装によってスローされます。

パッケージjava.lang.instrumentの説明

Javaプログラミング言語エージェントによりJVMで実行中のプログラムを計測するサービスを提供します。インストゥルメンテーションのメカニズムは、メソッドのバイト・コードの変更です。

パッケージの仕様

エージェントはJARファイルとして配備されます。JARファイルに含まれるマニフェストの属性は、エージェントを起動するためにロードされるエージェント・クラスを指定します。コマンド行インタフェースをサポートする実装では、コマンド行でオプションを指定する方法でエージェントを開始します。実装によっては、VMの開始後にエージェントを開始するメカニズムもサポートしている場合があります。たとえば、実行中のアプリケーションにツールを接続して、ツールのエージェントをそのアプリケーションにロードし始められるようなメカニズムを提供できる実装もあります。ロードの開始方法の詳細は、実装によって異なります。

コマンド行インタフェース

実装がコマンド行インタフェースからエージェントを開始する方法を提供する必要はありません。コマンド行インタフェースからエージェントを開始する方法を提供する実装では、このオプションをコマンド行に追加することでエージェントが開始されます。

-javaagent:jarpath[=options]

jarpathはエージェントJARファイルへのパスです。optionsはエージェント・オプションです。このスイッチは、1つのコマンド行で複数回使用できるため、複数のエージェントを作成できます。複数のエージェントで同じjarpathを使用できます。エージェントJARファイルはJARファイル仕様に従う必要があります。

エージェントJARファイルのマニフェストには属性Premain-Classが含まれる必要があります。この属性の値は、エージェント・クラスの名前です。エージェント・クラスは、基本的にmainアプリケーション・エントリ・ポイントと同様のpublic static premainメソッドを実装する必要があります。Java仮想マシン(JVM)が初期化されたら、エージェントが指定された順序で各premainメソッドが呼び出され、次に実際のアプリケーションのmainメソッドが呼び出されます。各premainメソッドは、起動シーケンスが実行される順序で返されなければいけません。

premainメソッドには2つのシグネチャのうちのいずれかがあります。JVMはエージェント・クラスで最初に次のメソッドを呼び出そうとします。

public static void premain(String agentArgs, Instrumentation inst);

エージェント・クラスにこのメソッドが実装されていない場合は、次のメソッドを呼び出そうとします。

public static void premain(String agentArgs);

エージェント・クラスにはagentmainメソッドが用意されている場合もあります。このメソッドはVMの開始後にエージェントを開始するときに使用します。コマンド行オプションを使用してエージェントを開始した場合は、agentmainメソッドが呼び出されません。

エージェント・クラスはシステム・クラス・ローダーによってロードされます(ClassLoader.getSystemClassLoaderを参照)。このクラス・ローダーは、通常、アプリケーションmainメソッドを含むクラスをロードします。premainメソッドは、アプリケーションmainメソッドと同じセキュリティルールとクラス・ローダールールで実行されます。エージェントpremainメソッドの実行内容に関するモデリング制約はありません。作成側スレッドを含め、アプリケーションmainが実行できることは、すべてpremainで有効です。

各エージェントは、agentArgsパラメータ経由でエージェント・オプションが渡されます。エージェント・オプションは単一の文字列として渡され、追加の解析はエージェント自身によって行われます。

エージェントを解決できない場合(たとえばエージェント・クラスをロードできなかったため、またはエージェント・クラスに適切なpremainメソッドがないため)、JVMは異常終了します。premainメソッドが、キャッチされない例外をスローすると、JVMが異常終了します。

VM開始後のエージェント開始

実装によっては、VMの開始後にエージェントを開始するメカニズムが用意されている場合もあります。開始する方法の詳細は、実装によって異なりますが、通常はアプリケーションが開始済みで、そのアプリケーション mainメソッドが呼出し済みです。VMの開始後にエージェントを開始できる場合は、次の条件が適用されます。

エージェントJARのマニフェストには属性Agent-Classが含まれる必要がある。この属性の値は、エージェント・クラスの名前です。
エージェント・クラスはpublic static agentmainメソッドを実装する必要がある。
システム・クラス・ローダー(ClassLoader.getSystemClassLoader)は、エージェントJARファイルをシステム・クラス・パスに追加するメカニズムをサポートする必要がある。

エージェントJARはシステム・クラス・パスに追加されます。このクラス・ローダーは、通常、アプリケーションmainメソッドを含むクラスをロードします。エージェント・クラスがロードされると、JVMはagentmainメソッドを呼び出そうとします。JVMはエージェント・クラスで最初に次のメソッドを呼び出そうとします。

public static void agentmain(String agentArgs, Instrumentation inst);

エージェント・クラスにこのメソッドが実装されていない場合は、次のメソッドを呼び出そうとします。

public static void agentmain(String agentArgs);

エージェント・クラスには、コマンド行オプションを使用してエージェントを開始するときに使用するpremainメソッドが用意されている場合があります。VMの開始後にエージェントが開始されると、premainメソッドは呼び出されません。

エージェントは、agentArgsパラメータ経由でエージェント・オプションが渡されます。エージェント・オプションは単一の文字列として渡され、追加の解析はエージェント自身によって行われます。

agentmainメソッドでは、エージェントの開始に必要な必須の初期化を実行するようにしてください。開始が完了すると、メソッドを返すようにします。エージェントを開始できない場合(たとえばエージェント・クラスをロードできなかったため、またはエージェント・クラスに適切なagentmainメソッドがないため)、JVMは異常終了します。agentmainメソッドが、キャッチされない例外をスローすると、無視されます。

マニフェスト属性

エージェントJARファイルには次のマニフェスト属性が定義されています。

Premain-Class

JVMの起動時にエージェントが指定される場合は、この属性でエージェント・クラスを指定します。つまり、premainメソッドが含まれるクラスです。JVMの起動時にエージェントが指定される場合は、この属性が必須です。この属性が存在しない場合、JVMは異常終了します。注: これはクラス名であり、ファイル名やパスではありません。

Agent-Class

VMの開始後にエージェントを開始するメカニズムが実装でサポートされている場合は、この属性でエージェント・クラスを指定します。つまり、agentmainメソッドが含まれるクラスです。この属性は必須です。存在しない場合、エージェントは開始しません。注: これはクラス名であり、ファイル名やパスではありません。

Boot-Class-Path

ブートストラップ・クラス・ローダーで検索されるパスのリストです。パスはディレクトリまたはライブラリを表します。多くのプラットフォームでは、通常、JARファイルまたはzipライブラリとして参照されます。クラスを検索するプラットフォーム固有のメカニズムが失敗すると、これらのパスがブートストラップ・クラス・ローダーで検索されます。パスはリストの順序で検索されます。リスト内のパスは1つ以上の空白文字で区切られます。パスの構文は、階層型URIのパス・コンポーネントの構文になります。スラッシュ文字(/)で始まると絶対パス、それ以外の場合は相対パスです。相対パスはエージェントのJARファイルの絶対パスに対して解決されます。パスが不正または存在しない場合は無視されます。VMの開始後にエージェントが開始される場合は、JARファイルを表さないパスは無視されます。この属性はオプションです。

Can-Redefine-Classes

ブール値(trueまたはfalse、大文字小文字は区別しない)。クラスを再定義する機能がこのエージェントに必要かを表します。true以外の値はfalseであるとみなされます。この属性はオプションで、デフォルトはfalseです。

Can-Retransform-Classes

ブール値(trueまたはfalse、大文字小文字は区別しない)。クラスを再変換する機能がこのエージェントに必要かを表します。true以外の値はfalseであるとみなされます。この属性はオプションで、デフォルトはfalseです。

Can-Set-Native-Method-Prefix

ブール値(trueまたはfalse、大文字小文字は区別しない)。ネイティブ・メソッドの接頭辞を設定する機能がこのエージェントに必要かを表します。true以外の値はfalseであるとみなされます。この属性はオプションで、デフォルトはfalseです。

エージェントJARファイルでは、マニフェスト内にPremain-Class属性とAgent-Class属性の両方が存在することがあります。-javaagentオプションを使用したコマンド行でエージェントを開始する場合は、Premain-Class属性でエージェント・クラスの名前を指定し、Agent-Class属性は無視されます。同様に、VMの開始後にエージェントが開始される場合は、Agent-Class属性でエージェント・クラスの名前を指定し、Premain-Class属性は無視されます。

パッケージ java.lang.instrument

パッケージjava.lang.instrumentの説明

パッケージの仕様

コマンド行インタフェース

VM開始後のエージェント開始

マニフェスト属性

関連項目