001/* ImageReaderWriterSpi.java -- Superclass for image reader and writer spis.
002   Copyright (C) 2004, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.imageio.spi;
040
041import javax.imageio.metadata.IIOMetadataFormat;
042import 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 */
053public 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}