JAVA-2300: add conversions of ObjectId to/from java.nio.ByteBuffer

Add conversions to/from java.nio.ByteBuffer via the new putToByteBuffer method and a new
constructor. This is useful for users who want to avoid the GC overhead of allocating a
byte array when serializing an ObjectId to bytes.

Author: Tom Dyas

bson/src/main/org/bson/types/ObjectId.java

@@ -244,17 +244,10 @@ public ObjectId(final String hexString) {
      * @throws IllegalArgumentException if array is null or not of length 12
      */
     public ObjectId(final byte[] bytes) {
-        if (bytes == null) {
-            throw new IllegalArgumentException();
-        }
-        if (bytes.length != 12) {
-            throw new IllegalArgumentException("need 12 bytes");
-        }
-
-        timestamp = makeInt(bytes[0], bytes[1], bytes[2], bytes[3]);
-        machineIdentifier = makeInt((byte) 0, bytes[4], bytes[5], bytes[6]);
-        processIdentifier = (short) makeInt((byte) 0, (byte) 0, bytes[7], bytes[8]);
-        counter = makeInt((byte) 0, bytes[9], bytes[10], bytes[11]);
+        // This null check allows the delegate constructor to throw the expected IllegalArgumentException.
+        // (ByteBuffer.wrap throws NullPointerException if bytes is null, which violates ObjectId's contract
+        // to callers.)
+        this(bytes != null ? ByteBuffer.wrap(bytes) : null);
     }
 
     /**
@@ -268,6 +261,28 @@ public ObjectId(final byte[] bytes) {
         this(legacyToBytes(timestamp, machineAndProcessIdentifier, counter));
     }
 
+    /**
+     * Constructs a new instance from the given ByteBuffer
+     *
+     * @param buffer the ByteBuffer
+     * @throws IllegalArgumentException if the buffer is null or does not have at least 12 bytes remaining
+     */
+    public ObjectId(final ByteBuffer buffer) {
+        if (buffer == null) {
+            throw new IllegalArgumentException();
+        }
+        if (buffer.remaining() < 12) {
+            throw new IllegalArgumentException("need 12 bytes");
+        }
+
+        // Note: Cannot use ByteBuffer.getInt because it depends on tbe buffer's byte order
+        // and ObjectId's are always in big-endian order.
+        timestamp = makeInt(buffer.get(), buffer.get(), buffer.get(), buffer.get());
+        machineIdentifier = makeInt((byte) 0, buffer.get(), buffer.get(), buffer.get());
+        processIdentifier = (short) makeInt((byte) 0, (byte) 0, buffer.get(), buffer.get());
+        counter = makeInt((byte) 0, buffer.get(), buffer.get(), buffer.get());
+    }
+
     private static byte[] legacyToBytes(final int timestamp, final int machineAndProcessIdentifier, final int counter) {
         byte[] bytes = new byte[12];
         bytes[0] = int3(timestamp);
@@ -291,22 +306,40 @@ private static byte[] legacyToBytes(final int timestamp, final int machineAndPro
      * @return the byte array
      */
     public byte[] toByteArray() {
-        byte[] bytes = new byte[12];
-        bytes[0] = int3(timestamp);
-        bytes[1] = int2(timestamp);
-        bytes[2] = int1(timestamp);
-        bytes[3] = int0(timestamp);
-        bytes[4] = int2(machineIdentifier);
-        bytes[5] = int1(machineIdentifier);
-        bytes[6] = int0(machineIdentifier);
-        bytes[7] = short1(processIdentifier);
-        bytes[8] = short0(processIdentifier);
-        bytes[9] = int2(counter);
-        bytes[10] = int1(counter);
-        bytes[11] = int0(counter);
-        return bytes;
+        ByteBuffer buffer = ByteBuffer.allocate(12);
+        putToByteBuffer(buffer);
+        return buffer.array();  // using .allocate ensures there is a backing array that can be returned
     }
 
+    /**
+      * Convert to bytes and put those bytes to the provided ByteBuffer.
+      * Note that the numbers are stored in big-endian order.
+      *
+      * @param buffer the ByteBuffer
+      * @throws IllegalArgumentException if the buffer is null or does not have at least 12 bytes remaining
+      */
+    public void putToByteBuffer(final ByteBuffer buffer) {
+        if (buffer == null) {
+            throw new IllegalArgumentException();
+        }
+        if (buffer.remaining() < 12) {
+            throw new IllegalArgumentException("need 12 bytes");
+        }
+
+        buffer.put(int3(timestamp));
+        buffer.put(int2(timestamp));
+        buffer.put(int1(timestamp));
+        buffer.put(int0(timestamp));
+        buffer.put(int2(machineIdentifier));
+        buffer.put(int1(machineIdentifier));
+        buffer.put(int0(machineIdentifier));
+        buffer.put(short1(processIdentifier));
+        buffer.put(short0(processIdentifier));
+        buffer.put(int2(counter));
+        buffer.put(int1(counter));
+        buffer.put(int0(counter));
+   }
+
     /**
      * Gets the timestamp (number of seconds since the Unix epoch).
      *

bson/src/test/unit/org/bson/types/ObjectIdTest.java

@@ -20,29 +20,44 @@
 
 import java.util.Date;
 import java.util.Random;
+import java.nio.ByteBuffer;
 
 import static org.junit.Assert.assertArrayEquals;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertTrue;
 
 public class ObjectIdTest {
     @Test
-    public void testToByteArray() {
+    public void testToBytes() {
         ObjectId objectId = new ObjectId(0x5106FC9A, 0x00BC8237, (short) 0x5581, 0x0036D289);
-        assertArrayEquals(new byte[]{81, 6, -4, -102, -68, -126, 55, 85, -127, 54, -46, -119}, objectId.toByteArray());
+        byte[] expectedBytes = new byte[]{81, 6, -4, -102, -68, -126, 55, 85, -127, 54, -46, -119};
+
+        assertArrayEquals(expectedBytes, objectId.toByteArray());
+
+        ByteBuffer buffer = ByteBuffer.allocate(12);
+        objectId.putToByteBuffer(buffer);
+        assertArrayEquals(expectedBytes, buffer.array());
     }
 
     @Test
-    public void testFromByteArray() {
-        ObjectId objectId = new ObjectId(new byte[]{81, 6, -4, -102, -68, -126, 55, 85, -127, 54, -46, -119});
-        assertEquals(0x5106FC9A, objectId.getTimestamp());
-        assertEquals(0x00BC8237, objectId.getMachineIdentifier());
-        assertEquals((short) 0x5581, objectId.getProcessIdentifier());
-        assertEquals(0x0036D289, objectId.getCounter());
+    public void testFromBytes() {
+        byte[] bytes = new byte[]{81, 6, -4, -102, -68, -126, 55, 85, -127, 54, -46, -119};
+
+        ObjectId objectId1 = new ObjectId(bytes);
+        assertEquals(0x5106FC9A, objectId1.getTimestamp());
+        assertEquals(0x00BC8237, objectId1.getMachineIdentifier());
+        assertEquals((short) 0x5581, objectId1.getProcessIdentifier());
+        assertEquals(0x0036D289, objectId1.getCounter());
+
+        ObjectId objectId2 = new ObjectId(ByteBuffer.wrap(bytes));
+        assertEquals(0x5106FC9A, objectId2.getTimestamp());
+        assertEquals(0x00BC8237, objectId2.getMachineIdentifier());
+        assertEquals((short) 0x5581, objectId2.getProcessIdentifier());
+        assertEquals(0x0036D289, objectId2.getCounter());
     }
 
     @Test
-    public void testBytes() {
+    public void testBytesRoundtrip() {
         ObjectId expected = new ObjectId();
         ObjectId actual = new ObjectId(expected.toByteArray());
         assertEquals(expected, actual);