You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by eb...@apache.org on 2013/11/27 16:05:38 UTC
svn commit: r1546060 -
/commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageParser.java
Author: ebourg
Date: Wed Nov 27 15:05:38 2013
New Revision: 1546060
URL: http://svn.apache.org/r1546060
Log:
Formatting
Modified:
commons/proper/imaging/trunk/src/main/java/org/apache/commons/imaging/ImageParser.java
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=1546060&r1=1546059&r2=1546060&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 Wed Nov 27 15:05:38 2013
@@ -57,41 +57,49 @@ import org.apache.commons.imaging.format
* 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
+ * 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
+ * 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
+ * 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 {
+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 ImageParser[] getAllImageParsers() {
@@ -122,17 +130,17 @@ public abstract class ImageParser extend
* 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.
+ * the IImageMetadata interface describing the content extracted
+ * from the source content.
+ * @throws ImageReadException In the event that the the ByteSource
+ * content does not conform to the format of the specific parser
+ * implementation.
+ * @throws IOException In the event of unsuccessful data read operation.
*/
- public final IImageMetadata getMetadata(final ByteSource byteSource)
- throws ImageReadException, IOException {
+ public final IImageMetadata getMetadata(final ByteSource byteSource) throws ImageReadException, IOException {
return getMetadata(byteSource, null);
}
@@ -141,45 +149,45 @@ public abstract class ImageParser extend
* 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
+ * 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
+ * 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).
+ * @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.
+ * the IImageMetadata interface describing the content extracted
+ * from the source content.
+ * @throws ImageReadException In the event that the the ByteSource
+ * content does not conform to the format of the specific parser
+ * implementation.
+ * @throws IOException In the event of unsuccessful data read operation.
*/
public abstract IImageMetadata getMetadata(ByteSource byteSource, Map<String, Object> params)
throws ImageReadException, IOException;
-
-
/**
* Get image metadata from the specified array of bytes. Format-specific
* ImageParser implementations are expected to return a valid
* IImageMetadata object or to throw an ImageReadException if unable
* to process the specified data.
+ *
* @param bytes A valid array of bytes
* @return A valid, potentially subject-matter-specific implementation of
- * the IImageMetadata interface describing the content extracted
- * from the source content.
- * @throws ImageReadException In the event that the the specified
- * content does not conform to the format of the specific parser
- * implementation.
- * @throws IOException In the event of unsuccessful data read operation.
+ * the IImageMetadata interface describing the content extracted
+ * from the source content.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful data read operation.
*/
- public final IImageMetadata getMetadata(final byte[] bytes)
- throws ImageReadException, IOException {
+ public final IImageMetadata getMetadata(final byte[] bytes) throws ImageReadException, IOException {
return getMetadata(bytes, null);
}
@@ -188,47 +196,46 @@ public abstract class ImageParser extend
* 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
+ * 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
+ * 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).
+ *
+ * @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.
+ * from the specified content.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful data read operation.
*/
public final IImageMetadata getMetadata(final byte[] bytes, final Map<String, Object> params)
throws ImageReadException, IOException {
return getMetadata(new ByteSourceArray(bytes), params);
}
-
-
-
/**
* Get image metadata from the specified file. Format-specific
* ImageParser implementations are expected to return a valid
* IImageMetadata object or to throw an ImageReadException if unable
* to process the specified data.
+ *
* @param file A valid reference to a file.
* @return A valid image metadata object describing the content extracted
- * from the specified content.
- * @throws ImageReadException In the event that the the specified
- * content does not conform to the format of the specific parser
- * implementation.
- * @throws IOException In the event of unsuccessful file read or
- * access operation.
+ * from the specified content.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful file read or
+ * access operation.
*/
- public final IImageMetadata getMetadata(final File file)
- throws ImageReadException, IOException {
+ public final IImageMetadata getMetadata(final File file) throws ImageReadException, IOException {
return getMetadata(file, null);
}
@@ -237,23 +244,25 @@ public abstract class ImageParser extend
* 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
+ * 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
+ * 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).
+ *
+ * @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.
+ * from the specified content.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful file read or
+ * access operation.
*/
public final IImageMetadata getMetadata(final File file, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -269,79 +278,75 @@ public abstract class ImageParser extend
return getMetadata(new ByteSourceFile(file), params);
}
-
-
- /**
- * Get image information from the specified ByteSource. Format-specific
+ /**
+ * 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
+ * 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
+ * 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).
+ * @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.
+ * from the specified data.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful data access operation.
*/
public abstract ImageInfo getImageInfo(ByteSource byteSource, Map<String, Object> params)
throws ImageReadException, IOException;
-
-
- /**
+ /**
* Get image information from the specified ByteSource. Format-specific
* ImageParser implementations are expected to return a valid
* ImageInfo object or to throw an ImageReadException if unable
* to process the specified data.
+ *
* @param byteSource A valid ByteSource object
* @return A valid image information object describing the content extracted
- * from the specified data.
- * @throws ImageReadException In the event that the the specified
- * content does not conform to the format of the specific parser
- * implementation.
- * @throws IOException In the event of unsuccessful data
- * access operation.
+ * from the specified data.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful data
+ * access operation.
*/
- public final ImageInfo getImageInfo(final ByteSource byteSource)
- throws ImageReadException, IOException {
+ public final ImageInfo getImageInfo(final ByteSource byteSource) throws ImageReadException, IOException {
return getImageInfo(byteSource, null);
}
-
-
- /**
+ /**
* Get image information from the specified array of bytes. Format-specific
* ImageParser implementations are expected to return a valid
* ImageInfo object or to throw an ImageReadException if unable
* to process the specified data.
* <p>The params argument provides a mechanism for individual
* implementations to pass optional information into the parser.
- * Not all formats will require this capability. Because the
+ * 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
+ * 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).
+ *
+ * @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.
+ * from the specified data.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful data
+ * access operation.
*/
public final ImageInfo getImageInfo(final byte[] bytes, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -355,21 +360,22 @@ public abstract class ImageParser extend
* 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
+ * 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
+ * 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).
+ *
+ * @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.
+ * from the specified data.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful file read or
+ * access operation.
*/
public final ImageInfo getImageInfo(final File file, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -383,44 +389,39 @@ 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
- * may be thrown by sub-classes
+ * @throws ImageReadException may be thrown by sub-classes
+ * @throws IOException may be thrown by sub-classes
*/
public FormatCompliance getFormatCompliance(final ByteSource byteSource)
throws ImageReadException, IOException {
return null;
}
-
/**
* Determines the format compliance of the content of the supplied byte
* array based on rules provided by a specific implementation.
+ *
* @param bytes A valid byte array.
* @return A valid FormatCompliance object.
- * @throws ImageReadException
- * may be thrown by sub-classes
- * @throws IOException
- * may be thrown by sub-classes
+ * @throws ImageReadException may be thrown by sub-classes
+ * @throws IOException may be thrown by sub-classes
*/
public final FormatCompliance getFormatCompliance(final byte[] bytes)
throws ImageReadException, IOException {
return getFormatCompliance(new ByteSourceArray(bytes));
}
-
/**
* Determines the format compliance of the specified file based on
* rules provided by a specific implementation.
+ *
* @param file A valid reference to a file.
* @return A valid format compliance object.
- * @throws ImageReadException
- * may be thrown by sub-classes
- * @throws IOException
- * may be thrown by sub-classes
+ * @throws ImageReadException may be thrown by sub-classes
+ * @throws IOException may be thrown by sub-classes
*/
public final FormatCompliance getFormatCompliance(final File file)
throws ImageReadException, IOException {
@@ -432,15 +433,15 @@ public abstract class ImageParser extend
}
/**
- * Gets all images specified by the byte source (some
+ * 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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public List<BufferedImage> getAllBufferedImages(final ByteSource byteSource)
throws ImageReadException, IOException {
@@ -454,34 +455,33 @@ public abstract class ImageParser extend
}
/**
- * Gets all images specified by the byte array (some
+ * 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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public final List<BufferedImage> getAllBufferedImages(final byte[] bytes)
throws ImageReadException, IOException {
return getAllBufferedImages(new ByteSourceArray(bytes));
}
- /**
- * Gets all images specified by indicated file (some
+ /**
+ * 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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
- public final List<BufferedImage> getAllBufferedImages(final File file)
- throws ImageReadException, IOException {
+ public final List<BufferedImage> getAllBufferedImages(final File file) throws ImageReadException, IOException {
if (!canAcceptExtension(file)) {
return null;
}
@@ -489,39 +489,38 @@ public abstract class ImageParser extend
return getAllBufferedImages(new ByteSourceFile(file));
}
-
- /**
- * Gets a buffered image specified by the byte source (for
+ /**
+ * 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).
+ * @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
- public abstract BufferedImage getBufferedImage(ByteSource byteSource,
- Map<String, Object> params) throws ImageReadException, IOException;
+ public abstract BufferedImage getBufferedImage(ByteSource byteSource, Map<String, Object> params)
+ throws ImageReadException, IOException;
- /**
- * Gets a buffered image specified by the byte array (for
+ /**
+ * 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).
+ *
+ * @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public final BufferedImage getBufferedImage(final byte[] bytes, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -529,19 +528,19 @@ public abstract class ImageParser extend
}
/**
- * Gets a buffered image specified by the indicated file (for
+ * 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).
+ *
+ * @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public final BufferedImage getBufferedImage(final File file, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -551,27 +550,29 @@ public abstract class ImageParser extend
return getBufferedImage(new ByteSourceFile(file), params);
}
-
-
+
+
/**
* Writes the content of a BufferedImage to the specified output
* stream.
+ *
* <p>The params argument provides a mechanism for individual
* implementations to pass optional information into the parser.
* Not all formats will support this capability. Currently,
* some of the parsers do not check for null arguments. So in cases
* where no optional specifications are supported, application
- * code should pass in an empty instance of an implementation of
+ * 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.)
+ *
+ * @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.
+ * cannot handle the input image or invalid params are specified.
+ * @throws IOException In the event of an write error from
+ * the output stream.
*/
public void writeImage(final BufferedImage src, final OutputStream os, final Map<String, Object> params)
throws ImageWriteException, IOException {
@@ -583,30 +584,29 @@ public abstract class ImageParser extend
/**
* 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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
- public final Dimension getImageSize(final byte[] bytes)
- throws ImageReadException, IOException {
+ public final Dimension getImageSize(final byte[] bytes) throws ImageReadException, IOException {
return getImageSize(bytes, null);
}
- /**
+ /**
* Get the size of the image described by the specified byte array.
- * @param bytes A valid byte array.
+ *
+ * @param bytes A valid byte array.
+ * @param params Optional instructions for special-handling or
+ * interpretation of the input data.
* @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public final Dimension getImageSize(final byte[] bytes, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -615,31 +615,29 @@ public abstract class ImageParser extend
/**
* 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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
- public final Dimension getImageSize(final File file) throws ImageReadException,
- IOException {
-
+ public final Dimension getImageSize(final File file) throws ImageReadException, IOException {
return getImageSize(file, null);
}
/**
* Get the size of the image described by the specified file.
- * @param file A valid reference to a file.
+ *
+ * @param file A valid reference to a file.
+ * @param params Optional instructions for special-handling or
+ * interpretation of the input data.
* @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public final Dimension getImageSize(final File file, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -653,56 +651,52 @@ public abstract class ImageParser extend
/**
* Get the size of the image described by the specified ByteSource.
+ *
* @param byteSource A valid reference to a ByteSource.
+ * @param params Optional instructions for special-handling or
+ * interpretation of the input data.
* @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public abstract Dimension getImageSize(ByteSource byteSource, Map<String, Object> params)
throws ImageReadException, IOException;
-
-
+
/**
- * Get a string containing XML-formatted text conforming to the Extensible
+ * 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
+ * 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.
+ * @param params Optional instructions for special-handling or
+ * interpretation of the input data.
+ * @return If XMP metadata is present, a valid string;
+ * if it is not present, 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 String getXmpXml(ByteSource byteSource, Map<String, Object> params)
throws ImageReadException, IOException;
-
-
/**
* Get an array of bytes describing the International Color Consortium (ICC)
* specification for the color space of the image contained in the
* input byte array. Not all formats support ICC profiles.
+ *
* @param bytes A valid array of bytes.
* @return If available, a valid array of bytes; otherwise, a null
- * @throws ImageReadException In the event that the the specified
- * content does not conform to the format of the specific parser
- * implementation.
- * @throws IOException In the event of unsuccessful read or
- * access operation.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
- public final byte[] getICCProfileBytes(final byte[] bytes)
- throws ImageReadException, IOException {
+ public final byte[] getICCProfileBytes(final byte[] bytes) throws ImageReadException, IOException {
return getICCProfileBytes(bytes, null);
}
@@ -710,15 +704,15 @@ public abstract class ImageParser extend
* 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.
+ *
+ * @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public final byte[] getICCProfileBytes(final byte[] bytes, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -729,16 +723,15 @@ public abstract class ImageParser extend
* 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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
- public final byte[] getICCProfileBytes(final File file)
- throws ImageReadException, IOException {
+ public final byte[] getICCProfileBytes(final File file) throws ImageReadException, IOException {
return getICCProfileBytes(file, null);
}
@@ -746,15 +739,15 @@ public abstract class ImageParser extend
* 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.
+ *
+ * @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public final byte[] getICCProfileBytes(final File file, final Map<String, Object> params)
throws ImageReadException, IOException {
@@ -769,55 +762,51 @@ 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.
+ * @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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public abstract byte[] getICCProfileBytes(ByteSource byteSource, Map<String, Object> params)
throws ImageReadException, IOException;
-
/**
* Write the ImageInfo and format-specific information for the image
* content of the specified byte array to a string.
+ *
* @param bytes A valid array of bytes.
* @return A valid string.
- * @throws ImageReadException In the event that the the specified
- * content does not conform to the format of the specific parser
- * implementation.
- * @throws IOException In the event of unsuccessful read or
- * access operation.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
- public final String dumpImageFile(final byte[] bytes) throws ImageReadException,
- IOException {
+ public final String dumpImageFile(final byte[] bytes) throws ImageReadException, IOException {
return dumpImageFile(new ByteSourceArray(bytes));
}
-
+
/**
* Write the ImageInfo and format-specific information for the image
* content of the specified file to a string.
+ *
* @param file A valid file reference.
* @return A valid string.
- * @throws ImageReadException In the event that the the specified
- * content does not conform to the format of the specific parser
- * implementation.
- * @throws IOException In the event of unsuccessful read or
- * access operation.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
- public final String dumpImageFile(final File file) throws ImageReadException,
- IOException {
+ public final String dumpImageFile(final File file) throws ImageReadException, IOException {
if (!canAcceptExtension(file)) {
return null;
}
@@ -829,16 +818,16 @@ 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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public final String dumpImageFile(final ByteSource byteSource)
throws ImageReadException, IOException {
@@ -855,13 +844,13 @@ public abstract class ImageParser extend
/**
* 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.
+ * @throws ImageReadException In the event that the the specified content
+ * does not conform to the format of the specific
+ * parser implementation.
+ * @throws IOException In the event of unsuccessful read or access operation.
*/
public boolean dumpImageFile(final PrintWriter pw, final ByteSource byteSource)
throws ImageReadException, IOException {
@@ -871,6 +860,7 @@ public abstract class ImageParser extend
/**
* Get a descriptive name for the implementation of an ImageParser.
+ *
* @return a valid, subject-matter-specific string.
*/
public abstract String getName();
@@ -879,19 +869,21 @@ public abstract class ImageParser extend
* 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
+ * Get an array of ImageFormat objects describing all accepted types
+ *
* @return A valid array of one or more elements.
*/
protected abstract ImageFormat[] getAcceptedTypes();
@@ -899,7 +891,8 @@ public abstract class ImageParser extend
/**
* Indicates whether the ImageParser implementation can accept
* the specified format
- * @param type An instance of ImageFormat.
+ *
+ * @param type An instance of ImageFormat.
* @return If the parser can accept the format, true; otherwise, false.
*/
public boolean canAcceptType(final ImageFormat type) {
@@ -916,7 +909,8 @@ public abstract class ImageParser extend
/**
* Indicates whether the ImageParser implementation can accept
* the specified file based on its extension.
- * @param file An valid file reference.
+ *
+ * @param file An valid file reference.
* @return If the parser can accept the format, true; otherwise, false.
*/
protected final boolean canAcceptExtension(final File file) {
@@ -926,7 +920,8 @@ public abstract class ImageParser extend
/**
* 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.
+ *
+ * @param filename An valid string giving a file name or file path.
* @return If the parser can accept the format, true; otherwise, false.
*/
protected final boolean canAcceptExtension(final String filename) {
@@ -950,14 +945,13 @@ public abstract class ImageParser extend
return false;
}
-
/**
* Get an instance of IBufferedImageFactory based on the presence
* of a specification for ImagingConstants..BUFFERED_IMAGE_FACTORY
* within the supplied params.
+ *
* @param params A valid Map object, or a null.
- * @return A valid instance of an implementation of a
- * IBufferedImageFactory.
+ * @return A valid instance of an implementation of a IBufferedImageFactory.
*/
protected IBufferedImageFactory getBufferedImageFactory(final Map<String, Object> params) {
if (params == null) {
@@ -979,9 +973,10 @@ public abstract class ImageParser extend
* whether it contains the ImagingConstants.PARAM_KEY_STRICT
* specification. Intended
* for internal use by ImageParser implementations.
+ *
* @param params A valid Map object (or a null).
* @return If the params specify strict format compliance, true;
- * otherwise, false.
+ * otherwise, false.
*/
public static boolean isStrict(final Map<String, Object> params) {
if (params == null || !params.containsKey(PARAM_KEY_STRICT)) {