RFR 9: 8065570: (bf spec) ByteBuffer.slice() should make it clear that the initial order is BIG_ENDIAN

[Brian Burkhalter]

This message resuscitates a dormant thread the most recent message of which is

http://mail.openjdk.java.net/pipermail/nio-dev/2014-December/002874.html

On Dec 4, 2014, at 11:27 AM, Brian Burkhalter <brian.burkhalter at oracle.com> wrote:

> On Dec 4, 2014, at 6:09 AM, Alan Bateman <Alan.Bateman at oracle.com> wrote:
> 
>> I think you'll need to dig into inconsistencies before we add any clarifications to the javadoc.
> 
> I concur; I’ll try to run it down. I think in the end it will devolve to one of two outcomes:
> 
> 1) only update the documentation to match the behavior, or
> 2) if the behavior is wrong, correct it and then update the documentation as needed.
> 
>> I assume any issues date back to JDK 1.4 but we need to check that. I don't have time to dig into myself just now but I believe the original intent was that all new buffers be created in BIG_ENDIAN and that view buffers are tied to whatever the order is of the byte buffer that they are created.

After reviewing the pertinent documentation in the java.nio package, it appears clear that the intent of the design was that:

1) all newly created ByteBuffers have BIG_ENDIAN byte order regardless of their mechanism of creation;
2) all newly created view buffers have the byte order of their parent ByteBuffer at the moment of their creation; and
2) all newly created Buffers which are neither ByteBuffers nor view buffers have the byte order of the underlying native hardware.

In the cases of the ByteBuffer instance methods asReadOnlyBuffer(), duplicate() and slice() this leads to the confusing situation that the returned, newly created ByteBuffer may have a different byte order from that of the ByteBuffer from which it was created, specifically when the original ByteBuffer has byte order LITTLE_ENDIAN the new one will have byte order BIG_ENDIAN.

Despite this superficially confusing behavior, it is longstanding, and given that the specification is clear on the matter, the safe approach appears to be to refine the specification of certain methods to state explicitly what the byte order of the returned, newly created Buffer will be. To this end I have an updated review request:

Webrev:	http://cr.openjdk.java.net/~bpb/8065570/webrev.01/
Specdiff:	http://cr.openjdk.java.net/~bpb/8065570/specdiff.01/

The gist of the change is to bring the specification of the byte order into the method documentation in addition to having it in the package and/or class documentation.

Please review at your convenience.

Thanks,

Brian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/nio-dev/attachments/20150713/64dabb9b/attachment-0001.html>