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

[Roger Riggs]

Hi Brian,

Looks like the right shape overall.

I would agree that IOOBE is the right exception for all the parameter 
consistency checks.
But with the different checks, the bare checkBounds method's IOOBE 
exception with
no message will be very uninformative.

Take a look the jdk.internal.util.Preconditions.checkFrom* methods.
At least that would provide a consistent set of exception message formats
and were designed to be inlined and efficient in the checks.

The other options for 3), 4), and 5) is useful convenience methods.

$.02, Roger

On 10/16/2018 01:15 PM, Brian Burkhalter wrote:
> https://bugs.openjdk.java.net/browse/JDK-5029431
> http://cr.openjdk.java.net/~bpb/5029431/webrev.00/
>
> This is a request for comment before proceeding to the complete task (add more methods?, tune the specification, add tests, file CSR).
>
> In the linked patch, two methods are added to the $Type$Buffer classes:
>
> 1) absolute bulk get: $Type$Buffer get(int index, $type$[] dst, int offset, int length)
> 2) absolute bulk put: $Type$Buffer put(int index, $type$[] src, int offset, int length)
>
> Other similar methods proposed to be added are:
>
> 3) $Type$Buffer get(int index, $type$[] dst)
> 4) $Type$Buffer put(int index, $type$[] src)
> 5) $Type$Buffer put(int index, $Type$Buffer src, int offset, int length)
>
> Does this look like an appropriate set of methods overall?
>
> With respect to methods 1 and 2, a question I have concerns the exception(s) which may be thrown. In the patch, an IndexOutOfBoundsException is thrown if there is any inconsistency in the supplied parameters. This is analogous to the absolute get and put methods which handle a single value [1, 2], but is not very precise. One alternative would be instead to specify these exceptions for parameter consistency:
>
> * IllegalArgumentException if index < 0
> * IndexOutOfBoundsException if {dst,src}.length, offset, and length do not meet the preconditions
> * Buffer{Under,Over}flowException for {get,put} if index + length > capacity()
>
> Here throwing an IAE is analogous to the behavior of alignmentOffset() [3], and the other two exceptions are as thrown by the analogous relative bulk get and put methods [4, 5]. One difficulty with using Buffer{Under,Over}flowException for this purpose is that these exceptions are documented as being specific to *relative* get and put operations [6, 7]. Using them in this case would require revising their specifications.
>
> Thanks,
>
> Brian
>
> [1] https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/ByteBuffer.html#get(int)
> [2] https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/ByteBuffer.html#put(int,byte)
> [3] https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/ByteBuffer.html#alignmentOffset(int,int)
> [4] https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/ByteBuffer.html#get(byte%5B%5D,int,int)
> [5] https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/ByteBuffer.html#put(byte%5B%5D,int,int)
> [6] https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/BufferUnderflowException.html
> [7] https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/BufferOverflowException.html

-- 
Thanks, Roger