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을 Throw 할 필요가 있습니다. 그 이후도, 트랜스 포머는 불려가 로드나 재정의가 시행됩니다. IllegalClassFormatException을 Throw 하는 것은 null을 돌려주는 것과 같은 효과가 있습니다만, 형식에 미비가 있는 로그의 작성이나 디버그를 용이하게 합니다.

파라미터:

loader - 변환되는 클래스를 정의하고 있는 로더. bootstrap loader의 경우는 null

className - 「Java 가상 머신 사양」으로 정의되고 있는 완전 수식 클래스의 내부 형식의 클래스명과 인터페이스명. 예를 들어, "java/util/List"

classBeingRedefined - 재정의의 경우는 재정의되고 있는 클래스, 그렇지 않은 경우는 null

protectionDomain - 정의 또는 재정의되고 있는 클래스의 보호 영역

classfileBuffer - 클래스 파일 형식의 입력 바이트 버퍼 (변경되어서는 안 된다)

반환값:

정형식의 클래스 파일 버퍼 (변환의 결과), 변환되지 않았던 경우는 null

예외:

IllegalClassFormatException - 입력이 정형식의 클래스 파일을 나타내지 않는 경우

관련 항목:

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