Интерфейс 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 Virtual Machine Tool Interface.

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

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

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

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

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

Обратите внимание, что термин файл класса используется в значении, определённом в главе 4 «Формат файла class» из документа Спецификация виртуальной машины Java, и означает последовательность байтов в формате файла класса независимо от того, хранятся ли они в файле.