Класс VirtualMachine

java.lang.Object

com.sun.tools.attach.VirtualMachine

public abstract class VirtualMachine extends Object

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

VirtualMachine представляет виртуальную машину Java, к которой подключена эта виртуальная машина 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`.

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

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создает и возвращает копию этого объекта.
`protected void`	`finalize()`	Устарело, подлежит удалению: этот элемент API подлежит удалению в будущей версии. Финализация объявлена устаревшей и подлежит удалению в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного промежутка реального времени.

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

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 Interface. Обратите внимание, что функция Agent_OnAttach[_L] вызывается, даже если библиотека агента была загружена до вызова этого метода.

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

Параметры:

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

options — параметры, передаваемые функции Agent_OnAttach[_L] (может быть null).

Исключения:

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.