java.lang.instrument

Интерфейсный ClassFileTransformer

public interface ClassFileTransformer

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

Отметьте, что файл класса термина используется как определено в разделе 3.1 из Спецификации Виртуальной машины Java™, чтобы означать последовательность байтов в формате файла класса, находятся ли они в файле.

С тех пор:

1.5

См. Также:

Instrumentation, Instrumentation.addTransformer(java.lang.instrument.ClassFileTransformer, boolean), Instrumentation.removeTransformer(java.lang.instrument.ClassFileTransformer)

Сводка метода

Методы

Модификатор и Тип	Метод и Описание
byte[]	transform(ClassLoader loader, String className, Class<?> classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer) Реализация этого метода может преобразовать предоставленный файл класса и возвратить новый заменяющий файл класса.

Деталь метода

преобразовать

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

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

Есть два вида преобразователей, определенных canRetransform параметр Instrumentation.addTransformer(ClassFileTransformer,boolean):

• способные преобразователи перепреобразования, которые были добавлены с canRetransform как истина
• неспособные преобразователи перепреобразования, которые были добавлены с canRetransform как ложь или где добавлено с 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; в то время как это имеет тот же самый эффект как возврат нуля. это облегчает журналирование или отладку повреждений формата.

Параметры:

loader - загрузчик определения класса, который будет преобразован, может быть null если программа начальной загрузки

className - имя класса во внутренней форме полностью определенного класса и интерфейса называет как определено в Спецификации виртуальной машины Java. Например, "java/util/List".

classBeingRedefined - если это инициировано пересматриванием, или повторно преобразуйте, класс, пересматриваемый или повторно преобразованный; если это - загрузка класса, null

protectionDomain - домен защиты класса, определяемого или пересмотренного

classfileBuffer - входной буфер байта в формате файла класса - не должен быть изменен

Возвраты:

правильно построенный буфер файла класса (результат преобразования), или null если никакие не преобразовывают, выполняется.

Броски:

IllegalClassFormatException - если ввод не представляет правильно построенный файл класса

См. Также:

Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition...)