gomp-20050608-branch/libjava/classpath/javax/imageio/spi/ImageReaderWriterSpi.java

   1 /* ImageReaderWriterSpi.java -- Superclass for image reader and writer spis.
   2    Copyright (C) 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.imageio.spi;
  40
  41 import javax.imageio.metadata.IIOMetadataFormat;
  42 import javax.imageio.metadata.IIOMetadataFormatImpl;
  43
  44 /**
  45  * An abstract superclass that contains the common parts of {@link
  46  * javax.imageio.spi.ImageReaderSpi} and {@link
  47  * javax.imageio.spi.ImageWriterSpi}.
  48  *
  49  * @since 1.4
  50  *
  51  * @author Sascha Brawer (brawer@dandelis.ch)
  52  */
  53 public abstract class ImageReaderWriterSpi
  54   extends IIOServiceProvider
  55 {
  56   /**
  57    * The human-readable, localized names of the supported image
  58    * formats. This value should be non-<code>null</code> after
  59    * construction.
  60    *
  61    * @see #getFormatNames()
  62    */
  63   protected String[] names;
  64
  65
  66   /**
  67    * The file suffixes of the supported image formats. This value
  68    * should be non-<code>null</code> after construction.
  69    *
  70    * @see #getFileSuffixes()
  71    */
  72   protected String[] suffixes;
  73
  74
  75   /**
  76    * The MIME types of the supported image formats.  This value
  77    * should be non-<code>null</code> after construction.
  78    *
  79    * @see #getMIMETypes()
  80    */
  81   protected String[] MIMETypes;
  82
  83
  84   /**
  85    * The fully qualified name of the class that implements the {@link
  86    * javax.imageio.ImageReader} or {@link javax.imageio.ImageWriter}
  87    * interface.  This value should be non-<code>null</code> after
  88    * construction.
  89    *
  90    * @see #getPluginClassName()
  91    */
  92   protected String pluginClassName;
  93
  94
  95   /**
  96    * Indicates whether the per-stream {@linkplain
  97    * javax.imageio.metadata.IIOMetadata metadata objects} associated
  98    * with this plug-in support format
  99    * <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 }