/*
* 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;
import org.apache.commons.imaging.util.Debug;
/**
* 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 (debug) {
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 {
try {
os.close(); // we are obligated to close stream.
} catch (final Exception e) {
Debug.debug(e);
}
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 (debug) {
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 (debug) {
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();
}
}