IIOMetadataFormatImpl
public interface IIOMetadataFormat
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.desktopmodule 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:
CHILD_*
constants; Object
. There is no provision for representing such objects textually. Modifier and Type | Field | Description |
---|---|---|
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. |
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. |
static final int |
CHILD_POLICY_EMPTY |
A constant returned by getChildPolicy to indicate that an element may not have any children. |
static final int |
CHILD_POLICY_MAX |
The largest valid CHILD_POLICY_* constant, to be used for range checks. |
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. |
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. |
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. |
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'. |
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. |
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. |
static final int |
DATATYPE_INTEGER |
A constant returned by getAttributeDataType indicating that the value of an attribute is a string representation of an integer. |
static final int |
DATATYPE_STRING |
A constant returned by getAttributeDataType indicating that the value of an attribute is a general Unicode string. |
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. |
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. |
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. |
static final int |
VALUE_NONE |
A constant returned by getObjectValueType to indicate the absence of a user object. |
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. |
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. |
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 . |
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. |
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 . |
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. |
Modifier and Type | Method | Description |
---|---|---|
boolean |
canNodeAppear |
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 |
Returns one of the constants starting with DATATYPE_ , indicating the format and interpretation of the value of the given attribute within the named element. |
String |
getAttributeDefaultValue |
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. |
String |
getAttributeDescription |
Returns a String containing a description of the named attribute, or null . |
String[] |
getAttributeEnumerations |
Returns an array of String s containing the legal enumerated values for the given attribute within the named element. |
int |
getAttributeListMaxLength |
Returns the maximum number of list items that may be used to define this attribute. |
int |
getAttributeListMinLength |
Returns the minimum number of list items that may be used to define this attribute. |
String |
getAttributeMaxValue |
Returns the maximum legal value for the attribute. |
String |
getAttributeMinValue |
Returns the minimum legal value for the attribute. |
String[] |
getAttributeNames |
Returns an array of String s listing the names of the attributes that may be associated with the named element. |
int |
getAttributeValueType |
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 |
Returns an array of String s 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 |
Returns one of the constants starting with CHILD_POLICY_ , indicating the legal pattern of children for the named element. |
String |
getElementDescription |
Returns a String containing a description of the named element, or null . |
int |
getElementMaxChildren |
Returns the maximum number of children of the named element with child policy CHILD_POLICY_REPEAT . |
int |
getElementMinChildren |
Returns the minimum number of children of the named element with child policy CHILD_POLICY_REPEAT . |
int |
getObjectArrayMaxLength |
Returns the maximum number of array elements that may be used to define the Object reference within the named element. |
int |
getObjectArrayMinLength |
Returns the minimum number of array elements that may be used to define the Object reference within the named element. |
Class |
getObjectClass |
Returns the Class type of the Object reference stored within the element. |
Object |
getObjectDefaultValue |
Returns an Object s containing the default value for the Object reference within the named element. |
Object[] |
getObjectEnumerations |
Returns an array of Object s containing the legal enumerated values for the Object reference within the named element. |
Comparable |
getObjectMaxValue |
Returns the maximum legal value for the Object reference within the named element. |
Comparable |
getObjectMinValue |
Returns the minimum legal value for the Object reference within the named element. |
int |
getObjectValueType |
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 |
Returns true if the named attribute must be present within the named element. |
static final int CHILD_POLICY_EMPTY
getChildPolicy
to indicate that an element may not have any children. In other words, it is required to be a leaf node.static final int CHILD_POLICY_ALL
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,...
.static final int CHILD_POLICY_SOME
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?,...
.static final int CHILD_POLICY_CHOICE
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|...
.static final int CHILD_POLICY_SEQUENCE
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|...)*
.static final int CHILD_POLICY_REPEAT
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*
.static final int CHILD_POLICY_MAX
CHILD_POLICY_*
constant, to be used for range checks.static final int VALUE_NONE
getObjectValueType
to indicate the absence of a user object.static final int VALUE_ARBITRARY
getAttributeValueType
and getObjectValueType
to indicate that the attribute or user object may be set a single, arbitrary value.static final int VALUE_RANGE
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.static final int VALUE_RANGE_MIN_INCLUSIVE_MASK
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.
static final int VALUE_RANGE_MAX_INCLUSIVE_MASK
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.
static final int VALUE_RANGE_MIN_INCLUSIVE
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.static final int VALUE_RANGE_MAX_INCLUSIVE
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.static final int VALUE_RANGE_MIN_MAX_INCLUSIVE
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.static final int VALUE_ENUMERATION
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 String
s; for objects, they are Object
s implementing a given class or interface. Attribute values of type DATATYPE_BOOLEAN
should be marked as enumerations.
static final int VALUE_LIST
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.static final int DATATYPE_STRING
getAttributeDataType
indicating that the value of an attribute is a general Unicode string.static final int DATATYPE_BOOLEAN
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.static final int DATATYPE_INTEGER
getAttributeDataType
indicating that the value of an attribute is a string representation of an integer.static final int DATATYPE_FLOAT
getAttributeDataType
indicating that the value of an attribute is a string representation of a decimal floating-point number.static final int DATATYPE_DOUBLE
getAttributeDataType
indicating that the value of an attribute is a string representation of a double-precision decimal floating-point number.String getRootName()
String
.boolean canNodeAppear(String elementName, ImageTypeSpecifier imageType)
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.elementName
- the name of the element being queried.imageType
- an ImageTypeSpecifier
indicating the type of the image that will be associated with the metadata.true
if the node is meaningful for images of the given type.int getElementMinChildren(String elementName)
CHILD_POLICY_REPEAT
. For example, an element representing color primary information might be required to have at least 3 children, one for each primary.elementName
- the name of the element being queried.int
.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element does not have a child policy of CHILD_POLICY_REPEAT
.int getElementMaxChildren(String elementName)
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.elementName
- the name of the element being queried.int
.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element does not have a child policy of CHILD_POLICY_REPEAT
.String getElementDescription(String elementName, Locale locale)
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.
elementName
- the name of the element.locale
- the Locale
for which localization will be attempted.IllegalArgumentException
- if elementName
is null
, or is not a legal element name for this format.int getChildPolicy(String elementName)
CHILD_POLICY_
, indicating the legal pattern of children for the named element.elementName
- the name of the element being queried.CHILD_POLICY_*
constants.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.String[] getChildNames(String elementName)
String
s 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.elementName
- the name of the element being queried.String
s, or null.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.String[] getAttributeNames(String elementName)
String
s listing the names of the attributes that may be associated with the named element.elementName
- the name of the element being queried.String
s.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.int getAttributeValueType(String elementName, String attrName)
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.elementName
- the name of the element being queried.attrName
- the name of the attribute being queried.VALUE_*
constants.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.int getAttributeDataType(String elementName, String attrName)
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.elementName
- the name of the element being queried.attrName
- the name of the attribute being queried.DATATYPE_*
constants.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.boolean isAttributeRequired(String elementName, String attrName)
true
if the named attribute must be present within the named element.elementName
- the name of the element being queried.attrName
- the name of the attribute being queried.true
if the attribute must be present.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.String getAttributeDefaultValue(String elementName, String attrName)
String
, or null
if no default value is available.elementName
- the name of the element being queried.attrName
- the name of the attribute being queried.String
containing the default value, or null
.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.String[] getAttributeEnumerations(String elementName, String attrName)
String
s containing the legal enumerated values for the given attribute within the named element. This method should only be called if getAttributeValueType
returns VALUE_ENUMERATION
.elementName
- the name of the element being queried.attrName
- the name of the attribute being queried.String
s.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.IllegalArgumentException
- if the given attribute is not defined as an enumeration.String getAttributeMinValue(String elementName, String attrName)
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_*
.elementName
- the name of the element being queried.attrName
- the name of the attribute being queried.String
containing the smallest legal value for the attribute.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.IllegalArgumentException
- if the given attribute is not defined as a range.String getAttributeMaxValue(String elementName, String attrName)
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_*
.elementName
- the name of the element being queried, as a String
.attrName
- the name of the attribute being queried.String
containing the largest legal value for the attribute.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.IllegalArgumentException
- if the given attribute is not defined as a range.int getAttributeListMinLength(String elementName, String attrName)
String
containing multiple whitespace-separated items. This method should only be called if getAttributeValueType
returns VALUE_LIST
.elementName
- the name of the element being queried.attrName
- the name of the attribute being queried.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.IllegalArgumentException
- if the given attribute is not defined as a list.int getAttributeListMaxLength(String elementName, String attrName)
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
.elementName
- the name of the element being queried.attrName
- the name of the attribute being queried.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.IllegalArgumentException
- if the given attribute is not defined as a list.String getAttributeDescription(String elementName, String attrName, Locale locale)
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.
elementName
- the name of the element.attrName
- the name of the attribute.locale
- the Locale
for which localization will be attempted.IllegalArgumentException
- if elementName
is null
, or is not a legal element name for this format.IllegalArgumentException
- if attrName
is null
or is not a legal attribute name for this element.int getObjectValueType(String elementName)
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.
elementName
- the name of the element being queried.VALUE_*
constants.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.Class<?> getObjectClass(String elementName)
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 int
s, this method would return int.class
). Object
references whose legal values are defined as a range must implement the Comparable
interface.
elementName
- the name of the element being queried.Class
object.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE
).Object getObjectDefaultValue(String elementName)
Object
s containing the default value for the Object
reference within the named element.elementName
- the name of the element being queried.Object
.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE
).Object[] getObjectEnumerations(String elementName)
Object
s 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).
elementName
- the name of the element being queried.Object
s.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE
).IllegalArgumentException
- if the Object
is not defined as an enumeration.Comparable<?> getObjectMinValue(String elementName)
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
.elementName
- the name of the element being queried.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE
).IllegalArgumentException
- if the Object
is not defined as a range.Comparable<?> getObjectMaxValue(String elementName)
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
.elementName
- the name of the element being queried.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE
).IllegalArgumentException
- if the Object
is not defined as a range.int getObjectArrayMinLength(String elementName)
Object
reference within the named element. This method should only be called if getObjectValueType
returns VALUE_LIST
.elementName
- the name of the element being queried.Object
reference.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE
).IllegalArgumentException
- if the Object
is not an array.int getObjectArrayMaxLength(String elementName)
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
.elementName
- the name of the element being queried.Object
reference.IllegalArgumentException
- if elementName
is null
or is not a legal element name for this format.IllegalArgumentException
- if the named element cannot contain an object value (i.e., if getObjectValueType(elementName) == VALUE_NONE
).IllegalArgumentException
- if the Object
is not an array.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/imageio/metadata/IIOMetadataFormat.html