Added accessor in Java to get vectors as ByteBuffers.

Also cleaned up ByteBuffer usage in general: ByteBuffer.position
now universally indicates the start of a ByteBuffer.

Change-Id: Ic4bfb98f9df9501b8fc82de2c45db7d7311135ac
Tested: on Linux.

java/flatbuffers/FlatBufferBuilder.java

@@ -245,6 +245,7 @@ public class FlatBufferBuilder {
     public void finish(int root_table) {
         prep(minalign, SIZEOF_INT);
         addOffset(root_table);
+        bb.position(space);
     }
 
     public void finish(int root_table, String file_identifier) {
@@ -255,13 +256,20 @@ public class FlatBufferBuilder {
         for (int i = FILE_IDENTIFIER_LENGTH - 1; i >= 0; i--) {
             addByte((byte)file_identifier.charAt(i));
         }
-        addOffset(root_table);
+        finish(root_table);
     }
 
+    // Get the ByteBuffer representing the FlatBuffer. Only call this after you've
+    // called finish(). The actual data starts at the ByteBuffer's current position,
+    // not necessarily at 0.
     public ByteBuffer dataBuffer() { return bb; }
 
-    // The FlatBuffer data doesn't start at offset 0 in the ByteBuffer:
-    public int dataStart() {
+    // The FlatBuffer data doesn't start at offset 0 in the ByteBuffer,
+    // but now the ByteBuffer's position is set to that location upon
+    // finish(). This method should not be needed anymore, but is left
+    // here as private for the moment to document this API change.
+    // It will be removed in the future.
+    private int dataStart() {
         return space;
     }
 
@@ -273,7 +281,7 @@ public class FlatBufferBuilder {
     }
 
     // Utility function for copying a byte array that starts at 0.
-    public byte[] sizedByteArray(){
+    public byte[] sizedByteArray() {
         return sizedByteArray(space, bb.capacity() - space);
     }
 }

java/flatbuffers/Table.java

@@ -38,6 +38,10 @@ public class Table {
   }
 
   // Create a java String from UTF-8 data stored inside the flatbuffer.
+  // This allocates a new string and converts to wide chars upon each access,
+  // which is not very efficient. Instead, each FlatBuffer string also comes with an
+  // accessor based on __vector_as_bytebuffer below, which is much more efficient,
+  // assuming your Java program can handle UTF-8 data directly.
   protected String __string(int offset) {
     offset += bb.getInt(offset);
     if (bb.hasArray()) {
@@ -45,10 +49,11 @@ public class Table {
     } else {
       // We can't access .array(), since the ByteBuffer is read-only.
       // We're forced to make an extra copy:
-      bb.position(offset + SIZEOF_INT);
       byte[] copy = new byte[bb.getInt(offset)];
+      int old_pos = bb.position();
+      bb.position(offset + SIZEOF_INT);
       bb.get(copy);
-      bb.position(0);
+      bb.position(old_pos);
       return new String(copy, 0, copy.length, Charset.forName("UTF-8"));
     }
   }
@@ -66,6 +71,21 @@ public class Table {
     return offset + bb.getInt(offset) + SIZEOF_INT;  // data starts after the length
   }
 
+  // Get a whole vector as a ByteBuffer. This is efficient, since it only allocates a new
+  // bytebuffer object, but does not actually copy the data, it still refers to the same
+  // bytes as the original ByteBuffer.
+  // Also useful with nested FlatBuffers etc.
+  protected ByteBuffer __vector_as_bytebuffer(int vector_offset, int elem_size) {
+    int o = __offset(vector_offset);
+    if (o == 0) return null;
+    int old_pos = bb.position();
+    bb.position(__vector(o));
+    ByteBuffer nbb = bb.slice();
+    bb.position(old_pos);
+    nbb.limit(__vector_len(o) * elem_size);
+    return nbb;
+  }
+
   // Initialize any Table-derived type to point to the union at the given offset.
   protected Table __union(Table t, int offset) {
     offset += bb_pos;
@@ -74,12 +94,12 @@ public class Table {
     return t;
   }
 
-  protected static boolean __has_identifier(ByteBuffer bb, int offset, String ident) {
+  protected static boolean __has_identifier(ByteBuffer bb, String ident) {
     if (ident.length() != FILE_IDENTIFIER_LENGTH)
         throw new AssertionError("FlatBuffers: file identifier must be length " +
                                  FILE_IDENTIFIER_LENGTH);
     for (int i = 0; i < FILE_IDENTIFIER_LENGTH; i++) {
-      if (ident.charAt(i) != (char)bb.get(offset + SIZEOF_INT + i)) return false;
+      if (ident.charAt(i) != (char)bb.get(bb.position() + SIZEOF_INT + i)) return false;
     }
     return true;
   }