Class IIOMetadata
- 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 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:
-
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
Modifier and Type | Field | Description |
---|---|---|
protected IIOMetadataController | controller | The |
protected IIOMetadataController | defaultController | An |
protected String[] | extraMetadataFormatClassNames | An array of names of classes implementing |
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 |
protected String | nativeMetadataFormatClassName | The name of the class implementing |
protected String | nativeMetadataFormatName | The name of the native metadata format for this object, initialized to |
protected boolean | standardFormatSupported | A boolean indicating whether the concrete subclass supports the standard metadata format, set via the constructor. |
Constructor Summary
Modifier | Constructor | Description |
---|---|---|
protected | IIOMetadata() | Constructs an empty |
protected | IIOMetadata(boolean standardMetadataFormatSupported,
String nativeMetadataFormatName,
String nativeMetadataFormatClassName,
String[] extraMetadataFormatNames,
String[] extraMetadataFormatClassNames) | Constructs an |
Method Summary
Modifier and Type | Method | Description |
---|---|---|
boolean | activateController() | Activates the installed |
abstract Node | getAsTree(String formatName) | Returns an XML DOM |
IIOMetadataController | getController() | Returns whatever |
IIOMetadataController | getDefaultController() | Returns the default |
String[] | getExtraMetadataFormatNames() | Returns an array of |
IIOMetadataFormat | getMetadataFormat(String formatName) | Returns an |
String[] | getMetadataFormatNames() | Returns an array of |
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. |
protected IIOMetadataNode | getStandardChromaNode() | Returns an |
protected IIOMetadataNode | getStandardCompressionNode() | Returns an |
protected IIOMetadataNode | getStandardDataNode() | Returns an |
protected IIOMetadataNode | getStandardDimensionNode() | Returns an |
protected IIOMetadataNode | getStandardDocumentNode() | Returns an |
protected IIOMetadataNode | getStandardTextNode() | Returns an |
protected IIOMetadataNode | getStandardTileNode() | Returns an |
protected IIOMetadataNode | getStandardTransparencyNode() | Returns an |
protected IIOMetadataNode | getStandardTree() | A utility method to return a tree of |
boolean | hasController() | Returns |
abstract boolean | isReadOnly() | Returns |
boolean | isStandardMetadataFormatSupported() | Returns |
abstract void | mergeTree(String formatName,
Node root) | Alters the internal state of this |
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. |
void | setController(IIOMetadataController controller) | Sets the |
void | setFromTree(String formatName,
Node root) | Sets the internal state of this |
Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
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 to null
and set via the constructor.
nativeMetadataFormatClassName
protected String nativeMetadataFormatClassName
The name of the class implementing IIOMetadataFormat
and representing the native metadata format, initialized to null
and 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 to null
and set via the constructor.
extraMetadataFormatClassNames
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.
defaultController
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()
controller
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
.
Constructor Detail
IIOMetadata
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.
IIOMetadata
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
-true
if this object can return or accept a DOM tree using the standard metadata format. -
nativeMetadataFormatName
- the name of the native metadata format, as aString
, ornull
if there is no native format. -
nativeMetadataFormatClassName
- the name of the class of the native metadata format, ornull
if there is no native format. -
extraMetadataFormatNames
- an array ofString
s indicating additional formats supported by this object, ornull
if there are none. -
extraMetadataFormatClassNames
- an array ofString
s indicating the class names of any additional formats supported by this object, ornull
if there are none. - Throws:
-
IllegalArgumentException
- ifextraMetadataFormatNames
has length 0. -
IllegalArgumentException
- ifextraMetadataFormatNames
andextraMetadataFormatClassNames
are neither bothnull
, nor of the same length.
Method Detail
isStandardMetadataFormatSupported
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:
-
true
if 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()
Returns true
if this object does not support the mergeTree
, setFromTree
, and reset
methods.
- Returns:
- true if this
IIOMetadata
object 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, 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:
- the name of the native format, or
null
. - See Also:
-
getExtraMetadataFormatNames()
,getMetadataFormatNames()
getExtraMetadataFormatNames
public String[] getExtraMetadataFormatNames()
Returns an array of String
s 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:
- an array of
String
s 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 of String
s 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:
- an array of
String
s. - See Also:
-
getNativeMetadataFormatName()
,isStandardMetadataFormatSupported()
,getExtraMetadataFormatNames()
getMetadataFormat
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
- the desired metadata format. - Returns:
- an
IIOMetadataFormat
object. - Throws:
-
IllegalArgumentException
- ifformatName
isnull
or 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 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
- the desired metadata format. - Returns:
- an XML DOM
Node
object forming the root of a tree. - Throws:
-
IllegalArgumentException
- ifformatName
isnull
or 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 this IIOMetadata
object from a tree of XML DOM Node
s 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
- the desired metadata format. -
root
- an XML DOMNode
object forming the root of a tree. - Throws:
-
IllegalStateException
- if this object is read-only. -
IllegalArgumentException
- ifformatName
isnull
or is not one of the names returned bygetMetadataFormatNames
. -
IllegalArgumentException
- ifroot
isnull
. -
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 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:
- an
IIOMetadataNode
, ornull
. - See Also:
getStandardTree()
getStandardCompressionNode
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:
- an
IIOMetadataNode
, ornull
. - See Also:
getStandardTree()
getStandardDataNode
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:
- an
IIOMetadataNode
, ornull
. - See Also:
getStandardTree()
getStandardDimensionNode
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:
- an
IIOMetadataNode
, ornull
. - See Also:
getStandardTree()
getStandardDocumentNode
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:
- an
IIOMetadataNode
, ornull
. - See Also:
getStandardTree()
getStandardTextNode
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:
- an
IIOMetadataNode
, ornull
. - See Also:
getStandardTree()
getStandardTileNode
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:
- an
IIOMetadataNode
, ornull
. - See Also:
getStandardTree()
getStandardTransparencyNode
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:
- an
IIOMetadataNode
, ornull
.
getStandardTree
protected final IIOMetadataNode getStandardTree()
A utility method to return a tree of IIOMetadataNode
s 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:
- an
IIOMetadataNode
representing the root of a metadata tree in thejavax_imageio_1.0
format. - 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 this IIOMetadata
object from a tree of XML DOM Node
s 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
- the desired metadata format. -
root
- an XML DOMNode
object forming the root of a tree. - Throws:
-
IllegalStateException
- if this object is read-only. -
IllegalArgumentException
- ifformatName
isnull
or is not one of the names returned bygetMetadataFormatNames
. -
IllegalArgumentException
- ifroot
isnull
. -
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 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
- An appropriateIIOMetadataController
, ornull
. - See Also:
-
IIOMetadataController
,getController()
,getDefaultController()
,hasController()
,activateController()
getController
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:
- the currently installed
IIOMetadataController
, ornull
. - See Also:
-
IIOMetadataController
,setController(javax.imageio.metadata.IIOMetadataController)
,getDefaultController()
,hasController()
,activateController()
getDefaultController
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:
- the default
IIOMetadataController
, ornull
. - See Also:
-
IIOMetadataController
,setController(IIOMetadataController)
,getController()
,hasController()
,activateController()
hasController
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:
-
true
if a controller is installed. - See Also:
-
IIOMetadataController
,setController(IIOMetadataController)
,getController()
,getDefaultController()
,activateController()
activateController
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:
-
true
if the controller completed normally. - Throws:
-
IllegalStateException
- if there is no controller currently installed. - See Also:
-
IIOMetadataController
,setController(IIOMetadataController)
,getController()
,getDefaultController()
,hasController()