You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
901 lines
34 KiB
901 lines
34 KiB
/*
|
|
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*/
|
|
|
|
package javax.imageio.metadata;
|
|
|
|
import org.w3c.dom.Node;
|
|
import java.lang.reflect.Method;
|
|
|
|
/**
|
|
* 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 <code>IIOMetadataNode</code> 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
|
|
* <code>getMetadataFormatNames</code>. 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 <code>ImageReader</code> and an
|
|
* <code>ImageWriter</code> for different image formats. To convert
|
|
* between two native formats as losslessly as the image file formats
|
|
* will allow, an <code>ImageTranscoder</code> object must be used.
|
|
*
|
|
* @see javax.imageio.ImageReader#getImageMetadata
|
|
* @see javax.imageio.ImageReader#getStreamMetadata
|
|
* @see javax.imageio.ImageReader#readAll
|
|
* @see javax.imageio.ImageWriter#getDefaultStreamMetadata
|
|
* @see javax.imageio.ImageWriter#getDefaultImageMetadata
|
|
* @see javax.imageio.ImageWriter#write
|
|
* @see javax.imageio.ImageWriter#convertImageMetadata
|
|
* @see javax.imageio.ImageWriter#convertStreamMetadata
|
|
* @see javax.imageio.IIOImage
|
|
* @see javax.imageio.ImageTranscoder
|
|
*
|
|
*/
|
|
public abstract class IIOMetadata {
|
|
|
|
/**
|
|
* A boolean indicating whether the concrete subclass supports the
|
|
* standard metadata format, set via the constructor.
|
|
*/
|
|
protected boolean standardFormatSupported;
|
|
|
|
/**
|
|
* The name of the native metadata format for this object,
|
|
* initialized to <code>null</code> and set via the constructor.
|
|
*/
|
|
protected String nativeMetadataFormatName = null;
|
|
|
|
/**
|
|
* The name of the class implementing <code>IIOMetadataFormat</code>
|
|
* and representing the native metadata format, initialized to
|
|
* <code>null</code> and set via the constructor.
|
|
*/
|
|
protected String nativeMetadataFormatClassName = null;
|
|
|
|
/**
|
|
* An array of names of formats, other than the standard and
|
|
* native formats, that are supported by this plug-in,
|
|
* initialized to <code>null</code> and set via the constructor.
|
|
*/
|
|
protected String[] extraMetadataFormatNames = null;
|
|
|
|
/**
|
|
* An array of names of classes implementing <code>IIOMetadataFormat</code>
|
|
* and representing the metadata formats, other than the standard and
|
|
* native formats, that are supported by this plug-in,
|
|
* initialized to <code>null</code> and set via the constructor.
|
|
*/
|
|
protected String[] extraMetadataFormatClassNames = null;
|
|
|
|
/**
|
|
* An <code>IIOMetadataController</code> that is suggested for use
|
|
* as the controller for this <code>IIOMetadata</code> object. It
|
|
* may be retrieved via <code>getDefaultController</code>. To
|
|
* install the default controller, call
|
|
* <code>setController(getDefaultController())</code>. This
|
|
* instance variable should be set by subclasses that choose to
|
|
* provide their own default controller, usually a GUI, for
|
|
* setting parameters.
|
|
*
|
|
* @see IIOMetadataController
|
|
* @see #getDefaultController
|
|
*/
|
|
protected IIOMetadataController defaultController = null;
|
|
|
|
/**
|
|
* The <code>IIOMetadataController</code> that will be
|
|
* used to provide settings for this <code>IIOMetadata</code>
|
|
* object when the <code>activateController</code> method
|
|
* is called. This value overrides any default controller,
|
|
* even when <code>null</code>.
|
|
*
|
|
* @see IIOMetadataController
|
|
* @see #setController(IIOMetadataController)
|
|
* @see #hasController()
|
|
* @see #activateController()
|
|
*/
|
|
protected IIOMetadataController controller = null;
|
|
|
|
/**
|
|
* Constructs an empty <code>IIOMetadata</code> object. The
|
|
* subclass is responsible for supplying values for all protected
|
|
* instance variables that will allow any non-overridden default
|
|
* implementations of methods to satisfy their contracts. For example,
|
|
* <code>extraMetadataFormatNames</code> should not have length 0.
|
|
*/
|
|
protected IIOMetadata() {}
|
|
|
|
/**
|
|
* Constructs an <code>IIOMetadata</code> object with the given
|
|
* format names and format class names, as well as a boolean
|
|
* indicating whether the standard format is supported.
|
|
*
|
|
* <p> This constructor does not attempt to check the class names
|
|
* for validity. Invalid class names may cause exceptions in
|
|
* subsequent calls to <code>getMetadataFormat</code>.
|
|
*
|
|
* @param standardMetadataFormatSupported <code>true</code> if
|
|
* this object can return or accept a DOM tree using the standard
|
|
* metadata format.
|
|
* @param nativeMetadataFormatName the name of the native metadata
|
|
* format, as a <code>String</code>, or <code>null</code> if there
|
|
* is no native format.
|
|
* @param nativeMetadataFormatClassName the name of the class of
|
|
* the native metadata format, or <code>null</code> if there is
|
|
* no native format.
|
|
* @param extraMetadataFormatNames an array of <code>String</code>s
|
|
* indicating additional formats supported by this object, or
|
|
* <code>null</code> if there are none.
|
|
* @param extraMetadataFormatClassNames an array of <code>String</code>s
|
|
* indicating the class names of any additional formats supported by
|
|
* this object, or <code>null</code> if there are none.
|
|
*
|
|
* @exception IllegalArgumentException if
|
|
* <code>extraMetadataFormatNames</code> has length 0.
|
|
* @exception IllegalArgumentException if
|
|
* <code>extraMetadataFormatNames</code> and
|
|
* <code>extraMetadataFormatClassNames</code> are neither both
|
|
* <code>null</code>, nor of the same length.
|
|
*/
|
|
protected IIOMetadata(boolean standardMetadataFormatSupported,
|
|
String nativeMetadataFormatName,
|
|
String nativeMetadataFormatClassName,
|
|
String[] extraMetadataFormatNames,
|
|
String[] extraMetadataFormatClassNames) {
|
|
this.standardFormatSupported = standardMetadataFormatSupported;
|
|
this.nativeMetadataFormatName = nativeMetadataFormatName;
|
|
this.nativeMetadataFormatClassName = nativeMetadataFormatClassName;
|
|
if (extraMetadataFormatNames != null) {
|
|
if (extraMetadataFormatNames.length == 0) {
|
|
throw new IllegalArgumentException
|
|
("extraMetadataFormatNames.length == 0!");
|
|
}
|
|
if (extraMetadataFormatClassNames == null) {
|
|
throw new IllegalArgumentException
|
|
("extraMetadataFormatNames != null && extraMetadataFormatClassNames == null!");
|
|
}
|
|
if (extraMetadataFormatClassNames.length !=
|
|
extraMetadataFormatNames.length) {
|
|
throw new IllegalArgumentException
|
|
("extraMetadataFormatClassNames.length != extraMetadataFormatNames.length!");
|
|
}
|
|
this.extraMetadataFormatNames =
|
|
(String[]) extraMetadataFormatNames.clone();
|
|
this.extraMetadataFormatClassNames =
|
|
(String[]) extraMetadataFormatClassNames.clone();
|
|
} else {
|
|
if (extraMetadataFormatClassNames != null) {
|
|
throw new IllegalArgumentException
|
|
("extraMetadataFormatNames == null && extraMetadataFormatClassNames != null!");
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns <code>true</code> if the standard metadata format is
|
|
* supported by <code>getMetadataFormat</code>,
|
|
* <code>getAsTree</code>, <code>setFromTree</code>, and
|
|
* <code>mergeTree</code>.
|
|
*
|
|
* <p> The default implementation returns the value of the
|
|
* <code>standardFormatSupported</code> instance variable.
|
|
*
|
|
* @return <code>true</code> if the standard metadata format
|
|
* is supported.
|
|
*
|
|
* @see #getAsTree
|
|
* @see #setFromTree
|
|
* @see #mergeTree
|
|
* @see #getMetadataFormat
|
|
*/
|
|
public boolean isStandardMetadataFormatSupported() {
|
|
return standardFormatSupported;
|
|
}
|
|
|
|
/**
|
|
* Returns <code>true</code> if this object does not support the
|
|
* <code>mergeTree</code>, <code>setFromTree</code>, and
|
|
* <code>reset</code> methods.
|
|
*
|
|
* @return true if this <code>IIOMetadata</code> object cannot be
|
|
* modified.
|
|
*/
|
|
public abstract boolean isReadOnly();
|
|
|
|
/**
|
|
* 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,
|
|
* <code>null</code>will be returned.
|
|
*
|
|
* <p> The structure and contents of the "native" metadata format
|
|
* are defined by the plug-in that created this
|
|
* <code>IIOMetadata</code> 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.
|
|
*
|
|
* <p> The default implementation returns the value of the
|
|
* <code>nativeMetadataFormatName</code> instance variable.
|
|
*
|
|
* @return the name of the native format, or <code>null</code>.
|
|
*
|
|
* @see #getExtraMetadataFormatNames
|
|
* @see #getMetadataFormatNames
|
|
*/
|
|
public String getNativeMetadataFormatName() {
|
|
return nativeMetadataFormatName;
|
|
}
|
|
|
|
/**
|
|
* Returns an array of <code>String</code>s containing the names
|
|
* of additional metadata formats, other than the native and standard
|
|
* formats, recognized by this plug-in's
|
|
* <code>getAsTree</code>, <code>setFromTree</code>, and
|
|
* <code>mergeTree</code> methods. If there are no such additional
|
|
* formats, <code>null</code> is returned.
|
|
*
|
|
* <p> The default implementation returns a clone of the
|
|
* <code>extraMetadataFormatNames</code> instance variable.
|
|
*
|
|
* @return an array of <code>String</code>s with length at least
|
|
* 1, or <code>null</code>.
|
|
*
|
|
* @see #getAsTree
|
|
* @see #setFromTree
|
|
* @see #mergeTree
|
|
* @see #getNativeMetadataFormatName
|
|
* @see #getMetadataFormatNames
|
|
*/
|
|
public String[] getExtraMetadataFormatNames() {
|
|
if (extraMetadataFormatNames == null) {
|
|
return null;
|
|
}
|
|
return (String[])extraMetadataFormatNames.clone();
|
|
}
|
|
|
|
/**
|
|
* Returns an array of <code>String</code>s containing the names
|
|
* of all metadata formats, including the native and standard
|
|
* formats, recognized by this plug-in's <code>getAsTree</code>,
|
|
* <code>setFromTree</code>, and <code>mergeTree</code> methods.
|
|
* If there are no such formats, <code>null</code> is returned.
|
|
*
|
|
* <p> The default implementation calls
|
|
* <code>getNativeMetadataFormatName</code>,
|
|
* <code>isStandardMetadataFormatSupported</code>, and
|
|
* <code>getExtraMetadataFormatNames</code> and returns the
|
|
* combined results.
|
|
*
|
|
* @return an array of <code>String</code>s.
|
|
*
|
|
* @see #getNativeMetadataFormatName
|
|
* @see #isStandardMetadataFormatSupported
|
|
* @see #getExtraMetadataFormatNames
|
|
*/
|
|
public String[] getMetadataFormatNames() {
|
|
String nativeName = getNativeMetadataFormatName();
|
|
String standardName = isStandardMetadataFormatSupported() ?
|
|
IIOMetadataFormatImpl.standardMetadataFormatName : null;
|
|
String[] extraNames = getExtraMetadataFormatNames();
|
|
|
|
int numFormats = 0;
|
|
if (nativeName != null) {
|
|
++numFormats;
|
|
}
|
|
if (standardName != null) {
|
|
++numFormats;
|
|
}
|
|
if (extraNames != null) {
|
|
numFormats += extraNames.length;
|
|
}
|
|
if (numFormats == 0) {
|
|
return null;
|
|
}
|
|
|
|
String[] formats = new String[numFormats];
|
|
int index = 0;
|
|
if (nativeName != null) {
|
|
formats[index++] = nativeName;
|
|
}
|
|
if (standardName != null) {
|
|
formats[index++] = standardName;
|
|
}
|
|
if (extraNames != null) {
|
|
for (int i = 0; i < extraNames.length; i++) {
|
|
formats[index++] = extraNames[i];
|
|
}
|
|
}
|
|
|
|
return formats;
|
|
}
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataFormat</code> object describing the
|
|
* given metadata format, or <code>null</code> if no description
|
|
* is available. The supplied name must be one of those returned
|
|
* by <code>getMetadataFormatNames</code> (<i>i.e.</i>, either the
|
|
* native format name, the standard format name, or one of those
|
|
* returned by <code>getExtraMetadataFormatNames</code>).
|
|
*
|
|
* <p> 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
|
|
* <code>IIOMetadataFormat</code> class from
|
|
* <code>nativeMetadataFormatClassName</code> or
|
|
* <code>extraMetadataFormatClassNames</code> as appropriate, and
|
|
* constructs an instance of that class using its
|
|
* <code>getInstance</code> method.
|
|
*
|
|
* @param formatName the desired metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataFormat</code> object.
|
|
*
|
|
* @exception IllegalArgumentException if <code>formatName</code>
|
|
* is <code>null</code> or is not one of the names recognized by
|
|
* the plug-in.
|
|
* @exception IllegalStateException if the class corresponding to
|
|
* the format name cannot be loaded.
|
|
*/
|
|
public IIOMetadataFormat getMetadataFormat(String formatName) {
|
|
if (formatName == null) {
|
|
throw new IllegalArgumentException("formatName == null!");
|
|
}
|
|
if (standardFormatSupported
|
|
&& formatName.equals
|
|
(IIOMetadataFormatImpl.standardMetadataFormatName)) {
|
|
return IIOMetadataFormatImpl.getStandardFormatInstance();
|
|
}
|
|
String formatClassName = null;
|
|
if (formatName.equals(nativeMetadataFormatName)) {
|
|
formatClassName = nativeMetadataFormatClassName;
|
|
} else if (extraMetadataFormatNames != null) {
|
|
for (int i = 0; i < extraMetadataFormatNames.length; i++) {
|
|
if (formatName.equals(extraMetadataFormatNames[i])) {
|
|
formatClassName = extraMetadataFormatClassNames[i];
|
|
break; // out of for
|
|
}
|
|
}
|
|
}
|
|
if (formatClassName == null) {
|
|
throw new IllegalArgumentException("Unsupported format name");
|
|
}
|
|
try {
|
|
Class cls = null;
|
|
final Object o = this;
|
|
|
|
// firstly we try to use classloader used for loading
|
|
// the IIOMetadata implemantation for this plugin.
|
|
ClassLoader loader = (ClassLoader)
|
|
java.security.AccessController.doPrivileged(
|
|
new java.security.PrivilegedAction() {
|
|
public Object run() {
|
|
return o.getClass().getClassLoader();
|
|
}
|
|
});
|
|
|
|
try {
|
|
cls = Class.forName(formatClassName, true,
|
|
loader);
|
|
} catch (ClassNotFoundException e) {
|
|
// we failed to load IIOMetadataFormat class by
|
|
// using IIOMetadata classloader.Next try is to
|
|
// use thread context classloader.
|
|
loader = (ClassLoader)
|
|
java.security.AccessController.doPrivileged(
|
|
new java.security.PrivilegedAction() {
|
|
public Object run() {
|
|
return Thread.currentThread().getContextClassLoader();
|
|
}
|
|
});
|
|
try {
|
|
cls = Class.forName(formatClassName, true,
|
|
loader);
|
|
} catch (ClassNotFoundException e1) {
|
|
// finally we try to use system classloader in case
|
|
// if we failed to load IIOMetadataFormat implementation
|
|
// class above.
|
|
cls = Class.forName(formatClassName, true,
|
|
ClassLoader.getSystemClassLoader());
|
|
}
|
|
}
|
|
|
|
Method meth = cls.getMethod("getInstance");
|
|
return (IIOMetadataFormat) meth.invoke(null);
|
|
} catch (Exception e) {
|
|
RuntimeException ex =
|
|
new IllegalStateException ("Can't obtain format");
|
|
ex.initCause(e);
|
|
throw ex;
|
|
}
|
|
|
|
}
|
|
|
|
/**
|
|
* Returns an XML DOM <code>Node</code> object that represents the
|
|
* root of a tree of metadata contained within this object
|
|
* according to the conventions defined by a given metadata
|
|
* format.
|
|
*
|
|
* <p> The names of the available metadata formats may be queried
|
|
* using the <code>getMetadataFormatNames</code> method.
|
|
*
|
|
* @param formatName the desired metadata format.
|
|
*
|
|
* @return an XML DOM <code>Node</code> object forming the
|
|
* root of a tree.
|
|
*
|
|
* @exception IllegalArgumentException if <code>formatName</code>
|
|
* is <code>null</code> or is not one of the names returned by
|
|
* <code>getMetadataFormatNames</code>.
|
|
*
|
|
* @see #getMetadataFormatNames
|
|
* @see #setFromTree
|
|
* @see #mergeTree
|
|
*/
|
|
public abstract Node getAsTree(String formatName);
|
|
|
|
/**
|
|
* Alters the internal state of this <code>IIOMetadata</code>
|
|
* object from a tree of XML DOM <code>Node</code>s whose syntax
|
|
* is defined by the given metadata format. The previous state is
|
|
* altered only as necessary to accommodate the nodes that are
|
|
* present in the given tree. If the tree structure or contents
|
|
* are invalid, an <code>IIOInvalidTreeException</code> will be
|
|
* thrown.
|
|
*
|
|
* <p> 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.
|
|
*
|
|
* @param formatName the desired metadata format.
|
|
* @param root an XML DOM <code>Node</code> object forming the
|
|
* root of a tree.
|
|
*
|
|
* @exception IllegalStateException if this object is read-only.
|
|
* @exception IllegalArgumentException if <code>formatName</code>
|
|
* is <code>null</code> or is not one of the names returned by
|
|
* <code>getMetadataFormatNames</code>.
|
|
* @exception IllegalArgumentException if <code>root</code> is
|
|
* <code>null</code>.
|
|
* @exception IIOInvalidTreeException if the tree cannot be parsed
|
|
* successfully using the rules of the given format.
|
|
*
|
|
* @see #getMetadataFormatNames
|
|
* @see #getAsTree
|
|
* @see #setFromTree
|
|
*/
|
|
public abstract void mergeTree(String formatName, Node root)
|
|
throws IIOInvalidTreeException;
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataNode</code> representing the chroma
|
|
* information of the standard <code>javax_imageio_1.0</code>
|
|
* metadata format, or <code>null</code> if no such information is
|
|
* available. This method is intended to be called by the utility
|
|
* routine <code>getStandardTree</code>.
|
|
*
|
|
* <p> The default implementation returns <code>null</code>.
|
|
*
|
|
* <p> Subclasses should override this method to produce an
|
|
* appropriate subtree if they wish to support the standard
|
|
* metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code>, or <code>null</code>.
|
|
*
|
|
* @see #getStandardTree
|
|
*/
|
|
protected IIOMetadataNode getStandardChromaNode() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataNode</code> representing the
|
|
* compression information of the standard
|
|
* <code>javax_imageio_1.0</code> metadata format, or
|
|
* <code>null</code> if no such information is available. This
|
|
* method is intended to be called by the utility routine
|
|
* <code>getStandardTree</code>.
|
|
*
|
|
* <p> The default implementation returns <code>null</code>.
|
|
*
|
|
* <p> Subclasses should override this method to produce an
|
|
* appropriate subtree if they wish to support the standard
|
|
* metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code>, or <code>null</code>.
|
|
*
|
|
* @see #getStandardTree
|
|
*/
|
|
protected IIOMetadataNode getStandardCompressionNode() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataNode</code> representing the data
|
|
* format information of the standard
|
|
* <code>javax_imageio_1.0</code> metadata format, or
|
|
* <code>null</code> if no such information is available. This
|
|
* method is intended to be called by the utility routine
|
|
* <code>getStandardTree</code>.
|
|
*
|
|
* <p> The default implementation returns <code>null</code>.
|
|
*
|
|
* <p> Subclasses should override this method to produce an
|
|
* appropriate subtree if they wish to support the standard
|
|
* metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code>, or <code>null</code>.
|
|
*
|
|
* @see #getStandardTree
|
|
*/
|
|
protected IIOMetadataNode getStandardDataNode() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataNode</code> representing the
|
|
* dimension information of the standard
|
|
* <code>javax_imageio_1.0</code> metadata format, or
|
|
* <code>null</code> if no such information is available. This
|
|
* method is intended to be called by the utility routine
|
|
* <code>getStandardTree</code>.
|
|
*
|
|
* <p> The default implementation returns <code>null</code>.
|
|
*
|
|
* <p> Subclasses should override this method to produce an
|
|
* appropriate subtree if they wish to support the standard
|
|
* metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code>, or <code>null</code>.
|
|
*
|
|
* @see #getStandardTree
|
|
*/
|
|
protected IIOMetadataNode getStandardDimensionNode() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataNode</code> representing the document
|
|
* information of the standard <code>javax_imageio_1.0</code>
|
|
* metadata format, or <code>null</code> if no such information is
|
|
* available. This method is intended to be called by the utility
|
|
* routine <code>getStandardTree</code>.
|
|
*
|
|
* <p> The default implementation returns <code>null</code>.
|
|
*
|
|
* <p> Subclasses should override this method to produce an
|
|
* appropriate subtree if they wish to support the standard
|
|
* metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code>, or <code>null</code>.
|
|
*
|
|
* @see #getStandardTree
|
|
*/
|
|
protected IIOMetadataNode getStandardDocumentNode() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataNode</code> representing the textual
|
|
* information of the standard <code>javax_imageio_1.0</code>
|
|
* metadata format, or <code>null</code> if no such information is
|
|
* available. This method is intended to be called by the utility
|
|
* routine <code>getStandardTree</code>.
|
|
*
|
|
* <p> The default implementation returns <code>null</code>.
|
|
*
|
|
* <p> Subclasses should override this method to produce an
|
|
* appropriate subtree if they wish to support the standard
|
|
* metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code>, or <code>null</code>.
|
|
*
|
|
* @see #getStandardTree
|
|
*/
|
|
protected IIOMetadataNode getStandardTextNode() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataNode</code> representing the tiling
|
|
* information of the standard <code>javax_imageio_1.0</code>
|
|
* metadata format, or <code>null</code> if no such information is
|
|
* available. This method is intended to be called by the utility
|
|
* routine <code>getStandardTree</code>.
|
|
*
|
|
* <p> The default implementation returns <code>null</code>.
|
|
*
|
|
* <p> Subclasses should override this method to produce an
|
|
* appropriate subtree if they wish to support the standard
|
|
* metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code>, or <code>null</code>.
|
|
*
|
|
* @see #getStandardTree
|
|
*/
|
|
protected IIOMetadataNode getStandardTileNode() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Returns an <code>IIOMetadataNode</code> representing the
|
|
* transparency information of the standard
|
|
* <code>javax_imageio_1.0</code> metadata format, or
|
|
* <code>null</code> if no such information is available. This
|
|
* method is intended to be called by the utility routine
|
|
* <code>getStandardTree</code>.
|
|
*
|
|
* <p> The default implementation returns <code>null</code>.
|
|
*
|
|
* <p> Subclasses should override this method to produce an
|
|
* appropriate subtree if they wish to support the standard
|
|
* metadata format.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code>, or <code>null</code>.
|
|
*/
|
|
protected IIOMetadataNode getStandardTransparencyNode() {
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Appends a new node to an existing node, if the new node is
|
|
* non-<code>null</code>.
|
|
*/
|
|
private void append(IIOMetadataNode root, IIOMetadataNode node) {
|
|
if (node != null) {
|
|
root.appendChild(node);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* A utility method to return a tree of
|
|
* <code>IIOMetadataNode</code>s representing the metadata
|
|
* contained within this object according to the conventions of
|
|
* the standard <code>javax_imageio_1.0</code> metadata format.
|
|
*
|
|
* <p> This method calls the various <code>getStandard*Node</code>
|
|
* methods to supply each of the subtrees rooted at the children
|
|
* of the root node. If any of those methods returns
|
|
* <code>null</code>, the corresponding subtree will be omitted.
|
|
* If all of them return <code>null</code>, a tree consisting of a
|
|
* single root node will be returned.
|
|
*
|
|
* @return an <code>IIOMetadataNode</code> representing the root
|
|
* of a metadata tree in the <code>javax_imageio_1.0</code>
|
|
* format.
|
|
*
|
|
* @see #getStandardChromaNode
|
|
* @see #getStandardCompressionNode
|
|
* @see #getStandardDataNode
|
|
* @see #getStandardDimensionNode
|
|
* @see #getStandardDocumentNode
|
|
* @see #getStandardTextNode
|
|
* @see #getStandardTileNode
|
|
* @see #getStandardTransparencyNode
|
|
*/
|
|
protected final IIOMetadataNode getStandardTree() {
|
|
IIOMetadataNode root = new IIOMetadataNode
|
|
(IIOMetadataFormatImpl.standardMetadataFormatName);
|
|
append(root, getStandardChromaNode());
|
|
append(root, getStandardCompressionNode());
|
|
append(root, getStandardDataNode());
|
|
append(root, getStandardDimensionNode());
|
|
append(root, getStandardDocumentNode());
|
|
append(root, getStandardTextNode());
|
|
append(root, getStandardTileNode());
|
|
append(root, getStandardTransparencyNode());
|
|
return root;
|
|
}
|
|
|
|
/**
|
|
* Sets the internal state of this <code>IIOMetadata</code> object
|
|
* from a tree of XML DOM <code>Node</code>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
|
|
* <code>IIOInvalidTreeException</code> will be thrown.
|
|
*
|
|
* <p> The default implementation calls <code>reset</code>
|
|
* followed by <code>mergeTree(formatName, root)</code>.
|
|
*
|
|
* @param formatName the desired metadata format.
|
|
* @param root an XML DOM <code>Node</code> object forming the
|
|
* root of a tree.
|
|
*
|
|
* @exception IllegalStateException if this object is read-only.
|
|
* @exception IllegalArgumentException if <code>formatName</code>
|
|
* is <code>null</code> or is not one of the names returned by
|
|
* <code>getMetadataFormatNames</code>.
|
|
* @exception IllegalArgumentException if <code>root</code> is
|
|
* <code>null</code>.
|
|
* @exception IIOInvalidTreeException if the tree cannot be parsed
|
|
* successfully using the rules of the given format.
|
|
*
|
|
* @see #getMetadataFormatNames
|
|
* @see #getAsTree
|
|
* @see #mergeTree
|
|
*/
|
|
public void setFromTree(String formatName, Node root)
|
|
throws IIOInvalidTreeException {
|
|
reset();
|
|
mergeTree(formatName, root);
|
|
}
|
|
|
|
/**
|
|
* 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.
|
|
* Note that there are many possible default values, depending on
|
|
* how the object was created.
|
|
*
|
|
* @exception IllegalStateException if this object is read-only.
|
|
*
|
|
* @see javax.imageio.ImageReader#getStreamMetadata
|
|
* @see javax.imageio.ImageReader#getImageMetadata
|
|
* @see javax.imageio.ImageWriter#getDefaultStreamMetadata
|
|
* @see javax.imageio.ImageWriter#getDefaultImageMetadata
|
|
*/
|
|
public abstract void reset();
|
|
|
|
/**
|
|
* Sets the <code>IIOMetadataController</code> to be used
|
|
* to provide settings for this <code>IIOMetadata</code>
|
|
* object when the <code>activateController</code> method
|
|
* is called, overriding any default controller. If the
|
|
* argument is <code>null</code>, no controller will be
|
|
* used, including any default. To restore the default, use
|
|
* <code>setController(getDefaultController())</code>.
|
|
*
|
|
* <p> The default implementation sets the <code>controller</code>
|
|
* instance variable to the supplied value.
|
|
*
|
|
* @param controller An appropriate
|
|
* <code>IIOMetadataController</code>, or <code>null</code>.
|
|
*
|
|
* @see IIOMetadataController
|
|
* @see #getController
|
|
* @see #getDefaultController
|
|
* @see #hasController
|
|
* @see #activateController()
|
|
*/
|
|
public void setController(IIOMetadataController controller) {
|
|
this.controller = controller;
|
|
}
|
|
|
|
/**
|
|
* Returns whatever <code>IIOMetadataController</code> is currently
|
|
* installed. This could be the default if there is one,
|
|
* <code>null</code>, or the argument of the most recent call
|
|
* to <code>setController</code>.
|
|
*
|
|
* <p> The default implementation returns the value of the
|
|
* <code>controller</code> instance variable.
|
|
*
|
|
* @return the currently installed
|
|
* <code>IIOMetadataController</code>, or <code>null</code>.
|
|
*
|
|
* @see IIOMetadataController
|
|
* @see #setController
|
|
* @see #getDefaultController
|
|
* @see #hasController
|
|
* @see #activateController()
|
|
*/
|
|
public IIOMetadataController getController() {
|
|
return controller;
|
|
}
|
|
|
|
/**
|
|
* Returns the default <code>IIOMetadataController</code>, if there
|
|
* is one, regardless of the currently installed controller. If
|
|
* there is no default controller, returns <code>null</code>.
|
|
*
|
|
* <p> The default implementation returns the value of the
|
|
* <code>defaultController</code> instance variable.
|
|
*
|
|
* @return the default <code>IIOMetadataController</code>, or
|
|
* <code>null</code>.
|
|
*
|
|
* @see IIOMetadataController
|
|
* @see #setController(IIOMetadataController)
|
|
* @see #getController
|
|
* @see #hasController
|
|
* @see #activateController()
|
|
*/
|
|
public IIOMetadataController getDefaultController() {
|
|
return defaultController;
|
|
}
|
|
|
|
/**
|
|
* Returns <code>true</code> if there is a controller installed
|
|
* for this <code>IIOMetadata</code> object.
|
|
*
|
|
* <p> The default implementation returns <code>true</code> if the
|
|
* <code>getController</code> method returns a
|
|
* non-<code>null</code> value.
|
|
*
|
|
* @return <code>true</code> if a controller is installed.
|
|
*
|
|
* @see IIOMetadataController
|
|
* @see #setController(IIOMetadataController)
|
|
* @see #getController
|
|
* @see #getDefaultController
|
|
* @see #activateController()
|
|
*/
|
|
public boolean hasController() {
|
|
return (getController() != null);
|
|
}
|
|
|
|
/**
|
|
* Activates the installed <code>IIOMetadataController</code> for
|
|
* this <code>IIOMetadata</code> object and returns the resulting
|
|
* value. When this method returns <code>true</code>, all values for this
|
|
* <code>IIOMetadata</code> object will be ready for the next write
|
|
* operation. If <code>false</code> is
|
|
* returned, no settings in this object will have been disturbed
|
|
* (<i>i.e.</i>, the user canceled the operation).
|
|
*
|
|
* <p> Ordinarily, the controller will be a GUI providing a user
|
|
* interface for a subclass of <code>IIOMetadata</code> for a
|
|
* particular plug-in. Controllers need not be GUIs, however.
|
|
*
|
|
* <p> The default implementation calls <code>getController</code>
|
|
* and the calls <code>activate</code> on the returned object if
|
|
* <code>hasController</code> returns <code>true</code>.
|
|
*
|
|
* @return <code>true</code> if the controller completed normally.
|
|
*
|
|
* @exception IllegalStateException if there is no controller
|
|
* currently installed.
|
|
*
|
|
* @see IIOMetadataController
|
|
* @see #setController(IIOMetadataController)
|
|
* @see #getController
|
|
* @see #getDefaultController
|
|
* @see #hasController
|
|
*/
|
|
public boolean activateController() {
|
|
if (!hasController()) {
|
|
throw new IllegalStateException("hasController() == false!");
|
|
}
|
|
return getController().activate(this);
|
|
}
|
|
}
|