模块 java.desktop
包 javax.imageio.metadata

类 IIOMetadata

java.lang.Object
javax.imageio.metadata.IIOMetadata
public abstract class IIOMetadata extends Object
一个抽象类，由表示与图像和流关联的元数据（非图像数据）的对象扩展。插件使用不透明的插件特定对象表示元数据。然而，这些对象提供了访问其内部信息的能力，作为支持 XML DOM 接口的 IIOMetadataNode 对象树以及用于存储非文本数据和检索有关合法数据值的信息的附加接口。这种树的格式依赖于插件，但插件可以选择支持下面描述的插件中性格式。单个插件可能支持多种元数据格式，其名称可能通过调用 getMetadataFormatNames 来确定。该插件还可以支持一种称为“本机”格式的特殊格式，该格式旨在对其元数据进行无损编码。这种格式通常专门设计用于特定的文件格式，因此图像可以以相同的格式加载和保存而不会丢失元数据，但对于在 ImageReader 和 ImageWriter 之间传输不同图像的元数据可能不太有用格式。要在图像文件格式允许的情况下尽可能无损地在两种本机格式之间进行转换，必须使用 ImageTranscoder 对象。
参见：

  • 字段摘要

    字段
    修饰符和类型
    Field
    描述
    protected IIOMetadataController
    controller
    当调用 activateController 方法时，将用于为此 IIOMetadata 对象提供设置的 IIOMetadataController。
    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()
    返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的色度信息，如果没有此类信息可用，则返回 null。
    protected IIOMetadataNode
    getStandardCompressionNode()
    返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的压缩信息，如果没有此类信息可用，则返回 null。
    protected IIOMetadataNode
    getStandardDataNode()
    返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的数据格式信息，如果没有此类信息可用，则返回 null。
    protected IIOMetadataNode
    getStandardDimensionNode()
    返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的维度信息，如果没有此类信息可用，则返回 null。
    protected IIOMetadataNode
    getStandardDocumentNode()
    返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的文档信息，如果没有此类信息可用，则返回 null。
    protected IIOMetadataNode
    getStandardTextNode()
    返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的文本信息，如果没有此类信息可用，则返回 null。
    protected IIOMetadataNode
    getStandardTileNode()
    返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的平铺信息，如果没有此类信息可用，则返回 null。
    protected IIOMetadataNode
    getStandardTransparencyNode()
    返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的透明度信息，如果没有此类信息可用，则返回 null。
    protected final IIOMetadataNode
    getStandardTree()
    根据标准 javax_imageio_1.0 元数据格式的约定，返回表示此对象中包含的元数据的 IIOMetadataNode 树的实用方法。
    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)
    设置 IIOMetadataController 用于在调用 activateController 方法时为此 IIOMetadata 对象提供设置，覆盖任何默认控制器。
    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，用于设置参数。
      参见：

    • controller

      protected IIOMetadataController  controller
      当调用 activateController 方法时，将用于为此 IIOMetadata 对象提供设置的 IIOMetadataController。此值会覆盖任何默认控制器，即使在 null 时也是如此。
      参见：

  • 构造方法详细信息

    • IIOMetadata

      protected IIOMetadata()
      构造一个空的 IIOMetadata 对象。子类负责为所有受保护的实例变量提供值，这些变量将允许任何未覆盖的默认方法实现来满足它们的约定。例如，extraMetadataFormatNames 的长度不应为 0。

    • IIOMetadata

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

      此构造函数不会尝试检查类名的有效性。无效的类名可能会导致后续调用 getMetadataFormat 时出现异常。

      参数：
      standardMetadataFormatSupported - true 如果此对象可以返回或接受使用标准元数据格式的 DOM 树。
      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 如果支持标准元数据格式。
      参见：

    • isReadOnly

      public abstract boolean isReadOnly()
      如果此对象不支持 mergeTree、setFromTree 和 reset 方法，则返回 true。
      返回：
      如果无法修改此 IIOMetadata 对象，则为真。

    • getNativeMetadataFormatName

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

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

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

      返回：
      本机格式的名称，或 null 。
      参见：

    • getExtraMetadataFormatNames

      public String [] getExtraMetadataFormatNames()
      返回一个 String 数组，其中包含此插件的 getAsTree 、 setFromTree 和 mergeTree 方法识别的附加元数据格式的名称，而不是本机和标准格式。如果没有这样的附加格式，则返回 null。

      默认实现返回 extraMetadataFormatNames 实例变量的克隆。

      返回：
      长度至少为 1 的 String 数组，或 null 。
      参见：

    • getMetadataFormatNames

      public String [] getMetadataFormatNames()
      返回一个 String 数组，其中包含所有元数据格式的名称，包括本机格式和标准格式，可由该插件的 getAsTree 、 setFromTree 和 mergeTree 方法识别。如果没有这样的格式，则返回null。

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

      返回：
      String 的数组。
      参见：

    • getMetadataFormat

      public IIOMetadataFormat  getMetadataFormat(String  formatName)
      返回描述给定元数据格式的 IIOMetadataFormat 对象，如果没有可用描述，则返回 null。提供的名称必须是 getMetadataFormatNames (IE，本机格式名称、标准格式名称或 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 返回的名称之一。
      参见：

    • 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 - 如果使用给定格式的规则无法成功解析树。
      参见：

    • getStandardChromaNode

      protected IIOMetadataNode  getStandardChromaNode()
      返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的色度信息，如果没有此类信息可用，则返回 null。此方法旨在由实用例程 getStandardTree 调用。

      默认实现返回 null 。

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

      返回：
      一个 IIOMetadataNode 或 null 。
      参见：

    • getStandardCompressionNode

      protected IIOMetadataNode  getStandardCompressionNode()
      返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的压缩信息，如果没有此类信息可用，则返回 null。此方法旨在由实用例程 getStandardTree 调用。

      默认实现返回 null 。

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

      返回：
      一个 IIOMetadataNode 或 null 。
      参见：

    • getStandardDataNode

      protected IIOMetadataNode  getStandardDataNode()
      返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的数据格式信息，如果没有此类信息可用，则返回 null。此方法旨在由实用例程 getStandardTree 调用。

      默认实现返回 null 。

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

      返回：
      一个 IIOMetadataNode 或 null 。
      参见：

    • getStandardDimensionNode

      protected IIOMetadataNode  getStandardDimensionNode()
      返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的维度信息，如果没有此类信息可用，则返回 null。此方法旨在由实用例程 getStandardTree 调用。

      默认实现返回 null 。

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

      返回：
      一个 IIOMetadataNode 或 null 。
      参见：

    • getStandardDocumentNode

      protected IIOMetadataNode  getStandardDocumentNode()
      返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的文档信息，如果没有此类信息可用，则返回 null。此方法旨在由实用例程 getStandardTree 调用。

      默认实现返回 null 。

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

      返回：
      一个 IIOMetadataNode 或 null 。
      参见：

    • getStandardTextNode

      protected IIOMetadataNode  getStandardTextNode()
      返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的文本信息，如果没有此类信息可用，则返回 null。此方法旨在由实用例程 getStandardTree 调用。

      默认实现返回 null 。

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

      返回：
      一个 IIOMetadataNode 或 null 。
      参见：

    • getStandardTileNode

      protected IIOMetadataNode  getStandardTileNode()
      返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的平铺信息，如果没有此类信息可用，则返回 null。此方法旨在由实用例程 getStandardTree 调用。

      默认实现返回 null 。

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

      返回：
      一个 IIOMetadataNode 或 null 。
      参见：

    • getStandardTransparencyNode

      protected IIOMetadataNode  getStandardTransparencyNode()
      返回一个 IIOMetadataNode 表示标准 javax_imageio_1.0 元数据格式的透明度信息，如果没有此类信息可用，则返回 null。此方法旨在由实用例程 getStandardTree 调用。

      默认实现返回 null 。

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

      返回：
      一个 IIOMetadataNode 或 null 。

    • getStandardTree

      protected final IIOMetadataNode  getStandardTree()
      根据标准 javax_imageio_1.0 元数据格式的约定，返回表示此对象中包含的元数据的 IIOMetadataNode 树的实用方法。

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

      返回：
      IIOMetadataNode 表示 javax_imageio_1.0 格式的元数据树的根。
      参见：

    • 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 - 如果使用给定格式的规则无法成功解析树。
      参见：

    • reset

      public abstract void reset()
      将此对象中存储的所有数据重置为默认值，通常重置为此对象在构造后立即处于的状态，尽管精确的语义是特定于插件的。请注意，有许多可能的默认值，具体取决于对象的创建方式。
      抛出：
      IllegalStateException - 如果此对象是只读的。
      参见：

    • setController

      public void setController(IIOMetadataController  controller)
      设置 IIOMetadataController 用于在调用 activateController 方法时为此 IIOMetadata 对象提供设置，覆盖任何默认控制器。如果参数是 null ，则不会使用任何控制器，包括任何默认值。要恢复默认值，请使用 setController(getDefaultController()) 。

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

      参数：
      controller - 一个合适的 IIOMetadataController 或 null 。
      参见：

    • getController

      public IIOMetadataController  getController()
      返回当前安装的任何 IIOMetadataController。如果有一个 null 或最近调用 setController 的参数，这可能是默认值。

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

      返回：
      当前安装的 IIOMetadataController 或 null 。
      参见：

    • getDefaultController

      public IIOMetadataController  getDefaultController()
      返回默认值 IIOMetadataController ，如果有的话，不管当前安装的控制器是什么。如果没有默认控制器，则返回 null 。

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

      返回：
      默认 IIOMetadataController 或 null 。
      参见：

    • hasController

      public boolean hasController()
      如果为此 IIOMetadata 对象安装了控制器，则返回 true。

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

      返回：
      true 如果安装了控制器。
      参见：

    • activateController

      public boolean activateController()
      为此 IIOMetadata 对象激活已安装的 IIOMetadataController 并返回结果值。当此方法返回 true 时，此 IIOMetadata 对象的所有值都将为下一次写入操作做好准备。如果返回 false，则此对象中的任何设置都不会受到干扰（IE，用户取消了操作）。

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

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

      返回：
      true 如果控制器正常完成。
      抛出：
      IllegalStateException - 如果当前没有安装控制器。
      参见：