TreeTest: rename root() to getRoot(), add getRootId(), implement Closeable, add JavaDocs

Author: greenrobot

objectbox-java/src/main/java/io/objectbox/tree/Tree.java

@@ -7,17 +7,31 @@
 import io.objectbox.model.PropertyType;
 
 import javax.annotation.Nullable;
+import java.io.Closeable;
 import java.util.concurrent.Callable;
 
 /**
  * Points to a root branch, can traverse child branches and read and write data in leafs.
+ * <p>
+ * To navigate in the tree, you typically start with {@link #getRoot()}, which returns a {@link Branch}.
+ * From one branch you can navigate to other branches and also {@link Leaf}s, which carry data attributes.
+ * <p>
+ * You can easily navigate the tree by using a path, which is either a string or a string array.
+ * A path refers to the names of the meta tree nodes, e.g. "Book.Author.Name".
+ * <p>
+ * If you already know the IDs, you can efficiently access branches, data leaves, and data values directly.
+ * <p>
+ * To access any data in the tree, you must use explicit transactions offer by methods such as
+ * {@link #runInTx(Runnable)}, {@link #runInReadTx(Runnable)}, {@link #callInTx(Callable)}, or
+ * {@link #callInReadTx(Callable)}.
  */
 @SuppressWarnings("SameParameterValue")
 @Experimental
-public class Tree {
+public class Tree implements Closeable {
 
     private long handle;
     private final BoxStore store;
+    private long rootId;
 
     /**
      * Create a tree instance for the given meta-branch root {@code uid}, or find a singular root if 0 is given.
@@ -36,10 +50,11 @@ public Tree(BoxStore store, String uid) {
     }
 
     /**
-     * Create a tree instance for the given meta-branch root {@code uid}, or find a singular root if 0 is given.
+     * Create a tree instance for the given data-branch root ID.
      */
     public Tree(BoxStore store, long rootId) {
         this.store = store;
+        this.rootId = rootId;
         //noinspection ConstantConditions Nullability annotations are not enforced.
         if (store == null) {
             throw new IllegalArgumentException("store must not be null");
@@ -51,29 +66,51 @@ long getHandle() {
         return handle;
     }
 
+    /**
+     * The root ID, which the tree was constructed with.
+     */
+    public long getRootId() {
+        return rootId;
+    }
+
     public BoxStore getStore() {
         return store;
     }
 
-    public Branch root() {
+    /**
+     * Gets the root of the data tree.
+     */
+    public Branch getRoot() {
         long dataBranchId = nativeGetRootId(handle);
         return new Branch(this, dataBranchId);
     }
 
+    /**
+     * Cleans up any (native) resources associated with this tree.
+     */
     public void close() {
         long handle = this.handle;
         nativeDelete(handle);
         this.handle = 0;
     }
 
+    /**
+     * Similar to {@link BoxStore#runInTx(Runnable)}, but allows Tree functions.
+     */
     public void runInTx(Runnable runnable) {
         store.runInTx(createTxRunnable(runnable));
     }
 
+    /**
+     * Similar to {@link BoxStore#runInReadTx(Runnable)}, but allows Tree functions.
+     */
     public void runInReadTx(Runnable runnable) {
         store.runInReadTx(createTxRunnable(runnable));
     }
 
+    /**
+     * Similar to {@link BoxStore#callInReadTx(Callable)}, but allows Tree functions.
+     */
     public <T> T callInTx(Callable<T> callable) throws Exception {
         return store.callInTx(createTxCallable(callable));
     }
@@ -89,6 +126,9 @@ public <T> T callInTxNoThrow(Callable<T> callable) {
         }
     }
 
+    /**
+     * Similar to {@link BoxStore#callInReadTx(Callable)}, but allows Tree functions.
+     */
     public <T> T callInReadTx(Callable<T> callable) {
         return store.callInReadTx(createTxCallable(callable));
     }
@@ -154,33 +194,54 @@ public Double getDouble(long id) {
         return leaf != null ? leaf.asDouble() : null;
     }
 
+    /**
+     * Puts (persists) a branch in the metamodel.
+     */
     public long putMetaBranch(long id, long parentBranchId, String name) {
         return nativePutMetaBranch(handle, id, parentBranchId, name, null);
     }
 
+    /**
+     * Puts (persists) a branch in the metamodel with an optional description.
+     */
     public long putMetaBranch(long id, long parentBranchId, String name, @Nullable String description) {
         return nativePutMetaBranch(handle, id, parentBranchId, name, description);
     }
 
+    /**
+     * Puts (persists) several branches in the metamodel to create the given path from the root.
+     */
     public long[] putMetaBranches(String[] path) {
         return nativePutMetaBranches(handle, 0, path);
     }
 
+    /**
+     * Puts (persists) several branches in the metamodel from the given parent ID (must be a meta branch).
+     */
     public long[] putMetaBranches(long parentBranchId, String[] path) {
         return nativePutMetaBranches(handle, parentBranchId, path);
     }
 
+    /**
+     * Puts (persists) a data leaf in the metamodel (describes values).
+     */
     public long putMetaLeaf(long id, long parentBranchId, String name, short valueType) {
         return nativePutMetaLeaf(handle, id, parentBranchId, name, valueType, false, null);
     }
 
+    /**
+     * Puts (persists) a data leaf in the metamodel (describes values).
+     */
     public long putMetaLeaf(long id, long parentBranchId, String name, short valueType,
-                     boolean isUnsigned) {
+                            boolean isUnsigned) {
         return nativePutMetaLeaf(handle, id, parentBranchId, name, valueType, isUnsigned, null);
     }
 
+    /**
+     * Puts (persists) a data leaf in the metamodel (describes values).
+     */
     public long putMetaLeaf(long id, long parentBranchId, String name, short valueType,
-                     boolean isUnsigned, @Nullable String description) {
+                            boolean isUnsigned, @Nullable String description) {
         return nativePutMetaLeaf(handle, id, parentBranchId, name, valueType, isUnsigned, description);
     }
 
@@ -205,30 +266,87 @@ public long putBranch(long parentBranchId, long metaId) {
         return nativePutBranch(handle, 0, parentBranchId, metaId, null);
     }
 
+
+    /**
+     * Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
+     *
+     * @param id             Existing ID or zero to insert a new data leaf.
+     * @param parentBranchId ID of the data branch, this data value belongs to.
+     * @param metaId         ID of the metadata leaf "describing" this data value.
+     * @param value          the actual data value.
+     * @return the ID of the put data leaf.
+     */
     public long putValue(long id, long parentBranchId, long metaId, long value) {
         return nativePutValueInteger(handle, id, parentBranchId, metaId, value);
     }
 
+    /**
+     * Puts (inserts) a new data value (using a data leaf).
+     *
+     * @param parentBranchId ID of the data branch, this data value belongs to.
+     * @param metaId         ID of the metadata leaf "describing" this data value.
+     * @param value          the actual data value.
+     * @return the ID of the new data leaf.
+     */
     public long putValue(long parentBranchId, long metaId, long value) {
         return nativePutValueInteger(handle, 0, parentBranchId, metaId, value);
     }
 
+    /**
+     * Puts (inserts) a new data value (using a data leaf).
+     *
+     * @param parentBranchId ID of the data branch, this data value belongs to.
+     * @param metaId         ID of the metadata leaf "describing" this data value.
+     * @param value          the actual data value.
+     * @return the ID of the new data leaf.
+     */
     public long putValue(long parentBranchId, long metaId, double value) {
         return nativePutValueFP(handle, 0, parentBranchId, metaId, value);
     }
 
+    /**
+     * Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
+     *
+     * @param id             Existing ID or zero to insert a new data leaf.
+     * @param parentBranchId ID of the data branch, this data value belongs to.
+     * @param metaId         ID of the metadata leaf "describing" this data value.
+     * @param value          the actual data value.
+     * @return the ID of the put data leaf.
+     */
     public long putValue(long id, long parentBranchId, long metaId, double value) {
         return nativePutValueFP(handle, id, parentBranchId, metaId, value);
     }
 
+    /**
+     * Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
+     *
+     * @param id             Existing ID or zero to insert a new data leaf.
+     * @param parentBranchId ID of the data branch, this data value belongs to.
+     * @param metaId         ID of the metadata leaf "describing" this data value.
+     * @param value          the actual data value.
+     * @return the ID of the put data leaf.
+     */
     public long putValue(long id, long parentBranchId, long metaId, String value) {
         return nativePutValueString(handle, id, parentBranchId, metaId, value);
     }
 
+    /**
+     * Puts (inserts) a new data value (using a data leaf).
+     *
+     * @param parentBranchId ID of the data branch, this data value belongs to.
+     * @param metaId         ID of the metadata leaf "describing" this data value.
+     * @param value          the actual data value.
+     * @return the ID of the new data leaf.
+     */
     public long putValue(long parentBranchId, long metaId, String value) {
         return nativePutValueString(handle, 0, parentBranchId, metaId, value);
     }
 
+    /**
+     * Puts (persists) a data leaf (containing a data value). If a data leaf exists with the same ID, it's overwritten.
+     *
+     * @return the ID of the put data leaf.
+     */
     public long put(Leaf leaf) {
         long id = leaf.getId();
         long parentId = leaf.getParentBranchId();

tests/objectbox-java-test/src/test/java/io/objectbox/tree/TreeTest.java

@@ -33,9 +33,10 @@ public void createTree() {
             return prepTree.putBranch(0, metaBranchIds[0]);  // Library data branch (data tree root)
         });
         tree = new Tree(store, rootId);
-        root = tree.root();
+        root = tree.getRoot();
         this.rootId = root.getId();
         assertNotEquals(0, this.rootId);
+        assertEquals(rootId, tree.getRootId());
         assertEquals(3, metaBranchIds.length);
     }
 
@@ -221,7 +222,7 @@ public void concurrentTxs() throws InterruptedException {
                 } catch (InterruptedException e) {
                     e.printStackTrace();
                 }
-                assertNull(tree.root().branch("Book"));
+                assertNull(tree.getRoot().branch("Book"));
                 readThreadOK.set(true);
             });
         });
@@ -236,7 +237,7 @@ public void concurrentTxs() throws InterruptedException {
                 } catch (InterruptedException e) {
                     e.printStackTrace();
                 }
-                long id = tree.putBranch(tree.root().getId(), metaBranchIds[1]);
+                long id = tree.putBranch(tree.getRoot().getId(), metaBranchIds[1]);
                 bookBranchId.set(id);
             });
         });
@@ -246,7 +247,7 @@ public void concurrentTxs() throws InterruptedException {
             System.out.println("Thread " + Thread.currentThread().getId() + " entered tree TX");
             latch.countDown();
             latch.await();
-            return tree.root().branch("Book");
+            return tree.getRoot().branch("Book");
         };
         Branch branch = tree.callInReadTx(branchCallable);
         assertNull(branch);