compact3

java.lang.instrument

Инструментарий интерфейса

public interface Instrumentation

Этот class предоставляет услуги, должен был инструментовать код языка программирования Java. Инструментарий является добавлением байт-кодов к методам с целью собирающихся данных, которые будут использоваться инструментами. Так как изменения являются просто дополнением, эти инструменты не изменяют состояние приложения или поведение. Примеры таких мягких инструментов включают контролирующие агенты, профилировщиков, покрытие анализаторы, и регистраторы события.

Есть два способа получить экземпляр Instrumentation интерфейс:

1. Когда JVM запускается в пути, который указывает на агент class. В этом случае Instrumentation экземпляр передают к premain метод агента class.

2. Когда JVM обеспечивает механизм, чтобы запустить агенты когда-то после того, как JVM запускается. В этом случае Instrumentation экземпляр передают к agentmain метод кода агента.

Эти механизмы описываются в спецификации пакета.

Как только агент получает Instrumentation экземпляр, агент может вызвать методы на экземпляре в любое время.

С тех пор:

1.5

Сводка метода

Модификатор и Тип	Метод и Описание
void	addTransformer(ClassFileTransformer transformer) Регистрирует предоставленный преобразователь.
void	addTransformer(ClassFileTransformer transformer, boolean canRetransform) Регистрирует предоставленный преобразователь.
void	appendToBootstrapClassLoaderSearch(JarFile jarfile) Определяет файл JAR с классами инструментария, которые будут определены начальной загрузкой загрузчик class.
void	appendToSystemClassLoaderSearch(JarFile jarfile) Определяет файл JAR с классами инструментария, которые будут определены системой загрузчик class.
Класс[]	getAllLoadedClasses() Возвращает массив всех классов, в настоящий момент загруженных JVM.
Класс[]	getInitiatedClasses(ClassLoader loader) Возвращает массив всех классов для который loader загрузчик инициирования.
long	getObjectSize(Object objectToSize) Возвращает специфичное для реализации приближение количества хранения, использованного указанным объектом.
boolean	isModifiableClass(Class<?> theClass) Определяет, является ли class поддающимся изменению перепреобразованием или переопределением.
boolean	isNativeMethodPrefixSupported() Возвраты, поддерживает ли текущая конфигурация JVM установку собственного префикса метода.
boolean	isRedefineClassesSupported() Возвраты, поддерживает ли текущая конфигурация JVM переопределение классов.
boolean	isRetransformClassesSupported() Возвраты, поддерживает ли текущая конфигурация JVM перепреобразование классов.
void	redefineClasses(ClassDefinition... definitions) Пересмотрите предоставленный набор классов, используя предоставленные файлы class.
boolean	removeTransformer(ClassFileTransformer transformer) Нерегистрирует предоставленный преобразователь.
void	retransformClasses(Class<?>... classes) Повторно преобразуйте предоставленный набор классов.
void	setNativeMethodPrefix(ClassFileTransformer transformer, String prefix) Этот метод изменяет обработку отказа собственного разрешения метода, позволяя повторную попытку с префиксом, которому применяются к имя.

Деталь метода

addTransformer

void addTransformer(ClassFileTransformer transformer,
                    boolean canRetransform)

Регистрирует предоставленный преобразователь. Все будущие определения class будут замечены преобразователем, кроме определений классов, на которые зависит любой зарегистрированный преобразователь. Преобразователь вызывают, когда классы загружаются, когда они пересматриваются. и если canRetransform истина, когда они повторно преобразовываются. См. ClassFileTransformer.transform для порядка вызовов преобразования. Если преобразователь выдаст исключение во время выполнения, то JVM все еще вызовет другие зарегистрированные преобразователи в порядке. Тот же самый преобразователь может быть добавлен не раз, но ему строго обескураживают - избегают этого, создавая новый экземпляр преобразователя class.

Этот метод предназначается для использования в инструментарии, как описано в спецификации class.

Параметры:

transformer - преобразователь, чтобы зарегистрироваться

canRetransform - могут преобразования этого преобразователя быть повторно преобразованными

Броски:

NullPointerException - если передано a null преобразователь

UnsupportedOperationException - если canRetransform истина, и текущая конфигурация JVM не позволяет перепреобразование (isRetransformClassesSupported() ложь),

С тех пор:

1.6

addTransformer

void addTransformer(ClassFileTransformer transformer)

Регистрирует предоставленный преобразователь.

То же самое как addTransformer(transformer, false).

Параметры:

transformer - преобразователь, чтобы зарегистрироваться

Броски:

NullPointerException - если передано a null преобразователь

См. Также:

addTransformer(ClassFileTransformer,boolean)

removeTransformer

boolean removeTransformer(ClassFileTransformer transformer)

Нерегистрирует предоставленный преобразователь. Будущие определения class не покажут преобразователю. Удаляет последний раз добавленный экземпляр соответствия преобразователя. Из-за многопоточной природы загрузки class, для преобразователя возможно получить вызовы после того, как это было удалено. Преобразователи должны быть записаны защитно, чтобы ожидать эту ситуацию.

Параметры:

transformer - преобразователь, чтобы незарегистрироваться

Возвраты:

истина, если преобразователь был найден и удален, ложь, если преобразователь не был найден

Броски:

NullPointerException - если передано a null преобразователь

isRetransformClassesSupported

boolean isRetransformClassesSupported()

Возвраты, поддерживает ли текущая конфигурация JVM перепреобразование классов. Возможность повторно преобразовать уже загруженный class является дополнительной возможностью JVM. Перепреобразование будет только поддерживаться если Can-Retransform-Classes явный атрибут устанавливается в true в файле JAR агента (как описано в спецификации пакета) и JVM поддерживает эту возможность. Во время единственного инстанцирования единственной JVM множественные вызовы этого метода будут всегда давать тот же самый ответ.

Возвраты:

истина, если текущая конфигурация JVM поддерживает перепреобразование классов, ложь если нет.

С тех пор:

1.6

См. Также:

retransformClasses(java.lang.Class<?>...)

retransformClasses

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

Повторно преобразуйте предоставленный набор классов.

Эта функция облегчает инструментарий уже загруженных классов. Когда классы первоначально загружаются или когда они пересматриваются, начальные байты файла class могут быть преобразованы с ClassFileTransformer. Эта функция запускает повторно процесс преобразования (произошло ли преобразование ранее). Это перепреобразование следует за этими шагами:

• запуск с начальных байтов файла class
• для каждого преобразователя, который был добавлен с canRetransform ложь, байты, возвращенные transform во время последнего class загружают или пересматривают, снова используются как вывод преобразования; отметьте, что это эквивалентно повторному применению предыдущего преобразования, неизменно; за исключением того, что transform не вызывается
• для каждого преобразователя, который был добавлен с canRetransform истина, transform метод вызывают в этих преобразователях
• преобразованные байты файла class устанавливаются как новое определение class

Порядок преобразования описывается в transform метод. Этот тот же самый порядок используется в автоматическом переприложении перепреобразования неспособные преобразования.

Начальные байты файла class представляют байты, которым передают ClassLoader.defineClass или redefineClasses (прежде, чем любые преобразования были применены), однако они не могли бы точно соответствовать им. У постоянного пула не могло бы быть того же самого расположения или содержания. Постоянный пул может иметь больше или меньше записей. Постоянные записи пула могут быть в различном порядке; однако, постоянные индексы пула в байт-кодах методов будут соответствовать. Некоторые атрибуты, возможно, не присутствуют. Где порядок не значим, например порядок методов, порядок не мог бы быть сохранен.

Этот метод работает на наборе, чтобы позволить взаимозависимые изменения больше чем одному class одновременно (перепреобразование class A может потребовать перепреобразования class B).

Если у повторно преобразованного метода есть активные стековые фреймы, те активные фреймы продолжают выполнять байт-коды исходного метода. Повторно преобразованный метод будет использоваться на новом, вызывает.

Этот метод не вызывает инициализации за исключением того, что, который произошел бы под общепринятой семантикой JVM. Другими словами пересмотр class не заставляет свои инициализаторы быть выполненными. Значения статических переменных останутся, как они были до вызова.

На экземпляры повторно преобразованного class не влияют.

Перепреобразование может изменить тела метода, постоянный пул и атрибуты. Перепреобразование не должно добавить, удалить или переименовать поля или методы, изменить подписи методов, или наследование изменения. Эти ограничения возможно быть снятым в будущих версиях. Байты файла class не проверяются, проверяются и устанавливаются, пока преобразования не были применены, если результирующие байты будут по ошибке этим методом, то выдаст исключение.

Если этот метод выдает исключение, никакие классы не были повторно преобразованы.

Этот метод предназначается для использования в инструментарии, как описано в спецификации class.

Параметры:

classes - массив классов, чтобы повторно преобразовать; массиву нулевому длиной разрешают, в этом случае, этот метод ничего не делает

Броски:

UnmodifiableClassException - если указанный class не может быть изменен (isModifiableClass(java.lang.Class<?>) возвратился бы false)

UnsupportedOperationException - если текущая конфигурация JVM не позволяет перепреобразование (isRetransformClassesSupported() ложь), или перепреобразование, предпринятое, чтобы произвести неподдерживаемые изменения

ClassFormatError - если данные не содержали допустимый class

NoClassDefFoundError - если имя в файле class не равно имени class

UnsupportedClassVersionError - если номера версий файла class не поддерживаются

ClassCircularityError - если новые классы содержат зацикливание

LinkageError - если ошибка редактирования происходит

NullPointerException - если предоставленный массив классов или какой-либо из его компонентов null.

С тех пор:

1.6

См. Также:

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

isRedefineClassesSupported

boolean isRedefineClassesSupported()

Возвраты, поддерживает ли текущая конфигурация JVM переопределение классов. Возможность пересмотреть уже загруженный class является дополнительной возможностью JVM. Переопределение будет только поддерживаться если Can-Redefine-Classes явный атрибут устанавливается в true в файле JAR агента (как описано в спецификации пакета) и JVM поддерживает эту возможность. Во время единственного инстанцирования единственной JVM множественные вызовы этого метода будут всегда давать тот же самый ответ.

Возвраты:

истина, если текущая конфигурация JVM поддерживает переопределение классов, ложь если нет.

См. Также:

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

redefineClasses

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

Пересмотрите предоставленный набор классов, используя предоставленные файлы class.

Этот метод используется, чтобы заменить определение class независимо от существующих байтов файла class, как можно было бы сделать, перекомпилировав из источника для отладки фиксировать-и-продолжать. Где существующие байты файла class должны быть преобразованы (например в инструментарии байт-кода) retransformClasses должен использоваться.

Этот метод работает на наборе, чтобы позволить взаимозависимые изменения больше чем одному class одновременно (переопределение class A может потребовать переопределения class B).

Если у пересмотренного метода есть активные стековые фреймы, те активные фреймы продолжают выполнять байт-коды исходного метода. Пересмотренный метод будет использоваться на новом, вызывает.

Этот метод не вызывает инициализации за исключением того, что, который произошел бы под общепринятой семантикой JVM. Другими словами пересмотр class не заставляет свои инициализаторы быть выполненными. Значения статических переменных останутся, как они были до вызова.

На экземпляры пересмотренного class не влияют.

Переопределение может изменить тела метода, постоянный пул и атрибуты. Переопределение не должно добавить, удалить или переименовать поля или методы, изменить подписи методов, или наследование изменения. Эти ограничения возможно быть снятым в будущих версиях. Байты файла class не проверяются, проверяются и устанавливаются, пока преобразования не были применены, если результирующие байты будут по ошибке этим методом, то выдаст исключение.

Если этот метод выдает исключение, никакие классы не были пересмотрены.

Этот метод предназначается для использования в инструментарии, как описано в спецификации class.

Параметры:

definitions - массив классов, чтобы пересмотреть с соответствующими определениями; массиву нулевому длиной разрешают, в этом случае, этот метод ничего не делает

Броски:

UnmodifiableClassException - если указанный class не может быть изменен (isModifiableClass(java.lang.Class<?>) возвратился бы false)

UnsupportedOperationException - если текущая конфигурация JVM не позволяет переопределение (isRedefineClassesSupported() ложь), или переопределение, предпринятое, чтобы произвести неподдерживаемые изменения

ClassFormatError - если данные не содержали допустимый class

NoClassDefFoundError - если имя в файле class не равно имени class

UnsupportedClassVersionError - если номера версий файла class не поддерживаются

ClassCircularityError - если новые классы содержат зацикливание

LinkageError - если ошибка редактирования происходит

NullPointerException - если предоставленный массив определений или какой-либо из его компонентов null

ClassNotFoundException - Никогда не может бросаться (подарок по причинам совместимости только)

См. Также:

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

isModifiableClass

boolean isModifiableClass(Class<?> theClass)

Определяет, является ли class поддающимся изменению перепреобразованием или переопределением. Если class является поддающимся изменению тогда этот метод возвраты true. Если class не является поддающимся изменению тогда этот метод возвраты false.

Для class, который будет повторно преобразован, isRetransformClassesSupported() должна также быть истина. Но значение isRetransformClassesSupported() не влияет на значение, возвращенное этой функцией. Для class, который будет пересмотрен, isRedefineClassesSupported() должна также быть истина. Но значение isRedefineClassesSupported() не влияет на значение, возвращенное этой функцией.

Примитивные классы (например, java.lang.Integer.TYPE) и классы массива никогда не являются поддающимися изменению.

Броски:

NullPointerException - если указанный class 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, возвращаются классы, инициируемые начальной загрузкой загрузчик class.

Параметры:

loader - загрузчик, инициируемый список class которого будет возвращен

Возвраты:

массив, содержащий все классы, для которых загрузчик является загрузчиком инициирования, нулевым длиной, если нет ни одного

getObjectSize

long getObjectSize(Object objectToSize)

Возвращает специфичное для реализации приближение количества хранения, использованного указанным объектом. Результат может включать некоторых или все издержки объекта, и таким образом полезен для сравнения в пределах реализации, но не между реализациями. Оценка может измениться во время единственного вызова JVM.

Параметры:

objectToSize - объект измерить

Возвраты:

специфичное для реализации приближение количества хранения используется указанным объектом

Броски:

NullPointerException - если предоставленный Объект null.

appendToBootstrapClassLoaderSearch

void appendToBootstrapClassLoaderSearch(JarFile jarfile)

Определяет файл JAR с классами инструментария, которые будут определены начальной загрузкой загрузчик class.

Когда встроенный загрузчик class виртуальной машины, известный как "начальная загрузка загрузчик class", неудачно ищет class, записи в JAR file будет искаться также.

Этот метод может использоваться многократно, чтобы добавить многократные файлы JAR, которые будут искаться в порядке, что этот метод был вызван.

Агент должен заботиться, чтобы гарантировать, что JAR не содержит классов или ресурсов кроме тех, чтобы быть определенным начальной загрузкой загрузчик class с целью инструментария. Отказ наблюдать это предупреждение мог привести к неожиданному поведению, которое трудно диагностировать. Например, предположите, что есть загрузчик L, и родитель Л для делегации является начальной загрузкой загрузчик class. Кроме того метод в class C, class, определенный L, ссылается на непубличное средство доступа class 1 C$. Если файл JAR будет содержать class 1 C$ тогда делегация начальной загрузки, то загрузчик class заставит 1 C$ быть определенным начальной загрузкой загрузчик class. В этом примере IllegalAccessError будет брошен, который может заставить приложение перестать работать. Один подход к уходу от этих типов проблем, должен использовать уникальное имя пакета для классов инструментария.

Спецификация Виртуальной машины Java™ определяет, что последующая попытка разрешить символьную ссылку, что виртуальная машина Java ранее неудачно попыталась разрешить всегда сбои с той же самой ошибкой, которая была брошена в результате начальной попытки разрешения. Следовательно, если файл JAR содержит запись, которая соответствует class, для которого виртуальная машина Java неудачно попыталась разрешить ссылку, тогда последующие попытки разрешить, что ссылка перестанет работать с той же самой ошибкой как начальная попытка.

Параметры:

jarfile - Файл JAR, который будет искаться, когда начальная загрузка загрузчик class неудачно ищет class.

Броски:

NullPointerException - Если jarfile null.

С тех пор:

1.6

См. Также:

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

appendToSystemClassLoaderSearch

void appendToSystemClassLoaderSearch(JarFile jarfile)

Определяет файл JAR с классами инструментария, которые будут определены системой загрузчик class. Когда система загрузчик class для делегации (см. getSystemClassLoader()) неудачно поиски class, записей в JarFile будет искаться также.

Этот метод может использоваться многократно, чтобы добавить многократные файлы JAR, которые будут искаться в порядке, что этот метод был вызван.

Агент должен заботиться, чтобы гарантировать, что JAR не содержит классов или ресурсов кроме тех, чтобы быть определенным системой загрузчик class с целью инструментария. Отказ наблюдать это предупреждение мог привести к неожиданному поведению, которое трудно диагностировать (см. appendToBootstrapClassLoaderSearch).

Системный загрузчик class поддерживает добавление файла JAR, который будет искаться, если это реализует названный метод appendToClassPathForInstrumentation который берет единственный параметр типа java.lang.String. Метод не обязан иметь public доступ. Имя файла JAR получается, вызывая getName() метод на jarfile и это обеспечивается как параметр для appendToClassPathForInstrumentation метод.

Спецификация Виртуальной машины Java™ определяет, что последующая попытка разрешить символьную ссылку, что виртуальная машина Java ранее неудачно попыталась разрешить всегда сбои с той же самой ошибкой, которая была брошена в результате начальной попытки разрешения. Следовательно, если файл JAR содержит запись, которая соответствует class, для которого виртуальная машина Java неудачно попыталась разрешить ссылку, тогда последующие попытки разрешить, что ссылка перестанет работать с той же самой ошибкой как начальная попытка.

Этот метод не изменяет значение java.class.path system property.

Параметры:

jarfile - Файл JAR, который будет искаться, когда система загрузчик class неудачно ищет class.

Броски:

UnsupportedOperationException - Если система загрузчик class не поддерживает добавление файл JAR, который будет искаться.

NullPointerException - Если jarfile null.

С тех пор:

1.6

См. Также:

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

isNativeMethodPrefixSupported

boolean isNativeMethodPrefixSupported()

Возвраты, поддерживает ли текущая конфигурация JVM установку собственного префикса метода. Возможность установить собственный префикс метода является дополнительной возможностью JVM. Установка собственного префикса метода будет только поддерживаться если Can-Set-Native-Method-Prefix явный атрибут устанавливается в true в файле JAR агента (как описано в спецификации пакета) и JVM поддерживает эту возможность. Во время единственного инстанцирования единственной JVM множественные вызовы этого метода будут всегда давать тот же самый ответ.

Возвраты:

истина, если текущая конфигурация JVM поддерживает установку собственного префикса метода, ложь если нет.

С тех пор:

1.6

См. Также:

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

setNativeMethodPrefix

void setNativeMethodPrefix(ClassFileTransformer transformer,
                           String prefix)

Этот метод изменяет обработку отказа собственного разрешения метода, позволяя повторную попытку с префиксом, которому применяются к имя. Когда использующийся с ClassFileTransformer, это позволяет собственным методам быть инструментованными.

Так как собственные методы не могут быть непосредственно инструментованы (у них нет никаких байт-кодов), они должны быть обернуты с несобственным методом, который может быть инструментован. Например, если мы имели:

   native boolean foo(int x);

Мы могли преобразовать файл class (с ClassFileTransformer во время начального определения class) так, чтобы это стало:

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

   native boolean wrapped_foo(int x);

Где foo становится оберткой для фактического собственного метода с добавленным префиксом, "обернутым _ ". Отметьте, что "обернутый _" был бы плохой выбор префикса, так как он мог бы очевидно сформировать имя существующего метода таким образом, что-то как" $ $ $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. Чтобы быть в состоянии эффективно определить последовательность префиксов, промежуточный префикс только применяется, если его несобственная обертка существует. Таким образом, в последнем примере, даже при том, что $trans1_foo не собственный метод, $trans1_ префикс применяется с тех пор $trans1_foo существует.

Параметры:

transformer - ClassFileTransformer, который обертывает использование этого префикса.

prefix - Префикс, чтобы примениться к обернутым собственным методам, повторяя отказавшее собственное разрешение метода. Если префикс также null или пустая строка, затем отказавшие собственные разрешения метода не повторяются для этого преобразователя.

Броски:

NullPointerException - если передано a null преобразователь.

UnsupportedOperationException - если текущая конфигурация JVM не позволяет устанавливать собственный префикс метода (isNativeMethodPrefixSupported() ложь).

IllegalArgumentException - если преобразователь не регистрируется (см. addTransformer).

С тех пор:

1.6