ナビゲーション・リンクをスキップ
Java(tm) Platform
Standard Edition 8

パッケージ java.lang.instrument

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

参照: 説明

パッケージ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属性は無視されます。

関連項目

ツールのマニュアルについては、次を参照してください。
導入されたバージョン:
JDK1.5
ナビゲーション・リンクをスキップ
Java(tm) Platform
Standard Edition 8

バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2017, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。