| CONTENTS | PREV | NEXT |
The javax.imageio.metadata package contains classes
and interfaces for accessing metadata.
Metadata may contain complex, hierarchical structures. The Java XML Document Object Model (DOM) API is used to represent these structures, allowing developers to leverage their knowledge of these interfaces.
The Image I/O API differentiates between stream metadata, which is associated with all images stored in an image file, and image metadata which is associated with a single image. For image formats that contain a single image, only image metadata is used.
Metadata may be obtained by
calling the ImageReader.getStreamMetadata and
getImageMetadata(int imageIndex) methods. These return
an object that implements the IIOMetadata interface.
The actual class type of the returned object is up to the
ImageReader, and will usually be a unique class used
only by that reader. This object should be designed to store as
much of the metadata allowed by the format as possible, as
losslessly as possible. However, this fidelity to the
specifications of the image format comes at a cost, as access to
the metadata becomes format-specific.
In order to allow access to the
metadata without the need for format-specific application code,
IIOMetadata objects expose their internal information
in the form of an XML DOM structure, which is essentially a tree of
nodes of various types that may contain a set of attributes
(String values accessed by name), and which may
reference a set of child nodes.
A single plug-in may support
multiple document formats, which are distinguished by a format
name. Typically, at least two formats will be supported by a given
plug-in. The first is a common, plug-in neutral format called
com.sun.imageio_1.0, which is defined in the class
comment for the IIOMetadata interface. The second will
be a highly plug-in specific format that exposes all of the
internal structure of the IIOMetadata object in the
form of a DOM. The latter format is referred to as the native
format of the plug-in; its name may be determined by calling the
getNativeMetadataFormatName method of the
IIOMetadata object returned by the reader (advanced
users may call a method of the same name on the
ImageReaderSpi object used to instantiate the reader.
The latter approach is useful for selecting a plug-in based on its
support for a particular format). The names of all of the supported
document formats may be determined similarly by calling
getMetadataFormatNames.
The contents of an
IIOMetadata object may be accessed in the form of a
tree of XML Node objects by calling its
getAsTree method. This method takes a
String argument which is the name of one of the
document formats supported by the plug-in. This document may then
be manipulated as a standard XML DOM tree.
As an example, to print the contents of an XML DOM tree, the following code may be used:
public void displayMetadata(Node root) {
displayMetadata(root, 0);
}
void indent(int level) {
for (int i = 0; i < level; i++) {
System.out.print(" ");
}
}
void displayMetadata(Node node, int level) {
indent(level); // emit open tag
System.out.print("<" + node.getNodeName());
NamedNodeMap map = node.getAttributes();
if (map != null) { // print attribute values
int length = map.getLength();
for (int i = 0; i < length; i++) {
Node attr = map.item(i);
System.out.print(" " + attr.getNodeName() +
"=\"" + attr.getNodeValue() + "\"");
}
}
Node child = node.getFirstChild();
if (child != null) {
System.out.println(">"); // close current tag
while (child != null) { // emit child tags recursively
displayMetadata(child, level + 1);
child = child.getNextSibling();
}
indent(level); // emit close tag
System.out.println("</" + node.getNodeName() + ">");
} else {
System.out.println("/>");
}
}
Executing
displayMetadata on the metadata from a PNG
test image yields the output:
<com.sun.imageio.png_1.0> <IHDR width="32" height="32" bitDepth="8" colorType="RGB" compressionMethod="deflate" filterMethod="adaptive" interlaceMethod="none"/> <cHRM whitePointX="31270" whitePointY="32900" redX="64000" redY="33000" greenX="30000" greenY="60000" blueX="15000" blueY="6000"/> <gAMA value="100000"/> </com.sun.imageio.png_1.0>We see that the image contains
IHDR, cHRM, and gAMA chunks.
The interpretation of the attribute values requires an
understanding of the PNG format; however, it is still possible for
an application that does not understand PNG internals to display
the values and allow them to be edited interactively.IIOMetadataFormat Interface An IIOMetadataFormat
object is used to describe the legal structure of a metadata
document format. It constrains the types of nodes that may appear,
the types of nodes that may be children of a node of a given type,
the names and data types of the attributes that may appear at a
node of a given type, and the audiotape of an Object
value that may be stored at a node of a given type. In XML terms,
the information provided by the IIOMetadataFormat
interface is somewhere in between a DTD (Document Type Definition),
which gives information about node types, children, and attributes,
and an XML Schema, which provides detailed information about data
types.
For simplicity, only a subset of
legal DTD structures can be described by
IIOMetadataFormat. For example, the children of a node
may be defined in an IIOMetadataFormat as a sequence
in which each child must appear once (a, b, c), a
sequence in which each child is optional (a?, b?, c?),
a choice of a single child (a | b | c), or a
repetition of a single node type (a)*, whereas a DTD
allows many more combinations.
A node may not contain any textual
data, but may contain a reference to an arbitrary
Object. The IIOMetadataFormat indicates
the class type and optionally the legal enumerated values or a
range of values for the Object. Arrays are supported
as well.
A DTD does not allow any attribute
data types other than character strings; an XML Schema allows
extremely complex data types to be built up from simpler ones.
IIOMetadataFormat occupies a middle ground; it allows
attributes to be constrained to belong to one of a predefined set
of simple data types, including integers, floating-point decimals,
and dates. Lists of these data types are also allowed.
Since an
IIOMetadataFormat might be used to automatically
construct a user interface for displaying and editing metadata,
restricted the set of legal structures greatly simplifies the
mapping between formats and user interface designs.
