Интерфейс ClassFileTransformer

public interface ClassFileTransformer

Преобразователь файлов классов. Агент регистрирует реализацию этого интерфейса с помощью метода addTransformer, чтобы метод преобразователя transform вызывался при загрузке классов, redefined или retransformed. Реализация должна переопределить один из методов transform определенных здесь. Преобразователи вызываются до того, как виртуальная машина Java определит класс.

Существует два вида преобразователей, определяемых параметром canRetransform метода Instrumentation.addTransformer(ClassFileTransformer,boolean):

• способные к повторной трансформации преобразователи, добавленные с параметром canRetransform равным true
• неспособные к повторной трансформации преобразователи, добавленные с параметром canRetransform равным false или добавленные с помощью метода Instrumentation.addTransformer(ClassFileTransformer)

После регистрации преобразователя с помощью метода addTransformer, преобразователь будет вызываться для каждого нового определения класса и каждой переопределения класса. Способные к повторной трансформации преобразователи также будут вызываться при каждой повторной трансформации класса. Запрос на новое определение класса выполняется с помощью метода ClassLoader.defineClass или его аналогов нативных методов. Запрос на переопределение класса выполняется с помощью Instrumentation.redefineClasses или его аналогов нативных методов. Запрос на повторную трансформацию класса выполняется с помощью Instrumentation.retransformClasses или его аналогов нативных методов. Преобразователь вызывается во время обработки запроса, до проверки или применения байтовых кодов файла класса. При наличии нескольких преобразователей преобразования выполняются последовательно путем объединения вызовов transform. То есть, байтовый массив, возвращаемый одним вызовом transform , становится входом (через параметр classfileBuffer) для следующего вызова.

Преобразования применяются в следующем порядке:

• Преобразователи, не способные к повторной трансформации
• Нативные преобразователи, не способные к повторной трансформации
• Преобразователи, способные к повторной трансформации
• Нативные преобразователи, способные к повторной трансформации

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

Входной массив (через параметр classfileBuffer ) для первого преобразователя:

• для нового определения класса, байты, переданные в ClassLoader.defineClass
• для переопределения класса, definitions.getDefinitionClassFile() , где definitions является параметром метода Instrumentation.redefineClasses
• для повторной трансформации класса, байты, переданные для нового определения класса или, если класс был переопределен, последний результат переопределения, со всеми преобразованиями, выполненными преобразователями, не способными к повторной трансформации, автоматически и без изменений повторно применёнными; подробности см. в Instrumentation.retransformClasses

Если реализующий метод определяет, что преобразования не нужны, он должен вернуть null. В противном случае он должен создать новый массив byte[], скопировать входной массив classfileBuffer в него, вместе со всеми желаемыми преобразованиями, и вернуть новый массив. Входной массив classfileBuffer не должен быть изменен.

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

Если преобразователь вызывает исключение (которое он не перехватывает), последующие преобразователи все равно будут вызваны, и загрузка, переопределение или повторная трансформация все равно будут попытанны. Таким образом, выброс исключения имеет тот же эффект, что и возврат null. Чтобы предотвратить неожиданное поведение при возникновении необрабатываемых исключений в коде преобразователя, преобразователь может перехватить Throwable. Если преобразователь считает, что classFileBuffer не представляет собой правильно отформатированный файл класса, он должен выбросить исключение IllegalClassFormatException; хотя это имеет тот же эффект, что и возврат null. Это облегчает ведение журнала или отладку ошибок формата.

Термин файл класса используется в соответствии с определением в разделе 3.1 спецификации «The Java Virtual Machine Specification», и означает последовательность байтов в формате файла класса, независимо от того, находятся ли они в файле.