Java > Open Source Codes > javax > imageio > ImageReader


1 /*
2  * @(#)ImageReader.java 1.140 03/08/27
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;
9
10 import java.awt.Point ;
11 import java.awt.Rectangle ;
12 import java.awt.image.BufferedImage ;
13 import java.awt.image.Raster ;
14 import java.awt.image.RenderedImage ;
15 import java.io.IOException ;
16 import java.util.ArrayList ;
17 import java.util.Iterator ;
18 import java.util.List ;
19 import java.util.Locale ;
20 import java.util.MissingResourceException ;
21 import java.util.ResourceBundle ;
22 import java.util.Set ;
23 import javax.imageio.spi.ImageReaderSpi ;
24 import javax.imageio.event.IIOReadWarningListener ;
25 import javax.imageio.event.IIOReadProgressListener ;
26 import javax.imageio.event.IIOReadUpdateListener ;
27 import javax.imageio.metadata.IIOMetadata ;
28 import javax.imageio.metadata.IIOMetadataFormatImpl ;
29 import javax.imageio.stream.ImageInputStream ;
30
31 /**
32  * An abstract superclass for parsing and decoding of images. This
33  * class must be subclassed by classes that read in images in the
34  * context of the Java Image I/O framework.
35  *
36  * <p> <code>ImageReader</code> objects are normally instantiated by
37  * the service provider interface (SPI) class for the specific format.
38  * Service provider classes (e.g., instances of
39  * <code>ImageReaderSpi</code>) are registered with the
40  * <code>IIORegistry</code>, which uses them for format recognition
41  * and presentation of available format readers and writers.
42  *
43  * <p> When an input source is set (using the <code>setInput</code>
44  * method), it may be marked as "seek forward only". This setting
45  * means that images contained within the input source will only be
46  * read in order, possibly allowing the reader to avoid caching
47  * portions of the input containing data associated with images that
48  * have been read previously.
49  *
50  * @see ImageWriter
51  * @see javax.imageio.spi.IIORegistry
52  * @see javax.imageio.spi.ImageReaderSpi
53  *
54  * @version 0.5
55  */
56 public abstract class ImageReader {
57
58     /**
59      * The <code>ImageReaderSpi</code> that instantiated this object,
60      * or <code>null</code> if its identity is not known or none
61      * exists. By default it is initialized to <code>null</code>.
62      */
63     protected ImageReaderSpi originatingProvider;
64
65     /**
66      * The <code>ImageInputStream</code> or other
67      * <code>Object</code> by <code>setInput</code> and retrieved
68      * by <code>getInput</code>. By default it is initialized to
69      * <code>null</code>.
70      */
71     protected Object input = null;
72
73     /**
74      * <code>true</code> if the current input source has been marked
75      * as allowing only forward seeking by <code>setInput</code>. By
76      * default, the value is <code>false</code>.
77      *
78      * @see #minIndex
79      * @see #setInput
80      */
81     protected boolean seekForwardOnly = false;
82
83     /**
84      * <code>true</code> if the current input source has been marked
85      * as allowing metadata to be ignored by <code>setInput</code>.
86      * By default, the value is <code>false</code>.
87      *
88      * @see #setInput
89      */
90     protected boolean ignoreMetadata = false;
91
92     /**
93      * The smallest valid index for reading, initially 0. When
94      * <code>seekForwardOnly</code> is <code>true</code>, various methods
95      * may throw an <code>IndexOutOfBoundsException</code> on an
96      * attempt to access data associate with an image having a lower
97      * index.
98      *
99      * @see #seekForwardOnly
100      * @see #setInput
101      */
102     protected int minIndex = 0;
103
104     /**
105      * An array of <code>Locale</code>s which may be used to localize
106      * warning messages, or <code>null</code> if localization is not
107      * supported.
108      */
109     protected Locale [] availableLocales = null;
110
111     /**
112      * The current <code>Locale</code> to be used for localization, or
113      * <code>null</code> if none has been set.
114      */
115     protected Locale locale = null;
116
117     /**
118      * A <code>List</code> of currently registered
119      * <code>IIOReadWarningListener</code>s, initialized by default to
120      * <code>null</code>, which is synonymous with an empty
121      * <code>List</code>.
122      */
123     protected List <IIOReadWarningListener > warningListeners = null;
124
125     /**
126      * A <code>List</code> of the <code>Locale</code>s associated with
127      * each currently registered <code>IIOReadWarningListener</code>,
128      * initialized by default to <code>null</code>, which is
129      * synonymous with an empty <code>List</code>.
130      */
131     protected List <Locale > warningLocales = null;
132
133     /**
134      * A <code>List</code> of currently registered
135      * <code>IIOReadProgressListener</code>s, initialized by default
136      * to <code>null</code>, which is synonymous with an empty
137      * <code>List</code>.
138      */
139     protected List <IIOReadProgressListener > progressListeners = null;
140
141     /**
142      * A <code>List</code> of currently registered
143      * <code>IIOReadUpdateListener</code>s, initialized by default to
144      * <code>null</code>, which is synonymous with an empty
145      * <code>List</code>.
146      */
147     protected List <IIOReadUpdateListener > updateListeners = null;
148     
149     /**
150      * If <code>true</code>, the current read operation should be
151      * aborted.
152      */
153     private boolean abortFlag = false;
154
155     /**
156      * Constructs an <code>ImageReader</code> and sets its
157      * <code>originatingProvider</code> field to the supplied value.
158      *
159      * <p> Subclasses that make use of extensions should provide a
160      * constructor with signature <code>(ImageReaderSpi,
161      * Object)</code> in order to retrieve the extension object. If
162      * the extension object is unsuitable, an
163      * <code>IllegalArgumentException</code> should be thrown.
164      *
165      * @param originatingProvider the <code>ImageReaderSpi</code> that is
166      * invoking this constructor, or <code>null</code>.
167      */
168     protected ImageReader(ImageReaderSpi originatingProvider) {
169         this.originatingProvider = originatingProvider;
170     }
171
172     /**
173      * Returns a <code>String</code> identifying the format of the
174      * input source.
175      *
176      * <p> The default implementation returns
177      * <code>originatingProvider.getFormatNames()[0]</code>.
178      * Implementations that may not have an originating service
179      * provider, or which desire a different naming policy should
180      * override this method.
181      *
182      * @exception IOException if an error occurs reading the
183      * information from the input source.
184      *
185      * @return the format name, as a <code>String</code>.
186      */
187     public String getFormatName() throws IOException {
188         return originatingProvider.getFormatNames()[0];
189     }
190
191     /**
192      * Returns the <code>ImageReaderSpi</code> that was passed in on
193      * the constructor. Note that this value may be <code>null</code>.
194      *
195      * @return an <code>ImageReaderSpi</code>, or <code>null</code>.
196      *
197      * @see ImageReaderSpi
198      */
199     public ImageReaderSpi getOriginatingProvider() {
200         return originatingProvider;
201     }
202
203     /**
204      * Sets the input source to use to the given
205      * <code>ImageInputStream</code> or other <code>Object</code>.
206      * The input source must be set before any of the query or read
207      * methods are used. If <code>input</code> is <code>null</code>,
208      * any currently set input source will be removed. In any case,
209      * the value of <code>minIndex</code> will be initialized to 0.
210      *
211      * <p> The <code>seekForwardOnly</code> parameter controls whether
212      * the value returned by <code>getMinIndex</code> will be
213      * increased as each image (or thumbnail, or image metadata) is
214      * read. If <code>seekForwardOnly</code> is true, then a call to
215      * <code>read(index)</code> will throw an
216      * <code>IndexOutOfBoundsException</code> if <code>index &lt
217      * this.minIndex</code>; otherwise, the value of
218      * <code>minIndex</code> will be set to <code>index</code>. If
219      * <code>seekForwardOnly</code> is <code>false</code>, the value of
220      * <code>minIndex</code> will remain 0 regardless of any read
221      * operations.
222      *
223      * <p> The <code>ignoreMetadata</code> parameter, if set to
224      * <code>true</code>, allows the reader to disregard any metadata
225      * encountered during the read. Subsequent calls to the
226      * <code>getStreamMetadata</code> and
227      * <code>getImageMetadata</code> methods may return
228      * <code>null</code>, and an <code>IIOImage</code> returned from
229      * <code>readAll</code> may return <code>null</code> from their
230      * <code>getMetadata</code> method. Setting this parameter may
231      * allow the reader to work more efficiently. The reader may
232      * choose to disregard this setting and return metadata normally.
233      *
234      * <p> Subclasses should take care to remove any cached
235      * information based on the previous stream, such as header
236      * information or partially decoded image data.
237      *
238      * <p> Use of a general <code>Object</code> other than an
239      * <code>ImageInputStream</code> is intended for readers that
240      * interact directly with a capture device or imaging protocol.
241      * The set of legal classes is advertised by the reader's service
242      * provider's <code>getInputTypes</code> method; most readers
243      * will return a single-element array containing only
244      * <code>ImageInputStream.class</code> to indicate that they
245      * accept only an <code>ImageInputStream</code>.
246      *
247      * <p> The default implementation checks the <code>input</code>
248      * argument against the list returned by
249      * <code>originatingProvider.getInputTypes()</code> and fails
250      * if the argument is not an instance of one of the classes
251      * in the list. If the originating provider is set to
252      * <code>null</code>, the input is accepted only if it is an
253      * <code>ImageInputStream</code>.
254      *
255      * @param input the <code>ImageInputStream</code> or other
256      * <code>Object</code> to use for future decoding.
257      * @param seekForwardOnly if <code>true</code>, images and metadata
258      * may only be read in ascending order from this input source.
259      * @param ignoreMetadata if <code>true</code>, metadata
260      * may be ignored during reads.
261      *
262      * @exception IllegalArgumentException if <code>input</code> is
263      * not an instance of one of the classes returned by the
264      * originating service provider's <code>getInputTypes</code>
265      * method, or is not an <code>ImageInputStream</code>.
266      *
267      * @see ImageInputStream
268      * @see #getInput
269      * @see javax.imageio.spi.ImageReaderSpi#getInputTypes
270      */
271     public void setInput(Object input,
272                          boolean seekForwardOnly,
273                          boolean ignoreMetadata) {
274         if (input != null) {
275             boolean found = false;
276             if (originatingProvider != null) {
277                 Class [] classes = originatingProvider.getInputTypes();
278                 for (int i = 0; i < classes.length; i++) {
279                     if (classes[i].isInstance(input)) {
280                         found = true;
281                         break;
282                     }
283                 }
284             } else {
285                 if (input instanceof ImageInputStream ) {
286                     found = true;
287                 }
288             }
289             if (!found) {
290                 throw new IllegalArgumentException ("Incorrect input type!");
291             }
292
293             this.seekForwardOnly = seekForwardOnly;
294             this.ignoreMetadata = ignoreMetadata;
295             this.minIndex = 0;
296         }
297
298         this.input = input;
299     }
300
301     /**
302      * Sets the input source to use to the given
303      * <code>ImageInputStream</code> or other <code>Object</code>.
304      * The input source must be set before any of the query or read
305      * methods are used. If <code>input</code> is <code>null</code>,
306      * any currently set input source will be removed. In any case,
307      * the value of <code>minIndex</code> will be initialized to 0.
308      *
309      * <p> The <code>seekForwardOnly</code> parameter controls whether
310      * the value returned by <code>getMinIndex</code> will be
311      * increased as each image (or thumbnail, or image metadata) is
312      * read. If <code>seekForwardOnly</code> is true, then a call to
313      * <code>read(index)</code> will throw an
314      * <code>IndexOutOfBoundsException</code> if <code>index &lt
315      * this.minIndex</code>; otherwise, the value of
316      * <code>minIndex</code> will be set to <code>index</code>. If
317      * <code>seekForwardOnly</code> is <code>false</code>, the value of
318      * <code>minIndex</code> will remain 0 regardless of any read
319      * operations.
320      *
321      * <p> This method is equivalent to <code>setInput(input,
322      * seekForwardOnly, false)</code>.
323      *
324      * @param input the <code>ImageInputStream</code> or other
325      * <code>Object</code> to use for future decoding.
326      * @param seekForwardOnly if <code>true</code>, images and metadata
327      * may only be read in ascending order from this input source.
328      *
329      * @exception IllegalArgumentException if <code>input</code> is
330      * not an instance of one of the classes returned by the
331      * originating service provider's <code>getInputTypes</code>
332      * method, or is not an <code>ImageInputStream</code>.
333      *
334      * @see #getInput
335      */
336     public void setInput(Object input,
337                          boolean seekForwardOnly) {
338         setInput(input, seekForwardOnly, false);
339     }
340
341     /**
342      * Sets the input source to use to the given
343      * <code>ImageInputStream</code> or other <code>Object</code>.
344      * The input source must be set before any of the query or read
345      * methods are used. If <code>input</code> is <code>null</code>,
346      * any currently set input source will be removed. In any case,
347      * the value of <code>minIndex</code> will be initialized to 0.
348      *
349      * <p> This method is equivalent to <code>setInput(input, false,
350      * false)</code>.
351      *
352      * @param input the <code>ImageInputStream</code> or other
353      * <code>Object</code> to use for future decoding.
354      *
355      * @exception IllegalArgumentException if <code>input</code> is
356      * not an instance of one of the classes returned by the
357      * originating service provider's <code>getInputTypes</code>
358      * method, or is not an <code>ImageInputStream</code>.
359      *
360      * @see #getInput
361      */
362     public void setInput(Object input) {
363         setInput(input, false, false);
364     }
365
366     /**
367      * Returns the <code>ImageInputStream</code> or other
368      * <code>Object</code> previously set as the input source. If the
369      * input source has not been set, <code>null</code> is returned.
370      *
371      * @return the <code>Object</code> that will be used for future
372      * decoding, or <code>null</code>.
373      *
374      * @see ImageInputStream
375      * @see #setInput
376      */
377     public Object getInput() {
378         return input;
379     }
380
381     /**
382      * Returns <code>true</code> if the current input source has been
383      * marked as seek forward only by passing <code>true</code> as the
384      * <code>seekForwardOnly</code> argument to the
385      * <code>setInput</code> method.
386      *
387      * @return <code>true</code> if the input source is seek forward
388      * only.
389      *
390      * @see #setInput
391      */
392     public boolean isSeekForwardOnly() {
393         return seekForwardOnly;
394     }
395
396     /**
397      * Returns <code>true</code> if the current input source has been
398      * marked as allowing metadata to be ignored by passing
399      * <code>true</code> as the <code>ignoreMetadata</code> argument
400      * to the <code>setInput</code> method.
401      *
402      * @return <code>true</code> if the metadata may be ignored.
403      *
404      * @see #setInput
405      */
406     public boolean isIgnoringMetadata() {
407         return ignoreMetadata;
408     }
409
410     /**
411      * Returns the lowest valid index for reading an image, thumbnail,
412      * or image metadata. If <code>seekForwardOnly()</code> is
413      * <code>false</code>, this value will typically remain 0,
414      * indicating that random access is possible. Otherwise, it will
415      * contain the value of the most recently accessed index, and
416      * increase in a monotonic fashion.
417      *
418      * @return the minimum legal index for reading.
419      */
420     public int getMinIndex() {
421         return minIndex;
422     }
423
424     // Localization
425
426     /**
427      * Returns an array of <code>Locale</code>s that may be used to
428      * localize warning listeners and compression settings. A return
429      * value of <code>null</code> indicates that localization is not
430      * supported.
431      *
432      * <p> The default implementation returns a clone of the
433      * <code>availableLocales</code> instance variable if it is
434      * non-<code>null</code>, or else returns <code>null</code>.
435      *
436      * @return an array of <code>Locale</code>s that may be used as
437      * arguments to <code>setLocale</code>, or <code>null</code>.
438      */
439     public Locale [] getAvailableLocales() {
440         if (availableLocales == null) {
441             return null;
442         } else {
443             return (Locale [])availableLocales.clone();
444         }
445     }
446
447     /**
448      * Sets the current <code>Locale</code> of this
449      * <code>ImageReader</code> to the given value. A value of
450      * <code>null</code> removes any previous setting, and indicates
451      * that the reader should localize as it sees fit.
452      *
453      * @param locale the desired <code>Locale</code>, or
454      * <code>null</code>.
455      *
456      * @exception IllegalArgumentException if <code>locale</code> is
457      * non-<code>null</code> but is not one of the values returned by
458      * <code>getAvailableLocales</code>.
459      *
460      * @see #getLocale
461      */
462     public void setLocale(Locale locale) {
463         if (locale != null) {
464             Locale [] locales = getAvailableLocales();
465             boolean found = false;
466             if (locales != null) {
467                 for (int i = 0; i < locales.length; i++) {
468                     if (locale.equals(locales[i])) {
469                         found = true;
470                         break;
471                     }
472                 }
473             }
474             if (!found) {
475                 throw new IllegalArgumentException ("Invalid locale!");
476             }
477         }
478         this.locale = locale;
479     }
480
481     /**
482      * Returns the currently set <code>Locale</code>, or
483      * <code>null</code> if none has been set.
484      *
485      * @return the current <code>Locale</code>, or <code>null</code>.
486      *
487      * @see #setLocale
488      */
489     public Locale getLocale() {
490         return locale;
491     }
492
493     // Image queries
494
495     /**
496      * Returns the number of images, not including thumbnails, available
497      * from the current input source.
498      *
499      * <p> Note that some image formats (such as animated GIF) do not
500      * specify how many images are present in the stream. Thus
501      * determining the number of images will require the entire stream
502      * to be scanned and may require memory for buffering. If images
503      * are to be processed in order, it may be more efficient to
504      * simply call <code>read</code> with increasing indices until an
505      * <code>IndexOutOfBoundsException</code> is thrown to indicate
506      * that no more images are available. The
507      * <code>allowSearch</code> parameter may be set to
508      * <code>false</code> to indicate that an exhaustive search is not
509      * desired; the return value will be <code>-1</code> to indicate
510      * that a search is necessary. If the input has been specified
511      * with <code>seekForwardOnly</code> set to <code>true</code>,
512      * this method throws an <code>IllegalStateException</code> if
513      * <code>allowSearch</code> is set to <code>true</code>.
514      *
515      * @param allowSearch if <code>true</code>, the true number of
516      * images will be returned even if a search is required. If
517      * <code>false</code>, the reader may return <code>-1</code>
518      * without performing the search.
519      *
520      * @return the number of images, as an <code>int</code>, or
521      * <code>-1</code> if <code>allowSearch</code> is
522      * <code>false</code> and a search would be required.
523      *
524      * @exception IllegalStateException if the input source has not been set,
525      * or if the input has been specified with <code>seekForwardOnly</code>
526      * set to <code>true</code>.
527      * @exception IOException if an error occurs reading the
528      * information from the input source.
529      *
530      * @see #setInput
531      */
532     public abstract int getNumImages(boolean allowSearch) throws IOException ;
533
534     /**
535      * Returns the width in pixels of the given image within the input
536      * source.
537      *
538      * <p> If the image can be rendered to a user-specified size, then
539      * this method returns the default width.
540      *
541      * @param imageIndex the index of the image to be queried.
542      *
543      * @return the width of the image, as an <code>int</code>.
544      *
545      * @exception IllegalStateException if the input source has not been set.
546      * @exception IndexOutOfBoundsException if the supplied index is
547      * out of bounds.
548      * @exception IOException if an error occurs reading the width
549      * information from the input source.
550      */
551     public abstract int getWidth(int imageIndex) throws IOException ;
552
553     /**
554      * Returns the height in pixels of the given image within the
555      * input source.
556      *
557      * <p> If the image can be rendered to a user-specified size, then
558      * this method returns the default height.
559      *
560      * @param imageIndex the index of the image to be queried.
561      *
562      * @return the height of the image, as an <code>int</code>.
563      *
564      * @exception IllegalStateException if the input source has not been set.
565      * @exception IndexOutOfBoundsException if the supplied index is
566      * out of bounds.
567      * @exception IOException if an error occurs reading the height
568      * information from the input source.
569      */
570     public abstract int getHeight(int imageIndex) throws IOException ;
571
572     /**
573      * Returns <code>true</code> if the storage format of the given
574      * image places no inherent impediment on random access to pixels.
575      * For most compressed formats, such as JPEG, this method should
576      * return <code>false</code>, as a large section of the image in
577      * addition to the region of interest may need to be decoded.
578      *
579      * <p> This is merely a hint for programs that wish to be
580      * efficient; all readers must be able to read arbitrary regions
581      * as specified in an <code>ImageReadParam</code>.
582      *
583      * <p> Note that formats that return <code>false</code> from
584      * this method may nonetheless allow tiling (<i>e.g.</i> Restart
585      * Markers in JPEG), and random access will likely be reasonably
586      * efficient on tiles. See {@link #isImageTiled
587      * <code>isImageTiled</code>}.
588      *
589      * <p> A reader for which all images are guaranteed to support
590      * easy random access, or are guaranteed not to support easy
591      * random access, may return <code>true</code> or
592      * <code>false</code> respectively without accessing any image
593      * data. In such cases, it is not necessary to throw an exception
594      * even if no input source has been set or the image index is out
595      * of bounds.
596      *
597      * <p> The default implementation returns <code>false</code>.
598      *
599      * @param imageIndex the index of the image to be queried.
600      *
601      * @return <code>true</code> if reading a region of interest of
602      * the given image is likely to be efficient.
603      *
604      * @exception IllegalStateException if an input source is required
605      * to determine the return value, but none has been set.
606      * @exception IndexOutOfBoundsException if an image must be
607      * accessed to determine the return value, but the supplied index
608      * is out of bounds.
609      * @exception IOException if an error occurs during reading.
610      */
611     public boolean isRandomAccessEasy(int imageIndex) throws IOException {
612         return false;
613     }
614
615     /**
616      * Returns the aspect ratio of the given image (that is, its width
617      * divided by its height) as a <code>float</code>. For images
618      * that are inherently resizable, this method provides a way to
619      * determine the appropriate width given a deired height, or vice
620      * versa. For non-resizable images, the true width and height
621      * are used.
622      *
623      * <p> The default implementation simply returns
624      * <code>(float)getWidth(imageIndex)/getHeight(imageIndex)</code>.
625      *
626      * @param imageIndex the index of the image to be queried.
627      *
628      * @return a <code>float</code> indicating the aspect ratio of the
629      * given image.
630      *
631      * @exception IllegalStateException if the input source has not been set.
632      * @exception IndexOutOfBoundsException if the supplied index is
633      * out of bounds.
634      * @exception IOException if an error occurs during reading.
635      */
636     public float getAspectRatio(int imageIndex) throws IOException {
637         return (float)getWidth(imageIndex)/getHeight(imageIndex);
638     }
639
640     /**
641      * Returns an <code>ImageTypeSpecifier</code> indicating the
642      * <code>SampleModel</code> and <code>ColorModel</code> which most
643      * closely represents the "raw" internal format of the image. For
644      * example, for a JPEG image the raw type might have a YCbCr color
645      * space even though the image would conventionally be transformed
646      * into an RGB color space prior to display. The returned value
647      * should also be included in the list of values returned by
648      * <code>getImageTypes</code>.
649      *
650      * <p> The default implementation simply returns the first entry
651      * from the list provided by <code>getImageType</code>.
652      *
653      * @param imageIndex the index of the image to be queried.
654      *
655      * @return an <code>ImageTypeSpecifier</code>.
656      *
657      * @exception IllegalStateException if the input source has not been set.
658      * @exception IndexOutOfBoundsException if the supplied index is
659      * out of bounds.
660      * @exception IOException if an error occurs reading the format
661      * information from the input source.
662      */
663     public ImageTypeSpecifier getRawImageType(int imageIndex)
664         throws IOException {
665         return (ImageTypeSpecifier )getImageTypes(imageIndex).next();
666     }
667
668     /**
669      * Returns an <code>Iterator</code> containing possible image
670      * types to which the given image may be decoded, in the form of
671      * <code>ImageTypeSpecifiers</code>s. At least one legal image
672      * type will be returned.
673      *
674      * <p> The first element of the iterator should be the most
675      * "natural" type for decoding the image with as little loss as
676      * possible. For example, for a JPEG image the first entry should
677      * be an RGB image, even though the image data is stored
678      * internally in a YCbCr color space.
679      *
680      * @param imageIndex the index of the image to be
681      * <code>retrieved</code>.
682      *
683      * @return an <code>Iterator</code> containing at least one
684      * <code>ImageTypeSpecifier</code> representing suggested image
685      * types for decoding the current given image.
686      *
687      * @exception IllegalStateException if the input source has not been set.
688      * @exception IndexOutOfBoundsException if the supplied index is
689      * out of bounds.
690      * @exception IOException if an error occurs reading the format
691      * information from the input source.
692      *
693      * @see ImageReadParam#setDestination(BufferedImage)
694      * @see ImageReadParam#setDestinationType(ImageTypeSpecifier)
695      */
696     public abstract Iterator <ImageTypeSpecifier >
697     getImageTypes(int imageIndex) throws IOException ;
698
699     /**
700      * Returns a default <code>ImageReadParam</code> object
701      * appropriate for this format. All subclasses should define a
702      * set of default values for all parameters and return them with
703      * this call. This method may be called before the input source
704      * is set.
705      *
706      * <p> The default implementation constructs and returns a new
707      * <code>ImageReadParam</code> object that does not allow source
708      * scaling (<i>i.e.</i>, it returns <code>new
709      * ImageReadParam()</code>.
710      *
711      * @return an <code>ImageReadParam</code> object which may be used
712      * to control the decoding process using a set of default settings.
713      */
714     public ImageReadParam getDefaultReadParam() {
715         return new ImageReadParam ();
716     }
717
718     /**
719      * Returns an <code>IIOMetadata</code> object representing the
720      * metadata associated with the input source as a whole (i.e., not
721      * associated with any particular image), or <code>null</code> if
722      * the reader does not support reading metadata, is set to ignore
723      * metadata, or if no metadata is available.
724      *
725      * @return an <code>IIOMetadata</code> object, or <code>null</code>.
726      *
727      * @exception IOException if an error occurs during reading.
728      */
729     public abstract IIOMetadata getStreamMetadata() throws IOException ;
730
731     /**
732      * Returns an <code>IIOMetadata</code> object representing the
733      * metadata associated with the input source as a whole (i.e.,
734      * not associated with any particular image). If no such data
735      * exists, <code>null</code> is returned.
736      *
737      * <p> The resuting metadata object is only responsible for
738      * returning documents in the format named by
739      * <code>formatName</code>. Within any documents that are
740      * returned, only nodes whose names are members of
741      * <code>nodeNames</code> are required to be returned. In this
742      * way, the amount of metadata processing done by the reader may
743      * be kept to a minimum, based on what information is actually
744      * needed.
745      *
746      * <p> If <code>formatName</code> is not the name of a supported
747      * metadata format, <code>null</code> is returned.
748      *
749      * <p> In all cases, it is legal to return a more capable metadata
750      * object than strictly necessary. The format name and node names
751      * are merely hints that may be used to reduce the reader's
752      * workload.
753      *
754      * <p> The default implementation simply returns the result of
755      * calling <code>getStreamMetadata()</code>, after checking that
756      * the format name is supported. If it is not,
757      * <code>null</code> is returned.
758      *
759      * @param formatName a metadata format name that may be used to retrieve
760      * a document from the returned <code>IIOMetadata</code> object.
761      * @param nodeNames a <code>Set</code> containing the names of
762      * nodes that may be contained in a retrieved document.
763      *
764      * @return an <code>IIOMetadata</code> object, or <code>null</code>.
765      *
766      * @exception IllegalArgumentException if <code>formatName</code>
767      * is <code>null</code>.
768      * @exception IllegalArgumentException if <code>nodeNames</code>
769      * is <code>null</code>.
770      * @exception IOException if an error occurs during reading.
771      */
772     public IIOMetadata getStreamMetadata(String formatName,
773                      Set <String > nodeNames)
774         throws IOException
775     {
776         return getMetadata(formatName, nodeNames, true, 0);
777     }
778
779     private IIOMetadata getMetadata(String formatName,
780                                     Set nodeNames,
781                                     boolean wantStream,
782                                     int imageIndex) throws IOException {
783         if (formatName == null) {
784             throw new IllegalArgumentException ("formatName == null!");
785         }
786         if (nodeNames == null) {
787             throw new IllegalArgumentException ("nodeNames == null!");
788         }
789         IIOMetadata metadata =
790             wantStream
791             ? getStreamMetadata()
792             : getImageMetadata(imageIndex);
793         if (metadata != null) {
794             if (metadata.isStandardMetadataFormatSupported() &&
795                 formatName.equals
796                 (IIOMetadataFormatImpl.standardMetadataFormatName)) {
797                 return metadata;
798             }
799             String nativeName = metadata.getNativeMetadataFormatName();
800             if (nativeName != null && formatName.equals(nativeName)) {
801                 return metadata;
802             }
803             String [] extraNames = metadata.getExtraMetadataFormatNames();
804             if (extraNames != null) {
805                 for (int i = 0; i < extraNames.length; i++) {
806                     if (formatName.equals(extraNames[i])) {
807                         return metadata;
808                     }
809                 }
810             }
811         }
812         return null;
813     }
814
815     /**
816      * Returns an <code>IIOMetadata</code> object containing metadata
817      * associated with the given image, or <code>null</code> if the
818      * reader does not support reading metadata, is set to ignore
819      * metadata, or if no metadata is available.
820      *
821      * @param imageIndex the index of the image whose metadata is to
822      * be retrieved.
823      *
824      * @return an <code>IIOMetadata</code> object, or
825      * <code>null</code>.
826      *
827      * @exception IllegalStateException if the input source has not been
828      * set.
829      * @exception IndexOutOfBoundsException if the supplied index is
830      * out of bounds.
831      * @exception IOException if an error occurs during reading.
832      */
833     public abstract IIOMetadata getImageMetadata(int imageIndex)
834         throws IOException ;
835
836     /**
837      * Returns an <code>IIOMetadata</code> object representing the
838      * metadata associated with the given image, or <code>null</code>
839      * if the reader does not support reading metadata or none
840      * is available.
841      *
842      * <p> The resuting metadata object is only responsible for
843      * returning documents in the format named by
844      * <code>formatName</code>. Within any documents that are
845      * returned, only nodes whose names are members of
846      * <code>nodeNames</code> are required to be returned. In this
847      * way, the amount of metadata processing done by the reader may
848      * be kept to a minimum, based on what information is actually
849      * needed.
850      *
851      * <p> If <code>formatName</code> is not the name of a supported
852      * metadata format, <code>null</code> may be returned.
853      *
854      * <p> In all cases, it is legal to return a more capable metadata
855      * object than strictly necessary. The format name and node names
856      * are merely hints that may be used to reduce the reader's
857      * workload.
858      *
859      * <p> The default implementation simply returns the result of
860      * calling <code>getImageMetadata(imageIndex)</code>, after
861      * checking that the format name is supported. If it is not,
862      * <code>null</code> is returned.
863      *
864      * @param imageIndex the index of the image whose metadata is to
865      * be retrieved.
866      * @param formatName a metadata format name that may be used to retrieve
867      * a document from the returned <code>IIOMetadata</code> object.
868      * @param nodeNames a <code>Set</code> containing the names of
869      * nodes that may be contained in a retrieved document.
870      *
871      * @return an <code>IIOMetadata</code> object, or <code>null</code>.
872      *
873      * @exception IllegalStateException if the input source has not been
874      * set.
875      * @exception IndexOutOfBoundsException if the supplied index is
876      * out of bounds.
877      * @exception IllegalArgumentException if <code>formatName</code>
878      * is <code>null</code>.
879      * @exception IllegalArgumentException if <code>nodeNames</code>
880      * is <code>null</code>.
881      * @exception IOException if an error occurs during reading.
882      */
883     public IIOMetadata getImageMetadata(int imageIndex,
884                                         String formatName,
885                     Set <String > nodeNames)
886         throws IOException {
887         return getMetadata(formatName, nodeNames, false, imageIndex);
888     }
889
890     /**
891      * Reads the image indexed by <code>imageIndex</code> and returns
892      * it as a complete <code>BufferedImage</code>, using a default
893      * <code>ImageReadParam</code>. This is a convenience method
894      * that calls <code>read(imageIndex, null)</code>.
895      *
896      * <p> The image returned will be formatted according to the first
897      * <code>ImageTypeSpecifier</code> returned from
898      * <code>getImageTypes</code>.
899      *
900      * <p> Any registered <code>IIOReadProgressListener</code> objects
901      * will be notified by calling their <code>imageStarted</code>
902      * method, followed by calls to their <code>imageProgress</code>
903      * method as the read progresses. Finally their
904      * <code>imageComplete</code> method will be called.
905      * <code>IIOReadUpdateListener</code> objects may be updated at
906      * other times during the read as pixels are decoded. Finally,
907      * <code>IIOReadWarningListener</code> objects will receive
908      * notification of any non-fatal warnings that occur during
909      * decoding.
910      *
911      * @param imageIndex the index of the image to be retrieved.
912      *
913      * @return the desired portion of the image as a
914      * <code>BufferedImage</code>.
915      *
916      * @exception IllegalStateException if the input source has not been
917      * set.
918      * @exception IndexOutOfBoundsException if the supplied index is
919      * out of bounds.
920      * @exception IOException if an error occurs during reading.
921   &nb