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

public abstract Class IIOMetadata

extends Object
Class Inheritance
Known Direct Subclasses
com.sun.imageio.plugins.bmp.BMPMetadata, com.sun.imageio.plugins.gif.GIFMetadata, com.sun.imageio.plugins.jpeg.JPEGMetadata, com.sun.imageio.plugins.png.PNGMetadata, com.sun.imageio.plugins.tiff.TIFFImageMetadata, com.sun.imageio.plugins.tiff.TIFFStreamMetadata, com.sun.imageio.plugins.wbmp.WBMPMetadata
Imports
org.w3c.dom.Node, java.lang.reflect.Method
An abstract class to be extended by objects that represent metadata (non-image data) associated with images and streams. Plug-ins represent metadata using opaque, plug-in specific objects. These objects, however, provide the ability to access their internal information as a tree of IIOMetadataNode objects that support the XML DOM interfaces as well as additional interfaces for storing non-textual data and retrieving information about legal data values. The format of such trees is plug-in dependent, but plug-ins may choose to support a plug-in neutral format described below. A single plug-in may support multiple metadata formats, whose names maybe determined by calling getMetadataFormatNames. The plug-in may also support a single special format, referred to as the "native" format, which is designed to encode its metadata losslessly. This format will typically be designed specifically to work with a specific file format, so that images may be loaded and saved in the same format with no loss of metadata, but may be less useful for transferring metadata between an ImageReader and an ImageWriter for different image formats. To convert between two native formats as losslessly as the image file formats will allow, an ImageTranscoder object must be used.
See Also
javax.imageio.ImageReader#getImageMetadata, javax.imageio.ImageReader#getStreamMetadata, javax.imageio.ImageReader#readAll, javax.imageio.ImageWriter#getDefaultStreamMetadata, javax.imageio.ImageWriter#getDefaultImageMetadata, javax.imageio.ImageWriter#write, javax.imageio.ImageWriter#convertImageMetadata, javax.imageio.ImageWriter#convertStreamMetadata, javax.imageio.IIOImage, javax.imageio.ImageTranscoder

Field Summary

Modifier and TypeField and Description
protected IIOMetadataController
controller

The IIOMetadataController that will be used to provide settings for this IIOMetadata object when the activateController method is called.

protected IIOMetadataController
defaultController

An IIOMetadataController that is suggested for use as the controller for this IIOMetadata object.

protected String[]
extraMetadataFormatClassNames

An array of names of classes implementing IIOMetadataFormat and representing the metadata formats, other than the standard and native formats, that are supported by this plug-in, initialized to null and set via the constructor.

protected String[]
extraMetadataFormatNames

An array of names of formats, other than the standard and native formats, that are supported by this plug-in, initialized to null and set via the constructor.

protected String
nativeMetadataFormatClassName

The name of the class implementing IIOMetadataFormat and representing the native metadata format, initialized to null and set via the constructor.

protected String
nativeMetadataFormatName

The name of the native metadata format for this object, initialized to null and set via the constructor.

protected boolean
standardFormatSupported

A boolean indicating whether the concrete subclass supports the standard metadata format, set via the constructor.

Constructor Summary

AccessConstructor and Description
protected
IIOMetadata()

Constructs an empty IIOMetadata object.

protected
IIOMetadata(boolean
true if this object can return or accept a DOM tree using the standard metadata format.
standardMetadataFormatSupported, String
the name of the native metadata format, as a String, or null if there is no native format.
nativeMetadataFormatName, String
the name of the class of the native metadata format, or null if there is no native format.
nativeMetadataFormatClassName, String[]
an array of Strings indicating additional formats supported by this object, or null if there are none.
extraMetadataFormatNames, String[]
an array of Strings indicating the class names of any additional formats supported by this object, or null if there are none.
extraMetadataFormatClassNames)

Constructs an IIOMetadata object with the given format names and format class names, as well as a boolean indicating whether the standard format is supported.

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if the controller completed normally.
activateController()

Activates the installed IIOMetadataController for this IIOMetadata object and returns the resulting value.

private void
append(IIOMetadataNode root, IIOMetadataNode node)

Appends a new node to an existing node, if the new node is non-null.

public abstract Node

Returns:

an XML DOM Node object forming the root of a tree.
getAsTree(String
the desired metadata format.
formatName)

Returns an XML DOM Node object that represents the root of a tree of metadata contained within this object according to the conventions defined by a given metadata format.

public IIOMetadataController

Returns:

the currently installed IIOMetadataController, or null.
getController()

Returns whatever IIOMetadataController is currently installed.

public IIOMetadataController

Returns:

the default IIOMetadataController, or null.
getDefaultController()

Returns the default IIOMetadataController, if there is one, regardless of the currently installed controller.

public String[]

Returns:

an array of Strings with length at least 1, or null.
getExtraMetadataFormatNames()

Returns an array of Strings containing the names of additional metadata formats, other than the native and standard formats, recognized by this plug-in's getAsTree, setFromTree, and mergeTree methods.

public IIOMetadataFormat

Returns:

an IIOMetadataFormat object.
getMetadataFormat(String
the desired metadata format.
formatName)

Returns an IIOMetadataFormat object describing the given metadata format, or null if no description is available.

private Class<?>
getMetadataFormatClass(String formatClassName)

public String[]

Returns:

an array of Strings.
getMetadataFormatNames()

Returns an array of Strings containing the names of all metadata formats, including the native and standard formats, recognized by this plug-in's getAsTree, setFromTree, and mergeTree methods.

public String

Returns:

the name of the native format, or null.
getNativeMetadataFormatName()

Returns the name of the "native" metadata format for this plug-in, which typically allows for lossless encoding and transmission of the metadata stored in the format handled by this plug-in. If no such format is supported, null will be returned.

protected IIOMetadataNode

Returns:

an IIOMetadataNode, or null.
getStandardChromaNode()

Returns an IIOMetadataNode representing the chroma information of the standard javax_imageio_1.0 metadata format, or null if no such information is available.

protected IIOMetadataNode

Returns:

an IIOMetadataNode, or null.
getStandardCompressionNode()

Returns an IIOMetadataNode representing the compression information of the standard javax_imageio_1.0 metadata format, or null if no such information is available.

protected IIOMetadataNode

Returns:

an IIOMetadataNode, or null.
getStandardDataNode()

Returns an IIOMetadataNode representing the data format information of the standard javax_imageio_1.0 metadata format, or null if no such information is available.

protected IIOMetadataNode

Returns:

an IIOMetadataNode, or null.
getStandardDimensionNode()

Returns an IIOMetadataNode representing the dimension information of the standard javax_imageio_1.0 metadata format, or null if no such information is available.

protected IIOMetadataNode

Returns:

an IIOMetadataNode, or null.
getStandardDocumentNode()

Returns an IIOMetadataNode representing the document information of the standard javax_imageio_1.0 metadata format, or null if no such information is available.

protected IIOMetadataNode

Returns:

an IIOMetadataNode, or null.
getStandardTextNode()

Returns an IIOMetadataNode representing the textual information of the standard javax_imageio_1.0 metadata format, or null if no such information is available.

protected IIOMetadataNode

Returns:

an IIOMetadataNode, or null.
getStandardTileNode()

Returns an IIOMetadataNode representing the tiling information of the standard javax_imageio_1.0 metadata format, or null if no such information is available.

protected IIOMetadataNode

Returns:

an IIOMetadataNode, or null.
getStandardTransparencyNode()

Returns an IIOMetadataNode representing the transparency information of the standard javax_imageio_1.0 metadata format, or null if no such information is available.

protected final IIOMetadataNode

Returns:

an IIOMetadataNode representing the root of a metadata tree in the javax_imageio_1.0 format.
getStandardTree()

A utility method to return a tree of IIOMetadataNodes representing the metadata contained within this object according to the conventions of the standard javax_imageio_1.0 metadata format.

public boolean

Returns:

true if a controller is installed.
hasController()

Returns true if there is a controller installed for this IIOMetadata object.

public abstract boolean

Returns:

true if this IIOMetadata object cannot be modified.
isReadOnly()

Returns true if this object does not support the mergeTree, setFromTree, and reset methods.

public boolean

Returns:

true if the standard metadata format is supported.
isStandardMetadataFormatSupported()

Returns true if the standard metadata format is supported by getMetadataFormat, getAsTree, setFromTree, and mergeTree.

public abstract void
mergeTree(String
the desired metadata format.
formatName, Node
an XML DOM Node object forming the root of a tree.
root)

Alters the internal state of this IIOMetadata object from a tree of XML DOM Nodes whose syntax is defined by the given metadata format.

public abstract void
reset()

Resets all the data stored in this object to default values, usually to the state this object was in immediately after construction, though the precise semantics are plug-in specific.

public void
setController(IIOMetadataController
An appropriate IIOMetadataController, or null.
controller)

Sets the IIOMetadataController to be used to provide settings for this IIOMetadata object when the activateController method is called, overriding any default controller.

public void
setFromTree(String
the desired metadata format.
formatName, Node
an XML DOM Node object forming the root of a tree.
root)

Sets the internal state of this IIOMetadata object from a tree of XML DOM Nodes whose syntax is defined by the given metadata format.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

controllerback to summary
protected IIOMetadataController controller

The IIOMetadataController that will be used to provide settings for this IIOMetadata object when the activateController method is called. This value overrides any default controller, even when null.

See Also
IIOMetadataController, setController(IIOMetadataController), hasController(), activateController()
defaultControllerback to summary
protected IIOMetadataController defaultController

An IIOMetadataController that is suggested for use as the controller for this IIOMetadata object. It may be retrieved via getDefaultController. To install the default controller, call setController(getDefaultController()). This instance variable should be set by subclasses that choose to provide their own default controller, usually a GUI, for setting parameters.

See Also
IIOMetadataController, getDefaultController
extraMetadataFormatClassNamesback to summary
protected String[] extraMetadataFormatClassNames

An array of names of classes implementing IIOMetadataFormat and representing the metadata formats, other than the standard and native formats, that are supported by this plug-in, initialized to null and set via the constructor.

extraMetadataFormatNamesback to summary
protected String[] extraMetadataFormatNames

An array of names of formats, other than the standard and native formats, that are supported by this plug-in, initialized to null and set via the constructor.

nativeMetadataFormatClassNameback to summary
protected String nativeMetadataFormatClassName

The name of the class implementing IIOMetadataFormat and representing the native metadata format, initialized to null and set via the constructor.

nativeMetadataFormatNameback to summary
protected String nativeMetadataFormatName

The name of the native metadata format for this object, initialized to null and set via the constructor.

standardFormatSupportedback to summary
protected boolean standardFormatSupported

A boolean indicating whether the concrete subclass supports the standard metadata format, set via the constructor.

Constructor Detail

IIOMetadataback to summary
protected IIOMetadata()

Constructs an empty IIOMetadata object. The subclass is responsible for supplying values for all protected instance variables that will allow any non-overridden default implementations of methods to satisfy their contracts. For example, extraMetadataFormatNames should not have length 0.

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

Constructs an IIOMetadata object with the given format names and format class names, as well as a boolean indicating whether the standard format is supported.

This constructor does not attempt to check the class names for validity. Invalid class names may cause exceptions in subsequent calls to getMetadataFormat.

Parameters
standardMetadataFormatSupported:boolean

true if this object can return or accept a DOM tree using the standard metadata format.

nativeMetadataFormatName:String

the name of the native metadata format, as a String, or null if there is no native format.

nativeMetadataFormatClassName:String

the name of the class of the native metadata format, or null if there is no native format.

extraMetadataFormatNames:String[]

an array of Strings indicating additional formats supported by this object, or null if there are none.

extraMetadataFormatClassNames:String[]

an array of Strings indicating the class names of any additional formats supported by this object, or null if there are none.

Exceptions
IllegalArgumentException:
  • if extraMetadataFormatNames has length 0.
  • if extraMetadataFormatNames and extraMetadataFormatClassNames are neither both null, nor of the same length.

Method Detail

activateControllerback to summary
public boolean activateController()

Activates the installed IIOMetadataController for this IIOMetadata object and returns the resulting value. When this method returns true, all values for this IIOMetadata object will be ready for the next write operation. If false is returned, no settings in this object will have been disturbed (i.e., the user canceled the operation).

Ordinarily, the controller will be a GUI providing a user interface for a subclass of IIOMetadata for a particular plug-in. Controllers need not be GUIs, however.

The default implementation calls getController and the calls activate on the returned object if hasController returns true.

Returns:boolean

true if the controller completed normally.

Exceptions
IllegalStateException:
if there is no controller currently installed.
See Also
IIOMetadataController, setController(IIOMetadataController), getController, getDefaultController, hasController
appendback to summary
private void append(IIOMetadataNode root, IIOMetadataNode node)

Appends a new node to an existing node, if the new node is non-null.

getAsTreeback to summary
public abstract Node getAsTree(String formatName)

Returns an XML DOM Node object that represents the root of a tree of metadata contained within this object according to the conventions defined by a given metadata format.

The names of the available metadata formats may be queried using the getMetadataFormatNames method.

Parameters
formatName:String

the desired metadata format.

Returns:Node

an XML DOM Node object forming the root of a tree.

Exceptions
IllegalArgumentException:
if formatName is null or is not one of the names returned by getMetadataFormatNames.
See Also
getMetadataFormatNames, setFromTree, mergeTree
getControllerback to summary
public IIOMetadataController getController()

Returns whatever IIOMetadataController is currently installed. This could be the default if there is one, null, or the argument of the most recent call to setController.

The default implementation returns the value of the controller instance variable.

Returns:IIOMetadataController

the currently installed IIOMetadataController, or null.

See Also
IIOMetadataController, setController, getDefaultController, hasController, activateController()
getDefaultControllerback to summary
public IIOMetadataController getDefaultController()

Returns the default IIOMetadataController, if there is one, regardless of the currently installed controller. If there is no default controller, returns null.

The default implementation returns the value of the defaultController instance variable.

Returns:IIOMetadataController

the default IIOMetadataController, or null.

See Also
IIOMetadataController, setController(IIOMetadataController), getController, hasController, activateController()
getExtraMetadataFormatNamesback to summary
public String[] getExtraMetadataFormatNames()

Returns an array of Strings containing the names of additional metadata formats, other than the native and standard formats, recognized by this plug-in's getAsTree, setFromTree, and mergeTree methods. If there are no such additional formats, null is returned.

The default implementation returns a clone of the extraMetadataFormatNames instance variable.

Returns:String[]

an array of Strings with length at least 1, or null.

See Also
getAsTree, setFromTree, mergeTree, getNativeMetadataFormatName, getMetadataFormatNames
getMetadataFormatback to summary
public IIOMetadataFormat getMetadataFormat(String formatName)

Returns an IIOMetadataFormat object describing the given metadata format, or null if no description is available. The supplied name must be one of those returned by getMetadataFormatNames (i.e., either the native format name, the standard format name, or one of those returned by getExtraMetadataFormatNames).

The default implementation checks the name against the global standard metadata format name, and returns that format if it is supported. Otherwise, it checks against the native format names followed by any additional format names. If a match is found, it retrieves the name of the IIOMetadataFormat class from nativeMetadataFormatClassName or extraMetadataFormatClassNames as appropriate, and constructs an instance of that class using its getInstance method.

Parameters
formatName:String

the desired metadata format.

Returns:IIOMetadataFormat

an IIOMetadataFormat object.

Exceptions
IllegalArgumentException:
if formatName is null or is not one of the names recognized by the plug-in.
IllegalStateException:
if the class corresponding to the format name cannot be loaded.
getMetadataFormatClassback to summary
private Class<?> getMetadataFormatClass(String formatClassName)
getMetadataFormatNamesback to summary
public String[] getMetadataFormatNames()

Returns an array of Strings containing the names of all metadata formats, including the native and standard formats, recognized by this plug-in's getAsTree, setFromTree, and mergeTree methods. If there are no such formats, null is returned.

The default implementation calls getNativeMetadataFormatName, isStandardMetadataFormatSupported, and getExtraMetadataFormatNames and returns the combined results.

Returns:String[]

an array of Strings.

See Also
getNativeMetadataFormatName, isStandardMetadataFormatSupported, getExtraMetadataFormatNames
getNativeMetadataFormatNameback to summary
public String getNativeMetadataFormatName()

Returns the name of the "native" metadata format for this plug-in, which typically allows for lossless encoding and transmission of the metadata stored in the format handled by this plug-in. If no such format is supported, null will be returned.

The structure and contents of the "native" metadata format are defined by the plug-in that created this IIOMetadata object. Plug-ins for simple formats will usually create a dummy node for the root, and then a series of child nodes representing individual tags, chunks, or keyword/value pairs. A plug-in may choose whether or not to document its native format.

The default implementation returns the value of the nativeMetadataFormatName instance variable.

Returns:String

the name of the native format, or null.

See Also
getExtraMetadataFormatNames, getMetadataFormatNames
getStandardChromaNodeback to summary
protected IIOMetadataNode getStandardChromaNode()

Returns an IIOMetadataNode representing the chroma information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. This method is intended to be called by the utility routine getStandardTree.

The default implementation returns null.

Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.

Returns:IIOMetadataNode

an IIOMetadataNode, or null.

See Also
getStandardTree
getStandardCompressionNodeback to summary
protected IIOMetadataNode getStandardCompressionNode()

Returns an IIOMetadataNode representing the compression information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. This method is intended to be called by the utility routine getStandardTree.

The default implementation returns null.

Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.

Returns:IIOMetadataNode

an IIOMetadataNode, or null.

See Also
getStandardTree
getStandardDataNodeback to summary
protected IIOMetadataNode getStandardDataNode()

Returns an IIOMetadataNode representing the data format information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. This method is intended to be called by the utility routine getStandardTree.

The default implementation returns null.

Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.

Returns:IIOMetadataNode

an IIOMetadataNode, or null.

See Also
getStandardTree
getStandardDimensionNodeback to summary
protected IIOMetadataNode getStandardDimensionNode()

Returns an IIOMetadataNode representing the dimension information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. This method is intended to be called by the utility routine getStandardTree.

The default implementation returns null.

Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.

Returns:IIOMetadataNode

an IIOMetadataNode, or null.

See Also
getStandardTree
getStandardDocumentNodeback to summary
protected IIOMetadataNode getStandardDocumentNode()

Returns an IIOMetadataNode representing the document information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. This method is intended to be called by the utility routine getStandardTree.

The default implementation returns null.

Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.

Returns:IIOMetadataNode

an IIOMetadataNode, or null.

See Also
getStandardTree
getStandardTextNodeback to summary
protected IIOMetadataNode getStandardTextNode()

Returns an IIOMetadataNode representing the textual information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. This method is intended to be called by the utility routine getStandardTree.

The default implementation returns null.

Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.

Returns:IIOMetadataNode

an IIOMetadataNode, or null.

See Also
getStandardTree
getStandardTileNodeback to summary
protected IIOMetadataNode getStandardTileNode()

Returns an IIOMetadataNode representing the tiling information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. This method is intended to be called by the utility routine getStandardTree.

The default implementation returns null.

Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.

Returns:IIOMetadataNode

an IIOMetadataNode, or null.

See Also
getStandardTree
getStandardTransparencyNodeback to summary
protected IIOMetadataNode getStandardTransparencyNode()

Returns an IIOMetadataNode representing the transparency information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. This method is intended to be called by the utility routine getStandardTree.

The default implementation returns null.

Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.

Returns:IIOMetadataNode

an IIOMetadataNode, or null.

getStandardTreeback to summary
protected final IIOMetadataNode getStandardTree()

A utility method to return a tree of IIOMetadataNodes representing the metadata contained within this object according to the conventions of the standard javax_imageio_1.0 metadata format.

This method calls the various getStandard*Node methods to supply each of the subtrees rooted at the children of the root node. If any of those methods returns null, the corresponding subtree will be omitted. If all of them return null, a tree consisting of a single root node will be returned.

Returns:IIOMetadataNode

an IIOMetadataNode representing the root of a metadata tree in the javax_imageio_1.0 format.

See Also
getStandardChromaNode, getStandardCompressionNode, getStandardDataNode, getStandardDimensionNode, getStandardDocumentNode, getStandardTextNode, getStandardTileNode, getStandardTransparencyNode
hasControllerback to summary
public boolean hasController()

Returns true if there is a controller installed for this IIOMetadata object.

The default implementation returns true if the getController method returns a non-null value.

Returns:boolean

true if a controller is installed.

See Also
IIOMetadataController, setController(IIOMetadataController), getController, getDefaultController, activateController()
isReadOnlyback to summary
public abstract boolean isReadOnly()

Returns true if this object does not support the mergeTree, setFromTree, and reset methods.

Returns:boolean

true if this IIOMetadata object cannot be modified.

isStandardMetadataFormatSupportedback to summary
public boolean isStandardMetadataFormatSupported()

Returns true if the standard metadata format is supported by getMetadataFormat, getAsTree, setFromTree, and mergeTree.

The default implementation returns the value of the standardFormatSupported instance variable.

Returns:boolean

true if the standard metadata format is supported.

See Also
getAsTree, setFromTree, mergeTree, getMetadataFormat
mergeTreeback to summary
public abstract void mergeTree(String formatName, Node root) throws IIOInvalidTreeException

Alters the internal state of this IIOMetadata object from a tree of XML DOM Nodes whose syntax is defined by the given metadata format. The previous state is altered only as necessary to accommodate the nodes that are present in the given tree. If the tree structure or contents are invalid, an IIOInvalidTreeException will be thrown.

As the semantics of how a tree or subtree may be merged with another tree are completely format-specific, plug-in authors may implement this method in whatever manner is most appropriate for the format, including simply replacing all existing state with the contents of the given tree.

Parameters
formatName:String

the desired metadata format.

root:Node

an XML DOM Node object forming the root of a tree.

Exceptions
IIOInvalidTreeException:
if the tree cannot be parsed successfully using the rules of the given format.
IllegalStateException:
if this object is read-only.
IllegalArgumentException:
  • if formatName is null or is not one of the names returned by getMetadataFormatNames.
  • if root is null.
See Also
getMetadataFormatNames, getAsTree, setFromTree
resetback to summary
public abstract void reset()

Resets all the data stored in this object to default values, usually to the state this object was in immediately after construction, though the precise semantics are plug-in specific. Note that there are many possible default values, depending on how the object was created.

Exceptions
IllegalStateException:
if this object is read-only.
See Also
javax.imageio.ImageReader#getStreamMetadata, javax.imageio.ImageReader#getImageMetadata, javax.imageio.ImageWriter#getDefaultStreamMetadata, javax.imageio.ImageWriter#getDefaultImageMetadata
setControllerback to summary
public void setController(IIOMetadataController controller)

Sets the IIOMetadataController to be used to provide settings for this IIOMetadata object when the activateController method is called, overriding any default controller. If the argument is null, no controller will be used, including any default. To restore the default, use setController(getDefaultController()).

The default implementation sets the controller instance variable to the supplied value.

Parameters
controller:IIOMetadataController

An appropriate IIOMetadataController, or null.

See Also
IIOMetadataController, getController, getDefaultController, hasController, activateController()
setFromTreeback to summary
public void setFromTree(String formatName, Node root) throws IIOInvalidTreeException

Sets the internal state of this IIOMetadata object from a tree of XML DOM Nodes whose syntax is defined by the given metadata format. The previous state is discarded. If the tree's structure or contents are invalid, an IIOInvalidTreeException will be thrown.

The default implementation calls reset followed by mergeTree(formatName, root).

Parameters
formatName:String

the desired metadata format.

root:Node

an XML DOM Node object forming the root of a tree.

Exceptions
IIOInvalidTreeException:
if the tree cannot be parsed successfully using the rules of the given format.
IllegalStateException:
if this object is read-only.
IllegalArgumentException:
  • if formatName is null or is not one of the names returned by getMetadataFormatNames.
  • if root is null.
See Also
getMetadataFormatNames, getAsTree, mergeTree