001    /* ImageReaderWriterSpi.java -- Superclass for image reader and writer spis.
002       Copyright (C) 2004, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.imageio.spi;
040    
041    import javax.imageio.metadata.IIOMetadataFormat;
042    import javax.imageio.metadata.IIOMetadataFormatImpl;
043    
044    /**
045     * An abstract superclass that contains the common parts of {@link
046     * javax.imageio.spi.ImageReaderSpi} and {@link
047     * javax.imageio.spi.ImageWriterSpi}.
048     *
049     * @since 1.4
050     *
051     * @author Sascha Brawer (brawer@dandelis.ch)
052     */
053    public abstract class ImageReaderWriterSpi
054      extends IIOServiceProvider
055    {
056      /**
057       * The human-readable, localized names of the supported image
058       * formats. This value should be non-<code>null</code> after
059       * construction.
060       *
061       * @see #getFormatNames()
062       */
063      protected String[] names;
064    
065    
066      /**
067       * The file suffixes of the supported image formats. This value
068       * should be non-<code>null</code> after construction.
069       *
070       * @see #getFileSuffixes()
071       */
072      protected String[] suffixes;
073    
074    
075      /**
076       * The MIME types of the supported image formats.  This value
077       * should be non-<code>null</code> after construction.
078       *
079       * @see #getMIMETypes()
080       */
081      protected String[] MIMETypes;
082    
083    
084      /**
085       * The fully qualified name of the class that implements the {@link
086       * javax.imageio.ImageReader} or {@link javax.imageio.ImageWriter}
087       * interface.  This value should be non-<code>null</code> after
088       * construction.
089       *
090       * @see #getPluginClassName()
091       */
092      protected String pluginClassName;
093    
094    
095      /**
096       * Indicates whether the per-stream {@linkplain
097       * javax.imageio.metadata.IIOMetadata metadata objects} associated
098       * with this plug-in support format
099       * <code>&#x201c;javax_imageio_1.0&#x201d;</code> in their
100       * <code>getAsTree</code> and <code>setAsTree</code> methods.
101       *
102       * @see #isStandardStreamMetadataFormatSupported()
103       */
104      protected boolean supportsStandardStreamMetadataFormat;
105    
106    
107      /**
108       * The name of the format that allows encoding all stream metadata
109       * without loss, or <code>null</code> if this plug-in does not
110       * provide a format that preserves all stream metadata.
111       */
112      protected String nativeStreamMetadataFormatName;
113    
114      protected String nativeStreamMetadataFormatClassName;
115    
116    
117      /**
118       * The names of additional formats for encoding stream metadata,
119       * other than the {@linkplain
120       * #isStandardStreamMetadataFormatSupported() standard} and the
121       * {@linkplain #getNativeStreamMetadataFormatName() native} formats,
122       * or <code>null</code> if this plug-in does not provide any extra
123       * formats.
124       */
125      protected String[] extraStreamMetadataFormatNames;
126    
127    
128      protected String[] extraStreamMetadataFormatClassNames;
129    
130    
131      /**
132       * Indicates whether the per-image {@linkplain
133       * javax.imageio.metadata.IIOMetadata metadata objects} associated
134       * with this plug-in support format
135       * <code>&#x201c;javax_imageio_1.0&#x201d;</code> in their
136       * <code>getAsTree</code> and <code>setAsTree</code> methods.
137       *
138       * @see #isStandardImageMetadataFormatSupported()
139       */
140      protected boolean supportsStandardImageMetadataFormat;
141    
142    
143      /**
144       * The name of the format that allows encoding all image metadata
145       * without loss, or <code>null</code> if this plug-in does not
146       * provide a format that preserves all image metadata.
147       */
148      protected String nativeImageMetadataFormatName;
149    
150      protected String nativeImageMetadataFormatClassName;
151    
152    
153      /**
154       * The names of additional formats for encoding image metadata,
155       * other than the {@linkplain
156       * #isStandardImageMetadataFormatSupported() standard} and the
157       * {@linkplain #getNativeImageMetadataFormatName() native} formats,
158       * or <code>null</code> if this plug-in does not provide any extra
159       * formats.
160       */
161      protected String[] extraImageMetadataFormatNames;
162    
163    
164      protected String[] extraImageMetadataFormatClassNames;
165    
166    
167      /**
168       * Constructs an <code>ImageReaderWriteSpi</code> instance, without
169       * specifying a number of parameters. Constructors of concrete
170       * subclasses must ensure that they set all inherited fields to
171       * meaningful values.
172       */
173      public ImageReaderWriterSpi()
174      {
175      }
176    
177    
178      /**
179       * Constructs an <code>ImageReaderWriteSpi</code> instance,
180       * specifying a number of parameters.
181       *
182       * @param names the human-readable, localized names of the supported
183       * image formats, for example <code>[&#x201c;Tagged Image File
184       * Format&#x201d;, &#x201c;Portable Network
185       * Graphics&#x201d;]</code>.
186       *
187       * @param suffixes the file suffixes of the supported image formats,
188       * for example <code>[&#x201c;tiff&#x201d;, &#x201c;tif&#x201d;,
189       * &#x201c;png&#x201d;]</code>.
190       *
191       * @param MIMETypes the MIME types of the supported image formats,
192       * for example <code>[&#x201c;image/tiff&#x201d;,
193       * &#x201c;image/png&#x201d;]</code>.
194       *
195       * @param pluginClassName the fully qualified name of the class that
196       * implements the {@link javax.imageio.ImageReader} or {@link
197       * javax.imageio.ImageWriter} interface.
198       *
199       * @param supportsStandardStreamMetadataFormat whether the
200       * per-stream {@linkplain javax.imageio.metadata.IIOMetadata
201       * metadata objects} associated with this plug-in support format
202       * <code>&#x201c;javax_imageio_1.0&#x201d;</code> in their
203       * <code>getAsTree</code> and <code>setAsTree</code> methods.
204       *
205       * @param nativeStreamMetadataFormatName the name of the format that
206       * allows encoding all stream metadata without loss, or
207       * <code>null</code> if this plug-in does not provide a format that
208       * preserves all stream metadata.
209       *
210       * @param extraStreamMetadataFormatNames the names of additional
211       * formats for encoding stream metadata, other than the {@linkplain
212       * #isStandardStreamMetadataFormatSupported() standard} and the
213       * {@linkplain #getNativeStreamMetadataFormatName() native} formats,
214       * or <code>null</code> if this plug-in does not provide any extra
215       * formats.
216       *
217       * @param supportsStandardImageMetadataFormat whether the per-image
218       * {@linkplain javax.imageio.metadata.IIOMetadata metadata objects}
219       * associated with this plug-in support format
220       * <code>&#x201c;javax_imageio_1.0&#x201d;</code> in their
221       * <code>getAsTree</code> and <code>setAsTree</code> methods.
222       *
223       * @param nativeImageMetadataFormatName the name of the format that
224       * allows encoding all image metadata without loss, or
225       * <code>null</code> if this plug-in does not provide a format that
226       * preserves all image metadata.
227       *
228       * @param extraImageMetadataFormatNames the names of additional
229       * formats for encoding image metadata, other than the {@linkplain
230       * #isStandardImageMetadataFormatSupported() standard} and the
231       * {@linkplain #getNativeImageMetadataFormatName() native} formats,
232       * or <code>null</code> if this plug-in does not provide any extra
233       * formats.
234       *
235       * @throws IllegalArgumentException if <code>vendorName</code>
236       * or <code>version</code> is <code>null</code>.
237       */
238      public ImageReaderWriterSpi(String vendorName, String version,
239                                  String[] names, String[] suffixes,
240                                  String[] MIMETypes, String pluginClassName,
241                                  boolean supportsStandardStreamMetadataFormat,
242                                  String nativeStreamMetadataFormatName,
243                                  String nativeStreamMetadataFormatClassName,
244                                  String[] extraStreamMetadataFormatNames,
245                                  String[] extraStreamMetadataFormatClassNames,
246                                  boolean supportsStandardImageMetadataFormat,
247                                  String nativeImageMetadataFormatName,
248                                  String nativeImageMetadataFormatClassName,
249                                  String[] extraImageMetadataFormatNames,
250                                  String[] extraImageMetadataFormatClassNames)
251      {
252        /* The inherited constructor will throw IllegalArgumentException
253         * if one of its arguments is null.
254         */
255        super(vendorName, version);
256    
257        if (names == null || names.length == 0 || pluginClassName == null)
258          throw new IllegalArgumentException();
259    
260        this.names = names;
261        this.suffixes = suffixes;
262        this.MIMETypes = MIMETypes;
263        this.pluginClassName = pluginClassName;
264    
265        this.supportsStandardStreamMetadataFormat
266          = supportsStandardStreamMetadataFormat;
267    
268        this.nativeStreamMetadataFormatName
269          = nativeStreamMetadataFormatName;
270    
271        this.nativeStreamMetadataFormatClassName
272          = nativeStreamMetadataFormatClassName;
273    
274        this.extraStreamMetadataFormatNames
275          = extraStreamMetadataFormatNames;
276    
277        this.extraStreamMetadataFormatClassNames
278          = extraStreamMetadataFormatClassNames;
279    
280        this.supportsStandardImageMetadataFormat
281          = supportsStandardImageMetadataFormat;
282    
283        this.nativeImageMetadataFormatName
284          = nativeImageMetadataFormatName;
285    
286        this.nativeImageMetadataFormatClassName
287          = nativeImageMetadataFormatClassName;
288    
289        this.extraImageMetadataFormatNames
290          = extraImageMetadataFormatNames;
291    
292        this.extraImageMetadataFormatClassNames
293          = extraImageMetadataFormatClassNames;
294      }
295    
296    
297      /**
298       * Returns the human-readable, localized names of the supported
299       * image formats. For example, a plug-in might return an array with
300       * the elements <code>[&#x201c;Tagged Image File Format&#x201d;,
301       * &#x201c;Portable Network Graphics&#x201d;]</code>.
302       */
303      public String[] getFormatNames()
304      {
305        return (String[]) names.clone();
306      }
307    
308    
309      /**
310       * Returns the file suffixes of the supported image formats, for
311       * example <code>[&#x201c;tiff&#x201d;, &#x201c;tif&#x201d;,
312       * &#x201c;png&#x201d;]</code>.
313       */
314      public String[] getFileSuffixes()
315      {
316        return suffixes;
317      }
318    
319    
320      /**
321       * Returns the MIME types of the supported image formats, for
322       * example <code>[&#x201c;image/tiff&#x201d;,
323       * &#x201c;image/png&#x201d;]</code>.
324       *
325       * @return an array of MIME type strings, or <code>null</code> if
326       * none of the supported formats has an associated MIME type.
327       */
328      public String[] getMIMETypes()
329      {
330        return MIMETypes;
331      }
332    
333    
334      /**
335       * Returns the fully qualified name of the class that implements the
336       * {@link javax.imageio.ImageReader} or {@link
337       * javax.imageio.ImageWriter} interface.
338       */
339      public String getPluginClassName()
340      {
341        return pluginClassName;
342      }
343    
344    
345      /**
346       * Returns whether the per-stream {@linkplain
347       * javax.imageio.metadata.IIOMetadata metadata objects} associated
348       * with this plug-in support format
349       * <code>&#x201c;javax_imageio_1.0&#x201d;</code> in their
350       * <code>getAsTree</code> and <code>setAsTree</code> methods.
351       */
352      public boolean isStandardStreamMetadataFormatSupported()
353      {
354        return supportsStandardStreamMetadataFormat;
355      }
356    
357    
358      /**
359       * Returns the name of the format that allows encoding all stream
360       * metadata without loss, or <code>null</code> if this plug-in does
361       * not provide a format that preserves all stream metadata.
362       *
363       * @see #getNativeImageMetadataFormatName()
364       */
365      public String getNativeStreamMetadataFormatName()
366      {
367        return nativeStreamMetadataFormatName;
368      }
369    
370    
371      /**
372       * Returns the names of additional formats for encoding stream
373       * metadata, other than the {@linkplain
374       * #isStandardStreamMetadataFormatSupported() standard} and the
375       * {@linkplain #getNativeStreamMetadataFormatName() native} formats,
376       * or <code>null</code> if this plug-in does not provide any extra
377       * formats.
378       *
379       * @see #getExtraImageMetadataFormatNames()
380       */
381      public String[] getExtraStreamMetadataFormatNames()
382      {
383        return extraStreamMetadataFormatNames;
384      }
385    
386    
387      /**
388       * Returns whether the per-image {@linkplain
389       * javax.imageio.metadata.IIOMetadata metadata objects} associated
390       * with this plug-in support format
391       * <code>&#x201c;javax_imageio_1.0&#x201d;</code> in their
392       * <code>getAsTree</code> and <code>setAsTree</code> methods.
393       */
394      public boolean isStandardImageMetadataFormatSupported()
395      {
396        return supportsStandardImageMetadataFormat;
397      }
398    
399    
400      /**
401       * Returns the name of the format that allows encoding all image
402       * metadata without loss, or <code>null</code> if this plug-in does
403       * not provide a format that preserves all image metadata.
404       *
405       * @see #getNativeStreamMetadataFormatName()
406       */
407      public String getNativeImageMetadataFormatName()
408      {
409        return nativeImageMetadataFormatName;
410      }
411    
412    
413      /**
414       * Returns the names of additional formats for encoding image
415       * metadata, other than the {@linkplain
416       * #isStandardImageMetadataFormatSupported() standard} and the
417       * {@linkplain #getNativeImageMetadataFormatName() native} formats,
418       * or <code>null</code> if this plug-in does not provide any extra
419       * formats.
420       *
421       * @see #getExtraStreamMetadataFormatNames()
422       */
423      public String[] getExtraImageMetadataFormatNames()
424      {
425        return extraImageMetadataFormatNames;
426      }
427    
428      /**
429       * Returns an IIOMetadataFormat object that represents the requested
430       * stream metadata format or null if the given format is supported
431       * but no IIOMetadataFormat can be created for it.
432       *
433       * @param formatName the requested stream metadata format name
434       *
435       * @return an IIOMetadataFormat object or null
436       *
437       * @throws IllegalArgumentException if formatName is null or is not
438       * one of the standard metadata format or this provider's native or
439       * extra stream metadata formats
440       */
441      public IIOMetadataFormat getStreamMetadataFormat (String formatName)
442      {
443        if (formatName == null)
444          throw new IllegalArgumentException ("null stream metadata format name");
445    
446        if (!formatName.equals (getNativeStreamMetadataFormatName())
447            && !formatName.equals (IIOMetadataFormatImpl.standardMetadataFormatName))
448          {
449            String[] extraNames = getExtraStreamMetadataFormatNames ();
450            boolean foundName = false;
451            for (int i = 0; i < extraNames.length; i++)
452              {
453                if (formatName.equals(extraNames[i]))
454                  {
455                    foundName = true;
456                    break;
457                  }
458              }
459            if (!foundName)
460              throw new IllegalArgumentException ("unsupported stream metadata format name");
461          }
462    
463        if (formatName.equals (IIOMetadataFormatImpl.standardMetadataFormatName))
464          return IIOMetadataFormatImpl.getStandardFormatInstance ();
465        else
466          // Default implementation returns null.
467          return null;
468      }
469    
470      /**
471       * Returns an IIOMetadataFormat object that represents the requested
472       * image metadata format or null if the given format is supported
473       * but no IIOMetadataFormat can be created for it.
474       *
475       * @param formatName the requested image metadata format name
476       *
477       * @return an IIOMetadataFormat object or null
478       *
479       * @throws IllegalArgumentException if formatName is null or is not
480       * one of the standard metadata format or this provider's native or
481       * extra image metadata formats
482       */
483      public IIOMetadataFormat getImageMetadataFormat (String formatName)
484      {
485        if (formatName == null)
486          throw new IllegalArgumentException ("null image metadata format name");
487    
488        if (!formatName.equals (getNativeImageMetadataFormatName())
489            && !formatName.equals (IIOMetadataFormatImpl.standardMetadataFormatName))
490          {
491            String[] extraNames = getExtraImageMetadataFormatNames ();
492            boolean foundName = false;
493            for (int i = 0; i < extraNames.length; i++)
494              {
495                if (formatName.equals(extraNames[i]))
496                  {
497                    foundName = true;
498                    break;
499                  }
500              }
501            if (!foundName)
502              throw new IllegalArgumentException ("unsupported image metadata format name");
503          }
504    
505        if (formatName.equals (IIOMetadataFormatImpl.standardMetadataFormatName))
506          return IIOMetadataFormatImpl.getStandardFormatInstance ();
507        else
508          // Default implementation returns null.
509          return null;
510      }
511    }