APIdia Launch Partner
Top Description Fields Methods
javax.imageio.metadata

public Interface IIOMetadataFormat

Known Direct Implementers
javax.imageio.metadata.IIOMetadataFormatImpl, com.sun.imageio.plugins.tiff.TIFFMetadataFormat
Imports
java.util.Locale, javax.imageio.ImageTypeSpecifier
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 implementation will construct only a single instance and cache it for future invocations of getInstance.

In the event that the plugin is provided as part of a named module, that module must export the package containing the implementation class to the 

java.desktop
module via a qualified export. An unqualified export is not recommended unless also needed for some other reason. Failing to export the package will result in access failure at runtime.

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:

Field Summary

Modifier and TypeField and Description
public 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.

public 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.

public static final int
CHILD_POLICY_EMPTY

A constant returned by getChildPolicy to indicate that an element may not have any children.

public static final int
CHILD_POLICY_MAX

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

public 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.

public 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.

public 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.

public static final int
DATATYPE_BOOLEAN

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

public 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.

public 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.

public static final int
DATATYPE_INTEGER

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

public static final int
DATATYPE_STRING

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

public 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.

public 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.

public 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.

public static final int
VALUE_NONE

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

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if the node is meaningful for images of the given type.
canNodeAppear(String
the name of the element being queried.
elementName, ImageTypeSpecifier
an ImageTypeSpecifier indicating the type of the image that will be associated with the metadata.
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.

public int

Returns:

one of the DATATYPE_* constants.
getAttributeDataType(String
the name of the element being queried.
elementName, String
the name of the attribute being queried.
attrName)

Returns one of the constants starting with DATATYPE_, indicating the format and interpretation of the value of the given attribute within the named element.

public String

Returns:

a String containing the default value, or null.
getAttributeDefaultValue(String
the name of the element being queried.
elementName, String
the name of the attribute being queried.
attrName)

Returns the default value of the named attribute, if it is not explicitly present within the named element, as a String, or null if no default value is available.

public String

Returns:

the attribute description.
getAttributeDescription(String
the name of the element.
elementName, String
the name of the attribute.
attrName, Locale
the Locale for which localization will be attempted.
locale)

Returns a String containing a description of the named attribute, or null.

public String[]

Returns:

an array of Strings.
getAttributeEnumerations(String
the name of the element being queried.
elementName, String
the name of the attribute being queried.
attrName)

Returns an array of Strings containing the legal enumerated values for the given attribute within the named element.

public int

Returns:

the largest legal number of list items for the attribute.
getAttributeListMaxLength(String
the name of the element being queried.
elementName, String
the name of the attribute being queried.
attrName)

Returns the maximum number of list items that may be used to define this attribute.

public int

Returns:

the smallest legal number of list items for the attribute.
getAttributeListMinLength(String
the name of the element being queried.
elementName, String
the name of the attribute being queried.
attrName)

Returns the minimum number of list items that may be used to define this attribute.

public String

Returns:

a String containing the largest legal value for the attribute.
getAttributeMaxValue(String
the name of the element being queried, as a String.
elementName, String
the name of the attribute being queried.
attrName)

Returns the maximum legal value for the attribute.

public String

Returns:

a String containing the smallest legal value for the attribute.
getAttributeMinValue(String
the name of the element being queried.
elementName, String
the name of the attribute being queried.
attrName)

Returns the minimum legal value for the attribute.

public String[]

Returns:

an array of Strings.
getAttributeNames(String
the name of the element being queried.
elementName)

Returns an array of Strings listing the names of the attributes that may be associated with the named element.

public int

Returns:

one of the VALUE_* constants.
getAttributeValueType(String
the name of the element being queried.
elementName, String
the name of the attribute being queried.
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.

public String[]

Returns:

an array of Strings, or null.
getChildNames(String
the name of the element being queried.
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.

public int

Returns:

one of the CHILD_POLICY_* constants.
getChildPolicy(String
the name of the element being queried.
elementName)

Returns one of the constants starting with CHILD_POLICY_, indicating the legal pattern of children for the named element.

public String

Returns:

the element description.
getElementDescription(String
the name of the element.
elementName, Locale
the Locale for which localization will be attempted.
locale)

Returns a String containing a description of the named element, or null.

public int

Returns:

an int.
getElementMaxChildren(String
the name of the element being queried.
elementName)

Returns the maximum number of children of the named element with child policy CHILD_POLICY_REPEAT.

public int

Returns:

an int.
getElementMinChildren(String
the name of the element being queried.
elementName)

Returns the minimum number of children of the named element with child policy CHILD_POLICY_REPEAT.

public int

Returns:

the largest valid array length for the Object reference.
getObjectArrayMaxLength(String
the name of the element being queried.
elementName)

Returns the maximum number of array elements that may be used to define the Object reference within the named element.

public int

Returns:

the smallest valid array length for the Object reference.
getObjectArrayMinLength(String
the name of the element being queried.
elementName)

Returns the minimum number of array elements that may be used to define the Object reference within the named element.

public Class<?>

Returns:

a Class object.
getObjectClass(String
the name of the element being queried.
elementName)

Returns the Class type of the Object reference stored within the element.

public Object

Returns:

an Object.
getObjectDefaultValue(String
the name of the element being queried.
elementName)

Returns an Objects containing the default value for the Object reference within the named element.

public Object[]

Returns:

an array of Objects.
getObjectEnumerations(String
the name of the element being queried.
elementName)

Returns an array of Objects containing the legal enumerated values for the Object reference within the named element.

public Comparable<?>

Returns:

the smallest legal value for the attribute.
getObjectMaxValue(String
the name of the element being queried.
elementName)

Returns the maximum legal value for the Object reference within the named element.

public Comparable<?>

Returns:

the smallest legal value for the attribute.
getObjectMinValue(String
the name of the element being queried.
elementName)

Returns the minimum legal value for the Object reference within the named element.

public int

Returns:

one of the VALUE_* constants.
getObjectValueType(String
the name of the element being queried.
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.

public String

Returns:

a String.
getRootName()

Returns the name of the root element of the format.

public boolean

Returns:

true if the attribute must be present.
isAttributeRequired(String
the name of the element being queried.
elementName, String
the name of the attribute being queried.
attrName)

Returns true if the named attribute must be present within the named element.

Field Detail

CHILD_POLICY_ALLback to summary
public 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,....

CHILD_POLICY_CHOICEback to summary
public 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|....

CHILD_POLICY_EMPTYback to summary
public 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.

CHILD_POLICY_MAXback to summary
public static final int CHILD_POLICY_MAX

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

CHILD_POLICY_REPEATback to summary
public 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*.

CHILD_POLICY_SEQUENCEback to summary
public 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|...)*.

CHILD_POLICY_SOMEback to summary
public 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?,....

DATATYPE_BOOLEANback to summary
public static final int DATATYPE_BOOLEAN

A constant returned by getAttributeDataType indicating that the value of an attribute is one of the boolean values 'true' or 'false'. Attribute values of type DATATYPE_BOOLEAN should be marked as enumerations, and the permitted values should be the string literal values "TRUE" or "FALSE", although a plugin may also recognise lower or mixed case equivalents.

DATATYPE_DOUBLEback to summary
public 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.

DATATYPE_FLOATback to summary
public 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.

DATATYPE_INTEGERback to summary
public static final int DATATYPE_INTEGER

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

DATATYPE_STRINGback to summary
public static final int DATATYPE_STRING

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

VALUE_ARBITRARYback to summary
public 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.

VALUE_ENUMERATIONback to summary
public 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.

VALUE_LISTback to summary
public 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.

VALUE_NONEback to summary
public static final int VALUE_NONE

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

VALUE_RANGEback to summary
public 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
VALUE_RANGE_MAX_INCLUSIVEback to summary
public 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.

VALUE_RANGE_MAX_INCLUSIVE_MASKback to summary
public 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 getAttributeValueType or getObjectValueType to determine if the maximum value of the range is inclusive.

VALUE_RANGE_MIN_INCLUSIVEback to summary
public 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.

VALUE_RANGE_MIN_INCLUSIVE_MASKback to summary
public 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 getAttributeValueType or getObjectValueType to determine if the minimum value of the range is inclusive.

VALUE_RANGE_MIN_MAX_INCLUSIVEback to summary
public 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.

Method Detail

canNodeAppearback to summary
public 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. For example, a metadata document format might contain an element that describes the primary colors of the image, which would not be allowed when writing a grayscale image.

Parameters
elementName:String

the name of the element being queried.

imageType:ImageTypeSpecifier

an ImageTypeSpecifier indicating the type of the image that will be associated with the metadata.

Returns:boolean

true if the node is meaningful for images of the given type.

getAttributeDataTypeback to summary
public 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 the named element. If getAttributeValueType returns VALUE_LIST, then the legal value is a whitespace-spearated list of values of the returned datatype.

Parameters
elementName:String

the name of the element being queried.

attrName:String

the name of the attribute being queried.

Returns:int

one of the DATATYPE_* constants.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
getAttributeDefaultValueback to summary
public String getAttributeDefaultValue(String elementName, String attrName)

Returns the default value of the named attribute, if it is not explicitly present within the named element, as a String, or null if no default value is available.

Parameters
elementName:String

the name of the element being queried.

attrName:String

the name of the attribute being queried.

Returns:String

a String containing the default value, or null.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
getAttributeDescriptionback to summary
public String getAttributeDescription(String elementName, String attrName, Locale locale)

Returns a String containing a description of the named attribute, or null. The description will be localized for the supplied Locale if possible.

If locale is null, the current default Locale returned by Locale.getLocale will be used.

Parameters
elementName:String

the name of the element.

attrName:String

the name of the attribute.

locale:Locale

the Locale for which localization will be attempted.

Returns:String

the attribute description.

Exceptions
IllegalArgumentException:
  • if elementName is null, or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
getAttributeEnumerationsback to summary
public String[] getAttributeEnumerations(String elementName, String attrName)

Returns an array of Strings containing the legal enumerated values for the given attribute within the named element. This method should only be called if getAttributeValueType returns VALUE_ENUMERATION.

Parameters
elementName:String

the name of the element being queried.

attrName:String

the name of the attribute being queried.

Returns:String[]

an array of Strings.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
  • if the given attribute is not defined as an enumeration.
getAttributeListMaxLengthback to summary
public int getAttributeListMaxLength(String elementName, String attrName)

Returns the maximum number of list items that may be used to define this attribute. A value of Integer.MAX_VALUE may be used to specify that there is no upper bound. The attribute itself is defined as a String containing multiple whitespace-separated items. This method should only be called if getAttributeValueType returns VALUE_LIST.

Parameters
elementName:String

the name of the element being queried.

attrName:String

the name of the attribute being queried.

Returns:int

the largest legal number of list items for the attribute.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
  • if the given attribute is not defined as a list.
getAttributeListMinLengthback to summary
public int getAttributeListMinLength(String elementName, String attrName)

Returns the minimum number of list items that may be used to define this attribute. The attribute itself is defined as a String containing multiple whitespace-separated items. This method should only be called if getAttributeValueType returns VALUE_LIST.

Parameters
elementName:String

the name of the element being queried.

attrName:String

the name of the attribute being queried.

Returns:int

the smallest legal number of list items for the attribute.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
  • if the given attribute is not defined as a list.
getAttributeMaxValueback to summary
public String getAttributeMaxValue(String elementName, String attrName)

Returns the maximum legal value for the attribute. Whether this value is inclusive or exclusive may be determined by the value of getAttributeValueType. The value is returned as a String; its interpretation is dependent on the value of getAttributeDataType. This method should only be called if getAttributeValueType returns VALUE_RANGE_*.

Parameters
elementName:String

the name of the element being queried, as a String.

attrName:String

the name of the attribute being queried.

Returns:String

a String containing the largest legal value for the attribute.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
  • if the given attribute is not defined as a range.
getAttributeMinValueback to summary
public String getAttributeMinValue(String elementName, String attrName)

Returns the minimum legal value for the attribute. Whether this value is inclusive or exclusive may be determined by the value of getAttributeValueType. The value is returned as a String; its interpretation is dependent on the value of getAttributeDataType. This method should only be called if getAttributeValueType returns VALUE_RANGE_*.

Parameters
elementName:String

the name of the element being queried.

attrName:String

the name of the attribute being queried.

Returns:String

a String containing the smallest legal value for the attribute.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
  • if the given attribute is not defined as a range.
getAttributeNamesback to summary
public String[] getAttributeNames(String elementName)

Returns an array of Strings listing the names of the attributes that may be associated with the named element.

Parameters
elementName:String

the name of the element being queried.

Returns:String[]

an array of Strings.

Exceptions
IllegalArgumentException:
if elementName is null or is not a legal element name for this format.
getAttributeValueTypeback to summary
public 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.

Parameters
elementName:String

the name of the element being queried.

attrName:String

the name of the attribute being queried.

Returns:int

one of the VALUE_* constants.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.
getChildNamesback to summary
public 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. If the element cannot have children, null is returned.

Parameters
elementName:String

the name of the element being queried.

Returns:String[]

an array of Strings, or null.

Exceptions
IllegalArgumentException:
if elementName is null or is not a legal element name for this format.
getChildPolicyback to summary
public int getChildPolicy(String elementName)

Returns one of the constants starting with CHILD_POLICY_, indicating the legal pattern of children for the named element.

Parameters
elementName:String

the name of the element being queried.

Returns:int

one of the CHILD_POLICY_* constants.

Exceptions
IllegalArgumentException:
if elementName is null or is not a legal element name for this format.
getElementDescriptionback to summary
public String getElementDescription(String elementName, Locale locale)

Returns a String containing a description of the named element, or null. The description will be localized for the supplied Locale if possible.

If locale is null, the current default Locale returned by Locale.getLocale will be used.

Parameters
elementName:String

the name of the element.

locale:Locale

the Locale for which localization will be attempted.

Returns:String

the element description.

Exceptions
IllegalArgumentException:
if elementName is null, or is not a legal element name for this format.
getElementMaxChildrenback to summary
public int getElementMaxChildren(String elementName)

Returns the maximum number of children of the named element with child policy CHILD_POLICY_REPEAT. For example, an element representing an entry in an 8-bit color palette might be allowed to repeat up to 256 times. A value of Integer.MAX_VALUE may be used to specify that there is no upper bound.

Parameters
elementName:String

the name of the element being queried.

Returns:int

an int.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element does not have a child policy of CHILD_POLICY_REPEAT.
getElementMinChildrenback to summary
public int getElementMinChildren(String elementName)

Returns the minimum number of children of the named element with child policy CHILD_POLICY_REPEAT. For example, an element representing color primary information might be required to have at least 3 children, one for each primary.

Parameters
elementName:String

the name of the element being queried.

Returns:int

an int.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element does not have a child policy of CHILD_POLICY_REPEAT.
getObjectArrayMaxLengthback to summary
public int getObjectArrayMaxLength(String elementName)

Returns the maximum number of array elements that may be used to define the Object reference within the named element. A value of Integer.MAX_VALUE may be used to specify that there is no upper bound. This method should only be called if getObjectValueType returns VALUE_LIST.

Parameters
elementName:String

the name of the element being queried.

Returns:int

the largest valid array length for the Object reference.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE).
  • if the Object is not an array.
getObjectArrayMinLengthback to summary
public int getObjectArrayMinLength(String elementName)

Returns the minimum number of array elements that may be used to define the Object reference within the named element. This method should only be called if getObjectValueType returns VALUE_LIST.

Parameters
elementName:String

the name of the element being queried.

Returns:int

the smallest valid array length for the Object reference.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE).
  • if the Object is not an array.
getObjectClassback to summary
public Class<?> getObjectClass(String elementName)

Returns the Class type of the Object reference stored within the element. If this element may not contain an Object reference, an IllegalArgumentException will be thrown. If the class type is an array, this field indicates the underlying class type (e.g, for an array of ints, this method would return int.class).

Object references whose legal values are defined as a range must implement the Comparable interface.

Parameters
elementName:String

the name of the element being queried.

Returns:Class<?>

a Class object.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE).
getObjectDefaultValueback to summary
public Object getObjectDefaultValue(String elementName)

Returns an Objects containing the default value for the Object reference within the named element.

Parameters
elementName:String

the name of the element being queried.

Returns:Object

an Object.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE).
getObjectEnumerationsback to summary
public Object[] getObjectEnumerations(String elementName)

Returns an array of Objects containing the legal enumerated values for the Object reference within the named element. This method should only be called if getObjectValueType returns VALUE_ENUMERATION.

The Object associated with a node that accepts enumerated values must be equal to one of the values returned by this method, as defined by the == operator (as opposed to the Object.equals method).

Parameters
elementName:String

the name of the element being queried.

Returns:Object[]

an array of Objects.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE).
  • if the Object is not defined as an enumeration.
getObjectMaxValueback to summary
public Comparable<?> getObjectMaxValue(String elementName)

Returns the maximum legal value for the Object reference within the named element. Whether this value is inclusive or exclusive may be determined by the value of getObjectValueType. This method should only be called if getObjectValueType returns one of the constants starting with VALUE_RANGE.

Parameters
elementName:String

the name of the element being queried.

Returns:Comparable<?>

the smallest legal value for the attribute.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE).
  • if the Object is not defined as a range.
getObjectMinValueback to summary
public Comparable<?> getObjectMinValue(String elementName)

Returns the minimum legal value for the Object reference within the named element. Whether this value is inclusive or exclusive may be determined by the value of getObjectValueType. This method should only be called if getObjectValueType returns one of the constants starting with VALUE_RANGE.

Parameters
elementName:String

the name of the element being queried.

Returns:Comparable<?>

the smallest legal value for the attribute.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE).
  • if the Object is not defined as a range.
getObjectValueTypeback to summary
public 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. If no object value can be stored within the given element, the result of this method will be VALUE_NONE.

Object references whose legal values are defined as a range must implement the Comparable interface.

Parameters
elementName:String

the name of the element being queried.

Returns:int

one of the VALUE_* constants.

Exceptions
IllegalArgumentException:
if elementName is null or is not a legal element name for this format.
See Also
Comparable
getRootNameback to summary
public String getRootName()

Returns the name of the root element of the format.

Returns:String

a String.

isAttributeRequiredback to summary
public boolean isAttributeRequired(String elementName, String attrName)

Returns true if the named attribute must be present within the named element.

Parameters
elementName:String

the name of the element being queried.

attrName:String

the name of the attribute being queried.

Returns:boolean

true if the attribute must be present.

Exceptions
IllegalArgumentException:
  • if elementName is null or is not a legal element name for this format.
  • if attrName is null or is not a legal attribute name for this element.