java.lang.instrument
インタフェース Instrumentation

public interface Instrumentation

このクラスは、Java プログラミング言語コードを計測するためのサービスを提供します。インストゥルメンテーションとは、ツールで使用するデータを収集することを目的としてメソッドにバイトコードを追加することです。変更は単に追加されるため、これらのツールはアプリケーションの状態や動作を変更しません。状態や動作に影響を及ぼさないこの種のツールには、監視エージェント、プロファイラ、カバレージアナライザ、およびイベントロガーなどがあります。

Instrumentation インタフェースのインスタンスにアクセスする唯一の方法は、エージェントクラスを指定する方法で JVM を起動することです (the package specification を参照)。Instrumentation インスタンスは、そのエージェントクラスの premain メソッドに渡されます。エージェントが Instrumentation インスタンスを取得すると、インスタンス上のメソッドをいつでも呼び出すことができます。

導入されたバージョン:

JDK1.5

メソッドの概要

void	addTransformer(ClassFileTransformer transformer) 提供されたトランスフォーマを登録します。
Class[]	getAllLoadedClasses() JVM により現在ロードされているすべてのクラスの配列を返します。
Class[]	getInitiatedClasses(ClassLoader loader) loader が起動ローダであるすべてのクラスの配列を返します。
long	getObjectSize(Object objectToSize) 指定されたオブジェクトにより消費される記憶領域の容量の実装固有の近似値を返します。
boolean	isRedefineClassesSupported() 現在の JVM 構成がクラスの再定義をサポートしているかどうかを返します。
void	redefineClasses(ClassDefinition[] definitions) 提供されたクラスファイルを使って提供されたクラスのセットを再定義します。
boolean	removeTransformer(ClassFileTransformer transformer) 提供されたトランスフォーマの登録を解除します。

メソッドの詳細

addTransformer

void addTransformer(ClassFileTransformer transformer)

提供されたトランスフォーマを登録します。これにより、登録されたトランスフォーマが依存するクラスの定義を除き、将来のすべてのクラス定義はトランスフォーマにより確認されます。複数のトランスフォーマが登録された場合、追加された順に呼び出されます。トランスフォーマが実行中に例外をスローすると、JVM は登録されているその他のトランスフォーマを順に呼び出します。同じトランスフォーマを複数回追加できます。addTransformer を使って登録されたすべてのトランスフォーマは、外部の JVMTI ClassFileLoadHook イベントリスナーが確認する前に、常にすべてのクラスファイルを確認します。

このメソッドは、class specification で記述されているように、インストゥルメンテーションで使用するものです。

パラメータ:

transformer - 登録するトランスフォーマ

例外:

NullPointerException - null トランスフォーマを渡した場合

removeTransformer

boolean removeTransformer(ClassFileTransformer transformer)

提供されたトランスフォーマの登録を解除します。登録解除されたトランスフォーマは、将来クラス定義を確認できなくなります。直前に追加された一致するトランスフォーマのインスタンスを削除します。クラスローディングのマルチスレッド的性質により、削除されたあとでもトランスフォーマを呼び出すことができます。このような状況を考慮して、慎重にトランスフォーマを記述する必要があります。

パラメータ:

transformer - 登録を解除するトランスフォーマ

戻り値:

トランスフォーマが見つかり、削除された場合は true。トランスフォーマが見つからなかった場合は false

例外:

NullPointerException - null トランスフォーマを渡した場合

isRedefineClassesSupported

boolean isRedefineClassesSupported()

現在の JVM 構成がクラスの再定義をサポートしているかどうかを返します。すでにロードされているクラスを再定義する機能は、JVM のオプションの機能です。単一の JVM の 1 つのインスタンス生成の間に、このメソッドに複数の呼び出しを行うと、常に同じ答えが返されます。

戻り値:

現在の JVM 構成がクラスの再定義をサポートする場合は true、サポートしない場合は false

関連項目:

redefineClasses(java.lang.instrument.ClassDefinition[])

redefineClasses

void redefineClasses(ClassDefinition[] definitions)
                     throws ClassNotFoundException,
                            UnmodifiableClassException

提供されたクラスファイルを使って提供されたクラスのセットを再定義します。同時に 1 つ以上のクラスに対してインターロックされた変更 (クラス A の再定義はクラス B の再定義を必要とするなど) を可能にするためにセット上で動作します。

再定義されたメソッドがアクティブなスタックフレームを持つ場合、アクティブなスタックフレームは元のメソッドのバイトコードを引き続き実行します。再定義されたメソッドは新しい呼び出しで使用されます。

このメソッドは、慣行の JVM セマンティクスの下で発生する初期化を除き、初期化を発生させません。つまり、クラスの再定義では、クラスの初期化子は実行されません。static 変数の値は呼び出し前の値のままに維持されます。

再定義されたクラスのインスタンスは影響を受けません。

登録されたトランスフォーマは、再定義操作が適用される前に呼び出されます。

再定義では、メソッドの本文、定数プール、および属性の変更が可能です。ただし、再定義では、フィールドまたはメソッドの追加、削除、あるいは名前の変更、メソッドのシグニチャーの変更、あるいは継承の変更はできません。これらの制約は、将来バージョンで解消される可能性があります。

長さゼロの definitions 配列は使用できますが、使用した場合、このメソッドは何も実行しません。

このメソッドが例外をスローした場合、クラスの再定義は行われません。

このメソッドは、class specification で記述されているように、インストゥルメンテーションで使用するものです。

パラメータ:

definitions - 対応する定義を使って再定義するクラスの配列

例外:

ClassNotFoundException - 指定されたクラスが見つからない場合

UnmodifiableClassException - 指定されたクラスを変更できない場合

UnsupportedOperationException - JVM の現在の構成が再定義 (isRedefineClassesSupported() が false) を許可しないか、再定義でサポートされていない変更を行った場合

ClassFormatError - データが有効なクラスを含まなかった場合

NoClassDefFoundError - クラスファイルの名前がクラスの名前と等しくない場合

UnsupportedClassVersionError - クラスファイルバージョン番号がサポートされていない場合

ClassCircularityError - 新しいクラスが循環を含む場合

LinkageError - リンケージエラーが発生した場合

NullPointerException - 提供された定義配列またはそのコンポーネントが null の場合

関連項目:

isRedefineClassesSupported(), addTransformer(java.lang.instrument.ClassFileTransformer), ClassFileTransformer

getAllLoadedClasses

Class[] getAllLoadedClasses()

JVM により現在ロードされているすべてのクラスの配列を返します。

戻り値:

JVM によりロードされたすべてのクラスを含む配列。クラスがない場合は長さゼロの配列

getInitiatedClasses

Class[] getInitiatedClasses(ClassLoader loader)

loader が起動ローダであるすべてのクラスの配列を返します。提供されたローダが null の場合、ブートストラップクラスローダにより起動されたクラスが返されます。

パラメータ:

loader - 起動したクラスリストが返されるローダ

戻り値:

ローダが起動ローダであるすべてのクラスを含む配列。クラスがない場合は長さゼロの配列

getObjectSize

long getObjectSize(Object objectToSize)

指定されたオブジェクトにより消費される記憶領域の容量の実装固有の近似値を返します。結果には、オブジェクトのオーバーヘッドの一部またはすべてが含まれる可能性があります。したがって、実装内での比較には役立ちますが、実装間での比較には役立ちません。 JVM の単一の呼び出しの間に近似値が変わる可能性があります。

パラメータ:

objectToSize - サイズを評価するオブジェクト

戻り値:

指定されたオブジェクトにより消費される記憶領域の容量の実装固有の近似値

例外:

NullPointerException - 提供されたオブジェクトが null の場合