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>“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}