Java > Open Source Codes > javax > imageio > spi > ImageReaderWriterSpi


1 /*
2  * @(#)ImageReaderWriterSpi.java 1.20 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 java.lang.reflect.Constructor ;
12 import java.lang.reflect.Method ;
13 import java.util.Arrays ;
14 import java.util.Iterator ;
15 import javax.imageio.ImageReader ;
16 import javax.imageio.metadata.IIOMetadata ;
17 import javax.imageio.metadata.IIOMetadataFormat ;
18 import javax.imageio.metadata.IIOMetadataFormatImpl ;
19 import javax.imageio.stream.ImageInputStream ;
20
21 /**
22  * A superclass containing instance variables and methods common to
23  * <code>ImageReaderSpi</code> and <code>ImageWriterSpi</code>.
24  *
25  * @see IIORegistry
26  * @see ImageReaderSpi
27  * @see ImageWriterSpi
28  *
29  * @version 0.5
30  */
31 public abstract class ImageReaderWriterSpi extends IIOServiceProvider {
32
33     /**
34      * An array of strings to be returned from
35      * <code>getFormatNames</code>, initially <code>null</code>.
36      * Constructors should set this to a non-<code>null</code> value.
37      */
38     protected String [] names = null;
39
40     /**
41      * An array of strings to be returned from
42      * <code>getFileSuffixes</code>, initially <code>null</code>.
43      */
44     protected String [] suffixes = null;
45
46     /**
47      * An array of strings to be returned from
48      * <code>getMIMETypes</code>, initially <code>null</code>.
49      */
50     protected String [] MIMETypes = null;
51
52     /**
53      * A <code>String</code> containing the name of the associated
54      * plug-in class, initially <code>null</code>.
55      */
56     protected String pluginClassName = null;
57    
58     /**
59      * A boolean indicating whether this plug-in supports the
60      * standard metadata format for stream metadata, initially
61      * <code>false</code>.
62      */
63     protected boolean supportsStandardStreamMetadataFormat = false;
64
65     /**
66      * A <code>String</code> containing the name of the native stream
67      * metadata format supported by this plug-in, initially
68      * <code>null</code>.
69      */
70     protected String nativeStreamMetadataFormatName = null;
71
72     /**
73      * A <code>String</code> containing the class name of the native
74      * stream metadata format supported by this plug-in, initially
75      * <code>null</code>.
76      */
77     protected String nativeStreamMetadataFormatClassName = null;
78
79     /**
80      * An array of <code>String</code>s containing the names of any
81      * additional stream metadata formats supported by this plug-in,
82      * initially <code>null</code>.
83      */
84     protected String [] extraStreamMetadataFormatNames = null;
85
86     /**
87      * An array of <code>String</code>s containing the class names of
88      * any additional stream metadata formats supported by this plug-in,
89      * initially <code>null</code>.
90      */
91     protected String [] extraStreamMetadataFormatClassNames = null;
92
93     /**
94      * A boolean indicating whether this plug-in supports the
95      * standard metadata format for image metadata, initially
96      * <code>false</code>.
97      */
98     protected boolean supportsStandardImageMetadataFormat = false;
99
100     /**
101      * A <code>String</code> containing the name of the
102      * native stream metadata format supported by this plug-in,
103      * initially <code>null</code>.
104      */
105     protected String nativeImageMetadataFormatName = null;
106
107     /**
108      * A <code>String</code> containing the class name of the
109      * native stream metadata format supported by this plug-in,
110      * initially <code>null</code>.
111      */
112     protected String nativeImageMetadataFormatClassName = null;
113
114     /**
115      * An array of <code>String</code>s containing the names of any
116      * additional image metadata formats supported by this plug-in,
117      * initially <code>null</code>.
118      */
119     protected String [] extraImageMetadataFormatNames = null;
120
121     /**
122      * An array of <code>String</code>s containing the class names of
123      * any additional image metadata formats supported by this
124      * plug-in, initially <code>null</code>.
125      */
126     protected String [] extraImageMetadataFormatClassNames = null;
127
128     /**
129      * Constructs an <code>ImageReaderWriterSpi</code> with a given
130      * set of values.
131      *
132      * @param vendorName the vendor name, as a non-<code>null</code>
133      * <code>String</code>.
134      * @param version a version identifier, as a non-<code>null</code>
135      * <code>String</code>.
136      * @param names a non-<code>null</code> array of
137      * <code>String</code>s indicating the format names. At least one
138      * entry must be present.
139      * @param suffixes an array of <code>String</code>s indicating the
140      * common file suffixes. If no suffixes are defined,
141      * <code>null</code> should be supplied. An array of length 0
142      * will be normalized to <code>null</code>.
143      * @param MIMETypes an array of <code>String</code>s indicating
144      * the format's MIME types. If no MIME types are defined,
145      * <code>null</code> should be supplied. An array of length 0
146      * will be normalized to <code>null</code>.
147      * @param pluginClassName the fully-qualified name of the
148      * associated <code>ImageReader</code> or <code>ImageWriter</code>
149      * class, as a non-<code>null</code> <code>String</code>.
150      * @param supportsStandardStreamMetadataFormat a
151      * <code>boolean</code> that indicates whether a stream metadata
152      * object can use trees described by the standard metadata format.
153      * @param nativeStreamMetadataFormatName a
154      * <code>String</code>, or <code>null</code>, to be returned from
155      * <code>getNativeStreamMetadataFormatName</code>.
156      * @param nativeStreamMetadataFormatClassName a
157      * <code>String</code>, or <code>null</code>, to be used to instantiate
158      * a metadata format object to be returned from
159      * <code>getNativeStreamMetadataFormat</code>.
160      * @param extraStreamMetadataFormatNames an array of
161      * <code>String</code>s, or <code>null</code>, to be returned from
162      * <code>getExtraStreamMetadataFormatNames</code>. An array of length
163      * 0 is normalized to <code>null</code>.
164      * @param extraStreamMetadataFormatClassNames an array of
165      * <code>String</code>s, or <code>null</code>, to be used to instantiate
166      * a metadata format object to be returned from
167      * <code>getStreamMetadataFormat</code>. An array of length
168      * 0 is normalized to <code>null</code>.
169      * @param supportsStandardImageMetadataFormat a
170      * <code>boolean</code> that indicates whether an image metadata
171      * object can use trees described by the standard metadata format.
172      * @param nativeImageMetadataFormatName a
173      * <code>String</code>, or <code>null</code>, to be returned from
174      * <code>getNativeImageMetadataFormatName</code>.
175      * @param nativeImageMetadataFormatClassName a
176      * <code>String</code>, or <code>null</code>, to be used to instantiate
177      * a metadata format object to be returned from
178      * <code>getNativeImageMetadataFormat</code>.
179      * @param extraImageMetadataFormatNames an array of
180      * <code>String</code>s to be returned from
181      * <code>getExtraImageMetadataFormatNames</code>. An array of length 0
182      * is normalized to <code>null</code>.
183      * @param extraImageMetadataFormatClassNames an array of
184      * <code>String</code>s, or <code>null</code>, to be used to instantiate
185      * a metadata format object to be returned from
186      * <code>getImageMetadataFormat</code>. An array of length
187      * 0 is normalized to <code>null</code>.
188      *
189      * @exception IllegalArgumentException if <code>vendorName</code>
190      * is <code>null</code>.
191      * @exception IllegalArgumentException if <code>version</code>
192      * is <code>null</code>.
193      * @exception IllegalArgumentException if <code>names</code>
194      * is <code>null</code> or has length 0.
195      * @exception IllegalArgumentException if <code>pluginClassName</code>
196      * is <code>null</code>.
197      */
198     public ImageReaderWriterSpi(String vendorName,
199                                 String version,
200                                 String [] names,
201                                 String [] suffixes,
202                                 String [] MIMETypes,
203                                 String pluginClassName,
204                                 boolean supportsStandardStreamMetadataFormat,
205                                 String nativeStreamMetadataFormatName,
206                                 String nativeStreamMetadataFormatClassName,
207                                 String [] extraStreamMetadataFormatNames,
208                                 String [] extraStreamMetadataFormatClassNames,
209                                 boolean supportsStandardImageMetadataFormat,
210                                 String nativeImageMetadataFormatName,
211                                 String nativeImageMetadataFormatClassName,
212                                 String [] extraImageMetadataFormatNames,
213                                 String [] extraImageMetadataFormatClassNames) {
214         super(vendorName, version);
215         if (names == null) {
216             throw new IllegalArgumentException ("names == null!");
217         }
218         if (names.length == 0) {
219             throw new IllegalArgumentException ("names.length == 0!");
220         }
221         if (pluginClassName == null) {
222             throw new IllegalArgumentException ("pluginClassName == null!");
223         }
224
225         this.names = (String [])names.clone();
226         // If length == 0, leave it null
227 if (suffixes != null && suffixes.length > 0) {
228             this.suffixes = (String [])suffixes.clone();
229         }
230         // If length == 0, leave it null
231 if (MIMETypes != null && MIMETypes.length > 0) {
232             this.MIMETypes = (String [])MIMETypes.clone();
233         }
234         this.pluginClassName = pluginClassName;
235
236         this.supportsStandardStreamMetadataFormat =
237             supportsStandardStreamMetadataFormat;
238         this.nativeStreamMetadataFormatName = nativeStreamMetadataFormatName;
239         this.nativeStreamMetadataFormatClassName =
240             nativeStreamMetadataFormatClassName;
241         // If length == 0, leave it null
242 if (extraStreamMetadataFormatNames != null &&
243             extraStreamMetadataFormatNames.length > 0) {
244             this.extraStreamMetadataFormatNames =
245                 (String [])extraStreamMetadataFormatNames.clone();
246         }
247         // If length == 0, leave it null
248 if (extraStreamMetadataFormatClassNames != null &&
249             extraStreamMetadataFormatClassNames.length > 0) {
250             this.extraStreamMetadataFormatClassNames =
251                 (String [])extraStreamMetadataFormatClassNames.clone();
252         }
253         this.supportsStandardImageMetadataFormat =
254             supportsStandardImageMetadataFormat;
255         this.nativeImageMetadataFormatName = nativeImageMetadataFormatName;
256         this.nativeImageMetadataFormatClassName =
257             nativeImageMetadataFormatClassName;
258         // If length == 0, leave it null
259 if (extraImageMetadataFormatNames != null &&
260             extraImageMetadataFormatNames.length > 0) {
261             this.extraImageMetadataFormatNames =
262                 (String [])extraImageMetadataFormatNames.clone();
263         }
264         // If length == 0, leave it null
265 if (extraImageMetadataFormatClassNames != null &&
266             extraImageMetadataFormatClassNames.length > 0) {
267             this.extraImageMetadataFormatClassNames =
268                 (String [])extraImageMetadataFormatClassNames.clone();
269         }
270     }
271
272     /**
273      * Constructs a blank <code>ImageReaderWriterSpi</code>. It is up
274      * to the subclass to initialize instance variables and/or
275      * override method implementations in order to provide working
276      * versions of all methods.
277      */
278     public ImageReaderWriterSpi() {
279     }
280
281     /**
282      * Returns an array of <code>String</code>s containing
283      * human-readable names for the formats that are generally usable
284      * by the <code>ImageReader</code> or <code>ImageWriter</code>
285      * implementation associated with this service provider. For
286      * example, a single <code>ImageReader</code> might be able to
287      * process both PBM and PNM files.
288      *
289      * @return a non-<code>null</code> array of <code>String</code>s
290      * or length at least 1 containing informal format names
291      * associated with this reader or writer.
292      */
293     public String [] getFormatNames() {
294         return (String [])names.clone();
295     }
296
297     /**
298      * Returns an array of <code>String</code>s containing a list of
299      * file suffixes associated with the formats that are generally
300      * usable by the <code>ImageReader</code> or
301      * <code>ImageWriter</code> implementation associated with this
302      * service provider. For example, a single
303      * <code>ImageReader</code> might be able to process files with
304      * '.pbm' and '.pnm' suffixes, or both '.jpg' and '.jpeg'
305      * suffixes. If there are no known file suffixes,
306      * <code>null</code> will be returned.
307      *
308      * <p> Returning a particular suffix does not guarantee that files
309      * with that suffix can be processed; it merely indicates that it
310      * may be worthwhile attempting to decode or encode such files
311      * using this service provider.
312      *
313      * @return an array of <code>String</code>s or length at least 1
314      * containing common file suffixes associated with this reader or
315      * writer, or <code>null</code>.
316      */
317     public String [] getFileSuffixes() {
318         return suffixes == null ? null : (String [])suffixes.clone();
319     }
320
321     /**
322      * Returns an array of <code>String</code>s containing a list of
323      * MIME types associated with the formats that are generally
324      * usable by the <code>ImageReader</code> or
325      * <code>ImageWriter</code> implementation associated with this
326      * service provider.
327      *
328      * <p> Ideally, only a single MIME type would be required in order
329      * to describe a particular format. However, for several reasons
330      * it is necessary to associate a list of types with each service
331      * provider. First, many common image file formats do not have
332      * standard MIME types, so a list of commonly used unofficial
333      * names will be required, such as <code>image/x-pbm</code> and
334      * <code>image/x-portable-bitmap</code>. Some file formats have
335      * official MIME types but may sometimes be referred to using
336      * their previous unofficial designations, such as
337      * <code>image/x-png</code> instead of the official
338      * <code>image/png</code>. Finally, a single service provider may
339      * be capable of parsing multiple distinct types from the MIME
340      * point of view, for example <code>image/x-xbitmap</code> and
341      * <code>image/x-xpixmap</code>.
342      *
343      * <p> Returning a particular MIME type does not guarantee that
344      * files claiming to be of that type can be processed; it merely
345      * indicates that it may be worthwhile attempting to decode or
346      * encode such files using this service provider.
347      *
348      * @return an array of <code>String</code>s or length at least 1
349      * containing MIME types associated with this reader or writer, or
350      * <code>null</code>.
351      */
352     public String [] getMIMETypes() {
353         return MIMETypes == null ? null : (String [])MIMETypes.clone();
354     }
355
356     /**
357      * Returns the fully-qualified class name of the
358      * <code>ImageReader</code> or <code>ImageWriter</code> plug-in
359      * associated with this service provider.
360      *
361      * @return the class name, as a non-<code>null</code>
362      * <code>String</code>.
363      */
364     public String getPluginClassName() {
365         return pluginClassName;
366     }
367
368     /**
369      * Returns <code>true</code> if the standard metadata format is
370      * among the document formats recognized by the
371      * <code>getAsTree</code> and <code>setFromTree</code> methods on
372      * the stream metadata objects produced or consumed by this
373      * plug-in.
374      *
375      * @return <code>true</code> if the standard format is supported
376      * for stream metadata.
377      */
378     public boolean isStandardStreamMetadataFormatSupported() {
379         return supportsStandardStreamMetadataFormat;
380     }
381
382     /**
383      * Returns the name of the "native" stream metadata format for
384      * this plug-in, which typically allows for lossless encoding and
385      * transmission of the stream metadata stored in the format handled by
386      * this plug-in. If no such format is supported,
387      * <code>null</code>will be returned.
388      *
389      * <p> The default implementation returns the
390      * <code>nativeStreamMetadataFormatName</code> instance variable,
391      * which is typically set by the constructor.
392      *
393      * @return the name of the native stream metadata format, or
394      * <code>null</code>.
395      *
396      */
397     public String getNativeStreamMetadataFormatName() {
398         return nativeStreamMetadataFormatName;
399     }
400
401     /**
402      * Returns an array of <code>String</code>s containing the names
403      * of additional document formats, other than the native and
404      * standard formats, recognized by the
405      * <code>getAsTree</code> and <code>setFromTree</code> methods on
406      * the stream metadata objects produced or consumed by this
407      * plug-in.
408      *
409      * <p> If the plug-in does not handle metadata, null should be
410      * returned.
411      *
412      * <p> The set of formats may differ according to the particular
413      * images being read or written; this method should indicate all
414      * the additional formats supported by the plug-in under any
415      * circumstances.
416      *
417      * <p> The default implementation returns a clone of the
418      * <code>extraStreamMetadataFormatNames</code> instance variable,
419      * which is typically set by the constructor.
420      *
421      * @return an array of <code>String</code>s, or null.
422      *
423      * @see IIOMetadata#getMetadataFormatNames
424      * @see #getExtraImageMetadataFormatNames
425      * @see #getNativeStreamMetadataFormatName
426      */
427     public String [] getExtraStreamMetadataFormatNames() {
428         return extraStreamMetadataFormatNames == null ?
429             null : (String [])extraStreamMetadataFormatNames.clone();
430     }
431
432     /**
433      * Returns <code>true</code> if the standard metadata format is
434      * among the document formats recognized by the
435      * <code>getAsTree</code> and <code>setFromTree</code> methods on
436      * the image metadata objects produced or consumed by this
437      * plug-in.
438      *
439      * @return <code>true</code> if the standard format is supported
440      * for image metadata.
441      */
442     public boolean isStandardImageMetadataFormatSupported() {
443         return supportsStandardImageMetadataFormat;
444     }
445
446     /**
447      * Returns the name of the "native" image metadata format for
448      * this plug-in, which typically allows for lossless encoding and
449      * transmission of the image metadata stored in the format handled by
450      * this plug-in. If no such format is supported,
451      * <code>null</code>will be returned.
452      *
453      * <p> The default implementation returns the
454      * <code>nativeImageMetadataFormatName</code> instance variable,
455      * which is typically set by the constructor.
456      *
457      * @return the name of the native image metadata format, or
458      * <code>null</code>.
459      *
460      * @see #getExtraImageMetadataFormatNames
461      */
462     public String getNativeImageMetadataFormatName() {
463         return nativeImageMetadataFormatName;
464     }
465
466     /**
467      * Returns an array of <code>String</code>s containing the names
468      * of additional document formats, other than the native and
469      * standard formats, recognized by the
470      * <code>getAsTree</code> and <code>setFromTree</code> methods on
471      * the image metadata objects produced or consumed by this
472      * plug-in.
473      *
474      * <p> If the plug-in does not handle image metadata, null should
475      * be returned.
476      *
477      * <p> The set of formats may differ according to the particular
478      * images being read or written; this method should indicate all
479      * the additional formats supported by the plug-in under any circumstances.
480      *
481      * <p> The default implementation returns a clone of the
482      * <code>extraImageMetadataFormatNames</code> instance variable,
483      * which is typically set by the constructor.
484      *
485      * @return an array of <code>String</code>s, or null.
486      *
487      * @see IIOMetadata#getMetadataFormatNames
488      * @see #getExtraStreamMetadataFormatNames
489      * @see #getNativeImageMetadataFormatName
490      */
491     public String [] getExtraImageMetadataFormatNames() {
492         return extraImageMetadataFormatNames == null ?
493             null : (String [])extraImageMetadataFormatNames.clone();
494     }
495
496     /**
497      * Returns an <code>IIOMetadataFormat</code> object describing the
498      * given stream metadata format, or <code>null</code> if no
499      * description is available. The supplied name must be the native
500      * stream metadata format name, the standard metadata format name,
501      * or one of those returned by
502      * <code>getExtraStreamMetadataFormatNames</code>.
503      *
504      * @param formatName the desired stream metadata format.
505      *
506      * @return an <code>IIOMetadataFormat</code> object.
507      *
508      * @exception IllegalArgumentException if <code>formatName</code>
509      * is <code>null</code> or is not a supported name.
510      */
511     public IIOMetadataFormat getStreamMetadataFormat(String formatName) {
512         return getMetadataFormat(formatName,
513                                  supportsStandardStreamMetadataFormat,
514                                  nativeStreamMetadataFormatName,
515                                  nativeStreamMetadataFormatClassName,
516                                  extraStreamMetadataFormatNames,
517                                  extraStreamMetadataFormatClassNames);
518     }
519
520     /**
521      * Returns an <code>IIOMetadataFormat</code> object describing the
522      * given image metadata format, or <code>null</code> if no
523      * description is available. The supplied name must be the native
524      * iamge metadata format name, the standard metadata format name,
525      * or one of those returned by
526      * <code>getExtraImageMetadataFormatNames</code>.
527      *
528      * @param formatName the desired image metadata format.
529      *
530      * @return an <code>IIOMetadataFormat</code> object.
531      *
532      * @exception IllegalArgumentException if <code>formatName</code>
533      * is <code>null</code> or is not a supported name.
534      */
535     public IIOMetadataFormat getImageMetadataFormat(String formatName) {
536         return getMetadataFormat(formatName,
537                                  supportsStandardImageMetadataFormat,
538                                  nativeImageMetadataFormatName,
539                                  nativeImageMetadataFormatClassName,
540                                  extraImageMetadataFormatNames,
541                                  extraImageMetadataFormatClassNames);
542     }
543
544     private IIOMetadataFormat getMetadataFormat(String formatName,
545                                                 boolean supportsStandard,
546                                                 String nativeName,
547                                                 String nativeClassName,
548                                                 String [] extraNames,
549                                                 String [] extraClassNames) {
550         if (formatName == null) {
551             throw new IllegalArgumentException ("formatName == null!");
552         }
553         if (supportsStandard && formatName.equals
554                 (IIOMetadataFormatImpl.standardMetadataFormatName)) {
555
556             return IIOMetadataFormatImpl.getStandardFormatInstance();
557         }
558         String formatClassName = null;
559         if (formatName.equals(nativeName)) {
560             formatClassName = nativeClassName;
561         } else if (extraNames != null) {
562             for (int i = 0; i < extraNames.length; i++) {
563                 if (formatName.equals(extraNames[i])) {
564                     formatClassName = extraClassNames[i];
565                     break; // out of for
566 }
567             }
568         }
569         if (formatClassName == null) {
570             throw new IllegalArgumentException ("Unsupported format name");
571         }
572         try {
573             Class cls = Class.forName(formatClassName, true,
574                                       ClassLoader.getSystemClassLoader());
575             Method meth = cls.getMethod("getInstance", null);
576             return (IIOMetadataFormat ) meth.invoke(null, null);
577         } catch (Exception e) {
578             RuntimeException ex =
579                 new IllegalStateException ("Can't obtain format");
580             ex.initCause(e);
581             throw ex;
582         }
583     }
584 }
585

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags