commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dam...@apache.org
Subject svn commit: r1354188 [1/2] - in /commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging: ./ common/ formats/tiff/
Date Tue, 26 Jun 2012 19:32:24 GMT
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>
+ *
+ * &nbsp;&nbsp;&nbsp; "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&#46;) 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.&#46;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&#46;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;
 



Mime
View raw message