-
CSR
-
Resolution: Approved
-
P3
-
None
-
binary, behavioral
-
low
-
-
Java API
-
SE
Summary
Update the specification of methods used in creation of instances of java.awt.image.Raster to accurately describe the reported exceptions in case of incorrect usage.
Problem
Several factory methods for constructing java.awt.image.Raster instances have specifications that do not match behaviours going back to at least JDK 8u. In some cases they are incorrect, in other cases they are incomplete for example where a public API factory method internally chains to another public API factory method and the first is silent on the exceptions that may be thrown by the second. A questionable case is that some methods throw NegativeArraySizeException entirely unintentionally and inconsistently. The specification requires that width and height both be positive otherwise IIllegalArgumentException is thrown. But in some cases if only one is negative NegativeArraySizeException is thrown.
Solution
More completely and accurately specify the exceptions that may be thrown by the API factory methods and constructors involved in the creation of Raster instances. For the greatest part of these do not change behaviour and just document the exceptions. An exception to this to properly check width and height are both positive and if not consistently throw IIllegalArgumentException.
Specification
The changed parts of the specification are as below.
class java.awt.image.Raster
-------------------------
==================================
public static WritableRaster createInterleavedRaster(int dataType,
int w, int h,
int bands,
Point location)
- * @throws RasterFormatException if {@code w} or {@code h}
- * is less than or equal to zero, or computing either
+ * @throws IllegalArgumentException if {@code dataType} is not
+ * one of the supported data types
+ * @throws IllegalArgumentException if {@code bands} is less than 1
+ * @throws IllegalArgumentException if {@code w} and {@code h} are not
+ * both > 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 createInterleavedRaster(int dataType,
int w, int h,
int scanlineStride,
int pixelStride,
int[] bandOffsets,
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 > 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
+ * @throws IllegalArgumentException if {@code scanlineStride}
+ * is less than 0
+ * @throws IllegalArgumentException if {@code pixelStride} is less than 0
+ * @throws NullPointerException if {@code bandOffsets} is null
=================
public static WritableRaster createBandedRaster(int dataType,
int w, int h,
int bands,
Point location)
- * @throws RasterFormatException if {@code w} or {@code h}
- * is less than or equal to zero, or computing either
+ * @throws IllegalArgumentException if {@code dataType} is not
+ * one of the supported data types, which are
+ * {@code DataBuffer.TYPE_BYTE},
+ * {@code DataBuffer.TYPE_USHORT}
+ * or {@code DataBuffer.TYPE_INT}
+ * @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 createBandedRaster(int dataType,
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
- * {@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 IllegalArgumentException if computing either
+ * {@code location.x + w} or
+ * {@code location.y + h} results in integer overflow
+ * @throws IllegalArgumentException if {@code scanlineStride}
+ * is less than 0
* @throws ArrayIndexOutOfBoundsException if {@code bankIndices}
- * or {@code bandOffsets} is {@code null}
+ * is {@code null}
+ * @throws NullPointerException if {@code bandOffsets} is {@code null}
===================
public static WritableRaster createInterleavedRaster(DataBuffer dataBuffer,
int w, int h,
int scanlineStride,
int pixelStride,
int[] bandOffsets,
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 NullPointerException if {@code dataBuffer} is null
+ * @throws IllegalArgumentException if {@code dataType} is not
+ * one of the supported data types, which are
+ * {@code DataBuffer.TYPE_BYTE}, or
+ * {@code DataBuffer.TYPE_USHORT}.
- * @throws NullPointerException if {@code dataBuffer} is null
+ * @throws IllegalArgumentException if {@code w} and {@code h} are not
+ * both > 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
+ * @throws IllegalArgumentException if {@code scanlineStride}
+ * is less than 0
+ * @throws IllegalArgumentException if {@code pixelStride} is less than 0
+ * @throws NullPointerException if {@code bandOffsets} is null
=====================
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
- * {@code location.x + w} or
- * {@code location.y + h} results in integer
- * overflow
+ * @throws NullPointerException if {@code dataBuffer} is null,
+ * or {@code bankIndices} is null, or {@code bandOffsets} is null
* @throws IllegalArgumentException if {@code dataType} is not
* one of the supported data types, which are
* {@code DataBuffer.TYPE_BYTE},
* {@code DataBuffer.TYPE_USHORT}
- * or {@code DataBuffer.TYPE_INT}
- * @throws NullPointerException if {@code dataBuffer} is null
+ * or {@code DataBuffer.TYPE_INT},
+ * or if {@code w} or {@code h} is less than or equal to zero,
+ * or if the product of {@code w} and {@code h} is greater
+ * than {@code Integer.MAX_VALUE}
+ * or if {@code scanlineStride} is less than zero,
+ * or if the length of {@code bankIndices} does not
+ * equal the length of {@code bandOffsets}
+ * @throws RasterFormatException if computing either
+ * {@code location.x + w} or
+ * {@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 IllegalArgumentException if {@code dataType} is not
+ * @throws IllegalArgumentException if {@code dataBuffer} is not
* one of the supported data types, which are
* {@code DataBuffer.TYPE_BYTE},
* {@code DataBuffer.TYPE_USHORT}
* or {@code DataBuffer.TYPE_INT}
=============================
class java.awt.image.SampleModel
---------------------------------
public SampleModel(int dataType, int w, int h, int numBands)
- * @throws IllegalArgumentException if {@code dataType} is not
- * one of the supported data types
+ * @throws IllegalArgumentException if {@code dataType} is not
+ * one of the pre-defined data type tags in the
+ * {@code DataBuffer} class
+ * @throws IllegalArgumentException if {@code numBands} is less than 1
=================================
class java.awt.image.ComponentSampleModel
-----------------------------------------
public ComponentSampleModel(int dataType,
int w, int h,
int pixelStride,
int scanlineStride,
int[] bandOffsets)
- * @throws IllegalArgumentException if {@code w} or
- * {@code h} is not greater than 0
- * @throws IllegalArgumentException if {@code pixelStride}
- * is less than 0
- * @throws IllegalArgumentException if {@code scanlineStride}
- * is less than 0
- * @throws IllegalArgumentException if {@code numBands}
- * is less than 1
+ * @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}
+ * and {@code h} is greater than {@code Integer.MAX_VALUE}
+ * @throws IllegalArgumentException if {@code pixelStride} is less than 0
+ * @throws IllegalArgumentException if {@code scanlineStride} is less than 0
+ * @throws NullPointerException if {@code bandOffsets} is {@code null}
+ * @throws IllegalArgumentException if {@code bandOffsets.length} is 0
* @throws IllegalArgumentException if {@code dataType} is not
- * one of the supported data types
+ * one of the supported data types for this sample model.
====================================
public ComponentSampleModel(int dataType,
int w, int h,
int pixelStride,
int scanlineStride,
int[] bankIndices,
int[] bandOffsets)
- * @throws IllegalArgumentException if {@code w} or
- * {@code h} is not greater than 0
- * @throws IllegalArgumentException if {@code pixelStride}
- * is less than 0
- * @throws IllegalArgumentException if {@code scanlineStride}
- * is less than 0
+ * @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 {@code pixelStride} is less than 0
+ * @throws IllegalArgumentException if {@code scanlineStride} is less than 0
+ * @throws NullPointerException if {@code bankIndices} is {@code null}
+ * @throws NullPointerException if {@code bandOffsets} is {@code null}
+ * @throws IllegalArgumentException if {@code bandOffsets.length} is 0
* @throws IllegalArgumentException if the length of
* {@code bankIndices} does not equal the length of
- * {@code bankOffsets}
+ * {@code bandOffsets}
* @throws IllegalArgumentException if any of the bank indices
* of {@code bandIndices} is less than 0
* @throws IllegalArgumentException if {@code dataType} is not
- * one of the supported data types
+ * one of the supported data types for this sample model
=========================================
class java.awt.image.BandedSampleModel
-----------------------------------------
public BandedSampleModel(int dataType, int w, int h, int numBands)
+ * @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 {@code numBands} is not > 0
* @throws IllegalArgumentException if {@code dataType} is not
- * one of the supported data types
+ * one of the supported data types for this sample model.
================
public BandedSampleModel(int dataType,
int w, int h,
int scanlineStride,
int[] bankIndices,
int[] bandOffsets)
+ * @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 {@code scanlineStride} is less than 0
+ * @throws NullPointerException if {@code bankIndices} is {@code null}
+ * @throws NullPointerException if {@code bandOffsets} is {@code null}
+ * @throws IllegalArgumentException if {@code bandOffsets.length} is 0
+ * @throws IllegalArgumentException if the length of
+ * {@code bankIndices} does not equal the length of
+ * {@code bandOffsets}
+ * @throws IllegalArgumentException if any of the bank indices
+ * of {@code bandIndices} is less than 0
* @throws IllegalArgumentException if {@code dataType} is not
- * one of the supported data types
+ * one of the supported data types for this sample model
====================
- csr of
-
JDK-8255800 Raster creation methods need some specification clean up
-
- Resolved
-