| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.commons.imaging; |
| |
| import java.awt.Dimension; |
| import java.awt.image.BufferedImage; |
| import java.io.File; |
| import java.io.IOException; |
| import java.io.OutputStream; |
| import java.io.PrintWriter; |
| import java.io.StringWriter; |
| import java.util.ArrayList; |
| import java.util.List; |
| import java.util.Map; |
| |
| import org.apache.commons.imaging.common.BinaryFileParser; |
| import org.apache.commons.imaging.common.IBufferedImageFactory; |
| import org.apache.commons.imaging.common.IImageMetadata; |
| import org.apache.commons.imaging.common.SimpleBufferedImageFactory; |
| import org.apache.commons.imaging.common.bytesource.ByteSource; |
| import org.apache.commons.imaging.common.bytesource.ByteSourceArray; |
| import org.apache.commons.imaging.common.bytesource.ByteSourceFile; |
| import org.apache.commons.imaging.formats.bmp.BmpImageParser; |
| import org.apache.commons.imaging.formats.dcx.DcxImageParser; |
| import org.apache.commons.imaging.formats.gif.GifImageParser; |
| import org.apache.commons.imaging.formats.icns.IcnsImageParser; |
| import org.apache.commons.imaging.formats.ico.IcoImageParser; |
| import org.apache.commons.imaging.formats.jpeg.JpegImageParser; |
| import org.apache.commons.imaging.formats.pcx.PcxImageParser; |
| import org.apache.commons.imaging.formats.png.PngImageParser; |
| import org.apache.commons.imaging.formats.pnm.PnmImageParser; |
| import org.apache.commons.imaging.formats.psd.PsdImageParser; |
| import org.apache.commons.imaging.formats.rgbe.RgbeImageParser; |
| import org.apache.commons.imaging.formats.tiff.TiffImageParser; |
| import org.apache.commons.imaging.formats.wbmp.WbmpImageParser; |
| import org.apache.commons.imaging.formats.xbm.XbmImageParser; |
| import org.apache.commons.imaging.formats.xpm.XpmImageParser; |
| |
| /** |
| * Provides the abstract base class for all image reading and writing |
| * utilities. ImageParser implementations are expected to extend this |
| * class providing logic for identifying and processing data in their |
| * own specific format. Specific implementations are found |
| * under the com.apache.commons.imaging.formats package. |
| * <h3>Application Notes</h3> |
| * <h4>Format support</h4> |
| * For the most recent information on format support for the |
| * Apache Commons Imaging package, refer to |
| * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a> |
| * at the main project development web site. |
| * <h4>On the accuracy of this Javadoc</h4> |
| * 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 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 assume |
| * that the documentation is perfect, especially in the more obscure |
| * and specialized areas of implementation. |
| * <h4>The "Map params" argument</h4> |
| * Many of the methods specified by this class accept an argument of |
| * type Map giving a list of parameters to be used when processing an |
| * image. For example, some of the output formats permit the specification |
| * of different kinds of image compression or color models. Some of the |
| * reading methods permit the calling application to require strict |
| * format compliance. In many cases, however, an application will not |
| * require the use of this argument. While some of the ImageParser |
| * implementations check for (and ignore) null arguments for this parameter, |
| * not all of them do (at least not at the time these notes were written). |
| * Therefore, a prudent programmer will always supply an valid, though |
| * empty instance of a Map implementation when calling such methods. |
| * Generally, the java HashMap class is useful for this purpose. |
| * <p>Additionally, developers creating or enhancing classes derived |
| * from ImageParser are encouraged to include such checks in their code. |
| */ |
| public abstract class ImageParser extends BinaryFileParser implements |
| ImagingConstants { |
| |
| /** |
| * Gets an array of new instances of all image parsers. |
| * @return A valid array of image parsers |
| */ |
| public static final ImageParser[] getAllImageParsers() { |
| final ImageParser result[] = { |
| new BmpImageParser(), |
| new DcxImageParser(), |
| new GifImageParser(), |
| new IcnsImageParser(), |
| new IcoImageParser(), |
| new JpegImageParser(), |
| new PcxImageParser(), |
| new PngImageParser(), |
| new PnmImageParser(), |
| new PsdImageParser(), |
| new RgbeImageParser(), |
| new TiffImageParser(), |
| new WbmpImageParser(), |
| new XbmImageParser(), |
| new XpmImageParser(), |
| // new JBig2ImageParser(), |
| // new TgaImageParser(), |
| }; |
| |
| return result; |
| } |
| |
| /** |
| * Get image metadata from the specified byte source. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * IImageMetadata object or to throw an ImageReadException if unable |
| * to process the specified byte source. |
| * @param byteSource A valid byte source. |
| * @return A valid, potentially subject-matter-specific implementation of |
| * the IImageMetadata interface describing the content extracted |
| * from the source content. |
| * @throws ImageReadException In the event that the the ByteSource |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful data read operation. |
| */ |
| public final IImageMetadata getMetadata(final ByteSource byteSource) |
| throws ImageReadException, IOException { |
| return getMetadata(byteSource, null); |
| } |
| |
| /** |
| * Get image metadata from the specified byte source. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * IImageMetadata object or to throw an ImageReadException if unable |
| * to process the specified byte source. |
| * <p>The params argument provides a mechanism for individual |
| * implementations to pass optional information into the parser. |
| * Not all formats will require this capability. Because the |
| * base class may call this method with a null params argument, |
| * implementations should <strong>always</strong> include logic |
| * for ignoring null input. |
| * @param byteSource A valid byte source. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid, potentially subject-matter-specific implementation of |
| * the IImageMetadata interface describing the content extracted |
| * from the source content. |
| * @throws ImageReadException In the event that the the ByteSource |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful data read operation. |
| */ |
| public abstract IImageMetadata getMetadata(ByteSource byteSource, Map<String,Object> params) |
| throws ImageReadException, IOException; |
| |
| |
| |
| /** |
| * Get image metadata from the specified array of bytes. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * IImageMetadata object or to throw an ImageReadException if unable |
| * to process the specified data. |
| * @param bytes A valid array of bytes |
| * @return A valid, potentially subject-matter-specific implementation of |
| * the IImageMetadata interface describing the content extracted |
| * from the source content. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful data read operation. |
| */ |
| public final IImageMetadata getMetadata(final byte bytes[]) |
| throws ImageReadException, IOException { |
| return getMetadata(bytes, null); |
| } |
| |
| /** |
| * Get image metadata from the specified array of bytes. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * IImageMetadata object or to throw an ImageReadException if unable |
| * to process the specified data. |
| * <p>The params argument provides a mechanism for individual |
| * implementations to pass optional information into the parser. |
| * Not all formats will require this capability. Because the |
| * base class may call this method with a null params argument, |
| * implementations should <strong>always</strong> include logic |
| * for ignoring null input. |
| * @param bytes A valid array of bytes |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid image metadata object describing the content extracted |
| * from the specified content. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful data read operation. |
| */ |
| public final IImageMetadata getMetadata(final byte bytes[], final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| return getMetadata(new ByteSourceArray(bytes), params); |
| } |
| |
| |
| |
| |
| /** |
| * Get image metadata from the specified file. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * IImageMetadata object or to throw an ImageReadException if unable |
| * to process the specified data. |
| * @param file A valid reference to a file. |
| * @return A valid image metadata object describing the content extracted |
| * from the specified content. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful file read or |
| * access operation. |
| */ |
| public final IImageMetadata getMetadata(final File file) |
| throws ImageReadException, IOException { |
| return getMetadata(file, null); |
| } |
| |
| /** |
| * Get image metadata from the specified file. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * IImageMetadata object or to throw an ImageReadException if unable |
| * to process the specified data. |
| * <p>The params argument provides a mechanism for individual |
| * implementations to pass optional information into the parser. |
| * Not all formats will require this capability. Because the |
| * base class may call this method with a null params argument, |
| * implementations should <strong>always</strong> include logic |
| * for ignoring null input. |
| * @param file A valid reference to a file. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid image metadata object describing the content extracted |
| * from the specified content. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful file read or |
| * access operation. |
| */ |
| public final IImageMetadata getMetadata(final File file, final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| if (getDebug()) { |
| System.out.println(getName() + ".getMetadata" + ": " |
| + file.getName()); |
| } |
| |
| if (!canAcceptExtension(file)) { |
| return null; |
| } |
| |
| return getMetadata(new ByteSourceFile(file), params); |
| } |
| |
| |
| |
| /** |
| * Get image information from the specified ByteSource. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * ImageInfo object or to throw an ImageReadException if unable |
| * to process the specified data. |
| * <p>The params argument provides a mechanism for individual |
| * implementations to pass optional information into the parser. |
| * Not all formats will require this capability. Because the |
| * base class may call this method with a null params argument, |
| * implementations should <strong>always</strong> include logic |
| * for ignoring null input. |
| * @param byteSource A valid ByteSource object |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid image information object describing the content extracted |
| * from the specified data. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful data |
| * access operation. |
| */ |
| public abstract ImageInfo getImageInfo(ByteSource byteSource, Map<String,Object> params) |
| throws ImageReadException, IOException; |
| |
| |
| |
| /** |
| * Get image information from the specified ByteSource. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * ImageInfo object or to throw an ImageReadException if unable |
| * to process the specified data. |
| * @param byteSource A valid ByteSource object |
| * @return A valid image information object describing the content extracted |
| * from the specified data. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful data |
| * access operation. |
| */ |
| public final ImageInfo getImageInfo(final ByteSource byteSource) |
| throws ImageReadException, IOException { |
| return getImageInfo(byteSource, null); |
| } |
| |
| |
| |
| /** |
| * Get image information from the specified array of bytes. Format-specific |
| * ImageParser implementations are expected to return a valid |
| * ImageInfo object or to throw an ImageReadException if unable |
| * to process the specified data. |
| * <p>The params argument provides a mechanism for individual |
| * implementations to pass optional information into the parser. |
| * Not all formats will require this capability. Because the |
| * base class may call this method with a null params argument, |
| * implementations should <strong>always</strong> include logic |
| * for ignoring null input. |
| * @param bytes A valid array of bytes |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid image information object describing the content extracted |
| * from the specified data. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful data |
| * access operation. |
| */ |
| public final ImageInfo getImageInfo(final byte bytes[], final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| return getImageInfo(new ByteSourceArray(bytes), params); |
| } |
| |
| /** |
| * Get image information from the specified file Format-specific |
| * ImageParser implementations are expected to return a valid |
| * ImageInfo object or to throw an ImageReadException if unable |
| * to process the specified data. |
| * <p>The params argument provides a mechanism for individual |
| * implementations to pass optional information into the parser. |
| * Not all formats will require this capability. Because the |
| * base class may call this method with a null params argument, |
| * implementations should <strong>always</strong> include logic |
| * for ignoring null input. |
| * @param file A valid File object |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid image information object describing the content extracted |
| * from the specified data. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful file read or |
| * access operation. |
| */ |
| public final ImageInfo getImageInfo(final File file, final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| if (!canAcceptExtension(file)) { |
| return null; |
| } |
| |
| return getImageInfo(new ByteSourceFile(file), params); |
| } |
| |
| /** |
| * Determines the format compliance of the content of the supplied byte |
| * source based on rules provided by a specific implementation. |
| * @param byteSource A valid instance of ByteSource |
| * @return true if the content is format-compliant; otherwise, false |
| * @throws ImageReadException |
| * may be thrown by sub-classes |
| * @throws IOException |
| * may be thrown by sub-classes |
| */ |
| public FormatCompliance getFormatCompliance(final ByteSource byteSource) |
| throws ImageReadException, IOException { |
| return null; |
| } |
| |
| |
| /** |
| * Determines the format compliance of the content of the supplied byte |
| * array based on rules provided by a specific implementation. |
| * @param bytes A valid byte array. |
| * @return A valid FormatCompliance object. |
| * @throws ImageReadException |
| * may be thrown by sub-classes |
| * @throws IOException |
| * may be thrown by sub-classes |
| */ |
| public final FormatCompliance getFormatCompliance(final byte bytes[]) |
| throws ImageReadException, IOException { |
| return getFormatCompliance(new ByteSourceArray(bytes)); |
| } |
| |
| |
| /** |
| * Determines the format compliance of the specified file based on |
| * rules provided by a specific implementation. |
| * @param file A valid reference to a file. |
| * @return A valid format compliance object. |
| * @throws ImageReadException |
| * may be thrown by sub-classes |
| * @throws IOException |
| * may be thrown by sub-classes |
| */ |
| public final FormatCompliance getFormatCompliance(final File file) |
| throws ImageReadException, IOException { |
| if (!canAcceptExtension(file)) { |
| return null; |
| } |
| |
| return getFormatCompliance(new ByteSourceFile(file)); |
| } |
| |
| /** |
| * Gets all images specified by the byte source (some |
| * formats may include multiple images within a single data source). |
| * @param byteSource A valid instance of ByteSource. |
| * @return A valid (potentially empty) list of BufferedImage objects. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public List<BufferedImage> getAllBufferedImages(final ByteSource byteSource) |
| throws ImageReadException, IOException { |
| final BufferedImage bi = getBufferedImage(byteSource, null); |
| |
| final List<BufferedImage> result = new ArrayList<BufferedImage>(); |
| |
| result.add(bi); |
| |
| return result; |
| } |
| |
| /** |
| * Gets all images specified by the byte array (some |
| * formats may include multiple images within a single data source). |
| * @param bytes A valid byte array |
| * @return A valid (potentially empty) list of BufferedImage objects. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final List<BufferedImage> getAllBufferedImages(final byte bytes[]) |
| throws ImageReadException, IOException { |
| return getAllBufferedImages(new ByteSourceArray(bytes)); |
| } |
| |
| /** |
| * Gets all images specified by indicated file (some |
| * formats may include multiple images within a single data source). |
| * @param file A valid reference to a file. |
| * @return A valid (potentially empty) list of BufferedImage objects. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final List<BufferedImage> getAllBufferedImages(final File file) |
| throws ImageReadException, IOException { |
| if (!canAcceptExtension(file)) { |
| return null; |
| } |
| |
| return getAllBufferedImages(new ByteSourceFile(file)); |
| } |
| |
| |
| /** |
| * Gets a buffered image specified by the byte source (for |
| * sources that specify multiple images, choice of which image |
| * is returned is implementation dependent). |
| * @param byteSource A valid instance of ByteSource |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid instance of BufferedImage. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public abstract BufferedImage getBufferedImage(ByteSource byteSource, |
| Map<String,Object> params) throws ImageReadException, IOException; |
| |
| /** |
| * Gets a buffered image specified by the byte array (for |
| * sources that specify multiple images, choice of which image |
| * is returned is implementation dependent). |
| * @param bytes A valid byte array |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid instance of BufferedImage. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final BufferedImage getBufferedImage(final byte bytes[], final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| return getBufferedImage(new ByteSourceArray(bytes), params); |
| } |
| |
| /** |
| * Gets a buffered image specified by the indicated file (for |
| * sources that specify multiple images, choice of which image |
| * is returned is implementation dependent). |
| * @param file A valid file reference. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data (null objects are permitted and |
| * must be supported by implementations). |
| * @return A valid instance of BufferedImage. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final BufferedImage getBufferedImage(final File file, final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| if (!canAcceptExtension(file)) { |
| return null; |
| } |
| |
| return getBufferedImage(new ByteSourceFile(file), params); |
| } |
| |
| |
| /** |
| * Writes the content of a BufferedImage to the specified output |
| * stream. |
| * <p>The params argument provides a mechanism for individual |
| * implementations to pass optional information into the parser. |
| * Not all formats will support this capability. Currently, |
| * some of the parsers do not check for null arguments. So in cases |
| * where no optional specifications are supported, application |
| * code should pass in an empty instance of an implementation of |
| * the map interface (i.e. an empty HashMap). |
| * @param src An image giving the source content for output |
| * @param os A valid output stream for storing the formatted image |
| * @param params A non-null Map implementation supplying optional, |
| * format-specific instructions for output |
| * (such as selections for data compression, color models, etc.) |
| * @throws ImageWriteException In the event that the output format |
| * cannot handle the input image or invalid params are specified. |
| * @throws IOException In the event of an write error from |
| * the output stream. |
| */ |
| public void writeImage(final BufferedImage src, final OutputStream os, final Map<String,Object> params) |
| throws ImageWriteException, IOException { |
| os.close(); // we are obligated to close stream. |
| |
| throw new ImageWriteException("This image format (" + getName() |
| + ") cannot be written."); |
| } |
| |
| /** |
| * Get the size of the image described by the specified byte array. |
| * @param bytes A valid byte array. |
| * @return A valid instance of Dimension. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final Dimension getImageSize(final byte bytes[]) |
| throws ImageReadException, IOException { |
| return getImageSize(bytes, null); |
| } |
| |
| /** |
| * Get the size of the image described by the specified byte array. |
| * @param bytes A valid byte array. |
| * @return A valid instance of Dimension. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final Dimension getImageSize(final byte bytes[], final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| return getImageSize(new ByteSourceArray(bytes), params); |
| } |
| |
| /** |
| * Get the size of the image described by the specified file. |
| * @param file A valid reference to a file. |
| * @return A valid instance of Dimension. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final Dimension getImageSize(final File file) throws ImageReadException, |
| IOException { |
| |
| return getImageSize(file, null); |
| } |
| |
| /** |
| * Get the size of the image described by the specified file. |
| * @param file A valid reference to a file. |
| * @return A valid instance of Dimension. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final Dimension getImageSize(final File file, final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| |
| if (!canAcceptExtension(file)) { |
| return null; |
| } |
| |
| return getImageSize(new ByteSourceFile(file), params); |
| } |
| |
| /** |
| * Get the size of the image described by the specified ByteSource. |
| * @param byteSource A valid reference to a ByteSource. |
| * @return A valid instance of Dimension. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public abstract Dimension getImageSize(ByteSource byteSource, Map<String,Object> params) |
| throws ImageReadException, IOException; |
| |
| |
| /** |
| * Get a string containing XML-formatted text conforming to the Extensible |
| * Metadata Platform (EXP) standard for representing information about |
| * image content. Not all image formats support EXP infomation and |
| * even for those that do, there is no guarantee that such information |
| * will be present in an image. |
| * @param byteSource A valid reference to a ByteSource. |
| * @return If XMP metadata is present, a valid string; |
| * if it is not present, a null. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public abstract String getXmpXml(ByteSource byteSource, Map<String,Object> params) |
| throws ImageReadException, IOException; |
| |
| |
| |
| /** |
| * Get an array of bytes describing the International Color Consortium (ICC) |
| * specification for the color space of the image contained in the |
| * input byte array. Not all formats support ICC profiles. |
| * @param bytes A valid array of bytes. |
| * @return If available, a valid array of bytes; otherwise, a null |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final byte[] getICCProfileBytes(final byte bytes[]) |
| throws ImageReadException, IOException { |
| return getICCProfileBytes(bytes, null); |
| } |
| |
| /** |
| * Get an array of bytes describing the International Color Consortium (ICC) |
| * specification for the color space of the image contained in the |
| * input byte array. Not all formats support ICC profiles. |
| * @param bytes A valid array of bytes. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data. |
| * @return If available, a valid array of bytes; otherwise, a null |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final byte[] getICCProfileBytes(final byte bytes[], final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| return getICCProfileBytes(new ByteSourceArray(bytes), params); |
| } |
| |
| /** |
| * Get an array of bytes describing the International Color Consortium (ICC) |
| * specification for the color space of the image contained in the |
| * input file. Not all formats support ICC profiles. |
| * @param file A valid file reference. |
| * @return If available, a valid array of bytes; otherwise, a null |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final byte[] getICCProfileBytes(final File file) |
| throws ImageReadException, IOException { |
| return getICCProfileBytes(file, null); |
| } |
| |
| /** |
| * Get an array of bytes describing the International Color Consortium (ICC) |
| * specification for the color space of the image contained in the |
| * input file. Not all formats support ICC profiles. |
| * @param file A valid file reference. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data. |
| * @return If available, a valid array of bytes; otherwise, a null |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final byte[] getICCProfileBytes(final File file, final Map<String,Object> params) |
| throws ImageReadException, IOException { |
| if (!canAcceptExtension(file)) { |
| return null; |
| } |
| |
| if (getDebug()) { |
| System.out.println(getName() + ": " + file.getName()); |
| } |
| |
| return getICCProfileBytes(new ByteSourceFile(file), params); |
| } |
| |
| |
| /** |
| * Get an array of bytes describing the International Color Consortium (ICC) |
| * specification for the color space of the image contained in the |
| * input byteSoruce. Not all formats support ICC profiles. |
| * @param byteSource A valid ByteSource. |
| * @param params Optional instructions for special-handling or |
| * interpretation of the input data. |
| * @return If available, a valid array of bytes; otherwise, a null |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public abstract byte[] getICCProfileBytes(ByteSource byteSource, Map<String,Object> params) |
| throws ImageReadException, IOException; |
| |
| |
| /** |
| * Write the ImageInfo and format-specific information for the image |
| * content of the specified byte array to a string. |
| * @param bytes A valid array of bytes. |
| * @return A valid string. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final String dumpImageFile(final byte bytes[]) throws ImageReadException, |
| IOException { |
| return dumpImageFile(new ByteSourceArray(bytes)); |
| } |
| |
| |
| /** |
| * Write the ImageInfo and format-specific information for the image |
| * content of the specified file to a string. |
| * @param file A valid file reference. |
| * @return A valid string. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final String dumpImageFile(final File file) throws ImageReadException, |
| IOException { |
| if (!canAcceptExtension(file)) { |
| return null; |
| } |
| |
| if (getDebug()) { |
| System.out.println(getName() + ": " + file.getName()); |
| } |
| |
| return dumpImageFile(new ByteSourceFile(file)); |
| } |
| |
| /** |
| * Write the ImageInfo and format-specific information for the image |
| * content of the specified byte source to a string. |
| * @param byteSource A valid byte source. |
| * @return A valid string. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public final String dumpImageFile(final ByteSource byteSource) |
| throws ImageReadException, IOException { |
| final StringWriter sw = new StringWriter(); |
| final PrintWriter pw = new PrintWriter(sw); |
| |
| dumpImageFile(pw, byteSource); |
| |
| pw.flush(); |
| |
| return sw.toString(); |
| } |
| |
| /** |
| * Write the ImageInfo and format-specific information for the image |
| * content of the specified byte source to a PrintWriter |
| * @param byteSource A valid byte source. |
| * @return A valid PrintWriter. |
| * @throws ImageReadException In the event that the the specified |
| * content does not conform to the format of the specific parser |
| * implementation. |
| * @throws IOException In the event of unsuccessful read or |
| * access operation. |
| */ |
| public boolean dumpImageFile(final PrintWriter pw, final ByteSource byteSource) |
| throws ImageReadException, IOException { |
| return false; |
| } |
| |
| |
| /** |
| * This method is not fully implemented in any of the current parsers, |
| * all of which return false when it is called. |
| * Although it was clearly intended to embed an ICC profile in a file, |
| * no description of the intended use of the File arguments is available. |
| * @param src A file reference. |
| * @param dst A file reference. |
| * @param profile An array of bytes describing the ICC profile |
| * @return true if the embedding operation was successful; otherwise, false. |
| */ |
| public abstract boolean embedICCProfile(File src, File dst, byte profile[]); |
| |
| /** |
| * Get a descriptive name for the implementation of an ImageParser. |
| * @return a valid, subject-matter-specific string. |
| */ |
| public abstract String getName(); |
| |
| /** |
| * Get the default extension for the format specified by an implementation |
| * of ImageParser. Some parsers can support more than one extension |
| * (i.e. .JPEG, .JPG; .TIF, .TIFF, etc.). |
| * @return A valid string. |
| */ |
| public abstract String getDefaultExtension(); |
| |
| /** |
| * Get an array of all accepted extensions |
| * @return A valid array of one or more elements. |
| */ |
| protected abstract String[] getAcceptedExtensions(); |
| |
| /** |
| * Get an array of ImageFormat objects describing all |
| * accepted types |
| * @return A valid array of one or more elements. |
| */ |
| protected abstract ImageFormat[] getAcceptedTypes(); |
| |
| /** |
| * Indicates whether the ImageParser implementation can accept |
| * the specified format |
| * @param type An instance of ImageFormat. |
| * @return If the parser can accept the format, true; otherwise, false. |
| */ |
| public boolean canAcceptType(final ImageFormat type) { |
| final ImageFormat types[] = getAcceptedTypes(); |
| |
| for (final ImageFormat type2 : types) { |
| if (type2.equals(type)) { |
| return true; |
| } |
| } |
| return false; |
| } |
| |
| /** |
| * Indicates whether the ImageParser implementation can accept |
| * the specified file based on its extension. |
| * @param file An valid file reference. |
| * @return If the parser can accept the format, true; otherwise, false. |
| */ |
| protected final boolean canAcceptExtension(final File file) { |
| return canAcceptExtension(file.getName()); |
| } |
| |
| /** |
| * Indicates whether the ImageParser implementation can accept |
| * the specified file name based on its extension. |
| * @param filename An valid string giving a file name or file path. |
| * @return If the parser can accept the format, true; otherwise, false. |
| */ |
| protected final boolean canAcceptExtension(final String filename) { |
| final String exts[] = getAcceptedExtensions(); |
| if (exts == null) { |
| return true; |
| } |
| |
| final int index = filename.lastIndexOf('.'); |
| if (index >= 0) { |
| String ext = filename.substring(index); |
| ext = ext.toLowerCase(); |
| |
| for (final String ext2 : exts) { |
| if (ext2.toLowerCase().equals(ext)) { |
| return true; |
| } |
| } |
| } |
| return false; |
| } |
| |
| |
| /** |
| * Get an instance of IBufferedImageFactory based on the presence |
| * of a specification for ImagingConstants..BUFFERED_IMAGE_FACTORY |
| * within the supplied params. |
| * @param params A valid Map object, or a null. |
| * @return A valid instance of an implementation of a |
| * IBufferedImageFactory. |
| */ |
| protected IBufferedImageFactory getBufferedImageFactory(final Map<String,Object> params) { |
| if (params == null) { |
| return new SimpleBufferedImageFactory(); |
| } |
| |
| final IBufferedImageFactory result = (IBufferedImageFactory) params |
| .get(ImagingConstants.BUFFERED_IMAGE_FACTORY); |
| |
| if (null != result) { |
| return result; |
| } |
| |
| return new SimpleBufferedImageFactory(); |
| } |
| |
| /** |
| * A utility method to search a params specification and determine |
| * whether it contains the ImagingConstants.PARAM_KEY_STRICT |
| * specification. Intended |
| * for internal use by ImageParser implementations. |
| * @param params A valid Map object (or a null). |
| * @return If the params specify strict format compliance, true; |
| * otherwise, false. |
| */ |
| public static final boolean isStrict(final Map<String,Object> params) { |
| if (params == null || !params.containsKey(PARAM_KEY_STRICT)) { |
| return false; |
| } |
| return ((Boolean) params.get(PARAM_KEY_STRICT)).booleanValue(); |
| } |
| } |
