commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dam...@apache.org
Subject svn commit: r1354188 [2/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
Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/Imaging.java Tue Jun 26 19:32:21 2012
@@ -40,52 +40,80 @@ import org.apache.commons.imaging.icc.Ic
 import org.apache.commons.imaging.util.Debug;
 
 /**
- * The primary interface to the Imaging library.
- * <p>
- * Almost all of the Imaging library's core functionality can be accessed
- * through it's methods.
- * <p>
- * All of Imaging's methods are static.
+ * The primary application programming interface (API) to the Imaging library.
  * <p>
+
+ * <h3>Application Notes</h3>
+ * <h4>Using this class</h4>
+ * Almost all of the Apache Commons Imaging library's core functionality can 
+ * be accessed through the methods provided by this class.
+ * The use of the Imaging class is similar to the Java API's ImageIO class,
+ * though Imaging supports formats and options not included in the standard 
+ * Java API. 
+ * <p>All of methods provided by the Imaging class are declared static.
+ * <p>The Apache Commons Imaging package is a pure Java implementation.
+ * <h4>Format support</h4>
+ * While the Apache Commons Imaging package handles a number of different 
+ * graphics formats, support for some formats is not yet complete.
+ * For the most recent information on support for specific formats, refer to
+ * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+ * at the main project development web site.
+ * <h4>Optional parameters for image reading and writing</h4>
+ * Some of the methods provided by this class accept an optional 
+ * <strong>params</strong> argument that permits the application to specify
+ * elements for special handling.  If these specifications are not required by
+ * the application, the params argument may be omitted (as appropriate) or
+ * a null argument may be provided. In image-writing operations, the option 
+ * parameters may include options such as data-compression type (if any), 
+ * color model, or other format-specific data representations.   The parameters 
+ * map may also be used to provide EXIF Tags and other metadata to those
+ * formats that support them. In image-reading operations,
+ * the parameters may include information about special handling in reading
+ * the image data.
+ * <p>Optional parameters are specified using a Map object (typically, 
+ * a Java HashMap) to specify a set of keys and values for input.  
+ * The specification for support keys is provided by the ImagingConstants 
+ * interface as well as by format-specific interfaces such as 
+ * JpegContants or TiffConstants.
+ * <h4>Example code</h4>
  * See the source of the SampleUsage class and other classes in the
  * org.apache.commons.imaging.examples package for examples.
  * 
  * @see <a
  *      href="https://svn.apache.org/repos/asf/commons/proper/imaging/trunk/src/test/java/org/apache/commons/imaging/examples/SampleUsage.java">org.apache.commons.imaging.examples.SampleUsage</a>
+ * @see <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
  */
 public abstract class Imaging implements ImagingConstants {
 
     /**
-     * Tries to guess whether a file contains an image based on its file
-     * extension.
-     * <p>
-     * Returns true if the file has a file extension associated with a file
-     * format, such as .jpg or .gif.
-     * <p>
-     * 
-     * @param file
-     *            File which may contain an image.
-     * @return true if the file has an image format file extension.
+     * Attempts to determine if a file contains an image recorded in 
+     * a supported graphics format based on its file-name extension 
+     * (for example "&#46jpg", "&#46;gif", "&#46;png", etc&#46;). 
+     * 
+     * @param file A valid File object providing a reference to 
+     * a file that may contain an image.
+     * @return true if the file-name includes a supported image 
+     * format file extension; otherwise, false.
      */
     public static boolean hasImageFileExtension(File file) {
-        if (!file.isFile())
+        if (file==null || !file.isFile())
             return false;
         return hasImageFileExtension(file.getName());
     }
 
     /**
-     * Tries to guess whether a filename represents an image based on its file
-     * extension.
-     * <p>
-     * Returns true if the filename has a file extension associated with a file
-     * format, such as .jpg or .gif.
-     * <p>
+     * Attempts to determine if a file contains an image recorded in 
+     * a supported graphics format based on its file-name extension 
+     * (for example "&#46jpg", "&#46;gif", "&#46;png", etc&#46;). 
      * 
-     * @param filename
-     *            String representing name of file which may contain an image.
+     * @param filename  A valid string representing name of file 
+     * which may contain an image.
      * @return true if the filename has an image format file extension.
      */
     public static boolean hasImageFileExtension(String filename) {
+        if(filename==null)
+            return false;
+        
         filename = filename.toLowerCase();
 
         ImageParser imageParsers[] = ImageParser.getAllImageParsers();
@@ -104,15 +132,19 @@ public abstract class Imaging implements
     }
 
     /**
-     * Tries to guess what the image type (if any) of data based on the file's
-     * "magic numbers," the first bytes of the data.
-     * <p>
+     * Attempts to determine the image format of a file based on its
+     * "magic numbers," the first bytes of the data.  
+     * <p>Many graphics format specify identifying byte 
+     * values that appear at the beginning of the data file.  This method
+     * checks for such identifying elements and returns a ImageFormat 
+     * enumeration indicating what it detects. Note that this 
+     * method can return "false positives" in cases where non-image files
+     * begin with the specified byte values.
      * 
-     * @param bytes
-     *            Byte array containing an image file.
+     * @param bytes  Byte array containing an image file.
      * @return An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns
      *         ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be
-     *         guessed.
+     *         determined.
      */
     public static ImageFormat guessFormat(byte bytes[])
             throws ImageReadException, IOException {
@@ -120,15 +152,19 @@ public abstract class Imaging implements
     }
 
     /**
-     * Tries to guess what the image type (if any) of a file based on the file's
-     * "magic numbers," the first bytes of the file.
-     * <p>
+     * Attempts to determine the image format of a file based on its
+     * "magic numbers," the first bytes of the data.  
+     * <p>Many graphics formats specify identifying byte 
+     * values that appear at the beginning of the data file.  This method
+     * checks for such identifying elements and returns a ImageFormat 
+     * enumeration indicating what it detects. Note that this 
+     * method can return "false positives" in cases where non-image files
+     * begin with the specified byte values.
      * 
-     * @param file
-     *            File containing image data.
+     * @param file  File containing image data.
      * @return An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns
      *         ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be
-     *         guessed.
+     *         determined.
      */
     public static ImageFormat guessFormat(File file) throws ImageReadException,
             IOException {
@@ -161,8 +197,32 @@ public abstract class Imaging implements
         return (a[0] == b[0]) && (a[1] == b[1]);
     }
 
+    
+    /**
+     * Attempts to determine the image format of a file based on its
+     * "magic numbers," the first bytes of the data.  
+     * <p>Many graphics formats specify identifying byte 
+     * values that appear at the beginning of the data file.  This method
+     * checks for such identifying elements and returns a ImageFormat 
+     * enumeration indicating what it detects. Note that this 
+     * method can return "false positives" in cases where non-image files
+     * begin with the specified byte values.
+     * 
+     * @param byteSource a valid ByteSource object potentially supplying 
+     * data for an image.
+     * @return An ImageFormat, such as ImageFormat.IMAGE_FORMAT_JPEG. Returns
+     *         ImageFormat.IMAGE_FORMAT_UNKNOWN if the image type cannot be
+     *         determined.
+     * @throws ImageReadException in the event of an unsuccessful 
+     * attempt to read the image data
+     * @throws IOException in the event of an unrecoverable I/O condition.
+     */
     public static ImageFormat guessFormat(ByteSource byteSource)
             throws ImageReadException, IOException {
+        
+        if(byteSource==null)
+            return ImageFormat.IMAGE_FORMAT_UNKNOWN;
+        
         InputStream is = null;
 
         try {
@@ -252,7 +312,7 @@ public abstract class Imaging implements
      * @param bytes
      *            Byte array containing an image file.
      * @return An instance of ICC_Profile or null if the image contains no ICC
-     *         profile..
+     *         profile.
      */
     public static ICC_Profile getICCProfile(byte bytes[])
             throws ImageReadException, IOException {
@@ -267,7 +327,7 @@ public abstract class Imaging implements
      * @param bytes
      *            Byte array containing an image file.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of ICC_Profile or null if the image contains no ICC
      *         profile..
      */
@@ -303,7 +363,7 @@ public abstract class Imaging implements
      * @param filename
      *            Filename associated with image data (optional).
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of ICC_Profile or null if the image contains no ICC
      *         profile..
      */
@@ -335,7 +395,7 @@ public abstract class Imaging implements
      * @param file
      *            File containing image data.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of ICC_Profile or null if the image contains no ICC
      *         profile..
      */
@@ -391,7 +451,7 @@ public abstract class Imaging implements
      * @param bytes
      *            Byte array containing an image file.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return A byte array.
      * @see IccProfileParser
      * @see ICC_Profile
@@ -431,7 +491,7 @@ public abstract class Imaging implements
      * @param file
      *            File containing image data.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return A byte array.
      * @see IccProfileParser
      * @see ICC_Profile
@@ -462,7 +522,7 @@ public abstract class Imaging implements
      * @param bytes
      *            Byte array containing an image file.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of ImageInfo.
      * @see ImageInfo
      */
@@ -527,7 +587,7 @@ public abstract class Imaging implements
      * @param filename
      *            Filename associated with image data (optional).
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of ImageInfo.
      * @see ImageInfo
      */
@@ -567,7 +627,7 @@ public abstract class Imaging implements
      * @param bytes
      *            Byte array containing an image file.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of ImageInfo.
      * @see ImageInfo
      */
@@ -588,7 +648,7 @@ public abstract class Imaging implements
      * @param file
      *            File containing image data.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of ImageInfo.
      * @see ImageInfo
      */
@@ -625,7 +685,7 @@ public abstract class Imaging implements
         return imageInfo;
     }
 
-    private static final ImageParser getImageParser(ByteSource byteSource)
+    private static ImageParser getImageParser(ByteSource byteSource)
             throws ImageReadException, IOException {
         ImageFormat format = guessFormat(byteSource);
         if (!format.equals(ImageFormat.IMAGE_FORMAT_UNKNOWN)) {
@@ -679,7 +739,7 @@ public abstract class Imaging implements
      * @param filename
      *            Filename associated with image data (optional).
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return The width and height of the image.
      */
     public static Dimension getImageSize(InputStream is, String filename,
@@ -707,7 +767,7 @@ public abstract class Imaging implements
      * @param bytes
      *            Byte array containing an image file.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return The width and height of the image.
      */
     public static Dimension getImageSize(byte bytes[], Map params)
@@ -735,7 +795,7 @@ public abstract class Imaging implements
      * @param file
      *            File containing image data.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return The width and height of the image.
      */
     public static Dimension getImageSize(File file, Map params)
@@ -774,7 +834,7 @@ public abstract class Imaging implements
      * @param filename
      *            Filename associated with image data (optional).
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return Xmp Xml as String, if present. Otherwise, returns null.
      */
     public static String getXmpXml(InputStream is, String filename, Map params)
@@ -802,7 +862,7 @@ public abstract class Imaging implements
      * @param bytes
      *            Byte array containing an image file.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return Xmp Xml as String, if present. Otherwise, returns null.
      */
     public static String getXmpXml(byte bytes[], Map params)
@@ -830,7 +890,7 @@ public abstract class Imaging implements
      * @param file
      *            File containing image data.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return Xmp Xml as String, if present. Otherwise, returns null.
      */
     public static String getXmpXml(File file, Map params)
@@ -845,7 +905,7 @@ public abstract class Imaging implements
      * @param byteSource
      *            File containing image data.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return Xmp Xml as String, if present. Otherwise, returns null.
      */
     public static String getXmpXml(ByteSource byteSource, Map params)
@@ -894,7 +954,7 @@ public abstract class Imaging implements
      * @param bytes
      *            Byte array containing an image file.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of IImageMetadata.
      * @see IImageMetadata
      */
@@ -946,7 +1006,7 @@ public abstract class Imaging implements
      * @param filename
      *            Filename associated with image data (optional).
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of IImageMetadata.
      * @see IImageMetadata
      */
@@ -994,7 +1054,7 @@ public abstract class Imaging implements
      * @param file
      *            File containing image data.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @return An instance of IImageMetadata.
      * @see IImageMetadata
      */
@@ -1011,14 +1071,15 @@ public abstract class Imaging implements
     }
 
     /**
-     * Returns a description of the image's structure.
-     * <p>
-     * Useful for exploring format-specific details of image files.
-     * <p>
-     * 
-     * @param bytes
-     *            Byte array containing an image file.
-     * @return A description of the image file's structure.
+     * 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 static String dumpImageFile(byte bytes[]) throws ImageReadException,
             IOException {
@@ -1026,14 +1087,15 @@ public abstract class Imaging implements
     }
 
     /**
-     * Returns a description of the image file's structure.
-     * <p>
-     * Useful for exploring format-specific details of image files.
-     * <p>
-     * 
-     * @param file
-     *            File containing image data.
-     * @return A description of the image file's structure.
+     * 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 static String dumpImageFile(File file) throws ImageReadException,
             IOException {
@@ -1047,11 +1109,31 @@ public abstract class Imaging implements
         return imageParser.dumpImageFile(byteSource);
     }
 
+    /**
+     * Attempts to determine the image format of the specified data and 
+     * evaluates its format compliance.   This method
+     * returns a FormatCompliance object which includes information
+     * about the data's compliance to a specific format.
+     * @param bytes a valid array of bytes containing image data.
+     * @return if successful, a valid FormatCompliance object.
+     * @throws ImageReadException in the event of unreadable data.
+     * @throws IOException in the event of an unrecoverable I/O condition.
+     */
     public static FormatCompliance getFormatCompliance(byte bytes[])
             throws ImageReadException, IOException {
         return getFormatCompliance(new ByteSourceArray(bytes));
     }
 
+    /**
+     * Attempts to determine the image format of the specified data and 
+     * evaluates its format compliance.   This method
+     * returns a FormatCompliance object which includes information
+     * about the data's compliance to a specific format.
+     * @param file valid file containing image data
+     * @return if successful, a valid FormatCompliance object.
+     * @throws ImageReadException in the event of unreadable data.
+     * @throws IOException in the event of an unrecoverable I/O condition.
+     */
     public static FormatCompliance getFormatCompliance(File file)
             throws ImageReadException, IOException {
         return getFormatCompliance(new ByteSourceFile(file));
@@ -1065,17 +1147,15 @@ public abstract class Imaging implements
     }
 
     /**
-     * Returns all images contained in an image.
-     * <p>
-     * Useful for image formats such as GIF and ICO in which a single file may
-     * contain multiple images.
-     * <p>
-     * 
-     * @param is
-     *            InputStream from which to read image data.
-     * @param filename
-     *            Filename associated with image data (optional).
-     * @return A vector of BufferedImages.
+     * Gets all images specified by the InputStream  (some 
+     * formats may include multiple images within a single data source).
+     * @param is A valid InputStream
+     * @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 static List<BufferedImage> getAllBufferedImages(InputStream is,
             String filename) throws ImageReadException, IOException {
@@ -1083,37 +1163,38 @@ public abstract class Imaging implements
     }
 
     /**
-     * Returns all images contained in an image.
-     * <p>
-     * Useful for image formats such as GIF and ICO in which a single file may
-     * contain multiple images.
-     * <p>
-     * 
-     * @param bytes
-     *            Byte array containing an image file.
-     * @return A vector of BufferedImages.
+     * Gets all images specified by the byte array (some 
+     * formats may include multiple images within a single data source).
+     * @param bytes a valid array of bytes
+     * @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 static List<BufferedImage> getAllBufferedImages(byte bytes[])
             throws ImageReadException, IOException {
         return getAllBufferedImages(new ByteSourceArray(bytes));
     }
 
-    /**
-     * Returns all images contained in an image file.
-     * <p>
-     * Useful for image formats such as GIF and ICO in which a single file may
-     * contain multiple images.
-     * <p>
-     * 
-     * @param file
-     *            File containing image data.
-     * @return A vector of BufferedImages.
+   /**
+     * Gets all images specified by the file (some 
+     * formats may include multiple images within a single data source).
+     * @param file A reference to a valid data 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 static List<BufferedImage> getAllBufferedImages(File file)
             throws ImageReadException, IOException {
         return getAllBufferedImages(new ByteSourceFile(file));
     }
 
+    
     private static List<BufferedImage> getAllBufferedImages(
             ByteSource byteSource) throws ImageReadException, IOException {
         ImageParser imageParser = getImageParser(byteSource);
@@ -1121,71 +1202,49 @@ public abstract class Imaging implements
         return imageParser.getAllBufferedImages(byteSource);
     }
 
-    // public static boolean extractImages(byte bytes[], File dstDir,
-    // String dstRoot, ImageParser encoder) throws ImageReadException,
-    // IOException, ImageWriteException
-    // {
-    // return extractImages(new ByteSourceArray(bytes), dstDir, dstRoot,
-    // encoder);
-    // }
-    //
-    // public static boolean extractImages(File file, File dstDir, String
-    // dstRoot,
-    // ImageParser encoder) throws ImageReadException, IOException,
-    // ImageWriteException
-    // {
-    // return extractImages(new ByteSourceFile(file), dstDir, dstRoot, encoder);
-    // }
-    //
-    // public static boolean extractImages(ByteSource byteSource, File dstDir,
-    // String dstRoot, ImageParser encoder) throws ImageReadException,
-    // IOException, ImageWriteException
-    // {
-    // ImageParser imageParser = getImageParser(byteSource);
-    //
-    // return imageParser.extractImages(byteSource, dstDir, dstRoot, encoder);
-    // }
 
     /**
-     * Reads the first image from an InputStream as a BufferedImage.
-     * <p>
-     * (TODO: elaborate here.)
+     * Reads the first image from an InputStream. 
      * <p>
-     * Sanselan can only read image info, metadata and ICC profiles from all
-     * image formats. However, note that the library cannot currently read or
-     * write JPEG image data. PSD (Photoshop) files can only be partially read
-     * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
-     * fully supported.
-     * <p>
-     * 
-     * @param is
-     *            InputStream to read image data from.
-     * @return A BufferedImage.
-     * @see ImagingConstants
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param is a valid ImageStream from which to read data.
+     * @return if successful, a valid buffered image
+     * @throws ImageReadException in the event of a processing error
+     * while reading an image (i.e. a format violation, etc.).
+     * @throws IOException  in the event of an unrecoverable I/O exception.
      */
+
     public static BufferedImage getBufferedImage(InputStream is)
             throws ImageReadException, IOException {
         return getBufferedImage(is, null);
     }
 
+    
+    
     /**
-     * Reads the first image from an InputStream as a BufferedImage.
-     * <p>
-     * (TODO: elaborate here.)
-     * <p>
-     * Sanselan can only read image info, metadata and ICC profiles from all
-     * image formats. However, note that the library cannot currently read or
-     * write JPEG image data. PSD (Photoshop) files can only be partially read
-     * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
-     * fully supported.
-     * <p>
-     * 
-     * @param is
-     *            InputStream to read image data from.
-     * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
-     * @return A BufferedImage.
-     * @see ImagingConstants
+     * Reads the first image from an InputStream 
+     * using data-processing options specified through a parameters
+     * map.  Options may be configured using the ImagingContants 
+     * interface or the various format-specific implementations provided
+     * by this package.
+     * <p>
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param is a valid ImageStream from which to read data.
+     * @param params an optional parameters map specifying options
+     * @return if successful, a valid buffered image
+     * @throws ImageReadException in the event of a processing error
+     * while reading an image (i.e. a format violation, etc.).
+     * @throws IOException  in the event of an unrecoverable I/O exception.
      */
     public static BufferedImage getBufferedImage(InputStream is, Map params)
             throws ImageReadException, IOException {
@@ -1196,97 +1255,103 @@ public abstract class Imaging implements
     }
 
     /**
-     * Reads the first image from an image file as a BufferedImage.
-     * <p>
-     * (TODO: elaborate here.)
-     * <p>
-     * Sanselan can only read image info, metadata and ICC profiles from all
-     * image formats. However, note that the library cannot currently read or
-     * write JPEG image data. PSD (Photoshop) files can only be partially read
-     * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
-     * fully supported.
+     * Reads the first image from a byte array. 
      * <p>
-     * 
-     * @param bytes
-     *            Byte array containing an image file.
-     * @return A BufferedImage.
-     * @see ImagingConstants
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param bytes a valid array of bytes from which to read data.
+     * @return if successful, a valid buffered image
+     * @throws ImageReadException in the event of a processing error
+     * while reading an image (i.e. a format violation, etc.).
+     * @throws IOException  in the event of an unrecoverable I/O exception.
      */
     public static BufferedImage getBufferedImage(byte bytes[])
             throws ImageReadException, IOException {
         return getBufferedImage(new ByteSourceArray(bytes), null);
     }
 
+   
     /**
-     * Reads the first image from an image file as a BufferedImage.
-     * <p>
-     * (TODO: elaborate here.)
-     * <p>
-     * Sanselan can only read image info, metadata and ICC profiles from all
-     * image formats. However, note that the library cannot currently read or
-     * write JPEG image data. PSD (Photoshop) files can only be partially read
-     * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
-     * fully supported.
-     * <p>
-     * 
-     * @param bytes
-     *            Byte array containing an image file.
-     * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
-     * @return A BufferedImage.
-     * @see ImagingConstants
-     */
+     * Reads the first image from a byte array
+     * using data-processing options specified through a parameters
+     * map.  Options may be configured using the ImagingContants 
+     * interface or the various format-specific implementations provided
+     * by this package.
+     * <p>
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param bytes a valid array of bytes from which to read data.
+     * @param params an optional parameters map specifying options.
+     * @return if successful, a valid buffered image
+     * @throws ImageReadException in the event of a processing error
+     * while reading an image (i.e. a format violation, etc.).
+     * @throws IOException  in the event of an unrecoverable I/O exception.
+     */ 
+    
+
     public static BufferedImage getBufferedImage(byte bytes[], Map params)
             throws ImageReadException, IOException {
         return getBufferedImage(new ByteSourceArray(bytes), params);
     }
 
+
+    
+    
     /**
-     * Reads the first image from an image file as a BufferedImage.
-     * <p>
-     * (TODO: elaborate here.)
+     * Reads the first image from a file. 
      * <p>
-     * Sanselan can only read image info, metadata and ICC profiles from all
-     * image formats. However, note that the library cannot currently read or
-     * write JPEG image data. PSD (Photoshop) files can only be partially read
-     * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
-     * fully supported.
-     * <p>
-     * 
-     * @param file
-     *            File containing image data.
-     * @return A BufferedImage.
-     * @see ImagingConstants
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param file a valid reference to a file containing image data.
+     * @return if successful, a valid buffered image
+     * @throws ImageReadException in the event of a processing error
+     * while reading an image (i.e. a format violation, etc.).
+     * @throws IOException  in the event of an unrecoverable I/O exception.
      */
     public static BufferedImage getBufferedImage(File file)
             throws ImageReadException, IOException {
         return getBufferedImage(new ByteSourceFile(file), null);
     }
 
+    
     /**
-     * Reads the first image from an image file as a BufferedImage.
-     * <p>
-     * (TODO: elaborate here.)
-     * <p>
-     * Sanselan can only read image info, metadata and ICC profiles from all
-     * image formats. However, note that the library cannot currently read or
-     * write JPEG image data. PSD (Photoshop) files can only be partially read
-     * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
-     * fully supported.
-     * <p>
-     * 
-     * @param file
-     *            File containing image data.
-     * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
-     * @return A BufferedImage.
-     * @see ImagingConstants
+     * Reads the first image from a file
+     * using data-processing options specified through a parameters
+     * map.  Options may be configured using the ImagingContants 
+     * interface or the various format-specific implementations provided
+     * by this package.
+     * <p>
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param file a valid reference to a file containing image data.
+     * @return if successful, a valid buffered image
+     * @throws ImageReadException in the event of a processing error
+     * while reading an image (i.e. a format violation, etc.).
+     * @throws IOException  in the event of an unrecoverable I/O exception.
      */
     public static BufferedImage getBufferedImage(File file, Map params)
             throws ImageReadException, IOException {
         return getBufferedImage(new ByteSourceFile(file), params);
     }
 
+    
+    
     private static BufferedImage getBufferedImage(ByteSource byteSource,
             Map params) throws ImageReadException, IOException {
         ImageParser imageParser = getImageParser(byteSource);
@@ -1315,9 +1380,35 @@ public abstract class Imaging implements
      * @param format
      *            The ImageFormat to use.
      * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+     *            Map of optional parameters, defined in ImagingConstants.
      * @see ImagingConstants
      */
+    
+    
+
+     /**
+     * Writes the content of a BufferedImage to a file using the specified 
+     * image format.  Specifications for storing the file (such as data compression,
+     * color models, metadata tags, etc.) may be specified using an optional
+     * parameters map. These specifications are defined in the ImagingConstants
+     * interface or in various format-specific implementations.
+     * <p>
+     * Image writing is not supported for all graphics formats.
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param src a valid BufferedImage object
+     * @param file the file to which the output image is to be written
+     * @param format the format in which the output image is to be written
+     * @param params an optional parameters map (nulls permitted)
+     * @throws ImageWriteException in the event of a format violation,
+     * unsupported image format, etc.
+     * @throws IOException in the event of an unrecoverable I/O exception.
+     * @see ImagingConstants
+     */    
     public static void writeImage(BufferedImage src, File file,
             ImageFormat format, Map params) throws ImageWriteException,
             IOException {
@@ -1338,27 +1429,30 @@ public abstract class Imaging implements
         }
     }
 
+    
     /**
-     * Writes a BufferedImage to a byte array.
-     * <p>
-     * (TODO: elaborate here.)
-     * <p>
-     * Sanselan can only read image info, metadata and ICC profiles from all
-     * image formats. However, note that the library cannot currently read or
-     * write JPEG image data. PSD (Photoshop) files can only be partially read
-     * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
-     * fully supported.
-     * <p>
-     * 
-     * @param src
-     *            The BufferedImage to be written.
-     * @param format
-     *            The ImageFormat to use.
-     * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
-     * @return A byte array containing the image file.
+     * Writes the content of a BufferedImage to a byte array using the specified 
+     * image format.  Specifications for storing the file (such as data compression,
+     * color models, metadata tags, etc.) may be specified using an optional
+     * parameters map. These specifications are defined in the ImagingConstants
+     * interface or in various format-specific implementations.
+     * <p>
+     * Image writing is not supported for all graphics formats.
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param src a valid BufferedImage object
+     * @param format the format in which the output image is to be written
+     * @param params an optional parameters map (nulls permitted)
+     * @return if successful, a valid array of bytes.
+     * @throws ImageWriteException in the event of a format violation,
+     * unsupported image format, etc.
+     * @throws IOException in the event of an unrecoverable I/O exception.
      * @see ImagingConstants
-     */
+     */   
     public static byte[] writeImageToBytes(BufferedImage src,
             ImageFormat format, Map params) throws ImageWriteException,
             IOException {
@@ -1369,28 +1463,30 @@ public abstract class Imaging implements
         return os.toByteArray();
     }
 
-    /**
-     * Writes a BufferedImage to an OutputStream.
-     * <p>
-     * (TODO: elaborate here.)
-     * <p>
-     * Sanselan can only read image info, metadata and ICC profiles from all
-     * image formats. However, note that the library cannot currently read or
-     * write JPEG image data. PSD (Photoshop) files can only be partially read
-     * and cannot be written. All other formats (PNG, GIF, TIFF, BMP, etc.) are
-     * fully supported.
-     * <p>
-     * 
-     * @param src
-     *            The BufferedImage to be written.
-     * @param os
-     *            The OutputStream to write to.
-     * @param format
-     *            The ImageFormat to use.
-     * @param params
-     *            Map of optional parameters, defined in SanselanConstants.
+
+     /**
+     * Writes the content of a BufferedImage to an OutputStream using the specified 
+     * image format.  Specifications for storing the file (such as data compression,
+     * color models, metadata tags, etc.) may be specified using an optional
+     * parameters map. These specifications are defined in the ImagingConstants
+     * interface or in various format-specific implementations.
+     * <p>
+     * Image writing is not supported for all graphics formats.
+     * For the most recent information on support for specific formats, refer to
+     * <a href="http://commons.apache.org/imaging/formatsupport.html">Format Support</a>
+     * at the main project development web site.   While the Apache Commons
+     * Imaging package does not fully support all formats, it  can read 
+     * image info, metadata and ICC profiles from all image formats that 
+     * provide this data.
+     * @param src a valid BufferedImage object
+     * @param os the OutputStream to which the output image is to be written
+     * @param format the format in which the output image is to be written
+     * @param params an optional parameters map (nulls permitted)
+     * @throws ImageWriteException in the event of a format violation,
+     * unsupported image format, etc.
+     * @throws IOException in the event of an unrecoverable I/O exception.
      * @see ImagingConstants
-     */
+     */    
     public static void writeImage(BufferedImage src, OutputStream os,
             ImageFormat format, Map params) throws ImageWriteException,
             IOException {

Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingConstants.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,13 @@
  */
 package org.apache.commons.imaging;
 
+/**
+ * Defines constants that may be used in passing options to 
+ * ImageParser read/write implementations, the utility routines
+ * implemented in the Imaging class, and throughout the
+ * Apache Commons Imaging package.  Individual ImageParser 
+ * implementations may define their own format-specific options.
+ */
 public interface ImagingConstants {
     /**
      * Parameter key. Applies to read and write operations.

Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImagingException.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,10 @@
  */
 package org.apache.commons.imaging;
 
+/**
+ * The base class for implementing custom exceptions in the 
+ * Apache Commons Imaging package.
+ */
 public class ImagingException extends Exception {
     private static final long serialVersionUID = -1L;
 

Modified: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java?rev=1354188&r1=1354187&r2=1354188&view=diff
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java (original)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/PixelDensity.java Tue Jun 26 19:32:21 2012
@@ -16,6 +16,10 @@
  */
 package org.apache.commons.imaging;
 
+/**
+ * Used to specify pixel density and physical dimensions when reading or
+ * storing image information.
+ */
 public class PixelDensity {
     private double horizontalDensity;
     private double verticalDensity;

Added: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html?rev=1354188&view=auto
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html (added)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html Tue Jun 26 19:32:21 2012
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Apache Commons Imaging</title>
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+    </head>
+    <body>
+        Provides utility classes that are employed across multiple
+        image formats and sub-packages.
+    </body>
+</html>

Propchange: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/common/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html?rev=1354188&view=auto
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html (added)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html Tue Jun 26 19:32:21 2012
@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Apache Commons Imaging</title>
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+    </head>
+    <body>
+        Provides classes and methods for reading and writing 
+        Tagged Image File Format (TIFF) files.   Tiff files are
+        widely used in applications for which supplemental 
+        metadata is added to images in the form of "tags".
+    </body>
+</html>

Propchange: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/formats/tiff/package.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html
URL: http://svn.apache.org/viewvc/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html?rev=1354188&view=auto
==============================================================================
--- commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html (added)
+++ commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html Tue Jun 26 19:32:21 2012
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Apache Commons Imaging</title>
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+    </head>
+    <body>
+        The main package for Apache Commons Imaging.
+    </body>
+</html>

Propchange: commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/package.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message