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

Field Summary

Fields

Modifier and Type	Field	Description
private long	handle
private String	pathSeparatorRegex
private long	rootId
private final BoxStore	store

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.
private <T> Callable<T>	createTxCallable(Callable<T> callable)
private Runnable	createTxRunnable(Runnable runnable)
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()
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.
(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, 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, String uid)
(package private) long	nativePutMetaBranch(long treeHandle, long id, long parentBranchId, String name, String description)
(package private) long[]	nativePutMetaBranches(long treeHandle, long parentBranchId, String[] path)
(package private) long	nativePutMetaLeaf(long treeHandle, long id, long parentBranchId, String name, short valueType, boolean isUnsigned, 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, 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, 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

Field Details

handle

private long handle

store

private final BoxStore store

rootId

private long rootId

pathSeparatorRegex

private String pathSeparatorRegex

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

getHandle

long getHandle()

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.

createTxRunnable

private Runnable createTxRunnable(Runnable runnable)

createTxCallable

private <T> Callable<T> createTxCallable(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 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.

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,
 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,
 String name,
 @Nullable
 String description)

nativePutMetaBranches

long[] nativePutMetaBranches(long treeHandle,
 long parentBranchId,
 String[] path)

nativePutMetaLeaf

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

nativePutBranch

long nativePutBranch(long treeHandle,
 long id,
 long parentBranchId,
 long metaId,
 @Nullable
 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
 String value)