Java > Open Source Codes > javax > imageio > ImageWriter


1 /*
2  * @(#)ImageWriter.java 1.94 04/05/05
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.Dimension ;
11 import java.awt.Rectangle ;
12 import java.awt.image.BufferedImage ;
13 import java.awt.image.RenderedImage ;
14 import java.awt.image.Raster ;
15 import java.io.IOException ;
16 import java.util.ArrayList ;
17 import java.util.List ;
18 import java.util.Locale ;
19 import java.util.MissingResourceException ;
20 import java.util.ResourceBundle ;
21 import javax.imageio.event.IIOWriteWarningListener ;
22 import javax.imageio.event.IIOWriteProgressListener ;
23 import javax.imageio.metadata.IIOMetadata ;
24 import javax.imageio.stream.ImageOutputStream ;
25 import javax.imageio.spi.ImageWriterSpi ;
26
27 /**
28  * An abstract superclass for encoding and writing images. This class
29  * must be subclassed by classes that write out images in the context
30  * of the Java Image I/O framework.
31  *
32  * <p> <code>ImageWriter</code> objects are normally instantiated by
33  * the service provider class for the specific format. Service
34  * provider classes are registered with the <code>IIORegistry</code>,
35  * which uses them for format recognition and presentation of
36  * available format readers and writers.
37  *
38  * <p>
39  *
40  * @see ImageReader
41  * @see ImageWriteParam
42  * @see javax.imageio.spi.IIORegistry
43  * @see javax.imageio.spi.ImageWriterSpi
44  *
45  * @version 0.5
46  */
47 public abstract class ImageWriter implements ImageTranscoder {
48
49     /**
50      * The <code>ImageWriterSpi</code> that instantiated this object,
51      * or <code>null</code> if its identity is not known or none
52      * exists. By default it is initialized to <code>null</code>.
53      */
54     protected ImageWriterSpi originatingProvider = null;
55
56     /**
57      * The <code>ImageOutputStream</code> or other <code>Object</code>
58      * set by <code>setOutput</code> and retrieved by
59      * <code>getOutput</code>. By default it is initialized to
60      * <code>null</code>.
61      */
62     protected Object output = null;
63
64     /**
65      * An array of <code>Locale</code>s that may be used to localize
66      * warning messages and compression setting values, or
67      * <code>null</code> if localization is not supported. By default
68      * it is initialized to <code>null</code>.
69      */
70     protected Locale [] availableLocales = null;
71
72     /**
73      * The current <code>Locale</code> to be used for localization, or
74      * <code>null</code> if none has been set. By default it is
75      * initialized to <code>null</code>.
76      */
77     protected Locale locale = null;
78
79     /**
80      * A <code>List</code> of currently registered
81      * <code>IIOWriteWarningListener</code>s, initialized by default to
82      * <code>null</code>, which is synonymous with an empty
83      * <code>List</code>.
84      */
85     protected List <IIOWriteWarningListener > warningListeners = null;
86
87     /**
88      * A <code>List</code> of <code>Locale</code>s, one for each
89      * element of <code>warningListeners</code>, initialized by default
90      * <code>null</code>, which is synonymous with an empty
91      * <code>List</code>.
92      */
93     protected List <Locale > warningLocales = null;
94
95     /**
96      * A <code>List</code> of currently registered
97      * <code>IIOWriteProgressListener</code>s, initialized by default
98      * <code>null</code>, which is synonymous with an empty
99      * <code>List</code>.
100      */
101     protected List <IIOWriteProgressListener > progressListeners = null;
102
103     /**
104      * If <code>true</code>, the current write operation should be
105      * aborted.
106      */
107     private boolean abortFlag = false;
108
109     /**
110      * Constructs an <code>ImageWriter</code> and sets its
111      * <code>originatingProvider</code> instance variable to the
112      * supplied value.
113      *
114      * <p> Subclasses that make use of extensions should provide a
115      * constructor with signature <code>(ImageWriterSpi,
116      * Object)</code> in order to retrieve the extension object. If
117      * the extension object is unsuitable, an
118      * <code>IllegalArgumentException</code> should be thrown.
119      *
120      * @param originatingProvider the <code>ImageWriterSpi</code> that
121      * is constructing this object, or <code>null</code>.
122      */
123     protected ImageWriter(ImageWriterSpi originatingProvider) {
124         this.originatingProvider = originatingProvider;
125     }
126
127     /**
128      * Returns the <code>ImageWriterSpi</code> object that created
129      * this <code>ImageWriter</code>, or <code>null</code> if this
130      * object was not created through the <code>IIORegistry</code>.
131      *
132      * <p> The default implementation returns the value of the
133      * <code>originatingProvider</code> instance variable.
134      *
135      * @return an <code>ImageWriterSpi</code>, or <code>null</code>.
136      *
137      * @see ImageWriterSpi
138      */
139     public ImageWriterSpi getOriginatingProvider() {
140         return originatingProvider;
141     }
142
143     /**
144      * Sets the destination to the given
145      * <code>ImageOutputStream</code> or other <code>Object</code>.
146      * The destination is assumed to be ready to accept data, and will
147      * not be closed at the end of each write. This allows distributed
148      * imaging applications to transmit a series of images over a
149      * single network connection. If <code>output</code> is
150      * <code>null</code>, any currently set output will be removed.
151      *
152      * <p> If <code>output</code> is an
153      * <code>ImageOutputStream</code>, calls to the
154      * <code>write</code>, <code>writeToSequence</code>, and
155      * <code>prepareWriteEmpty</code>/<code>endWriteEmpty</code>
156      * methods will preserve the existing contents of the stream.
157      * Other write methods, such as <code>writeInsert</code>,
158      * <code>replaceStreamMetadata</code>,
159      * <code>replaceImageMetadata</code>, <code>replacePixels</code>,
160      * <code>prepareInsertEmpty</code>/<code>endInsertEmpty</code>,
161      * and <code>endWriteSequence</code>, require the full contents
162      * of the stream to be readable and writable, and may alter any
163      * portion of the stream.
164      *
165      * <p> Use of a general <code>Object</code> other than an
166      * <code>ImageOutputStream</code> is intended for writers that
167      * interact directly with an output device or imaging protocol.
168      * The set of legal classes is advertised by the writer's service
169      * provider's <code>getOutputTypes</code> method; most writers
170      * will return a single-element array containing only
171      * <code>ImageOutputStream.class</code> to indicate that they
172      * accept only an <code>ImageOutputStream</code>.
173      *
174      * <p> The default implementation sets the <code>output</code>
175      * instance variable to the value of <code>output</code> after
176      * checking <code>output</code> against the set of classes
177      * advertised by the originating provider, if there is one.
178      *
179      * @param output the <code>ImageOutputStream</code> or other
180      * <code>Object</code> to use for future writing.
181      *
182      * @exception IllegalArgumentException if <code>output</code> is
183      * not an instance of one of the classes returned by the
184      * originating service provider's <code>getOutputTypes</code>
185      * method.
186      *
187      * @see #getOutput
188      */
189     public void setOutput(Object output) {
190         if (output != null) {
191             ImageWriterSpi provider = getOriginatingProvider();
192             if (provider != null) {
193                 Class [] classes = provider.getOutputTypes();
194                 boolean found = false;
195                 for (int i = 0; i < classes.length; i++) {
196                     if (classes[i].isInstance(output)) {
197                         found = true;
198                         break;
199                     }
200                 }
201                 if (!found) {
202                     throw new IllegalArgumentException ("Illegal output type!");
203                 }
204             }
205         }
206
207         this.output = output;
208     }
209
210     /**
211      * Returns the <code>ImageOutputStream</code> or other
212      * <code>Object</code> set by the most recent call to the
213      * <code>setOutput</code> method. If no destination has been
214      * set, <code>null</code> is returned.
215      *
216      * <p> The default implementation returns the value of the
217      * <code>output</code> instance variable.
218      *
219      * @return the <code>Object</code> that was specified using
220      * <code>setOutput</code>, or <code>null</code>.
221      *
222      * @see #setOutput
223      */
224     public Object getOutput() {
225         return output;
226     }
227
228     // Localization
229
230     /**
231      * Returns an array of <code>Locale</code>s that may be used to
232      * localize warning listeners and compression settings. A return
233      * value of <code>null</code> indicates that localization is not
234      * supported.
235      *
236      * <p> The default implementation returns a clone of the
237      * <code>availableLocales</code> instance variable if it is
238      * non-<code>null</code>, or else returns <code>null</code>.
239      *
240      * @return an array of <code>Locale</code>s that may be used as
241      * arguments to <code>setLocale</code>, or <code>null</code>.
242      */
243     public Locale [] getAvailableLocales() {
244         return (availableLocales == null) ?
245             null : (Locale [])availableLocales.clone();
246     }
247
248     /**
249      * Sets the current <code>Locale</code> of this
250      * <code>ImageWriter</code> to the given value. A value of
251      * <code>null</code> removes any previous setting, and indicates
252      * that the writer should localize as it sees fit.
253      *
254      * <p> The default implementation checks <code>locale</code>
255      * against the values returned by
256      * <code>getAvailableLocales</code>, and sets the
257      * <code>locale</code> instance variable if it is found. If
258      * <code>locale</code> is <code>null</code>, the instance variable
259      * is set to <code>null</code> without any checking.
260      *
261      * @param locale the desired <code>Locale</code>, or
262      * <code>null</code>.
263      *
264      * @exception IllegalArgumentException if <code>locale</code> is
265      * non-<code>null</code> but is not one of the values returned by
266      * <code>getAvailableLocales</code>.
267      *
268      * @see #getLocale
269      */
270     public void setLocale(Locale locale) {
271         if (locale != null) {
272             Locale [] locales = getAvailableLocales();
273             boolean found = false;
274             if (locales != null) {
275                 for (int i = 0; i < locales.length; i++) {
276                     if (locale.equals(locales[i])) {
277                         found = true;
278                         break;
279                     }
280                 }
281             }
282             if (!found) {
283                 throw new IllegalArgumentException ("Invalid locale!");
284             }
285         }
286         this.locale = locale;
287     }
288
289     /**
290      * Returns the currently set <code>Locale</code>, or
291      * <code>null</code> if none has been set.
292      *
293      * <p> The default implementation returns the value of the
294      * <code>locale</code> instance variable.
295      *
296      * @return the current <code>Locale</code>, or <code>null</code>.
297      *
298      * @see #setLocale
299      */
300     public Locale getLocale() {
301         return locale;
302     }
303
304     // Write params
305
306     /**
307      * Returns a new <code>ImageWriteParam</code> object of the
308      * appropriate type for this file format containing default
309      * values, that is, those values that would be used
310      * if no <code>ImageWriteParam</code> object were specified. This
311      * is useful as a starting point for tweaking just a few parameters
312      * and otherwise leaving the default settings alone.
313      *
314      * <p> The default implementation constructs and returns a new
315      * <code>ImageWriteParam</code> object that does not allow tiling,
316      * progressive encoding, or compression, and that will be
317      * localized for the current <code>Locale</code> (<i>i.e.</i>,
318      * what you would get by calling <code>new
319      * ImageWriteParam(getLocale())</code>.
320      *
321      * <p> Individual plug-ins may return an instance of
322      * <code>ImageWriteParam</code> with additional optional features
323      * enabled, or they may return an instance of a plug-in specific
324      * subclass of <code>ImageWriteParam</code>.
325      *
326      * @return a new <code>ImageWriteParam</code> object containing
327      * default values.
328      */
329     public ImageWriteParam getDefaultWriteParam() {
330         return new ImageWriteParam (getLocale());
331     }
332
333     // Metadata
334
335     /**
336      * Returns an <code>IIOMetadata</code> object containing default
337      * values for encoding a stream of images. The contents of the
338      * object may be manipulated using either the XML tree structure
339      * returned by the <code>IIOMetadata.getAsTree</code> method, an
340      * <code>IIOMetadataController</code> object, or via plug-in
341      * specific interfaces, and the resulting data supplied to one of
342      * the <code>write</code> methods that take a stream metadata
343      * parameter.
344      *
345      * <p> An optional <code>ImageWriteParam</code> may be supplied
346      * for cases where it may affect the structure of the stream
347      * metadata.
348      *
349      * <p> If the supplied <code>ImageWriteParam</code> contains
350      * optional setting values not supported by this writer (<i>e.g.</i>
351      * progressive encoding or any format-specific settings), they
352      * will be ignored.
353      *
354      * <p> Writers that do not make use of stream metadata
355      * (<i>e.g.</i>, writers for single-image formats) should return
356      * <code>null</code>.
357      *
358      * @param param an <code>ImageWriteParam</code> that will be used to
359      * encode the image, or <code>null</code>.
360      *
361      * @return an <code>IIOMetadata</code> object.
362      */
363     public abstract IIOMetadata
364         getDefaultStreamMetadata(ImageWriteParam param);
365
366     /**
367      * Returns an <code>IIOMetadata</code> object containing default
368      * values for encoding an image of the given type. The contents
369      * of the object may be manipulated using either the XML tree
370      * structure returned by the <code>IIOMetadata.getAsTree</code>
371      * method, an <code>IIOMetadataController</code> object, or via
372      * plug-in specific interfaces, and the resulting data supplied to
373      * one of the <code>write</code> methods that take a stream
374      * metadata parameter.
375      *
376      * <p> An optional <code>ImageWriteParam</code> may be supplied
377      * for cases where it may affect the structure of the image
378      * metadata.
379      *
380      * <p> If the supplied <code>ImageWriteParam</code> contains
381      * optional setting values not supported by this writer (<i>e.g.</i>
382      * progressive encoding or any format-specific settings), they
383      * will be ignored.
384      *
385      * @param imageType an <code>ImageTypeSpecifier</code> indicating the
386      * format of the image to be written later.
387      * @param param an <code>ImageWriteParam</code> that will be used to
388      * encode the image, or <code>null</code>.
389      *
390      * @return an <code>IIOMetadata</code> object.
391      */
392     public abstract IIOMetadata
393         getDefaultImageMetadata(ImageTypeSpecifier imageType,
394                                 ImageWriteParam param);
395
396     // comment inherited
397 public abstract IIOMetadata convertStreamMetadata(IIOMetadata inData,
398                                                       ImageWriteParam param);
399
400     // comment inherited
401 public abstract IIOMetadata
402         convertImageMetadata(IIOMetadata inData,
403                              ImageTypeSpecifier imageType,
404                              ImageWriteParam param);
405
406     // Thumbnails
407
408     /**
409      * Returns the number of thumbnails suported by the format being
410      * written, given the image type and any additional write
411      * parameters and metadata objects that will be used during
412      * encoding. A return value of <code>-1</code> indicates that
413      * insufficient information is available.
414      *
415      * <p> An <code>ImageWriteParam</code> may optionally be supplied
416      * for cases where it may affect thumbnail handling.
417      *
418      * <p> If the supplied <code>ImageWriteParam</code> contains
419      * optional setting values not supported by this writer (<i>e.g.</i>
420      * progressive encoding or any format-specific settings), they
421      * will be ignored.
422      *
423      * <p> The default implementation returns 0.
424      *
425      * @param imageType an <code>ImageTypeSpecifier</code> indicating
426      * the type of image to be written, or <code>null</code>.
427      * @param param the <code>ImageWriteParam</code> that will be used for
428      * writing, or <code>null</code>.
429      * @param streamMetadata an <code>IIOMetadata</code> object that will
430      * be used for writing, or <code>null</code>.
431      * @param imageMetadata an <code>IIOMetadata</code> object that will
432      * be used for writing, or <code>null</code>.
433      *
434      * @return the number of thumbnails that may be written given the
435      * supplied parameters, or <code>-1</code> if insufficient
436      * information is available.
437      */
438     public int getNumThumbnailsSupported(ImageTypeSpecifier imageType,
439                                          ImageWriteParam param,
440                                          IIOMetadata streamMetadata,
441                                          IIOMetadata imageMetadata) {
442         return 0;
443     }
444
445     /**
446      * Returns an array of <code>Dimension</code>s indicating the
447      * legal size ranges for thumbnail images as they will be encoded
448      * in the output file or stream. This information is merely
449      * advisory; the writer will resize any supplied thumbnails as
450      * necessary.
451      *
452      * <p> The information is returned as a set of pairs; the first
453      * element of a pair contains an (inclusive) minimum width and
454      * height, and the second element contains an (inclusive) maximum
455      * width and height. Together, each pair defines a valid range of
456      * sizes. To specify a fixed size, the same width and height will
457      * appear for both elements. A return value of <code>null</code>
458      * indicates that the size is arbitrary or unknown.
459      *
460      * <p> An <code>ImageWriteParam</code> may optionally be supplied
461      * for cases where it may affect thumbnail handling.
462      *
463      * <p> If the supplied <code>ImageWriteParam</code> contains
464      * optional setting values not supported by this writer (<i>e.g.</i>
465      * progressive encoding or any format-specific settings), they
466      * will be ignored.
467      *
468      * <p> The default implementation returns <code>null</code>.
469      *
470      * @param imageType an <code>ImageTypeSpecifier</code> indicating the
471      * type of image to be written, or <code>null</code>.
472      * @param param the <code>ImageWriteParam</code> that will be used for
473      * writing, or <code>null</code>.
474      * @param streamMetadata an <code>IIOMetadata</code> object that will
475      * be used for writing, or <code>null</code>.
476      * @param imageMetadata an <code>IIOMetadata</code> object that will
477      * be used for writing, or <code>null</code>.
478      *
479      * @return an array of <code>Dimension</code>s with an even length
480      * of at least two, or <code>null</code>.
481      */
482     public Dimension [] getPreferredThumbnailSizes(ImageTypeSpecifier imageType,
483                                                   ImageWriteParam param,
484                                                   IIOMetadata streamMetadata,
485                                                   IIOMetadata imageMetadata) {
486         return null;
487     }
488
489     /**
490      * Returns <code>true</code> if the methods that take an
491      * <code>IIOImage</code> parameter are capable of dealing with a
492      * <code>Raster</code> (as opposed to <code>RenderedImage</code>)
493      * source image. If this method returns <code>false</code>, then
494      * those methods will throw an
495      * <code>UnsupportedOperationException</code> if supplied with an
496      * <code>IIOImage</code> containing a <code>Raster</code>.
497      *
498      * <p> The default implementation returns <code>false</code>.
499      *
500      * @return <code>true</code> if <code>Raster</code> sources are
501      * supported.
502      */
503     public boolean canWriteRasters() {
504         return false;
505     }
506
507     /**
508      * Appends a complete image stream containing a single image and
509      * associated stream and image metadata and thumbnails to the
510      * output. Any necessary header information is included. If the
511      * output is an <code>ImageOutputStream</code>, its existing
512      * contents prior to the current seek position are not affected,
513      * and need not be readable or writable.
514      *
515      * <p> The output must have been set beforehand using the
516      * <code>setOutput</code> method.
517      *
518      * <p> Stream metadata may optionally be supplied; if it is
519      * <code>null</code>, default stream metadata will be used.
520      *
521      * <p> If <code>canWriteRasters</code> returns <code>true</code>,
522      * the <code>IIOImage</code> may contain a <code>Raster</code>
523      * source. Otherwise, it must contain a
524      * <code>RenderedImage</code> source.
525      *
526      * <p> The supplied thumbnails will be resized if needed, and any
527      * thumbnails in excess of the supported number will be ignored.
528      * If the format requires additional thumbnails that are not
529      * provided, the writer should generate them internally.
530      *
531      * <p> An <code>ImageWriteParam</code> may
532      * optionally be supplied to control the writing process. If
533      * <code>param</code> is <code>null</code>, a default write param
534      * will be used.
535      *
536      * <p> If the supplied <code>ImageWriteParam</code> contains
537      * optional setting values not supported by this writer (<i>e.g.</i>
538      * progressive encoding or any format-specific settings), they
539      * will be ignored.
540      *
541      * @param streamMetadata an <code>IIOMetadata</code> object representing
542      * stream metadata, or <code>null</code> to use default values.
543      * @param image an <code>IIOImage</code> object containing an
544      * image, thumbnails, and metadata to be written.
545      * @param param an <code>ImageWriteParam</code>, or
546      * <code>null</code> to use a default
547      * <code>ImageWriteParam</code>.
548      *
549      * @exception IllegalStateException if the output has not
550      * been set.
551      * @exception UnsupportedOperationException if <code>image</code>
552      * contains a <code>Raster</code> and <code>canWriteRasters</code>
553      * returns <code>false</code>.
554      * @exception IllegalArgumentException if <code>image</code> is
555      * <code>null</code>.
556      * @exception IOException if an error occurs during writing.
557      */
558     public abstract void write(IIOMetadata streamMetadata,
559                                IIOImage image,
560                                ImageWriteParam param) throws IOException ;
561
562     /**
563      * Appends a complete image stream containing a single image with
564      * default metadata and thumbnails to the output. This method is
565      * a shorthand for <code>write(null, image, null)</code>.
566      *
567      * @param image an <code>IIOImage</code> object containing an
568      * image, thumbnails, and metadata to be written.
569      *
570      * @exception IllegalStateException if the output has not
571      * been set.
572      * @exception IllegalArgumentException if <code>image</code> is
573      * <code>null</code>.
574      * @exception UnsupportedOperationException if <code>image</code>
575      * contains a <code>Raster</code> and <code>canWriteRasters</code>
576      * returns <code>false</code>.
577      * @exception IOException if an error occurs during writing.
578      */
579     public void write(IIOImage image) throws IOException {
580         write(null, image, null);
581     }
582
583     /**
584      * Appends a complete image stream consisting of a single image
585      * with default metadata and thumbnails to the output. This
586      * method is a shorthand for <code>write(null, new IIOImage(image,
587      * null, null), null)</code>.
588      *
589      * @param image a <code>RenderedImage</code> to be written.
590      *
591      * @exception IllegalStateException if the output has not
592      * been set.
593      * @exception IllegalArgumentException if <code>image</code> is
594      * <code>null</code>.
595      * @exception IOException if an error occurs during writing.
596      */
597     public void write(RenderedImage image) throws IOException {
598         write(null, new IIOImage (image, null, null), null);
599     }
600
601     // Check that the output has been set, then throw an
602 // UnsupportedOperationException.
603 private void unsupported() {
604         if (getOutput() == null) {
605             throw new IllegalStateException ("getOutput() == null!");
606         }
607         throw new UnsupportedOperationException ("Unsupported write variant!");
608     }
609
610     // Sequence writes
611
612     /**
613      * Returns <code>true</code> if the writer is able to append an
614      * image to an image stream that already contains header
615      * information and possibly prior images.
616      *
617      * <p> If <code>canWriteSequence</code> returns <code>false</code>,
618      * <code>writeToSequence</code> and <code>endWriteSequence</code>
619      * will throw an <code>UnsupportedOperationException</code>.
620      *
621      * <p> The default implementation returns <code>false</code>.
622      *
623      * @return <code>true</code> if images may be appended sequentially.
624      */
625     public boolean canWriteSequence() {
626         return false;
627     }
628
629     /**
630      * Prepares a stream to accept a series of subsequent
631      * <code>writeToSequence</code> calls, using the provided stream
632      * metadata object. The metadata will be written to the stream if
633      * it should precede the image data. If the argument is <code>null</code>,
634      * default stream metadata is used.
635      *
636      * <p> If the output is an <code>ImageOutputStream</code>, the existing
637      * contents of the output prior to the current seek position are
638      * flushed, and need not be readable or writable. If the format
639      * requires that <code>endWriteSequence</code> be able to rewind to
640      * patch up the header information, such as for a sequence of images
641      * in a single TIFF file, then the metadata written by this method
642      * must remain in a writable portion of the stream. Other formats
643      * may flush the stream after this method and after each image.
644      *
645      * <p> If <code>canWriteSequence</code> returns <code>false</code>,
646      * this method will throw an
647      * <code>UnsupportedOperationException</code>.
648      *
649      * <p> The output must have been set beforehand using either
650      * the <code>setOutput</code> method.
651      *
652      * <p> The default implementation throws an
653      * <code>IllegalStateException</code> if the output is
654      * <code>null</code>, and otherwise throws an
655      * <code>UnsupportedOperationException</code>.
656      *
657      * @param streamMetadata A stream metadata object, or <code>null</code>.
658      *
659      * @exception IllegalStateException if the output has not
660      * been set.
661      * @exception UnsupportedOperationException if
662      * <code>canWriteSequence</code> returns <code>false</code>.
663      * @exception IOException if an error occurs writing the stream
664      * metadata.
665      */
666     public void prepareWriteSequence(IIOMetadata streamMetadata)
667         throws IOException {
668         unsupported();
669     }
670
671     /**
672      * Appends a single image and possibly associated metadata and
673      * thumbnails, to the output. If the output is an
674      * <code>ImageOutputStream</code>, the existing contents of the
675      * output prior to the current seek position may be flushed, and
676      * need not be readable or writable, unless the plug-in needs to
677      * be able to patch up the header information when
678      * <code>endWriteSequence</code> is called (<italic>e.g.</italic> TIFF).
679      *
680      * <p> If <code>canWriteSequence</code> returns <code>false</code>,
681      * this method will throw an
682      * <code>UnsupportedOperationException</code>.
683      *
684      * <p> The output must have been set beforehand using
685      * the <code>setOutput</code> method.
686      *
687      * <p> <code>prepareWriteSequence</code> must have been called
688      * beforehand, or an <code>IllegalStateException</code> is thrown.
689      *
690      * <p> If <code>canWriteRasters</code> returns <code>true</code>,
691      * the <code>IIOImage</code> may contain a <code>Raster</code>
692      * source. Otherwise, it must contain a
693      * <code>RenderedImage</code> source.
694      *
695      * <p> The supplied thumbnails will be resized if needed, and any
696      * thumbnails in excess of the supported number will be ignored.
697      * If the format requires additional thumbnails that are not
698      * provided, the writer will generate them internally.
699      *
700      * <p> An <code>ImageWriteParam</code> may optionally be supplied
701      * to control the writing process. If <code>param</code> is
702      * <code>null</code>, a default write param will be used.
703      *
704      * <p> If the supplied <code>ImageWriteParam</code> contains
705      * optional setting values not supported by this writer (<i>e.g.</i>
706      * progressive encoding or any format-specific settings), they
707      * will be ignored.
708      *
709      * <p> The default implementation throws an
710      * <code>IllegalStateException</code> if the output is
711      * <code>null</code>, and otherwise throws an
712      * <code>UnsupportedOperationException</code>.
713      *
714      * @param image an <code>IIOImage</code> object containing an
715      * image, thumbnails, and metadata to be written.
716      * @param param an <code>ImageWriteParam</code>, or
717      * <code>null</code> to use a default
718      * <code>ImageWriteParam</code>.
719      *
720      * @exception IllegalStateException if the output has not
721      * been set, or <code>prepareWriteSequence</code> has not been called.
722      * @exception UnsupportedOperationException if
723      * <code>canWriteSequence</code> returns <code>false</code>.
724      * @exception IllegalArgumentException if <code>image</code> is
725      * <code>null</code>.
726      * @exception UnsupportedOperationException if <code>image</code>
727      * contains a <code>Raster</code> and <code>canWriteRasters</code>
728      * returns <code>false</code>.
729      * @exception IOException if an error occurs during writing.
730      */
731     public void writeToSequence(IIOImage image, ImageWriteParam param)
732         throws IOException {
733         unsupported();
734     }
735
736     /**
737      * Completes the writing of a sequence of images begun with
738      * <code>prepareWriteSequence</code>. Any stream metadata that
739      * should come at the end of the sequence of images is written out,
740      * and any header information at the beginning of the sequence is
741      * patched up if necessary. If the output is an
742      * <code>ImageOutputStream</code>, data through the stream metadata
743      * at the end of the sequence are flushed and need not be readable
744      * or writable.
745      *
746      * <p> If <code>canWriteSequence</code> returns <code>false</code>,
747      * this method will throw an
748      * <code>UnsupportedOperationException</code>.
749      *
750      * <p> The default implementation throws an
751      * <code>IllegalStateException</code> if the output is
752      * <code>null</code>, and otherwise throws an
753      * <code>UnsupportedOperationException</code>.
754      *
755      * @exception IllegalStateException if the output has not
756      * been set, or <code>prepareWriteSequence</code> has not been called.
757      * @exception UnsupportedOperationException if
758      * <code>canWriteSequence</code> returns <code>false</code>.
759      * @exception IOException if an error occurs during writing.
760      */
761     public void endWriteSequence() throws IOException {
762         unsupported();
763     }
764
765     // Metadata replacement
766
767     /**
768      * Returns <code>true</code> if it is possible to replace the
769      * stream metadata already present in the output.
770      *
771      * <p> The default implementation throws an
772      * <code>IllegalStateException</code> if the output is
773      * <code>null</code>, and otherwise returns <code>false</code>.
774      *
775      * @return <code>true</code> if replacement of stream metadata is
776      * allowed.
777      *
778      * @exception IllegalStateException if the output has not
779      * been set.
780      * @exception IOException if an I/O error occurs during the query.
781      */
782     public boolean canReplaceStreamMetadata() throws IOException {
783         if (getOutput() == null) {
784             throw new IllegalStateException ("getOutput() == null!");
785         }
786         return false;
787     }
788
789     /**
790      * Replaces the stream metadata in the output with new
791      * information. If the output is an
792      * <code>ImageOutputStream</code>, the prior contents of the
793      * stream are examined and possibly edited to make room for the
794      * new data. All of the prior contents of the output must be
795      * available for reading and writing.
796      *
797      * <p> If <code>canReplaceStreamMetadata</code> returns
798      * <code>false</code>, an
799      * <code>UnsupportedOperationException</code> will be thrown.
800      *
801      * <p> The default implementation throws an
802      * <code>IllegalStateException</code> if the output is
803      * <code>null</code>, and otherwise throws an
804      * <code>UnsupportedOperationException</code>.
805      *
806      * @param streamMetadata an <code>IIOMetadata</code> object representing
807      * stream metadata, or <code>null</code> to use default values.
808      *
809      * @exception IllegalStateException if the output has not
810      * been set.
811      * @exception UnsupportedOperationException if the
812      * <code>canReplaceStreamMetadata</code> returns
813      * <code>false</code>. modes do not include
814      * @exception IOException if an error occurs during writing.
815      */
816     public void replaceStreamMetadata(IIOMetadata streamMetadata)
817         throws IOException {
818         unsupported();
819     }
820
821     /**
822      * Returns <code>true</code> if it is possible to replace the
823      * image metadata associated with an existing image with index
824      * <code>imageIndex</code>. If this method returns
825      * <code>false</code>, a call to
826      * <code>replaceImageMetadata(imageIndex)</code> will throw an
827      * <code>UnsupportedOperationException</code>.
828      *
829      * <p> A writer that does not support any image metadata
830      * replacement may return <code>false</code> without performing
831      * bounds checking on the index.
832      *
833      * <p> The default implementation throws an
834      * <code>IllegalStateException</code> if the output is
835      * <code>null</code>, and otherwise returns <code>false</code>
836      * without checking the value of <code>imageIndex</code>.
837      *
838      * @param imageIndex the index of the image whose metadata is to
839      * be replaced.
840      *
841      * @return <code>true</code> if the image metadata of the given
842      * image can be replaced.
843      *
844      * @exception IllegalStateException if the output has not
845      * been set.
846      * @exception IndexOutOfBoundsException if the writer supports
847      * image metadata replacement in general, but
848      * <code>imageIndex</code> is less than 0 or greater than the
849      * largest available index.
850      * @exception IOException if an I/O error occurs during the query.
851      */
852     public boolean canReplaceImageMetadata(int imageIndex)
853         throws IOException {
854         if (getOutput() == null) {
855             throw new IllegalStateException ("getOutput() == null!");
856         }
857         return false;
858     }
859
860     /**
861      * Replaces the image metadata associated with an existing image.
862      *
863      * <p> If <code>canReplaceImageMetadata(imageIndex)</code> returns
864      * <code>false</code>, an
865      * <code>UnsupportedOperationException</code> will be thrown.
866      *
867      * <p> The default implementation throws an
868      * <code>IllegalStateException</code> if the output is
869      * <code>null</code>, and otherwise throws an
870      * <code>UnsupportedOperationException</code>.
871      *
872      * @param imageIndex the index of the image whose metadata is to
873      * be replaced.
874      * @param imageMetadata an <code>IIOMetadata</code> object
875      * representing image metadata, or <code>null</code>.
876      *
877      * @exception IllegalStateException if the output has not been
878      * set.
879      * @exception UnsupportedOperationException if
880      * <code>canReplaceImageMetadata</code> returns
881      * <code>false</code>.
882      * @exception IndexOutOfBoundsException if <code>imageIndex</code>
883      * is less than 0 or greater than the largest available index.
884      * @exception IOException if an error occurs during writing.
885      */
886     public void replaceImageMetadata(int imageIndex,
887                                      IIOMetadata imageMetadata)
888         throws IOException {
889         unsupported();
890     }
891
892     // Image insertion
893
894     /**
895      * Returns <code>true</code> if the writer supports the insertion
896      * of a new image at the given index. Existing images with
897      * indices greater than or equal to the insertion index will have
898      * their indices increased by 1. A value for
899      * <code>imageIndex</code> of <code>-1</code> may be used to
900      * signify an index one larger than the current largest index.
901      *
902      * <p> A writer that does not support any image insertion may
903      * return <code>false</code> without performing bounds checking on
904      * the index.
905      *
906      * <p> The default implementation throws an
907      * <code>IllegalStateException</code> if the output is
908      * <code>null</code>, and otherwise returns <code>false</code>
909      * withour checking the value of <code>imageIndex</code>.
910