Tree: add pathSeparatorRegex property, Branch path changes (make path string more prominent), JavaDocs

Author: greenrobot

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

@@ -1,10 +1,13 @@
 package io.objectbox.tree;
 
+import io.objectbox.annotation.apihint.Experimental;
+
 import javax.annotation.Nullable;
 
 /**
  * A branch within a {@link Tree}. May have {@link #branch(String[]) branches} or {@link #leaf(String[]) leaves}.
  */
+@Experimental
 public class Branch {
 
     private final Tree tree;
@@ -24,7 +27,8 @@ public long getId() {
     }
 
     /**
-     * Get the branch when following the given path starting from this branch.
+     * Get the branch following the given path of child branches from this branch.
+     *
      * @return null if no matching tree node was found
      */
     @Nullable
@@ -36,34 +40,31 @@ public Branch branch(String[] path) {
     }
 
     /**
-     * Get the branch attached to this branch with the given name or
-     * if {@code isDotSeparatedPath} the branch when following the path
-     * (e.g. {@code Branch1.Branch2}) starting from this branch.
+     * Get the branch following the given path of child branches from this branch.
+     *
      * @return null if no matching tree node was found
      */
     @Nullable
-    public Branch branch(String nameOrDotPath, boolean isDotSeparatedPath) {
-        checkNameOrDotPath(nameOrDotPath);
-        String[] path;
-        if (isDotSeparatedPath) {
-            path = nameOrDotPath.split("\\.");
-        } else {
-            path = new String[]{nameOrDotPath};
-        }
+    public Branch branch(String pathString) {
+        checkNameOrPath(pathString);
+        String[] path = pathString.split(tree.getPathSeparatorRegex());
         return branch(path);
     }
 
     /**
-     * Get the branch attached to this branch with the given name.
+     * Get the child branch directly attached to this branch with the given name.
+     *
      * @return null if no matching tree node was found
      */
     @Nullable
-    public Branch branch(String name) {
-        return branch(name, false);
+    public Branch branchChild(String name) {
+        String[] path = new String[]{name};
+        return branch(path);
     }
 
     /**
-     * Get the leaf when following the given path starting from this branch.
+     * Get the leaf following the given path of children from this branch.
+     *
      * @return null if no matching tree node was found
      */
     @Nullable
@@ -75,36 +76,33 @@ public Leaf leaf(String[] path) {
     }
 
     /**
-     * Get the leaf attached to this branch with the given name or
-     * if {@code isDotSeparatedPath} the leaf when following the path
-     * (e.g. {@code Branch1.Leaf1}) starting from this branch.
+     * Get the leaf following the given path of children from this branch.
+     *
      * @return null if no matching tree node was found
      */
     @Nullable
-    public Leaf leaf(String nameOrDotPath, boolean isDotSeparatedPath) {
-        checkNameOrDotPath(nameOrDotPath);
-        String[] path;
-        if (isDotSeparatedPath) {
-            path = nameOrDotPath.split("\\.");
-        } else {
-            path = new String[]{nameOrDotPath};
-        }
+    public Leaf leaf(String pathString) {
+        checkNameOrPath(pathString);
+        String[] path = pathString.split(tree.getPathSeparatorRegex());
         return leaf(path);
     }
 
     /**
-     * Get the leaf attached to this branch with the given name.
+     * Get the child leaf directly attached to this branch with the given name.
+     *
      * @return null if no matching tree node was found
      */
     @Nullable
-    public Leaf leaf(String name) {
-        return leaf(name, false);
+    public Leaf leafChild(String name) {
+        checkNameOrPath(name);
+        String[] path = new String[]{name};
+        return leaf(path);
     }
 
-    private void checkNameOrDotPath(String name) {
+    private void checkNameOrPath(String name) {
         //noinspection ConstantConditions Nullability annotations are not enforced.
         if (name == null || name.length() == 0) {
-            throw new IllegalArgumentException("nameOrDotPath must not be null or empty");
+            throw new IllegalArgumentException("name/path must not be null or empty");
         }
     }
 

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

@@ -6,6 +6,10 @@
 import javax.annotation.Nullable;
 import java.nio.charset.StandardCharsets;
 
+/**
+ * A data leaf represents a data value in a {@link Tree} as a child of a {@link Branch}.
+ * Each data value has a specific type, e.g. an int or a String.
+ */
 @Experimental
 public class Leaf {
 
@@ -27,6 +31,7 @@ public long getMetaId() {
         return node.metaId;
     }
 
+    /** See {@link PropertyType} for possible types (not all are used here). */
     public short getValueType() {
         return node.valueType;
     }

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

@@ -32,6 +32,7 @@ public class Tree implements Closeable {
     private long handle;
     private final BoxStore store;
     private long rootId;
+    private String pathSeparatorRegex = "\\.";
 
     /**
      * Create a tree instance for the given meta-branch root {@code uid}, or find a singular root if 0 is given.
@@ -66,6 +67,19 @@ long getHandle() {
         return handle;
     }
 
+    /**
+     * The path separator regex is used to split a string path into individual path names.
+     * Example: with the default separator, e.g. "Book.Author" becomes ["Book", "Author"].
+     */
+    public String getPathSeparatorRegex() {
+        return pathSeparatorRegex;
+    }
+
+    /** E.g. use "\\/" to change path strings to "Book/Author"; see {@link #getPathSeparatorRegex()} for details. */
+    public void setPathSeparatorRegex(String pathSeparatorRegex) {
+        this.pathSeparatorRegex = pathSeparatorRegex;
+    }
+
     /**
      * The root ID, which the tree was constructed with.
      */

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

@@ -124,13 +124,13 @@ public void treePath() {
         });
 
         tree.runInReadTx(() -> {
-            Branch book = root.branch("Book", true);
+            Branch book = root.branch("Book");
             assertNotNull(book);
             // get leaf indirectly by traversing branches
-            Branch author = book.branch("Author");
+            Branch author = book.branchChild("Author");
             assertNotNull(author);
 
-            Leaf name = author.leaf("Name");
+            Leaf name = author.leafChild("Name");
             assertNotNull(name);
             assertEquals("Tolkien", name.getString());
             assertFalse(name.isInt());
@@ -141,18 +141,31 @@ public void treePath() {
             assertEquals(author.getId(), name.getParentBranchId());
             assertEquals(metaLeafIds[0], name.getMetaId());
 
-            Leaf year = author.leaf("Year");
+            Leaf year = author.leafChild("Year");
             assertNotNull(year);
             assertEquals(2021, year.getInt());
 
-            Leaf height = author.leaf("Height");
+            Leaf height = author.leafChild("Height");
             assertNotNull(height);
             assertEquals(12.34, height.getDouble(), 0.0);
 
             // get leaf directly
             Leaf name2 = book.leaf(new String[]{"Author", "Name"});
             assertNotNull(name2);
             assertEquals("Tolkien", name2.getString());
+
+            // get leaf directly via path string
+            name2 = book.leaf("Author.Name");
+            assertNotNull(name2);
+            assertEquals("Tolkien", name2.getString());
+
+            // get leaf directly via path string with another separator
+            assertNull(book.leaf("Author/Name"));
+            tree.setPathSeparatorRegex("\\/");
+            name2 = book.leaf("Author/Name");
+            assertNotNull(name2);
+            assertEquals("Tolkien", name2.getString());
+
         });
     }
 
@@ -162,7 +175,7 @@ public void putValueForExistingLeaf_String() {
             long metaNameId = tree.putMetaLeaf(0, metaBranchIds[0], "Name", PropertyType.String);
             assertNotEquals(0, metaNameId);
             tree.putValue(rootId, metaNameId, "Bookery");
-            Leaf leaf = root.leaf("Name");
+            Leaf leaf = root.leafChild("Name");
             assertNotNull(leaf);
             assertEquals("Bookery", leaf.getString());
 
@@ -176,7 +189,7 @@ public void putValueForExistingLeaf_String() {
         });
 
         tree.runInReadTx(() -> {
-            Leaf name = root.leaf("Name");
+            Leaf name = root.leafChild("Name");
             assertNotNull(name);
             assertEquals("Unseen Library", name.getString());
         });
@@ -188,7 +201,7 @@ public void putValueForExistingLeaf_Int() {
             long metaYearId = tree.putMetaLeaf(0, metaBranchIds[0], "Year", PropertyType.Int);
             assertNotEquals(0, metaYearId);
             tree.putValue(rootId, metaYearId, 1982);
-            Leaf leaf = root.leaf("Year");
+            Leaf leaf = root.leafChild("Year");
             assertNotNull(leaf);
             assertEquals(1982, leaf.getInt());
 
@@ -202,7 +215,7 @@ public void putValueForExistingLeaf_Int() {
         });
 
         tree.runInReadTx(() -> {
-            Leaf year = root.leaf("Year");
+            Leaf year = root.leafChild("Year");
             assertNotNull(year);
             assertEquals(1977, year.getInt());
         });
@@ -222,7 +235,7 @@ public void concurrentTxs() throws InterruptedException {
                 } catch (InterruptedException e) {
                     e.printStackTrace();
                 }
-                assertNull(tree.getRoot().branch("Book"));
+                assertNull(tree.getRoot().branchChild("Book"));
                 readThreadOK.set(true);
             });
         });
@@ -247,7 +260,7 @@ public void concurrentTxs() throws InterruptedException {
             System.out.println("Thread " + Thread.currentThread().getId() + " entered tree TX");
             latch.countDown();
             latch.await();
-            return tree.getRoot().branch("Book");
+            return tree.getRoot().branchChild("Book");
         };
         Branch branch = tree.callInReadTx(branchCallable);
         assertNull(branch);