RFR 8154556: Use java.nio.ByteOrder instead of boolean value

[Paul Sandoz]

> On 21 Apr 2016, at 16:43, Alan Bateman <Alan.Bateman at oracle.com> wrote:
> 
> 
> 
> On 21/04/2016 15:34, Paul Sandoz wrote:
>> Hi
>> 
>> Please review:
>> 
>>   http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8154556-vh-nio-byteorder/webrev/ <http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8154556-vh-nio-byteorder/webrev/>
>> 
>> This is a small tweak to the VarHandle API. The array and ByteBuffer related factory methods on MethodhHandles now accept a java.no.ByteOrder rather than a boolean value.
>> 
>> Use of java.no.ByteOrder is considered more readable in code that a boolean value, for express big, little or native endianness.
>> 
> The switch the ByteOrder looks okay, just wondering if have to check for null and then adjust @throws NPE in the javadoc too.
> 

I blindly copied the same behaviour from ByteBuffer.order:

/**
 * Modifies this buffer's byte order.
 *
 * @param  bo
 *         The new byte order,
 *         either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
 *         or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}
 *
 * @return  This buffer
 */
public final ByteBuffer order(ByteOrder bo) {
    bigEndian = (bo == ByteOrder.BIG_ENDIAN);
    nativeByteOrder =
        (bigEndian == (Bits.byteOrder() == ByteOrder.BIG_ENDIAN));
    return this;
}

Was that behaviour intentional or an oversight? I am assuming the latter as it’s ambiguous what should happen if a third value, null, is passed.

I updated the webrev in place to throw an NPE.


> BTW: Is there a reason for "throws IllegalArgumentException"? This an unchecked so I assume not needed there (the @throws in the javadoc should be sufficient).
> 

I retained consistency with existing MH factory methods.

Thanks
Paul.