An IIOInvalidTreeException is thrown when an attempt
by an IIOMetadata object to parse a tree of
IIOMetadataNodes fails.  The node that led to the
parsing error may be stored.  As with any parsing error, the actual
error may occur at a different point that that where it is
detected.  The node returned by getOffendingNode
should merely be considered as a clue to the actual nature of the
problem.

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.

An interface to be implemented by objects that can determine the
settings of an IIOMetadata object, either by putting
up a GUI to obtain values from a user, or by other means.  This
interface merely specifies a generic activate method
that invokes the controller, without regard for how the controller
obtains values (i.e., whether the controller puts up a GUI
or merely computes a set of values is irrelevant to this
interface).

 Within the activate method, a controller obtains
initial values by querying the IIOMetadata object's
settings, either using the XML DOM tree or a plug-in specific
interface, modifies values by whatever means, then modifies the
IIOMetadata object's settings, using either the
setFromTree or mergeTree methods, or a
plug-in specific interface.  In general, applications may expect
that when the activate method returns
true, the IIOMetadata object is ready for
use in a write operation.

 Vendors may choose to provide GUIs for the
IIOMetadata subclasses they define for a particular
plug-in.  These can be set up as default controllers in the
corresponding IIOMetadata subclasses.

 Alternatively, an algorithmic process such as a database lookup
or the parsing of a command line could be used as a controller, in
which case the activate method would simply look up or
compute the settings, call methods on IIOMetadata to
set its state, and return true.

An object describing the structure of metadata documents returned
from IIOMetadata.getAsTree and passed to
IIOMetadata.setFromTree and mergeTree.
Document structures are described by a set of constraints on the
type and number of child elements that may belong to a given parent
element type, the names, types, and values of attributes that may
belong to an element, and the type and values of
Object reference that may be stored at a node.

 N.B: classes that implement this interface should contain a
method declared as public static getInstance() which
returns an instance of the class.  Commonly, an implementation will
construct only a single instance and cache it for future
invocations of getInstance.

 The structures that may be described by this class are a subset
of those expressible using XML document type definitions (DTDs),
with the addition of some basic information on the datatypes of
attributes and the ability to store an Object
reference within a node.  In the future, XML Schemas could be used
to represent these structures, and many others.

 The differences between
IIOMetadataFormat-described structures and DTDs are as
follows:


 Elements may not contain text or mix text with embedded
tags.

 The children of an element must conform to one of a few simple
patterns, described in the documentation for the
CHILD_* constants;

 The in-memory representation of an elements may contain a
reference to an Object.  There is no provision for
representing such objects textually.

A concrete class providing a reusable implementation of the
IIOMetadataFormat interface.  In addition, a static
instance representing the standard, plug-in neutral
javax_imageio_1.0 format is provided by the
getStandardFormatInstance method.

 In order to supply localized descriptions of elements and
attributes, a ResourceBundle with a base name of
this.getClass().getName()  "Resources" should be
supplied via the usual mechanism used by
ResourceBundle.getBundle.  Briefly, the subclasser
supplies one or more additional classes according to a naming
convention (by default, the fully-qualified name of the subclass
extending IIMetadataFormatImpl, plus the string
"Resources", plus the country, language, and variant codes
separated by underscores).  At run time, calls to
getElementDescription or
getAttributeDescription will attempt to load such
classes dynamically according to the supplied locale, and will use
either the element name, or the element name followed by a '/'
character followed by the attribute name as a key.  This key will
be supplied to the ResourceBundle's
getString method, and the resulting localized
description of the node or attribute is returned.

 The subclass may supply a different base name for the resource
bundles using the setResourceBaseName method.

 A subclass may choose its own localization mechanism, if so
desired, by overriding the supplied implementations of
getElementDescription and
getAttributeDescription.

A class representing a node in a meta-data tree, which implements
the
org.w3c.dom.Element interface and additionally allows
for the storage of non-textual objects via the
getUserObject and setUserObject methods.

 This class is not intended to be used for general XML
processing. In particular, Element nodes created
within the Image I/O API are not compatible with those created by
Sun's standard implementation of the org.w3.dom API.
In particular, the implementation is tuned for simple uses and may
not perform well for intensive processing.

 Namespaces are ignored in this implementation.  The terms "tag
name" and "node name" are always considered to be synonymous.

Note:
The DOM Level 3 specification added a number of new methods to the
Node, Element and Attr interfaces that are not
of value to the IIOMetadataNode implementation or specification.

Calling such methods on an IIOMetadataNode, or an Attr
instance returned from an IIOMetadataNode will result in a
DOMException being thrown.