Интерфейс описания

Все суперинтерфейсы:: 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.

Имя	Тип	Используется в	Значение
defaultValue	Объект	MBeanAttributeInfo MBeanParameterInfo	Значение по умолчанию для атрибута или параметра. См. `javax.management.openmbean`.
deprecated	Строка	Любой	Указание на то, что этот элемент модели информации больше не рекомендуется к использованию. Набор MBean, определённых приложением, в совокупности называется моделью информации. Стандартным является использование в этом поле строки, представляющей собой версию модели, в которой элемент был впервые устарел, за которой следует пробел и пояснение к устареванию, например `"1.3 Replaced by the Capacity attribute"`.
descriptionResource BundleBaseName	Строка	Любой	Базовое имя `ResourceBundle`, в котором можно найти ключ, указанный в поле `descriptionResourceKey`, например `"com.example.myapp.MBeanResources"`. Значение этого поля определяется этим спецификацией, но поле не устанавливается и не используется самой JMX API.
descriptionResourceKey	Строка	Любой	Ключ ресурса для описания этого элемента. В сочетании с `descriptionResourceBundleBaseName`, это позволяет найти локализованную версию описания. Значение этого поля определяется этим спецификацией, но поле не устанавливается и не используется самой JMX API.
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	Тип метрики, одна из строк "counter" или "gauge". Метрика — это измерение, экспортируемое объектом 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`. Оно также устанавливается для атрибутов, операций и параметров MXBeans. Это поле может быть установлено для `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 имеют предопределённое поведение для этих полей.

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

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

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

Переопределяет:: equals в классе Object
Параметры:: obj - объект для сравнения.
Возвращает:: true если объекты одинаковы; false в противном случае.
С момента:: 1.6
См. также:: Object.hashCode(), HashMap

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
См. также:: Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

© 1993, 2020, 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/11/docs/api/java.management/javax/management/Descriptor.html