java.lang.instrument (Java Platform SE 6)

概要

パッケージ

クラス

使用

階層ツリー

非推奨 API

索引

ヘルプ

Java^TM Platform
Standard Ed. 6

前のパッケージ 次のパッケージ

フレームあり フレームなし

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

エージェント 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 属性は無視されます。