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.BufferedImage;
  44: import java.awt.image.Raster;
  45: import java.awt.image.RenderedImage;
  46: import java.io.IOException;
  47: import java.util.ArrayList;
  48: import java.util.Iterator;
  49: import java.util.List;
  50: import java.util.Locale;
  51: import java.util.ResourceBundle;
  52: import java.util.MissingResourceException;
  53: 
  54: import javax.imageio.event.IIOWriteProgressListener;
  55: import javax.imageio.event.IIOWriteWarningListener;
  56: import javax.imageio.metadata.IIOMetadata;
  57: 
  58: import javax.imageio.spi.ImageWriterSpi;
  59: 
  60: /**
  61:  * A class for encoding images within the ImageIO framework.
  62:  *
  63:  * An ImageWriter for a given format is instantiated by an
  64:  * ImageWriterSpi for that format.  ImageWriterSpis are registered
  65:  * with the IIORegistry.
  66:  *
  67:  * The ImageWriter API supports writing animated images that may have
  68:  * multiple frames; to support such images many methods take an index
  69:  * parameter.
  70:  *
  71:  * Images may also be written in multiple passes, where each
  72:  * successive pass increases the level of detail in the destination
  73:  * image.
  74:  */
  75: public abstract class ImageWriter
  76:   implements ImageTranscoder
  77: {
  78:   private boolean aborted;
  79: 
  80:   /**
  81:    * All locales available for localization of warning messages, or
  82:    * null if localization is not supported.
  83:    */
  84:   protected Locale[] availableLocales = null;
  85: 
  86:   /**
  87:    * The current locale used to localize warning messages, or null if
  88:    * no locale has been set.
  89:    */
  90:   protected Locale locale = null;
  91: 
  92:   /**
  93:    * The image writer SPI that instantiated this writer.
  94:    */
  95:   protected ImageWriterSpi originatingProvider = null;
  96: 
  97:   /**
  98:    * An ImageInputStream to which image data is written.
  99:    */
 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: }