5029431: (bf) Add absolute bulk put and get methods

[Brian Burkhalter]

> On Feb 11, 2019, at 10:52 AM, Roger Riggs <Roger.Riggs at oracle.com> wrote:
> 
> There are not formatters or providers involved, it is just a method
> to create the exception;  so that a  disambiguating message text can be supplied.

Thanks for clarifying.

> On Feb 11, 2019, at 2:15 AM, Chris Hegarty <chris.hegarty at oracle.com> wrote:
> 
>> The signatures of the first 4 methods look right, the javadoc looks good too. I'm just mulling over the case where there are fewer than `length` bytes between the index and the limit. The relative bulk get/put will throw BufferUnderflowException or BufferOverflowException for these cases. I realize we touched on this in an earlier iteration but looking at it now then I think we need to re-examine that point to decide on the exceptions.
> 
> AFAIK current index / precondition checks regarding a buffer's space
> availability result in Buffer[Under|Over]flowException. Array based
> precondition checks result in IndexOutOfBoundsException. Might be best
> to keep the current model.

The presence of the absolute index into the buffer complicates the situation. In the absolute get() to an array, for example, get(index,$type$[],offset,length) throwing a BufferUnderflowException would make sense for

0 <= index < limit() && index + length > limit(),

but if index < 0 or index > limit() an IOOBE appears more logical. Likewise for put(index,$type$[],offset,length), a BufferOverflowException would work for

0 <= index < limit() && index + length > limit,

but IOOBE again seems more apropos for index < 0 or index > limit(). For any given method where an IOOBE could be thrown for different indexes being out of bounds, then a better disambiguation message as Roger suggested would be helpful. If an IOOBE can be thrown by only one particular index being out of range, then the default checkFromIndexSize() message might be enough. For example, for the code

        byte[] ba = new byte[42];
        bb.put(-1, ba, 0, 42);

the exception

java.lang.IndexOutOfBoundsException: Range [-1, -1 + 42) out of bounds for length 42

is thrown which looks to be sufficient if we know a priori which index is involved.

For the method put(index,$Type$Buffer,offset,length) the BufferUnderflowException would be for ‘src’ not having enough elements to copy to ‘this’ and the BufferOverflowException for ‘this’ not having enough space before limit() to contain the copied elements. Again, either ‘index’ or ‘offset’ being out of range would be better handled by an IOOBE.

Note that using Buffer*flowException would require an update to the specifications of these exceptions as now they are described as being specific to relative operations.

Currently (before this patch) the bounds check is done by java.nio.Buffer.checkBounds(). If we are using Objects.checkFromIndexSize() or Preconditions here it would be good to replace all uses of checkBounds().

Thanks,

Brian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/nio-dev/attachments/20190211/0e0166bf/attachment-0001.html>