パッケージ java.lang.instrument

Java プログラミング言語エージェントが JVM 上で実行されているプログラムを計測できるようにするサービスを提供します。

参照先:
説明

インタフェースの概要

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

クラスの概要

ClassDefinition

このクラスは、Instrumentation.redefineClasses メソッドに対するパラメータブロックとして機能します。

例外の概要

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

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

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

パッケージの仕様

JVM の起動時に「エージェントクラス」とその「エージェントオプション」を指定して、エージェントを起動します。

エージェントクラスはは、基本的に main アプリケーションエントリポイントと同様の public static premain メソッドを実装する必要があります。

public static voidpremain(String agentArgs, Instrumentation inst);

JVM が初期化されたあと、各 premain メソッドは、エージェントが指定された順に呼び出されます。次に、実際のアプリケーション main メソッドが呼び出されます。各 premain メソッドは、起動シーケンスが実行される順に返されなければなりません。エージェントクラスは、アプリケーション main メソッドを含むクラスをロードするのと同じクラスローダでロードされます。premain メソッドは、アプリケーション main メソッドと同じセキュリティ規則とクラスローダ規則の下で実行されます。エージェント premain メソッドの実行内容に関するモデリング制約はありません。生成スレッドを含め、アプリケーション main が実行できることは、すべて premain で有効です。

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

エージェントを解決できない (たとえば、エージェントクラスをロードできない、あるいはエージェントクラスが適合した premain メソッドを持たないなどの理由により) 場合、JVM は中断されます。premain メソッドがキャッチされない例外をスローした場合、JVM は中断されます。

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

コマンドラインインタフェースを持つ JVM では、JVM コマンドラインに次のスイッチを追加することでエージェントを指定します。

-javaagent:jarpath[=options]

jarpath はエージェント JAR ファイルへのパスです。options はエージェントオプションです。このスイッチは、同じコマンドライン上で複数回繰り返し、複数のエージェントを作成することができます。複数のエージェントが同じ jarpath を使用することができます。エージェント JAR ファイルは、JAR ファイル仕様に適合する必要があります。エージェント JAR ファイルでは、次のマニフェスト属性が定義されています。

Premain-Class

エージェントクラス、つまり、premain メソッドを含むクラスです。この属性は必須であり、存在しない場合は JVM が中断されます。注: これはクラス名であり、ファイル名やパスではありません。

Boot-Class-Path

ブートストラップクラスローダによって検索されるパスのリスト。パスはディレクトリやライブラリ (一般に、多くのプラットフォームで jar または zip ライブラリと呼ばれる) を表します。クラスの失敗を見つけるプラットフォーム固有のメカニズムのあと、これらのパスがブートストラップローダによって検索されます。パスの検索は、リストに表示されている順に行われます。リスト内のパスは 1 つ以上のスペースで区切られています。パスは、階層的な URI のパスコンポーネントの構文をとります。スラッシュ記号 (「/」) で始まるパスは絶対パス、そうでない場合は相対パスです。相対パスは、エージェント JAR ファイルの絶対パスに対して解決されます。不正または存在しないパスは無視されます。この属性はオプションです。

Can-Redefine-Classes

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

エージェント JAR ファイルは、クラスパスに追加されます。

関連ドキュメント

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

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

導入されたバージョン:

JDK1.5