Класс VirtualMachine

java.lang.Object

com.sun.tools.attach.VirtualMachine

public abstract class VirtualMachine extends Object

Виртуальная машина Java.

Объект VirtualMachine представляет виртуальную машину Java, к которой подключена данная виртуальная машина Java. Виртуальная машина, к которой она подключена, иногда называется целевой виртуальной машиной или целевой ВМ. Приложение (обычно инструмент, например, консоль управления или профайлер) использует VirtualMachine для загрузки агента в целевую ВМ. Например, инструмент-профайлер, написанный на языке Java, может подключиться к работающему приложению и загрузить свой агент-профайлер для профилирования работающего приложения.

VirtualMachine получается, вызвав метод attach с идентификатором, определяющим целевую виртуальную машину. Идентификатор зависит от реализации, но обычно представляет собой идентификатор процесса (или pid) в средах, где каждая виртуальная машина Java работает в собственном процессе операционной системы. В качестве альтернативы экземпляр VirtualMachine получается вызовом метода attach с объектом VirtualMachineDescriptor, полученным из списка описателей виртуальных машин, возвращаемых методом list. После получения ссылки на виртуальную машину методы loadAgent, loadAgentLibrary и loadAgentPath используются для загрузки агентов в целевую виртуальную машину. Метод loadAgent используется для загрузки агентов, написанных на языке Java и развернутых в JAR file. (См. java.lang.instrument для подробного описания того, как эти агенты загружаются и запускаются). Методы loadAgentLibrary и loadAgentPath используются для загрузки агентов, развернутых либо в динамической библиотеке, либо статически связанных с ВМ и использующих Интерфейс инструментов JVM.

В дополнение к загрузке агентов VirtualMachine предоставляет чтение доступа к system properties в целевой ВМ. Это может быть полезно в некоторых средах, где свойства, такие как java.home, os.name или os.arch, используются для построения пути к агенту, который будет загружен в целевую ВМ.

Следующий пример демонстрирует использование VirtualMachine:


      // attach to target VM
      VirtualMachine vm = VirtualMachine.attach("2177");

      // start management agent
      Properties props = new Properties();
      props.put("com.sun.management.jmxremote.port", "5000");
      vm.startManagementAgent(props);

      // detach
      vm.detach();

В этом примере мы подключаемся к виртуальной машине Java, идентифицированной идентификатором процесса 2177. Затем агент управления JMX запускается в целевом процессе с предоставленными аргументами. Наконец, клиент отсоединяется от целевой ВМ.

VirtualMachine безопасно использовать для нескольких потоков одновременно.

С:: 1.6

Краткое описание конструкторов

VirtualMachine(AttachProvider provider,
 String id)

Модификатор	Конструктор	Описание
`protected`	Инициализирует новый экземпляр этого класса.

Краткое описание методов

Модификатор и тип	Метод	Описание
`static VirtualMachine`	`attach(VirtualMachineDescriptor vmd)`	Подключение к виртуальной машине Java.
`static VirtualMachine`	`attach(String id)`	Подключение к виртуальной машине Java.
`abstract void`	`detach()`	Отключение от виртуальной машины.
`boolean`	`equals(Object ob)`	Проверка этого VirtualMachine на равенство другому объекту.
`abstract Properties`	`getAgentProperties()`	Возвращает текущие свойства агента в целевой виртуальной машине.
`abstract Properties`	`getSystemProperties()`	Возвращает текущие системные свойства в целевой виртуальной машине.
`int`	`hashCode()`	Возвращает значение хэш-кода для этого VirtualMachine.
`final String`	`id()`	Возвращает идентификатор этой виртуальной машины Java.
`static List<VirtualMachineDescriptor>`	`list()`	Возвращает список виртуальных машин Java.
`void`	`loadAgent(String agent)`	Загрузка агента.
`abstract void`	`loadAgent(String agent, String options)`	Загрузка агента.
`void`	`loadAgentLibrary(String agentLibrary)`	Загрузка библиотеки агента.
`abstract void`	`loadAgentLibrary(String agentLibrary, String options)`	Загрузка библиотеки агента.
`void`	`loadAgentPath(String agentPath)`	Загрузка библиотеки нативного агента по полному пути.
`abstract void`	`loadAgentPath(String agentPath, String options)`	Загрузка библиотеки нативного агента по полному пути.
`final AttachProvider`	`provider()`	Возвращает поставщика, создавшего эту виртуальную машину.
`abstract String`	`startLocalManagementAgent()`	Запускает локальный агент управления JMX в целевой виртуальной машине.
`abstract void`	`startManagementAgent(Properties agentProperties)`	Запускает агент управления JMX в целевой виртуальной машине.
`String`	`toString()`	Возвращает строковое представление `VirtualMachine`.

Методы, объявленные в классе java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Подробное описание конструкторов

VirtualMachine

protected VirtualMachine(AttachProvider provider, String id)

Инициализирует новый экземпляр этого класса.

Параметры:: provider - Предоставщик подключения, создающий этот класс.; id - Абстрактный идентификатор, определяющий виртуальную машину Java.
Исключения:: NullPointerException - Если provider или id имеют значение null.

Подробное описание методов

list

public static List<VirtualMachineDescriptor> list()

Возвращает список виртуальных машин Java.

Этот метод возвращает список элементов Java VirtualMachineDescriptor. Список является агрегацией списков описателей виртуальных машин, полученных путём вызова метода listVirtualMachines всех установленных attach providers. Если никакому предоставленному классу не известны виртуальные машины Java, то возвращается пустой список.

Возвращает:: Список описателей виртуальных машин.

attach

public static VirtualMachine attach(String id) throws AttachNotSupportedException, IOException

Подключается к виртуальной машине Java.

Этот метод получает список предоставщиков подключения, вызвав метод AttachProvider.providers(). Затем он итерируется по списку и вызывает метод attachVirtualMachine каждого предоставщика поочерёдно. Если предоставщик успешно подключится, итерация прекращается, а VirtualMachine, созданный предоставщиком, который успешно подключился, возвращается этим методом. Если метод attachVirtualMachine всех поставщиков генерирует AttachNotSupportedException, то и этот метод генерирует AttachNotSupportedException. Это означает, что AttachNotSupportedException выбрасывается, когда предоставленный идентификатор недействителен, или идентификатор соответствует виртуальной машине Java, которая не существует, или ни один из предоставщиков не может подключиться к ней. Это исключение также выбрасывается, если AttachProvider.providers() возвращает пустой список.

Параметры:: id - Абстрактный идентификатор, определяющий виртуальную машину Java.
Возвращает:: VirtualMachine, представляющий целевую ВМ.
Исключения:: AttachNotSupportedException - Если метод attachVirtualmachine всех установленных поставщиков генерирует AttachNotSupportedException или поставщики не установлены.; IOException - Если произошла ошибка ввода-вывода; NullPointerException - Если id имеет значение null.

attach

public static VirtualMachine attach(VirtualMachineDescriptor vmd) throws AttachNotSupportedException, IOException

Подключается к виртуальной машине Java.

Этот метод сначала вызывает метод provider() данного описателя виртуальной машины, чтобы получить поставщика подключения. Затем он вызывает метод attachVirtualMachine поставщика подключения, чтобы подключиться к целевой ВМ.

Параметры:: vmd - Описание виртуальной машины.
Возвращает:: VirtualMachine, представляющий целевую ВМ.
Исключения:: AttachNotSupportedException - Если метод attachVirtualmachine поставщика подключения генерирует AttachNotSupportedException.; IOException - Если произошла ошибка ввода-вывода; NullPointerException - Если vmd имеет значение null.

detach

public abstract void detach() throws IOException

Отсоединяется от виртуальной машины.

После отсоединения от виртуальной машины любая дальнейшая попытка вызвать операции с этой виртуальной машиной приведёт к исключению IOException. Если операция (например, loadAgent) выполняется в момент вызова этого метода, то поведение зависит от реализации. Другими словами, завершение операции или возникновение IOException зависит от реализации.

Если от виртуальной машины уже отсоединились, вызов этого метода не имеет эффекта.

Исключения:: IOException - Если произошла ошибка ввода-вывода

provider

public final AttachProvider provider()

Возвращает поставщика, который создал эту виртуальную машину.

Возвращает:: Поставщика, который создал эту виртуальную машину.

id

public final String id()

Возвращает идентификатор этой виртуальной машины Java.

Возвращает:: Идентификатор этой виртуальной машины Java.

loadAgentLibrary

public abstract void loadAgentLibrary(String agentLibrary, String options) throws AgentLoadException, AgentInitializationException, IOException

Загружает библиотеку агента.

Клиент JVM TI называется агентом. Он разработан на родном языке. Агент JVM TI развёртывается специфичным для платформы способом, но обычно является платформенным эквивалентом динамической библиотеки. В качестве альтернативы, он может быть статически связан с ВМ. Этот метод вызывает загрузку данной библиотеки агента в целевую ВМ (если она ещё не загружена или не статически связана с ВМ). Затем он заставляет целевую ВМ вызвать функцию Agent_OnAttach или, для статически связанного агента с именем 'L', функцию Agent_OnAttach_L, как указано в спецификации JVM Tools Interface. Обратите внимание, что функция Agent_OnAttach[_L] вызывается даже если библиотека агента была загружена до вызова этого метода.

Предоставленная библиотека агента — это имя библиотеки агента. Оно интерпретируется в целевой виртуальной машине способом, зависящим от реализации. Обычно реализация расширит имя библиотеки в имя файла, специфичное для операционной системы. Например, в системах UNIX имя L может быть расширено до libL.so и найдено с использованием пути поиска, указанного переменной среды LD_LIBRARY_PATH. Если агент с именем 'L' статически связан с ВМ, то ВМ должна экспортировать функцию Agent_OnAttach_L.

Если функция Agent_OnAttach[_L] в библиотеке агента возвращает ошибку, то выбрасывается AgentInitializationException. Возвращаемое значение функции Agent_OnAttach[_L] можно получить, вызвав метод returnValue в исключении.

Параметры:

agentLibrary - Имя библиотеки агента.

options - Параметры для передачи функции Agent_OnAttach[_L] (могут быть null).

Исключения:

AgentLoadException - Если библиотека агента не существует, библиотека агента не статически связана с ВМ, или библиотека агента не может быть загружена по другой причине.

AgentInitializationException - Если функция Agent_OnAttach[_L] возвращает ошибку.

IOException - Если произошла ошибка ввода-вывода

NullPointerException - Если agentLibrary имеет значение null.

См. также:

loadAgentLibrary

public void loadAgentLibrary(String agentLibrary) throws AgentLoadException, AgentInitializationException, IOException

Загружает библиотеку агента.

Этот метод-удобство работает так, как если бы был вызван:

loadAgentLibrary(agentLibrary, null);

Параметры:: agentLibrary - Имя библиотеки агента.
Исключения:: AgentLoadException - Если библиотека агента не существует, библиотека агента не статически связана с ВМ, или библиотека агента не может быть загружена по другой причине.; AgentInitializationException - Если функция Agent_OnAttach[_L] возвращает ошибку.; IOException - Если произошла ошибка ввода-вывода; NullPointerException - Если agentLibrary имеет значение null.

loadAgentPath

public abstract void loadAgentPath(String agentPath, String options) throws AgentLoadException, AgentInitializationException, IOException

Загрузить библиотеку нативного агента по полному пути.

Клиент JVM TI называется агентом. Он разработан на нативном языке. Агент JVM TI развертывается платформозависимым способом, но обычно является платформенным эквивалентом динамической библиотеки. В качестве альтернативы, нативная библиотека, указанная параметром agentPath, может быть статически связана с виртуальной машиной. Разбор параметра agentPath в имя статически связанной библиотеки выполняется платформозависимым способом в виртуальной машине. Например, в UNIX параметр agentPath /a/b/libL.so будет указывать на библиотеку 'L'. Более подробную информацию см. в спецификации JVM TI. Этот метод заставляет загрузить указанную библиотеку агента в целевую виртуальную машину (если она еще не загружена или не статически связана с виртуальной машиной). Затем он заставляет целевую виртуальную машину вызвать функцию Agent_OnAttach или, для статически связанного агента с именем 'L', функцию Agent_OnAttach_L, как указано в спецификации интерфейса JVM Tools. Обратите внимание, что функция Agent_OnAttach[_L] вызывается даже если библиотека агента была загружена до вызова этого метода.

Предоставляемая библиотека агента — это абсолютный путь для загрузки библиотеки агента. В отличие от loadAgentLibrary, имя библиотеки не расширяется в целевой виртуальной машине.

Если функция Agent_OnAttach[_L] в библиотеке агента возвращает ошибку, то будет брошено исключение AgentInitializationException. Возвращаемое значение из функции Agent_OnAttach[_L] можно получить, вызвав метод returnValue на исключении.

Параметры:

agentPath - Полный путь к библиотеке агента.

options - Параметры для передачи функции Agent_OnAttach[_L] (может быть null).

Исключения:

AgentLoadException - Если библиотека агента не существует, библиотека агента не статически связана с виртуальной машиной или библиотека агента не может быть загружена по другой причине.

AgentInitializationException - Если функция Agent_OnAttach[_L] возвращает ошибку.

IOException - Если произошла ошибка ввода-вывода

NullPointerException - Если agentPath является null.

См. также:

loadAgentPath

public void loadAgentPath(String agentPath) throws AgentLoadException, AgentInitializationException, IOException

Загрузить библиотеку нативного агента по полному пути.

Этот метод удобства работает так, как если бы вызывали:

loadAgentPath(agentLibrary, null);

Параметры:: agentPath - Полный путь к библиотеке агента.
Исключения:: AgentLoadException - Если библиотека агента не существует, библиотека агента не статически связана с виртуальной машиной или библиотека агента не может быть загружена по другой причине.; AgentInitializationException - Если функция Agent_OnAttach[_L] возвращает ошибку.; IOException - Если произошла ошибка ввода-вывода; NullPointerException - Если agentPath является null.

loadAgent

public abstract void loadAgent(String agent, String options) throws AgentLoadException, AgentInitializationException, IOException

Загружает агента.

Агент, предоставленный этому методу, — это имя пути к файлу JAR в файловой системе целевой виртуальной машины. Этот путь передается целевой виртуальной машине, где он интерпретируется. Целевая виртуальная машина пытается запустить агента в соответствии со спецификацией java.lang.instrument. То есть, указанный файл JAR добавляется в системный путь к классам (целевой виртуальной машины), и вызывается метод agentmain класса агента, указанный атрибутом Agent-Class в манифесте JAR. Этот метод завершается, когда завершается метод agentmain.

Параметры:: agent - Путь к файлу JAR, содержащему агента.; options - Параметры для передачи методу agentmain агента (может быть null).
Исключения:: AgentLoadException - Если агента не существует или он не может быть запущен в соответствии со спецификацией java.lang.instrument.; AgentInitializationException - Если agentmain вызывает исключение; IOException - Если произошла ошибка ввода-вывода; NullPointerException - Если agent является null.

loadAgent

public void loadAgent(String agent) throws AgentLoadException, AgentInitializationException, IOException

Загружает агента.

Этот метод удобства работает так, как если бы вызывали:

loadAgent(agent, null);

Параметры:: agent - Путь к файлу JAR, содержащему агента.
Исключения:: AgentLoadException - Если агента не существует или он не может быть запущен в соответствии со спецификацией java.lang.instrument.; AgentInitializationException - Если agentmain вызывает исключение; IOException - Если произошла ошибка ввода-вывода; NullPointerException - Если agent является null.

getSystemProperties

public abstract Properties getSystemProperties() throws IOException

Возвращает текущие системные свойства в целевой виртуальной машине.

Этот метод возвращает системные свойства в целевой виртуальной машине. Свойства, у которых ключ или значение не являются String, опускаются. Метод примерно эквивалентен вызову метода System.getProperties в целевой виртуальной машине, за исключением того, что свойства с ключом или значением, которое не является String, не включаются.

Этот метод обычно используется для определения агента, который нужно загрузить в целевую виртуальную машину с помощью loadAgent или loadAgentLibrary. Например, свойства java.home или user.dir могут использоваться для создания пути к библиотеке агента или файлу JAR.

Возвращает:

Системные свойства

Исключения:

AttachOperationFailedException - Если целевая виртуальная машина не может завершить операцию подключения. Более подробное сообщение об ошибке будет предоставлено методом Throwable.getMessage().

IOException - Если произошла ошибка ввода-вывода или ошибка связи, например, которая не может быть определена как ошибка, указывающая на то, что операция завершилась ошибкой в целевой виртуальной машине.

См. также:

getAgentProperties

public abstract Properties getAgentProperties() throws IOException

Возвращает текущие свойства агента в целевой виртуальной машине.

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

Этот метод возвращает свойства агента, у которых ключ и значение являются String. Свойства, у которых ключ или значение не являются String, опускаются. Если в целевой виртуальной машине нет свойств агента, возвращается пустой список свойств.

Возвращает:: Свойства агента
Исключения:: AttachOperationFailedException - Если целевая виртуальная машина не может завершить операцию подключения. Более подробное сообщение об ошибке будет предоставлено методом Throwable.getMessage().; IOException - Если произошла ошибка ввода-вывода или ошибка связи, например, которая не может быть определена как ошибка, указывающая на то, что операция завершилась ошибкой в целевой виртуальной машине.

startManagementAgent

public abstract void startManagementAgent(Properties agentProperties) throws IOException

Запускает агента управления JMX в целевой виртуальной машине.

Параметры конфигурации совпадают с теми, которые указаны в командной строке при запуске агента управления JMX. Так же, как и в командной строке, необходимо указать, по крайней мере, свойство com.sun.management.jmxremote.port.

Дополнительные сведения см. в онлайн-документации Мониторинг и управление с помощью технологии JMX.

Параметры:: agentProperties - Объект Properties, содержащий параметры конфигурации для агента.
Исключения:: AttachOperationFailedException - Если целевая виртуальная машина не может завершить операцию подключения. Более подробное сообщение об ошибке будет предоставлено методом Throwable.getMessage().; IOException - Если произошла ошибка ввода-вывода или ошибка связи, например, которая не может быть определена как ошибка, указывающая на то, что операция завершилась ошибкой в целевой виртуальной машине.; IllegalArgumentException - Если ключи или значения в agentProperties неверны.; NullPointerException - Если agentProperties равно null.
С момента:: 1.8

startLocalManagementAgent

public abstract String startLocalManagementAgent() throws IOException

Запускает локальный агент управления JMX в целевой виртуальной машине.

Для получения дополнительной информации см. онлайн-документацию по Мониторингу и управлению с помощью технологии JMX.

Возвращает:: Строковое представление адреса службы локального подключения. Значение может быть обработано конструктором JMXServiceURL(String).
Издаёт исключение:: AttachOperationFailedException - Если целевая виртуальная машина не может завершить операцию присоединения. Более конкретное сообщение об ошибке будет предоставлено Throwable.getMessage().; IOException - Если произошла ошибка ввода-вывода, например, ошибка связи, которую нельзя определить как ошибку, чтобы указать, что операция завершилась неудачно в целевой ВМ.
С:: 1.8

hashCode

public int hashCode()

Возвращает значение хэш-кода для этой VirtualMachine. Хэш-код основан на компонентах VirtualMachine и удовлетворяет общему контракту метода Object.hashCode.

Переопределяет:

hashCode в классе Object

Возвращает:

Значение хэш-кода для этой виртуальной машины

См. также:

equals

public boolean equals(Object ob)

Проверяет эту VirtualMachine на равенство с другим объектом.

Если заданный объект не является VirtualMachine, то этот метод возвращает false. Для того чтобы две VirtualMachine считались равными, необходимо, чтобы они обе ссылались на один и тот же поставщик, и их identifiers были равны.

Этот метод удовлетворяет общему контракту метода Object.equals.

Переопределяет:

equals в классе Object

Параметры:

ob - Объект, с которым сравнивается этот объект

Возвращает:

true тогда и только тогда, когда заданный объект является VirtualMachine, равным этому VirtualMachine.

См. также:

toString

public String toString()

Возвращает строковое представление VirtualMachine.

Переопределяет:: toString в классе Object
Возвращает:: строковое представление объекта

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/jdk.attach/com/sun/tools/attach/VirtualMachine.html