Java > Open Source Codes > javax > imageio > metadata > IIOMetadata


1 /*
2  * @(#)IIOMetadata.java 1.39 04/03/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.imageio.metadata;
9
10 import org.w3c.dom.Node ;
11 import java.lang.reflect.Method ;
12
13 /**
14  * An abstract class to be extended by objects that represent metadata
15  * (non-image data) associated with images and streams. Plug-ins
16  * represent metadata using opaque, plug-in specific objects. These
17  * objects, however, provide the ability to access their internal
18  * information as a tree of <code>IIOMetadataNode</code> objects that
19  * support the XML DOM interfaces as well as additional interfaces for
20  * storing non-textual data and retrieving information about legal
21  * data values. The format of such trees is plug-in dependent, but
22  * plug-ins may choose to support a plug-in neutral format described
23  * below. A single plug-in may support multiple metadata formats,
24  * whose names maybe determined by calling
25  * <code>getMetadataFormatNames</code>. The plug-in may also support
26  * a single special format, referred to as the "native" format, which
27  * is designed to encode its metadata losslessly. This format will
28  * typically be designed specifically to work with a specific file
29  * format, so that images may be loaded and saved in the same format
30  * with no loss of metadata, but may be less useful for transfering
31  * metadata between an <code>ImageReader</code> and an
32  * <code>ImageWriter</code> for different image formats. To convert
33  * between two native formats as losslessly as the image file formats
34  * will allow, an <code>ImageTranscoder</code> object must be used.
35  *
36  * @see javax.imageio.ImageReader#getImageMetadata
37  * @see javax.imageio.ImageReader#getStreamMetadata
38  * @see javax.imageio.ImageReader#readAll
39  * @see javax.imageio.ImageWriter#getDefaultStreamMetadata
40  * @see javax.imageio.ImageWriter#getDefaultImageMetadata
41  * @see javax.imageio.ImageWriter#write
42  * @see javax.imageio.ImageWriter#convertImageMetadata
43  * @see javax.imageio.ImageWriter#convertStreamMetadata
44  * @see javax.imageio.IIOImage
45  * @see javax.imageio.ImageTranscoder
46  *
47  * @version 0.5
48  */
49 public abstract class IIOMetadata {
50
51     /**
52      * A boolean indicating whether the concrete subclass supports the
53      * standard metadata format, set via the constructor.
54      */
55     protected boolean standardFormatSupported;
56
57     /**
58      * The name of the native metadata format for this object,
59      * initialized to <code>null</code> and set via the constructor.
60      */
61     protected String nativeMetadataFormatName = null;
62
63     /**
64      * The name of the class implementing <code>IIOMetadataFormat</code>
65      * and representing the native metadata format, initialized to
66      * <code>null</code> and set via the constructor.
67      */
68     protected String nativeMetadataFormatClassName = null;
69     
70     /**
71      * An array of names of formats, other than the standard and
72      * native formats, that are supported by this plug-in,
73      * initialized to <code>null</code> and set via the constructor.
74      */
75     protected String [] extraMetadataFormatNames = null;
76
77     /**
78      * An array of names of classes implementing <code>IIOMetadataFormat</code>
79      * and representing the metadata formats, other than the standard and
80      * native formats, that are supported by this plug-in,
81      * initialized to <code>null</code> and set via the constructor.
82      */
83     protected String [] extraMetadataFormatClassNames = null;
84
85     /**
86      * An <code>IIOMetadataController</code> that is suggested for use
87      * as the controller for this <code>IIOMetadata</code> object. It
88      * may be retrieved via <code>getDefaultController</code>. To
89      * install the default controller, call
90      * <code>setController(getDefaultController())</code>. This
91      * instance variable should be set by subclasses that choose to
92      * provide their own default controller, usually a GUI, for
93      * setting parameters.
94      *
95      * @see IIOMetadataController
96      * @see #getDefaultController
97      */
98     protected IIOMetadataController defaultController = null;
99
100     /**
101      * The <code>IIOMetadataController</code> that will be
102      * used to provide settings for this <code>IIOMetadata</code>
103      * object when the <code>activateController</code> method
104      * is called. This value overrides any default controller,
105      * even when <code>null</code>.
106      *
107      * @see IIOMetadataController
108      * @see #setController(IIOMetadataController)
109      * @see #hasController()
110      * @see #activateController()
111      */
112     protected IIOMetadataController controller = null;
113
114     /**
115      * Constructs an empty <code>IIOMetadata</code> object. The
116      * subclass is responsible for suppying values for all protected
117      * instance variables that will allow any non-overridden default
118      * implemtations of methods to satisfy their contracts. For example,
119      * <code>extraMetadataFormatNames</code> should not have length 0.
120      */
121     protected IIOMetadata() {}
122
123     /**
124      * Constructs an <code>IIOMetadata</code> object with the given
125      * format names and format class names, as well as a boolean
126      * indicating whether the standard format is supported.
127      *
128      * <p> This constructor does not attempt to check the class names
129      * for validity. Invalid class names may cause exceptions in
130      * subsequent calls to <code>getMetadataFormat</code>.
131      *
132      * @param standardMetadataFormatSupported <code>true</code> if
133      * this object can return or accept a DOM tree using the standard
134      * metadata format.
135      * @param nativeMetadataFormatName the name of the native metadata
136      * format, as a <code>String</code>, or <code>null</code> if there
137      * is no native format.
138      * @param nativeMetadataFormatClassName the name of the class of
139      * the native metadata format, or <code>null</code> if there is
140      * no native format.
141      * @param extraMetadataFormatNames an array of <code>String</code>s
142      * indicating additional formats supported by this object, or
143      * <code>null</code> if there are none.
144      * @param extraMetadataFormatClassNames an array of <code>String</code>s
145      * indicating the class names of any additional formats supported by
146      * this object, or <code>null</code> if there are none.
147      *
148      * @exception IllegalArgumentException if
149      * <code>extraMetadataFormatNames</code> has length 0.
150      * @exception IllegalArgumentException if
151      * <code>extraMetadataFormatNames</code> and
152      * <code>extraMetadataFormatClassNames</code> are neither both
153      * <code>null</code>, nor of the same length.
154      */
155     protected IIOMetadata(boolean standardMetadataFormatSupported,
156                           String nativeMetadataFormatName,
157                           String nativeMetadataFormatClassName,
158                           String [] extraMetadataFormatNames,
159                           String [] extraMetadataFormatClassNames) {
160         this.standardFormatSupported = standardMetadataFormatSupported;
161         this.nativeMetadataFormatName = nativeMetadataFormatName;
162         this.nativeMetadataFormatClassName = nativeMetadataFormatClassName;
163         if (extraMetadataFormatNames != null) {
164             if (extraMetadataFormatNames.length == 0) {
165                 throw new IllegalArgumentException
166                     ("extraMetadataFormatNames.length == 0!");
167             }
168             if (extraMetadataFormatClassNames == null) {
169                 throw new IllegalArgumentException
170                     ("extraMetadataFormatNames != null && extraMetadataFormatClassNames == null!");
171             }
172             if (extraMetadataFormatClassNames.length !=
173                 extraMetadataFormatNames.length) {
174                 throw new IllegalArgumentException
175                     ("extraMetadataFormatClassNames.length != extraMetadataFormatNames.length!");
176             }
177             this.extraMetadataFormatNames =
178                 (String []) extraMetadataFormatNames.clone();
179             this.extraMetadataFormatClassNames =
180                 (String []) extraMetadataFormatClassNames.clone();
181         } else {
182             if (extraMetadataFormatClassNames != null) {
183                 throw new IllegalArgumentException
184                     ("extraMetadataFormatNames == null && extraMetadataFormatClassNames != null!");
185             }
186         }
187     }
188
189     /**
190      * Returns <code>true</code> if the standard metadata format is
191      * supported by <code>getMetadataFormat</code>,
192      * <code>getAsTree</code>, <code>setFromTree</code>, and
193      * <code>mergeTree</code>.
194      *
195      * <p> The default implementation returns the value of the
196      * <code>standardFormatSupported</code> instance variable.
197      *
198      * @return <code>true</code> if the standard metadata format
199      * is supported.
200      *
201      * @see #getAsTree
202      * @see #setFromTree
203      * @see #mergeTree
204      * @see #getMetadataFormat
205      */
206     public boolean isStandardMetadataFormatSupported() {
207         return standardFormatSupported;
208     }
209
210     /**
211      * Returns <code>true</code> if this object does not support the
212      * <code>mergeTree</code>, <code>setFromTree</code>, and
213      * <code>reset</code> methods.
214      *
215      * @return true if this <code>IIOMetadata</code> object cannot be
216      * modified.
217      */
218     public abstract boolean isReadOnly();
219
220     /**
221      * Returns the name of the "native" metadata format for this
222      * plug-in, which typically allows for lossless encoding and
223      * transmission of the metadata stored in the format handled by
224      * this plug-in. If no such format is supported,
225      * <code>null</code>will be returned.
226      *
227      * <p> The structure and contents of the "native" metadata format
228      * are defined by the plug-in that created this
229      * <code>IIOMetadata</code> object. Plug-ins for simple formats
230      * will usually create a dummy node for the root, and then a
231      * series of child nodes representing individual tags, chunks, or
232      * keyword/value pairs. A plug-in may choose whether or not to
233      * document its native format.
234      *
235      * <p> The default implementation returns the value of the
236      * <code>nativeMetadataFormatName</code> instance variable.
237      *
238      * @return the name of the native format, or <code>null</code>.
239      *
240      * @see #getExtraMetadataFormatNames
241      * @see #getMetadataFormatNames
242      */
243     public String getNativeMetadataFormatName() {
244         return nativeMetadataFormatName;
245     }
246
247     /**
248      * Returns an array of <code>String</code>s containing the names
249      * of additional metadata formats, other than the native and standard
250      * formats, recognized by this plug-in's
251      * <code>getAsTree</code>, <code>setFromTree</code>, and
252      * <code>mergeTree</code> methods. If there are no such additional
253      * formats, <code>null</code> is returned.
254      *
255      * <p> The default implementation returns a clone of the
256      * <code>extraMetadataFormatNames</code> instance variable.
257      *
258      * @return an array of <code>String</code>s with length at least
259      * 1, or <code>null</code>.
260      *
261      * @see #getAsTree
262      * @see #setFromTree
263      * @see #mergeTree
264      * @see #getNativeMetadataFormatName
265      * @see #getMetadataFormatNames
266      */
267     public String [] getExtraMetadataFormatNames() {
268         if (extraMetadataFormatNames == null) {
269             return null;
270         }
271         return (String [])extraMetadataFormatNames.clone();
272     }
273
274     /**
275      * Returns an array of <code>String</code>s containing the names
276      * of all metadata formats, including the native and standard
277      * formats, recognized by this plug-in's <code>getAsTree</code>,
278      * <code>setFromTree</code>, and <code>mergeTree</code> methods.
279      * If there are no such formats, <code>null</code> is returned.
280      *
281      * <p> The default implementation calls
282      * <code>getNativeMetadataFormatName</code>,
283      * <code>isStandardMetadataFormatSupported</code>, and
284      * <code>getExtraMetadataFormatNames</code> and returns the
285      * combined results.
286      *
287      * @return an array of <code>String</code>s.
288      *
289      * @see #getNativeMetadataFormatName
290      * @see #isStandardMetadataFormatSupported
291      * @see #getExtraMetadataFormatNames
292      */
293     public String [] getMetadataFormatNames() {
294         String nativeName = getNativeMetadataFormatName();
295         String standardName = isStandardMetadataFormatSupported() ?
296             IIOMetadataFormatImpl.standardMetadataFormatName : null;
297         String [] extraNames = getExtraMetadataFormatNames();
298
299         int numFormats = 0;
300         if (nativeName != null) {
301             ++numFormats;
302         }
303         if (standardName != null) {
304             ++numFormats;
305         }
306         if (extraNames != null) {
307             numFormats += extraNames.length;
308         }
309         if (numFormats == 0) {
310             return null;
311         }
312
313         String [] formats = new String [numFormats];
314         int index = 0;
315         if (nativeName != null) {
316             formats[index++] = nativeName;
317         }
318         if (standardName != null) {
319             formats[index++] = standardName;
320         }
321         if (extraNames != null) {
322             for (int i = 0; i < extraNames.length; i++) {
323                 formats[index++] = extraNames[i];
324             }
325         }
326
327         return formats;
328     }
329
330     /**
331      * Returns an <code>IIOMetadataFormat</code> object describing the
332      * given metadata format, or <code>null</code> if no description
333      * is available. The supplied name must be one of those returned
334      * by <code>getMetadataFormatNames</code> (<i>i.e.</i>, either the
335      * native format name, the standard format name, or one of those
336      * returned by <code>getExtraMetadataFormatNames</code>).
337      *
338      * <p> The default implementation checks the name against the
339      * global standard metadata format name, and returns that format
340      * if it is supported. Otherwise, it checks against the native
341      * format names followed by any additional format names. If a
342      * match is found, it retrieves the name of the
343      * <code>IIOMetadataFormat</code> class from
344      * <code>nativeMetadataFormatClassName</code> or
345      * <code>extraMetadataFormatClassNames</code> as appropriate, and
346      * constructs an instance of that class using its
347      * <code>getInstance</code> method.
348      *
349      * @param formatName the desired metadata format.
350      *
351      * @return an <code>IIOMetadataFormat</code> object.
352      *
353      * @exception IllegalArgumentException if <code>formatName</code>
354      * is <code>null</code> or is not one of the names recognized by
355      * the plug-in.
356      * @exception IllegalStateException if the class corresponding to
357      * the format name cannot be loaded.
358      */
359     public IIOMetadataFormat getMetadataFormat(String formatName) {
360         if (formatName == null) {
361             throw new IllegalArgumentException ("formatName == null!");
362         }
363         if (standardFormatSupported
364             && formatName.equals
365                 (IIOMetadataFormatImpl.standardMetadataFormatName)) {
366             return IIOMetadataFormatImpl.getStandardFormatInstance();
367         }
368         String formatClassName = null;
369         if (formatName.equals(nativeMetadataFormatName)) {
370             formatClassName = nativeMetadataFormatClassName;
371         } else if (extraMetadataFormatNames != null) {
372             for (int i = 0; i < extraMetadataFormatNames.length; i++) {
373                 if (formatName.equals(extraMetadataFormatNames[i])) {
374                     formatClassName = extraMetadataFormatClassNames[i];
375                     break; // out of for
376 }
377             }
378         }
379         if (formatClassName == null) {
380             throw new IllegalArgumentException ("Unsupported format name");
381         }
382         try {
383             Class cls = null;
384             final Object o = this;
385
386             // firstly we try to use classloader used for loading
387 // the IIOMetadata implemantation for this plugin.
388 ClassLoader loader = (ClassLoader )
389                 java.security.AccessController.doPrivileged(
390                     new java.security.PrivilegedAction () {
391                             public Object run() {
392                                 return o.getClass().getClassLoader();
393                             }
394                         });
395             
396             try {
397                 cls = Class.forName(formatClassName, true,
398                                     loader);
399             } catch (ClassNotFoundException e) {
400                 // we failed to load IIOMetadataFormat class by
401 // using IIOMetadata classloader.Next try is to
402 // use thread context classloader.
403 loader = (ClassLoader )
404                     java.security.AccessController.doPrivileged(
405                         new java.security.PrivilegedAction () {
406                                 public Object run() {
407                                     return Thread.currentThread().getContextClassLoader();
408                                 }
409                         });
410                 try {
411                     cls = Class.forName(formatClassName, true,
412                                         loader);
413                 } catch (ClassNotFoundException e1) {
414                     // finally we try to use system classloader in case
415 // if we failed to load IIOMetadataFormat implementation
416 // class above.
417 cls = Class.forName(formatClassName, true,
418                                         ClassLoader.getSystemClassLoader());
419                 }
420             }
421             
422             Method meth = cls.getMethod("getInstance", null);
423             return (IIOMetadataFormat ) meth.invoke(null, null);
424         } catch (Exception e) {
425             RuntimeException ex =
426                 new IllegalStateException ("Can't obtain format");
427             ex.initCause(e);
428             throw ex;
429         }
430         
431     }
432
433     /**
434      * Returns an XML DOM <code>Node</code> object that represents the
435      * root of a tree of metadata contained within this object
436      * according to the conventions defined by a given metadata
437      * format.
438      *
439      * <p> The names of the available metadata formats may be queried
440      * using the <code>getMetadataFormatNames</code> method.
441      *
442      * @param formatName the desired metadata format.
443      *
444      * @return an XML DOM <code>Node</code> object forming the
445      * root of a tree.
446      *
447      * @exception IllegalArgumentException if <code>formatName</code>
448      * is <code>null</code> or is not one of the names returned by
449      * <code>getMetadataFormatNames</code>.
450      *
451      * @see #getMetadataFormatNames
452      * @see #setFromTree
453      * @see #mergeTree
454      */
455     public abstract Node getAsTree(String formatName);
456
457     /**
458      * Alters the internal state of this <code>IIOMetadata</code>
459      * object from a tree of XML DOM <code>Node</code>s whose syntax
460      * is defined by the given metadata format. The previous state is
461      * altered only as necessary to accomodate the nodes that are
462      * present in the given tree. If the tree structure or contents
463      * are invalid, an <code>IIOInvalidTreeException</code> will be
464      * thrown.
465      *
466      * <p> As the semantics of how a tree or subtree may be merged with
467      * another tree are completely format-specific, plug-in authors may
468      * implement this method in whatever manner is most appropriate for
469      * the format, including simply replacing all existing state with the
470      * contents of the given tree.
471      *
472      * @param formatName the desired metadata format.
473      * @param root an XML DOM <code>Node</code> object forming the
474      * root of a tree.
475      *
476      * @exception IllegalStateException if this object is read-only.
477      * @exception IllegalArgumentException if <code>formatName</code>
478      * is <code>null</code> or is not one of the names returned by
479      * <code>getMetadataFormatNames</code>.
480      * @exception IllegalArgumentException if <code>root</code> is
481      * <code>null</code>.
482      * @exception IIOInvalidTreeException if the tree cannot be parsed
483      * successfully using the rules of the given format.
484      *
485      * @see #getMetadataFormatNames
486      * @see #getAsTree
487      * @see #setFromTree
488      */
489     public abstract void mergeTree(String formatName, Node root)
490         throws IIOInvalidTreeException ;
491
492     /**
493      * Returns an <code>IIOMetadataNode</code> representing the chroma
494      * information of the standard <code>javax_imageio_1.0</code>
495      * metadata format, or <code>null</code> if no such information is
496      * available. This method is intended to be called by the utility
497      * routine <code>getStandardTree</code>.
498      *
499      * <p> The default implementation returns <code>null</code>.
500      *
501      * <p> Subclasses should override this method to produce an
502      * appropriate subtree if they wish to support the standard
503      * metadata format.
504      *
505      * @return an <code>IIOMetadataNode</code>, or <code>null</code>.
506      *
507      * @see #getStandardTree
508      */
509     protected IIOMetadataNode getStandardChromaNode() {
510         return null;
511     }
512
513     /**
514      * Returns an <code>IIOMetadataNode</code> representing the
515      * compression information of the standard
516      * <code>javax_imageio_1.0</code> metadata format, or
517      * <code>null</code> if no such information is available. This
518      * method is intended to be called by the utility routine
519      * <code>getStandardTree</code>.
520      *
521      * <p> The default implementation returns <code>null</code>.
522      *
523      * <p> Subclasses should override this method to produce an
524      * appropriate subtree if they wish to support the standard
525      * metadata format.
526      *
527      * @return an <code>IIOMetadataNode</code>, or <code>null</code>.
528      *
529      * @see #getStandardTree
530      */
531     protected IIOMetadataNode getStandardCompressionNode() {
532         return null;
533     }
534
535     /**
536      * Returns an <code>IIOMetadataNode</code> representing the data
537      * format information of the standard
538      * <code>javax_imageio_1.0</code> metadata format, or
539      * <code>null</code> if no such information is available. This
540      * method is intended to be called by the utility routine
541      * <code>getStandardTree</code>.
542      *
543      * <p> The default implementation returns <code>null</code>.
544      *
545      * <p> Subclasses should override this method to produce an
546      * appropriate subtree if they wish to support the standard
547      * metadata format.
548      *
549      * @return an <code>IIOMetadataNode</code>, or <code>null</code>.
550      *
551      * @see #getStandardTree
552      */
553     protected IIOMetadataNode getStandardDataNode() {
554         return null;
555     }
556
557     /**
558      * Returns an <code>IIOMetadataNode</code> representing the
559      * dimension information of the standard
560      * <code>javax_imageio_1.0</code> metadata format, or
561      * <code>null</code> if no such information is available. This
562      * method is intended to be called by the utility routine
563      * <code>getStandardTree</code>.
564      *
565      * <p> The default implementation returns <code>null</code>.
566      *
567      * <p> Subclasses should override this method to produce an
568      * appropriate subtree if they wish to support the standard
569      * metadata format.
570      *
571      * @return an <code>IIOMetadataNode</code>, or <code>null</code>.
572      *
573      * @see #getStandardTree
574      */
575     protected IIOMetadataNode getStandardDimensionNode() {
576         return null;
577     }
578
579     /**
580      * Returns an <code>IIOMetadataNode</code> representing the document
581      * information of the standard <code>javax_imageio_1.0</code>
582      * metadata format, or <code>null</code> if no such information is
583      * available. This method is intended to be called by the utility
584      * routine <code>getStandardTree</code>.
585      *
586      * <p> The default implementation returns <code>null</code>.
587      *
588      * <p> Subclasses should override this method to produce an
589      * appropriate subtree if they wish to support the standard
590      * metadata format.
591      *
592      * @return an <code>IIOMetadataNode</code>, or <code>null</code>.
593      *
594      * @see #getStandardTree
595      */
596     protected IIOMetadataNode getStandardDocumentNode() {
597         return null;
598     }
599
600     /**
601      * Returns an <code>IIOMetadataNode</code> representing the textual
602      * information of the standard <code>javax_imageio_1.0</code>
603      * metadata format, or <code>null</code> if no such information is
604      * available. This method is intended to be called by the utility
605      * routine <code>getStandardTree</code>.
606      *
607      * <p> The default implementation returns <code>null</code>.
608      *
609      * <p> Subclasses should override this method to produce an
610      * appropriate subtree if they wish to support the standard
611      * metadata format.
612      *
613      * @return an <code>IIOMetadataNode</code>, or <code>null</code>.
614      *
615      * @see #getStandardTree
616      */
617     protected IIOMetadataNode getStandardTextNode() {
618         return null;
619     }
620
621     /**
622      * Returns an <code>IIOMetadataNode</code> representing the tiling
623      * information of the standard <code>javax_imageio_1.0</code>
624      * metadata format, or <code>null</code> if no such information is
625      * available. This method is intended to be called by the utility
626      * routine <code>getStandardTree</code>.
627      *
628      * <p> The default implementation returns <code>null</code>.
629      *
630      * <p> Subclasses should override this method to produce an
631      * appropriate subtree if they wish to support the standard
632      * metadata format.
633      *
634      * @return an <code>IIOMetadataNode</code>, or <code>null</code>.
635      *
636      * @see #getStandardTree
637      */
638     protected IIOMetadataNode getStandardTileNode() {
639         return null;
640     }
641
642     /**
643      * Returns an <code>IIOMetadataNode</code> representing the
644      * transparency information of the standard
645      * <code>javax_imageio_1.0</code> metadata format, or
646      * <code>null</code> if no such information is available. This
647      * method is intended to be called by the utility routine
648      * <code>getStandardTree</code>.
649      *
650      * <p> The default implementation returns <code>null</code>.
651      *
652      * <p> Subclasses should override this method to produce an
653      * appropriate subtree if they wish to support the standard
654      * metadata format.
655      *
656      * @return an <code>IIOMetadataNode</code>, or <code>null</code>.
657      */
658     protected IIOMetadataNode getStandardTransparencyNode() {
659         return null;
660     }
661
662     /**
663      * Appends a new node to an existing node, if the new node is
664      * non-<code>null</code>.
665      */
666     private void append(IIOMetadataNode root, IIOMetadataNode node) {
667         if (node != null) {
668             root.appendChild(node);
669         }
670     }
671
672     /**
673      * A utility method to return a tree of
674      * <code>IIOMetadataNode</code>s representing the metadata
675      * contained within this object according to the conventions of
676      * the standard <code>javax_imageio_1.0</code> metadata format.
677      *
678      * <p> This method calls the various <code>getStandard*Node</code>
679      * methods to supply each of the subtrees rooted at the children
680      * of the root node. If any of those methods returns
681      * <code>null</code>, the corresponding subtree will be omitted.
682      * If all of them return <code>null</code>, a tree consisting of a
683      * single root node will be returned.
684      *
685      * @return an <code>IIOMetadataNode</code> representing the root
686      * of a metadata tree in the <code>javax_imageio_1.0</code>
687      * format.
688      *
689      * @see #getStandardChromaNode
690      * @see #getStandardCompressionNode
691      * @see #getStandardDataNode
692      * @see #getStandardDimensionNode
693      * @see #getStandardDocumentNode
694      * @see #getStandardTextNode
695      * @see #getStandardTileNode
696      * @see #getStandardTransparencyNode
697      */
698     protected final IIOMetadataNode getStandardTree() {
699         IIOMetadataNode root = new IIOMetadataNode
700                 (IIOMetadataFormatImpl.standardMetadataFormatName);
701         append(root, getStandardChromaNode());
702         append(root, getStandardCompressionNode());
703         append(root, getStandardDataNode());
704         append(root, getStandardDimensionNode());
705         append(root, getStandardDocumentNode());
706         append(root, getStandardTextNode());
707         append(root, getStandardTileNode());
708         append(root, getStandardTransparencyNode());
709         return root;
710     }
711
712     /**
713      * Sets the internal state of this <code>IIOMetadata</code> object
714      * from a tree of XML DOM <code>Node</code>s whose syntax is
715      * defined by the given metadata format. The previous state is
716      * discarded. If the tree's structure or contents are invalid, an
717      * <code>IIOInvalidTreeException</code> will be thrown.
718      *
719      * <p> The default implementation calls <code>reset</code>
720      * followed by <code>mergeTree(formatName, root)</code>.
721      *
722      * @param formatName the desired metadata format.
723      * @param root an XML DOM <code>Node</code> object forming the
724      * root of a tree.
725      *
726      * @exception IllegalStateException if this object is read-only.
727      * @exception IllegalArgumentException if <code>formatName</code>
728      * is <code>null</code> or is not one of the names returned by
729      * <code>getMetadataFormatNames</code>.
730      * @exception IllegalArgumentException if <code>root</code> is
731      * <code>null</code>.
732      * @exception IIOInvalidTreeException if the tree cannot be parsed
733      * successfully using the rules of the given format.
734      *
735      * @see #getMetadataFormatNames
736      * @see #getAsTree
737      * @see #mergeTree
738      */
739     public void setFromTree(String formatName, Node root)
740         throws IIOInvalidTreeException {
741         reset();
742         mergeTree(formatName, root);
743     }
744
745     /**
746      * Resets all the data stored in this object to default values,
747      * usually to the state this object was in immediately after
748      * construction, though the precise semantics are plug-in specific.
749      * Note that there are many possible default values, depending on
750      * how the object was created.
751      *
752      * @exception IllegalStateException if this object is read-only.
753      *
754      * @see javax.imageio.ImageReader#getStreamMetadata
755      * @see javax.imageio.ImageReader#getImageMetadata
756      * @see javax.imageio.ImageWriter#getDefaultStreamMetadata
757      * @see javax.imageio.ImageWriter#getDefaultImageMetadata
758      */
759     public abstract void reset();
760
761     /**
762      * Sets the <code>IIOMetadataController</code> to be used
763      * to provide settings for this <code>IIOMetadata</code>
764      * object when the <code>activateController</code> method
765      * is called, overriding any default controller. If the
766      * argument is <code>null</code>, no controller will be
767      * used, including any default. To restore the default, use
768      * <code>setController(getDefaultController())</code>.
769      *
770      * <p> The default implementation sets the <code>controller</code>
771      * instance variable to the supplied value.
772      *
773      * @param controller An appropriate
774      * <code>IIOMetadataController</code>, or <code>null</code>.
775      *
776      * @see IIOMetadataController
777      * @see #getController
778      * @see #getDefaultController
779      * @see #hasController
780      * @see #activateController()
781      */
782     public void setController(IIOMetadataController controller) {
783         this.controller = controller;
784     }
785
786     /**
787      * Returns whatever <code>IIOMetadataController</code> is currently
788      * installed. This could be the default if there is one,
789      * <code>null</code>, or the argument of the most recent call
790      * to <code>setController</code>.
791      *
792      * <p> The default implementation returns the value of the
793      * <code>controller</code> instance variable.
794      *
795      * @return the currently installed
796      * <code>IIOMetadataController</code>, or <code>null</code>.
797      *
798      * @see IIOMetadataController
799      * @see #setController
800      * @see #getDefaultController
801      * @see #hasController
802      * @see #activateController()
803      */
804     public IIOMetadataController getController() {
805         return controller;
806     }
807
808     /**
809      * Returns the default <code>IIOMetadataController</code>, if there
810      * is one, regardless of the currently installed controller. If
811      * there is no default controller, returns <code>null</code>.
812      *
813      * <p> The default implementation returns the value of the
814      * <code>defaultController</code> instance variable.
815      *
816      * @return the default <code>IIOMetadataController</code>, or
817      * <code>null</code>.
818      *
819      * @see IIOMetadataController
820      * @see #setController(IIOMetadataController)
821      * @see #getController
822      * @see #hasController
823      * @see #activateController()
824      */
825     public IIOMetadataController getDefaultController() {
826         return defaultController;
827     }
828
829     /**
830      * Returns <code>true</code> if there is a controller installed
831      * for this <code>IIOMetadata</code> object.
832      *
833      * <p> The default implementation returns <code>true</code> if the
834      * <code>getController</code> method returns a
835      * non-<code>null</code> value.
836      *
837      * @return <code>true</code> if a controller is installed.
838      *
839      * @see IIOMetadataController
840      * @see #setController(IIOMetadataController)
841      * @see #getController
842      * @see #getDefaultController
843      * @see #activateController()
844      */
845     public boolean hasController() {
846         return (getController() != null);
847     }
848
849     /**
850      * Activates the installed <code>IIOMetadataController</code> for
851      * this <code>IIOMetadata</code> object and returns the resulting
852      * value. When this method returns <code>true</code>, all values for this
853      * <code>IIOMetadata</code> object will be ready for the next write
854      * operation. If <code>false</code> is
855      * returned, no settings in this object will have been disturbed
856      * (<i>i.e.</i>, the user canceled the operation).
857      *
858      * <p> Ordinarily, the controller will be a GUI providing a user
859      * interface for a subclass of <code>IIOMetadata</code> for a
860      * particular plug-in. Controllers need not be GUIs, however.
861      *
862      * <p> The default implementation calls <code>getController</code>
863      * and the calls <code>activate</code> on the returned object if
864      * <code>hasController</code> returns <code>true</code>.
865      *
866      * @return <code>true</code> if the controller completed normally.
867      *
868      * @exception IllegalStateException if there is no controller
869      * currently installed.
870      *
871      * @see IIOMetadataController
872      * @see #setController(IIOMetadataController)
873      * @see #getController
874      * @see #getDefaultController
875      * @see #hasController
876      */
877     public boolean activateController() {
878         if (!hasController()) {
879             throw new IllegalStateException ("hasController() == false!");
880         }
881         return getController().activate(this);
882     }
883 }
884

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags