java.lang.instrument
인터페이스 Instrumentation

public interface Instrumentation

이 클래스는, Java 프로그램 언어 코드를 계측하기 위한 서비스를 제공합니다. Instrumentation이란, 툴로 사용하는 데이터를 수집하는 것을 목적으로 해 메소드에 바이트 코드를 추가하는 것입니다. 변경은 단지 추가되기 (위해)때문에, 이러한 툴은 어플리케이션 상태나 동작을 변경하지 않습니다. 상태나 동작에 영향을 미치지 않는 이런 종류의 툴에는, 감시 에이전트, 프로 filer, 카버리지 analyzer, 및 이벤트 로거등이 있습니다.

Instrumentation 인터페이스의 인스턴스를 취득하는 방법은 2 개 있습니다.

1. 에이전트 클래스를 지정하는 방법으로 JVM 를 기동했을 경우. 이 경우,Instrumentation 인스턴스는, 그 에이전트 클래스의 premain 메소드에게 건네집니다.

2. JVM 의 개시 후에 에이전트를 개시하는 기구가 JVM 에 준비되어 있는 경우. 이 경우,Instrumentation 인스턴스는, 그 에이전트 코드의 agentmain 메소드에게 건네집니다.

이러한 기구는,패키지의 스펙 으로 설명합니다.

에이전트가 Instrumentation 인스턴스를 취득하면(자), 인스턴스상의 메소드를 언제라도 호출할 수가 있습니다.

도입된 버젼:

1.5

메소드의 개요

void	addTransformer (ClassFileTransformer transformer) 제공된 트랜스 포머를 등록합니다.
void	addTransformer (ClassFileTransformer transformer, boolean canRetransform) 제공된 트랜스 포머를 등록합니다.
void	appendToBootstrapClassLoaderSearch (JarFile jarfile) bootstrap 클래스 로더로 정의되는 Instrumentation크라스로 JAR 파일을 지정합니다.
void	appendToSystemClassLoaderSearch (JarFile jarfile) 시스템 클래스 로더로 정의되는 Instrumentation크라스로 JAR 파일을 지정합니다.
Class []	getAllLoadedClasses () JVM 에 의해 현재 로드 사라질 수 있어 모든 클래스의 배열을 돌려줍니다.
Class []	getInitiatedClasses (ClassLoader loader) loader 가 기동 로더인 모든 클래스의 배열을 돌려줍니다.
long	getObjectSize (Object objectToSize) 지정된 객체에 의해 소비되는 기억 영역의 용량의 구현 고유의 근사치를 돌려줍니다.
boolean	isModifiableClass (Class <? > theClass) 클래스가 재변환 또는 재정의 로 변경 가능한가 어떤가를 판정합니다.
boolean	isNativeMethodPrefixSupported () 현재의 JVM 설정으로 네이티브 메소드의 접두사의 설정을 지원하고 있을지 어떨지를 돌려줍니다.
boolean	isRedefineClassesSupported () 현재의 JVM 구성이 클래스의 재정의를 지원하고 있을지 어떨지를 돌려줍니다.
boolean	isRetransformClassesSupported () 현재의 JVM 구성이 클래스의 재변환을 지원하고 있을지 어떨지를 돌려줍니다.
void	redefineClasses (ClassDefinition ... definitions) 제공된 클래스 파일을 사용해 제공된 클래스세트를 재정의합니다.
boolean	removeTransformer (ClassFileTransformer transformer) 제공된 트랜스 포머의 등록을 해제합니다.
void	retransformClasses (Class <? >... classes) 지정된 클래스 세트를 재변환합니다.
void	setNativeMethodPrefix (ClassFileTransformer transformer, String prefix) 이 메소드는, 이름에 접두사를 적용해 재시행할 수 있도록(듯이) 해, 네이티브 메소드 해결의 에러 처리를 변경합니다.

메소드의 상세

addTransformer

void addTransformer(ClassFileTransformer  transformer,
                    boolean canRetransform)

제공된 트랜스 포머를 등록합니다. 이것에 의해, 등록된 트랜스 포머가 의존하는 클래스의 정의를 제외해, 장래의 모든 클래스 정의는 트랜스 포머에 의해 확인됩니다. 트랜스 포머는, 클래스가 재정의 의 경우, 또는 canRetransform 가 true 라면 클래스가 재변환 의 경우에, 클래스의 로드시에 불려 갑니다. 변환이 불려 가는 순서에 대해서는,ClassFileTransformer.transform 를 참조해 주세요. 트랜스 포머가 실행중에 예외를 throw 하면(자), JVM 는 등록되어 있는 그 외의 트랜스 포머를 순서에 호출합니다. 같은 트랜스 포머를 여러 차례 추가할 수 있습니다만, 그렇게 해야 하는 것이 아닙니다. 이것을 피하려면 , 트랜스 포머 클래스의 새로운 인스턴스를 작성해 주세요.

이 메소드는,class specification 로 기술되고 있도록(듯이), Instrumentation으로 사용하는 것입니다.

파라미터:

transformer - 등록하는 트랜스 포머

canRetransform - 이 트랜스 포머의 변환을 재변환할 수 있을지 어떨지

예외:

NullPointerException - null 트랜스 포머를 건네주었을 경우

UnsupportedOperationException - canRetransform 가 true 이며, JVM 의 현재의 설정이 재변환 (isRetransformClassesSupported() 가 false)를 허가하지 않는 경우

도입된 버젼:

1.6

addTransformer

void addTransformer(ClassFileTransformer  transformer)

제공된 트랜스 포머를 등록합니다.

addTransformer(transformer, false) 와 같습니다.

파라미터:

transformer - 등록하는 트랜스 포머

예외:

NullPointerException - null 트랜스 포머를 건네주었을 경우

관련 항목:

addTransformer(ClassFileTransformer, boolean)

removeTransformer

boolean removeTransformer(ClassFileTransformer  transformer)

제공된 트랜스 포머의 등록을 해제합니다. 등록 해제된 트랜스 포머는, 장래 클래스 정의를 확인할 수 없게 됩니다. 직전에 추가된 일치하는 트랜스 포머의 인스턴스를 삭제합니다. 클래스 로딩의 multi-thread적 성질에 의해, 삭제된 후에도 트랜스 포머를 호출할 수가 있습니다. 이러한 상황을 고려해, 신중하게 트랜스 포머를 기술할 필요가 있습니다.

파라미터:

transformer - 등록을 해제하는 트랜스 포머

반환값:

트랜스 포머가 발견되어, 삭제되었을 경우는 true. 트랜스 포머가 발견되지 않았던 경우는 false

예외:

NullPointerException - null 트랜스 포머를 건네주었을 경우

isRetransformClassesSupported

boolean isRetransformClassesSupported()

현재의 JVM 구성이 클래스의 재변환을 지원하고 있을지 어떨지를 돌려줍니다. 벌써 로드 되고 있는 클래스를 재변환하는 기능은, JVM 의 옵션의 기능입니다. 재변환이 지원되는 것은, 에이전트 JAR 파일로 Can-Retransform-Classes Manifest 속성이 true 로 설정되어 있어 (package specification 참조), 한편 JVM 가 이 기능을 지원하고 있는 경우에 한정됩니다. 단일의 JVM 의 1 개의 인스턴스 생성동안에, 이 메소드에 복수의 호출을 실시하면, 항상 같은 대답이 돌려주어집니다.

반환값:

현재의 JVM 구성이 클래스의 재변환을 지원하는 경우는 true, 지원하지 않는 경우는 false

도입된 버젼:

1.6

관련 항목:

retransformClasses(java.lang.Class...)

retransformClasses

void retransformClasses(Class <? >... classes)
                        throws UnmodifiableClassException 

지정된 클래스 세트를 재변환합니다.

이 기능은, 벌써 로드 끝난 클래스의 Instrumentation을 용이하게 합니다. 클래스가 최초로 로드 되었을 때, 또는 클래스가 재정의 일 때, 초기 클래스 파일 바이트는 ClassFileTransformer 로 변환할 수 있습니다. 이 함수는, 변환이 이전 행해졌는지 어떠했는지에는 관계없이, 변환 처리를 재실행합니다. 이 재변환은 다음의 순서로 행해집니다.

• 초기 클래스 파일 바이트로부터 개시한다
• canRetransform 가 false 로 추가된 트랜스 포머 마다, 마지막 클래스의 로드 또는 재정의중에 변환 으로 반환되는 바이트가 변환의 출력으로서 재사용된다. 이것은 전회의 변환을 그대로재적용하는 것과 같다. 다만,변환 이 불려 가지 않는 점이 다르다
• canRetransform 가 true 로 추가된 트랜스 포머 마다, 트랜스 포머내에서 변환 메소드가 불려 간다
• 변환된 클래스 파일 바이트는, 클래스의 새로운 정의로서 인스톨 된다

변환의 순서에 대해서는,변환 메소드로 설명하고 있습니다. 재변환 불가능 트랜스 포머의 자동재적용에서도, 같은 순서가 사용됩니다.

초기 클래스 파일 바이트는,ClassLoader.defineClass 또는 redefineClasses (변환의 적용전)에게 건네지는 바이트를 나타냅니다. 다만, 정확하게 일치하지 않는 것이 있습니다. 정수 풀은 같은 레이아웃 또는 내용이다고는 할 수 없습니다. 정수 풀의 엔트리수가 다를 가능성이 있습니다. 정수 풀의 엔트리의 순서가 다른 일이 있습니다. 다만, 메소드의 바이트 코드로 정수 풀의 인덱스는 대응합니다. 일부의 속성은 존재하지 않을 가능성이 있습니다. 순서가 중요하지 않은 경우 (메소드의 순서 등), 순서가 유지되지 않는 경우가 있습니다.

이 메소드는, 동시에 1 개(살) 이상의 클래스에 대해서 상호의존의 관계에 있는 변경 (클래스 A 의 재변환은 클래스 B 의 재변환을 필요로 하는 등)을 가능하게 하기 위해서 세트상에서 동작합니다.

재변환된 메소드가 액티브한 스택 프레임을 가지는 경우, 액티브한 스택 프레임은 원의 메소드의 바이트 코드를 계속해 실행합니다. 재변환된 메소드는 새로운 호출로 사용됩니다.

이 메소드는, 관행의 JVM 시멘틱스아래에서 발생하는 초기화를 제외해, 초기화를 발생시키지 않습니다. 즉, 클래스의 재정의에서는, 클래스의 초기화자는 실행되지 않습니다. static 변수의 값은 호출해 전의 값대로 유지됩니다.

재변환된 클래스의 인스턴스는 영향을 받지 않습니다.

재변환에서는, 메소드의 본문, 정수 풀, 및 속성의 변경이 가능합니다. 다만, 재변환에서는, 필드 또는 메소드의 추가, 삭제, 혹은 이름의 변경, 메소드의 시그니챠의 변경, 혹은 상속의 변경은 할 수 없습니다. 이러한 제약은, 장래 버젼으로 해소될 가능성이 있습니다. 클래스 바이트 파일이 체크, 검증, 및 인스톨 되는 것은, 변환의 적용 나중이 됩니다. 얻을 수 있는 바이트가 에러가 되면(자), 이 메소드는 예외를 throw 합니다.

이 메소드가 예외를 throw 했을 경우, 클래스의 재변환은 행해지지 않습니다.

이 메소드는,class specification 로 기술되고 있도록(듯이), Instrumentation으로 사용하는 것입니다.

파라미터:

classes - 재변환하는 클래스의 배열. 길이 제로의 배열은 사용할 수 있지만, 사용했을 경우, 이 메소드는 아무것도 실행하지 않는다

예외:

UnmodifiableClassException - 지정된 클래스를 변경할 수 없는 경우 (isModifiableClass(java.lang.Class) (은)는 false 를 돌려준다)

UnsupportedOperationException - JVM 의 현재의 설정이 재변환 (isRetransformClassesSupported() 가 false)를 허가하지 않는지, 재변환으로 지원되지 않는 변경을 더하려고 했을 경우

ClassFormatError - 데이터가 유효한 클래스를 포함하지 않았던 경우

NoClassDefFoundError - 클래스 파일의 이름이 클래스의 이름과 동일하지 않은 경우

UnsupportedClassVersionError - 클래스 파일 버젼 번호가 지원되어 있지 않은 경우

ClassCircularityError - 새로운 클래스가 순환을 포함한 경우

LinkageError - 링키지 에러가 발생했을 경우

NullPointerException - 제공된 클래스 배열 또는 그 컴퍼넌트중 한쪽이 null 의 경우

도입된 버젼:

1.6

관련 항목:

isRetransformClassesSupported() , addTransformer(java.lang.instrument.ClassFileTransformer, boolean) , ClassFileTransformer

isRedefineClassesSupported

boolean isRedefineClassesSupported()

현재의 JVM 구성이 클래스의 재정의를 지원하고 있을지 어떨지를 돌려줍니다. 벌써 로드 되고 있는 클래스를 재정의하는 기능은, JVM 의 옵션의 기능입니다. 재정의가 지원되는 것은, 에이전트 JAR 파일로 Can-Redefine-Classes Manifest 속성이 true 로 설정되어 있어 (package specification 참조), 한편 JVM 가 이 기능을 지원하고 있는 경우에 한정됩니다. 단일의 JVM 의 1 개의 인스턴스 생성동안에, 이 메소드에 복수의 호출을 실시하면, 항상 같은 대답이 돌려주어집니다.

반환값:

현재의 JVM 구성이 클래스의 재정의를 지원하는 경우는 true, 지원하지 않는 경우는 false

관련 항목:

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

redefineClasses

void redefineClasses(ClassDefinition ... definitions)
                     throws ClassNotFoundException ,
                            UnmodifiableClassException 

제공된 클래스 파일을 사용해 제공된 클래스세트를 재정의합니다.

이 메소드를 사용해, 기존의 클래스 파일 바이트에의 참조가 없는 클래스의 정의를 옮겨놓습니다. 순서대로 디버그를 실시하기 위해서(때문에) 소스로부터 재컴파일 할 경우에 치환을 합니다. 기존의 클래스 파일 바이트가 변환되는 경우는 (바이트 코드의 Instrumentation내 등),retransformClasses 를 사용해 주세요.

이 메소드는, 동시에 1 개(살) 이상의 클래스에 대해서 상호의존의 관계에 있는 변경 (클래스 A 의 재정의는 클래스 B 의 재정의를 필요로 하는 등)을 가능하게 하기 위해서 세트상에서 동작합니다.

재정의된 메소드가 액티브한 스택 프레임을 가지는 경우, 액티브한 스택 프레임은 원의 메소드의 바이트 코드를 계속해 실행합니다. 재정의된 메소드는 새로운 호출로 사용됩니다.

이 메소드는, 관행의 JVM 시멘틱스아래에서 발생하는 초기화를 제외해, 초기화를 발생시키지 않습니다. 즉, 클래스의 재정의에서는, 클래스의 초기화자는 실행되지 않습니다. static 변수의 값은 호출해 전의 값대로 유지됩니다.

재정의된 클래스의 인스턴스는 영향을 받지 않습니다.

재정의에서는, 메소드의 본문, 정수 풀, 및 속성의 변경이 가능합니다. 다만, 재정의에서는, 필드 또는 메소드의 추가, 삭제, 혹은 이름의 변경, 메소드의 시그니챠의 변경, 혹은 상속의 변경은 할 수 없습니다. 이러한 제약은, 장래 버젼으로 해소될 가능성이 있습니다. 클래스 바이트 파일이 체크, 검증, 및 인스톨 되는 것은, 변환의 적용 나중이 됩니다. 얻을 수 있는 바이트가 에러가 되면(자), 이 메소드는 예외를 throw 합니다.

이 메소드가 예외를 throw 했을 경우, 클래스의 재정의는 행해지지 않습니다.

이 메소드는,class specification 로 기술되고 있도록(듯이), Instrumentation으로 사용하는 것입니다.

파라미터:

definitions - 대응하는 정의를 사용해 재정의하는 클래스의 배열. 길이 제로의 배열은 사용할 수 있지만, 사용했을 경우, 이 메소드는 아무것도 실행하지 않는다

예외:

UnmodifiableClassException - 지정된 클래스를 변경할 수 없는 경우 (isModifiableClass(java.lang.Class) (은)는 false 를 돌려준다)

UnsupportedOperationException - JVM 의 현재의 설정이 재정의 (isRedefineClassesSupported() 가 false)를 허가하지 않는지, 재정의로 지원되지 않는 변경을 더하려고 했을 경우

ClassFormatError - 데이터가 유효한 클래스를 포함하지 않았던 경우

NoClassDefFoundError - 클래스 파일의 이름이 클래스의 이름과 동일하지 않은 경우

UnsupportedClassVersionError - 클래스 파일 버젼 번호가 지원되어 있지 않은 경우

ClassCircularityError - 새로운 클래스가 순환을 포함한 경우

LinkageError - 링키지 에러가 발생했을 경우

NullPointerException - 제공된 정의 배열 또는 그 컴퍼넌트중 한쪽이 null 의 경우

ClassNotFoundException - throw 할 수 없는 (호환성을 유지하기 위해서 마셔 존재한다)

관련 항목:

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

isModifiableClass

boolean isModifiableClass(Class <? > theClass)

클래스가 재변환 또는 재정의 로 변경 가능한가 어떤가를 판정합니다. 클래스가 변경 가능한 경우, 이 메소드는 true 를 돌려줍니다. 클래스가 변경 불가능한 경우, 이 메소드는 false 를 돌려줍니다.

재변환되는 클래스에서는,isRetransformClassesSupported() 도 true 일 필요가 있습니다. 다만,isRetransformClassesSupported() 의 값은, 이 함수가 돌려주는 값에 영향 없습니다. 재정의되는 클래스에서는,isRedefineClassesSupported() 도 true 일 필요가 있습니다. 다만,isRedefineClassesSupported() 의 값은, 이 함수가 돌려주는 값에 영향 없습니다.

java.lang.Integer.TYPE 등의 프리미티브(primitive) 클래스와 배열 클래스가 변경 가능하게 될 것은 없습니다.

예외:

NullPointerException - 지정된 클래스가 null 인 경우

도입된 버젼:

1.6

관련 항목:

retransformClasses(java.lang.Class...) , isRetransformClassesSupported() , redefineClasses(java.lang.instrument.ClassDefinition...) , isRedefineClassesSupported()

getAllLoadedClasses

Class [] getAllLoadedClasses()

JVM 에 의해 현재 로드 사라질 수 있어 모든 클래스의 배열을 돌려줍니다.

반환값:

JVM 에 의해 로드 된 모든 클래스를 포함한 배열. 클래스가 없는 경우는 길이 제로의 배열

getInitiatedClasses

Class [] getInitiatedClasses(ClassLoader  loader)

loader 가 기동 로더인 모든 클래스의 배열을 돌려줍니다. 제공된 로더가 null 의 경우, bootstrap 클래스 로더에 의해 기동된 클래스가 돌려주어집니다.

파라미터:

loader - 기동한 클래스 리스트가 반환되는 로더

반환값:

로더가 기동 로더인 모든 클래스를 포함한 배열. 클래스가 없는 경우는 길이 제로의 배열

getObjectSize

long getObjectSize(Object  objectToSize)

지정된 객체에 의해 소비되는 기억 영역의 용량의 구현 고유의 근사치를 돌려줍니다. 결과에는, 객체의 오버헤드의 일부 또는 모든 것이 포함될 가능성이 있습니다. 따라서, 구현내에서의 비교에는 도움이 됩니다만, 구현간에서의 비교에는 도움이 되지 않습니다. JVM 의 단일의 호출동안에 근사치가 바뀔 가능성이 있습니다.

파라미터:

objectToSize - 사이즈를 평가하는 객체

반환값:

지정된 객체에 의해 소비되는 기억 영역의 용량의 구현 고유의 근사치

예외:

NullPointerException - 제공된 객체가 null 의 경우

appendToBootstrapClassLoaderSearch

void appendToBootstrapClassLoaderSearch(JarFile  jarfile)

bootstrap 클래스 로더로 정의되는 Instrumentation크라스로 JAR 파일을 지정합니다.

「bootstrap 클래스 로더」라고 불리는 가상 머신의 편입 클래스 로더가 클래스의 검색에 실패하면(자),JAR 파일 내의 엔트리도 검색됩니다.

이 메소드를 여러 차례 사용해, 이 메소드가 불려 가는 순서로 검색되는 복수의 JAR 파일을 추가할 수 있습니다.

Instrumentation을 하기 위해서, 에이전트에서는 JAR 파일에 bootstrap 클래스 로더로 정의되는 이외의 클래스 또는 자원이 포함되지 않는 것을 확인해 주세요. 이 경고의 감시에 실패하면(자), 진단하는 것이 곤란한 예기치 않은 동작이 되는 일이 있습니다. 예를 들어 로더 L 가 있어, 위양을 위한 L 의 부모가 bootstrap 클래스 로더이다고 합니다. 또, 클래스 C 가 L 로 정의되어 클래스 C 의 메소드가 public 가 아닌 액세스용 클래스 C$1 를 참조한다고 합니다. JAR 파일에 클래스 C$1 가 포함되는 경우, bootstrap 클래스 로더에의 위양에 의해, C$1 가 bootstrap 클래스 로더에 의해 정의됩니다. 이 예에서는 IllegalAccessError 가 throw 되어 어플리케이션이 실패합니다. 이러한 문제를 피하는 1 개의 방법으로서 Instrumentation크라스에 일의의 패키지명을 사용합니다.

「Java 가상 머신 스펙」에 의하면,Java 가상 머신이 이전에 상징적 참조를 해결하려고 해 실패했을 경우, 그 후 이 상징적 참조를 해결하려고 해도 반드시 실패해, 최초로 해결하려고 한 결과적으로 throw 된 에러와 같은 에러가 됩니다. 따라서, Java 가상 머신이 참조를 해결할 수 없었던 클래스에 대응하는 엔트리가 JAR 파일에 포함되는 경우, 그 참조를 해결하려고 해도 최초의 에러와 같은 에러로 실패합니다.

파라미터:

jarfile - bootstrap 클래스 로더가 클래스의 검색에 실패했을 때에 검색되는 JAR 파일

예외:

NullPointerException - jarfile 가 null 의 경우

도입된 버젼:

1.6

관련 항목:

appendToSystemClassLoaderSearch(java.util.jar.JarFile) , ClassLoader , JarFile

appendToSystemClassLoaderSearch

void appendToSystemClassLoaderSearch(JarFile  jarfile)

시스템 클래스 로더로 정의되는 Instrumentation크라스로 JAR 파일을 지정합니다. 위양용의 시스템 클래스 로더 (getSystemClassLoader() 를 참조)가 클래스의 검색에 실패했을 때에,JarFile 내의 엔트리도 검색됩니다.

이 메소드를 여러 차례 사용해, 이 메소드가 불려 가는 순서로 검색되는 복수의 JAR 파일을 추가할 수 있습니다.

Instrumentation 하기 위해서, 에이전트는 JAR 파일에 시스템 클래스 로더로 정의되는 이외의 클래스 또는 자원이 포함되지 않는 것을 확인할 필요가 있습니다. 이 경고의 감시에 실패하면(자), 진단하는 것이 곤란한 예기치 않은 동작이 되는 일이 있습니다 (appendToBootstrapClassLoaderSearch 를 참조).

시스템 클래스 로더에 appendToClassPathForInstrumentation 메소드가 구현되고 있는 경우는, 검색되는 JAR 파일의 추가가 지원됩니다. 이 메소드는 java.lang.String 형의 파라미터 1 개(살)을 취합니다. public 액세스를 하려면 이 메소드는 필요 없습니다. JAR 파일의 이름은,jarfile 의 getName() 메소드를 호출하는 것으로 취득되어jarfile 는 appendtoClassPathForInstrumentation 메소드의 파라미터로서 제공됩니다.

「Java 가상 머신 스펙」에 의하면,Java 가상 머신이 이전에 상징적 참조를 해결하려고 해 실패했을 경우, 그 후 이 상징적 참조를 해결하려고 해도 반드시 실패해, 최초로 해결하려고 한 결과적으로 throw 된 에러와 같은 에러가 됩니다. 따라서, Java 가상 머신이 참조를 해결할 수 없었던 클래스에 대응하는 엔트리가 JAR 파일에 포함되는 경우, 그 참조를 해결하려고 해도 최초의 에러와 같은 에러로 실패합니다.

이 메소드는 java.class.path 시스템 프로퍼티 의 값을 변경하지 않습니다.

파라미터:

jarfile - 시스템 클래스 로더가 클래스의 검색에 실패했을 때에 검색되는 JAR 파일

예외:

UnsupportedOperationException - 시스템 클래스 로더가 검색되는 JAR 파일의 추가를 지원하고 있지 않는 경우

NullPointerException - jarfile 가 null 의 경우

도입된 버젼:

1.6

관련 항목:

appendToBootstrapClassLoaderSearch(java.util.jar.JarFile) , ClassLoader.getSystemClassLoader() , JarFile

isNativeMethodPrefixSupported

boolean isNativeMethodPrefixSupported()

현재의 JVM 설정으로 네이티브 메소드의 접두사의 설정을 지원하고 있을지 어떨지를 돌려줍니다. 네이티브 메소드의 접두사를 설정하는 기능은, JVM 의 옵션 기능입니다. 네이티브 메소드의 접두사의 설정이 지원되는 것은, 에이전트 JAR 파일로 Can-Set-Native-Method-Prefix Manifest 속성이 true 로 설정되어 있어 (package specification 참조), 한편 JVM 가 이 기능을 지원하고 있는 경우에 한정됩니다. 단일의 JVM 의 1 개의 인스턴스 생성동안에, 이 메소드에 복수의 호출을 실시하면, 항상 같은 대답이 돌려주어집니다.

반환값:

현재의 JVM 설정이 네이티브 메소드의 접두사의 설정을 지원하는 경우는 true, 지원하지 않는 경우는 false

도입된 버젼:

1.6

관련 항목:

setNativeMethodPrefix(java.lang.instrument.ClassFileTransformer, java.lang.String)

setNativeMethodPrefix

void setNativeMethodPrefix(ClassFileTransformer  transformer,
                           String  prefix)

이 메소드는, 이름에 접두사를 적용해 재시행할 수 있도록(듯이) 해, 네이티브 메소드 해결의 에러 처리를 변경합니다. ClassFileTransformer 에 사용하면(자), 네이티브 메소드를 Instrumentation 할 수 있습니다.

네이티브 메소드는 직접 Instrumentation 할 수 없기 때문에 (바이트 코드가 없기 때문에), Instrumentation 가능한 네이티브가 아닌 메소드로 랩 할 필요가 있습니다. 예를 들어 다음의 메소드를 생각해 보겠습니다.

native boolean foo(int x);

클래스의 초기 정의시에 ClassFileTransformer 를 사용해 클래스 파일을 변환하면(자) 다음과 같이 됩니다.

boolean foo(int x) {
... record entry to foo ...
return wrapped_foo(x);
   }
   
native boolean wrapped_foo(int x);

여기서 foo 는 실제의 네이티브 메소드의 래퍼로, 접두사 「wrapped_」가 붙일 수 있고 있습니다. 「wrapped_」는, 기존의 메소드의 이름으로서 사용되고 있는 것이 상상할 수 있기 (위해)때문에, 접두사가 좋은 예가 아닙니다. 「$$$MyAgentWrapped$$$_」와 같이 하면 좋습니다만, 여기의 예에서는 보기 나뻐집니다.

래퍼는 네이티브 메소드 호출로 데이터를 수집할 수 있습니다만, 랩 된 메소드와 네이티브 구현을 묶는 것이 문제가 됩니다. 즉,wrapped_foo 메소드는, 예를 들어 다음과 같은 foo 의 네이티브 구현에 해결될 필요가 있습니다.

Java_somePackage_someClass_foo(JNIEnv* env, jint x)

이 함수에서는 접두사를 지정할 수 있어 적절한 해결을 합니다. 구체적으로는, 표준의 해결에 실패하면(자), 접두사를 고려해 해결이 재시행됩니다. 해결에는 2 개의 방법이 있습니다. JNI 함수 RegisterNatives 를 사용한 명시적인 해결과 일반적으로의 자동 해결입니다. RegisterNatives 를 사용하는 경우, JVM 에서는 다음이 관련짓고를 실시하려고 합니다.

method(foo) -> nativeImplementation(foo)

이것에 실패하면(자), 지정된 접두사를 메소드명의 전에 붙여 해결이 재시행되어 다음과 같은 올바른 해결을 얻을 수 있습니다.

method(wrapped_foo) -> nativeImplementation(foo)

자동 해결에서는, JVM 는 다음이 관련짓고를 실시하려고 합니다.

method(wrapped_foo) -> nativeImplementation(wrapped_foo)

이것에 실패하면(자), 지정된 접두사가 구현명으로부터 삭제되어 해결이 재시행되어 다음과 같은 올바른 해결을 얻을 수 있습니다.

method(wrapped_foo) -> nativeImplementation(foo)

접두사는 표준의 해결에 실패했을 때에 마셔 사용되기 (위해)때문에, 네이티브 메소드를 선택적으로 랩 할 수 있습니다.

각 ClassFileTransformer 에서는, 독자적인 바이트 코드 변환을 실시할 수가 있기 (위해)때문에, 복수 층의 래퍼를 적용할 수 있습니다. 그 때문에, 각 트랜스 포머에는 전용의 접두사가 필요합니다. 변환은 차례로 적용되기 (위해)때문에, 접두사가 적용되는 경우는, 같은 순서로 적용됩니다 (addTransformer 를 참조). 즉 3 개의 트랜스 포머에 의해 래퍼가 적용되면(자),foo 는 $trans3_$trans2_$trans1_foo 와 같이 됩니다. 다만, 2 번째의 트랜스 포머로 foo 에 래퍼가 적용되지 않았던 경우는,$trans3_$trans1_foo 와 같이 됩니다. 접두사의 순서를 효율적으로 판단할 수 있도록(듯이), 중간에 오는 접두사는 네이티브가 아닌 래퍼가 존재하는 경우만 적용됩니다. 즉 이 예에서는,$trans1_foo 가 네이티브 메소드가 아니어도,$trans1_foo 가 존재하기 위해(때문에) $trans1_ 접두사가 적용됩니다.

파라미터:

transformer - 이 접두사를 사용해 랩 하는 ClassFileTransformer

prefix - 랩 된 네이티브 메소드에 적용된 접두사

예외:

NullPointerException - null 트랜스 포머를 건네주었을 경우

UnsupportedOperationException - JVM 의 현재의 설정이 네이티브 메소드의 접두사 (isNativeMethodPrefixSupported() 가 false)의 설정을 허가하지 않는 경우

IllegalArgumentException - 트랜스 포머가 등록되지 않은 경우 (addTransformer 를 참조)

도입된 버젼:

1.6