ditto::Store Class Reference

Provides access to Collections and a write transaction API. More...

#include <Store.hpp>

Public Member Functions
std::set< std::shared_ptr< AttachmentFetcher > >	get_attachment_fetchers () const
	Returns a copy of all currently active attachment fetchers.
Collection	collection (std::string name) const
	Returns a Collection with the provided name.
std::vector< std::unique_ptr< WriteTransactionResult > >	write (std::function< void(WriteTransaction &)> fn) const
	Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.
PendingCollectionsOperation	collections () const
	Returns an object that lets you fetch or observe the collections in the store.
DiskUsage	get_disk_usage () const
	Provides access to the Store's disk usage.
QueryResult	execute (std::string query, nlohmann::json query_args=nullptr)
	Executes a DQL query and returns matching items as a query result.
std::shared_ptr< StoreObserver >	register_observer (std::string query, StoreObservationHandler change_handler)
	Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.
std::shared_ptr< StoreObserver >	register_observer (std::string query, nlohmann::json query_args, StoreObservationHandler change_handler)
	Installs and returns a change observer for a query, configuring Ditto to call the provided in change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.
std::shared_ptr< StoreObserver >	register_observer (std::string query, StoreObservationHandlerWithNextSignal change_handler)
	Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.
std::shared_ptr< StoreObserver >	register_observer (std::string query, nlohmann::json query_args, StoreObservationHandlerWithNextSignal change_handler)
	Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.
Attachment	new_attachment (std::string path, std::map< std::string, std::string > metadata=std::map< std::string, std::string >()) const
	Creates a new attachment, which can then be inserted into a document.
std::shared_ptr< AttachmentFetcher >	fetch_attachment (std::shared_ptr< AttachmentToken > token, AttachmentFetcherEventHandler event_handler) const
	Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.
std::shared_ptr< AttachmentFetcher >	fetch_attachment (std::unordered_map< std::string, any > map, AttachmentFetcherEventHandler event_handler) const
	Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

Public Attributes
std::set< std::shared_ptr< StoreObserver > >	observers
	Returns a copy of all currently active store observers.

Detailed Description

Provides access to Collections and a write transaction API.

Member Function Documentation

collection()

Collection ditto::Store::collection

(

std::string

name

)

const

Returns a Collection with the provided name.

Parameters

[in]

name

the name of the collection. A name is valid if: its length is less than 100 it does not contain the char '\0' it is not prefixed with "$TS_" it is not empty

Returns

a Collection.

Exceptions

if	name is not a valid Collection name.

collections()

PendingCollectionsOperation ditto::Store::collections

(

)

const

Returns an object that lets you fetch or observe the collections in the store.

Returns

a PendingCollectionsOperation object that you can use to fetch or observe the collections in the store

execute()

QueryResult ditto::Store::execute	(	std::string	query,
		nlohmann::json	query_args = nullptr )

Executes a DQL query and returns matching items as a query result.

This method only returns results from the local store without waiting for any SyncSubscriptions to have caught up with the latest changes. Only use this method if your program must proceed with immediate results. Use a StoreObserver to receive updates to query results as soon as they have been synced to this peer.

Parameters

query	a string containing a valid query expressed in DQL.
query_args	a dictionnary of values keyed by the placeholder name without the leading :.

fetch_attachment() [1/2]

std::shared_ptr< AttachmentFetcher > ditto::Store::fetch_attachment	(	std::shared_ptr< AttachmentToken >	token,
		AttachmentFetcherEventHandler	event_handler ) const

Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report changes to the status of the fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the event_handler lambda with a completed event object, which will hold a reference to the attachment.

Parameters

[in]	token	the AttachmentToken relevant to the attachment that you wish to download and observe.
[in]	event_handler	a lambda that will be called when there is an update relating to the attachment fetch attempt.

Returns

an AttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment's fetch attempt events.

Exceptions

`AttachmentNotFoundError`	if an attachment based on the provided token could not be found.
`AttachmentTokenInvalidError`	if the provided token is invalid.
`FailedToFetchAttachmentError`	if the fetch attempt failed for some other reason.

Note

this mutates the object, but in a synchronized, thread-safe fashion.

fetch_attachment() [2/2]

std::shared_ptr< AttachmentFetcher > ditto::Store::fetch_attachment	(	std::unordered_map< std::string, any >	map,
		AttachmentFetcherEventHandler	event_handler ) const

Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report changes to the status of the fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the event_handler lambda with a completed event object, which will hold a reference to the attachment.

Parameters

[in]	map	a map representation of the AttachmentToken relevant to the attachment that you wish to download and observe.
[in]	event_handler	a lambda that will be called when there is an update relating to the attachment fetch attempt.

Returns

an AttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment's fetch attempt events.

Exceptions

`AttachmentNotFoundError`	if an attachment based on the provided token could not be found.
`AttachmentTokenInvalidError`	if the provided token is invalid.
`FailedToFetchAttachmentError`	if the fetch attempt failed for some other reason.

Note

this mutates the object, but in a synchronized, thread-safe fashion.

get_disk_usage()

DiskUsage ditto::Store::get_disk_usage

(

)

const

Provides access to the Store's disk usage.

Returns

a DiskUsage object.

new_attachment()

Attachment ditto::Store::new_attachment	(	std::string	path,
		std::map< std::string, std::string >	metadata = std::map<std::string, std::string>() ) const

Creates a new attachment, which can then be inserted into a document.

The file residing at the provided path will be copied into the Ditto's store. The Attachment object that is returned is what you can then use to insert an attachment into a document.

You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment.

Below is a snippet to show how you can use the new_attachment functionality to insert an attachment into a document.

auto attachment = ditto.get_store().new_attachment("/path/to/my/file.pdf");
auto docID = collection.insert(json{{"attachment", attachment}, {"other",
"string"}});

Parameters

[in]	path	the path to the file that you want to create an attachment with.
[in]	metadata	metadata relating to the attachment.

Returns

an Attachment object, which can be used to insert the attachment into a document.

Exceptions

`AttachmentFileNotFoundError`	if the file at the provided path does not exist.
`AttachmentFilePermissionDeniedError`	if the file at the provided path cannot be read.
`FailedToCreateAttachmentError`	if the attachment could not be created for some other reason.

register_observer() [1/4]

std::shared_ptr< StoreObserver > ditto::Store::register_observer	(	std::string	query,
		nlohmann::json	query_args,
		StoreObservationHandler	change_handler )

Installs and returns a change observer for a query, configuring Ditto to call the provided in change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.

Parameters

query	a string containing a valid query expressed in DQL.
arguments	a dictionary of values keyed by the placeholder name without the leading :. Example: {{"mileage", 123}}.

Returns

An active StoreObserver for the provided query and arguments. You'll have to keep it in scope to keep receiving changes.

• Throws: DittoError if the query is not a valid DQL query.

register_observer() [2/4]

std::shared_ptr< StoreObserver > ditto::Store::register_observer	(	std::string	query,
		nlohmann::json	query_args,
		StoreObservationHandlerWithNextSignal	change_handler )

Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.

Parameters

query	a string containing a valid query expressed in DQL.
query_args	a dictionary of values keyed by the placeholder name without the leading :. Example: {{"mileage", 123}}.

Returns

: An active StoreObserver for the provided query and arguments. You'll have to keep it in scope to receive changes.

register_observer() [3/4]

std::shared_ptr< StoreObserver > ditto::Store::register_observer	(	std::string	query,
		StoreObservationHandler	change_handler )

Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.

Parameters

query

a string containing a valid query expressed in DQL.

Returns

An active StoreObserver for the provided query. You'll have to keep it in scope to receive changes.

• Throws: DittoError if the query is not a valid DQL query.

register_observer() [4/4]

std::shared_ptr< StoreObserver > ditto::Store::register_observer	(	std::string	query,
		StoreObservationHandlerWithNextSignal	change_handler )

Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.

Parameters

query

a string containing a valid query expressed in DQL.

Returns

An active StoreObserver for the provided query. You'll have to keep it in scope to keep receiving changes.

write()

std::vector< std::unique_ptr< WriteTransactionResult > > ditto::Store::write

(

std::function< void(WriteTransaction &)>

fn

)

const

Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.

Parameters

fn	a lambda that provides access to a write transaction object that can be used to perform operations on the store.

Returns

a list of WriteTransactionResults. There is a result for each operation performed as part of the write transaction.