Интерфейс Instrumentation

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Имя файла JAR получается путём вызова метода getName() на jarfile и предоставляется в качестве параметра методу appendToClassPathForInstrumentation.

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

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

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