java.lang.instrument
인터페이스 ClassFileTransformer

public interface ClassFileTransformer

클래스 파일을 변환하기 위해서, 이 인터페이스의 구현을 제공하는 에이전트. 변환은, JVM 에 의해 클래스가 정의되기 전에 발생합니다.

「클래스 파일」이라고 하는 용어는, 「Java 가상 머신 스펙」의「The class File Format」의 장의 정의에 따라 사용되어 바이트 순서가 파일에 존재할지 어떨지에 관계없이, 클래스 파일 형식의 바이트 순서를 의미합니다.

도입된 버젼:

1.5

관련 항목:

Instrumentation , Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer, boolean) , 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(ClassFileTransformer, boolean) 의 canRetransform 파라미터에 응해 2 종류의 트랜스 포머가 있습니다.

• true 로서 canRetransform 에 추가된 재변환 가능 트랜스 포머.
• false 로서 canRetransform 에 추가된, 또는 Instrumentation.addTransformer(ClassFileTransformer) 에 추가된, 재변환 불가능 트랜스 포머.

트랜스 포머가 addTransformer 로 등록되면(자), 트랜스 포머는, 새로운 클래스 정의와 클래스재정의마다 불려 갑니다. 재변환 가능 트랜스 포머는, 클래스의 재변환마다도 불려 갑니다. 새로운 클래스 정의의 요구는,ClassLoader.defineClass 또는 이 네이티브의 동등의 것을 사용해 행해집니다. 클래스재정의의 요구는,Instrumentation.redefineClasses 또는 이 네이티브의 동등의 것을 사용해 행해집니다. 클래스재변환의 요구는,Instrumentation.retransformClasses 또는 이 네이티브의 동등의 것을 사용해 행해집니다. 트랜스 포머는, 클래스 파일 바이트가 확인 또는 적용되기 전에, 요구의 처리중에 불려 갑니다. 복수의 트랜스 포머가 존재하는 경우, 변환은 transform 호출의 체인에 의해 구성됩니다. 즉,transform 의 호출에 의해 반환되는 바이트 배열은,classfileBuffer 파라미터를 개입시켜, 그 다음의 호출의 입력이 됩니다.

변환은 다음의 순서로 적용됩니다.

• 재변환 불가능 트랜스 포머
• 재변환 불가능 네이티브 트랜스 포머
• 재변환 가능 트랜스 포머
• 재변환 가능 네이티브 트랜스 포머

재변환에서는, 재변환 불가능 트랜스 포머는 불려 가지 않고, 직전의 변환 결과가 재사용됩니다. 그 이외의 경우는, 이 메소드가 불려 갑니다. 트랜스 포머의 각각의 종류내에서는, 등록된 순서로 트랜스 포머가 불려 갑니다. 네이티브 트랜스 포머는 Java 가상 머신 툴 인터페이스의 ClassFileLoadHook 이벤트로 제공됩니다.

최초의 트랜스 포머에의 입력은,classfileBuffer 파라미터를 개입시켜 건네받아 다음과 같이 됩니다.

• 새로운 클래스 정의의 경우는,ClassLoader.defineClass 에게 건네지는 바이트
• 클래스재정의의 경우는,definitions.getDefinitionClassFile(). 여기서,definitions 는 Instrumentation.redefineClasses 의 파라미터
• 클래스재변환의 경우는, 새로운 클래스 정의에게 건네지는 바이트. 재정의되었을 경우는 최신의 재정의. 어느 경우도, 재변환 불가능 트랜스 포머에 의해 행해지는 모든 변환이 그대로 자동적으로 재적용되어 불변이다. 상세한 것에 대하여는,Instrumentation.retransformClasses 를 참조

구현하고 있는 메소드가 변환 불요로 판정하면(자), 메소드는 null 를 돌려줍니다. 변환이 필요로 판정하면(자), 메소드는 새로운 byte[] 배열을 작성해, 모든 필요한 변환과 함께 classfileBuffer 입력을 그 배열안에 카피해, 새로운 배열을 돌려줍니다. classfileBuffer 입력은 변경되지 않습니다.

재변환과 재정의의 케이스에서는, 트랜스 포머는, 재정의 시멘틱스를 지원하지 않으면 안됩니다. 초기 정의중에 트랜스 포머가 변경한 클래스가 나중에 재변환 또는 재정의되는 경우, 트랜스 포머는, 2 번째의 클래스의 출력 클래스 파일로 최초의 출력 클래스 파일이 정당하게 재정의되고 있는 것을 확인하지 않으면 안됩니다.

트랜스 포머가 캐치 하지 않는 예외를 throw 하는 경우는, 그 이후도 트랜스 포머가 불려 가 로드나 재정의가 시행됩니다. 이 때문에, 예외를 throw 하는 것은 null 를 돌려주는 것과 같게 됩니다. 체크되지 않는 예외가 트랜스 포머 코드로 생성될 때 예기치 않은 동작이 일어나지 않게 하기 위한(해), 트랜스 포머는 Throwable 를 캐치 할 수가 있습니다. classFileBuffer 가 유효하게 포맷 된 클래스 파일을 나타내지 않으면 트랜스 포머가 판정했을 경우, 트랜스 포머는 IllegalClassFormatException 를 throw 할 필요가 있습니다. 이것에는 null 를 돌려주는 것과 같은 효과가 있습니다만, 형식의 미비에 대한 로그의 작성이나 디버그를 용이하게 합니다.

파라미터:

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

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

classBeingRedefined - 재정의 또는 재변환에 의해 트리거되었을 경우는, 재정의 또는 재변환되고 있는 클래스. 이것이 클래스 로드의 경우는,null

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

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

반환값:

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

예외:

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

관련 항목:

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