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>“javax_imageio_1.0”</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>“javax_imageio_1.0”</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>[“Tagged Image File
184 * Format”, “Portable Network
185 * Graphics”]</code>.
186 *
187 * @param suffixes the file suffixes of the supported image formats,
188 * for example <code>[“tiff”, “tif”,
189 * “png”]</code>.
190 *
191 * @param MIMETypes the MIME types of the supported image formats,
192 * for example <code>[“image/tiff”,
193 * “image/png”]</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>“javax_imageio_1.0”</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>“javax_imageio_1.0”</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>[“Tagged Image File Format”,
301 * “Portable Network Graphics”]</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>[“tiff”, “tif”,
312 * “png”]</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>[“image/tiff”,
323 * “image/png”]</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>“javax_imageio_1.0”</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>“javax_imageio_1.0”</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 }