JavaTM Platform
Standard Ed. 6

java.lang.instrument
�ӿ� Instrumentation


public interface Instrumentation

�����ṩ��� Java ������Դ�������ķ��񡣼�����򷽷��������ֽ��룬���Ѽ����ֹ�����ʹ�õ����ݡ����ڸ�����ȫ�ǽ������ӣ�������Щ���߲��޸�Ӧ�ó����״̬����Ϊ�������޺����ߵ����Ӱ�����������������������Ƿ��������¼���¼����

��ȡ Instrumentation �ӿڵ�ʵ�������ַ�ʽ��

  1. �� JVM ��ָʾһ��������ķ�ʽ����ʱ�������ݸ�������� premain ����һ�� Instrumentation ʵ����

  2. �� JVM �ṩij�ֻ����� JVM ����֮��ijһʱ����������ʱ�������ݸ���������� agentmain ����һ�� Instrumentation ʵ����

��Щ���������淶��������

���ij����������� Instrumentation ʵ��������������κ�ʱ����ø�ʵ���ϵķ�����

�����°汾��ʼ��
1.5

����ժҪ
 void addTransformer(ClassFileTransformer transformer)
          ע���ṩ��ת������
 void addTransformer(ClassFileTransformer transformer, boolean canRetransform)
          ע���ṩ��ת������
 void appendToBootstrapClassLoaderSearch(JarFile jarfile)
          ָ�� JAR �ļ������������������������塣
 void appendToSystemClassLoaderSearch(JarFile jarfile)
          ָ�� JAR �ļ����������ϵͳ����������塣
 Class[] getAllLoadedClasses()
          ���� JVM ��ǰ���ص�����������顣
 Class[] getInitiatedClasses(ClassLoader loader)
          �������г�ʼ���������� loader ��������顣
 long getObjectSize(Object objectToSize)
          ����ָ������ʹ�õ��ض���ʵ�ֵĽ��ƴ洢����
 boolean isModifiableClass(Class<?> theClass)
          ȷ��һ�����Ƿ���Ա� retransformation �� redefinition �޸ġ�
 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�� ���ת������ִ�й������׳��쳣��JVM ����Ȼ��˳�����������ע��ת���������Զ��������ͬ��ת��������������ô���һ���µ�ת������ʵ����������������

�˷���ּ�����ڼ�⣬������淶������

������
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)
ע���ṩ��ת�������Ժ���ඨ�彫�������ת������ʾ���Ƴ��������ӵ�ת������ƥ��ʵ������������صĶ��߳����ԣ��ڵ��ñ��Ƴ���ת���������ܽ��յ��á����Ա�дת����ʱӦ��ֹ�������������

������
transformer - Ҫע����ת����
���أ�
����ҵ����Ƴ�ת�������򷵻� true������Ҳ���ת�������򷵻� false
�׳���
NullPointerException - ���������һ�� null ת����

isRetransformClassesSupported

boolean isRetransformClassesSupported()
���ص�ǰ JVM �����Ƿ�֧�������ת���� ת���Ѽ������� JVM ��һ����ѡ���ܡ� ���� Can-Retransform-Classes �嵥�����ڴ��� JAR �ļ�������Ϊ true�������淶���������� JVM ֧�ִ�����ʱ����֧����ת���� �ڵ��� JVM �ĵ���ʵ���������У���ε��ô˷��������Ƿ�����ͬ�Ĵ𰸡�

���أ�
�����ǰ JVM ����֧�������ת�����򷵻� true�������֧�֣��򷵻� false��
�����°汾��ʼ��
1.6
������
retransformClasses(java.lang.Class...)

retransformClasses

void retransformClasses(Class<?>... classes)
                        throws UnmodifiableClassException
��ת���ṩ���༯��

�˺���Ϊ����Ѽ������ṩ�˷��㡣 ���������������ض�������ʱ����ʼ���ļ��ֽڿ���ʹ�� ClassFileTransformer ת���� �˺�������ת�����̣���ǰ�Ƿ�����ת������ ��ת�������²�����У�

ת����˳���� transform ���������������Զ�����Ӧ�ò�����ת����ת��ʱ��Ҳ��ʹ����һ˳��

��������ļ��ֽڱ�ʾ��Ӧ��ת��ǰ�����ݸ� ClassLoader.defineClass �� redefineClasses ���ֽڣ����п��ܲ���ȫƥ�䡣�����صIJ��ֻ����ݿ��ܲ�ͬ�������ص���Ŀ���ܶ�һЩ����һЩ����������Ŀ��˳����ܲ�ͬ�����ǣ������ֽ����г����ص��������Ƕ�Ӧ�ġ�һЩ���Կ��ܲ����ڡ���˳��û������ĵط������磬������˳�򣩣����ܲ�����˳��

�˷�����һ�������ϲ������Ա�����ͬʱ�Զ��������໥�����ĸ��ģ���ת���� A Ҫ����ת���� B����

�����ת���ķ����л�Ķ�ջ֡����ô��Щ���֡����������ԭ�������ֽ��롣��ת���ķ����������µĵ��á�

�˷������������κγ�ʼ��������JVM ���������·����ij�ʼ�����⡣���仰˵���ض���һ���಻���������ʼ�����������С���̬������ֵ�������֮ǰ��ֵһ����

��ת�����ʵ������Ӱ�졣

��ת�����ܻ���ķ����塢�����غ����ԡ���ת���������ӡ��Ƴ����������ֶλ򷽷������ø��ķ���ǩ�����̳й�ϵ�����Ժ�İ汾�У����ܻ�ȡ����Щ���ơ���Ӧ��ת��֮ǰ�����ļ��ֽڲ��ᱻ��顢��֤�Ͱ�װ���������ֽڴ��󣬴˷������׳��쳣��

����˷����׳��쳣���򲻻���ת���κ��ࡣ

�˷���ּ�����ڼ�⣬������淶������

������
classes - Ҫת���������飻 ��������Ϊ 0 ���飬����������£��˷�����ִ���κβ���
�׳���
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 ��һ����ѡ���ܡ� ���� Can-Retransform-Classes �嵥�����ڴ��� JAR �ļ�������Ϊ true�������淶���������� JVM ֧�ִ�����ʱ����֧����ת���� ��ִ�е��� JVM �ĵ�ʵ���������У��Դ˷����Ķ�ε��ý�ʼ�շ���ͬһӦ��

���أ�
�����ǰ JVM ����֧������ض��壬��Ϊ true������Ϊ false��
������
redefineClasses(java.lang.instrument.ClassDefinition...)

redefineClasses

void redefineClasses(ClassDefinition... definitions)
                     throws ClassNotFoundException,
                            UnmodifiableClassException
ʹ���ṩ�����ļ��ض����ṩ���༯��

�˷������������Ķ��壬�����������е����ļ��ֽڣ����� fix-and-continue ���Թ��������±���Դ����ʱ������һ������Ҫת���������ļ��ֽڵĵط������磬�ֽ������У�Ӧ��ʹ�� retransformClasses��

�˷�����һ�������ϲ������Ա�����ͬʱ�Զ��������໥�����ĸ��ģ��ض����� A Ҫ���ض����� B����

����ض���ķ����л�Ķ�ջ֡����ô��Щ���֡����������ԭ�������ֽ��롣�����µĵ�����ʹ�ô��ض���ķ�����

�˷������������κγ�ʼ��������JVM ���������·����ij�ʼ�����⡣���仰˵���ض���һ���಻���������ʼ�����������С���̬������ֵ�������֮ǰ��ֵһ����

�ض������ʵ������Ӱ�졣

�ض�����ܻ���ķ����塢�����غ����ԡ��ض��岻�����ӡ��Ƴ����������ֶλ򷽷������ø��ķ���ǩ�����̳й�ϵ�����Ժ�İ汾�У����ܻ�ȡ����Щ���ơ���Ӧ��ת��֮ǰ�����ļ��ֽڲ��ᱻ��顢��֤�Ͱ�װ���������ֽڴ��󣬴˷������׳��쳣��

����˷����׳��쳣���򲻻��ض����κ��ࡣ

�˷���ּ�����ڼ�⣬������淶������

������
definitions - Ҫʹ����Ӧ�����������ض���������飻��������Ϊ 0 ���飬����������£��˷�����ִ���κβ���
�׳���
UnmodifiableClassException - ����޷��޸�ָ�����ࣨisModifiableClass(java.lang.Class) ���� false��
UnsupportedOperationException - ��� JVM �ĵ�ǰ���ò������ض��壨isRedefineClassesSupported() Ϊ false�����ض�����ͼ��������֧�ֵĸ���
ClassFormatError - ������ݲ�������Ч��
NoClassDefFoundError - ������ļ��е������������Ʋ����
UnsupportedClassVersionError - ������ļ��汾�Ų���֧��
ClassCircularityError - ����������ѭ��
LinkageError - ����������Ӵ���
NullPointerException - ����ṩ�Ķ�����������κ����Ϊ null��
ClassNotFoundException - �����׳�������ֻ��Ϊ�˼��ݣ�
������
isRedefineClassesSupported(), addTransformer(java.lang.instrument.ClassFileTransformer, boolean), ClassFileTransformer

isModifiableClass

boolean isModifiableClass(Class<?> theClass)
ȷ��һ�����Ƿ���Ա� retransformation �� redefinition �޸ġ� �������Ա��޸ģ���ô�˷������� true�� ����಻�ܱ��޸ģ���ô�˷������� false��

����Ҫ��ת�����࣬isRetransformClassesSupported() Ҳ����Ϊ true���� isRetransformClassesSupported() ��ֵ��Ӱ��˺������ص�ֵ�� ����Ҫ�ض�����࣬isRedefineClassesSupported() Ҳ����Ϊ true���� isRedefineClassesSupported() ��ֵ��Ӱ��˺������ص�ֵ��

�����ࣨ���� java.lang.Integer.TYPE���������಻���޸ġ�

�׳���
NullPointerException - ���ָ������Ϊ null��
�����°汾��ʼ��
1.6
������
retransformClasses(java.lang.Class...), isRetransformClassesSupported(), redefineClasses(java.lang.instrument.ClassDefinition...), isRedefineClassesSupported()

getAllLoadedClasses

Class[] getAllLoadedClasses()
���� JVM ��ǰ���ص�����������顣

���أ�
���� JVM ���ص�����������飻���û�У��򷵻س���Ϊ 0 ����

getInitiatedClasses

Class[] getInitiatedClasses(ClassLoader loader)
�������г�ʼ���������� loader ��������顣����ṩ�ļ�����Ϊ null���򷵻����������������ʼ�����ࡣ

������
loader - ���������ʼ�����б��ļ�����
���أ�
������ʼ���������� loader ��������飻���û�У��򷵻س���Ϊ 0 ����

getObjectSize

long getObjectSize(Object objectToSize)
����ָ������ʹ�õ��ض���ʵ�ֵĽ��ƴ洢�����ý�����ܰ�������IJ��ֻ�ȫ����������ˣ���һ��ʵ���н��бȽ�ʱ��Ϊ���ã�����������ʵ��֮��ıȽϡ� �ù���ֵ�� JVM �ĵ��������ڼ���ܷ����仯��

������
objectToSize - ��Ҫȷ����С�Ķ���
���أ�
ָ������ʹ�õ��ض���ʵ�ֵĽ��ƴ洢��
�׳���
NullPointerException - ����ṩ�� Object Ϊ null��

appendToBootstrapClassLoaderSearch

void appendToBootstrapClassLoaderSearch(JarFile jarfile)
ָ�� JAR �ļ������������������������塣

������������������������Ϊ�����������������δ�ܳɹ���������ʱ��JAR �ļ��е���ĿҲ����������

���Զ��ʹ�ô˷��������յ��ô˷�����˳�����Ӷ��Ҫ������ JAR �ļ���

������Ҫ�����������Ϊ��������������Դ�⣬����Ӧ��ע��ȷ�� JAR �������κ����������Դ�� Υ���˹涨������������ϵIJ���Ԥ����Ϊ�����磬�����м����� L��L �Ĵ�����������Ϊ������������� ���⣬��һ���� C �ķ�������һ�� L ������࣬�����˷ǹ�����ȡ�� C$1����� JAR �ļ������� C$1����ô������������Ĵ��������� C$1 ����������������塣�����н��׳� IllegalAccessError������ܵ���Ӧ�ó���ʧ�ܡ�һ��������������İ취�ǣ��Լ����ʹ��Ψһ�İ����ơ�

Java ������淶�涨���������Խ��� Java �������ǰδ�ܳɹ������ķ������ý�����ʧ�ܣ����׳��������������ʧ��ʱ��ͬ�Ĵ�����ˣ���� JAR �ļ�������ij����Ŀ��Ӧ�� Java �����δ�ܳɹ��������õ��࣬��ô�������Խ��������ý�����ʧ�ܣ����׳��������������ʧ��ʱ��ͬ�Ĵ���

������
jarfile - �������������δ�ɹ���������ʱҪ������ JAR �ļ���
�׳���
NullPointerException - ��� jarfile Ϊ null��
�����°汾��ʼ��
1.6
������
appendToSystemClassLoaderSearch(java.util.jar.JarFile), ClassLoader, JarFile

appendToSystemClassLoaderSearch

void appendToSystemClassLoaderSearch(JarFile jarfile)
ָ�� JAR �ļ����������ϵͳ����������塣 ��������ϵͳ����������μ� getSystemClassLoader()��δ�ܳɹ���������ʱ��JarFile �е���ĿҲ����������

���Զ��ʹ�ô˷��������յ��ô˷�����˳�����Ӷ��Ҫ������ JAR �ļ���

������Ҫϵͳ�������Ϊ��������������Դ�⣬����Ӧ��ע��ȷ�� JAR �������κ����������Դ�� Υ���˹涨������������ϵIJ���Ԥ����Ϊ�����μ� appendToBootstrapClassLoaderSearch����

���ʵ������Ϊ appendToClassPathForInstrumentation �ķ���������һ������Ϊ java.lang.String �IJ���������ôϵͳ�������֧������Ҫ������ JAR �ļ�����Ҫ��÷������� public ����Ȩ��JAR �ļ�������ͨ���� jarfile ���� getName() ������ȡ��������Ϊ�����ṩ�� appendtoClassPathForInstrumentation ������

Java ������淶�涨���������Խ��� Java �������ǰδ�ܳɹ������ķ������ý�����ʧ�ܣ����׳��������������ʧ��ʱ��ͬ�Ĵ�����ˣ���� JAR �ļ�������ij����Ŀ��Ӧ�� Java �����δ�ܳɹ��������õ��࣬��ô�������Խ��������ý�����ʧ�ܣ����׳��������������ʧ��ʱ��ͬ�Ĵ���

�˷��������� 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 ��һ����ѡ���ܡ� ���� Can-Set-Native-Method-Prefix �嵥�����ڴ��� JAR �ļ�������Ϊ true�������淶���������� JVM ֧�ִ�����ʱ����֧�����ñ�������ǰ׺�� �ڵ��� JVM �ĵ���ʵ���������У���ε��ô˷��������Ƿ�����ͬ��Ӧ��

���أ�
�����ǰ JVM ����֧�����ñ�������ǰ׺���򷵻� true�����򷵻� false��
�����°汾��ʼ��
1.6
������
setNativeMethodPrefix(java.lang.instrument.ClassFileTransformer, java.lang.String)

setNativeMethodPrefix

void setNativeMethodPrefix(ClassFileTransformer transformer,
                           String prefix)
ͨ���������ԣ���ǰ׺Ӧ�õ����ƣ��˷����޸ı�������������ʧ�ܴ����� ���� ClassFileTransformer һ��ʹ��ʱ����������Ȿ��������

���ڱ�����������ֱ�Ӽ�⣨����û���ֽ��룩����˱���ʹ�ÿ��Լ��ķDZ���������װ���ǡ����磬����У�

   native boolean foo(int x);

��ô����ת�����ļ�������ij�ʼ���������ʹ�� 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)

�˺�������ָ��ǰ׺������ǡ���Ľ����� ��ȷ��˵������׼����ʧ��ʱ�����������³��Կ���ǰ׺�����н��������ַ�ʽ��ʹ�� 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���� ���ԣ��������ת����Ӧ���˰�װ����foo ����Ϊ $trans3_$trans2_$trans1_foo�����ǣ�����ڶ���ת����û�ж� foo Ӧ�ð�װ������ô������ $trans3_$trans1_foo��Ҫ��Ч��ȷ��ǰ׺���У�������DZ�����װ������ʱ��Ӧ���м�ǰ׺����ˣ������һ��ʾ���У���ʹ $trans1_foo ���DZ���������$trans1_ ǰ׺Ҳ��Ӧ�ã���Ϊ $trans1_foo ���ڡ�

������
transformer - ʹ�ô�ǰ׺��װ�� ClassFileTransformer��
prefix - ��Ӧ�õ���װ�ı���������ǰ׺��
�׳���
NullPointerException - ������� null ת������
UnsupportedOperationException - ��� JVM �ĵ�ǰ���ò��������ñ�������ǰ׺��isNativeMethodPrefixSupported() Ϊ false����
IllegalArgumentException - ���ת����û��ע�ᣨ�μ� addTransformer����
�����°汾��ʼ��
1.6

JavaTM Platform
Standard Ed. 6

�ύ��������
�йظ���� API �ο����ϺͿ�����Ա�ĵ�������� Java SE ������Ա�ĵ������ĵ���������ϸ�ġ����򿪷���Ա���������Լ�������������ﶨ�塢ʹ�ü��ɺ͹�������ʾ����

��Ȩ���� 2007 Sun Microsystems, Inc. ��������Ȩ���� ����������֤��������������ĵ����·ַ�������