Source for javax.imageio.ImageWriter

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