java.lang.Object javax.imageio.metadata.IIOMetadata
public abstract class IIOMetadata
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 transfering 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.
Field Summary | |
---|---|
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 | |
---|---|
protected |
IIOMetadata
() Constructs an empty IIOMetadata object. |
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. |
Method Summary | |
---|---|
boolean |
activateController
() Activates the installed IIOMetadataController for this IIOMetadata object and returns the resulting value. |
abstract
org.w3c.dom.Node
|
getAsTree
(
String
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. |
IIOMetadataController |
getController
() Returns whatever IIOMetadataController is currently installed. |
IIOMetadataController |
getDefaultController
() Returns the default IIOMetadataController, if there is one, regardless of the currently installed controller. |
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. |
IIOMetadataFormat |
getMetadataFormat
(
String
formatName) Returns an IIOMetadataFormat object describing the given metadata format, or null if no description is available. |
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. |
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 IIOMetadataNode representing the chroma information of the standard javax_imageio_1.0 metadata format, or null if no such information is available. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
protected 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. |
boolean |
hasController
() Returns true if there is a controller installed for this IIOMetadata object. |
abstract boolean |
isReadOnly
() Returns true if this object does not support the mergeTree, setFromTree, and reset methods. |
boolean |
isStandardMetadataFormatSupported
() Returns true if the standard metadata format is supported by getMetadataFormat, getAsTree, setFromTree, and mergeTree. |
abstract void |
mergeTree
(
String
Alters the internal state of this IIOMetadata object from a tree of XML DOM Nodes whose syntax is defined by the given metadata format. |
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 IIOMetadataController to be used to provide settings for this IIOMetadata object when the activateController method is called, overriding any default controller. |
void |
setFromTree
(
String
Sets the internal state of this IIOMetadata object from a tree of XML DOM Nodes whose syntax is defined by the given metadata format. |
Methods inherited from class java.lang. Object |
---|
clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait |
Field Detail |
---|
protected boolean standardFormatSupported
protected String nativeMetadataFormatName
protected String nativeMetadataFormatClassName
protected String[] extraMetadataFormatNames
protected String[] extraMetadataFormatClassNames
protected IIOMetadataController defaultController
protected IIOMetadataController controller
Constructor Detail |
---|
protected IIOMetadata()
protected IIOMetadata(boolean standardMetadataFormatSupported, String nativeMetadataFormatName, String nativeMetadataFormatClassName, String[] extraMetadataFormatNames, String[] extraMetadataFormatClassNames)
This constructor does not attempt to check the class names for validity. Invalid class names may cause exceptions in subsequent calls to getMetadataFormat.
Method Detail |
---|
public boolean isStandardMetadataFormatSupported()
The default implementation returns the value of the standardFormatSupported instance variable.
public abstract boolean isReadOnly()
public String getNativeMetadataFormatName()
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.
public String[] getExtraMetadataFormatNames()
The default implementation returns a clone of the extraMetadataFormatNames instance variable.
public String[] getMetadataFormatNames()
The default implementation calls getNativeMetadataFormatName, isStandardMetadataFormatSupported, and getExtraMetadataFormatNames and returns the combined results.
public IIOMetadataFormat getMetadataFormat(String formatName)
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.
public abstract org.w3c.dom.NodeNodegetAsTree(String formatName)
The names of the available metadata formats may be queried using the getMetadataFormatNames method.
public abstract void mergeTree(String formatName, org.w3c.dom.Node root) throws IIOInvalidTreeExceptionformatName,Noderoot) throwsIIOInvalidTreeException
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.
protected IIOMetadataNode getStandardChromaNode()
The default implementation returns null.
Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.
protected IIOMetadataNode getStandardCompressionNode()
The default implementation returns null.
Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.
protected IIOMetadataNode getStandardDataNode()
The default implementation returns null.
Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.
protected IIOMetadataNode getStandardDimensionNode()
The default implementation returns null.
Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.
protected IIOMetadataNode getStandardDocumentNode()
The default implementation returns null.
Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.
protected IIOMetadataNode getStandardTextNode()
The default implementation returns null.
Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.
protected IIOMetadataNode getStandardTileNode()
The default implementation returns null.
Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.
protected IIOMetadataNode getStandardTransparencyNode()
The default implementation returns null.
Subclasses should override this method to produce an appropriate subtree if they wish to support the standard metadata format.
protected final IIOMetadataNode getStandardTree()
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.
public void setFromTree(String formatName, org.w3c.dom.Node root) throws IIOInvalidTreeExceptionformatName,Noderoot) throwsIIOInvalidTreeException
The default implementation calls reset followed by mergeTree(formatName, root).
public abstract void reset()
public void setController(IIOMetadataController controller)
The default implementation sets the controller instance variable to the supplied value.
public IIOMetadataController getController()
The default implementation returns the value of the controller instance variable.
public IIOMetadataController getDefaultController()
The default implementation returns the value of the defaultController instance variable.
public boolean hasController()
The default implementation returns true if the getController method returns a non-null value.
public boolean activateController()
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.