A ObjectBox store represents a database storing data in a given directory on a local file system. More...

#include <objectbox.hpp>

Public Member Functions
	Store (OBX_model *model)
	Creates a Store with the given model and default Options. More...

	Store (Options &options)
	Creates a Store with the given Options, which also contain the data model. More...

	Store (Options &&options)
	Creates a Store with the given Options, which also contain the data model. More...

	Store (OBX_store *cStore)
	Wraps an existing C-API store pointer, taking ownership (don't close it manually anymore) More...

	Store (const Store &)=delete
	Can't be copied, single owner of C resources is required (to avoid double-free during destruction) More...

	Store (Store &&source) noexcept

virtual	~Store ()

OBX_store *	cPtr () const

uint64_t	id () const

uint32_t	getStoreTypeId ()
	Get Store type. More...

uint64_t	getDbSize () const
	Get the size of the store. For a disk-based store type, this corresponds to the size on disk, and for the in-memory store type, this is roughly the used memory bytes occupied by the data. More...

uint64_t	getDbSizeOnDisk () const
	The size in bytes occupied by the database on disk (if any). More...

template<class EntityBinding >
Box< EntityBinding >	box ()

Transaction	tx (TxMode mode)
	Starts a transaction using the given mode. More...

Transaction	txRead ()
	Starts a read(-only) transaction. More...

Transaction	txWrite ()
	Starts a (read &) write transaction. More...

obx_schema_id	getEntityTypeIdNoThrow (const char *entityName) const
	Does not throw if the given type name is not found (it may still throw in other conditions). More...

obx_schema_id	getEntityTypeId (const char *entityName) const

obx_schema_id	getPropertyIdNoThrow (obx_schema_id entityId, const char *propertyName) const
	Does not throw if the given property name is not found (it may still throw in other conditions). More...

obx_schema_id	getPropertyId (obx_schema_id entityId, const char *propertyName) const

obx_schema_id	getPropertyId (const char entityName, const char propertyName) const

BoxTypeless	boxTypeless (const char *entityName)

bool	awaitCompletion ()
	Await all (including future) async submissions to be completed (the async queue becomes empty). More...

bool	awaitSubmitted ()
	Await previously submitted async operations to be completed (the async queue may still contain elements). More...

void	backUpToFile (const char *backupFile, uint32_t flags=0) const
	Backs up the store DB to the given backup-file, using the given flags. Note: backup is a server-only feature. More...

std::shared_ptr< SyncClient >	syncClient ()

void	prepareToClose ()
	Prepares the store to close by setting its internal state to "closing". Methods like tx() an boxFor() will throw ShuttingDownException once closing is initiated. Unlike close(), this method will return immediately and does not free resources just yet. This is typically used in a multi-threaded context to allow an orderly shutdown in stages which go through a "not accepting new requests" state. More...

void	close ()
	Closes all resources of this store before the destructor is called, e.g. to avoid waiting in the destructor. Avoid calling methods on the Store after this call; most methods will throw ShuttingDownException in that case. Calling close() more than once have no effect, and concurrent calls to close() are fine too. More...

Static Public Member Functions
static const char *	versionCString ()
	Return the (runtime) version of the library to be printed. The current format is "major.minor.patch" (e.g. "1.0.0") but may change in any future release. Thus, only use for information purposes. More...

static std::string	versionString ()
	Creates a new string containing versionCString() More...

static const char *	versionCoreCString ()
	Return the version of the ObjectBox core to be printed (currently also contains a version date and features). The format may change in any future release; only use for information purposes. More...

static std::string	versionCoreString ()
	Creates a new string containing versionCoreCString() More...

static void	getVersion (int major, int minor, int *patch)
	Return the version of the library as ints. Pointers may be null. More...

static void	debugLog (bool enabled)
	Enable (or disable) debug logging for ObjectBox internals. This requires a version of the library with the DebugLog feature. You can check if the feature is available with obx_has_feature(OBXFeature_DebugLog). More...

static bool	debugLogEnabled ()
	Checks if debug logs are enabled for ObjectBox internals. This depends on the availability of the DebugLog feature. If the feature is available, it returns the current state, which is adjustable via obx_debug_log(). Otherwise, it always returns false for standard release builds (or true if you are having a special debug version). More...

static void	removeDbFiles (const std::string &directory)
	Delete the store files from the given directory. More...

static size_t	getDbFileSize (const std::string &directory)

Detailed Description

A ObjectBox store represents a database storing data in a given directory on a local file system.

Once opened using one of the constructors, Store is an entry point to data access APIs such as Box, Query, and Transaction.

It's possible open multiple stores in different directories, e.g. at the same time.

Constructor & Destructor Documentation

◆ Store() [1/6]

obx::Store::Store ( OBX_model * model )

inlineexplicit

Creates a Store with the given model and default Options.

◆ Store() [2/6]

obx::Store::Store ( Options & options )

inlineexplicit

Creates a Store with the given Options, which also contain the data model.

◆ Store() [3/6]

obx::Store::Store ( Options && options )

inlineexplicit

Creates a Store with the given Options, which also contain the data model.

◆ Store() [4/6]

obx::Store::Store ( OBX_store * cStore )

inlineexplicit

Wraps an existing C-API store pointer, taking ownership (don't close it manually anymore)

◆ Store() [5/6]

obx::Store::Store ( const Store & )

delete

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

◆ Store() [6/6]

obx::Store::Store ( Store && source )

noexcept

◆ ~Store()

virtual obx::Store::~Store ( )

virtual

Member Function Documentation

◆ awaitCompletion()

bool obx::Store::awaitCompletion ( )

inline

Await all (including future) async submissions to be completed (the async queue becomes empty).

Returns: true if all submissions were completed (or async processing was not started); false if shutting down or an error occurred

◆ awaitSubmitted()

bool obx::Store::awaitSubmitted ( )

inline

Await previously submitted async operations to be completed (the async queue may still contain elements).

Returns: true if all submissions were completed (or async processing was not started); false if shutting down or an error occurred

◆ backUpToFile()

void obx::Store::backUpToFile	(	const char *	backupFile,
		uint32_t	flags = `0`
	)		const

inline

Backs up the store DB to the given backup-file, using the given flags. Note: backup is a server-only feature.

Parameters

flags 0 for defaults or OBXBackupFlags bit flags

◆ box()

template<class EntityBinding >

Box<EntityBinding> obx::Store::box ( )

inline

◆ boxTypeless()

BoxTypeless obx::Store::boxTypeless ( const char * entityName )

◆ close()

void obx::Store::close ( )

Closes all resources of this store before the destructor is called, e.g. to avoid waiting in the destructor. Avoid calling methods on the Store after this call; most methods will throw ShuttingDownException in that case. Calling close() more than once have no effect, and concurrent calls to close() are fine too.

Note: This waits for write transactions to finish before returning from this call.; The Store destructor also calls close(), so you do not have to call this method explicitly unless you want to control the timing of closing resources and potentially waiting for asynchronous resources (e.g. transactions and internal queues) to finish up.

◆ cPtr()

OBX_store* obx::Store::cPtr ( ) const

Exceptions

ShuttingDownException if the Store is closed (close() was call on the store).

◆ debugLog()

static void obx::Store::debugLog ( bool enabled )

inlinestatic

Enable (or disable) debug logging for ObjectBox internals. This requires a version of the library with the DebugLog feature. You can check if the feature is available with obx_has_feature(OBXFeature_DebugLog).

◆ debugLogEnabled()

static bool obx::Store::debugLogEnabled ( )

inlinestatic

Checks if debug logs are enabled for ObjectBox internals. This depends on the availability of the DebugLog feature. If the feature is available, it returns the current state, which is adjustable via obx_debug_log(). Otherwise, it always returns false for standard release builds (or true if you are having a special debug version).

◆ getDbFileSize()

static size_t obx::Store::getDbFileSize ( const std::string & directory )

inlinestatic

◆ getDbSize()

uint64_t obx::Store::getDbSize ( ) const

inline

Get the size of the store. For a disk-based store type, this corresponds to the size on disk, and for the in-memory store type, this is roughly the used memory bytes occupied by the data.

Returns: the size in bytes of the database, or 0 if the file does not exist or some error occurred.

◆ getDbSizeOnDisk()

uint64_t obx::Store::getDbSizeOnDisk ( ) const

inline

The size in bytes occupied by the database on disk (if any).

Returns: 0 if the underlying database is in-memory only, or the size could not be determined.

◆ getEntityTypeId()

obx_schema_id obx::Store::getEntityTypeId ( const char * entityName ) const

inline

◆ getEntityTypeIdNoThrow()

obx_schema_id obx::Store::getEntityTypeIdNoThrow ( const char * entityName ) const

inline

Does not throw if the given type name is not found (it may still throw in other conditions).

◆ getPropertyId() [1/2]

obx_schema_id obx::Store::getPropertyId	(	const char *	entityName,
		const char *	propertyName
	)		const

inline

◆ getPropertyId() [2/2]

obx_schema_id obx::Store::getPropertyId	(	obx_schema_id	entityId,
		const char *	propertyName
	)		const

inline

◆ getPropertyIdNoThrow()

obx_schema_id obx::Store::getPropertyIdNoThrow	(	obx_schema_id	entityId,
		const char *	propertyName
	)		const

inline

Does not throw if the given property name is not found (it may still throw in other conditions).

◆ getStoreTypeId()

uint32_t obx::Store::getStoreTypeId ( )

inline

Get Store type.

Returns: One of OBXStoreTypeId

◆ getVersion()

static void obx::Store::getVersion	(	int *	major,
		int *	minor,
		int *	patch
	)

inlinestatic

Return the version of the library as ints. Pointers may be null.

◆ id()

uint64_t obx::Store::id ( ) const

Returns: non-zero ID for the Store

◆ prepareToClose()

void obx::Store::prepareToClose ( )

Prepares the store to close by setting its internal state to "closing". Methods like tx() an boxFor() will throw ShuttingDownException once closing is initiated. Unlike close(), this method will return immediately and does not free resources just yet. This is typically used in a multi-threaded context to allow an orderly shutdown in stages which go through a "not accepting new requests" state.

◆ removeDbFiles()

static void obx::Store::removeDbFiles ( const std::string & directory )

inlinestatic

Delete the store files from the given directory.

◆ syncClient()

std::shared_ptr< SyncClient > obx::Store::syncClient ( )

inline

Returns: an existing SyncClient associated with the store (if available; see Sync::client() to create one)

Note: : implemented in objectbox-sync.hpp

◆ tx()

Transaction obx::Store::tx ( TxMode mode )

Starts a transaction using the given mode.

◆ txRead()

Transaction obx::Store::txRead ( )

Starts a read(-only) transaction.

◆ txWrite()

Transaction obx::Store::txWrite ( )

Starts a (read &) write transaction.

◆ versionCoreCString()

static const char* obx::Store::versionCoreCString ( )

inlinestatic

Return the version of the ObjectBox core to be printed (currently also contains a version date and features). The format may change in any future release; only use for information purposes.

◆ versionCoreString()

static std::string obx::Store::versionCoreString ( )

inlinestatic

Creates a new string containing versionCoreCString()

◆ versionCString()

static const char* obx::Store::versionCString ( )

inlinestatic

Return the (runtime) version of the library to be printed. The current format is "major.minor.patch" (e.g. "1.0.0") but may change in any future release. Thus, only use for information purposes.

See also: getVersion() for integer based versions

◆ versionString()

static std::string obx::Store::versionString ( )

inlinestatic

Creates a new string containing versionCString()

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Store() [1/6]

◆ Store() [2/6]

◆ Store() [3/6]

◆ Store() [4/6]

◆ Store() [5/6]

◆ Store() [6/6]

◆ ~Store()

Member Function Documentation

◆ awaitCompletion()

◆ awaitSubmitted()

◆ backUpToFile()

◆ box()

◆ boxTypeless()

◆ close()

◆ cPtr()

◆ debugLog()

◆ debugLogEnabled()

◆ getDbFileSize()

◆ getDbSize()

◆ getDbSizeOnDisk()

◆ getEntityTypeId()

◆ getEntityTypeIdNoThrow()

◆ getPropertyId() [1/2]

◆ getPropertyId() [2/2]

◆ getPropertyIdNoThrow()

◆ getStoreTypeId()

◆ getVersion()

◆ id()

◆ prepareToClose()

◆ removeDbFiles()

◆ syncClient()

◆ tx()

◆ txRead()

◆ txWrite()

◆ versionCoreCString()

◆ versionCoreString()

◆ versionCString()

◆ versionString()