You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by da...@apache.org on 2012/06/26 21:32:24 UTC
svn commit: r1354188 [1/2] - in
/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging: ./
common/ formats/tiff/
Author: damjan
Date: Tue Jun 26 19:32:21 2012
New Revision: 1354188
URL: http://svn.apache.org/viewvc?rev=1354188&view=rev
Log:
Add more Javadoc to main package.
Submitted by: Gary Lucas <gwlucas at sonalysts dot com>
Jira issue key: IMAGING-81
Added:
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html (with props)
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html (with props)
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html (with props)
Modified:
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ColorTools.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/FormatCompliance.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageDump.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageFormat.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageParser.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageReadException.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageWriteException.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ColorTools.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ColorTools.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ColorTools.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ColorTools.java Tue Jun 26 19:32:21 2012
@@ -31,7 +31,12 @@ import java.io.File;
import java.io.IOException;
/**
- * This class is a mess and needs to be cleaned up.
+ * A selection of tools for evaluating and manipulating color
+ * spaces, color values, etc.
+ * <p>The Javadoc provided in the original code gave the
+ * following notation:<br><br>
+ *
+ * "This class is a mess and needs to be cleaned up."
*/
public class ColorTools {
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/FormatCompliance.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/FormatCompliance.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/FormatCompliance.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/FormatCompliance.java Tue Jun 26 19:32:21 2012
@@ -23,6 +23,10 @@ import java.nio.charset.Charset;
import java.util.ArrayList;
import java.util.List;
+/**
+ * Provides information about the compliance of a specified data
+ * source (byte array, file, etc.) to an image format.
+ */
public class FormatCompliance {
private final boolean failOnError;
private final String description;
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageDump.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageDump.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageDump.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageDump.java Tue Jun 26 19:32:21 2012
@@ -24,6 +24,10 @@ import java.awt.image.BufferedImage;
import org.apache.commons.imaging.icc.IccProfileInfo;
import org.apache.commons.imaging.icc.IccProfileParser;
+/**
+ * Used to store metadata and descriptive information extracted from
+ * image files.
+ */
public class ImageDump {
private String colorSpaceTypeToName(ColorSpace cs) {
// System.out.println(prefix + ": " + "type: "
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageFormat.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageFormat.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageFormat.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageFormat.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,9 @@
*/
package org.apache.commons.imaging;
+/**
+ * Provides a definition for an image format.
+ */
public class ImageFormat {
public final String name;
public final String extension;
@@ -78,7 +81,12 @@ public class ImageFormat {
public static final ImageFormat IMAGE_FORMAT_XPM = new ImageFormat("XPM");
public static final ImageFormat IMAGE_FORMAT_RGBE = new ImageFormat("RGBE");
- public static final ImageFormat[] getAllFormats() {
+ /**
+ * Gets an array of ImageFormat objects for all supported image
+ * formats.
+ * @return A valid array of ImageFormat objects.
+ */
+ public static ImageFormat[] getAllFormats() {
ImageFormat result[] = { IMAGE_FORMAT_UNKNOWN, IMAGE_FORMAT_PNG,
IMAGE_FORMAT_GIF, IMAGE_FORMAT_TIFF, IMAGE_FORMAT_JPEG,
IMAGE_FORMAT_BMP, IMAGE_FORMAT_PSD, IMAGE_FORMAT_PBM,
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageParser.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageParser.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageParser.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageParser.java Tue Jun 26 19:32:21 2012
@@ -51,9 +51,49 @@ import org.apache.commons.imaging.format
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() {
ImageParser result[] = { new JpegImageParser(), new TiffImageParser(),
new PngImageParser(), new BmpImageParser(),
@@ -70,29 +110,144 @@ public abstract class ImageParser extend
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(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 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(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(byte bytes[], Map 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(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(File file, Map params)
throws ImageReadException, IOException {
if (debug)
@@ -105,19 +260,108 @@ public abstract class ImageParser extend
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 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(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(byte bytes[], Map 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(File file, Map params)
throws ImageReadException, IOException {
if (!canAcceptExtension(file))
@@ -127,6 +371,10 @@ public abstract class ImageParser extend
}
/**
+ * 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
@@ -137,11 +385,33 @@ public abstract class ImageParser extend
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(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(File file)
throws ImageReadException, IOException {
if (!canAcceptExtension(file))
@@ -150,6 +420,17 @@ public abstract class ImageParser extend
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(ByteSource byteSource)
throws ImageReadException, IOException {
BufferedImage bi = getBufferedImage(byteSource, null);
@@ -161,11 +442,33 @@ public abstract class ImageParser extend
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(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(File file)
throws ImageReadException, IOException {
if (!canAcceptExtension(file))
@@ -174,55 +477,60 @@ public abstract class ImageParser extend
return getAllBufferedImages(new ByteSourceFile(file));
}
- // public boolean extractImages(ByteSource byteSource, File dstDir,
- // String dstRoot, ImageParser encoder) throws ImageReadException,
- // IOException, ImageWriteException
- // {
- // List v = getAllBufferedImages(byteSource);
- //
- // if (v == null)
- // return false;
- //
- // for (int i = 0; i < v.size(); i++)
- // {
- // BufferedImage image = (BufferedImage) v.get(i);
- // File file = new File(dstDir, dstRoot + "_" + i
- // + encoder.getDefaultExtension());
- // encoder.writeImage(image, new FileOutputStream(file), null);
- // }
- //
- // return false;
- // }
- //
- // public final boolean extractImages(byte bytes[], File dstDir,
- // String dstRoot, ImageParser encoder)
- //
- // throws ImageReadException, IOException, ImageWriteException
- // {
- // return extractImages(new ByteSourceArray(bytes), dstDir, dstRoot,
- // encoder);
- // }
- //
- // public final boolean extractImages(File file, File dstDir,
- // String dstRoot, ImageParser encoder)
- //
- // throws ImageReadException, IOException, ImageWriteException
- // {
- // if (!canAcceptExtension(file))
- // return false;
- //
- // return extractImages(new ByteSourceFile(file), dstDir, dstRoot,
- // encoder);
- // }
-
+
+ /**
+ * 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 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(byte bytes[], Map 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(File file, Map params)
throws ImageReadException, IOException {
if (!canAcceptExtension(file))
@@ -230,10 +538,27 @@ public abstract class ImageParser extend
return getBufferedImage(new ByteSourceFile(file), params);
}
-
+
+
/**
- * @throws IOException
- * may be thrown by sub-classes
+ * 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(BufferedImage src, OutputStream os, Map params)
throws ImageWriteException, IOException {
@@ -247,22 +572,66 @@ public abstract class ImageParser extend
+ ") 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(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(byte bytes[], Map 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(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(File file, Map params)
throws ImageReadException, IOException {
@@ -272,27 +641,111 @@ public abstract class ImageParser extend
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 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 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(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(byte bytes[], Map 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(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(File file, Map params)
throws ImageReadException, IOException {
if (!canAcceptExtension(file))
@@ -304,14 +757,53 @@ public abstract class ImageParser extend
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 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(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(File file) throws ImageReadException,
IOException {
if (!canAcceptExtension(file))
@@ -323,6 +815,17 @@ public abstract class ImageParser extend
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(ByteSource byteSource)
throws ImageReadException, IOException {
StringWriter sw = new StringWriter();
@@ -336,26 +839,67 @@ public abstract class ImageParser extend
}
/**
- * @throws ImageReadException
- * may be thrown by sub-classes
- * @throws IOException
- * may be thrown by sub-classes
+ * 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(PrintWriter pw, 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(ImageFormat type) {
ImageFormat types[] = getAcceptedTypes();
@@ -365,10 +909,22 @@ public abstract class ImageParser extend
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(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(String filename) {
String exts[] = getAcceptedExtensions();
if (exts == null)
@@ -386,6 +942,15 @@ public abstract class ImageParser extend
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(Map params) {
if (params == null)
return new SimpleBufferedImageFactory();
@@ -399,6 +964,15 @@ public abstract class ImageParser extend
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(Map params) {
if (params == null || !params.containsKey(PARAM_KEY_STRICT))
return false;
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageReadException.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageReadException.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageReadException.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageReadException.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,11 @@
*/
package org.apache.commons.imaging;
+/**
+ * A custom exception thrown when an ImageParser or other utility
+ * encounters a format-violation, non-supported element, or other
+ * condition that renders image data unaccessible.
+ */
public class ImageReadException extends ImagingException {
private static final long serialVersionUID = -1L;
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageWriteException.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageWriteException.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageWriteException.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageWriteException.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,11 @@
*/
package org.apache.commons.imaging;
+/**
+ * A custom exception thrown when an ImageParser or other utility
+ * encounters a format-violation, non-supported element, or other
+ * condition that renders image data unwritable.
+ */
public class ImageWriteException extends ImagingException {
static final long serialVersionUID = -1L;