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

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

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

public interface Descriptor extends Serializable, Cloneable

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

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

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

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

END_OF_DOCUMENT_MARKER

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

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

ModelMBean Fields
Имя	Тип	Используется в	Значение
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	Имя операционного дескриптора для метода get.
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 Descriptor Fields» в документе спецификации JMX.
presentationString	String	Любой	Строка в формате XML для отображения данных.
protocolMap	Descriptor	ModelMBeanAttributeInfo	См. раздел «Поддержка протоколов» в документе спецификации JMX. Сопоставления должны быть подходящими для атрибута, и записи могут обновляться или дополняться во время выполнения.
role	String	ModelMBeanConstructorInfo ModelMBeanOperationInfo	Один из «constructor», «operation», «getter» или «setter».
setMethod	String	ModelMBeanAttributeInfo	Имя операционного дескриптора для метода set.
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()

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

Возвращает:

Массив строк полей в формате имяПоля=значениеПоля
Если значение поля не является строкой, то для него вызывается метод 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)

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

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

Overrides:

equals в классе Object

Параметры:

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

Возвращает:

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

См. также:

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

Возвращает:

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

См. также:

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