Интерфейс 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, установленных на платформе. Сервис транспорта устанавливается на платформе, если он установлен в файле jar, который виден определяющему загрузчику класса для типа TransportService, и этот файл jar содержит файл конфигурации провайдера с именем TransportService в каталоге ресурсов META-INF/services, и файл конфигурации провайдера содержит полное имя класса реализации сервиса транспорта. Сервис транспорта — это конкретный подкласс TransportService. Формат файла конфигурации провайдера такой же, как и для коннекторов, за исключением того, что каждый перечисленный класс должен быть полным именем класса, реализующего интерфейс TransportService.

END_OF_DOCUMENT_MARKER

Для каждого установленного на платформе 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

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

Modifier and Type	Method	Description
`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 устанавливает соединение и успешно выполняет рукопожатие с целевой виртуальной машиной. Затем соединитель может использовать этот метод для создания зеркала виртуальной машины для представления составного состояния целевой виртуальной машины.

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

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

Параметры:

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, 2021, 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/17/docs/api/jdk.jdi/com/sun/jdi/VirtualMachineManager.html