Интерфейс VirtualMachineManager

public interface VirtualMachineManager

Менеджер подключений к целевым виртуальным машинам. VirtualMachineManager позволяет одному приложению отлаживать несколько целевых ВМ. (Обратите внимание, что обратное не поддерживается; целевая ВМ может быть отлажена только одним приложением-отладчиком.) Данный интерфейс содержит методы для управления подключениями к удалённым целевым ВМ и получения зеркала VirtualMachine для доступных целевых ВМ.

Подключения могут быть установлены с помощью одного из нескольких различных объектов Connector. Каждый коннектор описывает различный способ подключения отладчика к целевой ВМ.

VirtualMachineManager поддерживает множество различных сценариев подключения отладчика к виртуальной машине. Четыре примера представлены в таблице ниже. Примеры используют синтаксис командной строки в реализации Sun. Некоторые реализации Connector могут потребовать немного иного обращения, чем представлено ниже.

Четыре сценария подключения отладчика к виртуальной машине"
Сценарий	Описание
Отладчик запускает целевую ВМ (простейший, наиболее распространённый сценарий)	Отладчик вызывает метод `LaunchingConnector.launch(java.util.Map)` по умолчанию коннектора, полученного с помощью `defaultConnector()`. Целевая ВМ запускается, и устанавливается соединение между этой ВМ и отладчиком. Возвращается зеркало `VirtualMachine`. Или, для большего контроля Отладчик выбирает коннектор из списка, возвращённого `launchingConnectors()`, с желаемыми характеристиками (например, тип транспорта и т. д.). Отладчик вызывает метод `LaunchingConnector.launch(java.util.Map)` выбранного коннектора. Целевая ВМ запускается, и устанавливается соединение между этой ВМ и отладчиком. Возвращается зеркало `VirtualMachine`.
Отладчик подключается к ранее запущенной ВМ	Целевая ВМ запускается с параметрами `-agentlib:jdwp=transport=xxx,server=y` Целевая ВМ генерирует и выводит адрес, специфичный для транспорта, на котором она будет ожидать подключения. Запускается отладчик. Отладчик выбирает коннектор из списка, возвращённого `attachingConnectors()`, соответствующий транспорту с именем "xxx". Отладчик предоставляет параметры коннектора по умолчанию (полученные через `Connector.defaultArguments()`) конечному пользователю, позволяя пользователю заполнить адрес, специфичный для транспорта, сгенерированный целевой ВМ. Отладчик вызывает метод `AttachingConnector.attach(java.util.Map)` выбранного коннектора для подключения к целевой ВМ. Возвращается зеркало `VirtualMachine`.
Целевая ВМ подключается к ранее запущенному отладчику	При запуске отладчик выбирает один или несколько коннекторов из списка, возвращённого `listeningConnectors()`, для одного или нескольких транспортов. Отладчик вызывает метод `ListeningConnector.startListening(java.util.Map)` для каждого выбранного коннектора. Для каждого вызова генерируется и возвращается строка адреса, специфичная для транспорта. Отладчик предоставляет имена транспортов и соответствующие строки адресов конечному пользователю. Отладчик вызывает `ListeningConnector.accept(java.util.Map)` для каждого выбранного коннектора, чтобы ожидать подключения целевой ВМ. Позже, целевая ВМ запускается конечным пользователем с параметрами `-agentlib:jdwp=transport=xxx,address=yyy`, где "xxx" - транспорт для одного из коннекторов, выбранных отладчиком, а "yyy" - адрес, сгенерированный `ListeningConnector.accept(java.util.Map)` для этого транспорта. Вызов отладчика `ListeningConnector.accept(java.util.Map)` возвращает зеркало `VirtualMachine`.
Целевая ВМ запускает отладчик (иногда называется отладкой "Just-In-Time")	Целевая ВМ запускается с параметрами `-agentlib:jdwp=launch=cmdline,onuncaught=y,transport=xxx,server=y` Позже, в целевой ВМ происходит необработанное исключение. Целевая ВМ генерирует адрес, специфичный для транспорта, на котором она будет ожидать подключения. Целевая ВМ запускает отладчик со следующими пунктами, соединёнными вместе (разделенными пробелами), чтобы сформировать командную строку: Значение launch= Значение transport= Сгенерированный адрес, специфичный для транспорта, по которому ВМ ожидает подключения отладчика. При запуске отладчик выбирает коннектор из списка, возвращённого `attachingConnectors()`, соответствующий транспорту с именем "xxx". Отладчик изменяет параметры коннектора по умолчанию (полученные через `Connector.defaultArguments()`), чтобы указать адрес, специфичный для транспорта, на котором ВМ ожидает подключения. При необходимости, другие параметры коннектора могут быть представлены пользователю. Отладчик вызывает метод `AttachingConnector.attach(java.util.Map)` выбранного коннектора для подключения к целевой ВМ. Возвращается зеркало `VirtualMachine`.

Коннекторы создаются во время запуска. То есть, они создаются в первый раз, когда вызывается Bootstrap.virtualMachineManager(). Список всех коннекторов, созданных во время запуска, можно получить из VirtualMachineManager, вызвав метод allConnectors.

Коннекторы создаются во время запуска, если они установлены в платформе. Кроме того, коннекторы создаются автоматически VirtualMachineManager для инкапсуляции любых реализаций TransportService, установленных в платформе. Эти два механизма создания коннекторов описаны здесь.

Коннектор устанавливается на платформе, если он установлен в файле jar, который виден определяющему загрузчику класса типа Connector, и этот файл jar содержит файл конфигурации поставщика с именем Connector в каталоге ресурсов META-INF/services, и файл конфигурации поставщика перечисляет полное имя класса реализации коннектора. Коннектор - это класс, реализующий интерфейс Connector. Более точно, класс реализует один из конкретных типов коннекторов, а именно AttachingConnector, ListeningConnector или LaunchingConnector. Формат файла конфигурации поставщика - по одному полному имени класса на строке. Пробелы и символы табуляции вокруг каждого класса, а также пустые строки игнорируются. Символ комментария - '#' (0x23), и на каждой строке все символы после первого символа комментария игнорируются. Файл должен быть закодирован в UTF-8.

Во время запуска VirtualMachineManager пытается загрузить и создать (используя конструктор без аргументов) каждый класс, перечисленный в файле конфигурации поставщика. Исключения, возникающие при загрузке или создании коннектора, перехватываются и игнорируются. Другими словами, процесс запуска продолжается несмотря на ошибки.

В дополнение к коннекторам, установленным на платформе, VirtualMachineManager также будет создавать коннекторы для инкапсуляции любых реализаций TransportService, установленных на платформе. TransportService устанавливается на платформе, если он установлен в файле jar, который виден определяющему загрузчику класса типа TransportService, и этот файл jar содержит файл конфигурации поставщика с именем TransportService в каталоге ресурсов META-INF/services, и файл конфигурации поставщика перечисляет полное имя класса реализации TransportService. TransportService является конкретным подклассом TransportService. Формат файла конфигурации поставщика такой же, как и для коннекторов, за исключением того, что каждый указанный класс должен быть полным именем класса, реализующего интерфейс TransportService.

Для каждого установленного на платформе TransportService, VirtualMachineManager создаёт соответствующий AttachingConnector и ListeningConnector. Эти Connectors созданы для инкапсуляции Transport, который в свою очередь инкапсулирует TransportService. AttachingConnector будет именоваться на основе имени транспортной службы, соединённого со строкой Attach. Например, если метод транспортной службы name() возвращает telepathic, то AttachingConnector будет именоваться telepathicAttach. Аналогично, ListeningConnector будет именоваться, добавив строку Listen к имени транспортной службы. Метод description() как AttachingConnector, так и ListeningConnector, будет делегировать вызов методу description() подчинённой транспортной службы. Как AttachingConnector, так и ListeningConnector будут иметь два Connector Arguments. StringArgument с именем address — аргумент коннектора для указания адреса подключения или прослушивания. IntegerArgument с именем timeout — аргумент коннектора для указания таймаута при подключении или приёме. Таймаут коннектора может быть проигнорирован, в зависимости от того, поддерживает ли транспортная служба таймаут подключения или приёма.

Инициализация менеджера виртуальной машины завершится ошибкой, то есть Bootstrap.virtualMachineManager() выбросит ошибку, если менеджер виртуальной машины не сможет создать какие-либо коннекторы.

Since:: 1.3

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

Модификатор и тип	Метод	Описание
`List<Connector>`	`allConnectors()`	Возвращает список всех известных объектов `Connector`.
`List<AttachingConnector>`	`attachingConnectors()`	Возвращает список известных объектов `AttachingConnector`.
`List<VirtualMachine>`	`connectedVirtualMachines()`	Отображает все целевые виртуальные машины, подключённые к отладчику.
`VirtualMachine`	`createVirtualMachine(Connection connection)`	Создаёт новую виртуальную машину.
`VirtualMachine`	`createVirtualMachine(Connection connection, Process process)`	Создаёт зеркало виртуальной машины для целевой виртуальной машины.
`LaunchingConnector`	`defaultConnector()`	Определяет стандартный коннектор.
`List<LaunchingConnector>`	`launchingConnectors()`	Возвращает список известных объектов `LaunchingConnector`.
`List<ListeningConnector>`	`listeningConnectors()`	Возвращает список известных объектов `ListeningConnector`.
`int`	`majorInterfaceVersion()`	Возвращает номер основной версии интерфейса JDI.
`int`	`minorInterfaceVersion()`	Возвращает номер дополнительной версии интерфейса JDI.

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

defaultConnector

LaunchingConnector defaultConnector()

Определяет подключение по умолчанию. Это подключение должно использоваться в качестве запускающего, когда выбор подключения со специфическими характеристиками не требуется.

Возвращает:: подключение по умолчанию LaunchingConnector

launchingConnectors

List<LaunchingConnector> launchingConnectors()

Возвращает список известных объектов запускающих подключений LaunchingConnector. Любой из возвращённых объектов может быть использован для запуска новой виртуальной машины (VM) и немедленного создания зеркала VirtualMachine для неё. Обратите внимание, что запущенная целевая виртуальная машина (VM) посредством запускающего подключения не гарантированно будет стабильной до получения события VMStartEvent.

Возвращает:: список объектов запускающих подключений LaunchingConnector.

attachingConnectors

List<AttachingConnector> attachingConnectors()

Возвращает список известных объектов присоединяющих подключений AttachingConnector. Любой из возвращённых объектов может быть использован для присоединения к существующей целевой виртуальной машине (VM) и создания зеркала VirtualMachine для неё.

Возвращает:: список объектов присоединяющих подключений AttachingConnector.

listeningConnectors

List<ListeningConnector> listeningConnectors()

Возвращает список известных объектов прослушивающих подключений ListeningConnector. Любой из возвращённых объектов может быть использован для прослушивания подключения, инициированного целевой виртуальной машиной (VM), и создания зеркала VirtualMachine для неё.

Возвращает:: список объектов прослушивающих подключений ListeningConnector.

allConnectors

List<Connector> allConnectors()

Возвращает список всех известных объектов подключений Connector.

Возвращает:: список объектов подключений Connector.

connectedVirtualMachines

List<VirtualMachine> connectedVirtualMachines()

Перечисляет все целевые виртуальные машины (VM), подключенные к отладчику. Список включает экземпляры VirtualMachine для всех целевых виртуальных машин (VM), которые инициировали подключение, и для всех целевых виртуальных машин (VM), к которым данный менеджер инициировал подключение. Целевая виртуальная машина (VM) останется в этом списке до отключения VM. VMDisconnectEvent помещается в очередь событий после удаления VM из списка.

Возвращает:: список объектов VirtualMachine, каждое из которых отражает целевую виртуальную машину (VM).

majorInterfaceVersion

int majorInterfaceVersion()

Возвращает номер основной версии интерфейса JDI. Смотрите VirtualMachine.version() для получения версии и информации о целевой виртуальной машине (VM) и VirtualMachine.description() для получения дополнительной информации о версии.

Возвращает:: целое число основного номера версии.

minorInterfaceVersion

int minorInterfaceVersion()

Возвращает номер дополнительной версии интерфейса JDI. Смотрите VirtualMachine.version() для получения версии и информации о целевой виртуальной машине (VM) и VirtualMachine.description() для получения дополнительной информации о версии.

Возвращает:: целое число дополнительного номера версии

createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException

Создаёт зеркало виртуальной машины (VM) для целевой VM.

Создаёт зеркало виртуальной машины (VM) для целевой VM, для которой уже существует Connection. Подключение создаётся, когда Connector устанавливает подключение и успешно завершает обмен с целевой виртуальной машиной (VM). Затем Connector может использовать этот метод для создания зеркала виртуальной машины (VM) для представления составного состояния целевой VM.

Аргумент process задаёт объект Process для целевой VM. Он может быть указан как null. Если целевая VM запущена посредством LaunchingConnector то аргумент process должен быть указан, в противном случае вызов VirtualMachine.process() на созданной виртуальной машине (VM) вернёт null.

Этот метод предназначен для того, чтобы Connectors могли создавать зеркало виртуальной машины (VM), когда установлено подключение к целевой VM. Только разработчики, создающие новые реализации Connectors, должны использовать этот метод напрямую.

Параметры:

connection - Открытое подключение к целевой VM.

process - Если запущено, объект Process для целевой VM. null если не запущено.

Возвращает:

новую виртуальную машину, представляющую целевую VM.

Исключения:

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

IllegalStateException - если подключение не открыто

С:

1.5

См. также:

createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection) throws IOException

Создаёт новую виртуальную машину.

Этот удобный метод работает так, как будто вызывается метод createVirtualMachine(Connection, Process) и задаёт null в качестве аргумента process.

Возвращает:: новую виртуальную машину
Исключения:: IOException - если произошла ошибка ввода-вывода; IllegalStateException - если подключение не открыто
С:: 1.5

© 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.jdi/com/sun/jdi/VirtualMachineManager.html