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

Все суперинтерфейсы:: 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
Имя	Тип	Используется в	Значение
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	Строка[]	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 или созданных с использованием класса `StandardMBean`, это поле будет присутствовать в описателе MBeanInfo.
legalValues	Набор<?>	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 или созданных с использованием класса `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	Строка[]	MBeanAttributeInfo	Имена классов исключений, которые могут быть выброшены при установке атрибута. Значение этого поля определяется этим спецификацией, но само API JMX поле не устанавливает и не использует. Исключения, выброшенные при получении атрибута, задаются полем `exceptions`.
severity	Строка Целое число	MBeanNotificationInfo	Уровень серьезности этого уведомления. Может быть 0, означающее неизвестный уровень серьезности, или значение от 1 до 6, представляющее уменьшение уровней серьезности. Может быть представлено как строка с десятичной точкой или `Integer`.
since	Строка	Любой	Версия модели информации, в которой этот элемент был введён. Набор MBean, определенный приложением, называется моделью информации. Приложение также может определять версии этой модели и использовать поле `"since"` для записи версии, в которой элемент впервые появился.
units	Строка	MBeanAttributeInfo MBeanParameterInfo MBeanOperationInfo	Единицы измерения атрибута, параметра или возвращаемого значения операции, например `"bytes"` или `"seconds"`.

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

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

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» в документе спецификации 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: редко видимо.

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, то значение поля в возвращаемом массиве будет пустым. Если описатель пустой, вы получите пустой массив.

См. также:

setFields(java.lang.String[], java.lang.Object[])

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, если описатель неизменяем и вызов изменил бы его содержимое.

См. также:

getFields()

clone

Object clone() throws RuntimeOperationsException

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

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

isValid

boolean isValid() throws RuntimeOperationsException

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

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

equals

boolean equals(Object obj)

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

Если одно значение 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, 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/java.management/javax/management/Descriptor.html