- java.lang.Object
-
- javax.imageio.metadata.IIOMetadata
-
public abstract class IIOMetadata extends Object
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 ofIIOMetadataNodeobjects 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 callinggetMetadataFormatNames. 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 anImageReaderand anImageWriterfor different image formats. To convert between two native formats as losslessly as the image file formats will allow, anImageTranscoderobject must be used.- See Also:
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),ImageTranscoder.convertImageMetadata(javax.imageio.metadata.IIOMetadata, javax.imageio.ImageTypeSpecifier, javax.imageio.ImageWriteParam),ImageTranscoder.convertStreamMetadata(javax.imageio.metadata.IIOMetadata, javax.imageio.ImageWriteParam),IIOImage,ImageTranscoder
-
-
Field Summary
Fields Modifier and Type Field Description protected IIOMetadataControllercontrollerTheIIOMetadataControllerthat will be used to provide settings for thisIIOMetadataobject when theactivateControllermethod is called.protected IIOMetadataControllerdefaultControllerAnIIOMetadataControllerthat is suggested for use as the controller for thisIIOMetadataobject.protected String[]extraMetadataFormatClassNamesAn array of names of classes implementingIIOMetadataFormatand representing the metadata formats, other than the standard and native formats, that are supported by this plug-in, initialized tonulland set via the constructor.protected String[]extraMetadataFormatNamesAn array of names of formats, other than the standard and native formats, that are supported by this plug-in, initialized tonulland set via the constructor.protected StringnativeMetadataFormatClassNameThe name of the class implementingIIOMetadataFormatand representing the native metadata format, initialized tonulland set via the constructor.protected StringnativeMetadataFormatNameThe name of the native metadata format for this object, initialized tonulland set via the constructor.protected booleanstandardFormatSupportedA boolean indicating whether the concrete subclass supports the standard metadata format, set via the constructor.
-
Constructor Summary
Constructors Modifier Constructor Description protectedIIOMetadata()Constructs an emptyIIOMetadataobject.protectedIIOMetadata(boolean standardMetadataFormatSupported, String nativeMetadataFormatName, String nativeMetadataFormatClassName, String[] extraMetadataFormatNames, String[] extraMetadataFormatClassNames)Constructs anIIOMetadataobject with the given format names and format class names, as well as a boolean indicating whether the standard format is supported.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description booleanactivateController()Activates the installedIIOMetadataControllerfor thisIIOMetadataobject and returns the resulting value.abstract NodegetAsTree(String formatName)Returns an XML DOMNodeobject that represents the root of a tree of metadata contained within this object according to the conventions defined by a given metadata format.IIOMetadataControllergetController()Returns whateverIIOMetadataControlleris currently installed.IIOMetadataControllergetDefaultController()Returns the defaultIIOMetadataController, if there is one, regardless of the currently installed controller.String[]getExtraMetadataFormatNames()Returns an array ofStrings containing the names of additional metadata formats, other than the native and standard formats, recognized by this plug-in'sgetAsTree,setFromTree, andmergeTreemethods.IIOMetadataFormatgetMetadataFormat(String formatName)Returns anIIOMetadataFormatobject describing the given metadata format, ornullif no description is available.String[]getMetadataFormatNames()Returns an array ofStrings containing the names of all metadata formats, including the native and standard formats, recognized by this plug-in'sgetAsTree,setFromTree, andmergeTreemethods.StringgetNativeMetadataFormatName()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.protected IIOMetadataNodegetStandardChromaNode()Returns anIIOMetadataNoderepresenting the chroma information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available.protected IIOMetadataNodegetStandardCompressionNode()Returns anIIOMetadataNoderepresenting the compression information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available.protected IIOMetadataNodegetStandardDataNode()Returns anIIOMetadataNoderepresenting the data format information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available.protected IIOMetadataNodegetStandardDimensionNode()Returns anIIOMetadataNoderepresenting the dimension information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available.protected IIOMetadataNodegetStandardDocumentNode()Returns anIIOMetadataNoderepresenting the document information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available.protected IIOMetadataNodegetStandardTextNode()Returns anIIOMetadataNoderepresenting the textual information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available.protected IIOMetadataNodegetStandardTileNode()Returns anIIOMetadataNoderepresenting the tiling information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available.protected IIOMetadataNodegetStandardTransparencyNode()Returns anIIOMetadataNoderepresenting the transparency information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available.protected IIOMetadataNodegetStandardTree()A utility method to return a tree ofIIOMetadataNodes representing the metadata contained within this object according to the conventions of the standardjavax_imageio_1.0metadata format.booleanhasController()Returnstrueif there is a controller installed for thisIIOMetadataobject.abstract booleanisReadOnly()Returnstrueif this object does not support themergeTree,setFromTree, andresetmethods.booleanisStandardMetadataFormatSupported()Returnstrueif the standard metadata format is supported bygetMetadataFormat,getAsTree,setFromTree, andmergeTree.abstract voidmergeTree(String formatName, Node root)Alters the internal state of thisIIOMetadataobject from a tree of XML DOMNodes whose syntax is defined by the given metadata format.abstract voidreset()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.voidsetController(IIOMetadataController controller)Sets theIIOMetadataControllerto be used to provide settings for thisIIOMetadataobject when theactivateControllermethod is called, overriding any default controller.voidsetFromTree(String formatName, Node root)Sets the internal state of thisIIOMetadataobject from a tree of XML DOMNodes whose syntax is defined by the given metadata format.
-
-
-
Field Detail
-
standardFormatSupported
protected boolean standardFormatSupported
A boolean indicating whether the concrete subclass supports the standard metadata format, set via the constructor.
-
nativeMetadataFormatName
protected String nativeMetadataFormatName
The name of the native metadata format for this object, initialized tonulland set via the constructor.
-
nativeMetadataFormatClassName
protected String nativeMetadataFormatClassName
The name of the class implementingIIOMetadataFormatand representing the native metadata format, initialized tonulland set via the constructor.
-
extraMetadataFormatNames
protected String[] extraMetadataFormatNames
An array of names of formats, other than the standard and native formats, that are supported by this plug-in, initialized tonulland set via the constructor.
-
extraMetadataFormatClassNames
protected String[] extraMetadataFormatClassNames
An array of names of classes implementingIIOMetadataFormatand representing the metadata formats, other than the standard and native formats, that are supported by this plug-in, initialized tonulland set via the constructor.
-
defaultController
protected IIOMetadataController defaultController
AnIIOMetadataControllerthat is suggested for use as the controller for thisIIOMetadataobject. It may be retrieved viagetDefaultController. To install the default controller, callsetController(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()
-
controller
protected IIOMetadataController controller
TheIIOMetadataControllerthat will be used to provide settings for thisIIOMetadataobject when theactivateControllermethod is called. This value overrides any default controller, even whennull.
-
-
Constructor Detail
-
IIOMetadata
protected IIOMetadata()
Constructs an emptyIIOMetadataobject. 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,extraMetadataFormatNamesshould not have length 0.
-
IIOMetadata
protected IIOMetadata(boolean standardMetadataFormatSupported, String nativeMetadataFormatName, String nativeMetadataFormatClassName, String[] extraMetadataFormatNames, String[] extraMetadataFormatClassNames)Constructs anIIOMetadataobject 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-trueif this object can return or accept a DOM tree using the standard metadata format.nativeMetadataFormatName- the name of the native metadata format, as aString, ornullif there is no native format.nativeMetadataFormatClassName- the name of the class of the native metadata format, ornullif there is no native format.extraMetadataFormatNames- an array ofStrings indicating additional formats supported by this object, ornullif there are none.extraMetadataFormatClassNames- an array ofStrings indicating the class names of any additional formats supported by this object, ornullif there are none.- Throws:
IllegalArgumentException- ifextraMetadataFormatNameshas length 0.IllegalArgumentException- ifextraMetadataFormatNamesandextraMetadataFormatClassNamesare neither bothnull, nor of the same length.
-
-
Method Detail
-
isStandardMetadataFormatSupported
public boolean isStandardMetadataFormatSupported()
Returnstrueif the standard metadata format is supported bygetMetadataFormat,getAsTree,setFromTree, andmergeTree.The default implementation returns the value of the
standardFormatSupportedinstance variable.- Returns:
trueif the standard metadata format is supported.- See Also:
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()
Returnstrueif this object does not support themergeTree,setFromTree, andresetmethods.- Returns:
- true if this
IIOMetadataobject cannot be modified.
-
getNativeMetadataFormatName
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,nullwill be returned.The structure and contents of the "native" metadata format are defined by the plug-in that created this
IIOMetadataobject. 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
nativeMetadataFormatNameinstance variable.- Returns:
- the name of the native format, or
null. - See Also:
getExtraMetadataFormatNames(),getMetadataFormatNames()
-
getExtraMetadataFormatNames
public String[] getExtraMetadataFormatNames()
Returns an array ofStrings containing the names of additional metadata formats, other than the native and standard formats, recognized by this plug-in'sgetAsTree,setFromTree, andmergeTreemethods. If there are no such additional formats,nullis returned.The default implementation returns a clone of the
extraMetadataFormatNamesinstance variable.- Returns:
- an array of
Strings with length at least 1, ornull. - See Also:
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()
Returns an array ofStrings containing the names of all metadata formats, including the native and standard formats, recognized by this plug-in'sgetAsTree,setFromTree, andmergeTreemethods. If there are no such formats,nullis returned.The default implementation calls
getNativeMetadataFormatName,isStandardMetadataFormatSupported, andgetExtraMetadataFormatNamesand returns the combined results.- Returns:
- an array of
Strings. - See Also:
getNativeMetadataFormatName(),isStandardMetadataFormatSupported(),getExtraMetadataFormatNames()
-
getMetadataFormat
public IIOMetadataFormat getMetadataFormat(String formatName)
Returns anIIOMetadataFormatobject describing the given metadata format, ornullif no description is available. The supplied name must be one of those returned bygetMetadataFormatNames(i.e., either the native format name, the standard format name, or one of those returned bygetExtraMetadataFormatNames).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
IIOMetadataFormatclass fromnativeMetadataFormatClassNameorextraMetadataFormatClassNamesas appropriate, and constructs an instance of that class using itsgetInstancemethod.- Parameters:
formatName- the desired metadata format.- Returns:
- an
IIOMetadataFormatobject. - Throws:
IllegalArgumentException- ifformatNameisnullor is not one of the names recognized by the plug-in.IllegalStateException- if the class corresponding to the format name cannot be loaded.
-
getAsTree
public abstract Node getAsTree(String formatName)
Returns an XML DOMNodeobject 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
getMetadataFormatNamesmethod.- Parameters:
formatName- the desired metadata format.- Returns:
- an XML DOM
Nodeobject forming the root of a tree. - Throws:
IllegalArgumentException- ifformatNameisnullor is not one of the names returned bygetMetadataFormatNames.- See Also:
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
Alters the internal state of thisIIOMetadataobject from a tree of XML DOMNodes 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, anIIOInvalidTreeExceptionwill 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- the desired metadata format.root- an XML DOMNodeobject forming the root of a tree.- Throws:
IllegalStateException- if this object is read-only.IllegalArgumentException- ifformatNameisnullor is not one of the names returned bygetMetadataFormatNames.IllegalArgumentException- ifrootisnull.IIOInvalidTreeException- if the tree cannot be parsed successfully using the rules of the given format.- See Also:
getMetadataFormatNames(),getAsTree(java.lang.String),setFromTree(java.lang.String, org.w3c.dom.Node)
-
getStandardChromaNode
protected IIOMetadataNode getStandardChromaNode()
Returns anIIOMetadataNoderepresenting the chroma information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available. This method is intended to be called by the utility routinegetStandardTree.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:
- an
IIOMetadataNode, ornull. - See Also:
getStandardTree()
-
getStandardCompressionNode
protected IIOMetadataNode getStandardCompressionNode()
Returns anIIOMetadataNoderepresenting the compression information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available. This method is intended to be called by the utility routinegetStandardTree.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:
- an
IIOMetadataNode, ornull. - See Also:
getStandardTree()
-
getStandardDataNode
protected IIOMetadataNode getStandardDataNode()
Returns anIIOMetadataNoderepresenting the data format information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available. This method is intended to be called by the utility routinegetStandardTree.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:
- an
IIOMetadataNode, ornull. - See Also:
getStandardTree()
-
getStandardDimensionNode
protected IIOMetadataNode getStandardDimensionNode()
Returns anIIOMetadataNoderepresenting the dimension information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available. This method is intended to be called by the utility routinegetStandardTree.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:
- an
IIOMetadataNode, ornull. - See Also:
getStandardTree()
-
getStandardDocumentNode
protected IIOMetadataNode getStandardDocumentNode()
Returns anIIOMetadataNoderepresenting the document information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available. This method is intended to be called by the utility routinegetStandardTree.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:
- an
IIOMetadataNode, ornull. - See Also:
getStandardTree()
-
getStandardTextNode
protected IIOMetadataNode getStandardTextNode()
Returns anIIOMetadataNoderepresenting the textual information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available. This method is intended to be called by the utility routinegetStandardTree.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:
- an
IIOMetadataNode, ornull. - See Also:
getStandardTree()
-
getStandardTileNode
protected IIOMetadataNode getStandardTileNode()
Returns anIIOMetadataNoderepresenting the tiling information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available. This method is intended to be called by the utility routinegetStandardTree.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:
- an
IIOMetadataNode, ornull. - See Also:
getStandardTree()
-
getStandardTransparencyNode
protected IIOMetadataNode getStandardTransparencyNode()
Returns anIIOMetadataNoderepresenting the transparency information of the standardjavax_imageio_1.0metadata format, ornullif no such information is available. This method is intended to be called by the utility routinegetStandardTree.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:
- an
IIOMetadataNode, ornull.
-
getStandardTree
protected final IIOMetadataNode getStandardTree()
A utility method to return a tree ofIIOMetadataNodes representing the metadata contained within this object according to the conventions of the standardjavax_imageio_1.0metadata format.This method calls the various
getStandard*Nodemethods to supply each of the subtrees rooted at the children of the root node. If any of those methods returnsnull, the corresponding subtree will be omitted. If all of them returnnull, a tree consisting of a single root node will be returned.- Returns:
- an
IIOMetadataNoderepresenting the root of a metadata tree in thejavax_imageio_1.0format. - See Also:
getStandardChromaNode(),getStandardCompressionNode(),getStandardDataNode(),getStandardDimensionNode(),getStandardDocumentNode(),getStandardTextNode(),getStandardTileNode(),getStandardTransparencyNode()
-
setFromTree
public void setFromTree(String formatName, Node root) throws IIOInvalidTreeException
Sets the internal state of thisIIOMetadataobject from a tree of XML DOMNodes whose syntax is defined by the given metadata format. The previous state is discarded. If the tree's structure or contents are invalid, anIIOInvalidTreeExceptionwill be thrown.The default implementation calls
resetfollowed bymergeTree(formatName, root).- Parameters:
formatName- the desired metadata format.root- an XML DOMNodeobject forming the root of a tree.- Throws:
IllegalStateException- if this object is read-only.IllegalArgumentException- ifformatNameisnullor is not one of the names returned bygetMetadataFormatNames.IllegalArgumentException- ifrootisnull.IIOInvalidTreeException- if the tree cannot be parsed successfully using the rules of the given format.- See Also:
getMetadataFormatNames(),getAsTree(java.lang.String),mergeTree(java.lang.String, org.w3c.dom.Node)
-
reset
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.- Throws:
IllegalStateException- if this object is read-only.- See Also:
ImageReader.getStreamMetadata(),ImageReader.getImageMetadata(int),ImageWriter.getDefaultStreamMetadata(javax.imageio.ImageWriteParam),ImageWriter.getDefaultImageMetadata(javax.imageio.ImageTypeSpecifier, javax.imageio.ImageWriteParam)
-
setController
public void setController(IIOMetadataController controller)
Sets theIIOMetadataControllerto be used to provide settings for thisIIOMetadataobject when theactivateControllermethod is called, overriding any default controller. If the argument isnull, no controller will be used, including any default. To restore the default, usesetController(getDefaultController()).The default implementation sets the
controllerinstance variable to the supplied value.- Parameters:
controller- An appropriateIIOMetadataController, ornull.- See Also:
IIOMetadataController,getController(),getDefaultController(),hasController(),activateController()
-
getController
public IIOMetadataController getController()
Returns whateverIIOMetadataControlleris currently installed. This could be the default if there is one,null, or the argument of the most recent call tosetController.The default implementation returns the value of the
controllerinstance variable.- Returns:
- the currently installed
IIOMetadataController, ornull. - See Also:
IIOMetadataController,setController(javax.imageio.metadata.IIOMetadataController),getDefaultController(),hasController(),activateController()
-
getDefaultController
public IIOMetadataController getDefaultController()
Returns the defaultIIOMetadataController, if there is one, regardless of the currently installed controller. If there is no default controller, returnsnull.The default implementation returns the value of the
defaultControllerinstance variable.- Returns:
- the default
IIOMetadataController, ornull. - See Also:
IIOMetadataController,setController(IIOMetadataController),getController(),hasController(),activateController()
-
hasController
public boolean hasController()
Returnstrueif there is a controller installed for thisIIOMetadataobject.The default implementation returns
trueif thegetControllermethod returns a non-nullvalue.- Returns:
trueif a controller is installed.- See Also:
IIOMetadataController,setController(IIOMetadataController),getController(),getDefaultController(),activateController()
-
activateController
public boolean activateController()
Activates the installedIIOMetadataControllerfor thisIIOMetadataobject and returns the resulting value. When this method returnstrue, all values for thisIIOMetadataobject will be ready for the next write operation. Iffalseis 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
IIOMetadatafor a particular plug-in. Controllers need not be GUIs, however.The default implementation calls
getControllerand the callsactivateon the returned object ifhasControllerreturnstrue.- Returns:
trueif the controller completed normally.- Throws:
IllegalStateException- if there is no controller currently installed.- See Also:
IIOMetadataController,setController(IIOMetadataController),getController(),getDefaultController(),hasController()
-
-