Пакет java.lang.instrument

Предоставляет услуги, которые позволяют агентам языка программирования Java инструментовать программы, работающие на JVM.

См.: Описание

Сводка интерфейса

Интерфейс	Описание
ClassFileTransformer	Агент обеспечивает реализацию этого интерфейса, чтобы преобразовать файлы class.
Инструментарий	Этот class предоставляет услуги, должен был инструментовать код языка программирования Java.

Сводка класса

Класс	Описание
ClassDefinition	Этот class служит блоком параметра к Instrumentation.redefineClasses метод.

Сводка исключения

Исключение	Описание
IllegalClassFormatException	Брошенный реализацией ClassFileTransformer.transform когда его входные параметры недопустимы.
UnmodifiableClassException	Брошенный реализацией Instrumentation.redefineClasses когда один из указанных классов не может быть изменен.

Пакет java.lang.instrument Описание

Предоставляет услуги, которые позволяют агентам языка программирования Java инструментовать программы, работающие на JVM. Механизм для инструментария является модификацией байт-кодов методов.

Спецификация пакета

Агент развертывается как файл JAR. Атрибут в декларации файла JAR определяет агент class, который будет загружен, чтобы запустить агент. Для реализаций, которые поддерживают интерфейс командной строки, агент запускается, определяя опцию на командной строке. Реализации могут также поддерживать механизм, чтобы запустить агенты некоторое время после того, как VM запустился. Например, реализация может обеспечить механизм, который позволяет инструменту присоединять к рабочему приложению, и приобщать загрузку агента инструмента в рабочее приложение. Детали относительно того, как загрузка инициируется, являются зависящими от реализации.

Интерфейс командной строки

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

-javaagent:jarpath [=опции]

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

Декларация файла JAR агента должна содержать атрибут Premain-Class. Значение этого атрибута является именем агента class. Агент class должен реализовать общедоступные помехи premain метод, подобный в принципе main точка входа приложения. После того, как виртуальная машина Java (JVM) инициализировала, каждый premain метод вызовут в порядке, агенты были определены, тогда реальное приложение main метод вызовут. Каждый premain метод должен возвратиться для последовательности запуска, чтобы продолжиться.

premain у метода есть одна из двух возможных подписей. JVM сначала пытается вызвать следующий метод на агент class:

public static void premain(String agentArgs, Instrumentation inst);

Если агент, class не реализует этот метод тогда JVM, попытается вызвать:

public static void premain(String agentArgs);

Агент class может также иметь agentmain метод для использования, когда агент запускается после запуска VM. Когда агент запускается, используя параметр командной строки, agentmain метод не вызывается.

class агента будет загружен системой загрузчик class (см. ClassLoader.getSystemClassLoader). Это - загрузчик class, который обычно загружает class, содержащий приложение main метод. premain методы будут выполнены в соответствии с той же самой безопасностью и правилами classloader как приложение main метод. Нет никаких ограничений моделирования на какой агент premain метод может сделать. Что-либо приложение main может сделать, включая создание потоков, является законным от premain.

Каждый агент передают его опции агента через agentArgs параметр. Опции агента передают как единственная строка, любой дополнительный парсинг должен быть выполнен агентом непосредственно.

Если агент не может быть разрешен (например, потому что агент, class не может быть загружен, или потому что у агента class нет соответствующего premain метод), JVM прервется. Если a premain метод выдает непойманное исключение, JVM прервется.

Запуск Агентов После Запуска VM

Реализация может обеспечить механизм, чтобы запустить агенты когда-то после, VM запустился. Детали относительно того, как это инициируется, являются определенной реализацией, но обычно приложение уже запустилось и main метод был уже вызван. В случаях, где реализация поддерживает запуск агентов после того, как запустился VM, следующее применяется:

1. Декларация JAR агента должна содержать атрибут Agent-Class. Значение этого атрибута является именем агента class.

2. Агент class должен реализовать общедоступные помехи agentmain метод.

3. Система загрузчик class ( ClassLoader.getSystemClassLoader) должен поддерживать механизм, чтобы добавить файл JAR агента к системе путь class.

JAR агента добавляется к системе путь class. Это - загрузчик class, который обычно загружает class, содержащий приложение main метод. Агент class загружается и JVM, пытается вызвать agentmain метод. JVM сначала пытается вызвать следующий метод на агент class:

public static void agentmain(String agentArgs, Instrumentation inst);

Если агент, class не реализует этот метод тогда JVM, попытается вызвать:

public static void agentmain(String agentArgs);

Агент class может также иметь premain метод для использования, когда агент запускается, используя параметр командной строки. Когда агент запускается после того, как VM запускаются premain метод не вызывается.

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

agentmain метод должен сделать любую необходимую инициализацию, требуемую запустить агент. Когда запуск полон, метод должен возвратиться. Если агент не может быть запущен (например, потому что агент, class не может быть загружен, или потому что у агента class нет совместимого agentmain метод), JVM не будет прерываться. Если agentmain метод выдает непойманное исключение, он будет проигнорирован.

Явные Атрибуты

Следующие явные атрибуты определяются для файла JAR агента:

Premain-Class

Когда агент определяется во время запуска JVM, этот атрибут определяет агент class. Таким образом, class, содержащий premain метод. Когда агент определяется во время запуска JVM, этот атрибут требуется. Если атрибут не будет присутствовать, то JVM прервется. Отметьте: это - имя class, не имя файла или путь.

Agent-Class

Если реализация поддерживает механизм, чтобы запустить агенты когда-то после того, как VM запустился тогда, этот атрибут определяет агент class. Таким образом, class, содержащий agentmain метод. Этот атрибут требуется, если он не будет присутствовать, то агент не будет запущен. Отметьте: это - имя class, не имя файла или путь.

Boot-Class-Path

Список путей, которые будут искаться начальной загрузкой загрузчик class. Пути представляют каталоги или библиотеки (обычно называемый JAR, или архивируйте библиотеки по многим платформам). Эти пути ищутся начальной загрузкой загрузчик class после платформы, которую привели к сбою определенные механизмы определения местоположения class. Пути ищутся в перечисленном порядке. Пути в списке разделяются одними или более пробелами. Путь берет синтаксис компонента пути иерархического URI. Путь является абсолютным, если он начинается с символа наклонной черты (' / '), иначе это относительно. Относительный путь разрешается против абсолютного пути файла JAR агента. Игнорируются уродливые и несуществующие пути. Когда агент запускается когда-то после того, как VM запустил тогда пути, которые не представляют файл JAR, игнорируются. Этот атрибут является дополнительным.

Can-Redefine-Classes

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

Can-Retransform-Classes

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

Can-Set-Native-Method-Prefix

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

У файла JAR агента могут быть оба Premain-Class и Agent-Class атрибуты, существующие в декларации. Когда агент запускается на командной строке, используя -javaagent опция тогда Premain-Class атрибут определяет имя агента class и Agent-Class атрибут игнорируется. Точно так же, если агент запускается когда-то после того, как VM запустился, то Agent-Class атрибут определяет имя агента class (значение Premain-Class атрибут игнорируется).

Связанная Документация

Для документации инструмента, пожалуйста, см.:

• Инструменты JDK и Утилиты

С тех пор:

JDK1.5