Package io.objectbox.tree

Class Tree

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    @Experimental
public class Tree
extends java.lang.Object
implements java.io.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, java.lang.String uid)
      Create a tree instance for the given meta-branch root uid, or find a singular root if 0 is given.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      <T> T callInReadTx​(java.util.concurrent.Callable<T> callable)
      Similar to BoxStore.callInReadTx(Callable), but allows Tree functions.
      <T> T callInTx​(java.util.concurrent.Callable<T> callable)
      Similar to BoxStore.callInReadTx(Callable), but allows Tree functions.
      <T> T callInTxNoThrow​(java.util.concurrent.Callable<T> callable)
      Wraps any Exception thrown by the callable into a RuntimeException.
      void close()
      Cleans up any (native) resources associated with this tree.
      private <T> java.util.concurrent.Callable<T> createTxCallable​(java.util.concurrent.Callable<T> callable)  
      private java.lang.Runnable createTxRunnable​(java.lang.Runnable runnable)  
      java.lang.Double getDouble​(long id)
      Get data value for the given ID or null if no data leaf exists with that ID.
      (package private) long getHandle()  
      java.lang.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.
      java.lang.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()  
      java.lang.String getString​(long id)
      Get data value for the given ID or null if no data leaf exists with that ID.
      (package private) void nativeClearTransaction​(long handle)  
      (package private) static long nativeCreate​(long store, long rootId)
      Create a (Data)Tree instance for the given meta-branch root, or find a singular root if 0 is given.
      (package private) static long nativeCreateWithUid​(long store, java.lang.String uid)
      Not usable yet; TX is not aligned
      (package private) static void nativeDelete​(long handle)  
      (package private) LeafNode nativeGetLeafById​(long treeHandle, long leafId)  
      (package private) long nativeGetRootId​(long handle)
      Get the root data branch ID.
      (package private) long nativePutBranch​(long treeHandle, long id, long parentBranchId, long metaId, java.lang.String uid)  
      (package private) long nativePutMetaBranch​(long treeHandle, long id, long parentBranchId, java.lang.String name, java.lang.String description)  
      (package private) long[] nativePutMetaBranches​(long treeHandle, long parentBranchId, java.lang.String[] path)  
      (package private) long nativePutMetaLeaf​(long treeHandle, long id, long parentBranchId, java.lang.String name, short valueType, boolean isUnsigned, java.lang.String description)  
      (package private) long nativePutValueFP​(long treeHandle, long id, long parentBranchId, long metaId, double value)  
      (package private) long nativePutValueInteger​(long treeHandle, long id, long parentBranchId, long metaId, long value)  
      (package private) long nativePutValueString​(long treeHandle, long id, long parentBranchId, long metaId, java.lang.String value)  
      (package private) boolean nativeSetTransaction​(long handle, long txHandle)  
      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, java.lang.String uid)
      Put a new or existing data branch
      long putBranch​(long parentBranchId, long metaId, java.lang.String uid)
      Put a new (inserts) data branch
      long putMetaBranch​(long id, long parentBranchId, java.lang.String name)
      Puts (persists) a branch in the metamodel.
      long putMetaBranch​(long id, long parentBranchId, java.lang.String name, java.lang.String description)
      Puts (persists) a branch in the metamodel with an optional description.
      long[] putMetaBranches​(long parentBranchId, java.lang.String[] path)
      Puts (persists) several branches in the metamodel from the given parent ID (must be a meta branch).
      long[] putMetaBranches​(java.lang.String[] path)
      Puts (persists) several branches in the metamodel to create the given path from the root.
      long putMetaLeaf​(long id, long parentBranchId, java.lang.String name, short valueType)
      Puts (persists) a data leaf in the metamodel (describes values).
      long putMetaLeaf​(long id, long parentBranchId, java.lang.String name, short valueType, boolean isUnsigned)
      Puts (persists) a data leaf in the metamodel (describes values).
      long putMetaLeaf​(long id, long parentBranchId, java.lang.String name, short valueType, boolean isUnsigned, java.lang.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, java.lang.String value)
      Puts (persists) a data value (using a data leaf).
      long putValue​(long parentBranchId, long metaId, java.lang.String value)
      Puts (inserts) a new data value (using a data leaf).
      void runInReadTx​(java.lang.Runnable runnable)
      Similar to BoxStore.runInReadTx(Runnable), but allows Tree functions.
      void runInTx​(java.lang.Runnable runnable)
      Similar to BoxStore.runInTx(Runnable), but allows Tree functions.
      void setPathSeparatorRegex​(java.lang.String pathSeparatorRegex)
      E.g.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • handle

        private long handle

      • rootId

        private long rootId

      • pathSeparatorRegex

        private java.lang.String pathSeparatorRegex

    • Constructor Detail

      • Tree

        public Tree​(BoxStore store,
            java.lang.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 Detail

      • getHandle

        long getHandle()

      • getPathSeparatorRegex

        public java.lang.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​(java.lang.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.

      • 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 java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable

      • runInTx

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

      • callInTx

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

      • callInTxNoThrow

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

      • callInReadTx

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

      • createTxRunnable

        private java.lang.Runnable createTxRunnable​(java.lang.Runnable runnable)

      • createTxCallable

        private <T> java.util.concurrent.Callable<T> createTxCallable​(java.util.concurrent.Callable<T> callable)

      • 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 java.lang.String getString​(long id)
        Get data value for the given ID or null if no data leaf exists with that ID.

      • getInteger

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

      • getDouble

        @Nullable
public java.lang.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,
                          java.lang.String name)
        Puts (persists) a branch in the metamodel.

      • putMetaBranch

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

      • putMetaBranches

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

      • putMetaBranches

        public long[] putMetaBranches​(long parentBranchId,
                              java.lang.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,
                        java.lang.String name,
                        short valueType)
        Puts (persists) a data leaf in the metamodel (describes values).

      • putMetaLeaf

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

      • putMetaLeaf

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

      • putBranch

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

      • putBranch

        public long putBranch​(long parentBranchId,
                      long metaId,
                      @Nullable
                      java.lang.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,
                     java.lang.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,
                     java.lang.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.

      • nativeCreate

        static long nativeCreate​(long store,
                         long rootId)
        Create a (Data)Tree instance for the given meta-branch root, or find a singular root if 0 is given.

      • nativeCreateWithUid

        static long nativeCreateWithUid​(long store,
                                java.lang.String uid)
        Not usable yet; TX is not aligned

      • nativeDelete

        static void nativeDelete​(long handle)

      • nativeSetTransaction

        boolean nativeSetTransaction​(long handle,
                             long txHandle)

      • nativeClearTransaction

        void nativeClearTransaction​(long handle)

      • nativeGetRootId

        long nativeGetRootId​(long handle)
        Get the root data branch ID.

      • nativeGetLeafById

        LeafNode nativeGetLeafById​(long treeHandle,
                           long leafId)

      • nativePutMetaBranch

        long nativePutMetaBranch​(long treeHandle,
                         long id,
                         long parentBranchId,
                         java.lang.String name,
                         @Nullable
                         java.lang.String description)

      • nativePutMetaBranches

        long[] nativePutMetaBranches​(long treeHandle,
                             long parentBranchId,
                             java.lang.String[] path)

      • nativePutMetaLeaf

        long nativePutMetaLeaf​(long treeHandle,
                       long id,
                       long parentBranchId,
                       java.lang.String name,
                       short valueType,
                       boolean isUnsigned,
                       @Nullable
                       java.lang.String description)

      • nativePutBranch

        long nativePutBranch​(long treeHandle,
                     long id,
                     long parentBranchId,
                     long metaId,
                     @Nullable
                     java.lang.String uid)

      • nativePutValueInteger

        long nativePutValueInteger​(long treeHandle,
                           long id,
                           long parentBranchId,
                           long metaId,
                           long value)

      • nativePutValueFP

        long nativePutValueFP​(long treeHandle,
                      long id,
                      long parentBranchId,
                      long metaId,
                      double value)

      • nativePutValueString

        long nativePutValueString​(long treeHandle,
                          long id,
                          long parentBranchId,
                          long metaId,
                          @Nullable
                          java.lang.String value)