| Frames | No Frames |
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: }