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

Все суперинтерфейсы:: 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. Для MXBean это означает, что они должны иметь сопоставленный тип Java, называемый opendata(J) в правилах сопоставления типов MXBean.

Поля дескриптора
Имя	Тип	Используется в	Значение
defaultValue	Object	MBeanAttributeInfo MBeanParameterInfo	Значение атрибута или параметра по умолчанию. См. `javax.management.openmbean`.
deprecated	String	Любой	Указание на то, что использовать этот элемент информационной модели больше не рекомендуется. Набор MBean, определенных приложением, в совокупности называется информационной моделью. Согласно соглашению, значение этого поля содержит строку с версией модели, в которой элемент был впервые объявлен устаревшим, за которой следует пробел и пояснение причины, например `"1.3 Replaced by the Capacity attribute"`.
descriptionResource BundleBaseName	String	Любой	Базовое имя `ResourceBundle`, в котором можно найти ключ, указанный в поле `descriptionResourceKey`, например `"com.example.myapp.MBeanResources"`. Значение этого поля определено данной спецификацией, однако само поле не устанавливается и не используется API JMX.
descriptionResourceKey	String	Любой	Ключ ресурса для описания этого элемента. В сочетании с `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 неизменяемым. Если значение этого поля равно true, гарантируется, что MBeanInfo данного MBean не изменится за время существования MBean. Поэтому клиент может прочитать его один раз и кэшировать полученное значение. Если значение этого поля равно false или оно отсутствует, такой гарантии нет, хотя это не означает, что MBeanInfo обязательно изменится. См. также уведомление `"jmx.mbean.info.changed"`.
infoTimeout	String Long	MBeanInfo	Время в миллисекундах, в течение которого MBeanInfo с достаточной вероятностью останется неизменным. Значение может быть `Long` или десятичной строкой. Это подсказка от DynamicMBean или любого MBean, который не определяет `immutableInfo` как `true`, о том, что MBeanInfo вряд ли изменится в течение этого периода и поэтому может кэшироваться. Если это поле отсутствует или имеет значение zero, кэшировать MBeanInfo не рекомендуется, если только для `immutableInfo` не задано значение `true` или в массиве `MBeanNotificationInfo` этого MBean нет уведомления `"jmx.mbean.info.changed"`.
interfaceClassName	String	MBeanInfo	Имя интерфейса Java для стандартного MBean или MXBean, возвращаемое методом `Class.getName()`. Стандартный MBean или MXBean, зарегистрированный непосредственно в MBean Server или созданный с помощью класса `StandardMBean`, будет содержать это поле в дескрипторе MBeanInfo.
legalValues	Set<?>	MBeanAttributeInfo MBeanParameterInfo	Допустимые значения атрибута или параметра. См. `javax.management.openmbean`.
locale	String	Любой	Локаль описания в этом `MBeanInfo`, `MBeanAttributeInfo` и т. д., возвращаемая методом `Locale.toString()`.
maxValue	Object	MBeanAttributeInfo MBeanParameterInfo	Максимальное допустимое значение атрибута или параметра. См. `javax.management.openmbean`.
metricType	String	MBeanAttributeInfo MBeanOperationInfo	Тип метрики: одна из строк "counter" или "gauge". Метрика — это измерение, экспортируемое MBean, обычно атрибут, но иногда результат операции. Метрика типа counter имеет значение, которое никогда не уменьшается, кроме как при сбросе к начальному значению. Метрики-счетчики почти всегда являются неотрицательными целыми числами. Например, это может быть число полученных запросов. Метрика типа gauge имеет числовое значение, которое может увеличиваться или уменьшаться. Например, это может быть число открытых соединений, частота попаданий в кэш или показание температуры.
minValue	Object	MBeanAttributeInfo MBeanParameterInfo	Минимальное допустимое значение атрибута или параметра. См. `javax.management.openmbean`.
mxbean	String	MBeanInfo	Строка `"true"` или `"false"` в зависимости от того, является ли этот MBean объектом `MXBean`. Стандартный 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	Любой	Версия информационной модели, в которой был добавлен этот элемент. Набор MBean, определенных приложением, в совокупности называется информационной моделью. Приложение также может определять версии этой модели и использовать поле `"since"` для записи версии, в которой элемент появился впервые.
units	String	MBeanAttributeInfo MBeanParameterInfo MBeanOperationInfo	Единицы измерения атрибута, параметра или возвращаемого значения операции, например `"bytes"` или `"seconds"`.

Некоторые дополнительные поля определены для Model MBean. См. сведения о ModelMBeanInfo, ModelMBeanAttributeInfo, ModelMBeanConstructorInfo, ModelMBeanNotificationInfo и ModelMBeanOperationInfo, а также главу "Model MBeans" спецификации JMX. В следующей таблице приведены эти поля. Обратите внимание: если в этой таблице типом указано Number, также можно использовать строку с десятичным представлением Long.

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

Поля ModelMBean
Имя	Тип	Используется в	Значение
class	String	ModelMBeanOperationInfo	Класс, в котором определен метод (полное имя).
currencyTimeLimit	Number	ModelMBeanInfo ModelMBeanAttributeInfo ModelMBeanOperationInfo	Срок действия кэшированного значения: <0 — никогда, =0 — всегда, >0 — секунды.
default	Object	ModelMBeanAttributeInfo	Значение атрибута по умолчанию.
descriptorType	String	Любой	Тип дескриптора: "mbean", "attribute", "constructor", "operation" или "notification".
displayName	String	Любой	Понятное пользователю имя этого элемента.
export	String	ModelMBeanInfo	Имя, используемое для экспорта или публикации этого MBean, чтобы другие агенты JMX могли его обнаружить.
getMethod	String	ModelMBeanAttributeInfo	Имя дескриптора операции для метода получения.
lastUpdatedTimeStamp	Number	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	Number	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	Имя дескриптора операции для метода задания.
severity	Number	ModelMBeanNotificationInfo	От 0 до 6, где 0: неизвестная; 1: невосстановимая; 2: критическая, сбой; 3: серьезная; 4: незначительная, пограничная, ошибка; 5: предупреждение; 6: нормальная, устраненная, информационная
targetObject	Object	ModelMBeanOperationInfo	Объект, для которого следует выполнить этот метод.
targetType	String	ModelMBeanOperationInfo	Тип ссылки на объект для targetObject. Возможные значения: ObjectReference \| Handle \| EJBHandle \| IOR \| RMIReference.
value	Object	ModelMBeanAttributeInfo ModelMBeanOperationInfo	Текущее (кэшированное) значение атрибута или операции.
visibility	Number	Любой	От 1 до 4, где 1: всегда видимый; 4: редко видимый.

Начиная с:: 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()

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

Возвращает:

Массив строк с полями в формате fieldName=fieldValue
Если значение поля не является String, для него будет вызван метод 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.

Переопределяет:

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().

Переопределяет:

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://docs.oracle.com/en/java/javase/25/docs/api/java.management/javax/management/Descriptor.html