javax.imageio.metadata
Interface IIOMetadataFormat

All Known Implementing Classes:

IIOMetadataFormatImpl

public interface IIOMetadataFormat

An object describing the structure of metadata documents returned from IIOMetadata.getAsTree and passed to IIOMetadata.setFromTree and mergeTree. Document structures are described by a set of constraints on the type and number of child elements that may belong to a given parent element type, the names, types, and values of attributes that may belong to an element, and the type and values of Object reference that may be stored at a node.

N.B: classes that implement this interface should contain a method declared as public static getInstance() which returns an instance of the class. Commonly, an implentation will construct only a single instance and cache it for future invocations of getInstance.

The structures that may be described by this class are a subset of those expressible using XML document type definitions (DTDs), with the addition of some basic information on the datatypes of attributes and the ability to store an Object reference within a node. In the future, XML Schemas could be used to represent these structures, and many others.

The differences between IIOMetadataFormat-described structures and DTDs are as follows:

• Elements may not contain text or mix text with embedded tags.
• The children of an element must conform to one of a few simple patterns, described in the documentation for the CHILD_* constants;
• The in-memory representation of an elements may contain a reference to an Object. There is no provision for representing such objects textually.

Field Summary

static int	CHILD_POLICY_ALL A constant returned by getChildPolicy to indicate that an element must have a single instance of each of its legal child elements, in order.
static int	CHILD_POLICY_CHOICE A constant returned by getChildPolicy to indicate that an element must have zero or one children, selected from among its legal child elements.
static int	CHILD_POLICY_EMPTY A constant returned by getChildPolicy to indicate that an element may not have any children.
static int	CHILD_POLICY_MAX The largest valid CHILD_POLICY_* constant, to be used for range checks.
static int	CHILD_POLICY_REPEAT A constant returned by getChildPolicy to indicate that an element must have zero or more instances of its unique legal child element.
static int	CHILD_POLICY_SEQUENCE A constant returned by getChildPolicy to indicate that an element must have a sequence of instances of any of its legal child elements.
static int	CHILD_POLICY_SOME A constant returned by getChildPolicy to indicate that an element must have zero or one instance of each of its legal child elements, in order.
static int	DATATYPE_BOOLEAN A constant returned by getAttributeDataType indicating that the value of an attribute is one of 'true' or 'false'.
static int	DATATYPE_DOUBLE A constant returned by getAttributeDataType indicating that the value of an attribute is a string representation of a double-precision decimal floating-point number.
static int	DATATYPE_FLOAT A constant returned by getAttributeDataType indicating that the value of an attribute is a string representation of a decimal floating-point number.
static int	DATATYPE_INTEGER A constant returned by getAttributeDataType indicating that the value of an attribute is a string representation of an integer.
static int	DATATYPE_STRING A constant returned by getAttributeDataType indicating that the value of an attribute is a general Unicode string.
static int	VALUE_ARBITRARY A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set a single, arbitrary value.
static int	VALUE_ENUMERATION A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set one of a number of enumerated values.
static int	VALUE_LIST A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set to a list or array of values.
static int	VALUE_NONE A constant returned by getObjectValueType to indicate the absence of a user object.
static int	VALUE_RANGE A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set a range of values.
static int	VALUE_RANGE_MAX_INCLUSIVE A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set to a range of values.
static int	VALUE_RANGE_MAX_INCLUSIVE_MASK A value that may be or'ed with VALUE_RANGE to obtain VALUE_RANGE_MAX_INCLUSIVE, and with VALUE_RANGE_MIN_INCLUSIVE to obtain VALUE_RANGE_MIN_MAX_INCLUSIVE.
static int	VALUE_RANGE_MIN_INCLUSIVE A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set to a range of values.
static int	VALUE_RANGE_MIN_INCLUSIVE_MASK A value that may be or'ed with VALUE_RANGE to obtain VALUE_RANGE_MIN_INCLUSIVE, and with VALUE_RANGE_MAX_INCLUSIVE to obtain VALUE_RANGE_MIN_MAX_INCLUSIVE.
static int	VALUE_RANGE_MIN_MAX_INCLUSIVE A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set a range of values.

Method Summary

boolean	canNodeAppear (String elementName, ImageTypeSpecifier imageType) Returns true if the element (and the subtree below it) is allowed to appear in a metadata document for an image of the given type, defined by an ImageTypeSpecifier.
int	getAttributeDataType (String elementName, String attrName) Returns one of the constants starting with DATATYPE_, indicating the format and interpretation of the value of the given attribute within th enamed element.
String	getAttributeDefaultValue (String elementName, String attrName) Returns the default value of the named attribute, if it is not explictly present within the named element, as a String, or null if no default value is available.
String	getAttributeDescription (String elementName, String attrName, Locale locale) Returns a String containing a description of the named attribute, or null.
String []	getAttributeEnumerations (String elementName, String attrName) Returns an array of Strings containing the legal enumerated values for the given attribute within the named element.
int	getAttributeListMaxLength (String elementName, String attrName) Returns the maximum number of list items that may be used to define this attribute.
int	getAttributeListMinLength (String elementName, String attrName) Returns the minimum number of list items that may be used to define this attribute.
String	getAttributeMaxValue (String elementName, String attrName) Returns the maximum legal value for the attribute.
String	getAttributeMinValue (String elementName, String attrName) Returns the minimum legal value for the attribute.
String []	getAttributeNames (String elementName) Returns an array of Strings listing the names of the attributes that may be associated with the named element.
int	getAttributeValueType (String elementName, String attrName) Returns one of the constants starting with VALUE_, indicating whether the values of the given attribute within the named element are arbitrary, constrained to lie within a specified range, constrained to be one of a set of enumerated values, or are a whitespace-separated list of arbitrary values.
String []	getChildNames (String elementName) Returns an array of Strings indicating the names of the element which are allowed to be children of the named element, in the order in which they should appear.
int	getChildPolicy (String elementName) Returns one of the constants starting with CHILD_POLICY_, indicating the legal pattern of children for the named element.
String	getElementDescription (String elementName, Locale locale) Returns a String containing a description of the named element, or null.
int	getElementMaxChildren (String elementName) Returns the maximum number of children of the named element with child policy CHILD_POLICY_REPEAT.
int	getElementMinChildren (String elementName) Returns the minimum number of children of the named element with child policy CHILD_POLICY_REPEAT.
int	getObjectArrayMaxLength (String elementName) Returns the maximum number of array elements that may be used to define the Object reference within the named element.
int	getObjectArrayMinLength (String elementName) Returns the minimum number of array elements that may be used to define the Object reference within the named element.
Class <?>	getObjectClass (String elementName) Returns the Class type of the Object reference stored within the element.
Object	getObjectDefaultValue (String elementName) Returns an Objects containing the default value for the Object reference within the named element.
Object []	getObjectEnumerations (String elementName) Returns an array of Objects containing the legal enumerated values for the Object reference within the named element.
Comparable <?>	getObjectMaxValue (String elementName) Returns the maximum legal value for the Object reference within the named element.
Comparable <?>	getObjectMinValue (String elementName) Returns the minimum legal value for the Object reference within the named element.
int	getObjectValueType (String elementName) Returns one of the enumerated values starting with VALUE_, indicating the type of values (enumeration, range, or array) that are allowed for the Object reference.
String	getRootName () Returns the name of the root element of the format.
boolean	isAttributeRequired (String elementName, String attrName) Returns true if the named attribute must be present within the named element.

Field Detail

CHILD_POLICY_EMPTY

static final int CHILD_POLICY_EMPTY

A constant returned by getChildPolicy to indicate that an element may not have any children. In other words, it is required to be a leaf node.

See Also:

Constant Field Values

CHILD_POLICY_ALL

static final int CHILD_POLICY_ALL

A constant returned by getChildPolicy to indicate that an element must have a single instance of each of its legal child elements, in order. In DTD terms, the contents of the element are defined by a sequence a,b,c,d,....

See Also:

Constant Field Values

CHILD_POLICY_SOME

static final int CHILD_POLICY_SOME

A constant returned by getChildPolicy to indicate that an element must have zero or one instance of each of its legal child elements, in order. In DTD terms, the contents of the element are defined by a sequence a?,b?,c?,d?,....

See Also:

Constant Field Values

CHILD_POLICY_CHOICE

static final int CHILD_POLICY_CHOICE

A constant returned by getChildPolicy to indicate that an element must have zero or one children, selected from among its legal child elements. In DTD terms, the contents of the element are defined by a selection a|b|c|d|....

See Also:

Constant Field Values

CHILD_POLICY_SEQUENCE

static final int CHILD_POLICY_SEQUENCE

A constant returned by getChildPolicy to indicate that an element must have a sequence of instances of any of its legal child elements. In DTD terms, the contents of the element are defined by a sequence (a|b|c|d|...)*.

See Also:

Constant Field Values

CHILD_POLICY_REPEAT

static final int CHILD_POLICY_REPEAT

A constant returned by getChildPolicy to indicate that an element must have zero or more instances of its unique legal child element. In DTD terms, the contents of the element are defined by a starred expression a*.

See Also:

Constant Field Values

CHILD_POLICY_MAX

static final int CHILD_POLICY_MAX

The largest valid CHILD_POLICY_* constant, to be used for range checks.

See Also:

Constant Field Values

VALUE_NONE

static final int VALUE_NONE

A constant returned by getObjectValueType to indicate the absence of a user object.

See Also:

Constant Field Values

VALUE_ARBITRARY

static final int VALUE_ARBITRARY

A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set a single, arbitrary value.

See Also:

Constant Field Values

VALUE_RANGE

static final int VALUE_RANGE

A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set a range of values. Both the minimum and maximum values of the range are exclusive. It is recommended that ranges of integers be inclusive on both ends, and that exclusive ranges be used only for floating-point data.

See Also:

VALUE_RANGE_MIN_MAX_INCLUSIVE , Constant Field Values

VALUE_RANGE_MIN_INCLUSIVE_MASK

static final int VALUE_RANGE_MIN_INCLUSIVE_MASK

A value that may be or'ed with VALUE_RANGE to obtain VALUE_RANGE_MIN_INCLUSIVE, and with VALUE_RANGE_MAX_INCLUSIVE to obtain VALUE_RANGE_MIN_MAX_INCLUSIVE.

Similarly, the value may be and'ed with the value of getAttributeValueTypeor getObjectValueType to determine if the minimum value of the range is inclusive.

See Also:

Constant Field Values

VALUE_RANGE_MAX_INCLUSIVE_MASK

static final int VALUE_RANGE_MAX_INCLUSIVE_MASK

A value that may be or'ed with VALUE_RANGE to obtain VALUE_RANGE_MAX_INCLUSIVE, and with VALUE_RANGE_MIN_INCLUSIVE to obtain VALUE_RANGE_MIN_MAX_INCLUSIVE.

Similarly, the value may be and'ed with the value of getAttributeValueTypeor getObjectValueType to determine if the maximum value of the range is inclusive.

See Also:

Constant Field Values

VALUE_RANGE_MIN_INCLUSIVE

static final int VALUE_RANGE_MIN_INCLUSIVE

A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set to a range of values. The minimum (but not the maximum) value of the range is inclusive.

See Also:

Constant Field Values

VALUE_RANGE_MAX_INCLUSIVE

static final int VALUE_RANGE_MAX_INCLUSIVE

A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set to a range of values. The maximum (but not the minimum) value of the range is inclusive.

See Also:

Constant Field Values

VALUE_RANGE_MIN_MAX_INCLUSIVE

static final int VALUE_RANGE_MIN_MAX_INCLUSIVE

A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set a range of values. Both the minimum and maximum values of the range are inclusive. It is recommended that ranges of integers be inclusive on both ends, and that exclusive ranges be used only for floating-point data.

See Also:

Constant Field Values

VALUE_ENUMERATION

static final int VALUE_ENUMERATION

A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set one of a number of enumerated values. In the case of attributes, these values are Strings; for objects, they are Objects implementing a given class or interface.

Attribute values of type DATATYPE_BOOLEAN should be marked as enumerations.

See Also:

Constant Field Values

VALUE_LIST

static final int VALUE_LIST

A constant returned by getAttributeValueType and getObjectValueType to indicate that the attribute or user object may be set to a list or array of values. In the case of attributes, the list will consist of whitespace-separated values within a String; for objects, an array will be used.

See Also:

Constant Field Values

DATATYPE_STRING

static final int DATATYPE_STRING

A constant returned by getAttributeDataType indicating that the value of an attribute is a general Unicode string.

See Also:

Constant Field Values

DATATYPE_BOOLEAN

static final int DATATYPE_BOOLEAN

A constant returned by getAttributeDataType indicating that the value of an attribute is one of 'true' or 'false'.

See Also:

Constant Field Values

DATATYPE_INTEGER

static final int DATATYPE_INTEGER

A constant returned by getAttributeDataType indicating that the value of an attribute is a string representation of an integer.

See Also:

Constant Field Values

DATATYPE_FLOAT

static final int DATATYPE_FLOAT

A constant returned by getAttributeDataType indicating that the value of an attribute is a string representation of a decimal floating-point number.

See Also:

Constant Field Values

DATATYPE_DOUBLE

static final int DATATYPE_DOUBLE

A constant returned by getAttributeDataType indicating that the value of an attribute is a string representation of a double-precision decimal floating-point number.

See Also:

Constant Field Values

Method Detail

getRootName

String    getRootName()

Returns the name of the root element of the format.

Returns:

a String.

canNodeAppear