Интерфейс IIOMetadataFormat

public interface IIOMetadataFormat

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

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

Структуры, которые может описывать этот класс, являются подмножеством тех, которые можно выразить с помощью определений типов документов XML (DTD), с добавлением некоторых основных сведений о типах данных атрибутов и возможностью хранить Object ссылку внутри узла. В будущем для представления этих структур могут использоваться XML-схемы и многие другие.

Различия между структурами, описанными IIOMetadataFormat и DTD, следующие:

• Элементы не могут содержать текст или смешивать текст со встроенными тегами.
• Дочерние элементы элемента должны соответствовать одному из нескольких простых шаблонов, описанных в документации для CHILD_* констант;
• Внутреннее представление элемента может содержать ссылку на Object. Нет возможности представить такие объекты в текстовом формате.

Поля

CHILD_POLICY_EMPTY

static final int CHILD_POLICY_EMPTY

Константа, возвращаемая getChildPolicy, для обозначения того, что элемент не может иметь дочерних элементов. Другими словами, он должен быть листом.

См. также:

Значения константных полей

CHILD_POLICY_ALL

static final int CHILD_POLICY_ALL

Константа, возвращаемая getChildPolicy, для обозначения того, что элемент должен иметь по одному экземпляру каждого из своих допустимых дочерних элементов в определённом порядке. В терминах DTD содержимое элемента определяется последовательностью a,b,c,d,....

См. также:

Значения константных полей

CHILD_POLICY_SOME

static final int CHILD_POLICY_SOME

Константа, возвращаемая getChildPolicy, для обозначения того, что элемент должен иметь ноль или один экземпляр каждого из своих допустимых дочерних элементов в определённом порядке. В терминах DTD содержимое элемента определяется последовательностью a?,b?,c?,d?,....

См. также:

Значения константных полей

CHILD_POLICY_CHOICE

static final int CHILD_POLICY_CHOICE

Константа, возвращаемая getChildPolicy, для обозначения того, что элемент должен иметь ноль или один дочерний элемент, выбранный из числа его допустимых дочерних элементов. В терминах DTD содержимое элемента определяется выбором a|b|c|d|....

См. также:

Значения константных полей

CHILD_POLICY_SEQUENCE

static final int CHILD_POLICY_SEQUENCE

Константа, возвращаемая getChildPolicy, для обозначения того, что элемент должен иметь последовательность экземпляров любого из его допустимых дочерних элементов. В терминах DTD содержимое элемента определяется последовательностью (a|b|c|d|...)*.

См. также:

Значения константных полей

CHILD_POLICY_REPEAT

static final int CHILD_POLICY_REPEAT

Константа, возвращаемая getChildPolicy, для обозначения того, что элемент должен иметь ноль или более экземпляров своего единственного допустимого дочернего элемента. В терминах DTD содержимое элемента определяется выражением со звёздочкой a*.

См. также:

Значения константных полей

CHILD_POLICY_MAX

static final int CHILD_POLICY_MAX

Наибольшая допустимая CHILD_POLICY_* константа, используемая для проверок диапазона.

См. также:

Значения константных полей

VALUE_NONE

static final int VALUE_NONE

Константа, возвращаемая getObjectValueType, для обозначения отсутствия пользовательского объекта.

См. также:

Значения константных полей

VALUE_ARBITRARY

static final int VALUE_ARBITRARY

Константа, возвращаемая getAttributeValueType и getObjectValueType, для обозначения того, что атрибут или пользовательский объект могут быть установлены в единственное произвольное значение.

См. также:

Значения константных полей

VALUE_RANGE

static final int VALUE_RANGE

Константа, возвращаемая getAttributeValueType и getObjectValueType, для обозначения того, что атрибут или пользовательский объект могут быть установлены в диапазон значений. Как минимальное, так и максимальное значения диапазона исключаются. Рекомендуется, чтобы диапазоны целых чисел были включительными на обоих концах, а исключительные диапазоны использовались только для данных с плавающей точкой.

См. также:

VALUE_RANGE_MIN_MAX_INCLUSIVE, Значения константных полей

VALUE_RANGE_MIN_INCLUSIVE_MASK

static final int VALUE_RANGE_MIN_INCLUSIVE_MASK

См. также:

Значения константных полей

VALUE_RANGE_MAX_INCLUSIVE_MASK

static final int VALUE_RANGE_MAX_INCLUSIVE_MASK

См. также:

Значения константных полей

VALUE_RANGE_MIN_INCLUSIVE

static final int VALUE_RANGE_MIN_INCLUSIVE

Константа, возвращаемая getAttributeValueType и getObjectValueType, для обозначения того, что атрибут или пользовательский объект могут быть установлены в диапазон значений. Минимальное (но не максимальное) значение диапазона включительно.

См. также:

Значения константных полей

VALUE_RANGE_MAX_INCLUSIVE

static final int VALUE_RANGE_MAX_INCLUSIVE

Константа, возвращаемая getAttributeValueType и getObjectValueType, для обозначения того, что атрибут или пользовательский объект могут быть установлены в диапазон значений. Максимальное (но не минимальное) значение диапазона включительно.

См. также:

Значения константных полей

VALUE_RANGE_MIN_MAX_INCLUSIVE

static final int VALUE_RANGE_MIN_MAX_INCLUSIVE

Константа, возвращаемая getAttributeValueType и getObjectValueType, для обозначения того, что атрибут или пользовательский объект могут быть установлены в диапазон значений. Как минимальное, так и максимальное значения диапазона включительно. Рекомендуется, чтобы диапазоны целых чисел были включительными на обоих концах, а исключительные диапазоны использовались только для данных с плавающей точкой.

См. также:

Значения константных полей

VALUE_ENUMERATION

static final int VALUE_ENUMERATION

См. также:

Значения константных полей

VALUE_LIST

static final int VALUE_LIST

Константа, возвращаемая getAttributeValueType и getObjectValueType, для обозначения того, что атрибут или пользовательский объект могут быть установлены в список или массив значений. В случае атрибутов список будет состоять из значений, разделённых пробелами, в String; для объектов будет использован массив.

См. также:

Значения константных полей

DATATYPE_STRING

static final int DATATYPE_STRING

Константа, возвращаемая getAttributeDataType, указывающая, что значение атрибута — строка Юникода общего вида.

См. также:

Значения константных полей

DATATYPE_BOOLEAN

static final int DATATYPE_BOOLEAN

Константа, возвращаемая getAttributeDataType, указывающая, что значение атрибута — одно из логических значений «true» или «false». Значения атрибутов типа DATATYPE_BOOLEAN следует пометить как перечисления, а разрешённые значения должны быть строковыми литералами «TRUE» или «FALSE», хотя плагин также может распознавать эквиваленты в нижнем или смешанном регистре.

См. также:

Значения константных полей

DATATYPE_INTEGER

static final int DATATYPE_INTEGER

Константа, возвращаемая getAttributeDataType, указывающая, что значение атрибута — строковое представление целого числа.

См. также:

Значения константных полей

DATATYPE_FLOAT

static final int DATATYPE_FLOAT

Константа, возвращаемая getAttributeDataType, указывающая, что значение атрибута — строковое представление десятичного числа с плавающей точкой.

См. также:

Значения константных полей

DATATYPE_DOUBLE

static final int DATATYPE_DOUBLE

Константа, возвращаемая getAttributeDataType, указывающая, что значение атрибута — строковое представление числа двойной точности с плавающей точкой.

См. также:

Значения константных полей

Методы

getRootName

String getRootName()

Возвращает имя корневого элемента формата.

Возвращает:

a String.

canNodeAppear

boolean canNodeAppear(String elementName,
                      ImageTypeSpecifier imageType)

Возвращает true, если элемент (и поддерево ниже него) разрешено отображать в документе метаданных для изображения заданного типа, определённого ImageTypeSpecifier. Например, формат документа метаданных может содержать элемент, описывающий основные цвета изображения, который не будет разрешён при записи изображения в оттенках серого.

Параметры:

elementName - имя элемента, запрос к которому производится.

imageType - ImageTypeSpecifier, указывающий тип изображения, которое будет связано с метаданными.

Возвращает:

true, если узел имеет значение для изображений данного типа.

getElementMinChildren

int getElementMinChildren(String elementName)

Возвращает минимальное количество дочерних элементов указанного элемента с политикой дочерних элементов CHILD_POLICY_REPEAT. Например, элементу, представляющему информацию о базовых цветах, может потребоваться как минимум 3 дочерних элемента, по одному для каждого базового цвета.

Параметры:

elementName - имя элемента, запрос к которому производится.

Возвращает:

int.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если у указанного элемента нет политики дочерних элементов CHILD_POLICY_REPEAT.

getElementMaxChildren

int getElementMaxChildren(String elementName)

Возвращает максимальное количество дочерних элементов указанного элемента с политикой дочерних элементов CHILD_POLICY_REPEAT. Например, элемент, представляющий запись в 8-битной палитре цветов, может повторяться до 256 раз. Значение Integer.MAX_VALUE может использоваться для указания отсутствия верхнего предела.

Параметры:

elementName - имя элемента, запрос к которому производится.

Возвращает:

int.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если у указанного элемента нет политики дочерних элементов CHILD_POLICY_REPEAT.

getElementDescription

String getElementDescription(String elementName,
                             Locale locale)

Параметры:

elementName - имя элемента.

locale - Locale для которого будет осуществлена локализация.

Возвращает:

описание элемента.

Исключения:

IllegalArgumentException - если elementName равно null, или не является допустимым именем элемента для данного формата.

getChildPolicy

int getChildPolicy(String elementName)

Возвращает одно из констант, начинающихся с CHILD_POLICY_, указывающих допустимый шаблон дочерних элементов для указанного элемента.

Параметры:

elementName - имя элемента, запрос к которому производится.

Возвращает:

одну из CHILD_POLICY_* констант.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

getChildNames

String[] getChildNames(String elementName)

Возвращает массив Strings, указывающих имена элементов, которые могут быть дочерними элементами указанного элемента, в порядке их появления. Если у элемента нет дочерних элементов, возвращается null.

Параметры:

elementName - имя элемента, запрос к которому производится.

Возвращает:

массив Strings, или null.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

getAttributeNames

String[] getAttributeNames(String elementName)

Возвращает массив Strings, перечисляющих имена атрибутов, которые могут быть связаны с указанным элементом.

Параметры:

elementName - имя элемента, запрос к которому производится.

Возвращает:

массив Strings.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

getAttributeValueType

int getAttributeValueType(String elementName,
                          String attrName)

Возвращает одно из констант, начинающихся с VALUE_, указывающих, являются ли значения данного атрибута внутри указанного элемента произвольными, ограничены ли они заданным диапазоном, ограничены ли они набором перечисленных значений или представляют собой список произвольных значений, разделённых пробелами.

Параметры:

elementName - имя элемента, запрос к которому производится.

attrName - имя атрибута, запрос к которому производится.

Возвращает:

одну из VALUE_* констант.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если attrName равно null или не является допустимым именем атрибута для данного элемента.

getAttributeDataType

int getAttributeDataType(String elementName,
                         String attrName)

Возвращает одну из констант, начинающихся с DATATYPE_, указывающую формат и интерпретацию значения данного атрибута внутри указанного элемента. Если getAttributeValueType возвращает VALUE_LIST, то допустимое значение — это список значений возвращаемого типа, разделённых пробелами.

Параметры:

elementName - имя элемента, запрос к которому производится.

attrName - имя атрибута, запрос к которому производится.

Возвращает:

одну из DATATYPE_* констант.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если attrName равно null или не является допустимым именем атрибута для данного элемента.

isAttributeRequired

boolean isAttributeRequired(String elementName,
                            String attrName)

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

Параметры:

elementName - имя элемента, запрос к которому производится.

attrName - имя атрибута, запрос к которому производится.

Возвращает:

true, если атрибут должен быть присутствовать.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если attrName равно null или не является допустимым именем атрибута для данного элемента.

getAttributeDefaultValue

String getAttributeDefaultValue(String elementName,
                                String attrName)

Возвращает значение по умолчанию указанного атрибута, если оно не указано явно внутри указанного элемента, как String, или null, если значение по умолчанию недоступно.

Параметры:

elementName - имя элемента, запрос к которому производится.

attrName - имя атрибута, запрос к которому производится.

Возвращает:

String содержащий значение по умолчанию, или null.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если attrName равно null или не является допустимым именем атрибута для данного элемента.

getAttributeEnumerations

String[] getAttributeEnumerations(String elementName,
                                  String attrName)

Возвращает массив Strings, содержащий допустимые перечисленные значения для данного атрибута внутри указанного элемента. Этот метод следует вызывать только в том случае, если getAttributeValueType возвращает VALUE_ENUMERATION.

Параметры:

elementName - имя элемента, запрос к которому производится.

attrName - имя атрибута, запрос к которому производится.

Возвращает:

массив Strings.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если attrName равно null или не является допустимым именем атрибута для данного элемента.

IllegalArgumentException - если заданный атрибут не определён как перечисление.

getAttributeMinValue

String getAttributeMinValue(String elementName,
                            String attrName)

Возвращает минимальное допустимое значение для атрибута. Включительно или исключающее значение может быть определено значением getAttributeValueType. Значение возвращается как String; его интерпретация зависит от значения getAttributeDataType. Этот метод следует вызывать только в том случае, если getAttributeValueType возвращает VALUE_RANGE_*.

Параметры:

elementName - имя элемента, запрос к которому производится.

attrName - имя атрибута, запрос к которому производится.

Возвращает:

String содержащий наименьшее допустимое значение для атрибута.

Исключения:

IllegalArgumentException - если elementName равно null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если attrName равно null или не является допустимым именем атрибута для данного элемента.

IllegalArgumentException - если заданный атрибут не определён как диапазон.

getAttributeMaxValue

String getAttributeMaxValue(String elementName,
                            String attrName)

Возвращает максимальное допустимое значение для атрибута. Включительно или исключающее значение может быть определено значением getAttributeValueType. Значение возвращается как String; его интерпретация зависит от значения getAttributeDataType. Этот метод следует вызывать только в том случае, если getAttributeValueType возвращает VALUE_RANGE_*.

Параметры:

elementName — имя запрошиваемого элемента в виде String.

attrName — имя запрошиваемого атрибута.

Возвращает:

объект String, содержащий наибольшее допустимое значение атрибута.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если attrName имеет значение null или не является допустимым именем атрибута для данного элемента.

IllegalArgumentException — если указанный атрибут не определен как диапазон.

getAttributeListMinLength

int getAttributeListMinLength(String elementName,
                              String attrName)

Возвращает минимальное количество элементов списка, которые могут быть использованы для определения данного атрибута. Сам атрибут определён как String, содержащий несколько элементов, разделённых пробелами. Этот метод следует вызывать только если getAttributeValueType возвращает VALUE_LIST.

Параметры:

elementName — имя запрошиваемого элемента.

attrName — имя запрошиваемого атрибута.

Возвращает:

наименьшее допустимое количество элементов списка для атрибута.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если attrName имеет значение null или не является допустимым именем атрибута для данного элемента.

IllegalArgumentException — если данный атрибут не определён как список.

getAttributeListMaxLength

int getAttributeListMaxLength(String elementName,
                              String attrName)

Возвращает максимальное количество элементов списка, которые могут быть использованы для определения данного атрибута. Значение Integer.MAX_VALUE может использоваться для указания отсутствия верхней границы. Сам атрибут определён как String, содержащий несколько элементов, разделённых пробелами. Этот метод следует вызывать только если getAttributeValueType возвращает VALUE_LIST.

Параметры:

elementName — имя запрошиваемого элемента.

attrName — имя запрошиваемого атрибута.

Возвращает:

наибольшее допустимое количество элементов списка для атрибута.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если attrName имеет значение null или не является допустимым именем атрибута для данного элемента.

IllegalArgumentException — если данный атрибут не определён как список.

getAttributeDescription

String getAttributeDescription(String elementName,
                               String attrName,
                               Locale locale)

Параметры:

elementName — имя элемента.

attrName — имя атрибута.

locale — Locale для которого будет выполнена локализация.

Возвращает:

описание атрибута.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null, или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если attrName имеет значение null или не является допустимым именем атрибута для данного элемента.

getObjectValueType

int getObjectValueType(String elementName)

Параметры:

elementName — имя запрошиваемого элемента.

Возвращает:

один из констант VALUE_*.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

См. также:

Comparable

getObjectClass

Class<?> getObjectClass(String elementName)

Параметры:

elementName — имя запрошиваемого элемента.

Возвращает:

объект Class.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если указанный элемент не может содержать значение объекта (т.е., если getObjectValueType(elementName) == VALUE_NONE).

getObjectDefaultValue

Object getObjectDefaultValue(String elementName)

Возвращает Object содержащий значение по умолчанию для ссылки Object внутри указанного элемента.

Параметры:

elementName — имя запрошиваемого элемента.

Возвращает:

объект Object.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если указанный элемент не может содержать значение объекта (т.е., если getObjectValueType(elementName) == VALUE_NONE).

getObjectEnumerations

Object[] getObjectEnumerations(String elementName)

Параметры:

elementName — имя запрошиваемого элемента.

Возвращает:

массив Object.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если указанный элемент не может содержать значение объекта (т.е., если getObjectValueType(elementName) == VALUE_NONE).

IllegalArgumentException — если Object не определен как перечисление.

getObjectMinValue

Comparable<?> getObjectMinValue(String elementName)

Возвращает минимальное допустимое значение для ссылки Object внутри указанного элемента. Включительно или исключительное значение может быть определено значением getObjectValueType. Этот метод следует вызывать только если getObjectValueType возвращает одно из констант, начинающихся с VALUE_RANGE.

Параметры:

elementName — имя запрошиваемого элемента.

Возвращает:

наименьшее допустимое значение для атрибута.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если указанный элемент не может содержать значение объекта (т.е., если getObjectValueType(elementName) == VALUE_NONE).

IllegalArgumentException — если Object не определен как диапазон.

getObjectMaxValue

Comparable<?> getObjectMaxValue(String elementName)

Возвращает максимальное допустимое значение для ссылки Object внутри указанного элемента. Включительно или исключительное значение может быть определено значением getObjectValueType. Этот метод следует вызывать только если getObjectValueType возвращает одно из констант, начинающихся с VALUE_RANGE.

Параметры:

elementName — имя запрошиваемого элемента.

Возвращает:

наименьшее допустимое значение для атрибута.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если указанный элемент не может содержать значение объекта (т.е., если getObjectValueType(elementName) == VALUE_NONE).

IllegalArgumentException — если Object не определен как диапазон.

getObjectArrayMinLength

int getObjectArrayMinLength(String elementName)

Возвращает минимальное количество элементов массива, которые могут быть использованы для определения ссылки Object внутри указанного элемента. Этот метод следует вызывать только если getObjectValueType возвращает VALUE_LIST.

Параметры:

elementName — имя запрошиваемого элемента.

Возвращает:

наименьшая допустимая длина массива для ссылки Object.

Выбрасывает:

IllegalArgumentException — если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException — если указанный элемент не может содержать значение объекта (т.е., если getObjectValueType(elementName) == VALUE_NONE).

IllegalArgumentException — если Object не является массивом.

getObjectArrayMaxLength

int getObjectArrayMaxLength(String elementName)

Возвращает максимальное количество элементов массива, которые могут быть использованы для определения ссылки Object внутри указанного элемента. Значение Integer.MAX_VALUE может быть использовано для указания отсутствия верхней границы. Этот метод следует вызывать только если getObjectValueType возвращает VALUE_LIST.

Параметры:

elementName - имя запрашиваемого элемента.

Возвращает:

наибольшую допустимую длину массива для ссылки Object.

Выбрасывает:

IllegalArgumentException - если elementName имеет значение null или не является допустимым именем элемента для данного формата.

IllegalArgumentException - если именованный элемент не может содержать значение объекта (т.е., если getObjectValueType(elementName) == VALUE_NONE).

IllegalArgumentException - если Object не является массивом.