Summary

The specifications of Raster.createPackedRaster(..) factory methods is updated to document exceptions and the conditions under which they may be thrown.

Problem

These Raster.createPackedRaster(..) methods do not document all the conditions under which they may throw exceptions. Also 2 overloads each of createInterleavedRaster and createBandedRaster need to be updated as a result of discussions during review and some observations whilst developing the change.

Solution

Update the specification - and ensure that the implementation matches the updated specification.

Specification

class java.awt.image.Raster

       * @throws IllegalArgumentException if {@code scanlineStride}
-      *         is less than 0
-      * @throws IllegalArgumentException if {@code pixelStride} is less than 0
+      *         is less than or equal to 0
+     * @throws IllegalArgumentException if {@code w * pixelStride} is greater
+     *         than {@code scanlineStride}
+     * @throws IllegalArgumentException if the data size need to store all
+     *          lines of the image is greater than {@code Integer.MAX_VALUE}
      */
     public static WritableRaster createInterleavedRaster(int dataType,
                                                          int w, int h,
                                                          int scanlineStride,
                                                          int[] bandOffsets,
                                                          Point location) 

+      * @throws RasterFormatException if {@code dataBuffer} is too small.
+      * @throws IllegalArgumentException if any element of {@code bandOffsets} is greater
+      *         than {@code pixelStride} or the {@code scanlineStride}
       public static WritableRaster createInterleavedRaster(DataBuffer dataBuffer,
                                                          int w, int h,
                                                          int scanlineStride,
                                                          int pixelStride,
                                                          int[] bandOffsets,
                                                          Point location)

+      * @throws IllegalArgumentException if the lengths of {@code bankIndices}
+      *         and {@code bandOffsets} are different.
+     * @throws IllegalArgumentException if the data size need to store all
+     *          lines of a bank of the image is greater than {@code Integer.MAX_VALUE}
      */
     public static WritableRaster createBandedRaster(int dataType,
                                                     int w, int h,
                                                     int scanlineStride,
                                                     int[] bankIndices,
                                                     int[] bandOffsets,
                                                     Point location)

+      * @throws IllegalArgumentException if the lengths of {@code bankIndices}
+      *         and {@code bandOffsets} are different.
+      * @throws ArrayIndexOutOfBoundsException if any element of {@code bankIndices}
+      *         is greater or equal to the number of bands in {@code dataBuffer}    
 public static WritableRaster createBandedRaster(DataBuffer dataBuffer,
                                                     int w, int h,
                                                     int scanlineStride,
                                                     int[] bankIndices,
                                                     int[] bandOffsets,
                                                     Point location)


-     * @throws RasterFormatException if {@code w} or {@code h}
-     *         is less than or equal to zero, or computing either
+     * @throws NullPointerException if {@code bandMasks} is null
+     * @throws IllegalArgumentException if {@code w} and {@code h}
+     *         are not both greater than 0
+     * @throws IllegalArgumentException if the product of {@code w}
+     *         and {@code h} is greater than {@code Integer.MAX_VALUE}
+     * @throws RasterFormatException if computing either
      *         {@code location.x + w} or
-     *         {@code location.y + h} results in integer
-     *         overflow
+     *         {@code location.y + h} results in integer overflow
     public static WritableRaster createPackedRaster(int dataType,
                                                     int w, int h,
                                                     int[] bandMasks,
                                                     Point location)

-     * @throws RasterFormatException if {@code w} or {@code h}
-     *         is less than or equal to zero, or computing either
-     *         {@code location.x + w} or
-     *         {@code location.y + h} results in integer
-     *         overflow
+     * @throws IllegalArgumentException if {@code w} and {@code h}
+     *         are not both greater than 0
+     * @throws IllegalArgumentException if the product of {@code w}
+     *         and {@code h} is greater than {@code Integer.MAX_VALUE}
+     * @throws RasterFormatException if computing either
+     *         {@code location.x + w} or
+     *         {@code location.y + h} results in integer overflow
public static WritableRaster createPackedRaster(int dataType, 
                                                int w, int h,
                                                int bands,
                                                int bitsPerBand,
                                                Point location) 

-     * @throws RasterFormatException if {@code w} or {@code h}
-     *         is less than or equal to zero, or computing either
+     * @throws IllegalArgumentException if {@code w} and {@code h}
+     *         are not both greater than 0
+     * @throws IllegalArgumentException if the product of {@code w}
+     *         and {@code h} is greater than {@code Integer.MAX_VALUE}
+     * @throws IllegalArgumentException if computing either
      *         {@code location.x + w} or
-     *         {@code location.y + h} results in integer
-     *         overflow
+     *         {@code location.y + h} results in integer overflow
 public static WritableRaster createPackedRaster(DataBuffer dataBuffer,
                                                 int w, int h,
                                                 int scanlineStride,
                                                 int[] bandMasks,
                                                 Point location)

-     * @throws RasterFormatException if {@code w} or {@code h}
-     *         is less than or equal to zero, or computing either
+     * @throws IllegalArgumentException if {@code w} and {@code h}
+     *         are not both greater than 0
+     * @throws IllegalArgumentException if the product of {@code w}
+     *         and {@code h} is greater than {@code Integer.MAX_VALUE}
+     * @throws IllegalArgumentException if computing either
+     *         {@code location.x + w} or
+     *         {@code location.y + h} results in integer overflow
+     * @throws RasterFormatException if computing either
      *         {@code location.x + w} or
-     *         {@code location.y + h} results in integer
-     *         overflow
+     *         {@code location.y + h} results in integer overflow
     public static WritableRaster createPackedRaster(DataBuffer dataBuffer,
                                                     int w, int h,
                                                     int bitsPerPixel,
                                                     Point location)