Also see:

IIOMetadataController
getDefaultController

Also see:

IIOMetadataController
setController(IIOMetadataController)
hasController()
activateController()

 protected IIOMetadata() 
{

}

Constructs an empty 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) 
{
        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!");
            }
        }
}

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.

This constructor does not attempt to check the class names for validity. Invalid class names may cause exceptions in subsequent calls to getMetadataFormat.

Parameters:

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 Strings indicating additional formats supported by this object, or null if there are none.

extraMetadataFormatClassNames - an array of Strings indicating the class names of any additional formats supported by this object, or null if there are none.

Throws:

IllegalArgumentException - if extraMetadataFormatNames has length 0.

IllegalArgumentException - if extraMetadataFormatNames and extraMetadataFormatClassNames are neither both null, nor of the same length.

exception: IllegalArgumentException - if extraMetadataFormatNames has length 0.

exception: IllegalArgumentException - if extraMetadataFormatNames and extraMetadataFormatClassNames are neither both null, nor of the same length.

 public boolean activateController() 
{
        if (!hasController()) {
            throw new IllegalStateException("hasController() == false!");
        }
        return getController().activate(this);
}

Activates the installed 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.

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

 The names of the available metadata formats may be queried
using the getMetadataFormatNames method.

 public IIOMetadataController getController() 
{
        return controller;
}

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

 public IIOMetadataController getDefaultController() 
{
        return defaultController;
}

Returns the default 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.

 public String[] getExtraMetadataFormatNames() 
{
        if (extraMetadataFormatNames == null) {
            return null;
        }
        return (String[])extraMetadataFormatNames.clone();
}

Returns an array of Strings 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.

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

 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 array of Strings 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.

 public String getNativeMetadataFormatName() 
{
        return nativeMetadataFormatName;
}

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

 protected IIOMetadataNode getStandardChromaNode() 
{
        return null;
}

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

 protected IIOMetadataNode getStandardCompressionNode() 
{
        return null;
}

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

 protected IIOMetadataNode getStandardDataNode() 
{
        return null;
}

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

 protected IIOMetadataNode getStandardDimensionNode() 
{
        return null;
}

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

 protected IIOMetadataNode getStandardDocumentNode() 
{
        return null;
}

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

 protected IIOMetadataNode getStandardTextNode() 
{
        return null;
}

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

 protected IIOMetadataNode getStandardTileNode() 
{
        return null;
}

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

 protected IIOMetadataNode getStandardTransparencyNode() 
{
        return null;
}

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

 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;
}

A utility method to return a tree of IIOMetadataNodes 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.

 public boolean hasController() 
{
        return (getController() != null);
}

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

 abstract public boolean isReadOnly()
Returns true if this object does not support the
mergeTree, setFromTree, and
reset methods.

 public boolean isStandardMetadataFormatSupported() 
{
        return standardFormatSupported;
}

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

 abstract public  void mergeTree(String formatName,
    Node root) throws IIOInvalidTreeException
Alters the internal state of this IIOMetadata
object from a tree of XML DOM Nodes 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.

 abstract public  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.
Note that there are many possible default values, depending on
how the object was created.

 public  void setController(IIOMetadataController controller) 
{
        this.controller = controller;
}

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

 public  void setFromTree(String formatName,
    Node root) throws IIOInvalidTreeException 
{
        reset();
        mergeTree(formatName, root);
}

Sets the internal state of this IIOMetadata object from a tree of XML DOM Nodes 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).