obx::TreeCursor Class Reference

Primary tree interface against the database. Offers tree path based get/put functionality. Not-thread safe: use a TreeCursor instance from one thread only; i.e. the underlying transaction is bound to a thread. More...

#include <objectbox.hpp>

Public Member Functions
	TreeCursor (Tree &tree, Transaction *tx)
	TreeCursor (Tree &tree, Transaction &tx)
	TreeCursor (TreeCursor &&source) noexcept
	Move constructor "stealing" the C resource from the source. More...
	~TreeCursor ()
	TreeCursor (const TreeCursor &)=delete
	Can't be copied, single owner of C resources is required (to avoid double-free during destruction) More...
void	setTransaction (Transaction *tx)
	Sets or clears a transaction from the tree cursor. More...
void	setTransaction (Transaction &tx)
bool	get (const char *path, const void **data, size_t *size, const void **metadata=nullptr, size_t *metadataSize=nullptr)
	A "low-level" get operation to access a tree leaf using the raw FlatBuffer bytes stored in the database. As usual, the data is only valid during the lifetime of the transaction and before the first write to the DB. An advantage of using "raw" operations is that custom properties can be passed in the FlatBuffer. More...
const char *	getLeafPathCString (obx_id leafId)
	Gets the full path (from the root) of the given leaf ID (allocated C string version). More...
std::string	getLeafPath (obx_id leafId)
	Gets the full path (from the root) of the given leaf ID (allocated C string version). More...
LeavesInfo	getLeavesInfo (const char *path=nullptr)
	Given an existing path, return all existing leaves with their paths. As this traverses the data tree (i.e. not the meta tree), it will only return nodes that exist (obviously). Thus, the meta tree may contain additional paths, but these are unused by the data tree (currently at least). More...
LeavesInfo	getLeavesInfo (const std::string &path)
TreePutResult	put (const char *path, void *data, size_t size, OBXPropertyType type, obx_id *outId=nullptr, void *metadata=nullptr, size_t metadata_size=0, OBXPutMode dataPutMode=OBXPutMode_PUT)
	A "low-level" put operation for a tree leaf using given raw FlatBuffer bytes. Any non-existing branches and meta nodes are put on the fly if an optional meta-leaf FlatBuffers is given. A typical usage pattern is to first try without the meta-leaf, and if it does not work, create the meta-leaf and call again with the meta leaf. This approach takes into account that meta-leaves typically exist, and thus no resources are wasted for meta-leaf creation if it's not required. An advantage of using "raw" operations is that custom properties can be passed in the FlatBuffers. More...
size_t	consolidateNodeConflicts ()
	Explicitly consolidates tree node conflicts (non unique nodes sharing a common path). See also Tree::consolidateNodeConflictsAsync() for an asynchronous version. More...

Detailed Description

Primary tree interface against the database. Offers tree path based get/put functionality. Not-thread safe: use a TreeCursor instance from one thread only; i.e. the underlying transaction is bound to a thread.

Constructor & Destructor Documentation

TreeCursor() [1/4]

obx::TreeCursor::TreeCursor ( Tree &  tree, Transaction *  tx  )

inline

TreeCursor() [2/4]

obx::TreeCursor::TreeCursor ( Tree &  tree, Transaction &  tx  )

inline

TreeCursor() [3/4]

obx::TreeCursor::TreeCursor ( TreeCursor &&  source )

inlinenoexcept

Move constructor "stealing" the C resource from the source.

~TreeCursor()

obx::TreeCursor::~TreeCursor ( )

inline

TreeCursor() [4/4]

obx::TreeCursor::TreeCursor ( const TreeCursor &  )

delete

Can't be copied, single owner of C resources is required (to avoid double-free during destruction)

Member Function Documentation

consolidateNodeConflicts()

size_t obx::TreeCursor::consolidateNodeConflicts ( )

inline

Explicitly consolidates tree node conflicts (non unique nodes sharing a common path). See also Tree::consolidateNodeConflictsAsync() for an asynchronous version.

get()

bool obx::TreeCursor::get ( const char *  path, const void **  data, size_t *  size, const void **  metadata = nullptr, size_t *  metadataSize = nullptr  )

inline

A "low-level" get operation to access a tree leaf using the raw FlatBuffer bytes stored in the database. As usual, the data is only valid during the lifetime of the transaction and before the first write to the DB. An advantage of using "raw" operations is that custom properties can be passed in the FlatBuffer.

Parameters

data	receiver of the data pointer (non-null pointer to a pointer), which will be pointing to FlatBuffers bytes for the data leaf after this call.
metadata	optional FlatBuffers receiver (nullable pointer to a pointer) for the meta leaf.

Returns

true if a node was found at the given path

getLeafPath()

std::string obx::TreeCursor::getLeafPath ( obx_id  leafId )

inline

Gets the full path (from the root) of the given leaf ID (allocated C string version).

Returns

The path or an empty string if not successful.

getLeafPathCString()

const char* obx::TreeCursor::getLeafPathCString ( obx_id  leafId )

inline

Gets the full path (from the root) of the given leaf ID (allocated C string version).

Returns

If successful, an allocated path is returned (malloc), which must be free()-ed by the caller.

If not successful, NULL is returned.

getLeavesInfo() [1/2]

LeavesInfo obx::TreeCursor::getLeavesInfo ( const char *  path = nullptr )

inline

Given an existing path, return all existing leaves with their paths. As this traverses the data tree (i.e. not the meta tree), it will only return nodes that exist (obviously). Thus, the meta tree may contain additional paths, but these are unused by the data tree (currently at least).

Parameters

path	the branch or leaf path to use. Optional: if no path is given, the root node is taken.

Returns

leaf info ordered by path depth (i.e. starting from paths with the smallest number of branches); paths at same depth are ordered by id.

getLeavesInfo() [2/2]

LeavesInfo obx::TreeCursor::getLeavesInfo ( const std::string &  path )

inline

put()

TreePutResult obx::TreeCursor::put ( const char *  path, void *  data, size_t  size, OBXPropertyType  type, obx_id *  outId = nullptr, void *  metadata = nullptr, size_t  metadata_size = 0, OBXPutMode  dataPutMode = OBXPutMode_PUT  )

inline

A "low-level" put operation for a tree leaf using given raw FlatBuffer bytes. Any non-existing branches and meta nodes are put on the fly if an optional meta-leaf FlatBuffers is given. A typical usage pattern is to first try without the meta-leaf, and if it does not work, create the meta-leaf and call again with the meta leaf. This approach takes into account that meta-leaves typically exist, and thus no resources are wasted for meta-leaf creation if it's not required. An advantage of using "raw" operations is that custom properties can be passed in the FlatBuffers.

Parameters

data	prepared FlatBuffers bytes for the data leaf (non-const as the data buffer will be mutated); note: slots for IDs must be already be prepared (zero values)
type	value type of the given leafObject: it has to be passed to verify against stored metadata
outId	Receives the ID of the data leaf object that was put (pointer can be null)
metadata	optional FlatBuffers for the meta leaf; at minimum, "name" and "type" must be set. Note: slots for IDs must be already be prepared (zero values). Passing null indicates that the branches and meta nodes must already exist; otherwise the operation will fail and OBX_NOT_FOUND will be returned.
dataPutMode	For the data leaf only (the actual value tree node)

Returns

result status enum

setTransaction() [1/2]

void obx::TreeCursor::setTransaction ( Transaction &  tx )

inline

setTransaction() [2/2]

void obx::TreeCursor::setTransaction ( Transaction *  tx )

inline

Sets or clears a transaction from the tree cursor.

A typical use case for this function is to cache the tree cursor for reusing it later. Note: before closing a transaction, ensure to clear it here first (set to null).