パッケージ java.lang.instrument

Java プログラミング言語エージェントにより JVM で実行中のプログラムを計測するサービスを提供します。

参照: 説明

インタフェースのサマリー

インタフェース	説明
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 の開始後にエージェントを開始できる場合は、次の条件が適用されます。

1. エージェント JAR のマニフェストには属性 Agent-Class が含まれる必要がある。この属性の値は、エージェントクラスの名前です。

2. エージェントクラスは public static agentmain メソッドを実装する必要がある。

3. システムクラスローダー (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 属性は無視されます。

関連項目

ツールのマニュアルについては、次を参照してください。

• JDK ツールとユーティリティー

導入されたバージョン:

JDK1.5