EMMA Coverage Report (generated Wed Aug 16 18:51:55 GMT 2006)
[all classes][javax.imageio]

COVERAGE SUMMARY FOR SOURCE FILE [ImageWriter.java]

nameclass, %method, %block, %line, %
ImageWriter.java100% (1/1)9%   (5/57)12%  (77/649)12%  (27/228)

COVERAGE BREAKDOWN BY CLASS AND METHOD

nameclass, %method, %block, %line, %
     
class ImageWriter100% (1/1)9%   (5/57)12%  (77/649)12%  (27/228)
ImageWriter (ImageWriterSpi): void 100% (1/1)100% (27/27)100% (10/10)
abort (): void 0%   (0/1)0%   (0/4)0%   (0/2)
abortRequested (): boolean 0%   (0/1)0%   (0/3)0%   (0/1)
addIIOWriteProgressListener (IIOWriteProgressListener): void 0%   (0/1)0%   (0/17)0%   (0/6)
addIIOWriteWarningListener (IIOWriteWarningListener): void 0%   (0/1)0%   (0/17)0%   (0/6)
canInsertEmpty (int): boolean 0%   (0/1)0%   (0/4)0%   (0/2)
canInsertImage (int): boolean 0%   (0/1)0%   (0/4)0%   (0/2)
canRemoveImage (int): boolean 0%   (0/1)0%   (0/4)0%   (0/2)
canReplaceImageMetadata (int): boolean 0%   (0/1)0%   (0/4)0%   (0/2)
canReplacePixels (int): boolean 0%   (0/1)0%   (0/4)0%   (0/2)
canReplaceStreamMetadata (): boolean 0%   (0/1)0%   (0/4)0%   (0/2)
canWriteEmpty (): boolean 0%   (0/1)0%   (0/4)0%   (0/2)
canWriteRasters (): boolean 0%   (0/1)0%   (0/2)0%   (0/1)
canWriteSequence (): boolean 0%   (0/1)0%   (0/2)0%   (0/1)
checkOutputSet (): void 0%   (0/1)0%   (0/9)0%   (0/3)
clearAbortRequest (): void 0%   (0/1)0%   (0/4)0%   (0/2)
dispose (): void 0%   (0/1)0%   (0/1)0%   (0/1)
endInsertEmpty (): void 0%   (0/1)0%   (0/9)0%   (0/3)
endReplacePixels (): void 0%   (0/1)0%   (0/9)0%   (0/3)
endWriteEmpty (): void 0%   (0/1)0%   (0/8)0%   (0/3)
endWriteSequence (): void 0%   (0/1)0%   (0/10)0%   (0/4)
getAvailableLocales (): Locale [] 0%   (0/1)0%   (0/3)0%   (0/1)
getDefaultWriteParam (): ImageWriteParam 0%   (0/1)0%   (0/6)0%   (0/1)
getLocale (): Locale 0%   (0/1)0%   (0/3)0%   (0/1)
getNumThumbnailsSupported (ImageTypeSpecifier, ImageWriteParam, IIOMetadata, ... 0%   (0/1)0%   (0/2)0%   (0/1)
getOriginatingProvider (): ImageWriterSpi 0%   (0/1)0%   (0/3)0%   (0/1)
getOutput (): Object 100% (1/1)100% (3/3)100% (1/1)
getPreferredThumbnailSizes (ImageTypeSpecifier, ImageWriteParam, IIOMetadata,... 0%   (0/1)0%   (0/2)0%   (0/1)
prepareInsertEmpty (int, ImageTypeSpecifier, int, int, IIOMetadata, List, Ima... 0%   (0/1)0%   (0/9)0%   (0/3)
prepareReplacePixels (int, Rectangle): void 0%   (0/1)0%   (0/9)0%   (0/3)
prepareWriteEmpty (IIOMetadata, ImageTypeSpecifier, int, int, IIOMetadata, Li... 0%   (0/1)0%   (0/8)0%   (0/3)
prepareWriteSequence (IIOMetadata): void 0%   (0/1)0%   (0/10)0%   (0/4)
processImageComplete (): void 100% (1/1)21%  (4/19)29%  (2/7)
processImageProgress (float): void 0%   (0/1)0%   (0/20)0%   (0/7)
processImageStarted (int): void 100% (1/1)20%  (4/20)29%  (2/7)
processThumbnailComplete (): void 0%   (0/1)0%   (0/19)0%   (0/7)
processThumbnailProgress (float): void 0%   (0/1)0%   (0/20)0%   (0/7)
processThumbnailStarted (int, int): void 0%   (0/1)0%   (0/21)0%   (0/7)
processWarningOccurred (int, String): void 0%   (0/1)0%   (0/21)0%   (0/7)
processWarningOccurred (int, String, String): void 0%   (0/1)0%   (0/68)0%   (0/20)
processWriteAborted (): void 0%   (0/1)0%   (0/19)0%   (0/7)
removeAllIIOWriteProgressListeners (): void 0%   (0/1)0%   (0/7)0%   (0/3)
removeAllIIOWriteWarningListeners (): void 0%   (0/1)0%   (0/7)0%   (0/3)
removeIIOWriteProgressListener (IIOWriteProgressListener): void 0%   (0/1)0%   (0/12)0%   (0/5)
removeIIOWriteWarningListener (IIOWriteWarningListener): void 0%   (0/1)0%   (0/12)0%   (0/5)
removeImage (int): void 0%   (0/1)0%   (0/9)0%   (0/3)
replaceImageMetadata (int, IIOMetadata): void 0%   (0/1)0%   (0/9)0%   (0/3)
replacePixels (Raster, ImageWriteParam): void 0%   (0/1)0%   (0/9)0%   (0/3)
replacePixels (RenderedImage, ImageWriteParam): void 0%   (0/1)0%   (0/9)0%   (0/3)
replaceStreamMetadata (IIOMetadata): void 0%   (0/1)0%   (0/8)0%   (0/3)
reset (): void 0%   (0/1)0%   (0/13)0%   (0/6)
setLocale (Locale): void 0%   (0/1)0%   (0/37)0%   (0/10)
setOutput (Object): void 100% (1/1)89%  (39/44)92%  (12/13)
write (IIOImage): void 0%   (0/1)0%   (0/8)0%   (0/3)
write (RenderedImage): void 0%   (0/1)0%   (0/13)0%   (0/3)
writeInsert (int, IIOImage, ImageWriteParam): void 0%   (0/1)0%   (0/9)0%   (0/3)
writeToSequence (IIOImage, ImageWriteParam): void 0%   (0/1)0%   (0/8)0%   (0/3)

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

[all classes][javax.imageio]
EMMA 2.0.6427 (unsupported private build) (C) Vladimir Roubtsov