001    /* ImageWriter.java -- Encodes raster images.
002       Copyright (C) 2004, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.imageio;
040    
041    import java.awt.Dimension;
042    import java.awt.Rectangle;
043    import java.awt.image.BufferedImage;
044    import java.awt.image.Raster;
045    import java.awt.image.RenderedImage;
046    import java.io.IOException;
047    import java.util.ArrayList;
048    import java.util.Iterator;
049    import java.util.List;
050    import java.util.Locale;
051    import java.util.ResourceBundle;
052    import java.util.MissingResourceException;
053    
054    import javax.imageio.event.IIOWriteProgressListener;
055    import javax.imageio.event.IIOWriteWarningListener;
056    import javax.imageio.metadata.IIOMetadata;
057    
058    import javax.imageio.spi.ImageWriterSpi;
059    
060    /**
061     * A class for encoding images within the ImageIO framework.
062     *
063     * An ImageWriter for a given format is instantiated by an
064     * ImageWriterSpi for that format.  ImageWriterSpis are registered
065     * with the IIORegistry.
066     *
067     * The ImageWriter API supports writing animated images that may have
068     * multiple frames; to support such images many methods take an index
069     * parameter.
070     *
071     * Images may also be written in multiple passes, where each
072     * successive pass increases the level of detail in the destination
073     * image.
074     */
075    public abstract class ImageWriter
076      implements ImageTranscoder
077    {
078      private boolean aborted;
079    
080      /**
081       * All locales available for localization of warning messages, or
082       * null if localization is not supported.
083       */
084      protected Locale[] availableLocales = null;
085    
086      /**
087       * The current locale used to localize warning messages, or null if
088       * no locale has been set.
089       */
090      protected Locale locale = null;
091    
092      /**
093       * The image writer SPI that instantiated this writer.
094       */
095      protected ImageWriterSpi originatingProvider = null;
096    
097      /**
098       * An ImageInputStream to which image data is written.
099       */
100      protected Object output = null;
101    
102      /**
103       * A list of installed progress listeners.  Initially null, meaning
104       * no installed listeners.
105       */
106      protected List<IIOWriteProgressListener> progressListeners = null;
107    
108      /**
109       * A list of installed warning listeners.  Initially null, meaning
110       * no installed listeners.
111       */
112      protected List<IIOWriteWarningListener> warningListeners = null;
113    
114      /**
115       * A list of warning locales corresponding with the list of
116       * installed warning listeners.  Initially null, meaning no locales.
117       */
118      protected List<Locale> warningLocales = null;
119    
120      /**
121       * Construct an image writer.
122       *
123       * @param originatingProvider the provider that is constructing this
124       * image writer, or null
125       */
126      protected ImageWriter(ImageWriterSpi originatingProvider)
127      {
128        this.originatingProvider = originatingProvider;
129      }
130    
131      /**
132       * Throw an IllegalStateException if output is null.
133       *
134       * @exception IllegalStateException if output is null
135       */
136      private void checkOutputSet()
137      {
138        if (output == null)
139          throw new IllegalStateException("no output set");
140      }
141    
142      /**
143       * Request that writing be aborted.  The unwritten portions of the
144       * destination image will be undefined.
145       *
146       * Writers should clear the abort flag before starting a write
147       * operation, then poll it periodically during the write operation.
148       */
149      public void abort()
150      {
151        aborted = true;
152      }
153    
154      /**
155       * Check if the abort flag is set.
156       *
157       * @return true if the current write operation should be aborted,
158       * false otherwise
159       */
160      protected boolean abortRequested()
161      {
162        return aborted;
163      }
164    
165      /**
166       * Install a write progress listener.  This method will return
167       * immediately if listener is null.
168       *
169       * @param listener a write progress listener or null
170       */
171      public void addIIOWriteProgressListener(IIOWriteProgressListener listener)
172      {
173        if (listener == null)
174          return;
175        if (progressListeners == null)
176          progressListeners = new ArrayList ();
177        progressListeners.add(listener);
178      }
179    
180      /**
181       * Install a write warning listener.  This method will return
182       * immediately if listener is null.  Warning messages sent to this
183       * listener will be localized using the current locale.  If the
184       * current locale is null then this writer will select a sensible
185       * default.
186       *
187       * @param listener a write warning listener
188       */
189      public void addIIOWriteWarningListener (IIOWriteWarningListener listener)
190      {
191        if (listener == null)
192          return;
193        if (warningListeners == null)
194          warningListeners = new ArrayList ();
195        warningListeners.add(listener);
196      }
197    
198      /**
199       * Check whether a new empty image can be inserted at the given
200       * frame index.  Pixel values may be filled in later using the
201       * replacePixels methods.  Indices greater than the insertion index
202       * will be incremented.  If imageIndex is -1, the image will be
203       * appended at the end of the current image list.
204       *
205       * @param imageIndex the frame index
206       *
207       * @return true if an empty image can be inserted at imageIndex,
208       * false otherwise
209       *
210       * @exception IllegalStateException if output is null
211       * @exception IndexOutOfBoundsException if imageIndex is less than
212       * -1 or greater than the last index in the current image list
213       * @exception IOException if a write error occurs
214       */
215      public boolean canInsertEmpty(int imageIndex)
216        throws IOException
217      {
218        checkOutputSet();
219        return false;
220      }
221    
222      /**
223       * Check whether an image can be inserted at the given frame index.
224       * Indices greater than the insertion index will be incremented.  If
225       * imageIndex is -1, the image will be appended at the end of the
226       * current image list.
227       *
228       * @param imageIndex the frame index
229       *
230       * @return true if an image can be inserted at imageIndex, false
231       * otherwise
232       *
233       * @exception IllegalStateException if output is null
234       * @exception IndexOutOfBoundsException if imageIndex is less than
235       * -1 or greater than the last index in the current image list
236       * @exception IOException if a write error occurs
237       */
238      public boolean canInsertImage(int imageIndex)
239        throws IOException
240      {
241        checkOutputSet();
242        return false;
243      }
244    
245      /**
246       * Check whether an image can be removed from the given frame index.
247       * Indices greater than the removal index will be decremented.
248       *
249       * @param imageIndex the frame index
250       *
251       * @return true if an image can be removed from imageIndex, false
252       * otherwise
253       *
254       * @exception IllegalStateException if output is null
255       * @exception IndexOutOfBoundsException if imageIndex is less than 0
256       * or greater than the last index in the current image list
257       * @exception IOException if a write error occurs
258       */
259      public boolean canRemoveImage(int imageIndex)
260        throws IOException
261      {
262        checkOutputSet();
263        return false;
264      }
265    
266      /**
267       * Check whether the metadata associated the image at the given
268       * frame index can be replaced.
269       *
270       * @param imageIndex the frame index
271       *
272       * @return true if the metadata associated with the image at
273       * imageIndex can be replaced, false otherwise
274       *
275       * @exception IllegalStateException if output is null
276       * @exception IndexOutOfBoundsException if imageIndex is less than 0
277       * or greater than the last index in the current image list
278       * @exception IOException if a write error occurs
279       */
280      public boolean canReplaceImageMetadata(int imageIndex)
281        throws IOException
282      {
283        checkOutputSet();
284        return false;
285      }
286    
287      /**
288       * Check whether the pixels within the image at the given index can
289       * be replaced.
290       *
291       * @param imageIndex the frame index
292       *
293       * @return true if the pixels in the image at imageIndex can be
294       * replaced, false otherwise
295       *
296       * @exception IllegalStateException if output is null
297       * @exception IndexOutOfBoundsException if imageIndex is less than 0
298       * or greater than the last index in the current image list
299       * @exception IOException if a write error occurs
300       */
301      public boolean canReplacePixels(int imageIndex)
302        throws IOException
303      {
304        checkOutputSet();
305        return false;
306      }
307    
308      /**
309       * Check whether the metadata associated the entire image stream can
310       * be replaced.
311       *
312       * @return true if the stream metadata can be replaced, false
313       * otherwise
314       *
315       * @exception IllegalStateException if output is null
316       * @exception IOException if a write error occurs
317       */
318      public boolean canReplaceStreamMetadata()
319        throws IOException
320      {
321        checkOutputSet();
322        return false;
323      }
324    
325      /**
326       * Check whether an entire empty image, including empty metadata and
327       * empty thumbnails, can be written to the output stream, leaving
328       * pixel values to be filled in later using the replacePixels
329       * methods.
330       *
331       * @return true if an entire empty image can be written before its
332       * contents are filled in, false otherwise
333       *
334       * @exception IllegalStateException if output is null
335       * @exception IOException if a write error occurs
336       */
337      public boolean canWriteEmpty()
338        throws IOException
339      {
340        checkOutputSet();
341        return false;
342      }
343    
344      /**
345       * Check if IIOImages containing raster data are supported.
346       *
347       * @return true if raster IIOImages are supported, false otherwise
348       */
349      public boolean canWriteRasters()
350      {
351        return false;
352      }
353    
354      /**
355       * Check if an image can be appended at the end of the current list
356       * of images even if prior images have already been written.
357       *
358       * @return true if sequences of images can be written, false
359       * otherwise
360       */
361      public boolean canWriteSequence()
362      {
363        return false;
364      }
365    
366      /**
367       * Clear the abort flag.
368       */
369      protected void clearAbortRequest()
370      {
371        aborted = false;
372      }
373    
374      /**
375       * Convert IIOMetadata from an input reader format, returning an
376       * IIOMetadata suitable for use by an image writer.
377       *
378       * The ImageTypeSpecifier specifies the destination image type.
379       *
380       * An optional ImageWriteParam argument is available in case the
381       * image writing parameters affect the metadata conversion.
382       *
383       * @param inData the metadata coming from an image reader
384       * @param imageType the output image type of the writer
385       * @param param the image writing parameters or null
386       *
387       * @return the converted metadata that should be used by the image
388       * writer, or null if this ImageTranscoder has no knowledge of the
389       * input metadata
390       *
391       * @exception IllegalArgumentException if either inData or imageType
392       * is null
393       */
394      public abstract IIOMetadata convertImageMetadata (IIOMetadata inData,
395                                                        ImageTypeSpecifier imageType,
396                                                        ImageWriteParam param);
397    
398      /**
399       * Convert IIOMetadata from an input stream format, returning an
400       * IIOMetadata suitable for use by an image writer.
401       *
402       * An optional ImageWriteParam argument is available in case the
403       * image writing parameters affect the metadata conversion.
404       *
405       * @param inData the metadata coming from an input image stream
406       * @param param the image writing parameters or null
407       *
408       * @return the converted metadata that should be used by the image
409       * writer, or null if this ImageTranscoder has no knowledge of the
410       * input metadata
411       *
412       * @exception IllegalArgumentException if inData is null
413       */
414      public abstract IIOMetadata convertStreamMetadata (IIOMetadata inData,
415                                                         ImageWriteParam param);
416    
417      /**
418       * Releases any resources allocated to this object.  Subsequent
419       * calls to methods on this object will produce undefined results.
420       *
421       * The default implementation does nothing; subclasses should use
422       * this method ensure that native resources are released.
423       */
424      public void dispose()
425      {
426        // The default implementation is empty. Subclasses have to overwrite it.
427      }
428    
429      /**
430       * Retrieve the available locales.  Return null if no locales are
431       * available or a clone of availableLocales.
432       *
433       * @return an array of locales or null
434       */
435      public Locale[] getAvailableLocales()
436      {
437        return availableLocales;
438      }
439    
440      /**
441       * Get a metadata object appropriate for encoding an image specified
442       * by the given image type specifier and optional image write
443       * parameters.
444       *
445       * @param imageType an image type specifier
446       * @param param image writing parameters, or null
447       *
448       * @return a metadata object appropriate for encoding an image of
449       * the given type with the given parameters
450       */
451      public abstract IIOMetadata getDefaultImageMetadata (ImageTypeSpecifier imageType, ImageWriteParam param);
452    
453      /**
454       * Get a metadata object appropriate for encoding the default image
455       * type handled by this writer, optionally considering image write
456       * parameters.
457       *
458       * @param param image writing parameters, or null
459       *
460       * @return a metadata object appropriate for encoding an image of
461       * the default type with the given parameters
462       */
463      public abstract IIOMetadata getDefaultStreamMetadata (ImageWriteParam param);
464    
465      /**
466       * Retrieve the default write parameters for this writer's image
467       * format.
468       *
469       * The default implementation returns new ImageWriteParam().
470       *
471       * @return image writing parameters
472       */
473      public ImageWriteParam getDefaultWriteParam()
474      {
475        return new ImageWriteParam(getLocale());
476      }
477    
478      /**
479       * Get this writer's locale.  null is returned if the locale has not
480       * been set.
481       *
482       * @return this writer's locale, or null
483       */
484      public Locale getLocale()
485      {
486        return locale;
487      }
488    
489      /**
490       * Get the number of thumbnails supported by this image writer,
491       * based on the given image type, image writing parameters, and
492       * stream and image metadata.  The image writing parameters are
493       * optional, in case they affect the number of thumbnails supported.
494       *
495       * @param imageType an image type specifier, or null
496       * @param param image writing parameters, or null
497       * @param streamMetadata the metadata associated with this stream,
498       * or null
499       * @param imageMetadata the metadata associated with this image, or
500       * null
501       *
502       * @return the number of thumbnails that this writer supports
503       * writing or -1 if the given information is insufficient
504       */
505      public int getNumThumbnailsSupported (ImageTypeSpecifier imageType,
506                                            ImageWriteParam param,
507                                            IIOMetadata streamMetadata,
508                                            IIOMetadata imageMetadata)
509      {
510        return 0;
511      }
512    
513      /**
514       * Get the ImageWriterSpi that created this writer or null.
515       *
516       * @return an ImageWriterSpi, or null
517       */
518      public ImageWriterSpi getOriginatingProvider()
519      {
520        return originatingProvider;
521      }
522    
523      /**
524       * Get this reader's image output destination.  null is returned if
525       * the image destination has not been set.
526       *
527       * @return an image output destination object, or null
528       */
529      public Object getOutput()
530      {
531        return output;
532      }
533    
534      /**
535       * Get the preferred sizes for thumbnails based on the given image
536       * type, image writing parameters, and stream and image metadata.
537       * The preferred sizes are returned in pairs of dimension values;
538       * the first value in the array is a dimension object representing
539       * the minimum thumbnail size, the second value is a dimension
540       * object representing a maximum thumbnail size.  The writer can
541       * select a size within the range given by each pair, or it can
542       * ignore these size hints.
543       *
544       * @param imageType an image type specifier, or null
545       * @param param image writing parameters, or null
546       * @param streamMetadata the metadata associated with this stream,
547       * or null
548       * @param imageMetadata the metadata associated with this image, or
549       * null
550       *
551       * @return an array of dimension pairs whose length is a multiple of
552       * 2, or null if there is no preferred size (any size is allowed) or
553       * if the size is unknown (insufficient information was provided)
554       */
555      public Dimension[] getPreferredThumbnailSizes (ImageTypeSpecifier imageType,
556                                                     ImageWriteParam param,
557                                                     IIOMetadata streamMetadata,
558                                                     IIOMetadata imageMetadata)
559      {
560        return null;
561      }
562    
563      /**
564       * Notifies all installed write progress listeners that image
565       * loading has completed by calling their imageComplete methods.
566       */
567      protected void processImageComplete()
568      {
569        if (progressListeners != null)
570          {
571            Iterator it = progressListeners.iterator();
572    
573            while (it.hasNext())
574              {
575                IIOWriteProgressListener listener =
576                  (IIOWriteProgressListener) it.next();
577                listener.imageComplete(this);
578              }
579          }
580      }
581    
582      /**
583       * Notifies all installed write progress listeners that a certain
584       * percentage of the image has been loaded, by calling their
585       * imageProgress methods.
586       *
587       * @param percentageDone the percentage of image data that has been
588       * loaded
589       */
590      protected void processImageProgress(float percentageDone)
591      {
592        if (progressListeners != null)
593          {
594            Iterator it = progressListeners.iterator();
595    
596            while (it.hasNext())
597              {
598                IIOWriteProgressListener listener =
599                  (IIOWriteProgressListener) it.next();
600                listener.imageProgress(this, percentageDone);
601              }
602          }
603      }
604    
605      /**
606       * Notifies all installed write progress listeners, by calling their
607       * imageStarted methods, that image loading has started on the given
608       * image.
609       *
610       * @param imageIndex the frame index of the image that has started
611       * loading
612       */
613      protected void processImageStarted(int imageIndex)
614      {
615        if (progressListeners != null)
616          {
617            Iterator it = progressListeners.iterator();
618    
619            while (it.hasNext())
620              {
621                IIOWriteProgressListener listener =
622                  (IIOWriteProgressListener) it.next();
623                listener.imageStarted(this, imageIndex);
624              }
625          }
626      }
627    
628      /**
629       * Notifies all installed write progress listeners, by calling their
630       * thumbnailComplete methods, that a thumbnail has completed
631       * loading.
632       */
633      protected void processThumbnailComplete()
634      {
635        if (progressListeners != null)
636          {
637            Iterator it = progressListeners.iterator();
638    
639            while (it.hasNext())
640              {
641                IIOWriteProgressListener listener =
642                  (IIOWriteProgressListener) it.next();
643                listener.thumbnailComplete(this);
644              }
645          }
646      }
647    
648      /**
649       * Notifies all installed write progress listeners that a certain
650       * percentage of a thumbnail has been loaded, by calling their
651       * thumbnailProgress methods.
652       *
653       * @param percentageDone the percentage of thumbnail data that has
654       * been loaded
655       */
656      protected void processThumbnailProgress(float percentageDone)
657      {
658        if (progressListeners != null)
659          {
660            Iterator it = progressListeners.iterator();
661    
662            while (it.hasNext())
663              {
664                IIOWriteProgressListener listener =
665                  (IIOWriteProgressListener) it.next();
666                listener.thumbnailProgress(this, percentageDone);
667              }
668          }
669      }
670    
671      /**
672       * Notifies all installed write progress listeners, by calling their
673       * imageStarted methods, that thumbnail loading has started on the
674       * given thumbnail of the given image.
675       *
676       * @param imageIndex the frame index of the image one of who's
677       * thumbnails has started loading
678       * @param thumbnailIndex the index of the thumbnail that has started
679       * loading
680       */
681      protected void processThumbnailStarted(int imageIndex, int thumbnailIndex)
682      {
683        if (progressListeners != null)
684          {
685            Iterator it = progressListeners.iterator();
686    
687            while (it.hasNext())
688              {
689                IIOWriteProgressListener listener =
690                  (IIOWriteProgressListener) it.next();
691                listener.thumbnailStarted(this, imageIndex, thumbnailIndex);
692              }
693          }
694      }
695    
696      /**
697       * Notifies all installed warning listeners, by calling their
698       * warningOccurred methods, that a warning message has been raised.
699       *
700       * @param imageIndex the index of the image that was being written
701       * when the warning was raised
702       * @param warning the warning message
703       *
704       * @exception IllegalArgumentException if warning is null
705       */
706      protected void processWarningOccurred(int imageIndex, String warning)
707      {
708         if (warningListeners != null)
709          {
710            Iterator it = warningListeners.iterator();
711    
712            while (it.hasNext())
713              {
714                IIOWriteWarningListener listener =
715                  (IIOWriteWarningListener) it.next();
716                listener.warningOccurred(this, imageIndex, warning);
717              }
718          }
719      }
720    
721      /**
722       * Notify all installed warning listeners, by calling their
723       * warningOccurred methods, that a warning message has been raised.
724       * The warning message is retrieved from a resource bundle, using
725       * the given basename and keyword.
726       *
727       * @param imageIndex the index of the image that was being written
728       * when the warning was raised
729       * @param baseName the basename of the resource from which to
730       * retrieve the warning message
731       * @param keyword the keyword used to retrieve the warning from the
732       * resource bundle
733       *
734       * @exception IllegalArgumentException if either baseName or keyword
735       * is null
736       * @exception IllegalArgumentException if no resource bundle is
737       * found using baseName
738       * @exception IllegalArgumentException if the given keyword produces
739       * no results from the resource bundle
740       * @exception IllegalArgumentException if the retrieved object is
741       * not a String
742       */
743      protected void processWarningOccurred(int imageIndex,
744                                            String baseName,
745                                            String keyword)
746      {
747        if (baseName == null || keyword == null)
748          throw new IllegalArgumentException ("null argument");
749    
750        ResourceBundle b = null;
751    
752        try
753          {
754            b = ResourceBundle.getBundle(baseName, getLocale());
755          }
756        catch (MissingResourceException e)
757          {
758            throw new IllegalArgumentException ("no resource bundle found");
759          }
760    
761        Object str = null;
762    
763        try
764          {
765            str = b.getObject(keyword);
766          }
767        catch (MissingResourceException e)
768          {
769            throw new IllegalArgumentException ("no results found for keyword");
770          }
771    
772        if (! (str instanceof String))
773          throw new IllegalArgumentException ("retrieved object not a String");
774    
775        String warning = (String) str;
776    
777        if (warningListeners != null)
778          {
779            Iterator it = warningListeners.iterator();
780    
781            while (it.hasNext())
782              {
783                IIOWriteWarningListener listener =
784                  (IIOWriteWarningListener) it.next();
785                listener.warningOccurred(this, imageIndex, warning);
786              }
787          }
788      }
789    
790      /**
791       * Notifies all installed write progress listeners that image
792       * loading has been aborted by calling their writeAborted methods.
793       */
794      protected void processWriteAborted()
795      {
796        if (progressListeners != null)
797          {
798            Iterator it = progressListeners.iterator();
799    
800            while (it.hasNext())
801              {
802                IIOWriteProgressListener listener =
803                  (IIOWriteProgressListener) it.next();
804                listener.writeAborted(this);
805              }
806          }
807      }
808    
809      /**
810       * Uninstall all write progress listeners.
811       */
812      public void removeAllIIOWriteProgressListeners()
813      {
814        if (progressListeners != null)
815          {
816            progressListeners.clear();
817          }
818      }
819    
820      /**
821       * Uninstall all write warning listeners.
822       */
823      public void removeAllIIOWriteWarningListeners()
824      {
825        if (progressListeners != null)
826          {
827            progressListeners.clear();
828          }
829      }
830    
831      /**
832       * Uninstall the given write progress listener.
833       *
834       * @param listener the listener to remove
835       */
836      public void removeIIOWriteProgressListener (IIOWriteProgressListener listener)
837      {
838        if (listener == null)
839          return;
840        if (progressListeners != null)
841          {
842            progressListeners.remove(listener);
843          }
844      }
845      /**
846       * Uninstall the given write warning listener.
847       *
848       * @param listener the listener to remove
849       */
850      public void removeIIOWriteWarningListener (IIOWriteWarningListener listener)
851      {
852        if (listener == null)
853          return;
854        if (warningListeners != null)
855          {
856            warningListeners.remove(listener);
857          }
858      }
859      /**
860       * Reset this writer's internal state.
861       */
862      public void reset()
863      {
864        setOutput(null);
865        setLocale(null);
866        removeAllIIOWriteWarningListeners();
867        removeAllIIOWriteProgressListeners();
868        clearAbortRequest();
869      }
870    
871      /**
872       * Set the current locale or use the default locale.
873       *
874       * @param locale the locale to set, or null
875       */
876      public void setLocale(Locale locale)
877      {
878        if (locale != null)
879          {
880            // Check if its a valid locale.
881            boolean found = false;
882    
883            if (availableLocales != null)
884              for (int i = availableLocales.length - 1; i >= 0; --i)
885                if (availableLocales[i].equals(locale))
886                  found = true;
887    
888            if (! found)
889              throw new IllegalArgumentException("looale not available");
890          }
891    
892        this.locale = locale;
893      }
894    
895      /**
896       * Set the output destination of the given object.  The output
897       * destination must be set before many methods can be called on this
898       * writer. (see all ImageWriter methods that throw
899       * IllegalStateException).  If input is null then the current input
900       * source will be removed.
901       *
902       * @param output the output destination object
903       *
904       * @exception IllegalArgumentException if input is not a valid input
905       * source for this writer and is not an ImageInputStream
906       */
907      public void setOutput(Object output)
908      {
909        if (output != null)
910          {
911            // Check if its a valid output object.
912            boolean found = false;
913            Class[] types = null;
914    
915            if (originatingProvider != null)
916              types = originatingProvider.getOutputTypes();
917    
918            if (types != null)
919              for (int i = types.length - 1; i >= 0; --i)
920                if (types[i].isInstance(output))
921                  found = true;
922    
923            if (! found)
924              throw new IllegalArgumentException("output type not available");
925          }
926    
927        this.output = output;
928      }
929    
930      /**
931       * Write an image stream, including thumbnails and metadata to the
932       * output stream.  The output must have been set prior to this
933       * method being called.  Metadata associated with the stream may be
934       * supplied, or it can be left null.  IIOImage may contain raster
935       * data if this writer supports rasters, or it will contain a
936       * rendered image.  Thumbnails are resized if need be.  Image
937       * writing parameters may be specified to affect writing, or may be
938       * left null.
939       *
940       * @param streamMetadata metadata associated with this stream, or
941       * null
942       * @param image an IIOImage containing image data, metadata and
943       * thumbnails to be written
944       * @param param image writing parameters, or null
945       *
946       * @exception IllegalStateException if output is null
947       * @exception UnsupportedOperationException if image contains raster
948       * data but this writer does not support rasters
949       * @exception IllegalArgumentException if image is null
950       * @exception IOException if a write error occurs
951       */
952      public abstract void write (IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param)
953        throws IOException;
954    
955      /**
956       * Complete inserting an empty image in the output stream.
957       *
958       * @exception IllegalStateException if output is null
959       * @exception UnsupportedOperationException if inserting empty
960       * images is not supported
961       * @exception IllegalArgumentException if a call to
962       * prepareInsertEmpty was not called previous to this method being
963       * called (a sequence of prepareInsertEmpty calls must be terminated
964       * by a call to endInsertEmpty)
965       * @exception IllegalArgumentException if prepareWriteEmpty was
966       * called before this method being called (without a terminating
967       * call to endWriteEmpty)
968       * @exception IllegalArgumentException if prepareReplacePixels was
969       * called before this method being called (without a terminating
970       * call to endReplacePixels)
971       * @exception IOException if a write error occurs
972       */
973      public void endInsertEmpty ()
974        throws IOException
975      {
976        if (!canInsertEmpty(0))
977          throw new UnsupportedOperationException();
978      }
979    
980      /**
981       * Complete replacing pixels in an image in the output stream.
982       *
983       * @exception IllegalStateException if output is null
984       * @exception UnsupportedOperationException if replacing pixels is
985       * not supported by this writer
986       * @exception IllegalArgumentException if prepareReplacePixels was
987       * not called before this method being called
988       * @exception IOException if a write error occurs
989       */
990      public void endReplacePixels ()
991        throws IOException
992      {
993        if (!canReplacePixels(0))
994          throw new UnsupportedOperationException();
995      }
996    
997      /**
998       * Complete writing an empty image to the image output stream.
999       *
1000       * @exception IllegalStateException if output is null
1001       * @exception UnsupportedOperationException if writing empty images
1002       * is not supported
1003       * @exception IllegalArgumentException if a call to
1004       * prepareWriteEmpty was not called previous to this method being
1005       * called (a sequence of prepareWriteEmpty calls must be terminated
1006       * by a call to endWriteEmpty)
1007       * @exception IllegalArgumentException if prepareInsertEmpty was
1008       * called before this method being called (without a terminating
1009       * call to endInsertEmpty)
1010       * @exception IllegalArgumentException if prepareReplacePixels was
1011       * called before this method being called (without a terminating
1012       * call to endReplacePixels)
1013       * @exception IOException if a write error occurs
1014       */
1015      public void endWriteEmpty ()
1016        throws IOException
1017      {
1018        if (!canWriteEmpty())
1019          throw new UnsupportedOperationException();
1020      }
1021    
1022      /**
1023       * Complete writing a sequence of images to the output stream.  This
1024       * method may patch header data and write out footer data.
1025       *
1026       * @exception IllegalStateException if output is null
1027       * @exception IllegalStateException if prepareWriteSequence has not
1028       * been called
1029       * @exception UnsupportedOperationException if writing a sequence of
1030       * images is not supported
1031       * @exception IOException if a write error occurs
1032       */
1033      public void endWriteSequence ()
1034        throws IOException
1035      {
1036        checkOutputSet();
1037        if (!canWriteSequence())
1038          throw new UnsupportedOperationException();
1039      }
1040    
1041      /**
1042       * Start inserting an empty image in the image output stream.  All
1043       * indices after the specified index are incremented.  An index of
1044       * -1 implies that the empty image should be appended to the end of
1045       * the current image list.
1046       *
1047       * The insertion that this method call starts is not complete until
1048       * endInsertEmpty is called.  prepareInsertEmpty cannot be called
1049       * again until endInsertEmpty is called and calls to
1050       * prepareWriteEmpty and prepareInsertEmpty may not be intersperced.
1051       *
1052       * @param imageIndex the image index
1053       * @param imageType the image type specifier
1054       * @param width the image width
1055       * @param height the image height
1056       * @param imageMetadata the image metadata, or null
1057       * @param thumbnails a list of thumbnails, or null
1058       * @param param image write parameters, or null
1059       *
1060       * @exception IllegalStateException if output is null
1061       * @exception UnsupportedOperationException if inserting empty
1062       * images is not supported
1063       * @exception IndexOutOfBoundsException if imageIndex is less than
1064       * -1 or greater than the last index in the current image list
1065       * @exception IllegalStateException if a previous call to
1066       * prepareInsertEmpty was made (without a terminating call to
1067       * endInsertEmpty)
1068       * @exception IllegalStateException if a previous call to
1069       * prepareWriteEmpty was made (without a terminating call to
1070       * endWriteEmpty)
1071       * @exception IllegalArgumentException if imageType is null or
1072       * thumbnails contain non-BufferedImage objects
1073       * @exception IllegalArgumentException if either width or height is
1074       * less than 1
1075       * @exception IOException if a write error occurs
1076       */
1077      public void prepareInsertEmpty (int imageIndex, ImageTypeSpecifier imageType,
1078                                      int width, int height,
1079                                      IIOMetadata imageMetadata,
1080                                      List<? extends BufferedImage> thumbnails,
1081                                      ImageWriteParam param)
1082        throws IOException
1083      {
1084        if (!canInsertEmpty(imageIndex))
1085          throw new UnsupportedOperationException();
1086      }
1087    
1088      /**
1089       * Start the replacement of pixels within an image in the output
1090       * stream.  Output pixels will be clipped to lie within region.
1091       *
1092       * @param imageIndex the index of the image in which pixels are
1093       * being replaced
1094       * @param region the rectangle to which to limit pixel replacement
1095       *
1096       * @exception IllegalStateException if output is null
1097       * @exception UnsupportedOperationException if replacing pixels is
1098       * not supported
1099       * @exception IndexOutOfBoundsException if imageIndex is less than 0
1100       * or greater than the last index in the current image list
1101       * @exception IllegalStateException if a previous call to
1102       * prepareReplacePixels was made (without a terminating call to
1103       * endReplacePixels)
1104       * @exception IllegalArgumentException if either region.width or
1105       * region.height is less than 1, or if region is null
1106       * @exception IOException if a write error occurs
1107       */
1108      public void prepareReplacePixels (int imageIndex, Rectangle region)
1109        throws IOException
1110      {
1111        if (canReplacePixels(imageIndex))
1112          throw new UnsupportedOperationException();
1113      }
1114    
1115      /**
1116       * Start writing an empty image to the end of the image output
1117       * stream.
1118       *
1119       * The writing that this method call starts is not complete until
1120       * endWriteEmpty is called.  prepareWritetEmpty cannot be called
1121       * again until endWriteEmpty is called and calls to
1122       * prepareWriteEmpty and prepareInsertEmpty may not be intersperced.
1123       *
1124       * @param streamMetadata metadata associated with the stream, or null
1125       * @param imageType the image type specifier
1126       * @param width the image width
1127       * @param height the image height
1128       * @param imageMetadata the image metadata, or null
1129       * @param thumbnails a list of thumbnails, or null
1130       * @param param image write parameters, or null
1131       *
1132       * @exception IllegalStateException if output is null
1133       * @exception UnsupportedOperationException if writing empty images
1134       * is not supported
1135       * @exception IndexOutOfBoundsException if imageIndex is less than
1136       * -1 or greater than the last index in the current image list
1137       * @exception IllegalStateException if a previous call to
1138       * prepareInsertEmpty was made (without a terminating call to
1139       * endInsertEmpty)
1140       * @exception IllegalStateException if a previous call to
1141       * prepareWriteEmpty was made (without a terminating call to
1142       * endWriteEmpty)
1143       * @exception IllegalArgumentException if imageType is null or
1144       * thumbnails contain non-BufferedImage objects
1145       * @exception IllegalArgumentException if either width or height is
1146       * less than 1
1147       * @exception IOException if a write error occurs
1148       */
1149      public void prepareWriteEmpty (IIOMetadata streamMetadata,
1150                                     ImageTypeSpecifier imageType,
1151                                     int width, int height,
1152                                     IIOMetadata imageMetadata,
1153                                     List<? extends BufferedImage> thumbnails,
1154                                     ImageWriteParam param)
1155        throws IOException
1156      {
1157        if (!canWriteEmpty())
1158          throw new UnsupportedOperationException();
1159      }
1160    
1161      /**
1162       * Start the writing of a sequence of images.
1163       *
1164       * @param streamMetadata the stream metadata, or null
1165       *
1166       * @exception IllegalStateException if output is null
1167       * @exception UnsupportedOperationException if writing sequences of
1168       * images is not supported
1169       * @exception IOException if a write error occurs
1170       */
1171      public void prepareWriteSequence (IIOMetadata streamMetadata)
1172        throws IOException
1173      {
1174        checkOutputSet();
1175        if (!canWriteSequence())
1176          throw new UnsupportedOperationException();
1177      }
1178    
1179      /**
1180       * Remove the image at the specified index from the output stream.
1181       *
1182       * @param imageIndex the frame index from which to remove the image
1183       *
1184       * @exception IllegalStateException if output is null
1185       * @exception UnsupportedOperationException if removing this image
1186       * is not supported
1187       * @exception IndexOutOfBoundsException if imageIndex is less than 0
1188       * or greater than the last index in the current image list
1189       * @exception IOException if a write error occurs
1190       */
1191      public void removeImage (int imageIndex)
1192        throws IOException
1193      {
1194        if (!canRemoveImage(imageIndex))
1195          throw new UnsupportedOperationException();
1196      }
1197    
1198      /**
1199       * Replace the metadata associated with the image at the given
1200       * index.
1201       *
1202       * @param imageIndex the index of the image whose metadata should be
1203       * replaced
1204       * @param imageMetadata the metadata, or null
1205       *
1206       * @exception IllegalStateException if output is null
1207       * @exception UnsupportedOperationException if replacing this
1208       * image's metadata is not supported
1209       * @exception IndexOutOfBoundsException if imageIndex is less than 0
1210       * or greater than the last index in the current image list
1211       * @exception IOException if a write error occurs
1212       */
1213      public void replaceImageMetadata (int imageIndex, IIOMetadata imageMetadata)
1214        throws IOException
1215      {
1216        if (!canReplaceImageMetadata(imageIndex))
1217          throw new UnsupportedOperationException();
1218      }
1219    
1220      /**
1221       * Replace a region of an image in the output stream with a portion
1222       * of the given rendered image.  The image data must be of the same
1223       * type as that in the output stream.  The destination region is
1224       * given by the image writing parameters and the source region is
1225       * the one given to prepareReplacePixels.
1226       *
1227       * @param image the rendered image with which to overwrite the image
1228       * region in the stream
1229       * @param param the image writing parameters
1230       *
1231       * @exception IllegalStateException if output is null
1232       * @exception UnsupportedOperationException if replacing pixels is
1233       * not supported
1234       * @exception IllegalStateException if prepareReplacePixels was not
1235       * called before this method was called
1236       * @exception IllegalArgumentException if image is null or if param
1237       * is null or if the overlap of the source and destination regions
1238       * contains no pixels or if the image types differ and no conversion
1239       * is possible
1240       * @exception IOException if a write error occurs
1241       */
1242      public void replacePixels (RenderedImage image,
1243                                 ImageWriteParam param)
1244        throws IOException
1245      {
1246        if (!canReplacePixels(0))
1247          throw new UnsupportedOperationException();
1248      }
1249    
1250      /**
1251       * Replace a region of an image in the output stream with a portion
1252       * of the given raster data.  The image data must be of the same
1253       * type as that in the output stream.  The destination region is
1254       * given by the image writing parameters and the source region is
1255       * the one given to prepareReplacePixels.
1256       *
1257       * @param raster the raster data with which to overwrite the image
1258       * region in the stream
1259       * @param param the image writing parameters
1260       *
1261       * @exception IllegalStateException if output is null
1262       * @exception UnsupportedOperationException if replacing pixels is
1263       * not supported
1264       * @exception IllegalStateException if prepareReplacePixels was not
1265       * called before this method was called
1266       * @exception UnsupportedOperationException if raster data is not
1267       * supported
1268       * @exception IllegalArgumentException if raster is null or if param
1269       * is null or if the overlap of the source and destination regions
1270       * contains no pixels or if the image types differ and no conversion
1271       * is possible
1272       * @exception IOException if a write error occurs
1273       */
1274      public void replacePixels (Raster raster, ImageWriteParam param)
1275        throws IOException
1276      {
1277        if (!canReplacePixels(0))
1278        throw new UnsupportedOperationException();
1279      }
1280    
1281      /**
1282       * Replace the metadata associated with this image stream.
1283       *
1284       * @param streamMetadata the stream metadata, or null
1285       *
1286       * @exception IllegalStateException if output is null
1287       * @exception UnsupportedOperationException if replacing the stream
1288       * metadata is not supported
1289       * @exception IOException if a write error occurs
1290       */
1291      public void replaceStreamMetadata (IIOMetadata streamMetadata)
1292        throws IOException
1293      {
1294        if (!canReplaceStreamMetadata())
1295          throw new UnsupportedOperationException();
1296      }
1297    
1298      /**
1299       * Write a rendered image to the output stream.
1300       *
1301       * @param image a rendered image containing image data to be written
1302       *
1303       * @exception IllegalStateException if output is null
1304       * @exception IllegalArgumentException if image is null
1305       * @exception IOException if a write error occurs
1306       */
1307      public void write (RenderedImage image)
1308        throws IOException
1309      {
1310        checkOutputSet();
1311        write (null, new IIOImage(image, null, null), null);
1312      }
1313    
1314      /**
1315       * Write a image data, metadata and thumbnails to the output stream.
1316       *
1317       * @param image image data, metadata and thumbnails to be written
1318       *
1319       * @exception IllegalStateException if output is null
1320       * @exception UnsupportedOperationException if image contains raster
1321       * data but this writer does not support rasters
1322       * @exception IllegalArgumentException if image is null
1323       * @exception IOException if a write error occurs
1324       */
1325      public void write (IIOImage image)
1326        throws IOException
1327      {
1328        checkOutputSet();
1329        write (null, image, null);
1330      }
1331    
1332      /**
1333       * Insert an image into the output stream.  Indices greater than the
1334       * specified index are incremented accordingly.  Specifying an index
1335       * of -1 causes the image to be appended at the end of the current
1336       * image list.
1337       *
1338       * @param imageIndex the frame index at which to insert the image
1339       * @param image the image data, metadata and thumbnails to be
1340       * inserted
1341       * @param param image write parameters, or null
1342       *
1343       * @exception IllegalStateException if output is null
1344       * @exception UnsupportedOperationException if image insertion is
1345       * not supported
1346       * @exception IllegalArgumentException if image is null
1347       * @exception IndexOutOfBoundsException if imageIndex is less than
1348       * -1 or greater than the last index in the current image list
1349       * @exception UnsupportedOperationException if image contains raster
1350       * data but this writer does not support rasters
1351       * @exception IOException if a write error occurs
1352       */
1353      public void writeInsert (int imageIndex, IIOImage image, ImageWriteParam param)
1354        throws IOException
1355      {
1356        if (!canInsertImage(imageIndex))
1357          throw new UnsupportedOperationException();
1358      }
1359    
1360      /**
1361       * Write a sequence of images, including thumbnails and metadata, to
1362       * the output stream.  The output must have been set prior to this
1363       * method being called.  Metadata associated with the stream may be
1364       * supplied, or it can be left null.  IIOImage may contain raster
1365       * data if this writer supports rasters, or it will contain a
1366       * rendered image.  Thumbnails are resized if need be.  Image
1367       * writing parameters may be specified to affect writing, or may be
1368       * left null.
1369       *
1370       * @param streamMetadata metadata associated with this stream, or
1371       * null
1372       * @param image an IIOImage containing image data, metadata and
1373       * thumbnails to be written
1374       * @param param image writing parameters, or null
1375       *
1376       * @exception IllegalStateException if output is null
1377       * @exception UnsupportedOperationException if writing sequences of
1378       * images is not supported
1379       * @exception IllegalArgumentException if image is null
1380       * @exception UnsupportedOperationException if image contains raster
1381       * data but this writer does not support rasters
1382       * @exception IOException if a write error occurs
1383       */
1384      public void writeToSequence (IIOImage image, ImageWriteParam param)
1385        throws IOException
1386      {
1387        if (!canWriteSequence())
1388          throw new UnsupportedOperationException();
1389      }
1390    }