javax.imageio.metadata
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 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.

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) , ImageWriter.convertImageMetadata(javax.imageio.metadata.IIOMetadata, javax.imageio.ImageTypeSpecifier, javax.imageio.ImageWriteParam) , ImageWriter.convertStreamMetadata(javax.imageio.metadata.IIOMetadata, javax.imageio.ImageWriteParam) , IIOImage , ImageTranscoder

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 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.
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 formatName, Node 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.
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 formatName, Node 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.

Methods inherited from 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.

See Also:

IIOMetadataController , setController(IIOMetadataController) , hasController() , activateController()

Constructor Detail

IIOMetadata

protected IIOMetadata()

Constructs an empty IIOMetadata object. The subclass is responsible for suppying values for all protected instance variables that will allow any non-overridden default implemtations 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 a String, or null if there is no native format.

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

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

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

Throws:

IllegalArgumentException - if extraMetadataFormatNames has length 0.

IllegalArgumentException - if extraMetadataFormatNames and extraMetadataFormatClassNames are neither both null, 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, nullwill 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 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:

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

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