패키지 java.lang.instrument

Java 프로그램 언어 에이전트가 JVM 상에서 실행되고 있는 프로그램을 계측 할 수 있도록(듯이) 하는 서비스를 제공합니다.

참조처:
설명

인터페이스의 개요

ClassFileTransformer	클래스 파일을 변환하기 위해서, 이 인터페이스의 구현을 제공하는 에이전트.
Instrumentation	이 클래스는, Java 프로그램 언어 코드를 계측하기 위한 서비스를 제공합니다.

클래스의 개요

ClassDefinition

이 클래스는,Instrumentation.redefineClasses 메소드에 대한 파라미터 블록으로서 기능합니다.

예외의 개요

IllegalClassFormatException	입력 파라미터가 무효인 경우에,ClassFileTransformer.transform 의 구현에 의해 throw 됩니다.
UnmodifiableClassException	지정된 클래스의 1 개를 변경할 수 없는 경우,Instrumentation.redefineClasses 의 구현에 의해 throw 됩니다.

패키지 java.lang.instrument 의 설명

Java 프로그램 언어 에이전트가 JVM 상에서 실행되고 있는 프로그램을 계측 할 수 있도록(듯이) 하는 서비스를 제공합니다. Instrumentation의 메카니즘은, 메소드의 바이트 코드의 변경입니다.

패키지의 스펙

에이전트는 JAR 파일로서 배치됩니다. JAR 파일의 Manifest의 속성은, 에이전트를 개시하기 위해서 로드 되는 에이전트 클래스를 지정합니다. 커멘드행 인터페이스를 지원하는 구현에서는, 커멘드행으로 옵션을 지정하는 방법으로 에이전트를 개시합니다. 구현에 따라서는, VM 의 개시 후에 에이전트를 개시하는 기구도 지원하고 있는 경우가 있습니다. 예를 들어, 실행중의 어플리케이션에 툴을 접속해, 툴의 에이전트를 그 어플리케이션에 로드해 시작할 수 있는 것 같은 기구를 제공할 수 있는 구현도 있습니다. 로드의 개시 방법의 자세한 것은, 구현에 따라서 다릅니다.

커멘드행 인터페이스

커멘드행 인터페이스를 지원하는 구현에서는, 이 옵션을 커멘드행에 추가하는 방법으로 에이전트를 개시합니다.

-javaagent:jarpath[=options]

jarpath 는 에이전트 JAR 파일의 패스입니다. options 는 에이전트의 옵션입니다. 이 스윗치는, 1 개의 커멘드행으로 여러 차례 사용할 수 있기 (위해)때문에, 복수의 에이전트를 작성할 수 있습니다. 복수의 에이전트로 같은 jarpath 를 사용할 수 있습니다. 에이전트 JAR 파일은 JAR 파일 스펙에 따를 필요가 있습니다.

에이전트 JAR 파일의 Manifest에는 속성 Premain-Class 가 포함될 필요가 있습니다. 이 속성의 값은, 에이전트 클래스의 이름. 에이전트 클래스는, 기본적으로 main 어플리케이션 엔트리 포인트와 같은 public static premain 메소드를 구현할 필요가 있습니다. Java 가상 머신 (JVM)이 초기화되면(자), 에이전트가 지정된 순서로 각 premain 메소드가 불려 가 다음에 실제의 어플리케이션의 main 메소드가 불려 갑니다. 각 premain 메소드는, 기동 순서가 실행되는 순서로 돌려주어지지 않으면 안됩니다.

premain 메소드에는 2 개의 시그니챠 가운데중 한쪽이 있습니다. JVM 는 에이전트 클래스에서 최초로 다음의 메소드를 호출하려고 합니다.

public static void premain(String agentArgs, Instrumentation inst);

에이전트 클래스에 이 메소드가 구현되어 있지 않은 경우는, 다음의 메소드를 호출하려고 합니다.

public static void premain(String agentArgs);

에이전트 클래스에는 agentmain 메소드가 준비되어 있는 경우도 있습니다. 이 메소드는 VM 의 개시 후에 에이전트를 개시할 경우에 사용합니다. 커멘드행 옵션을 사용해 에이전트를 개시했을 경우는,agentmain 메소드가 불려 가지 않습니다.

에이전트 클래스는 시스템 클래스 로더에 의해 로드 됩니다 (ClassLoader.getSystemClassLoader 를 참조). 이 클래스 로더는, 일반적으로, 어플리케이션 main 메소드를 포함한 클래스를 로드합니다. premain 메소드는, 어플리케이션 main 메소드와 같은 시큐리티 규칙과 클래스 로더 규칙으로 실행됩니다. 에이전트 premain 메소드의 실행 내용에 관한 모델링 제약은 없습니다. 작성측 thread를 포함해 어플리케이션 main 를 실행할 수 있는 것은, 모두 premain 로 유효합니다.

각 에이전트는,agentArgs 파라미터 경유로 에이전트 옵션이 건네받습니다. 에이전트 옵션은 단일의 캐릭터 라인으로서 건네받아 추가의 해석은 에이전트 자신에 의해 행해집니다.

에이전트를 해결할 수 없는 경우 (예를 들어 에이전트 클래스를 로드할 수 없었기 (위해)때문에, 또는 에이전트 클래스에 적절한 premain 메소드가 없기 때문에), JVM 는 이상종료(ABEND) 합니다. premain 메소드가, 캐치 되지 않는 예외를 throw 하면(자), JVM 가 이상종료(ABEND) 합니다.

VM 개시 후의 에이전트 개시

구현에 따라서는, VM 의 개시 후에 에이전트를 개시하는 기구가 준비되어 있는 경우도 있습니다. 개시하는 방법의 자세한 것은, 구현에 따라서 다릅니다만, 일반적으로은 어플리케이션이 개시가 끝난 상태로, 그 어플리케이션 main 메소드가 호출이 끝난 상태입니다. VM 의 개시 후에 에이전트를 개시할 수 있는 경우는, 다음의 조건이 적용됩니다.

1. 에이전트 JAR 의 Manifest에는 속성 Agent-Class 가 포함될 필요가 있다. 이 속성의 값은, 에이전트 클래스의 이름.

2. 에이전트 클래스는 public static agentmain 메소드를 구현할 필요가 있다.

3. 시스템 클래스 로더 (ClassLoader.getSystemClassLoader )는, 에이전트 JAR 파일을 시스템 클래스 패스에 추가하는 기구를 지원할 필요가 있다.

에이전트 JAR 는 시스템 클래스 패스에 추가됩니다. 이 클래스 로더는, 일반적으로, 어플리케이션 main 메소드를 포함한 클래스를 로드합니다. 에이전트 클래스가 로드 되면(자), JVM 는 agentmain 메소드를 호출하려고 합니다. JVM 는 에이전트 클래스에서 최초로 다음의 메소드를 호출하려고 합니다.

public static void agentmain(String agentArgs, Instrumentation inst);

에이전트 클래스에 이 메소드가 구현되어 있지 않은 경우는, 다음의 메소드를 호출하려고 합니다.

public static void agentmain(String agentArgs);

에이전트 클래스에는, 커멘드행 옵션을 사용해 에이전트를 개시할 경우에 사용하는 premain 메소드가 준비되어 있는 경우가 있습니다. VM 의 개시 후에 에이전트가 개시되면(자),premain 메소드는 불려 가지 않습니다.

에이전트는,agentArgs 파라미터 경유로 에이전트 옵션이 건네받습니다. 에이전트 옵션은 단일의 캐릭터 라인으로서 건네받아 추가의 해석은 에이전트 자신에 의해 행해집니다.

agentmain 메소드에서는, 에이전트의 개시에 필요한 필수의 초기화를 실행하도록 해 주세요. 개시가 완료하면(자), 메소드를 돌려주도록(듯이) 합니다. 에이전트를 개시할 수 없는 경우 (예를 들어 에이전트 클래스를 로드할 수 없었기 (위해)때문에, 또는 에이전트 클래스에 적절한 agentmain 메소드가 없기 때문에), JVM 는 이상종료(ABEND) 합니다. agentmain 메소드가, 캐치 되지 않는 예외를 throw 하면(자), 무시됩니다.

Manifest 속성

에이전트 JAR 파일에는 다음의 Manifest 속성이 정의되고 있습니다.

Premain-Class

JVM 의 기동시에 에이전트가 지정되는 경우는, 이 속성으로 에이전트 클래스를 지정합니다. 즉,premain 메소드가 포함되는 클래스입니다. JVM 의 기동시에 에이전트가 지정되는 경우는, 이 속성이 필수입니다. 이 속성이 존재하지 않는 경우, JVM 는 이상종료(ABEND) 합니다. 주:이것은 클래스명이며, 파일명이나 패스가 아닙니다.

Agent-Class

VM 의 개시 후에 에이전트를 개시하는 기구가 구현으로 지원되고 있는 경우는, 이 속성으로 에이전트 클래스를 지정합니다. 즉,agentmain 메소드가 포함되는 클래스입니다. 이 속성은 필수입니다. 존재하지 않는 경우, 에이전트는 개시하지 않습니다. 주:이것은 클래스명이며, 파일명이나 패스가 아닙니다.

Boot-Class-Path

bootstrap 클래스 로더로 검색되는 패스의 리스트입니다. 패스는 디렉토리 또는 라이브러리를 나타냅니다. 많은 플랫폼에서는, 일반적으로, JAR 파일 또는 zip 라이브러리로서 참조됩니다. 클래스를 검색하는 플랫폼 고유의 기구가 실패하면(자), 이러한 패스가 bootstrap 클래스 로더로 검색됩니다. 패스는 리스트의 순서로 검색됩니다. 리스트내의 패스는 1 개 이상의 공백 문자로 단락지어집니다. 패스의 구문은, 계층형 URI 의 패스 컴포넌트의 구문이 됩니다. slash 문자 (/)로 시작되면(자) 절대 패스, 그 이외의 경우는 상대 패스입니다. 상대 패스는 에이전트의 JAR 파일의 절대 패스에 대해서 해결됩니다. 패스가 부정 또는 존재하지 않는 경우는 무시됩니다. VM 의 개시 후에 에이전트가 개시되는 경우는, JAR 파일을 나타내지 않는 패스는 무시됩니다. 이 속성은 옵션입니다.

Can-Redefine-Classes

불리언 값 (true 또는 false, 대문자 소문자는 구별하지 않는다). 클래스를 재정의하는 기능이 이 에이전트에 필요한가를 나타냅니다. true 이외의 값은 false 이다고 보입니다. 이 속성은 옵션으로, 디폴트는 false 입니다.

Can-Retransform-Classes

불리언 값 (true 또는 false, 대문자 소문자는 구별하지 않는다). 클래스를 재변환하는 기능이 이 에이전트에 필요한가를 나타냅니다. true 이외의 값은 false 이다고 보입니다. 이 속성은 옵션으로, 디폴트는 false 입니다.

Can-Set-Native-Method-Prefix

불리언 값 (true 또는 false, 대문자 소문자는 구별하지 않는다). 네이티브 메소드의 접두사를 설정하는 기능이 이 에이전트에 필요한가를 나타냅니다. true 이외의 값은 false 이다고 보입니다. 이 속성은 옵션으로, 디폴트는 false 입니다.

에이전트 JAR 파일에서는, Manifest내에 Premain-Class 속성과 Agent-Class 속성의 양쪽 모두가 존재하는 일이 있습니다. -javaagent 옵션을 사용한 커멘드행으로 에이전트를 개시하는 경우는,Premain-Class 속성으로 에이전트 클래스의 이름을 지정해,Agent-Class 속성은 무시됩니다. 같이 VM 의 개시 후에 에이전트가 개시되는 경우는,Agent-Class 속성으로 에이전트 클래스의 이름을 지정해,Premain-Class 속성은 무시됩니다.

관련 문서

툴의 메뉴얼에 대해서는, 다음을 참조해 주세요.

• JDK 툴과 유틸리티

도입된 버젼:

JDK1. 5 @revised 1.6