Описание интерфейса

Все суперинтерфейсы:: Cloneable, Serializable

Все известные реализующие классы:: DescriptorSupport, ImmutableDescriptor

public interface Descriptor extends Serializable, Cloneable

Дополнительные метаданные для элемента JMX. Descriptor ассоциируется с MBeanInfo, MBeanAttributeInfo и т. д. Он состоит из набора полей. Поле — это имя и связанное с ним значение.

Имена полей нечувствительны к регистру. Имена descriptorType, descriptortype и DESCRIPTORTYPE эквивалентны. Однако регистр, использованный при первоначальном установлении поля, сохраняется в результатах методов getFields() и getFieldNames().

Не все имена и значения полей предопределены. Новые поля могут быть определены и добавлены любой программой.

Описание может быть изменяемым или неизменяемым. Неизменяемое описание, после создания, никогда не меняется. Методы Descriptor, которые могут изменить содержимое описания, вызовут исключение для неизменяемого описания. Неизменяемые описания обычно являются экземплярами ImmutableDescriptor или его подкласса. Изменяемые описания обычно являются экземплярами DescriptorSupport или его подкласса.

Некоторые поля используются реализацией JMX. Это означает, что наличие поля может изменить поведение API JMX или что поле может быть установлено в описаниях, возвращаемых API JMX. Эти поля выделены курсивом в таблице ниже, и для каждого из них существует соответствующая константа в классе JMX. Например, поле defaultValue представлено константой JMX.DEFAULT_VALUE_FIELD.

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

Имена полей, определенные спецификацией JMX в этой и последующих версиях, никогда не будут содержать точку (.). Пользователи могут безопасно создавать свои собственные поля, включая точку в имени, и быть уверены, что эти имена не будут конфликтовать с будущими версиями API JMX. Рекомендуется использовать соглашения о именовании пакетов Java, чтобы избежать конфликтов между именами полей из разных источников. Например, поле, созданное example.com, может иметь имя com.example.interestLevel.

Обратите внимание, что значения полей defaultValue, legalValues, maxValue и minValue должны быть согласованы с типом, возвращаемым методом getType() для связанного MBeanAttributeInfo или MBeanParameterInfo. Для MXBeans это означает, что они должны быть такого же типа Java, как и opendata(J) в правилах сопоставления типов MXBean.

Descriptor Fields
Name	Type	Used in	Meaning
defaultValue	Object	MBeanAttributeInfo MBeanParameterInfo	Значение по умолчанию для атрибута или параметра. См. `javax.management.openmbean`.
deprecated	String	Any	Указывает, что этот элемент модели информации больше не рекомендуется к использованию. Набор MBeans, определенных приложением, называется моделью информации. Соглашение заключается в том, что значение этого поля содержит строку, представляющую версию модели, в которой элемент был впервые устаревшим, за которой следует пробел и объяснение устаревания, например `"1.3 Replaced by the Capacity attribute"`.
descriptionResource BundleBaseName	String	Any	Базовое имя для `ResourceBundle`, в котором можно найти ключ, указанный в поле `descriptionResourceKey`, например `"com.example.myapp.MBeanResources"`. Значение этого поля определено этим спецификацией, но само API JMX не устанавливает или не использует это поле.
descriptionResourceKey	String	Any	Ключ ресурса для описания этого элемента. В сочетании с полем `descriptionResourceBundleBaseName`, это позволяет найти локализованную версию описания. Значение этого поля определено этой спецификацией, но само API JMX не устанавливает или не использует это поле.
enabled	String	MBeanAttributeInfo MBeanNotificationInfo MBeanOperationInfo	Строка `"true"` или `"false"`, в зависимости от того, включен ли этот элемент. Если атрибут или операция не включены, они существуют, но в настоящее время недоступны. Пользовательский интерфейс может отображать их как серые элементы. Например, атрибут может иметь смысл только после вызова метода `start()` MBean, а в ином случае он отключен. Аналогично, уведомление может быть отключено, если в настоящее время его нельзя выдать, но это возможно в других обстоятельствах.
exceptions	String[]	MBeanAttributeInfo, MBeanConstructorInfo, MBeanOperationInfo	Имена классов исключений, которые могут быть выброшены при вызове конструктора или операции, или при получении атрибута. Значение этого поля определено этим спецификацией, но само API JMX не устанавливает или не использует это поле. Исключения, выбрасываемые при установке атрибута, задаются полем `setExceptions`.
immutableInfo	String	MBeanInfo	Строка `"true"` или `"false"`, в зависимости от того, является ли MBeanInfo этого MBean неизменяемым. Когда это поле истинно, MBeanInfo для данного MBean гарантированно не изменится в течение всего срока службы MBean. Таким образом, клиент может прочитать его один раз и кэшировать прочитанное значение. Когда это поле ложно или отсутствует, такой гарантии нет, хотя это не означает, что MBeanInfo обязательно изменится. См. также уведомление `"jmx.mbean.info.changed"`.
infoTimeout	String Long	MBeanInfo	Время в миллисекундах, в течение которого можно разумно ожидать, что MBeanInfo не изменится. Значение может быть `Long` или десятичной строкой. Это предоставляет подсказку от DynamicMBean или любого MBean, который не определяет `immutableInfo` как `true`, что MBeanInfo, скорее всего, не изменится в течение этого периода и, следовательно, может быть кэширован. Когда это поле отсутствует или имеет значение ноль, не рекомендуется кэшировать MBeanInfo, если не задан `immutableInfo` в значение `true` или в нем есть `"jmx.mbean.info.changed"` в массиве `MBeanNotificationInfo`.
interfaceClassName	String	MBeanInfo	Имя Java-интерфейса для Standard MBean или MXBean, возвращаемое методом `Class.getName()`. У Standard MBean или MXBean, зарегистрированных непосредственно в MBean Server или созданных с помощью класса `StandardMBean`, в описателе MBeanInfo будет это поле.
legalValues	Set<?>	MBeanAttributeInfo MBeanParameterInfo	Допустимые значения для атрибута или параметра. См. `javax.management.openmbean`.
locale	String	Any	Локаль описания в этом `MBeanInfo`, `MBeanAttributeInfo` и т.д., как возвращается методом `Locale.toString()`.
maxValue	Object	MBeanAttributeInfo MBeanParameterInfo	Максимальное допустимое значение для атрибута или параметра. См. `javax.management.openmbean`.
metricType	String	MBeanAttributeInfo MBeanOperationInfo	Тип метрики, одна из строк "счетчик" или "измеритель". Метрика — это измерение, экспортируемое MBean, обычно атрибут, но иногда результат операции. Метрика, являющаяся счетчиком, имеет значение, которое никогда не уменьшается, за исключением сброса до начального значения. Метрики-счетчики почти всегда являются целыми неотрицательными числами. Примером может служить количество полученных запросов. Метрика, являющаяся измерителем, имеет числовое значение, которое может увеличиваться или уменьшаться. Примерами могут служить количество открытых соединений, коэффициент попадания в кэш или показания температуры.
minValue	Object	MBeanAttributeInfo MBeanParameterInfo	Минимальное допустимое значение для атрибута или параметра. См. `javax.management.openmbean`.
mxbean	String	MBeanInfo	Строка `"true"` или `"false"`, в зависимости от того, является ли этот MBean `MXBean`. У Standard MBean или MXBean, зарегистрированных непосредственно в MBean Server или созданных с помощью класса `StandardMBean`, в описателе MBeanInfo будет это поле.
openType	`OpenType`	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	Открытый тип этого элемента. В случае `MBeanAttributeInfo` и `MBeanParameterInfo` это открытый тип атрибута или параметра. В случае `MBeanOperationInfo` это открытый тип возвращаемого значения. Это поле устанавливается в описателе для всех экземпляров `OpenMBeanAttributeInfoSupport`, `OpenMBeanOperationInfoSupport` и `OpenMBeanParameterInfoSupport`. Оно также устанавливается для атрибутов, операций и параметров MXBean. Это поле может быть установлено для `MBeanNotificationInfo`, в этом случае оно указывает открытый тип, который будет иметь `user data`.
originalType	String	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	Исходный тип Java этого элемента, как он отображался в методе интерфейса `MXBean`, который создал этот `MBeanAttributeInfo` (и т.д.). Например, метод `public` `MemoryUsage` `getHeapMemoryUsage();` в интерфейсе MXBean определяет атрибут, называемый `HeapMemoryUsage`, типа `CompositeData`. Поле `originalType` в описателе этого атрибута будет иметь значение `"java.lang.management.MemoryUsage"`. Формат этой строки описан в разделе Имена типов спецификации MXBean.
setExceptions	String[]	MBeanAttributeInfo	Имена классов исключений, которые могут быть выброшены при установке атрибута. Значение этого поля определено этим спецификацией, но само API JMX не устанавливает или не использует это поле. Исключения, выбрасываемые при получении атрибута, задаются полем `exceptions`.
severity	String Integer	MBeanNotificationInfo	Уровень серьезности этого уведомления. Он может быть равен 0, что означает неизвестный уровень серьезности, или принимать значения от 1 до 6, представляющие убывающие уровни серьезности. Он может быть представлен как десятичная строка или `Integer`.
since	String	Any	Версия модели информации, в которой этот элемент был представлен. Набор MBeans, определенных приложением, называется моделью информации. Приложение также может определить версии этой модели и использовать поле `"since"` для записи версии, в которой элемент появился впервые.
units	String	MBeanAttributeInfo MBeanParameterInfo MBeanOperationInfo	Единицы измерения атрибута, параметра или значения возврата операции, например `"bytes"` или `"seconds"`.

END_OF_DOCUMENT_MARKER

Дополнительные поля определяются MBeans модели. Смотрите информацию для ModelMBeanInfo, ModelMBeanAttributeInfo, ModelMBeanConstructorInfo, ModelMBeanNotificationInfo и ModelMBeanOperationInfo, а также главу «Model MBeans» в спецификации JMX. В следующей таблице эти поля обобщены. Обратите внимание, что когда Тип в этой таблице — Число, можно также использовать строку, представляющую десятичное представление целого числа.

Ничто не мешает использовать эти поля в MBeans, которые не являются MBeans модели. Например, поля displayName, severity и visibility представляют интерес вне MBeans модели. Но только MBeans модели имеют предварительно определенное поведение для этих полей.

Поля ModelMBean
Имя	Тип	Используется в	Значение
class	String	ModelMBeanOperationInfo	Класс, в котором определен метод (полное имя).
currencyTimeLimit	Число	ModelMBeanInfo ModelMBeanAttributeInfo ModelMBeanOperationInfo	Сколько времени кешированное значение является действительным: <0 никогда, =0 всегда, >0 секунд.
default	Объект	ModelMBeanAttributeInfo	Значение по умолчанию для атрибута.
descriptorType	String	Любой	Тип дескриптора, «mbean», «attribute», «constructor», «operation» или «notification».
displayName	String	Любой	Человекопонятное имя этого элемента.
export	String	ModelMBeanInfo	Имя, которое будет использоваться для экспорта/раскрытия этого MBean, чтобы его можно было найти другими агентами JMX.
getMethod	String	ModelMBeanAttributeInfo	Имя дескриптора операции для метода get.
lastUpdatedTimeStamp	Число	ModelMBeanAttributeInfo ModelMBeanOperationInfo	Когда было установлено значение value.
log	String	ModelMBeanInfo ModelMBeanNotificationInfo	t или T: регистрировать все уведомления, f или F: не регистрировать уведомления.
logFile	String	ModelMBeanInfo ModelMBeanNotificationInfo	Полное имя файла для регистрации событий.
messageID	String	ModelMBeanNotificationInfo	Уникальный ключ для текста сообщения (для перевода, анализа).
messageText	String	ModelMBeanNotificationInfo	Текст уведомления.
name	String	Любой	Имя этого элемента.
persistFile	String	ModelMBeanInfo	Имя файла, в который должен быть сохранен MBean.
persistLocation	String	ModelMBeanInfo	Полное имя каталога, в который должен быть сохранен MBean (при необходимости).
persistPeriod	Число	ModelMBeanInfo ModelMBeanAttributeInfo	Частота цикла сохранения в секундах. Используется, когда persistPolicy равен «OnTimer» или «NoMoreOftenThan».
persistPolicy	String	ModelMBeanInfo ModelMBeanAttributeInfo	Одно из: OnUpdate\|OnTimer\|NoMoreOftenThan\|OnUnregister\|Always\|Never. См. раздел «Поля дескриптора MBean» в документе спецификации JMX.
presentationString	String	Любой	Строка в формате XML для представления данных.
protocolMap	Descriptor	ModelMBeanAttributeInfo	См. раздел «Поддержка карты протоколов» в документе спецификации JMX. Сопоставления должны быть соответствующими для атрибута, и записи могут быть обновлены или дополнены во время выполнения.
role	String	ModelMBeanConstructorInfo ModelMBeanOperationInfo	Одно из «constructor», «operation», «getter» или «setter».
setMethod	String	ModelMBeanAttributeInfo	Имя дескриптора операции для метода set.
severity	Число	ModelMBeanNotificationInfo	0-6, где 0: неизвестно; 1: необратимая ошибка; 2: критическая ошибка, сбой; 3: серьезная ошибка; 4: незначительная ошибка; 5: предупреждение; 6: нормальное, исправлено, информативное.
targetObject	Объект	ModelMBeanOperationInfo	Объект, на котором необходимо выполнить этот метод.
targetType	String	ModelMBeanOperationInfo	Тип ссылки на объект для targetObject. Может быть: ObjectReference \| Handle \| EJBHandle \| IOR \| RMIReference.
value	Объект	ModelMBeanAttributeInfo ModelMBeanOperationInfo	Текущее (кешированное) значение для атрибута или операции.
visibility	Число	Любой	1-4, где 1: всегда видимый, 4: редко видимый.

Since:: 1.5

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

Модификатор и тип	Метод	Описание
`Object`	`clone()`	Возвращает дескриптор, равный этому дескриптору.
`boolean`	`equals(Object obj)`	Сравнивает этот дескриптор с заданным объектом.
`String[]`	`getFieldNames()`	Возвращает все имена полей в дескрипторе.
`String[]`	`getFields()`	Возвращает все поля, содержащиеся в этом дескрипторе, в виде массива строк.
`Object`	`getFieldValue(String fieldName)`	Возвращает значение для определенного имени поля или null, если для этого имени нет значения.
`Object[]`	`getFieldValues(String... fieldNames)`	Возвращает все значения полей в дескрипторе в виде массива объектов.
`int`	`hashCode()`	Возвращает значение хэш-кода для этого дескриптора.
`boolean`	`isValid()`	Возвращает true, если все поля имеют допустимые значения, учитывая их имена.
`void`	`removeField(String fieldName)`	Удаляет поле из дескриптора.
`void`	`setField(String fieldName, Object fieldValue)`	Устанавливает значение для определенного имени поля.
`void`	`setFields(String[] fieldNames, Object[] fieldValues)`	Устанавливает все поля в массиве имен полей в новое значение с тем же индексом в массиве значений полей.

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

getFieldValue

Object getFieldValue(String fieldName) throws RuntimeOperationsException

Возвращает значение для определенного имени поля или null, если для этого имени нет значения.

Параметры:: fieldName - имя поля.
Возвращает:: соответствующее значение или null, если поле отсутствует.
Изначает исключения:: RuntimeOperationsException - если имя поля некорректно.

setField

void setField(String fieldName, Object fieldValue) throws RuntimeOperationsException

Устанавливает значение для определенного имени поля. Это изменит существующее поле или добавит новое.

Значение поля будет проверено перед установкой. Если оно недействительно, будет выброшено исключение. Значение «действительности» зависит от реализации дескриптора.

Параметры:: fieldName - Имя поля для установки. Не может быть null или пустым.; fieldValue - Значение поля для установки для имени поля. Может быть null, если это допустимое значение для поля.
Изначает исключения:: RuntimeOperationsException - если имя поля или значение поля некорректны (исключение обернуто в IllegalArgumentException); или если дескриптор неизменяем (исключение обернуто в UnsupportedOperationException).

getFields

String[] getFields()

Возвращает все поля, содержащиеся в этом дескрипторе, в виде массива строк.

Возвращает:

Массив строк полей в формате имяПоля=значениеПоля
Если значение поля не является строкой, то метод toString() будет вызван для него, и возвращаемое значение, заключенное в скобки, будет использовано в качестве значения поля в возвращаемом массиве. Если значение поля равно null, то значение поля в возвращаемом массиве будет пустым. Если дескриптор пуст, вы получите пустой массив.

См. также:

getFieldNames

String[] getFieldNames()

Возвращает все имена полей в дескрипторе.

Возвращает:: Массив строк имён полей. Если дескриптор пуст, вы получите пустой массив.

getFieldValues

Object[] getFieldValues(String... fieldNames)

Возвращает все значения полей в дескрипторе в виде массива объектов. Возвращаемые значения находятся в том же порядке, что и в параметре массива строк fieldNames.

Параметры:: fieldNames - Массив строк с именами полей, для которых должны быть возвращены значения. Если массив пуст, то будет возвращен пустой массив. Если массив null, то будут возвращены все значения, как если бы параметром был массив, возвращаемый getFieldNames(). Если имя поля в массиве не существует, в том числе в случае, когда оно равно null или пустой строке, то для соответствующего элемента возвращаемого массива возвращается null.
Возвращает:: Массив объектов значений полей. Если список fieldNames пуст, вы получите пустой массив.

removeField

void removeField(String fieldName)

Удаляет поле из дескриптора.

Параметры:: fieldName - Имя строки поля, которое нужно удалить. Если имя поля некорректно или поле не найдено, исключение не выбрасывается.
Изначает исключения:: RuntimeOperationsException - если поле с данным именем существует и дескриптор неизменяем. Обернутое исключение будет UnsupportedOperationException.

setFields

void setFields(String[] fieldNames, Object[] fieldValues) throws RuntimeOperationsException

Устанавливает все поля в массиве имён полей новым значениям с тем же индексом в массиве значений полей. Размеры массивов должны совпадать.

Значение поля будет проверено перед установкой. Если оно недействительно, будет выброшено исключение. Если массивы пустые, то никаких изменений не произойдёт.

Параметры:

fieldNames - Массив строк имён полей. Массив и элементы массива не могут быть null.

fieldValues - Массив объектов соответствующих значений полей. Массив не может быть null. Элементы массива могут быть null.

Изначает исключения:

RuntimeOperationsException - если изменение не удаётся по какой-либо причине. Обернутое исключение - IllegalArgumentException, если fieldNames или fieldValues равно null, или если массивы имеют разную длину, или если в одном из них есть недопустимое значение. Обернутое исключение - UnsupportedOperationException, если дескриптор неизменяем, и вызов изменит его содержимое.

См. также:

clone

Object clone() throws RuntimeOperationsException

Возвращает дескриптор, равный этому дескриптору. Изменения в возвращаемом дескрипторе не повлияют на этот дескриптор, и наоборот. Если этот дескриптор неизменяем, он может выполнить это условие, вернув себя.

Возвращает:: Дескриптор, равный этому дескриптору.
Изначает исключения:: RuntimeOperationsException - для недопустимого значения для имён полей или значений полей. Если создание дескриптора терпит неудачу по какой-либо причине, это исключение будет выброшено.

isValid

boolean isValid() throws RuntimeOperationsException

Возвращает true, если все поля имеют допустимые значения, учитывая их имена.

Возвращает:: true, если значения допустимы.
Изначает исключения:: RuntimeOperationsException - Если проверка на корректность терпит неудачу по какой-либо причине, это исключение будет выброшено. Метод возвращает false, если дескриптор некорректен, но выбрасывает это исключение, если попытка определить корректность терпит неудачу.

equals

boolean equals(Object obj)

Сравнивает этот дескриптор с заданным объектом. Объекты равны, если заданный объект также является Descriptor, и если два Descriptor имеют одинаковые имена полей (возможно, различающиеся регистром) и одинаковые связанные значения. Соответствующие значения для поля в двух Descriptor равны, если выполняются следующие условия:

Если одно значение равно null, то другое также должно быть null.
Если одно значение является массивом примитивных типов, то другое должно быть массивом примитивных типов того же типа с теми же элементами.
Если одно значение является массивом объектов, то другое также должно быть массивом, и Arrays.deepEquals(Object[],Object[]) должен вернуть true.
В противном случае Object.equals(Object) должен вернуть true.

Overrides:

equals в классе Object

Параметры:

obj - объект для сравнения.

Возвращает:

true, если объекты одинаковые; false в противном случае.

С момента:

1.6

См. также:

hashCode

int hashCode()

Возвращает значение хэш-кода для этого дескриптора. Хэш-код вычисляется как сумма хэш-кодов каждого поля в дескрипторе. Хэш-код поля с именем n и значением v равен n.toLowerCase().hashCode() ^ h. Здесь h — хэш-код v, вычисляемый следующим образом:

Если v равно null, то h равно 0.
Если v является массивом примитивных типов, то h вычисляется с использованием соответствующего перегрузки java.util.Arrays.hashCode.
Если v является массивом объектов, то h вычисляется с использованием Arrays.deepHashCode(Object[]).
В противном случае h равен v.hashCode().

Overrides:

hashCode в классе Object

Возвращает:

Значение хэш-кода для этого объекта.

С момента:

1.6

См. также:

© 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/java.management/javax/management/Descriptor.html