Интерфейс Instrumentation

void addTransformer(ClassFileTransformer transformer, boolean canRetransform)

Регистрирует предоставленный трансформатор. Все будущие определения классов будут видны трансформатору, за исключением определений классов, от которых зависит любой зарегистрированный трансформатор. Трансформатор вызывается при загрузке классов, при их переопределении и, если canRetransform имеет значение true, при их перетрансформации. ClassFileTransformer определяет порядок вызовов трансформации. Если трансформатор генерирует исключение во время выполнения, JVM все равно вызовет другие зарегистрированные трансформаторы в порядке. Один и тот же трансформатор может быть добавлен более одного раза, но это настоятельно не рекомендуется — избегайте этого, создавая новый экземпляр класса трансформатора.

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

void addTransformer(ClassFileTransformer transformer)

Регистрирует предоставленный трансформатор.

То же, что и addTransformer(transformer, false).

boolean removeTransformer(ClassFileTransformer transformer)

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

boolean isRetransformClassesSupported()

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

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

Перетрансформирует указанный набор классов.

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

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

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

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

Этот метод работает с набором, чтобы позволить взаимозависимые изменения более чем одного класса одновременно (перетрансформация класса A может потребовать перетрансформации класса B).

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

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

Экземпляры перетрансформированного класса не затронуты.

Поддерживаемые изменения файла класса описаны в JVM TI RetransformClasses. Байты файла класса не проверяются, не верифицируются и не устанавливаются до тех пор, пока не будут применены все трансформации. Если полученные байты некорректны, этот метод сгенерирует исключение.

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

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

boolean isRedefineClassesSupported()

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

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

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

Этот метод используется для замены определения класса без ссылки на байты существующего файла класса, как это можно сделать при повторной компиляции из исходного кода для отладки «исправь и продолжай». В случаях, когда существующие байты файла класса должны быть преобразованы (например, в инструментировании байткода), следует использовать retransformClasses.

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

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

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

Экземпляры переопределённого класса не затронуты.

Поддерживаемые изменения в файлах классов описаны в JVM TI RedefineClasses. Байты файла класса не проверяются, не верифицируются и не устанавливаются до тех пор, пока не будут применены преобразования, если полученные байты неверны, этот метод выбросит исключение.

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

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

boolean isModifiableClass(Class<?> theClass)

Проверяет, можно ли изменить класс с помощью повторной трансформации или переопределения. Если класс можно изменить, этот метод возвращает true. Если класс нельзя изменить, этот метод возвращает false.

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

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

Class[] getAllLoadedClasses()

Возвращает массив всех классов, которые в настоящее время загружены JVM. Возвращаемый массив включает все классы и интерфейсы, включая скрытые классы или интерфейсы, и классы массивов всех типов.

Class[] getInitiatedClasses(ClassLoader loader)

Возвращает массив всех классов, которые loader может найти по имени с помощью ClassLoader::loadClass, Class::forName и связывания байткода. То есть все классы, для которых loader был записан как инициализирующий загрузчик. Если указанный loader является null, возвращаются классы, которые может найти загрузчик bootstrap по имени.

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

long getObjectSize(Object objectToSize)

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

void appendToBootstrapClassLoaderSearch(JarFile jarfile)

Указывает JAR-файл с классами инструментирования, которые будут определены загрузчиком bootstrap.

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

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

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

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

void appendToSystemClassLoaderSearch(JarFile jarfile)

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

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

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

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

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

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

boolean isNativeMethodPrefixSupported()

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

void setNativeMethodPrefix(ClassFileTransformer transformer, String prefix)

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

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

   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)

Эта функция позволяет указать префикс и обеспечить правильное разрешение. В частности, когда стандартное разрешение терпит неудачу, разрешение повторяется, учитывая префикс. Существует два способа разрешения, явное разрешение с функцией 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 существует.

void redefineModule(Module module, Set<Module> extraReads, Map<String,Set<Module>> extraExports, Map<String,Set<Module>> extraOpens, Set<Class<?>> extraUses, Map<Class<?>,List<Class<?>>> extraProvides)

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

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

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

Параметр extraExports — это карта дополнительных пакетов для экспорта. Параметр extraOpens — это карта дополнительных пакетов для открытия. В обоих случаях, ключ карты — это полное имя пакета, определённое в разделе 6.5.3 спецификации языка Java, например, "java.lang". Значение карты — это непустой набор модулей, которым пакет должен быть экспортирован или открыт.

Параметр extraProvides — это дополнительные поставщики сервисов для предоставления модулем. Ключ карты — это тип сервиса. Значение карты — это непустой список типов реализации, каждый из которых является членом модуля и реализацией сервиса.

Этот метод безопасен для одновременного использования и позволяет множеству агентов внедрять и обновлять один и тот же модуль примерно в одно и то же время.

boolean isModifiableModule(Module module)

Проверяет, можно ли изменить модуль с помощью redefineModule. Если модуль изменяем, этот метод возвращает true. Если модуль не изменяем, этот метод возвращает false. Этот метод всегда возвращает true когда модуль безымянный (поскольку переопределение безымянного модуля является бесполезным действием).