javax.imageio.metadata
接口 IIOMetadataFormat

所有已知实现类：

IIOMetadataFormatImpl

public interface IIOMetadataFormat

描述从 IIOMetadata.getAsTree 返回并传递给 IIOMetadata.setFromTree 和 mergeTree 的元数据文档结构的对象。文档结构通过以下事物描述：一个关于可能属于某个给定父元素类型的子元素类型和数目的限制条件集合、可能属于某个元素的属性的名称、类型和值、以及可能存储在节点中的 Object 引用的类型和值。

N.B：实现此接口的类应该包含声明为 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 进行“或”运算来获取 VALUE_RANGE_MIN_INCLUSIVE，可以与 VALUE_RANGE_MAX_INCLUSIVE 进行“或”运算来获取 VALUE_RANGE_MIN_MAX_INCLUSIVE。

类似地，可以将该值与 getAttributeValueType 或 getObjectValueType 的值进行“与”运算来确定是否包括范围的最小值。

另请参见：

常量字段值

VALUE_RANGE_MAX_INCLUSIVE_MASK

static final int VALUE_RANGE_MAX_INCLUSIVE_MASK

该值可以与 VALUE_RANGE 进行“或”运算来获取 VALUE_RANGE_MAX_INCLUSIVE，可以与 VALUE_RANGE_MIN_INCLUSIVE 进行“或”运算来获取 VALUE_RANGE_MIN_MAX_INCLUSIVE。

类似地，可以将该值与 getAttributeValueType 或 getObjectValueType 的值进行“与”运算来确定是否包括范围的最大值。

另请参见：

常量字段值

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

getAttributeValueType 和 getObjectValueType 返回的常量，指示可以将属性或用户对象设置为许多枚举值之一。对于属性来说，这些值为 String；对于对象，其为实现给定类或接口的 Object。

应该将 DATATYPE_BOOLEAN 类型的属性值标记为枚举。

另请参见：

常量字段值

VALUE_LIST

static final int VALUE_LIST

getAttributeValueType 和 getObjectValueType 返回的常量，指示可以将属性或用户对象设置为一个值的列表或数组。对于属性来说，列表将由在 String 中由空白分隔的值组成；对于对象，将使用数组。

另请参见：

常量字段值

DATATYPE_STRING

static final int DATATYPE_STRING

getAttributeDataType 返回的常量，指示属性的值为通用的 Unicode 字符串。

另请参见：

常量字段值

DATATYPE_BOOLEAN

static final int DATATYPE_BOOLEAN

getAttributeDataType 返回的常量，指示属性的值为 '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()

返回格式的根元素的名称。

返回：

String。

canNodeAppear

boolean canNodeAppear(String elementName,
                      ImageTypeSpecifier imageType)

如果允许元素（和它下面的子树）在给定类型（由 ImageTypeSpecifier 定义）的图像的元数据文档中出现，则返回 true。例如，元数据文档格式可能包含描述图像原色的元素，该元素在写入灰度级图像时是不允许出现的。

参数：

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)

返回包含指定元素的描述的 String，或者 null。如果可能，应将该描述本地化为提供的 Locale。

如果 locale 为 null，则使用 Locale.getLocale 返回的当前默认 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)

返回一个按出现顺序排列的 String 数组，指示允许作为指定元素子元素的元素的名称。如果元素不能有子元素，则返回 null。

参数：

elementName - 要查询的元素的名称。

返回：

String 数组，或 null。

抛出：

IllegalArgumentException - 如果 elementName 为 null 或者不是此格式的合法元素名称。

getAttributeNames

String[] getAttributeNames(String elementName)

返回一个 String 数组，该数组列出了与指定元素关联的属性的名称。

参数：

elementName - 要查询的元素的名称。

返回：

String 数组。

抛出：

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)

返回一个 String 数组，其包含指定元素中给定属性的合法枚举值。只应在 getAttributeValueType 返回 VALUE_ENUMERATION的情况下调用此方法。

参数：

elementName - 要查询的元素的名称。

attrName - 要查询的属性的名称。

返回：

String 数组。

抛出：

IllegalArgumentException - 如果 elementName 为 null 或者不是此格式的合法元素名称。

IllegalArgumentException - 如果 attrName 为 null 或者不是此元素的合法属性名称。

IllegalArgumentException - 如果没有将给定属性定义为枚举。

getAttributeMinValue

String getAttributeMinValue(String elementName,
                            String attrName)

返回属性的最小合法值。是否包括此值可由 getAttributeValueType 的值确定。该值以 String 的形式返回；其解释依赖于 getAttributeDataType 的值。只应在 getAttributeValueType 返回 VALUE_RANGE_* 的情况下调用此方法。

参数：

elementName - 要查询的元素的名称。

attrName - 要查询的属性的名称。

返回：

包含属性的最小合法值的 String。

抛出：