Package io.objectbox.tree

Class Tree

java.lang.Object
io.objectbox.tree.Tree
All Implemented Interfaces:
Closeable, AutoCloseable
@Experimental public class Tree extends Object implements Closeable
A higher level tree API operating on branch and leaf nodes. Points to a root branch, can traverse child branches and read and write data in leafs.

Depends on a compatible tree model (entity types), which is matched by type and property names. E.g. names like "DataLeaf.valueString" are fixed and may not be changed. Adding properties to tree types is allowed.

Note there are TWO ways to work with tree data (both ways can be mixed): - Standard ObjectBox entity types with e.g. Box<DataLeaf> - Higher level tree API via this Tree class

To navigate in the tree, you typically start with getRoot(), which returns a Branch. From one branch you can navigate to other branches and also Leafs, which carry data attributes.

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".

If you already know the IDs, you can efficiently access branches, data leaves, and data values directly.

To access any data in the tree, you must use explicit transactions offer by methods such as runInTx(Runnable), runInReadTx(Runnable), callInTx(Callable), or callInReadTx(Callable).

  • Constructor Summary

    Constructors
    Constructor
    Description
    Tree(BoxStore store, long rootId)
    Create a tree instance for the given data-branch root ID.
    Tree(BoxStore store, String uid)
    Create a tree instance for the given meta-branch root uid, or find a singular root if 0 is given.

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T
    callInReadTx(Callable<T> callable)
    Similar to BoxStore.callInReadTx(Callable), but allows Tree functions.
    <T> T
    callInTx(Callable<T> callable)
    Similar to BoxStore.callInReadTx(Callable), but allows Tree functions.
    <T> T
    callInTxNoThrow(Callable<T> callable)
    Wraps any Exception thrown by the callable into a RuntimeException.
    void
    close()
    Cleans up any (native) resources associated with this tree.
    Double
    getDouble(long id)
    Get data value for the given ID or null if no data leaf exists with that ID.
    Long
    getInteger(long id)
    Get data value for the given ID or null if no data leaf exists with that ID.
    Leaf
    getLeaf(long id)
    Get the leaf for the given ID or null if no leaf exists with that ID.
    String
    getPathSeparatorRegex()
    The path separator regex is used to split a string path into individual path names.
    Branch
    getRoot()
    Gets the root of the data tree.
    long
    getRootId()
    The root ID, which the tree was constructed with.
    BoxStore
    getStore()
     
    String
    getString(long id)
    Get data value for the given ID or null if no data leaf exists with that ID.
    long
    put(Leaf leaf)
    Puts (persists) a data leaf (containing a data value).
    long
    putBranch(long parentBranchId, long metaId)
    Put a new (inserts) data branch
    long
    putBranch(long id, long parentBranchId, long metaId, String uid)
    Put a new or existing data branch
    long
    putBranch(long parentBranchId, long metaId, String uid)
    Put a new (inserts) data branch
    long
    putMetaBranch(long id, long parentBranchId, String name)
    Puts (persists) a branch in the metamodel.
    long
    putMetaBranch(long id, long parentBranchId, String name, String description)
    Puts (persists) a branch in the metamodel with an optional description.
    long[]
    putMetaBranches(long parentBranchId, String[] path)
    Puts (persists) several branches in the metamodel from the given parent ID (must be a meta branch).
    long[]
    putMetaBranches(String[] path)
    Puts (persists) several branches in the metamodel to create the given path from the root.
    long
    putMetaLeaf(long id, long parentBranchId, String name, short valueType)
    Puts (persists) a data leaf in the metamodel (describes values).
    long
    putMetaLeaf(long id, long parentBranchId, String name, short valueType, boolean isUnsigned)
    Puts (persists) a data leaf in the metamodel (describes values).
    long
    putMetaLeaf(long id, long parentBranchId, String name, short valueType, boolean isUnsigned, String description)
    Puts (persists) a data leaf in the metamodel (describes values).
    long
    putValue(long parentBranchId, long metaId, double value)
    Puts (inserts) a new data value (using a data leaf).
    long
    putValue(long parentBranchId, long metaId, long value)
    Puts (inserts) a new data value (using a data leaf).
    long
    putValue(long id, long parentBranchId, long metaId, double value)
    Puts (persists) a data value (using a data leaf).
    long
    putValue(long id, long parentBranchId, long metaId, long value)
    Puts (persists) a data value (using a data leaf).
    long
    putValue(long id, long parentBranchId, long metaId, String value)
    Puts (persists) a data value (using a data leaf).
    long
    putValue(long parentBranchId, long metaId, String value)
    Puts (inserts) a new data value (using a data leaf).
    void
    runInReadTx(Runnable runnable)
    Similar to BoxStore.runInReadTx(Runnable), but allows Tree functions.
    void
    runInTx(Runnable runnable)
    Similar to BoxStore.runInTx(Runnable), but allows Tree functions.
    void
    setPathSeparatorRegex(String pathSeparatorRegex)
    E.g.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Tree

      public Tree(BoxStore store, String uid)
      Create a tree instance for the given meta-branch root uid, or find a singular root if 0 is given.

    • Tree

      public Tree(BoxStore store, long rootId)
      Create a tree instance for the given data-branch root ID.

  • Method Details

    • getPathSeparatorRegex

      public String getPathSeparatorRegex()
      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"].

    • setPathSeparatorRegex

      public void setPathSeparatorRegex(String pathSeparatorRegex)
      E.g. use "\\/" to change path strings to "Book/Author"; see getPathSeparatorRegex() for details.

    • getRootId

      public long getRootId()
      The root ID, which the tree was constructed with.

    • getStore

      public BoxStore getStore()

    • getRoot

      public Branch getRoot()
      Gets the root of the data tree.

    • close

      public void close()
      Cleans up any (native) resources associated with this tree.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • runInTx

      public void runInTx(Runnable runnable)
      Similar to BoxStore.runInTx(Runnable), but allows Tree functions.

    • runInReadTx

      public void runInReadTx(Runnable runnable)
      Similar to BoxStore.runInReadTx(Runnable), but allows Tree functions.

    • callInTx

      public <T> T callInTx(Callable<T> callable) throws Exception
      Similar to BoxStore.callInReadTx(Callable), but allows Tree functions.
      Throws:
      Exception

    • callInTxNoThrow

      public <T> T callInTxNoThrow(Callable<T> callable)
      Wraps any Exception thrown by the callable into a RuntimeException.

    • callInReadTx

      public <T> T callInReadTx(Callable<T> callable)
      Similar to BoxStore.callInReadTx(Callable), but allows Tree functions.

    • getLeaf

      @Nullable public Leaf getLeaf(long id)
      Get the leaf for the given ID or null if no leaf exists with that ID.

    • getString

      @Nullable public String getString(long id)
      Get data value for the given ID or null if no data leaf exists with that ID.

    • getInteger

      @Nullable public Long getInteger(long id)
      Get data value for the given ID or null if no data leaf exists with that ID.

    • getDouble

      @Nullable public Double getDouble(long id)
      Get data value for the given ID or null if no data leaf exists with that ID.

    • putMetaBranch

      public long putMetaBranch(long id, long parentBranchId, String name)
      Puts (persists) a branch in the metamodel.

    • putMetaBranch

      public long putMetaBranch(long id, long parentBranchId, String name, @Nullable String description)
      Puts (persists) a branch in the metamodel with an optional description.

    • putMetaBranches

      public long[] putMetaBranches(String[] path)
      Puts (persists) several branches in the metamodel to create the given path from the root.

    • putMetaBranches

      public long[] putMetaBranches(long parentBranchId, String[] path)
      Puts (persists) several branches in the metamodel from the given parent ID (must be a meta branch).

    • putMetaLeaf

      public long putMetaLeaf(long id, long parentBranchId, String name, short valueType)
      Puts (persists) a data leaf in the metamodel (describes values).

    • putMetaLeaf

      public long putMetaLeaf(long id, long parentBranchId, String name, short valueType, boolean isUnsigned)
      Puts (persists) a data leaf in the metamodel (describes values).

    • putMetaLeaf

      public long putMetaLeaf(long id, long parentBranchId, String name, short valueType, boolean isUnsigned, @Nullable String description)
      Puts (persists) a data leaf in the metamodel (describes values).

    • putBranch

      public long putBranch(long id, long parentBranchId, long metaId, @Nullable String uid)
      Put a new or existing data branch

    • putBranch

      public long putBranch(long parentBranchId, long metaId, @Nullable String uid)
      Put a new (inserts) data branch

    • putBranch

      public long putBranch(long parentBranchId, long metaId)
      Put a new (inserts) data branch

    • putValue

      public long putValue(long id, long parentBranchId, long metaId, long value)
      Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
      Parameters:
      id - Existing ID or zero to insert a new data leaf.
      parentBranchId - ID of the data branch, this data value belongs to.
      metaId - ID of the metadata leaf "describing" this data value.
      value - the actual data value.
      Returns:
      the ID of the put data leaf.

    • putValue

      public long putValue(long parentBranchId, long metaId, long value)
      Puts (inserts) a new data value (using a data leaf).
      Parameters:
      parentBranchId - ID of the data branch, this data value belongs to.
      metaId - ID of the metadata leaf "describing" this data value.
      value - the actual data value.
      Returns:
      the ID of the new data leaf.

    • putValue

      public long putValue(long parentBranchId, long metaId, double value)
      Puts (inserts) a new data value (using a data leaf).
      Parameters:
      parentBranchId - ID of the data branch, this data value belongs to.
      metaId - ID of the metadata leaf "describing" this data value.
      value - the actual data value.
      Returns:
      the ID of the new data leaf.

    • putValue

      public long putValue(long id, long parentBranchId, long metaId, double value)
      Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
      Parameters:
      id - Existing ID or zero to insert a new data leaf.
      parentBranchId - ID of the data branch, this data value belongs to.
      metaId - ID of the metadata leaf "describing" this data value.
      value - the actual data value.
      Returns:
      the ID of the put data leaf.

    • putValue

      public long putValue(long id, long parentBranchId, long metaId, String value)
      Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
      Parameters:
      id - Existing ID or zero to insert a new data leaf.
      parentBranchId - ID of the data branch, this data value belongs to.
      metaId - ID of the metadata leaf "describing" this data value.
      value - the actual data value.
      Returns:
      the ID of the put data leaf.

    • putValue

      public long putValue(long parentBranchId, long metaId, String value)
      Puts (inserts) a new data value (using a data leaf).
      Parameters:
      parentBranchId - ID of the data branch, this data value belongs to.
      metaId - ID of the metadata leaf "describing" this data value.
      value - the actual data value.
      Returns:
      the ID of the new data leaf.

    • put

      public long put(Leaf leaf)
      Puts (persists) a data leaf (containing a data value). If a data leaf exists with the same ID, it's overwritten.
      Returns:
      the ID of the put data leaf.