Интерфейс ClassFileTransformer

byte[] transform(ClassLoader loader,
                 String className,
                 Class<?> classBeingRedefined,
                 ProtectionDomain protectionDomain,
                 byte[] classfileBuffer)
          throws IllegalClassFormatException

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

Существуют два типа преобразователей, определяемых параметром 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, это облегчает ведение журнала или отладку ошибок форматирования.