| 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.
