| java.lang.Object
 javax.imageio.metadata.IIOMetadata
| IIOMetadata | | abstract public class IIOMetadata (Code) | | 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: javax.imageio.ImageReader.getImageMetadata
See Also: javax.imageio.ImageReader.getStreamMetadata
See Also: javax.imageio.ImageReader.readAll
See Also: javax.imageio.ImageWriter.getDefaultStreamMetadata
See Also: javax.imageio.ImageWriter.getDefaultImageMetadata
See Also: javax.imageio.ImageWriter.write
See Also: javax.imageio.ImageWriter.convertImageMetadata
See Also: javax.imageio.ImageWriter.convertStreamMetadata
See Also: javax.imageio.IIOImage
See Also: javax.imageio.ImageTranscoder
version:
0.5 |
| 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.
This constructor does not attempt to check the class names
for validity. |
| Method Summary | |
| public boolean | activateController()
Activates the installed IIOMetadataController for
this IIOMetadata object and returns the resulting
value. | | abstract public 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. | | public IIOMetadataController | getController()
Returns whatever IIOMetadataController is currently
installed. | | public IIOMetadataController | getDefaultController()
Returns the default IIOMetadataController, if there
is one, regardless of the currently installed controller. | | 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. | | public IIOMetadataFormat | getMetadataFormat(String formatName)
Returns an IIOMetadataFormat object describing the
given metadata format, or null if no description
is available. | | 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. | | 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. | | 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. | | final 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.
This method calls the various getStandard*Node
methods to supply each of the subtrees rooted at the children
of the root node. | | public boolean | hasController()
Returns true if there is a controller installed
for this IIOMetadata object. | | abstract public boolean | isReadOnly()
Returns true if this object does not support the
mergeTree, setFromTree, and
reset methods. | | public boolean | isStandardMetadataFormatSupported()
Returns true if the standard metadata format is
supported by getMetadataFormat,
getAsTree, setFromTree, and
mergeTree. | | abstract public 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 public 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 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 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. |
| defaultController | | protected IIOMetadataController defaultController(Code) | | 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
See Also: IIOMetadata.getDefaultController |
| extraMetadataFormatClassNames | | protected String[] extraMetadataFormatClassNames(Code) | | 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.
|
| extraMetadataFormatNames | | protected String[] extraMetadataFormatNames(Code) | | 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.
|
| nativeMetadataFormatClassName | | protected String nativeMetadataFormatClassName(Code) | | The name of the class implementing IIOMetadataFormat
and representing the native metadata format, initialized to
null and set via the constructor.
|
| nativeMetadataFormatName | | protected String nativeMetadataFormatName(Code) | | The name of the native metadata format for this object,
initialized to null and set via the constructor.
|
| standardFormatSupported | | protected boolean standardFormatSupported(Code) | | A boolean indicating whether the concrete subclass supports the
standard metadata format, set via the constructor.
|
| IIOMetadata | | protected IIOMetadata()(Code) | | 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)(Code) | | 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 ifthis object can return or accept a DOM tree using the standardmetadata format.
Parameters:
nativeMetadataFormatName - the name of the native metadataformat, as a String, or null if thereis no native format.
Parameters:
nativeMetadataFormatClassName - the name of the class of the native metadata format, or null if there isno native format.
Parameters:
extraMetadataFormatNames - an array of Stringsindicating additional formats supported by this object, ornull if there are none.
Parameters:
extraMetadataFormatClassNames - an array of Stringsindicating the class names of any additional formats supported bythis object, or null if there are none.
exception:
IllegalArgumentException - ifextraMetadataFormatNames has length 0.
exception:
IllegalArgumentException - ifextraMetadataFormatNames andextraMetadataFormatClassNames are neither bothnull, nor of the same length. |
| activateController | | public boolean activateController()(Code) | | 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.
true if the controller completed normally.
exception:
IllegalStateException - if there is no controllercurrently installed.
See Also: IIOMetadataController
See Also: IIOMetadata.setController(IIOMetadataController)
See Also: IIOMetadata.getController
See Also: IIOMetadata.getDefaultController
See Also: IIOMetadata.hasController |
| getAsTree | | abstract public Node getAsTree(String formatName)(Code) | | 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. an XML DOM Node object forming theroot of a tree.
exception:
IllegalArgumentException - if formatNameis null or is not one of the names returned bygetMetadataFormatNames.
See Also: IIOMetadata.getMetadataFormatNames
See Also: IIOMetadata.setFromTree
See Also: IIOMetadata.mergeTree |
| getMetadataFormat | | public IIOMetadataFormat getMetadataFormat(String formatName)(Code) | | 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. an IIOMetadataFormat object.
exception:
IllegalArgumentException - if formatNameis null or is not one of the names recognized bythe plug-in.
exception:
IllegalStateException - if the class corresponding tothe format name cannot be loaded. |
| getNativeMetadataFormatName | | public String getNativeMetadataFormatName()(Code) | | 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.
the name of the native format, or null.
See Also: IIOMetadata.getExtraMetadataFormatNames
See Also: IIOMetadata.getMetadataFormatNames |
| getStandardChromaNode | | protected IIOMetadataNode getStandardChromaNode()(Code) | | 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.
an IIOMetadataNode, or null.
See Also: IIOMetadata.getStandardTree |
| getStandardCompressionNode | | protected IIOMetadataNode getStandardCompressionNode()(Code) | | 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.
an IIOMetadataNode, or null.
See Also: IIOMetadata.getStandardTree |
| getStandardDataNode | | protected IIOMetadataNode getStandardDataNode()(Code) | | 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.
an IIOMetadataNode, or null.
See Also: IIOMetadata.getStandardTree |
| getStandardDimensionNode | | protected IIOMetadataNode getStandardDimensionNode()(Code) | | 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.
an IIOMetadataNode, or null.
See Also: IIOMetadata.getStandardTree |
| getStandardDocumentNode | | protected IIOMetadataNode getStandardDocumentNode()(Code) | | 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.
an IIOMetadataNode, or null.
See Also: IIOMetadata.getStandardTree |
| getStandardTextNode | | protected IIOMetadataNode getStandardTextNode()(Code) | | 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.
an IIOMetadataNode, or null.
See Also: IIOMetadata.getStandardTree |
| getStandardTileNode | | protected IIOMetadataNode getStandardTileNode()(Code) | | 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.
an IIOMetadataNode, or null.
See Also: IIOMetadata.getStandardTree |
| getStandardTransparencyNode | | protected IIOMetadataNode getStandardTransparencyNode()(Code) | | 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.
an IIOMetadataNode, or null. |
| isReadOnly | | abstract public boolean isReadOnly()(Code) | | Returns true if this object does not support the
mergeTree, setFromTree, and
reset methods.
true if this IIOMetadata object cannot bemodified. |
| mergeTree | | abstract public void mergeTree(String formatName, Node root) throws IIOInvalidTreeException(Code) | | 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 accomodate 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.
Parameters:
root - an XML DOM Node object forming theroot of a tree.
exception:
IllegalStateException - if this object is read-only.
exception:
IllegalArgumentException - if formatNameis null or is not one of the names returned bygetMetadataFormatNames.
exception:
IllegalArgumentException - if root isnull.
exception:
IIOInvalidTreeException - if the tree cannot be parsedsuccessfully using the rules of the given format.
See Also: IIOMetadata.getMetadataFormatNames
See Also: IIOMetadata.getAsTree
See Also: IIOMetadata.setFromTree |
|
|