Интерфейс 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`.
Целевая ВМ запускает отладчик (иногда называется отладкой "в реальном времени")	Целевая ВМ запускается с параметрами `-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, установленных на платформе. Услуга транспорта устанавливается на платформе, если она установлена в файле jar, который виден для загрузчика классов, определяющего тип TransportService, и этот файл jar содержит файл конфигурации поставщика с именем TransportService в каталоге ресурсов META-INF/services, а файл конфигурации поставщика содержит полное имя класса реализации службы транспорта. Услуга транспорта — это конкретный подкласс 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. Любой из возвращённых объектов может быть использован для запуска новой целевой виртуальной машины и немедленного создания зеркала VirtualMachine для неё. Обратите внимание, что целевая виртуальная машина, запущенная запускающим подключением, не гарантируется стабильной до получения события VMStartEvent.

Возвращает:: список объектов LaunchingConnector.

attachingConnectors

List<AttachingConnector> attachingConnectors()

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

Возвращает:: список объектов AttachingConnector.

listeningConnectors

List<ListeningConnector> listeningConnectors()

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

Возвращает:: список объектов ListeningConnector.

allConnectors

List<Connector> allConnectors()

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

Возвращает:: список объектов Connector.

connectedVirtualMachines

List<VirtualMachine> connectedVirtualMachines()

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

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

majorInterfaceVersion

int majorInterfaceVersion()

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

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

minorInterfaceVersion

int minorInterfaceVersion()

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

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

createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException

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

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

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

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

Параметры:

connection - Открытое соединение с целевой виртуальной машиной.

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

Возвращает:

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

Исключения:

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

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

С тех пор:

1.5

См. также:

createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection) throws IOException

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

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

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

© 1993, 2023, 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://docs.oracle.com/en/java/javase/21/docs/api/jdk.jdi/com/sun/jdi/VirtualMachineManager.html