001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.imaging; 018 019import java.awt.Dimension; 020import java.awt.image.BufferedImage; 021import java.io.File; 022import java.io.IOException; 023import java.io.OutputStream; 024import java.io.PrintWriter; 025import java.io.StringWriter; 026import java.nio.ByteOrder; 027import java.util.ArrayList; 028import java.util.Arrays; 029import java.util.List; 030import java.util.Locale; 031import java.util.logging.Level; 032import java.util.logging.Logger; 033 034import org.apache.commons.imaging.bytesource.ByteSource; 035import org.apache.commons.imaging.common.BinaryFileParser; 036import org.apache.commons.imaging.common.BufferedImageFactory; 037import org.apache.commons.imaging.common.ImageMetadata; 038import org.apache.commons.imaging.common.SimpleBufferedImageFactory; 039import org.apache.commons.imaging.formats.bmp.BmpImageParser; 040import org.apache.commons.imaging.formats.dcx.DcxImageParser; 041import org.apache.commons.imaging.formats.gif.GifImageParser; 042import org.apache.commons.imaging.formats.icns.IcnsImageParser; 043import org.apache.commons.imaging.formats.ico.IcoImageParser; 044import org.apache.commons.imaging.formats.jpeg.JpegImageParser; 045import org.apache.commons.imaging.formats.pcx.PcxImageParser; 046import org.apache.commons.imaging.formats.png.PngImageParser; 047import org.apache.commons.imaging.formats.pnm.PnmImageParser; 048import org.apache.commons.imaging.formats.psd.PsdImageParser; 049import org.apache.commons.imaging.formats.rgbe.RgbeImageParser; 050import org.apache.commons.imaging.formats.tiff.TiffImageParser; 051import org.apache.commons.imaging.formats.wbmp.WbmpImageParser; 052import org.apache.commons.imaging.formats.webp.WebPImageParser; 053import org.apache.commons.imaging.formats.xbm.XbmImageParser; 054import org.apache.commons.imaging.formats.xpm.XpmImageParser; 055import org.apache.commons.lang3.ArrayUtils; 056 057/** 058 * Provides the abstract base class for all image reading and writing utilities. ImageParser implementations are expected to extend this class providing logic 059 * for identifying and processing data in their own specific format. Specific implementations are found under the com.apache.commons.imaging.formats package. 060 * 061 * <h2>Application Notes</h2> 062 * 063 * <h3>Format support</h3> 064 * 065 * For the most recent information on format support for the Apache Commons Imaging package, refer to 066 * <a href="https://commons.apache.org/imaging/formatsupport.html">Format Support</a> at the main project development web site. 067 * 068 * <h3>On the accuracy of this Javadoc</h3> 069 * 070 * The original authors of this class did not supply documentation. The Javadoc for this class is based on inspection of the source code. In some cases, the 071 * purpose and usage for particular methods was deduced from the source and may not perfectly reflect the intentions of the original. Therefore, you should not 072 * assume that the documentation is perfect, especially in the more obscure and specialized areas of implementation. 073 * 074 * <h3>The "params" argument</h3> 075 * 076 * <p> 077 * Many of the methods specified by this class accept an argument of type {@code T} defining the parameters to be used when processing an image. For example, 078 * some of the output formats permit of different kinds of image compression or color models. Some of the reading methods permit the calling application to 079 * require strict format compliance. 080 * </p> 081 * 082 * @param <T> type of parameters used by this image parser 083 */ 084public abstract class AbstractImageParser<T extends ImagingParameters<T>> extends BinaryFileParser { 085 086 private static final Logger LOGGER = Logger.getLogger(AbstractImageParser.class.getName()); 087 088 /** 089 * Gets an array of new instances of all image parsers. 090 * 091 * @return A valid array of image parsers 092 */ 093 public static List<AbstractImageParser<?>> getAllImageParsers() { 094 return Arrays.asList(new BmpImageParser(), new DcxImageParser(), new GifImageParser(), new IcnsImageParser(), new IcoImageParser(), 095 new JpegImageParser(), new PcxImageParser(), new PngImageParser(), new PnmImageParser(), new PsdImageParser(), new RgbeImageParser(), 096 new TiffImageParser(), new WebPImageParser(), new WbmpImageParser(), new XbmImageParser(), new XpmImageParser() 097 // new JBig2ImageParser(), 098 // new TgaImageParser(), 099 ); 100 } 101 102 /** 103 * Constructs a new instance with the default, big-endian, byte order. 104 */ 105 public AbstractImageParser() { 106 // empty 107 } 108 109 /** 110 * Constructs a new instance. 111 * 112 * @param byteOrder the byte order. 113 */ 114 public AbstractImageParser(final ByteOrder byteOrder) { 115 super(byteOrder); 116 } 117 118 /** 119 * Tests whether the ImageParser implementation can accept the specified file based on its extension. 120 * 121 * @param file An valid file reference. 122 * @return If the parser can accept the format, true; otherwise, false. 123 */ 124 public boolean canAcceptExtension(final File file) { 125 return canAcceptExtension(file.getName()); 126 } 127 128 /** 129 * Tests whether the ImageParser implementation can accept the specified file name based on its extension. 130 * 131 * @param fileName A valid string giving a file name or file path. 132 * @return If the parser can accept the format, true; otherwise, false. 133 */ 134 public final boolean canAcceptExtension(final String fileName) { 135 final String[] extensions = getAcceptedExtensions(); 136 if (extensions == null) { 137 return true; 138 } 139 final int index = fileName.lastIndexOf('.'); 140 if (index >= 0 && ArrayUtils.contains(extensions, fileName.substring(index + 1).toLowerCase(Locale.ROOT))) { 141 return true; 142 } 143 return false; 144 } 145 146 /** 147 * Tests whether the ImageParser implementation can accept the specified format. 148 * 149 * @param imageFormat An instance of ImageFormat. 150 * @return If the parser can accept the format, true; otherwise, false. 151 */ 152 public boolean canAcceptType(final ImageFormat imageFormat) { 153 return ArrayUtils.contains(getAcceptedTypes(), imageFormat); 154 } 155 156 /** 157 * Writes the ImageInfo and format-specific information for the image content of the specified byte array to a string. 158 * 159 * @param bytes A valid array of bytes. 160 * @return A valid string. 161 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 162 * @throws IOException In the event of unsuccessful read or access operation. 163 */ 164 public final String dumpImageFile(final byte[] bytes) throws ImagingException, IOException { 165 return dumpImageFile(ByteSource.array(bytes)); 166 } 167 168 /** 169 * Writes the ImageInfo and format-specific information for the image content of the specified byte source to a string. 170 * 171 * @param byteSource A valid byte source. 172 * @return A valid string. 173 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 174 * @throws IOException In the event of unsuccessful read or access operation. 175 */ 176 public final String dumpImageFile(final ByteSource byteSource) throws ImagingException, IOException { 177 final StringWriter sw = new StringWriter(); 178 final PrintWriter pw = new PrintWriter(sw); 179 180 dumpImageFile(pw, byteSource); 181 182 pw.flush(); 183 184 return sw.toString(); 185 } 186 187 /** 188 * Writes the ImageInfo and format-specific information for the image content of the specified file to a string. 189 * 190 * @param file A valid file reference. 191 * @return A valid string. 192 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 193 * @throws IOException In the event of unsuccessful read or access operation. 194 */ 195 public final String dumpImageFile(final File file) throws ImagingException, IOException { 196 if (!canAcceptExtension(file)) { 197 return null; 198 } 199 200 if (LOGGER.isLoggable(Level.FINEST)) { 201 LOGGER.finest(getName() + ": " + file.getName()); 202 } 203 204 return dumpImageFile(ByteSource.file(file)); 205 } 206 207 /** 208 * Writes the ImageInfo and format-specific information for the image content of the specified byte source to a PrintWriter 209 * 210 * @param pw print writer used for writing the ImageInfo 211 * @param byteSource A valid byte source. 212 * @return A valid PrintWriter. 213 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 214 * @throws IOException In the event of unsuccessful read or access operation. 215 */ 216 public boolean dumpImageFile(final PrintWriter pw, final ByteSource byteSource) throws ImagingException, IOException { 217 return false; 218 } 219 220 /** 221 * Gets an array of all accepted extensions 222 * 223 * @return A valid array of one or more elements. 224 */ 225 protected abstract String[] getAcceptedExtensions(); 226 227 /** 228 * Gets an array of ImageFormat objects describing all accepted types 229 * 230 * @return A valid array of one or more elements. 231 */ 232 protected abstract ImageFormat[] getAcceptedTypes(); 233 234 /** 235 * Gets all images specified by the byte array (some formats may include multiple images within a single data source). 236 * 237 * @param bytes A valid byte array 238 * @return A valid (potentially empty) list of BufferedImage objects. 239 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 240 * @throws IOException In the event of unsuccessful read or access operation. 241 */ 242 public final List<BufferedImage> getAllBufferedImages(final byte[] bytes) throws ImagingException, IOException { 243 return getAllBufferedImages(ByteSource.array(bytes)); 244 } 245 246 /** 247 * Gets all images specified by the byte source (some formats may include multiple images within a single data source). 248 * 249 * @param byteSource A valid instance of ByteSource. 250 * @return A valid (potentially empty) list of BufferedImage objects. 251 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 252 * @throws IOException In the event of unsuccessful read or access operation. 253 */ 254 public List<BufferedImage> getAllBufferedImages(final ByteSource byteSource) throws ImagingException, IOException { 255 final BufferedImage bi = getBufferedImage(byteSource, null); 256 257 final List<BufferedImage> result = new ArrayList<>(); 258 259 // FIXME this doesn't look like we're actually getting all images contained in the given ByteSource... 260 result.add(bi); 261 262 return result; 263 } 264 265 /** 266 * Gets all images specified by indicated file (some formats may include multiple images within a single data source). 267 * 268 * @param file A valid reference to a file. 269 * @return A valid (potentially empty) list of BufferedImage objects. 270 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 271 * @throws IOException In the event of unsuccessful read or access operation. 272 */ 273 public final List<BufferedImage> getAllBufferedImages(final File file) throws ImagingException, IOException { 274 if (!canAcceptExtension(file)) { 275 return null; 276 } 277 278 return getAllBufferedImages(ByteSource.file(file)); 279 } 280 281 /** 282 * Gets a buffered image specified by the byte array (for sources that specify multiple images, choice of which image is returned is implementation 283 * dependent). 284 * 285 * @param bytes A valid byte array 286 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 287 * implementations). 288 * @return A valid instance of BufferedImage. 289 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 290 * @throws IOException In the event of unsuccessful read or access operation. 291 */ 292 public final BufferedImage getBufferedImage(final byte[] bytes, final T params) throws ImagingException, IOException { 293 return getBufferedImage(ByteSource.array(bytes), params); 294 } 295 296 /** 297 * Gets a buffered image specified by the byte source (for sources that specify multiple images, choice of which image is returned is implementation 298 * dependent). 299 * 300 * @param byteSource A valid instance of ByteSource 301 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 302 * implementations). 303 * @return A valid instance of BufferedImage. 304 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 305 * @throws IOException In the event of unsuccessful read or access operation. 306 */ 307 public abstract BufferedImage getBufferedImage(ByteSource byteSource, T params) throws ImagingException, IOException; 308 309 /** 310 * Gets a buffered image specified by the indicated file (for sources that specify multiple images, choice of which image is returned is implementation 311 * dependent). 312 * 313 * @param file A valid file reference. 314 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 315 * implementations). 316 * @return A valid instance of BufferedImage. 317 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 318 * @throws IOException In the event of unsuccessful read or access operation. 319 */ 320 public final BufferedImage getBufferedImage(final File file, final T params) throws ImagingException, IOException { 321 if (!canAcceptExtension(file)) { 322 return null; 323 } 324 325 return getBufferedImage(ByteSource.file(file), params); 326 } 327 328 /** 329 * Gets an instance of IBufferedImageFactory based on the presence of a specification for ImagingConstants..BUFFERED_IMAGE_FACTORY within the supplied 330 * params. 331 * 332 * @param params optional parameters. 333 * @return A valid instance of an implementation of a IBufferedImageFactory. 334 */ 335 protected BufferedImageFactory getBufferedImageFactory(final T params) { 336 if (params == null) { 337 return new SimpleBufferedImageFactory(); 338 } 339 340 final BufferedImageFactory result = params.getBufferedImageFactory(); 341 342 if (null != result) { 343 return result; 344 } 345 346 return new SimpleBufferedImageFactory(); 347 } 348 349 /** 350 * Gets the default extension for the format specified by an implementation of ImageParser. Some parsers can support more than one extension (i.e. .JPEG, 351 * .JPG; .TIF, .TIFF, etc.). 352 * 353 * @return A valid string. 354 */ 355 public abstract String getDefaultExtension(); 356 357 /** 358 * Gets a default parameters instance for this parser. 359 * 360 * @return default parameters instance 361 */ 362 public abstract T getDefaultParameters(); 363 364 /** 365 * Determines the format compliance of the content of the supplied byte array based on rules provided by a specific implementation. 366 * 367 * @param bytes A valid byte array. 368 * @return A valid FormatCompliance object. 369 * @throws ImagingException may be thrown by sub-classes 370 * @throws IOException may be thrown by sub-classes 371 */ 372 public final FormatCompliance getFormatCompliance(final byte[] bytes) throws ImagingException, IOException { 373 return getFormatCompliance(ByteSource.array(bytes)); 374 } 375 376 /** 377 * Determines the format compliance of the content of the supplied byte source based on rules provided by a specific implementation. 378 * 379 * @param byteSource A valid instance of ByteSource 380 * @return true if the content is format-compliant; otherwise, false 381 * @throws ImagingException may be thrown by sub-classes 382 * @throws IOException may be thrown by sub-classes 383 */ 384 public FormatCompliance getFormatCompliance(final ByteSource byteSource) throws ImagingException, IOException { 385 return null; 386 } 387 388 /** 389 * Determines the format compliance of the specified file based on rules provided by a specific implementation. 390 * 391 * @param file A valid reference to a file. 392 * @return A valid format compliance object. 393 * @throws ImagingException may be thrown by sub-classes 394 * @throws IOException may be thrown by sub-classes 395 */ 396 public final FormatCompliance getFormatCompliance(final File file) throws ImagingException, IOException { 397 if (!canAcceptExtension(file)) { 398 return null; 399 } 400 401 return getFormatCompliance(ByteSource.file(file)); 402 } 403 404 /** 405 * Gets an array of bytes describing the International Color Consortium (ICC) specification for the color space of the image contained in the input byte 406 * array. Not all formats support ICC profiles. 407 * 408 * @param bytes A valid array of bytes. 409 * @return If available, a valid array of bytes; otherwise, a null 410 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 411 * @throws IOException In the event of unsuccessful read or access operation. 412 */ 413 public final byte[] getIccProfileBytes(final byte[] bytes) throws ImagingException, IOException { 414 return getIccProfileBytes(bytes, null); 415 } 416 417 /** 418 * Gets an array of bytes describing the International Color Consortium (ICC) specification for the color space of the image contained in the input byte 419 * array. Not all formats support ICC profiles. 420 * 421 * @param bytes A valid array of bytes. 422 * @param params Optional instructions for special-handling or interpretation of the input data. 423 * @return If available, a valid array of bytes; otherwise, a null 424 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 425 * @throws IOException In the event of unsuccessful read or access operation. 426 */ 427 public final byte[] getIccProfileBytes(final byte[] bytes, final T params) throws ImagingException, IOException { 428 return getIccProfileBytes(ByteSource.array(bytes), params); 429 } 430 431 /** 432 * Gets an array of bytes describing the International Color Consortium (ICC) specification for the color space of the image contained in the input 433 * byteSource. Not all formats support ICC profiles. 434 * 435 * @param byteSource A valid ByteSource. 436 * @param params Optional instructions for special-handling or interpretation of the input data. 437 * @return If available, a valid array of bytes; otherwise, a null 438 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 439 * @throws IOException In the event of unsuccessful read or access operation. 440 */ 441 public abstract byte[] getIccProfileBytes(ByteSource byteSource, T params) throws ImagingException, IOException; 442 443 /** 444 * Gets an array of bytes describing the International Color Consortium (ICC) specification for the color space of the image contained in the input file. 445 * Not all formats support ICC profiles. 446 * 447 * @param file A valid file reference. 448 * @return If available, a valid array of bytes; otherwise, a null 449 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 450 * @throws IOException In the event of unsuccessful read or access operation. 451 */ 452 public final byte[] getIccProfileBytes(final File file) throws ImagingException, IOException { 453 return getIccProfileBytes(file, null); 454 } 455 456 /** 457 * Gets an array of bytes describing the International Color Consortium (ICC) specification for the color space of the image contained in the input file. 458 * Not all formats support ICC profiles. 459 * 460 * @param file A valid file reference. 461 * @param params Optional instructions for special-handling or interpretation of the input data. 462 * @return If available, a valid array of bytes; otherwise, a null 463 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 464 * @throws IOException In the event of unsuccessful read or access operation. 465 */ 466 public final byte[] getIccProfileBytes(final File file, final T params) throws ImagingException, IOException { 467 if (!canAcceptExtension(file)) { 468 return null; 469 } 470 471 if (LOGGER.isLoggable(Level.FINEST)) { 472 LOGGER.finest(getName() + ": " + file.getName()); 473 } 474 475 return getIccProfileBytes(ByteSource.file(file), params); 476 } 477 478 /** 479 * Gets image information from the specified array of bytes. Format-specific ImageParser implementations are expected to return a valid ImageInfo object or 480 * to throw an ImageReadException if unable to process the specified data. 481 * <p> 482 * The params argument provides a mechanism for individual implementations to pass optional information into the parser. Not all formats will require this 483 * capability. Because the base class may call this method with a null params argument, implementations should <strong>always</strong> include logic for 484 * ignoring null input. 485 * 486 * @param bytes A valid array of bytes 487 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 488 * implementations). 489 * @return A valid image information object describing the content extracted from the specified data. 490 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 491 * @throws IOException In the event of unsuccessful data access operation. 492 */ 493 public final ImageInfo getImageInfo(final byte[] bytes, final T params) throws ImagingException, IOException { 494 return getImageInfo(ByteSource.array(bytes), params); 495 } 496 497 /** 498 * Gets image information from the specified ByteSource. Format-specific ImageParser implementations are expected to return a valid ImageInfo object or to 499 * throw an ImageReadException if unable to process the specified data. 500 * 501 * @param byteSource A valid ByteSource object 502 * @return A valid image information object describing the content extracted from the specified data. 503 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 504 * @throws IOException In the event of unsuccessful data access operation. 505 */ 506 public final ImageInfo getImageInfo(final ByteSource byteSource) throws ImagingException, IOException { 507 return getImageInfo(byteSource, null); 508 } 509 510 /** 511 * Gets image information from the specified ByteSource. Format-specific ImageParser implementations are expected to return a valid ImageInfo object or to 512 * throw an ImageReadException if unable to process the specified data. 513 * 514 * <p> 515 * The params argument provides a mechanism for individual implementations to pass optional information into the parser. Not all formats will require this 516 * capability. Because the base class may call this method with a null params argument, implementations should <strong>always</strong> include logic for 517 * ignoring null input. 518 * 519 * @param byteSource A valid ByteSource object 520 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 521 * implementations). 522 * @return A valid image information object describing the content extracted from the specified data. 523 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 524 * @throws IOException In the event of unsuccessful data access operation. 525 */ 526 public abstract ImageInfo getImageInfo(ByteSource byteSource, T params) throws ImagingException, IOException; 527 528 /** 529 * Gets image information from the specified file Format-specific ImageParser implementations are expected to return a valid ImageInfo object or to throw an 530 * ImageReadException if unable to process the specified data. 531 * <p> 532 * The params argument provides a mechanism for individual implementations to pass optional information into the parser. Not all formats will require this 533 * capability. Because the base class may call this method with a null params argument, implementations should <strong>always</strong> include logic for 534 * ignoring null input. 535 * 536 * @param file A valid File object 537 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 538 * implementations). 539 * @return A valid image information object describing the content extracted from the specified data. 540 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 541 * @throws IOException In the event of unsuccessful file read or access operation. 542 */ 543 public final ImageInfo getImageInfo(final File file, final T params) throws ImagingException, IOException { 544 if (!canAcceptExtension(file)) { 545 return null; 546 } 547 548 return getImageInfo(ByteSource.file(file), params); 549 } 550 551 /** 552 * Gets the size of the image described by the specified byte array. 553 * 554 * @param bytes A valid byte array. 555 * @return A valid instance of Dimension. 556 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 557 * @throws IOException In the event of unsuccessful read or access operation. 558 */ 559 public final Dimension getImageSize(final byte[] bytes) throws ImagingException, IOException { 560 return getImageSize(bytes, null); 561 } 562 563 /** 564 * Gets the size of the image described by the specified byte array. 565 * 566 * @param bytes A valid byte array. 567 * @param params Optional instructions for special-handling or interpretation of the input data. 568 * @return A valid instance of Dimension. 569 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 570 * @throws IOException In the event of unsuccessful read or access operation. 571 */ 572 public final Dimension getImageSize(final byte[] bytes, final T params) throws ImagingException, IOException { 573 return getImageSize(ByteSource.array(bytes), params); 574 } 575 576 /** 577 * Gets the size of the image described by the specified ByteSource. 578 * 579 * @param byteSource A valid reference to a ByteSource. 580 * @param params Optional instructions for special-handling or interpretation of the input data. 581 * @return A valid instance of Dimension. 582 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 583 * @throws IOException In the event of unsuccessful read or access operation. 584 */ 585 public abstract Dimension getImageSize(ByteSource byteSource, T params) throws ImagingException, IOException; 586 587 /** 588 * Gets the size of the image described by the specified file. 589 * 590 * @param file A valid reference to a file. 591 * @return A valid instance of Dimension. 592 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 593 * @throws IOException In the event of unsuccessful read or access operation. 594 */ 595 public final Dimension getImageSize(final File file) throws ImagingException, IOException { 596 return getImageSize(file, null); 597 } 598 599 /** 600 * Gets the size of the image described by the specified file. 601 * 602 * @param file A valid reference to a file. 603 * @param params Optional instructions for special-handling or interpretation of the input data. 604 * @return A valid instance of Dimension. 605 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 606 * @throws IOException In the event of unsuccessful read or access operation. 607 */ 608 public final Dimension getImageSize(final File file, final T params) throws ImagingException, IOException { 609 610 if (!canAcceptExtension(file)) { 611 return null; 612 } 613 614 return getImageSize(ByteSource.file(file), params); 615 } 616 617 /** 618 * Gets image metadata from the specified array of bytes. Format-specific ImageParser implementations are expected to return a valid IImageMetadata object 619 * or to throw an ImageReadException if unable to process the specified data. 620 * 621 * @param bytes A valid array of bytes 622 * @return A valid, potentially subject-matter-specific implementation of the IImageMetadata interface describing the content extracted from the source 623 * content. 624 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 625 * @throws IOException In the event of unsuccessful data read operation. 626 */ 627 public final ImageMetadata getMetadata(final byte[] bytes) throws ImagingException, IOException { 628 return getMetadata(bytes, null); 629 } 630 631 /** 632 * Gets image metadata from the specified array of bytes. Format-specific ImageParser implementations are expected to return a valid IImageMetadata object 633 * or to throw an ImageReadException if unable to process the specified data. 634 * 635 * <p> 636 * The params argument provides a mechanism for individual implementations to pass optional information into the parser. Not all formats will require this 637 * capability. Because the base class may call this method with a null params argument, implementations should <strong>always</strong> include logic for 638 * ignoring null input. 639 * 640 * @param bytes A valid array of bytes 641 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 642 * implementations). 643 * @return A valid image metadata object describing the content extracted from the specified content. 644 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 645 * @throws IOException In the event of unsuccessful data read operation. 646 */ 647 public final ImageMetadata getMetadata(final byte[] bytes, final T params) throws ImagingException, IOException { 648 return getMetadata(ByteSource.array(bytes), params); 649 } 650 651 /** 652 * Gets image metadata from the specified byte source. Format-specific ImageParser implementations are expected to return a valid IImageMetadata object or 653 * to throw an ImageReadException if unable to process the specified byte source. 654 * 655 * @param byteSource A valid byte source. 656 * @return A valid, potentially subject-matter-specific implementation of the IImageMetadata interface describing the content extracted from the source 657 * content. 658 * @throws ImagingException In the event that the ByteSource content does not conform to the format of the specific parser implementation. 659 * @throws IOException In the event of unsuccessful data read operation. 660 */ 661 public final ImageMetadata getMetadata(final ByteSource byteSource) throws ImagingException, IOException { 662 return getMetadata(byteSource, null); 663 } 664 665 /** 666 * Gets image metadata from the specified byte source. Format-specific ImageParser implementations are expected to return a valid IImageMetadata object or 667 * to throw an ImageReadException if unable to process the specified byte source. 668 * 669 * <p> 670 * The params argument provides a mechanism for individual implementations to pass optional information into the parser. Not all formats will require this 671 * capability. Because the base class may call this method with a null params argument, implementations should <strong>always</strong> include logic for 672 * ignoring null input. 673 * 674 * @param byteSource A valid byte source. 675 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 676 * implementations). 677 * @return A valid, potentially subject-matter-specific implementation of the IImageMetadata interface describing the content extracted from the source 678 * content. 679 * @throws ImagingException In the event that the ByteSource content does not conform to the format of the specific parser implementation. 680 * @throws IOException In the event of unsuccessful data read operation. 681 */ 682 public abstract ImageMetadata getMetadata(ByteSource byteSource, T params) throws ImagingException, IOException; 683 684 /** 685 * Gets image metadata from the specified file. Format-specific ImageParser implementations are expected to return a valid IImageMetadata object or to throw 686 * an ImageReadException if unable to process the specified data. 687 * 688 * @param file A valid reference to a file. 689 * @return A valid image metadata object describing the content extracted from the specified content. 690 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 691 * @throws IOException In the event of unsuccessful file read or access operation. 692 */ 693 public final ImageMetadata getMetadata(final File file) throws ImagingException, IOException { 694 return getMetadata(file, null); 695 } 696 697 /** 698 * Gets image metadata from the specified file. Format-specific ImageParser implementations are expected to return a valid IImageMetadata object or to throw 699 * an ImageReadException if unable to process the specified data. 700 * 701 * <p> 702 * The params argument provides a mechanism for individual implementations to pass optional information into the parser. Not all formats will require this 703 * capability. Because the base class may call this method with a null params argument, implementations should <strong>always</strong> include logic for 704 * ignoring null input. 705 * 706 * @param file A valid reference to a file. 707 * @param params Optional instructions for special-handling or interpretation of the input data (null objects are permitted and must be supported by 708 * implementations). 709 * @return A valid image metadata object describing the content extracted from the specified content. 710 * @throws ImagingException In the event that the specified content does not conform to the format of the specific parser implementation. 711 * @throws IOException In the event of unsuccessful file read or access operation. 712 */ 713 public final ImageMetadata getMetadata(final File file, final T params) throws ImagingException, IOException { 714 if (LOGGER.isLoggable(Level.FINEST)) { 715 LOGGER.finest(getName() + ".getMetadata" + ": " + file.getName()); 716 } 717 718 if (!canAcceptExtension(file)) { 719 return null; 720 } 721 722 return getMetadata(ByteSource.file(file), params); 723 } 724 725 /** 726 * Gets a descriptive name for the implementation of an ImageParser. 727 * 728 * @return a valid, subject-matter-specific string. 729 */ 730 public abstract String getName(); 731 732 /** 733 * Writes the content of a BufferedImage to the specified output stream. 734 * 735 * <p> 736 * The params argument provides a mechanism for individual implementations to pass optional information into the parser. Not all formats will support this 737 * capability. Currently, some of the parsers do not check for null arguments. 738 * </p> 739 * 740 * @param src An image giving the source content for output 741 * @param os A valid output stream for storing the formatted image 742 * @param params optional parameters, defining format-specific instructions for output (such as selections for data compression, color models, etc.) 743 * @throws ImagingException In the event that the output format cannot handle the input image or invalid params are specified. 744 * @throws IOException In the event of an write error from the output stream. 745 */ 746 public void writeImage(final BufferedImage src, final OutputStream os, final T params) throws ImagingException, IOException { 747 throw new ImagingException("This image format (" + getName() + ") cannot be written."); 748 } 749}