BufferedImage documentation inconsistent with implementation

[Philip Race]

A BufferedImage is a single always writable Tile.

The method that is most questionable is releaseWritableTile(int, int) 
being a no-op.
It doesn't even throw an AAIOB if you pass in something other than (0,0)
It probably should have a clause

"This method is a no-op and immediately returns without checking the 
passed values
since a BufferedImage has only a single tile which is always writable."

The observer methods could also benefit from doc that observers will 
never be added or
removed (no-op methods) since there will never any events to dispatch.
So there's no point in adding real support for listeners.

I think the doc on isTileWritable is well-intentioned but not well-worded.

-phil


On 4/12/23 3:08 AM, Martin Desruisseaux wrote:
>
> Hello all
>
> BufferedImage implements WritableRenderedImage, but the javadoc of all 
> WritableRenderedImage methods are inconsistent with implementation:
>
>   * getWritableTile(…) said "All registered TileObservers are notified
>     when a tile goes from having no writers to having one writer" but
>     the implementation doesn't do that.
>   * releaseWritableTile(…) said "All registered TileObservers are
>     notified when a tile goes from having one writer to having no
>     writers" but the implementation does nothing.
>   * isTileWritable(…) said "throws ArrayIndexOutOfBoundsException if
>     both tileX and tileY are not equal to 0" but the implementation
>     throws IllegalArgumentException is *either* tileX or tileY is not 0.
>   * addTileObserver(…) and removeTileObserver(…) are no-op, but the
>     javadoc don't said that.
>
> Should the javadoc be updated for saying that most methods are 
> actually no-op, or should the implementation be updated with real 
> support of listeners? Or should BufferedImage be considered as 
> permanently checkout out for writing, in which case the current 
> javadoc is not wrong (except above-cited throws clause) but a note 
> about the "permanently checkout-out" behavior would be helpfui?
>
>     Martin
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/client-libs-dev/attachments/20230413/62ee5130/attachment.htm>