javax.imageio.metadata
类 IIOMetadata

java.lang.Object
  javax.imageio.metadata.IIOMetadata

public abstract class IIOMetadata
extends Object

将由表示与图像和流关联的元数据（非图像数据）的对象扩展的抽象类。插件表示使用不透明、特定于插件的对象的元数据。但是这些对象提供以 IIOMetadataNode 对象的树的形式访问其内部信息的能力，IIOMetadataNode 对象支持 XML DOM 接口以及用于存储非文本数据和检索关于合法数据值的信息的其他接口。这种树的格式是依赖于插件的，但插件可以选择支持下述插件无关的格式。单个插件可能支持多个元数据格式，这些格式的名称可以通过调用 getMetadataFormatNames 确定。插件还可支持单个特殊格式（叫做“本机”格式），设计用于无损耗地编码其元数据。通常，此格式专门设计用于与特定文件格式一起使用，以便以同一种格式加载和保存图像而不丢失元数据，但是对于在不同图像格式的 ImageReader 和 ImageWriter 之间传输元数据没有多大用途。要像图像文件格式所允许的那样无损耗地在两个本机格式之间转换元数据，必须使用 ImageTranscoder 对象。

另请参见：

ImageReader.getImageMetadata(int), ImageReader.getStreamMetadata(), ImageReader.readAll(int, javax.imageio.ImageReadParam), ImageWriter.getDefaultStreamMetadata(javax.imageio.ImageWriteParam), ImageWriter.getDefaultImageMetadata(javax.imageio.ImageTypeSpecifier, javax.imageio.ImageWriteParam), ImageWriter.write(javax.imageio.metadata.IIOMetadata, javax.imageio.IIOImage, javax.imageio.ImageWriteParam), ImageWriter.convertImageMetadata(javax.imageio.metadata.IIOMetadata, javax.imageio.ImageTypeSpecifier, javax.imageio.ImageWriteParam), ImageWriter.convertStreamMetadata(javax.imageio.metadata.IIOMetadata, javax.imageio.ImageWriteParam), IIOImage, ImageTranscoder

字段摘要

protected IIOMetadataController	controller 调用 activateController 方法时，将用来为此 IIOMetadataController 对象提供设置值的 IIOParamController。
protected IIOMetadataController	defaultController 建议用作此 IIOMetadata 对象的控制器的 IIOMetadataController。
protected String[]	extraMetadataFormatClassNames 实现 IIOMetadataFormat 和表示此插件支持的元数据格式（标准格式和本机格式除外）的类的名称所组成的数组，初始化为 null，通过构造方法设置。
protected String[]	extraMetadataFormatNames 此插件支持的格式（标准格式和本机格式除外）的名称所组成的数组，初始化为 null，通过构造方法设置。
protected String	nativeMetadataFormatClassName 实现 IIOMetadataFormat 和表示本机元数据格式的类的名称，初始化为 null，通过构造方法设置。
protected String	nativeMetadataFormatName 此对象本机元数据格式的名称，初始化为 null，通过构造方法设置。
protected boolean	standardFormatSupported 指示具体子类是否支持标准元数据格式的 boolean 值，通过构造方法设置。

构造方法摘要

protected	IIOMetadata() 构造一个空的 IIOMetadata 对象。
protected	IIOMetadata(boolean standardMetadataFormatSupported, String nativeMetadataFormatName, String nativeMetadataFormatClassName, String[] extraMetadataFormatNames, String[] extraMetadataFormatClassNames) 构造一个 IIOMetadata 对象，使其带有给定格式名称和格式类名称，以及指示是否支持标准格式的 boolean 值。

方法摘要

boolean	activateController() 激活为此 IIOMetadata 对象安装的 IIOMetadataController，并返回所得到的值。
abstract Node	getAsTree(String formatName) 返回 XML DOM Node 对象，该对象表示此对象所包含的元数据树的根（根据给定元数据格式定义的约定）。
IIOMetadataController	getController() 返回当前已安装的所有 IIOMetadataController。
IIOMetadataController	getDefaultController() 返回默认 IIOMetadataController（如果有），不考虑当前安装的控制器。
String[]	getExtraMetadataFormatNames() 返回一个 String 数组，包含此插件的 getAsTree、setFromTree 和 mergeTree 方法可识别的其他元数据格式（本机格式和标准格式除外）的名称。
IIOMetadataFormat	getMetadataFormat(String formatName) 返回描述给定元数据格式的 IIOMetadataFormat 对象，如果没有可用的描述，则返回 null。
String[]	getMetadataFormatNames() 返回一个 String 数组，包含包括此插件的 getAsTree、setFromTree 和 mergeTree 方法可识别的所有元数据格式（包括本机格式和标准格式）的名称。
String	getNativeMetadataFormatName() 返回此插件的“本机”元数据格式的名称，该格式通常允许无损失地编码和传输以此插件处理的格式存储的元数据。
protected IIOMetadataNode	getStandardChromaNode() 返回表示标准 javax_imageio_1.0 元数据格式的色度信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。
protected IIOMetadataNode	getStandardCompressionNode() 返回表示标准 javax_imageio_1.0 元数据格式的压缩信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。
protected IIOMetadataNode	getStandardDataNode() 返回表示标准 javax_imageio_1.0 元数据格式的数据格式信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。
protected IIOMetadataNode	getStandardDimensionNode() 返回表示标准 javax_imageio_1.0 元数据格式的维度信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。
protected IIOMetadataNode	getStandardDocumentNode() 返回表示标准 javax_imageio_1.0 元数据格式的文档信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。
protected IIOMetadataNode	getStandardTextNode() 返回表示标准 javax_imageio_1.0 元数据格式的文本信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。
protected IIOMetadataNode	getStandardTileNode() 返回表示标准 javax_imageio_1.0 元数据格式的平铺信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。
protected IIOMetadataNode	getStandardTransparencyNode() 返回表示标准 javax_imageio_1.0 元数据格式的透明度信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。
protected IIOMetadataNode	getStandardTree() 返回表示此对象中所包含元数据的 IIOMetadataNode 的树（根据标准 javax_imageio_1.0 元数据格式的约定）的实用方法。
boolean	hasController() 如果存在为此 IIOMetadata 对象安装的控制器，则返回 true。
abstract boolean	isReadOnly() 如果此对象不支持 mergeTree、setFromTree 和 reset 方法，则返回 true。
boolean	isStandardMetadataFormatSupported() 如果 getMetadataFormat、getAsTree、setFromTree 和 mergeTree 支持标准元数据格式，则返回 true。
abstract void	mergeTree(String formatName, Node root) 根据 XML DOM Node 树（其语法由给定元数据格式定义）改变此 IIOMetadata 对象的内部状态。
abstract void	reset() 将此对象中存储的所有数据重置为默认值，通常为此对象构造后立即处于的状态，尽管精确的语义是特定于插件的。
void	setController(IIOMetadataController controller) 设置在调用 activateController 方法时用来为此 IIOParam 对象提供设置值的 IIOMetadataController，重写任何默认控制器。
void	setFromTree(String formatName, Node root) 根据 XML DOM Node 的树（其语法由给定元数据格式定义）设置此 IIOMetadata 对象的内部状态。

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

字段详细信息

standardFormatSupported

protected boolean standardFormatSupported

指示具体子类是否支持标准元数据格式的 boolean 值，通过构造方法设置。

nativeMetadataFormatName

protected String nativeMetadataFormatName

此对象本机元数据格式的名称，初始化为 null，通过构造方法设置。

nativeMetadataFormatClassName

protected String nativeMetadataFormatClassName

实现 IIOMetadataFormat 和表示本机元数据格式的类的名称，初始化为 null，通过构造方法设置。

extraMetadataFormatNames

protected String[] extraMetadataFormatNames

此插件支持的格式（标准格式和本机格式除外）的名称所组成的数组，初始化为 null，通过构造方法设置。

extraMetadataFormatClassNames

protected String[] extraMetadataFormatClassNames

实现 IIOMetadataFormat 和表示此插件支持的元数据格式（标准格式和本机格式除外）的类的名称所组成的数组，初始化为 null，通过构造方法设置。

defaultController

protected IIOMetadataController defaultController

建议用作此 IIOMetadata 对象的控制器的 IIOMetadataController。它可以通过 getDefaultController 检索。要安装默认控制器，请调用 setController(getDefaultController())。此实例变量应该由子类设置，这些子类可以选择提供自己的默认控制器（通常是一个 GUI）来设置参数。

另请参见：

IIOMetadataController, getDefaultController()

controller

protected IIOMetadataController controller

调用 activateController 方法时，将用来为此 IIOMetadataController 对象提供设置值的 IIOParamController。此值重写任何默认控制器，即使为 null 时也是如此。

另请参见：

IIOMetadataController, setController(IIOMetadataController), hasController(), activateController()

构造方法详细信息

IIOMetadata

protected IIOMetadata()

构造一个空的 IIOMetadata 对象。子类负责为所有受保护的实例变量提供值，这将使方法的未重写默认实现符合其协定。例如，extraMetadataFormatNames 的长度不应为 0。

IIOMetadata

protected IIOMetadata(boolean standardMetadataFormatSupported,
                      String nativeMetadataFormatName,
                      String nativeMetadataFormatClassName,
                      String[] extraMetadataFormatNames,
                      String[] extraMetadataFormatClassNames)

构造一个 IIOMetadata 对象，使其带有给定格式名称和格式类名称，以及指示是否支持标准格式的 boolean 值。

此构造方法不会试图检查类名称的有效性。无效的类名称在后续调用 getMetadataFormat 时可能导致异常。

参数：

standardMetadataFormatSupported - 如果此对象可返回或接受使用标准元数据格式的 DOM 树，则该参数为 true。

nativeMetadataFormatName - String 形式的本机元数据格式的名称；如果不存在本机格式，则为 null。

nativeMetadataFormatClassName - 本机元数据格式的类名称；如果不存在本机格式，则为 null。

extraMetadataFormatNames - 指示此对象所支持的其他格式的 String 数组；如果不支持任何其他格式，则为 null。

extraMetadataFormatClassNames - 指示此对象所支持的所有其他格式的类名称的 String 数组；如果不支持任何其他格式，则为 null。

抛出：

IllegalArgumentException - 如果 extraMetadataFormatNames 的长度为 0。

IllegalArgumentException - 如果 extraMetadataFormatNames 和 extraMetadataFormatClassNames 既不同时为 null 也不具有相同长度。

方法详细信息

isStandardMetadataFormatSupported

public boolean isStandardMetadataFormatSupported()

如果 getMetadataFormat、getAsTree、setFromTree 和 mergeTree 支持标准元数据格式，则返回 true。

默认的实现返回 standardFormatSupported 实例变量的值。

返回：

如果支持标准元数据格式，则返回 true。

另请参见：

getAsTree(java.lang.String), setFromTree(java.lang.String, org.w3c.dom.Node), mergeTree(java.lang.String, org.w3c.dom.Node), getMetadataFormat(java.lang.String)

isReadOnly

public abstract boolean isReadOnly()

如果此对象不支持 mergeTree、setFromTree 和 reset 方法，则返回 true。

返回：

如果无法修改此 IIOMetadata 对象，则返回 true。

getNativeMetadataFormatName

public String getNativeMetadataFormatName()

返回此插件的“本机”元数据格式的名称，该格式通常允许无损失地编码和传输以此插件处理的格式存储的元数据。如果不支持这种格式，则将返回 null。

创建此 IIOMetadata 对象的插件定义“本机”元数据格式的结构和内容。用于简单格式的插件通常先为根创建一个虚拟节点，然后再创建一系列表示个别标记、存储块和关键字/值对的子节点。插件可以选择是否记录其本机格式。

默认的实现返回 nativeMetadataFormatName 实例变量的值。

返回：

本机格式的名称；或 null。

另请参见：

getExtraMetadataFormatNames(), getMetadataFormatNames()

getExtraMetadataFormatNames

public String[] getExtraMetadataFormatNames()

返回一个 String 数组，包含此插件的 getAsTree、setFromTree 和 mergeTree 方法可识别的其他元数据格式（本机格式和标准格式除外）的名称。如果不存在这样的其他格式，则返回 null。

默认实现返回 extraMetadataFormatNames 实例变量的副本。

返回：

长度至少为 1 的 String 数组；或 null。

另请参见：

getAsTree(java.lang.String), setFromTree(java.lang.String, org.w3c.dom.Node), mergeTree(java.lang.String, org.w3c.dom.Node), getNativeMetadataFormatName(), getMetadataFormatNames()

getMetadataFormatNames

public String[] getMetadataFormatNames()

返回一个 String 数组，包含包括此插件的 getAsTree、setFromTree 和 mergeTree 方法可识别的所有元数据格式（包括本机格式和标准格式）的名称。如果不存在这样的格式，则返回 null。

默认实现调用 getNativeMetadataFormatName、isStandardMetadataFormatSupported 和 getExtraMetadataFormatNames 并返回组合结果。

返回：

String 数组。

另请参见：

getNativeMetadataFormatName(), isStandardMetadataFormatSupported(), getExtraMetadataFormatNames()

getMetadataFormat

public IIOMetadataFormat getMetadataFormat(String formatName)

返回描述给定元数据格式的 IIOMetadataFormat 对象，如果没有可用的描述，则返回 null。提供的名称必须为 getMetadataFormatNames 返回的名称之一（即，本机格式名称、标准格式名称或 getExtraMetadataFormatNames 返回的名称之一）。

默认实现凭借全局标准元数据格式名称进行名称检查，如果支持则返回该格式。否则，它将凭借本机格式名称然后是任何其他格式名称进行检查。如果发现匹配项，则其从 nativeMetadataFormatClassName 或 extraMetadataFormatClassNames 检索相应的 IIOMetadataFormat 类的名称，并使用其 getInstance 方法构造该类的实例。

参数：

formatName - 所需的元数据格式。

返回：

IIOMetadataFormat 对象。

抛出：

IllegalArgumentException - 如果 formatName 为 null，或者不是插件可识别的名称之一。

IllegalStateException - 如果无法加载与格式名称对应的类。

getAsTree

public abstract Node getAsTree(String formatName)

返回 XML DOM Node 对象，该对象表示此对象所包含的元数据树的根（根据给定元数据格式定义的约定）。

使用 getMetadataFormatNames 方法可以查询可用元数据格式的名称。

参数：

formatName - 所需的元数据格式。

返回：

形成树的根的 XML DOM Node 对象。

抛出：

IllegalArgumentException - 如果 formatName 为 null，或者不是 getMetadataFormatNames 返回的名称之一。

另请参见：

getMetadataFormatNames(), setFromTree(java.lang.String, org.w3c.dom.Node), mergeTree(java.lang.String, org.w3c.dom.Node)

mergeTree

public abstract void mergeTree(String formatName,
                               Node root)
                        throws IIOInvalidTreeException

根据 XML DOM Node 树（其语法由给定元数据格式定义）改变此 IIOMetadata 对象的内部状态。只在存在于给定树中的节点需要时才改变以前的状态。如果树结构或内容无效，则抛出 IIOInvalidTreeException。

由于如何将一个树或子树与另一个树合并的语义完全特定于格式，因此插件设计者可以使用最适合格式的方式实现此方法，包括使用给定树的内容取代所有的现有状态。

参数：

formatName - 所需的元数据格式。

root - 形成树的根的 XML DOM Node 对象。

抛出：

IllegalStateException - 如果此对象是只读的。

IllegalArgumentException - 如果 formatName 为 null，或者不是 getMetadataFormatNames 返回的名称之一。

IllegalArgumentException - 如果 root 为 null。

IIOInvalidTreeException - 如果使用给定格式的规则无法成功地解析树。

另请参见：

getMetadataFormatNames(), getAsTree(java.lang.String), setFromTree(java.lang.String, org.w3c.dom.Node)

getStandardChromaNode

protected IIOMetadataNode getStandardChromaNode()

返回表示标准 javax_imageio_1.0 元数据格式的色度信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。此方法将由实用例行程序 getStandardTree 调用。

默认实现返回 null。

如果子类希望支持标准元数据格式，则其应该重写此方法以生成适当的子树。

返回：

IIOMetadataNode，或者 null。

另请参见：

getStandardTree()

getStandardCompressionNode

protected IIOMetadataNode getStandardCompressionNode()

返回表示标准 javax_imageio_1.0 元数据格式的压缩信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。此方法将由实用例行程序 getStandardTree 调用。

默认实现返回 null。

如果子类希望支持标准元数据格式，则其应该重写此方法以生成适当的子树。

返回：

IIOMetadataNode，或者 null。

另请参见：

getStandardTree()

getStandardDataNode

protected IIOMetadataNode getStandardDataNode()

返回表示标准 javax_imageio_1.0 元数据格式的数据格式信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。此方法将由实用例行程序 getStandardTree 调用。

默认实现返回 null。

如果子类希望支持标准元数据格式，则其应该重写此方法以生成适当的子树。

返回：

IIOMetadataNode，或者 null。

另请参见：

getStandardTree()

getStandardDimensionNode

protected IIOMetadataNode getStandardDimensionNode()

返回表示标准 javax_imageio_1.0 元数据格式的维度信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。此方法将由实用例行程序 getStandardTree 调用。

默认实现返回 null。

如果子类希望支持标准元数据格式，则其应该重写此方法以生成适当的子树。

返回：

IIOMetadataNode，或者 null。

另请参见：

getStandardTree()

getStandardDocumentNode

protected IIOMetadataNode getStandardDocumentNode()

返回表示标准 javax_imageio_1.0 元数据格式的文档信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。此方法将由实用例行程序 getStandardTree 调用。

默认实现返回 null。

如果子类希望支持标准元数据格式，则其应该重写此方法以生成适当的子树。

返回：

IIOMetadataNode，或者 null。

另请参见：

getStandardTree()

getStandardTextNode

protected IIOMetadataNode getStandardTextNode()

返回表示标准 javax_imageio_1.0 元数据格式的文本信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。此方法将由实用例行程序 getStandardTree 调用。

默认实现返回 null。

如果子类希望支持标准元数据格式，则其应该重写此方法以生成适当的子树。

返回：

IIOMetadataNode，或者 null。

另请参见：

getStandardTree()

getStandardTileNode

protected IIOMetadataNode getStandardTileNode()

返回表示标准 javax_imageio_1.0 元数据格式的平铺信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。此方法将由实用例行程序 getStandardTree 调用。

默认实现返回 null。

如果子类希望支持标准元数据格式，则其应该重写此方法以生成适当的子树。

返回：

IIOMetadataNode，或者 null。

另请参见：

getStandardTree()

getStandardTransparencyNode

protected IIOMetadataNode getStandardTransparencyNode()

返回表示标准 javax_imageio_1.0 元数据格式的透明度信息的 IIOMetadataNode；如果没有可用的此类信息，则返回 null。此方法将由实用例行程序 getStandardTree 调用。

默认实现返回 null。

如果子类希望支持标准元数据格式，则其应该重写此方法以生成适当的子树。

返回：

IIOMetadataNode，或者 null。

getStandardTree

protected final IIOMetadataNode getStandardTree()

返回表示此对象中所包含元数据的 IIOMetadataNode 的树（根据标准 javax_imageio_1.0 元数据格式的约定）的实用方法。

此方法调用各种 getStandard*Node 方法提供每个以根节点的子节点为根的子树。如果这些方法中任意一个返回 null，则省略相应的子树。如果它们都返回 null，则返回由单个树节点组成的树。

返回：

表示 javax_imageio_1.0 格式的元数据树的根的 IIOMetadataNode。

另请参见：

getStandardChromaNode(), getStandardCompressionNode(), getStandardDataNode(), getStandardDimensionNode(), getStandardDocumentNode(), getStandardTextNode(), getStandardTileNode(), getStandardTransparencyNode()

setFromTree

public void setFromTree(String formatName,
                        Node root)
                 throws IIOInvalidTreeException

根据 XML DOM Node 的树（其语法由给定元数据格式定义）设置此 IIOMetadata 对象的内部状态。丢弃以前的状态。如果树结构或内容无效，则抛出 IIOInvalidTreeException。

默认实现先调用 reset，然后调用 mergeTree(formatName, root)。

参数：

formatName - 所需的元数据格式。

root - 形成树的根的 XML DOM Node 对象。

抛出：

IllegalStateException - 如果此对象是只读的。

IllegalArgumentException - 如果 formatName 为 null，或者不是 getMetadataFormatNames 返回的名称之一。

IllegalArgumentException - 如果 root 为 null。

IIOInvalidTreeException - 如果使用给定格式的规则无法成功地解析树。

另请参见：

getMetadataFormatNames(), getAsTree(java.lang.String), mergeTree(java.lang.String, org.w3c.dom.Node)

reset

public abstract void reset()

将此对象中存储的所有数据重置为默认值，通常为此对象构造后立即处于的状态，尽管精确的语义是特定于插件的。注意，因创建对象的方式不同而存在多种可能的默认值。

抛出：

IllegalStateException - 如果此对象是只读的。

另请参见：

ImageReader.getStreamMetadata(), ImageReader.getImageMetadata(int), ImageWriter.getDefaultStreamMetadata(javax.imageio.ImageWriteParam), ImageWriter.getDefaultImageMetadata(javax.imageio.ImageTypeSpecifier, javax.imageio.ImageWriteParam)

setController

public void setController(IIOMetadataController controller)

设置在调用 activateController 方法时用来为此 IIOParam 对象提供设置值的 IIOMetadataController，重写任何默认控制器。如果该参数为 null，则不使用任何控制器，包括所有默认控制器。要恢复默认值，请使用 setController(getDefaultController())。

默认实现将 controller 实例变量设置为提供的值。

参数：

controller - 一个适当的 IIOMetadataController，或者为 null。

另请参见：

IIOMetadataController, getController(), getDefaultController(), hasController(), activateController()

getController

public IIOMetadataController getController()

返回当前已安装的所有 IIOMetadataController。返回值可以是默认控制器（如果有）、null 或最近一次调用 setController 时使用的参数。

默认的实现返回 controller 实例变量的值。

返回：

当前安装的 IIOMetadataController；或者 null。

另请参见：

IIOMetadataController, setController(javax.imageio.metadata.IIOMetadataController), getDefaultController(), hasController(), activateController()

getDefaultController

public IIOMetadataController getDefaultController()

返回默认 IIOMetadataController（如果有），不考虑当前安装的控制器。如果没有默认安装器，则返回 null。

默认的实现返回 defaultController 实例变量的值。

返回：

默认 IIOMetadataController 或 null。

另请参见：

IIOMetadataController, setController(IIOMetadataController), getController(), hasController(), activateController()

hasController

public boolean hasController()

如果存在为此 IIOMetadata 对象安装的控制器，则返回 true。

如果 getController 方法返回非 null 值，则默认实现返回 true。

返回：

如果安装了一个控制器，则返回 true。

另请参见：

IIOMetadataController, setController(IIOMetadataController), getController(), getDefaultController(), activateController()

activateController

public boolean activateController()

激活为此 IIOMetadata 对象安装的 IIOMetadataController，并返回所得到的值。当此方法返回 true 时，此 IIOMetadata 对象的所有值都已准备好进行下一次读取或写入操作。如果返回 false，则此对象中没有任何设置会被干扰（也就是说，用户取消了该操作）。

通常，控制器将是一个 GUI，为特定插件的 IIOMetadata 的子类提供用户界面。不过，控制器不必一定是 GUI。

默认实现调用 getController，如果 hasController 返回 true，则对返回对象调用 activate。

返回：

如果控制器完全正常，则返回 true。

抛出：

IllegalStateException - 如果当前没有安装控制器。

另请参见：

IIOMetadataController, setController(IIOMetadataController), getController(), getDefaultController(), hasController()