ImageReaderSpi


1   /*
2    * @(#)ImageReaderSpi.java  1.41 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.io.IOException  ;
11  import javax.imageio.ImageReader  ;
12  import javax.imageio.stream.ImageInputStream  ;
13  
14  /**
15   * The service provider interface (SPI) for <code>ImageReader</code>s.
16   * For more information on service provider classes, see the class comment
17   * for the <code>IIORegistry</code> class.
18   * 
19   * <p> Each <code>ImageReaderSpi</code> provides several types of information
20   * about the <code>ImageReader</code> class with which it is associated.
21   *
22   * <p> The name of the vendor who defined the SPI class and a
23   * brief description of the class are available via the
24   * <code>getVendorName</code>, <code>getDescription</code>,
25   * and <code>getVersion</code> methods.
26   * These methods may be internationalized to provide locale-specific
27   * output.  These methods are intended mainly to provide short,
28   * human-readable information that might be used to organize a pop-up
29   * menu or other list.
30   *
31   * <p> Lists of format names, file suffixes, and MIME types associated
32   * with the service may be obtained by means of the
33   * <code>getFormatNames</code>, <code>getFileSuffixes</code>, and
34   * <code>getMIMETypes</code> methods.  These methods may be used to
35   * identify candidate <code>ImageReader</code>s for decoding a
36   * particular file or stream based on manual format selection, file
37   * naming, or MIME associations (for example, when accessing a file
38   * over HTTP or as an email attachment).
39   *
40   * <p> A more reliable way to determine which <code>ImageReader</code>s
41   * are likely to be able to parse a particular data stream is provided
42   * by the <code>canDecodeInput</code> method.  This methods allows the
43   * service provider to inspect the actual stream contents.
44   *
45   * <p> Finally, an instance of the <code>ImageReader</code> class
46   * associated with this service provider may be obtained by calling
47   * the <code>createReaderInstance</code> method.  Any heavyweight
48   * initialization, such as the loading of native libraries or creation
49   * of large tables, should be deferred at least until the first
50   * invocation of this method.
51   *
52   * @see IIORegistry
53   * @see javax.imageio.ImageReader
54   *
55   * @version 0.5
56   */
57  public abstract class ImageReaderSpi extends ImageReaderWriterSpi   {
58  
59      /**
60       * A single-element array, initially containing
61       * <code>ImageInputStream.class</code>, to be returned from
62       * <code>getInputTypes</code>.
63       */
64      public static final Class  [] STANDARD_INPUT_TYPE =
65          { ImageInputStream  .class };
66  
67      /**
68       * An array of <code>Class</code> objects to be returned from
69       * <code>getInputTypes</code>, initially <code>null</code>.
70       */
71      protected Class  [] inputTypes = null;
72  
73      /**
74       * An array of strings to be returned from
75       * <code>getImageWriterSpiNames</code>, initially
76       * <code>null</code>.
77       */
78      protected String  [] writerSpiNames = null;
79  
80      /**
81       * The <code>Class</code> of the reader, initially
82       * <code>null</code>.
83       */
84      private Class   readerClass = null;
85      
86      /**
87       * Constructs a blank <code>ImageReaderSpi</code>.  It is up to
88       * the subclass to initialize instance variables and/or override
89       * method implementations in order to provide working versions of
90       * all methods.
91       */
92      protected ImageReaderSpi() {
93      }
94  
95      /**
96       * Constructs an <code>ImageReaderSpi</code> with a given
97       * set of values.
98       *
99       * @param vendorName the vendor name, as a non-<code>null</code>
100      * <code>String</code>.
101      * @param version a version identifier, as a non-<code>null</code>
102      * <code>String</code>.
103      * @param names a non-<code>null</code> array of
104      * <code>String</code>s indicating the format names.  At least one
105      * entry must be present.
106      * @param suffixes an array of <code>String</code>s indicating the
107      * common file suffixes.  If no suffixes are defined,
108      * <code>null</code> should be supplied.  An array of length 0
109      * will be normalized to <code>null</code>.
110      * @param MIMETypes an array of <code>String</code>s indicating
111      * the format's MIME types.  If no MIME types are defined,
112      * <code>null</code> should be supplied.  An array of length 0
113      * will be normalized to <code>null</code>.
114      * @param readerClassName the fully-qualified name of the
115      * associated <code>ImageReader</code> class, as a
116      * non-<code>null</code> <code>String</code>.
117      * @param inputTypes a non-<code>null</code> array of
118      * <code>Class</code> objects of length at least 1 indicating the
119      * legal input types.
120      * @param writerSpiNames an array <code>String</code>s naming the
121      * classes of all associated <code>ImageWriter</code>s, or
122      * <code>null</code>.  An array of length 0 is normalized to
123      * <code>null</code>.
124      * @param supportsStandardStreamMetadataFormat a
125      * <code>boolean</code> that indicates whether a stream metadata
126      * object can use trees described by the standard metadata format.
127      * @param nativeStreamMetadataFormatName a
128      * <code>String</code>, or <code>null</code>, to be returned from
129      * <code>getNativeStreamMetadataFormatName</code>.
130      * @param nativeStreamMetadataFormatClassName a
131      * <code>String</code>, or <code>null</code>, to be used to instantiate
132      * a metadata format object to be returned from
133      * <code>getNativeStreamMetadataFormat</code>.
134      * @param extraStreamMetadataFormatNames an array of
135      * <code>String</code>s, or <code>null</code>, to be returned from
136      * <code>getExtraStreamMetadataFormatNames</code>.  An array of length
137      * 0 is normalized to <code>null</code>.
138      * @param extraStreamMetadataFormatClassNames an array of
139      * <code>String</code>s, or <code>null</code>, to be used to instantiate
140      * a metadata format object to be returned from
141      * <code>getStreamMetadataFormat</code>.  An array of length
142      * 0 is normalized to <code>null</code>.
143      * @param supportsStandardImageMetadataFormat a
144      * <code>boolean</code> that indicates whether an image metadata
145      * object can use trees described by the standard metadata format.
146      * @param nativeImageMetadataFormatName a
147      * <code>String</code>, or <code>null</code>, to be returned from
148      * <code>getNativeImageMetadataFormatName</code>. 
149      * @param nativeImageMetadataFormatClassName a
150      * <code>String</code>, or <code>null</code>, to be used to instantiate
151      * a metadata format object to be returned from
152      * <code>getNativeImageMetadataFormat</code>.
153      * @param extraImageMetadataFormatNames an array of
154      * <code>String</code>s to be returned from
155      * <code>getExtraImageMetadataFormatNames</code>.  An array of length 0
156      * is normalized to <code>null</code>.
157      * @param extraImageMetadataFormatClassNames an array of
158      * <code>String</code>s, or <code>null</code>, to be used to instantiate
159      * a metadata format object to be returned from
160      * <code>getImageMetadataFormat</code>.  An array of length
161      * 0 is normalized to <code>null</code>.
162      *
163      * @exception IllegalArgumentException if <code>vendorName</code>
164      * is <code>null</code>.
165      * @exception IllegalArgumentException if <code>version</code>
166      * is <code>null</code>.
167      * @exception IllegalArgumentException if <code>names</code>
168      * is <code>null</code> or has length 0.
169      * @exception IllegalArgumentException if <code>readerClassName</code>
170      * is <code>null</code>.
171      * @exception IllegalArgumentException if <code>inputTypes</code>
172      * is <code>null</code> or has length 0.
173      */
174     public ImageReaderSpi(String   vendorName,
175                           String   version,
176                           String  [] names,
177                           String  [] suffixes,
178                           String  [] MIMETypes,
179                           String   readerClassName,
180                           Class  [] inputTypes,
181                           String  [] writerSpiNames,
182                           boolean supportsStandardStreamMetadataFormat,
183                           String   nativeStreamMetadataFormatName,
184                           String   nativeStreamMetadataFormatClassName,
185                           String  [] extraStreamMetadataFormatNames,
186                           String  [] extraStreamMetadataFormatClassNames,
187                           boolean supportsStandardImageMetadataFormat,
188                           String   nativeImageMetadataFormatName,
189                           String   nativeImageMetadataFormatClassName,
190                           String  [] extraImageMetadataFormatNames,
191                           String  [] extraImageMetadataFormatClassNames) {
192         super(vendorName, version,
193               names, suffixes, MIMETypes, readerClassName,
194               supportsStandardStreamMetadataFormat,
195               nativeStreamMetadataFormatName,
196               nativeStreamMetadataFormatClassName,
197               extraStreamMetadataFormatNames,
198               extraStreamMetadataFormatClassNames,
199               supportsStandardImageMetadataFormat,
200               nativeImageMetadataFormatName,
201               nativeImageMetadataFormatClassName,
202               extraImageMetadataFormatNames,
203               extraImageMetadataFormatClassNames);
204 
205         if (inputTypes == null) {
206             throw new IllegalArgumentException  
207                 ("inputTypes == null!");
208         }
209         if (inputTypes.length == 0) {
210             throw new IllegalArgumentException  
211                 ("inputTypes.length == 0!");
212         }
213         this.inputTypes = (Class  [])inputTypes.clone();
214         // If length == 0, leave it null
215         if (writerSpiNames != null && writerSpiNames.length > 0) {
216             this.writerSpiNames = (String  [])writerSpiNames.clone();
217         }
218     }
219 
220     /**
221      * Returns an array of <code>Class</code> objects indicating what
222      * types of objects may be used as arguments to the reader's
223      * <code>setInput</code> method.
224      *
225      * <p> For most readers, which only accept input from an
226      * <code>ImageInputStream</code>, a single-element array
227      * containing <code>ImageInputStream.class</code> should be
228      * returned.
229      * 
230      * @return a non-<code>null</code> array of
231      * <code>Class</code>objects of length at least 1.
232      */
233     public Class  [] getInputTypes() {
234         return (Class  [])inputTypes.clone();
235     }
236 
237     /**
238      * Returns <code>true</code> if the supplied source object appears
239      * to be of the format supported by this reader.  Returning
240      * <code>true</code> from this method does not guarantee that
241      * reading will succeed, only that there appears to be a
242      * reasonable chance of success based on a brief inspection of the
243      * stream contents.  If the source is an
244      * <code>ImageInputStream</code>, implementations will commonly
245      * check the first several bytes of the stream for a "magic
246      * number" associated with the format.  Once actual reading has
247      * commenced, the reader may still indicate failure at any time
248      * prior to the completion of decoding.
249      *
250      * <p> It is important that the state of the object not be
251      * disturbed in order that other <code>ImageReaderSpi</code>s can
252      * properly determine whether they are able to decode the object.
253      * In particular, if the source is an
254      * <code>ImageInputStream</code>, a
255      * <code>mark</code>/<code>reset</code> pair should be used to
256      * preserve the stream position.
257      *
258      * <p> Formats such as "raw," which can potentially attempt
259      * to read nearly any stream, should return <code>false</code>
260      * in order to avoid being invoked in preference to a closer
261      * match.
262      *
263      * <p> If <code>source</code> is not an instance of one of the
264      * classes returned by <code>getInputTypes</code>, the method
265      * should simply return <code>false</code>.
266      *
267      * @param source the object (typically an
268      * <code>ImageInputStream</code>) to be decoded.
269      *
270      * @return <code>true</code> if it is likely that this stream can
271      * be decoded.
272      *
273      * @exception IllegalArgumentException if <code>source</code> is
274      * <code>null</code>.
275      * @exception IOException if an I/O error occurs while reading the
276      * stream.
277      */
278     public abstract boolean canDecodeInput(Object   source) throws IOException  ;
279 
280     /**
281      * Returns an instance of the <code>ImageReader</code>
282      * implementation associated with this service provider.
283      * The returned object will initially be in an initial state
284      * as if its <code>reset</code> method had been called.
285      *
286      * <p> The default implementation simply returns
287      * <code>createReaderInstance(null)</code>.
288      *
289      * @return an <code>ImageReader</code> instance.
290      *
291      * @exception IOException if an error occurs during loading, 
292      * or initialization of the reader class, or during instantiation
293      * or initialization of the reader object.
294      */
295     public ImageReader   createReaderInstance() throws IOException   {
296         return createReaderInstance(null);
297     }
298 
299     /**
300      * Returns an instance of the <code>ImageReader</code>
301      * implementation associated with this service provider.
302      * The returned object will initially be in an initial state
303      * as if its <code>reset</code> method had been called.
304      *
305      * <p> An <code>Object</code> may be supplied to the plug-in at
306      * construction time.  The nature of the object is entirely
307      * plug-in specific.
308      *
309      * <p> Typically, a plug-in will implement this method using code
310      * such as <code>return new MyImageReader(this)</code>.
311      *
312      * @param extension a plug-in specific extension object, which may
313      * be <code>null</code>.
314      *
315      * @return an <code>ImageReader</code> instance.
316      *
317      * @exception IOException if the attempt to instantiate
318      * the reader fails.
319      * @exception IllegalArgumentException if the
320      * <code>ImageReader</code>'s contructor throws an
321      * <code>IllegalArgumentException</code> to indicate that the
322      * extension object is unsuitable.
323      */
324     public abstract ImageReader   createReaderInstance(Object   extension) 
325         throws IOException  ;
326 
327     /**
328      * Returns <code>true</code> if the <code>ImageReader</code> object
329      * passed in is an instance of the <code>ImageReader</code> 
330      * associated with this service provider.
331      *
332      * <p> The default implementation compares the fully-qualified
333      * class name of the <code>reader</code> argument with the class
334      * name passed into the constructor.  This method may be overridden
335      * if more sophisticated checking is required.
336      *
337      * @param reader an <code>ImageReader</code> instance.
338      *
339      * @return <code>true</code> if <code>reader</code> is recognized.
340      *
341      * @exception IllegalArgumentException if <code>reader</code> is
342      * <code>null</code>.
343      */
344     public boolean isOwnReader(ImageReader   reader) {
345         if (reader == null) {
346             throw new IllegalArgumentException  ("reader == null!");
347         }
348         String   name = reader.getClass().getName();
349         return name.equals(pluginClassName);
350     }
351 
352     /**
353      * Returns an array of <code>String</code>s containing the fully
354      * qualified names of all the <code>ImageWriterSpi</code> classes
355      * that can understand the internal metadata representation used
356      * by the <code>ImageReader</code> associated with this service
357      * provider, or <code>null</code> if there are no such
358      * <code>ImageWriter</code>s specified.  If a
359      * non-<code>null</code> value is returned, it must have non-zero
360      * length.
361      *
362      * <p> The first item in the array must be the name of the service
363      * provider for the "preferred" writer, as it will be used to
364      * instantiate the <code>ImageWriter</code> returned by
365      * <code>ImageIO.getImageWriter(ImageReader)</code>.
366      *
367      * <p> This mechanism may be used to obtain
368      * <code>ImageWriters</code> that will understand the internal
369      * structure of non-pixel meta-data (see
370      * <code>IIOTreeInfo</code>) generated by an
371      * <code>ImageReader</code>.  By obtaining this data from the
372      * <code>ImageReader</code> and passing it on to one of the
373      * <code>ImageWriters</code> obtained with this method, a client
374      * program can read an image, modify it in some way, and write it
375      * back out while preserving all meta-data, without having to
376      * understand anything about the internal structure of the
377      * meta-data, or even about the image format.
378      *
379      * @return an array of <code>String</code>s of length at least 1
380      * containing names of <code>ImageWriterSpi</code>, or
381      * <code>null</code>.
382      *
383      * @see javax.imageio.ImageIO#getImageWriter(ImageReader)
384      */
385     public String  [] getImageWriterSpiNames() {
386         return writerSpiNames == null ?
387             null : (String  [])writerSpiNames.clone();
388     }
389 }
390
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags