ImageWriterSpi


1   /*
2    * @(#)ImageWriterSpi.java  1.38 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.imageio.spi;
9   
10  import java.awt.image.RenderedImage  ;
11  import java.io.IOException  ;
12  import javax.imageio.ImageTypeSpecifier  ;
13  import javax.imageio.ImageWriter  ;
14  import javax.imageio.stream.ImageOutputStream  ;
15  
16  /**
17   * The service provider interface (SPI) for <code>ImageWriter</code>s.
18   * For more information on service provider classes, see the class comment
19   * for the <code>IIORegistry</code> class.
20   *
21   * <p> Each <code>ImageWriterSpi</code> provides several types of information
22   * about the <code>ImageWriter</code> class with which it is associated.
23   *
24   * <p> The name of the vendor who defined the SPI class and a
25   * brief description of the class are available via the
26   * <code>getVendorName</code>, <code>getDescription</code>,
27   * and <code>getVersion</code> methods.
28   * These methods may be internationalized to provide locale-specific
29   * output.  These methods are intended mainly to provide short,
30   * human-writable information that might be used to organize a pop-up
31   * menu or other list.
32   *
33   * <p> Lists of format names, file suffixes, and MIME types associated
34   * with the service may be obtained by means of the
35   * <code>getFormatNames</code>, <code>getFileSuffixes</code>, and
36   * <code>getMIMEType</code> methods.  These methods may be used to
37   * identify candidate <code>ImageWriter</code>s for writing a
38   * particular file or stream based on manual format selection, file
39   * naming, or MIME associations.
40   *
41   * <p> A more reliable way to determine which <code>ImageWriter</code>s
42   * are likely to be able to parse a particular data stream is provided
43   * by the <code>canEncodeImage</code> method.  This methods allows the
44   * service provider to inspect the actual image contents.
45   *
46   * <p> Finally, an instance of the <code>ImageWriter</code> class
47   * associated with this service provider may be obtained by calling
48   * the <code>createWriterInstance</code> method.  Any heavyweight
49   * initialization, such as the loading of native libraries or creation
50   * of large tables, should be deferred at least until the first
51   * invocation of this method.
52   *
53   * @see IIORegistry
54   * @see javax.imageio.ImageTypeSpecifier
55   * @see javax.imageio.ImageWriter
56   *
57   * @version 0.5
58   */
59  public abstract class ImageWriterSpi extends ImageReaderWriterSpi   {
60  
61      /**
62       * A single-element array, initially containing
63       * <code>ImageInputStream.class</code>, to be returned from
64       * <code>getInputTypes</code>.
65       */
66      public static final Class  [] STANDARD_OUTPUT_TYPE =
67          { ImageOutputStream  .class };
68  
69      /**
70       * An array of <code>Class</code> objects to be returned from
71       * <code>getOutputTypes</code>, initially <code>null</code>.
72       */
73      protected Class  [] outputTypes = null;
74  
75      /**
76       * An array of strings to be returned from
77       * <code>getImageReaderSpiNames</code>, initially
78       * <code>null</code>.
79       */
80      protected String  [] readerSpiNames = null;
81  
82      /**
83       * The <code>Class</code> of the writer, initially
84       * <code>null</code>.
85       */
86      private Class   writerClass = null;
87  
88      /**
89       * Constructs a blank <code>ImageWriterSpi</code>.  It is up to
90       * the subclass to initialize instance variables and/or override
91       * method implementations in order to provide working versions of
92       * all methods.
93       */
94      protected ImageWriterSpi() {
95      }
96  
97      /**
98       * Constructs an <code>ImageWriterSpi</code> with a given
99       * set of values.
100      *
101      * @param vendorName the vendor name, as a non-<code>null</code>
102      * <code>String</code>.
103      * @param version a version identifier, as a non-<code>null</code>
104      * <code>String</code>.
105      * @param names a non-<code>null</code> array of
106      * <code>String</code>s indicating the format names.  At least one
107      * entry must be present.
108      * @param suffixes an array of <code>String</code>s indicating the
109      * common file suffixes.  If no suffixes are defined,
110      * <code>null</code> should be supplied.  An array of length 0
111      * will be normalized to <code>null</code>.
112      * @param MIMETypes an array of <code>String</code>s indicating
113      * the format's MIME types.  If no suffixes are defined,
114      * <code>null</code> should be supplied.  An array of length 0
115      * will be normalized to <code>null</code>.
116      * @param writerClassName the fully-qualified name of the
117      * associated <code>ImageWriterSpi</code> class, as a
118      * non-<code>null</code> <code>String</code>.
119      * @param outputTypes an array of <code>Class</code> objects of
120      * length at least 1 indicating the legal output types.
121      * @param readerSpiNames an array <code>String</code>s of length
122      * at least 1 naming the classes of all associated
123      * <code>ImageReader</code>s, or <code>null</code>.  An array of
124      * length 0 is normalized to <code>null</code>.
125      * @param supportsStandardStreamMetadataFormat a
126      * <code>boolean</code> that indicates whether a stream metadata
127      * object can use trees described by the standard metadata format.
128      * @param nativeStreamMetadataFormatName a
129      * <code>String</code>, or <code>null</code>, to be returned from
130      * <code>getNativeStreamMetadataFormatName</code>.
131      * @param nativeStreamMetadataFormatClassName a
132      * <code>String</code>, or <code>null</code>, to be used to instantiate
133      * a metadata format object to be returned from
134      * <code>getNativeStreamMetadataFormat</code>.
135      * @param extraStreamMetadataFormatNames an array of
136      * <code>String</code>s, or <code>null</code>, to be returned from
137      * <code>getExtraStreamMetadataFormatNames</code>.  An array of length
138      * 0 is normalized to <code>null</code>.
139      * @param extraStreamMetadataFormatClassNames an array of
140      * <code>String</code>s, or <code>null</code>, to be used to instantiate
141      * a metadata format object to be returned from
142      * <code>getStreamMetadataFormat</code>.  An array of length
143      * 0 is normalized to <code>null</code>.
144      * @param supportsStandardImageMetadataFormat a
145      * <code>boolean</code> that indicates whether an image metadata
146      * object can use trees described by the standard metadata format.
147      * @param nativeImageMetadataFormatName a
148      * <code>String</code>, or <code>null</code>, to be returned from
149      * <code>getNativeImageMetadataFormatName</code>. 
150      * @param nativeImageMetadataFormatClassName a
151      * <code>String</code>, or <code>null</code>, to be used to instantiate
152      * a metadata format object to be returned from
153      * <code>getNativeImageMetadataFormat</code>.
154      * @param extraImageMetadataFormatNames an array of
155      * <code>String</code>s to be returned from
156      * <code>getExtraImageMetadataFormatNames</code>.  An array of length 0
157      * is normalized to <code>null</code>.
158      * @param extraImageMetadataFormatClassNames an array of
159      * <code>String</code>s, or <code>null</code>, to be used to instantiate
160      * a metadata format object to be returned from
161      * <code>getImageMetadataFormat</code>.  An array of length
162      * 0 is normalized to <code>null</code>.
163      *
164      * @exception IllegalArgumentException if <code>vendorName</code>
165      * is <code>null</code>.
166      * @exception IllegalArgumentException if <code>version</code>
167      * is <code>null</code>.
168      * @exception IllegalArgumentException if <code>names</code>
169      * is <code>null</code> or has length 0.
170      * @exception IllegalArgumentException if <code>writerClassName</code>
171      * is <code>null</code>.
172      * @exception IllegalArgumentException if <code>outputTypes</code>
173      * is <code>null</code> or has length 0.
174      */
175     public ImageWriterSpi(String   vendorName,
176                           String   version,
177                           String  [] names,
178                           String  [] suffixes,
179                           String  [] MIMETypes,
180                           String   writerClassName,
181                           Class  [] outputTypes,
182                           String  [] readerSpiNames,
183                           boolean supportsStandardStreamMetadataFormat,
184                           String   nativeStreamMetadataFormatName,
185                           String   nativeStreamMetadataFormatClassName,
186                           String  [] extraStreamMetadataFormatNames,
187                           String  [] extraStreamMetadataFormatClassNames,
188                           boolean supportsStandardImageMetadataFormat,
189                           String   nativeImageMetadataFormatName,
190                           String   nativeImageMetadataFormatClassName,
191                           String  [] extraImageMetadataFormatNames,
192                           String  [] extraImageMetadataFormatClassNames) {
193         super(vendorName, version,
194               names, suffixes, MIMETypes, writerClassName,
195               supportsStandardStreamMetadataFormat,
196               nativeStreamMetadataFormatName,
197               nativeStreamMetadataFormatClassName,
198               extraStreamMetadataFormatNames,
199               extraStreamMetadataFormatClassNames,
200               supportsStandardImageMetadataFormat,
201               nativeImageMetadataFormatName,
202               nativeImageMetadataFormatClassName,
203               extraImageMetadataFormatNames,
204               extraImageMetadataFormatClassNames);
205 
206         if (outputTypes == null) {
207             throw new IllegalArgumentException  
208                 ("outputTypes == null!");
209         }
210         if (outputTypes.length == 0) {
211             throw new IllegalArgumentException  
212                 ("outputTypes.length == 0!");
213         }
214         this.outputTypes = (Class  [])outputTypes.clone();
215         // If length == 0, leave it null
216         if (readerSpiNames != null && readerSpiNames.length > 0) {
217             this.readerSpiNames = (String  [])readerSpiNames.clone();
218         }
219     }
220 
221     /**
222      * Returns <code>true</code> if the format that this writer
223      * outputs preserves pixel data bit-accurately.  The default
224      * implementation returns <code>true</code>.
225      *
226      * @return <code>true</code> if the format preserves full pixel
227      * accuracy.
228      */
229     public boolean isFormatLossless() {
230         return true;
231     }
232 
233     /**
234      * Returns an array of <code>Class</code> objects indicating what
235      * types of objects may be used as arguments to the writer's
236      * <code>setOutput</code> method.
237      *
238      * <p> For most writers, which only output to an
239      * <code>ImageOutputStream</code>, a single-element array
240      * containing <code>ImageOutputStream.class</code> should be
241      * returned.
242      *
243      * @return a non-<code>null</code> array of
244      * <code>Class</code>objects of length at least 1.
245      */
246     public Class  [] getOutputTypes() {
247         return (Class  [])outputTypes.clone();
248     }
249 
250     /**
251      * Returns <code>true</code> if the <code>ImageWriter</code>
252      * implementation associated with this service provider is able to
253      * encode an image with the given layout.  The layout
254      * (<i>i.e.</i>, the image's <code>SampleModel</code> and
255      * <code>ColorModel</code>) is described by an
256      * <code>ImageTypeSpecifier</code> object.
257      *
258      * <p> A return value of <code>true</code> is not an absolute
259      * guarantee of successful encoding; the encoding process may still
260      * produce errors due to factors such as I/O errors, inconsistent
261      * or malformed data structures, etc.  The intent is that a
262      * reasonable inspection of the basic structure of the image be
263      * performed in order to determine if it is within the scope of
264      * the encoding format.  For example, a service provider for a
265      * format that can only encode greyscale would return
266      * <code>false</code> if handed an RGB <code>BufferedImage</code>.
267      * Similarly, a service provider for a format that can encode
268      * 8-bit RGB imagery might refuse to encode an image with an
269      * associated alpha channel.
270      *
271      * <p> Different <code>ImageWriter</code>s, and thus service
272      * providers, may choose to be more or less strict.  For example,
273      * they might accept an image with premultiplied alpha even though
274      * it will have to be divided out of each pixel, at some loss of
275      * precision, in order to be stored.
276      *
277      * @param type an <code>ImageTypeSpecifier</code> specifying the
278      * layout of the image to be written.
279      *
280      * @return <code>true</code> if this writer is likely to be able
281      * to encode images with the given layout.
282      *
283      * @exception IllegalArgumentException if <code>type</code>
284      * is <code>null</code>.
285      */
286     public abstract boolean canEncodeImage(ImageTypeSpecifier   type);
287 
288     /**
289      * Returns <code>true</code> if the <code>ImageWriter</code>
290      * implementation associated with this service provider is able to
291      * encode the given <code>RenderedImage</code> instance.  Note
292      * that this includes instances of
293      * <code>java.awt.image.BufferedImage</code>.
294      *
295      * <p> See the discussion for
296      * <code>canEncodeImage(ImageTypeSpecifier)</code> for information
297      * on the semantics of this method.
298      *
299      * @param im an instance of <code>RenderedImage</code> to be encoded.
300      *
301      * @return <code>true</code> if this writer is likely to be able
302      * to encode this image.
303      *
304      * @exception IllegalArgumentException if <code>im</code>
305      * is <code>null</code>.
306      */
307     public boolean canEncodeImage(RenderedImage   im) {
308         return canEncodeImage(ImageTypeSpecifier.createFromRenderedImage(im));
309     }
310 
311     /**
312      * Returns an instance of the <code>ImageWriter</code>
313      * implementation associated with this service provider.
314      * The returned object will initially be in an initial state as if
315      * its <code>reset</code> method had been called.
316      *
317      * <p> The default implementation simply returns
318      * <code>createWriterInstance(null)</code>.
319      *     
320      * @return an <code>ImageWriter</code> instance.
321      *
322      * @exception IOException if an error occurs during loading, 
323      * or initialization of the writer class, or during instantiation
324      * or initialization of the writer object.
325      */
326     public ImageWriter   createWriterInstance() throws IOException   {
327         return createWriterInstance(null);
328     }
329 
330     /**
331      * Returns an instance of the <code>ImageWriter</code>
332      * implementation associated with this service provider.
333      * The returned object will initially be in an initial state
334      * as if its <code>reset</code> method had been called.
335      *
336      * <p> An <code>Object</code> may be supplied to the plug-in at
337      * construction time.  The nature of the object is entirely
338      * plug-in specific.
339      *
340      * <p> Typically, a plug-in will implement this method using code
341      * such as <code>return new MyImageWriter(this)</code>.
342      *
343      * @param extension a plug-in specific extension object, which may
344      * be <code>null</code>.
345      *
346      * @return an <code>ImageWriter</code> instance.
347      *
348      * @exception IOException if the attempt to instantiate
349      * the writer fails.
350      * @exception IllegalArgumentException if the
351      * <code>ImageWriter</code>'s constructor throws an
352      * <code>IllegalArgumentException</code> to indicate that the
353      * extension object is unsuitable.
354      */
355     public abstract ImageWriter   createWriterInstance(Object   extension)
356         throws IOException  ;
357 
358     /**
359      * Returns <code>true</code> if the <code>ImageWriter</code> object
360      * passed in is an instance of the <code>ImageWriter</code> 
361      * associated with this service provider.
362      *
363      * @param writer an <code>ImageWriter</code> instance.
364      *
365      * @return <code>true</code> if <code>writer</code> is recognized
366      *
367      * @exception IllegalArgumentException if <code>writer</code> is
368      * <code>null</code>.
369      */
370     public boolean isOwnWriter(ImageWriter   writer) { 
371         if (writer == null) {
372             throw new IllegalArgumentException  ("writer == null!");
373         }
374         String   name = writer.getClass().getName();
375         return name.equals(pluginClassName);
376     }
377 
378     /**
379      * Returns an array of <code>String</code>s containing all the
380      * fully qualified names of all the <code>ImageReaderSpi</code>
381      * classes that can understand the internal metadata
382      * representation used by the <code>ImageWriter</code> associated
383      * with this service provider, or <code>null</code> if there are
384      * no such <code>ImageReaders</code> specified.  If a
385      * non-<code>null</code> value is returned, it must have non-zero
386      * length.
387      *
388      * <p> The first item in the array must be the name of the service
389      * provider for the "preferred" reader, as it will be used to
390      * instantiate the <code>ImageReader</code> returned by
391      * <code>ImageIO.getImageReader(ImageWriter)</code>.
392      *
393      * <p> This mechanism may be used to obtain
394      * <code>ImageReaders</code> that will generated non-pixel
395      * meta-data (see <code>IIOExtraDataInfo</code>) in a structure
396      * understood by an <code>ImageWriter</code>.  By reading the
397      * image and obtaining this data from one of the
398      * <code>ImageReaders</code> obtained with this method and passing
399      * it on to the <code>ImageWriter</code>, a client program can
400      * read an image, modify it in some way, and write it back out
401      * preserving all meta-data, without having to understand anything
402      * about the internal structure of the meta-data, or even about
403      * the image format.
404      *
405      * @return an array of <code>String</code>s of length at least 1
406      * containing names of <code>ImageReaderSpi</code>s, or
407      * <code>null</code>.
408      *
409      * @see javax.imageio.ImageIO#getImageReader(ImageWriter)
410      * @see ImageReaderSpi#getImageWriterSpiNames()
411      */
412     public String  [] getImageReaderSpiNames() {
413         return readerSpiNames == null ?
414             null : (String  [])readerSpiNames.clone();
415     }
416 }
417
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags