JavaTM 2 Platform
Standard Ed. 5.0

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


public interface ClassFileTransformer

クラスファイルを変換するために、このインタフェースの実装を提供するエージェント。変換は、JVM によりクラスが定義される前に発生します。

「クラスファイル」という用語は、『Java 仮想マシン仕様』の「The class File Format」の章の定義に従って使用され、バイトシーケンスがファイルに存在するかどうかにかかわらず、クラスファイル形式のバイトシーケンスを意味します。

導入されたバージョン:
JDK1.5
関連項目:
Instrumentation, Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer), Instrumentation.removeTransformer(java.lang.instrument.ClassFileTransformer)

メソッドの概要
 byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer)
          このメソッドの実装は、提供されたクラスファイルを変換して、新しい置換クラスファイルを返すことができます。
 

メソッドの詳細

transform

byte[] transform(ClassLoader loader,
                 String className,
                 Class<?> classBeingRedefined,
                 ProtectionDomain protectionDomain,
                 byte[] classfileBuffer)
                 throws IllegalClassFormatException
このメソッドの実装は、提供されたクラスファイルを変換して、新しい置換クラスファイルを返すことができます。

トランスフォーマが Instrumentation.addTransformer で登録されると、トランスフォーマは、新しいクラス定義とクラス再定義のたびに呼び出されます。新しいクラス定義の要求は、ClassLoader.defineClass を使って行われます。クラス再定義の要求は、Instrumentation.redefineClasses またはこのネイティブの同等のものを使って行われます。トランスフォーマは、クラスファイルバイトが確認または適用される前に、要求の処理中に呼び出されます。

実装しているメソッドが変換不要と判定すると、メソッドは null を返します。変換が必要と判定すると、メソッドは新しい byte[] 配列を作成し、すべての必要な変換とともに classfileBuffer 入力をその配列の中にコピーし、新しい配列を返します。classfileBuffer 入力は変更されません。

再定義のケースでは、トランスフォーマは、再定義セマンティクスをサポートしなければなりません。初期定義中にトランスフォーマが変更したクラスがあとで再定義される場合、トランスフォーマは、2 番目のクラスの出力クラスファイルで最初の出力クラスファイルが正当に再定義されていることを確認しなければなりません。

classFileBuffer が有効にフォーマットされたクラスファイルを表さないとトランスフォーマが判定した場合、トランスフォーマは IllegalClassFormatException をスローする必要があります。それ以降も、トランスフォーマは呼び出され、ロードや再定義が試行されます。IllegalClassFormatException をスローするのは、null を返すのと同じ効果がありますが、形式に不備のあるログの作成やデバッグを容易にします。

パラメータ:
loader - 変換されるクラスを定義しているローダ。ブートストラップローダの場合は null
className - 『Java 仮想マシン仕様』で定義されている完全修飾クラスの内部形式のクラス名とインタフェース名。たとえば、"java/util/List"
classBeingRedefined - 再定義の場合は、再定義されているクラス、そうでない場合は null
protectionDomain - 定義または再定義されているクラスの保護領域
classfileBuffer - クラスファイル形式の入力バイトバッファ (変更されてはならない)
戻り値:
整形式のクラスファイルバッファ (変換の結果)、変換されなかった場合は null
例外:
IllegalClassFormatException - 入力が整形式のクラスファイルを表さない場合
関連項目:
Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition[])

JavaTM 2 Platform
Standard Ed. 5.0

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。