RFR: 8377568: DataBuffer constructors and methods do not specify required exceptions

[Alexey Ivanov]

On Tue, 17 Feb 2026 19:17:27 GMT, Phil Race <prr at openjdk.org> wrote:

> This fix updates DataBuffer subclasses to actually adhere to their stated specifications by rejecting certain invalid parameters for constructors and getters and setters.
> A new egression test for each of the constructor and getter/setter cases is supplied.
> 
> No existing regression tests fail with this change, and standard demos work.
> 
> Problems caused by these changes are most likely to occur if the client has a bug such that 
> - a client uses the constructors that accept an array and then supplies a "size" that is greater than the array.
> - a client uses the constructors that accept an array and then supplies a "size" that is less than the array and then uses getter/setters that are within the array but outside the range specified by size. 
> 
> Since very few clients (and just one case in the JDK that I found) even use these array constructors the changes are unlikely to make a difference to clients.
> 
> A CSR will be submitted.

You have to use the `@throws` javadoc tag, `throw` will not work.

Usually, the description of condition where an exception is thrown doesn't have a full stop. Currently, the ending punctuation is inconsistent even within one constructor, for example `public DataBufferByte(byte[][] dataArray, int size)`.

https://github.com/prrace/jdk/blob/2c9edaaad1a7ec66f73703b458ee3684eae886e1/src/java.desktop/share/classes/java/awt/image/DataBufferByte.java#L188-L194

The first has `.`; the second has `,`; the third has `.` where `,` should be and has no `.` at the end.

src/java.desktop/share/classes/java/awt/image/DataBuffer.java line 555:

> 553:             throw new ArrayIndexOutOfBoundsException("Invalid index (bankOffset+i) is " +
> 554:                  "(" + offsets[bank] + " + " + i + ") which is too large for size : " + size);
> 555:         }

Suggestion:

      if ((i + offsets[bank]) >= size) {
          throw new ArrayIndexOutOfBoundsException("Invalid index (bankOffset+i) is " +
                  "(" + offsets[bank] + " + " + i + ") which is too large for size : " + size);
      }

Wrong indentation.

src/java.desktop/share/classes/java/awt/image/DataBufferByte.java line 74:

> 72:      *
> 73:      * @param size The size of the {@code DataBuffer}.
> 74:      * throw IllegalArgumentException if {@code size} is less than zero.

Suggestion:

     * @throws IllegalArgumentException if {@code size} is less than zero

You have to use `@throws` javadoc tag. Usually, `@throws` descriptions don't have a full stop.

https://github.com/openjdk/jdk/blob/4ab05d25c170036cd85155c45e58930fedf614a4/src/java.desktop/share/classes/java/awt/image/DataBuffer.java#L117-L118

src/java.desktop/share/classes/java/awt/image/DataBufferByte.java line 93:

> 91:      * @param numBanks The number of banks in the {@code DataBuffer}.
> 92:      * throw IllegalArgumentException if {@code size} is less than zero,
> 93:      * or {@code numBanks} is less than one

Suggestion:

     * @throws IllegalArgumentException if {@code size} is less than zero,
     *         or {@code numBanks} is less than one

src/java.desktop/share/classes/java/awt/image/DataBufferByte.java line 159:

> 157:      * throw NullPointerException if {@code dataArray} is {@code null}.
> 158:      * throw IllegalArgumentException if {@code size} is less than zero,
> 159:      * or {@code (offset + size)} is greater than the length of {@code dataArray}

Suggestion:

     * @throws NullPointerException if {@code dataArray} is {@code null}
     * @throws IllegalArgumentException if {@code size} is less than zero,
     *         or {@code (offset + size)} is greater than the length of {@code dataArray}

-------------

Changes requested by aivanov (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/29766#pullrequestreview-3816313674
PR Review Comment: https://git.openjdk.org/jdk/pull/29766#discussion_r2819087749
PR Review Comment: https://git.openjdk.org/jdk/pull/29766#discussion_r2819097726
PR Review Comment: https://git.openjdk.org/jdk/pull/29766#discussion_r2819099213
PR Review Comment: https://git.openjdk.org/jdk/pull/29766#discussion_r2819102952