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

[Brian Burkhalter]

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