спецификации, руководства, описания, API

Протокол Провода Отладки ^JavaTM

Краткий обзор

Протокол Провода Отладки ^JavaTM (JDWP) является протоколом, используемым для передачи между отладчиком и виртуальной машиной Java (VM), который это отлаживает (после этого названный целевым VM). JDWP является дополнительным; это не могло бы быть доступно в некоторых реализациях Java (ТМ) 2 SDK. Существование JDWP может позволить тому же самому отладчику работать

в различном процессе на том же самом компьютере, или
на удаленном компьютере,

JDWP отличается от многих спецификаций протокола, в которых он только детализирует формат и расположение, не транспорт. Реализация JDWP может быть разработана, чтобы принять различные транспортные механизмы через простой API. Определенный транспорт не обязательно поддерживает каждый отладчик/цель упомянутые выше комбинации VM.

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

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

JDWP является одним уровнем в пределах Архитектуры Отладчика Платформы Java (JPDA). Эта архитектура также содержит высокоуровневый Интерфейс Отладки Java (JDI). JDWP разрабатывается, чтобы облегчить эффективное использование JDI; многие из его возможностей адаптируются с этой целью. JDI является более подходящим чем JDWP для многих инструментов отладчика, особенно записанные в языке программирования Java. Для получения дополнительной информации по Архитектуре Отладчика Платформы Java см. документацию Архитектуры Отладчика Платформы Java для этого выпуска.

Запуск JDWP

После того, как транспортное соединение устанавливается и прежде, чем любые пакеты будут отправлены, квитирование происходит между двумя сторонами соединения:

У процесса квитирования есть следующие шаги:

Сторона отладчика отправляет 14 байтов стороне VM, состоя из 14 символов ASCII строки "JDWP-квитирование".
Сторона VM отвечает с теми же самыми 14 байтами: JDWP-квитирование

Пакеты JDWP

JDWP является базируемым пакетом и не является stateful. Есть два основных пакетных типа: пакеты команды и пакеты ответа.

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

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

JDWP является асинхронным; многократные пакеты команды могут быть отправлены прежде, чем первый пакет ответа получается.

Команда и пакетные заголовки ответа равны в размере; это должно сделать транспорты легче реализовать и абстрагировать. Расположение каждого пакета похоже на это:

Пакет команды

Заголовок
- длина (4 байта)
- идентификатор (4 байта)
- флаги (1 байт)
- набор команд (1 байт)
- команда (1 байт)
данные (Переменная)

Пакет ответа

Заголовок
- длина (4 байта)
- идентификатор (4 байта)
- флаги (1 байт)
- код ошибки (2 байта)
данные (Переменная)

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

Команда и Пакетные Поля Ответа

Совместно используемые Поля Заголовка

длина

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

идентификатор

Поле идентификатора используется, чтобы однозначно определить каждую пакетную пару команды/ответа. У пакета ответа есть тот же самый идентификатор как пакет команды, на который это отвечает. Это позволяет асинхронные команды и отвечает, чтобы быть соответствующим. Поле идентификатора должно быть уникальным среди всех выдающихся команд, отправленных от одного источника. (Выдающиеся команды, происходящие из отладчика, могут использовать тот же самый идентификатор в качестве выдающихся команд, происходящих из целевого VM.) Кроме этого, нет никаких требований к выделению идентификатора.

Простой монотонный счетчик должен быть достаточным для большинства реализаций. Это позволит 2^32 уникальные выдающиеся пакеты и является самой простой альтернативой реализации.

флаги

Флаги используются, чтобы измениться, как любая команда ставится в очередь и обрабатывается и тегировать пакеты команды, которые происходят из целевого VM. Есть в настоящий момент определенные флаговые биты; будущие версии протокола могут определить дополнительные флаги.

0x80: Пакет ответа

Бит ответа, когда установлено, указывает, что этот пакет является ответом.

Пакетные Поля Заголовка команды

набор команд

Это поле полезно как средство для группировки команд значимым способом. Определенные наборы команд Sun привыкли к групповым командам интерфейсами, которые они поддерживают в JDI. Например, все команды, которые поддерживают интерфейс VirtualMachine JDI, группируются в наборе команд VirtualMachine.

Пространство набора команд примерно делится следующим образом:

0 - 63: Наборы команд, отправленных целевому VM
64 - 127: Наборы команд, отправленных отладчику
128 - 256: Определенные поставщиком команды и расширения.

команда

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

Пакетные Поля Заголовка ответа

код ошибки: Это поле используется, чтобы указать, был ли пакет команды, которому отвечают также, успешно обработан. Значение нуля указывает на успех, ненулевое значение указывает на ошибку. Возвращенный код ошибки может быть определенным для каждого набора команд / команда, но это часто отображается на код ошибки TI JVM.

Данные

Поле данных уникально для каждого набора команд / команда. Это также отличается между пакетными парами команды и ответа. Например, пакет команды, который запрашивает значение поля, будет содержать ссылки на объект и полевой идентификатор для требуемого значения в его поле данных. Пакетное поле данных ответа будет содержать значение поля.

Подробная информация о Команде

Вообще, поле данных пакета команды или ответа является абстракцией группы многократных полей, которые определяют данные команды или ответа. Каждое подполе поля данных кодируется в обратном порядке байтов (Java) формат. Подробный состав полей данных для каждой команды и ее ответа описывается в этом разделе.

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

Имя	Размер	Описание
`byte`	1 байт	Значение байта.
`boolean`	1 байт	Булево значение, закодированное как 0 для лжи и ненулевой для истины.
`int`	4 байта	Четырехбайтовое целочисленное значение. Целое число подписывается если явно не утверждено, чтобы быть без знака.
`long`	8 байтов	Восьмибайтовое целочисленное значение. Значение подписывается если явно не утверждено, чтобы быть без знака.
`objectID`	Предназначайтесь для VM-specific, до 8 байтов (см. ниже),	Однозначно определяет объект в целевом VM. Определенный объект будет идентифицирован точно одним objectID в командах JDWP и ответах всюду по его времени жизни (или пока objectID будет явно расположен). ObjectID не снова используется, чтобы идентифицировать различный объект, если он не был явно расположен, независимо от того, был ли объект, на который ссылаются, собран "мусор". objectID 0 представляет нулевой объект. Отметьте, что существование объектного ID не предотвращает сборку "мусора" объекта. Любая попытка получить доступ к собранному "мусор" объекту с его объектным ID приведет к коду ошибки INVALID_OBJECT. Сборка "мусора" может быть отключена с командой DisableCollection, но не обычно необходимо сделать так.
`tagged-objectID`	размер objectID плюс один байт	Первый байт является байтом подписи, который используется, чтобы идентифицировать тип объекта. См. JDWP.Tag для возможных значений этого байта (отметьте, что только объектные теги, не примитивные теги, могут использоваться). Это сразу сопровождается objectID непосредственно.
`threadID`	то же самое как objectID	Однозначно определяет объект в целевом VM, который, как известно, является потоком
`threadGroupID`	то же самое как objectID	Однозначно определяет объект в целевом VM, который, как известно, является группой потока
`stringID`	то же самое как objectID	Однозначно определяет объект в целевом VM, который, как известно, является строковым объектом. Отметьте: это очень отличается от строки, которая является значением.
`classLoaderID`	то же самое как objectID	Однозначно определяет объект в целевом VM, который, как известно, является объектом загрузчика класса
`classObjectID`	то же самое как objectID	Однозначно определяет объект в целевом VM, который, как известно, является объектом класса.
`arrayID`	то же самое как objectID	Однозначно определяет объект в целевом VM, который, как известно, является массивом.
`referenceTypeID`	то же самое как objectID	Однозначно определяет ссылочный тип в целевом VM. Нельзя предположить это для определенного класса, `classObjectID` и `referenceTypeID` то же самое. Определенный ссылочный тип будет идентифицирован точно одним ID в командах JDWP и ответах всюду по его времени жизни, referenceTypeID не снова используется, чтобы идентифицировать различный ссылочный тип, независимо от того, был ли класс, на который ссылаются, разгружен.
`classID`	то же самое как referenceTypeID	Однозначно определяет ссылочный тип в целевом VM, который, как известно, является типом класса.
`interfaceID`	то же самое как referenceTypeID	Однозначно определяет ссылочный тип в целевом VM, который, как известно, является интерфейсным типом.
`arrayTypeID`	то же самое как referenceTypeID	Однозначно определяет ссылочный тип в целевом VM, который, как известно, является типом массива.
`methodID`	Предназначайтесь для VM-specific, до 8 байтов (см. ниже),	Однозначно определяет метод в некотором классе в целевом VM. methodID должен однозначно определить метод в пределах своего класса/интерфейса или любого из его подклассов/подинтерфейсов/конструкторов. methodID не обязательно уникален самостоятельно; это всегда соединяется с referenceTypeID, чтобы однозначно определить один метод. referenceTypeID может идентифицировать или тип объявления метода или подтип.
`fieldID`	Предназначайтесь для VM-specific, до 8 байтов (см. ниже),	Однозначно определяет поле в некотором классе в целевом VM. fieldID должен однозначно определить поле в пределах своего класса/интерфейса или любого из его подклассов/подинтерфейсов/конструкторов. fieldID не обязательно уникален самостоятельно; это всегда соединяется с referenceTypeID, чтобы однозначно определить одно поле. referenceTypeID может идентифицировать или тип объявления поля или подтип.
`frameID`	Предназначайтесь для VM-specific, до 8 байтов (см. ниже),	Однозначно определяет фрейм в целевом VM. frameID должен однозначно определить фрейм в пределах всего VM (не только в пределах данного потока). frameID должны только быть допустимыми в течение времени, его поток приостанавливается.
`location`	Предназначайтесь VM определенный	Исполнимое расположение. Расположение идентифицируется однобайтовым тегом типа, сопровождаемым a `classID` сопровождаемый a `methodID` сопровождаемый восьмибайтовым индексом без знака, который идентифицирует расположение в пределах метода. Индексные значения ограничиваются следующим образом: Индекс расположения запуска для метода является меньше чем все другие расположения в методе. Индекс расположения конца для метода больше чем все другие расположения в методе. Если таблица номера строки существует для метода, расположения, которые принадлежат определенной строке, должны упасть между индексом расположения строки и индексом расположения следующей строки в таблице. Индексные значения в пределах метода монотонно увеличиваются с первой исполнимой точки в методе к последнему. Для многих реализаций у каждой инструкции байт-кода в методе есть свой собственный индекс, но это не требуется. Тег типа необходим, чтобы идентифицировать, идентифицирует ли classID расположения класс или интерфейс. Почти все расположения в пределах классов, но возможно иметь исполняемый код в статическом инициализаторе интерфейса.
`string`	Переменная	UTF-8 закодированная строка, не нуль завершался, предшествовавший четырехбайтовой целочисленной длиной.
`value`	Переменная	Значение, полученное от целевого VM. Первый байт является байтом подписи, который используется, чтобы идентифицировать тип. См. JDWP.Tag для возможных значений этого байта. Это сразу сопровождается значением непосредственно. Это значение может быть objectID (см., Получают Размеры ID), или примитивное значение (1 - 8 байтов). Больше деталей о каждом типе значения может быть найдено в следующей таблице.
`untagged-value`	Переменная	A `value` как описано выше без байта подписи. Эта форма используется, когда информация о подписи может быть определена от контекста.
`arrayregion`	Переменная	Компактное представление значений используется с некоторыми операциями над массивом. Первый байт является байтом подписи, который используется, чтобы идентифицировать тип. См. JDWP.Tag для возможных значений этого байта. Затем четырехбайтовое целое число, указывающее на число значений в последовательности. Это сопровождается значениями непосредственно: Примитивные значения кодируются как последовательность `untagged-values`; Объектные значения кодируются как последовательность `values`.

Объектные идентификаторы, идентификаторы ссылочного типа, полевые идентификаторы, идентификаторы метода, и идентификаторы фрейма могут быть измерены по-другому в различных целевых реализациях VM. Как правило, их размеры соответствуют размеру собственных идентификаторов, используемых для этих элементов в вызовах JVMDI и JNI. Максимальный размер любого из этих типов составляет 8 байтов. "idSizes" команда в наборе команд VirtualMachine используется отладчиком, чтобы определить размер каждого из этих типов.

Если отлаживаемая программа получает Пакет Команды с нереализованным или нераспознанным набором команд или командой тогда, это возвращает Пакет Ответа с полевым набором кода ошибки к NOT_IMPLEMENTED (см. Ошибочные Константы).

Детали протокола

Свяжитесь с Нами

Протокол Провода Отладки JavaTM