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

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, сопоставленного в правилах сопоставления типов MXBean и называемого opendata(J).

Имя	Тип	Используется в	Значение
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	Тип метрики, одна из строк "counter" или "gauge". Метрика — это измерение, экспортируемое 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".

Некоторые дополнительные поля определены модельными MBean. См. информацию по ModelMBeanInfo, ModelMBeanAttributeInfo, ModelMBeanConstructorInfo, ModelMBeanNotificationInfo и ModelMBeanOperationInfo, а также главу "Model MBeans" спецификации JMX.

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

Имя	Тип	Используется в	Значение
class	String	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 Descriptor Fields" в документе спецификации 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: редко видно.

Методы

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)

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

equals в классе Object

Параметры:

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

Возвращает:

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

С:

1.6

См. также:

Object.hashCode(), HashMap

hashCode

int hashCode()

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

hashCode в классе Object

Возвращает:

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

С:

1.6

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)