RFR: 8306320: BufferedImage spec needs clarification w.r.t its implementation of the WritableRenderedImage interface [v2]

[Phil Race]

On Thu, 20 Apr 2023 08:48:51 GMT, Martin Desruisseaux <duke at openjdk.org> wrote:

>> `BufferedImage` implements the `WritableRenderedImage` interface. But the Javadoc is copied from `WritableRenderedImage`, while `BufferedImage` does something quite different. In particular, `TileObserver` are ignored. This pull request add `@implSlec` for explaining the default behaviour.
>> 
>> This commit has one specification change in `isTileWritable`: the exception type is changed from `ArrayIndexOutOfBoundsException` to `IllegalArgumentException` for matching the implementation. The logical conditions is also corrected.
>> 
>> This commit contains a trivial code change: `new Point(0,0)` is replaced by `new Point()` for saving a few byte codes.
>
> Martin Desruisseaux has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update documentation for adressing comment on pull requests, with two changes to be discussed:
>   
>   - The "The default implementation" sentence has not yet been removed, for reason discussed on the pull request.
>   - The discussion about (0,0) tile indices mentions the relationship with `getTileMinX()` and `getTileMinY()`.

src/java.desktop/share/classes/java/awt/image/BufferedImage.java line 1569:

> 1567:     /**
> 1568:      * Returns whether or not a tile is currently checked out for writing.
> 1569:      *

I think we need a few words here too -
"The only tile in a {@code BufferedImage} is at (0,0) and it is always writable, so calling this method with (0,0)
will always return {@code true}, and any other coordinate will cause an exception to be thrown".

src/java.desktop/share/classes/java/awt/image/BufferedImage.java line 1593:

> 1591:      * Since a {@code BufferedImage} consists of a single tile,
> 1592:      * and that tile is always checked out for writing, the
> 1593:      * default implementation returns an array of one point.

I'd be happier with "the default implementation" -> "this method".
I did read your notes on subclasses etc but really these methods should have been final so I'd like to make
the documentation reflect that rather than implying that there's an open door to do something else.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/13506#discussion_r1177129499
PR Review Comment: https://git.openjdk.org/jdk/pull/13506#discussion_r1177137083