public abstract class IIOMetadata extends Object
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.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
Modifier and Type | Field and Description |
---|---|
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.
|
Modifier | Constructor and Description |
---|---|
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. |
Modifier and Type | Method and Description |
---|---|
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
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. |
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
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. |
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
IIOMetadataNode s 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 Node s 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 Node s whose syntax is
defined by the given metadata format. |
protected boolean standardFormatSupported
protected String nativeMetadataFormatName
null
and set via the constructor.protected String nativeMetadataFormatClassName
IIOMetadataFormat
and representing the native metadata format, initialized to
null
and set via the constructor.protected String[] extraMetadataFormatNames
null
and set via the constructor.protected String[] extraMetadataFormatClassNames
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 IIOMetadataController defaultController
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.IIOMetadataController
,
getDefaultController()
protected IIOMetadataController controller
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
.protected IIOMetadata()
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.protected IIOMetadata(boolean standardMetadataFormatSupported, String nativeMetadataFormatName, String nativeMetadataFormatClassName, String[] extraMetadataFormatNames, String[] extraMetadataFormatClassNames)
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
.
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 String
s
indicating additional formats supported by this object, or
null
if there are none.extraMetadataFormatClassNames
- an array of String
s
indicating the class names of any additional formats supported by
this object, or null
if there are none.IllegalArgumentException
- if
extraMetadataFormatNames
has length 0.IllegalArgumentException
- if
extraMetadataFormatNames
and
extraMetadataFormatClassNames
are neither both
null
, nor of the same length.public boolean isStandardMetadataFormatSupported()
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.
true
if the standard metadata format
is supported.getAsTree(java.lang.String)
,
setFromTree(java.lang.String, org.w3c.dom.Node)
,
mergeTree(java.lang.String, org.w3c.dom.Node)
,
getMetadataFormat(java.lang.String)
public abstract boolean isReadOnly()
true
if this object does not support the
mergeTree
, setFromTree
, and
reset
methods.IIOMetadata
object cannot be
modified.public String getNativeMetadataFormatName()
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.
null
.getExtraMetadataFormatNames()
,
getMetadataFormatNames()
public String[] getExtraMetadataFormatNames()
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.
String
s with length at least
1, or null
.getAsTree(java.lang.String)
,
setFromTree(java.lang.String, org.w3c.dom.Node)
,
mergeTree(java.lang.String, org.w3c.dom.Node)
,
getNativeMetadataFormatName()
,
getMetadataFormatNames()
public String[] getMetadataFormatNames()
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.
String
s.getNativeMetadataFormatName()
,
isStandardMetadataFormatSupported()
,
getExtraMetadataFormatNames()
public IIOMetadataFormat getMetadataFormat(String formatName)
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.
formatName
- the desired metadata format.IIOMetadataFormat
object.IllegalArgumentException
- if formatName
is null
or is not one of the names recognized by
the plug-in.IllegalStateException
- if the class corresponding to
the format name cannot be loaded.public abstract Node getAsTree(String formatName)
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.
formatName
- the desired metadata format.Node
object forming the
root of a tree.IllegalArgumentException
- if formatName
is null
or is not one of the names returned by
getMetadataFormatNames
.getMetadataFormatNames()
,
setFromTree(java.lang.String, org.w3c.dom.Node)
,
mergeTree(java.lang.String, org.w3c.dom.Node)
public abstract void mergeTree(String formatName, Node root) throws IIOInvalidTreeException
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 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.
formatName
- the desired metadata format.root
- an XML DOM Node
object forming the
root of a tree.IllegalStateException
- if this object is read-only.IllegalArgumentException
- if formatName
is null
or is not one of the names returned by
getMetadataFormatNames
.IllegalArgumentException
- if root
is
null
.IIOInvalidTreeException
- if the tree cannot be parsed
successfully using the rules of the given format.getMetadataFormatNames()
,
getAsTree(java.lang.String)
,
setFromTree(java.lang.String, org.w3c.dom.Node)
protected IIOMetadataNode getStandardChromaNode()
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.
IIOMetadataNode
, or null
.getStandardTree()
protected IIOMetadataNode getStandardCompressionNode()
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.
IIOMetadataNode
, or null
.getStandardTree()
protected IIOMetadataNode getStandardDataNode()
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.
IIOMetadataNode
, or null
.getStandardTree()
protected IIOMetadataNode getStandardDimensionNode()
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.
IIOMetadataNode
, or null
.getStandardTree()
protected IIOMetadataNode getStandardDocumentNode()
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.
IIOMetadataNode
, or null
.getStandardTree()
protected IIOMetadataNode getStandardTextNode()
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.
IIOMetadataNode
, or null
.getStandardTree()
protected IIOMetadataNode getStandardTileNode()
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.
IIOMetadataNode
, or null
.getStandardTree()
protected IIOMetadataNode getStandardTransparencyNode()
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.
IIOMetadataNode
, or null
.protected final IIOMetadataNode getStandardTree()
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.
IIOMetadataNode
representing the root
of a metadata tree in the javax_imageio_1.0
format.getStandardChromaNode()
,
getStandardCompressionNode()
,
getStandardDataNode()
,
getStandardDimensionNode()
,
getStandardDocumentNode()
,
getStandardTextNode()
,
getStandardTileNode()
,
getStandardTransparencyNode()
public void setFromTree(String formatName, Node root) throws IIOInvalidTreeException
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)
.
formatName
- the desired metadata format.root
- an XML DOM Node
object forming the
root of a tree.IllegalStateException
- if this object is read-only.IllegalArgumentException
- if formatName
is null
or is not one of the names returned by
getMetadataFormatNames
.IllegalArgumentException
- if root
is
null
.IIOInvalidTreeException
- if the tree cannot be parsed
successfully using the rules of the given format.getMetadataFormatNames()
,
getAsTree(java.lang.String)
,
mergeTree(java.lang.String, org.w3c.dom.Node)
public abstract void reset()
IllegalStateException
- if this object is read-only.ImageReader.getStreamMetadata()
,
ImageReader.getImageMetadata(int)
,
ImageWriter.getDefaultStreamMetadata(javax.imageio.ImageWriteParam)
,
ImageWriter.getDefaultImageMetadata(javax.imageio.ImageTypeSpecifier, javax.imageio.ImageWriteParam)
public void setController(IIOMetadataController controller)
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.
controller
- An appropriate
IIOMetadataController
, or null
.IIOMetadataController
,
getController()
,
getDefaultController()
,
hasController()
,
activateController()
public IIOMetadataController getController()
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.
IIOMetadataController
, or null
.IIOMetadataController
,
setController(javax.imageio.metadata.IIOMetadataController)
,
getDefaultController()
,
hasController()
,
activateController()
public IIOMetadataController getDefaultController()
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.
IIOMetadataController
, or
null
.IIOMetadataController
,
setController(IIOMetadataController)
,
getController()
,
hasController()
,
activateController()
public boolean hasController()
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.
true
if a controller is installed.IIOMetadataController
,
setController(IIOMetadataController)
,
getController()
,
getDefaultController()
,
activateController()
public boolean activateController()
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.IllegalStateException
- if there is no controller
currently installed.IIOMetadataController
,
setController(IIOMetadataController)
,
getController()
,
getDefaultController()
,
hasController()
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.