Summary

Document the exceptions that will be thrown for illegal or incompatible size and other parameters that are passed to BufferedImage constructors.

Problem

java.awt.image.BufferedImage constructors have always thrown a RuntimeException if the parameters specifying size are not legal or not compatible with the image type but this has never been documented.

Solution

Ensure the behaviour is consistent and specify the behaviour to throw IllegalArgumentException.

Specification

class java.awt.image.BufferedImage

      /**
       * Constructs a {@code BufferedImage} of one of the predefined
       * image types.  The {@code ColorSpace} for the image is the
       * default sRGB space.
+      * {@code BufferedImage} is a type that supports only one tile.
+      * The pixels are stored in a {@code DataBuffer}.
+      * A {@code DataBuffer} is a container for one or more banks of
+      * Java primitive arrays so the number of samples that can be
+      * stored are limited by the maximum size of a Java array.
+      * This is at most {@code Integer.MAX_VALUE}.
+      * The number of samples per-pixel for an {@code imageType} affect
+      * the maximum. For example if an image format uses bytes to store
+      * separately each of the four samples in an ARGB pixel format image,
+      * it will only be able to hold one fourth as many pixels as an image
+      * that uses an int to store all four samples.
+      * For example {@code TYPE_4BYTE_ABGR} may use 4 bytes to store a pixel
+      * whereas {@code TYPE_INT_ARGB} may use a single int.
+      * So the maximum number of pixels in a {@code BufferedImage} is
+      * format dependent.
       * @param width     width of the created image
       * @param height    height of the created image
       * @param imageType type of the created image
+      * @throws IllegalArgumentException if {@code width} or {@code height} is
+      *          not greater than zero.
+      * @throws IllegalArgumentException if the multiplication product of
+      *          {@code width}, {@code height}, and the number of samples per pixel
+      *          for the specified format exceeds the maximum length of a Java array.
+      * @throws IllegalArgumentException if the {@code imageType} is not one of
+      *         the pre-defined recognized image types.
public BufferedImage(int width,
                      int height,
                      int imageType)


+      * @throws IllegalArgumentException if {@code width} or {@code height} is
+      *          not greater than zero.
+      * @throws IllegalArgumentException if the multiplication product of
+      *          {@code width} and {@code height}
+      *          exceeds the maximum length of a Java array.
public BufferedImage (int width,
                       int height,
                       int imageType,
                       IndexColorModel cm);

+      * @throws IllegalArgumentException if {@code width} or {@code height} is
+      *          not greater than zero.
+      * @throws IllegalArgumentException if the multiplication product of
+      *          {@code width} and {@code height}
+      *          exceeds the maximum length of a Java array.
public BufferedImage (ColorModel cm,
                       WritableRaster raster,
                       boolean isRasterPremultiplied,
                       Hashtable properties);