Пакет java.lang.instrument

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

public static void premain(String agentArgs);

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

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

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

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

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

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

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

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

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

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

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

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

public static void agentmain(String agentArgs);

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

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

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

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

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

Premain-Class

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

Agent-Class

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

Boot-Class-Path

Список путей, которые будут искаться загрузчиком класса начальной загрузки. Пути представляют каталоги или библиотеки (обычно называемый JAR, или архивируйте библиотеки по многим платформам). Эти пути ищутся загрузчиком класса начальной загрузки после платформы, которую привели к сбою определенные механизмы определения местоположения класса. Пути ищутся в перечисленном порядке. Пути в списке разделяются одними или более пробелами. Путь берет синтаксис компонента пути иерархического 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 атрибут определяет имя класса агента и Agent-Class атрибут игнорируется. Точно так же, если агент запускается когда-то после того, как VM запустился, то Agent-Class атрибут определяет имя класса агента (значение Premain-Class атрибут игнорируется).

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

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

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

С тех пор:

JDK1.5