DittoSDK.DittoStore Class Reference

A class encompassing functionality relating to the embedded storage. This is not a class you instantiate directly. Instead you access DittoStore objects using Ditto.Store. More...

Public Member Functions
DittoPendingCollectionsOperation	Collections ()
	Returns an object that lets you fetch or observe the collections in the store.
DittoCollection	Collection (string collectionName)
	A method to reference a DittoCollection.
unsafe List< DittoWriteTransactionResult >	Write (Action< DittoWriteTransaction > handler)
	Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.
Task< DittoQueryResult >	ExecuteAsync (string query, Dictionary< string, object > arguments=default)
	Executes a DQL query and returns matching items as a query result.
DittoStoreObserver	RegisterObserver (string query, Action< DittoQueryResult > storeObservationHandler)
DittoStoreObserver	RegisterObserver (string query, Action< DittoQueryResult, Action > storeObservationHandlerWithSignalNext)
DittoStoreObserver	RegisterObserver (string query, Func< DittoQueryResult, Task > storeObservationHandlerTask)
DittoStoreObserver	RegisterObserver (string query, Dictionary< string, object > arguments, Func< DittoQueryResult, Task > storeObservationHandlerTask)
DittoStoreObserver	RegisterObserver (string query, Dictionary< string, object > arguments, Action< DittoQueryResult > storeObservationHandler)
DittoStoreObserver	RegisterObserver (string query, Dictionary< string, object > arguments, Action< DittoQueryResult, Action > storeObservationHandlerWithSignalNext)
	Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local passed in query must be a SELECT query, otherwise a store error with queryNotSupported reason is thrown.
Task< DittoAttachment >	NewAttachmentAsync (string path, Dictionary< string, string > metadata=null)
	Creates a new attachment, which can then be inserted into a document.
DittoAttachmentFetcher	FetchAttachment (DittoAttachmentToken token, Action< DittoAttachmentFetchEvent > onFetchEvent)
	Fetch the attachment corresponding to the provided attachment token.
DittoAttachmentFetcher	FetchAttachment (Dictionary< string, object > token, Action< DittoAttachmentFetchEvent > onFetchEvent)
	Fetch the attachment corresponding to the provided attachment token. Expects a dictionary representation of the token as returned in a DittoQueryResultItem

Properties
IReadOnlyCollection< DittoStoreObserver >	Observers [get]
	Gets all currently active store observers.
IReadOnlyCollection< DittoAttachmentFetcher >	AttachmentFetchers [get]
	Gets all currently active attachment fetchers.
unsafe List< string >	CollectionNames [get]
	Gets the names of all collections known about on this device.
DittoDiskUsage	DiskUsage [get]
	Gets a reference to the store disk usage.
DittoCollection	this[string collectionName] = new ConcurrentDictionary<DittoAttachmentFetcher, byte>() [get]
	Retrieve a DittoCollection. var collection = ditto.store["cars"];

Detailed Description

A class encompassing functionality relating to the embedded storage. This is not a class you instantiate directly. Instead you access DittoStore objects using Ditto.Store.

Member Function Documentation

Collection()

DittoCollection DittoSDK.DittoStore.Collection ( string collectionName )

inline

A method to reference a DittoCollection.

Parameters

collectionName

The name of the collection.

Returns

A reference to the DittoCollection.

Collections()

DittoPendingCollectionsOperation DittoSDK.DittoStore.Collections ( )

inline

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

Returns

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

ExecuteAsync()

Task< DittoQueryResult > DittoSDK.DittoStore.ExecuteAsync ( string query, Dictionary< string, object > arguments = default )

inline

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

Note

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

Returns

A DittoSDK.DittoQueryResult containing a DittoSDK.DittoQueryResultItem for each match.

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: new Dictionary<string, object>() { { "mileage", 123 } }

Exceptions

DittoStoreException

Can throw a DittoStoreException. For more granular exception handling check its subtypes: DittoQueryArgumentsInvalidException - If the query string is not a valid DQL DittoQueryInvalidException - If the arguments dictionary is not valid (contains unsupported types) DittoQueryException - Error during query execution.

FetchAttachment() [1/2]

DittoAttachmentFetcher DittoSDK.DittoStore.FetchAttachment ( Dictionary< string, object > token, Action< DittoAttachmentFetchEvent > onFetchEvent )

inline

Fetch the attachment corresponding to the provided attachment token. Expects a dictionary representation of the token as returned in a DittoQueryResultItem

Parameters

token	Dictionary representation of the token for the attachment that you want to fetch.
onFetchEvent	An action that will be called when there is an update relating to the attachment fetch attempt. If the attachment is already available then this will be called almost immediately with a completed fetch event value.

Returns

A DittoAttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment fetch attempt's events. If the attachment fetcher could not be created then null will be returned. This can happen if, for example, an invalid attachment token was provided.

FetchAttachment() [2/2]

DittoAttachmentFetcher DittoSDK.DittoStore.FetchAttachment ( DittoAttachmentToken token, Action< DittoAttachmentFetchEvent > onFetchEvent )

inline

Fetch the attachment corresponding to the provided attachment token.

Parameters

token	The token for the attachment that you want to fetch.
onFetchEvent	An action that will be called when there is an update relating to the attachment fetch attempt. If the attachment is already available then this will be called almost immediately with a completed fetch event value.

Returns

A DittoAttachmentFetcher instance that can be used to cancel the attachment fetch.

Exceptions

DittoAttachmentNotFoundException	Attachment could not be found.
DittoAttachmentTokenInvalidException	The provided token is invalid.
DittoFailedToFetchAttachmentException	Error encountered trying to fetch the attachment.

NewAttachmentAsync()

Task< DittoAttachment > DittoSDK.DittoStore.NewAttachmentAsync ( string path, Dictionary< string, string > metadata = null )

inline

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

The file residing at the provided path will be copied into Ditto's store. The DittoAttachment 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 NewAttachmentAsync functionality to insert an attachment into a document.

var attachment = await store.NewAttachmentAsync("/path/to/my/file.zip");
if (attachment != null)
{
    var document = new Dictionary<string, object>()
    {
        { "some", "string" },
        { "myAttachment", attachment }
    };
    Ditto.Store.ExecuteAsync(
        query: "INSERT INTO COLLECTION myCollection (myAttachment ATTACHMENT) DOCUMENTS (:document1)",
        arguments: new Dictionary<string, object>()
        {
            {  "document1", document }
        }
    );
}

Parameters

path	Path to the file on disk that will be used as the attachment.
metadata	Optional metadata relating to the attachment.

Returns

A DittoAttachment object, which can be used to insert the attachment into a document

Exceptions

DittoAttachmentFileNotFoundException	File not found at the provided path.
DittoAttachmentFilePermissionDeniedException	Permission denied error.
DittoFailedToCreateAttachmentException	Error encountered trying to create the attachment.

RegisterObserver() [1/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Action< DittoQueryResult > storeObservationHandler )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Action<DittoQueryResult, Action>)

RegisterObserver() [2/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Action< DittoQueryResult, Action > storeObservationHandlerWithSignalNext )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Action<DittoQueryResult, Action>)

RegisterObserver() [3/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Dictionary< string, object > arguments, Action< DittoQueryResult > storeObservationHandler )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Action<DittoQueryResult, Action>)

Parameters

storeObservationHandler

A simplified callback containing the DittoQueryResult, where signalNext is automatically called when the handler finishes.

RegisterObserver() [4/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Dictionary< string, object > arguments, Action< DittoQueryResult, Action > storeObservationHandlerWithSignalNext )

inline

Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local passed in query must be a SELECT query, otherwise a store error with queryNotSupported reason is thrown.

Returns

An active DittoStoreObserver for the passed in query and arguments. You'll have to keep it to be able to cancel the observation, i.e. remove it from the store again. Otherwise it will remain active until Ditto goes out of scope.

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: new Dictionary<string, object>() { { "mileage" , 123 } }
storeObservationHandlerWithSignalNext	A callback that is invoked whenever an active store observer receives a new result. The first parameter is the query result, while the second is an Action, signalNext, that should be called when the handler is ready to receive new data.

Exceptions

DittoStoreException

Can throw a DittoStoreException. For more granular exception handling check the following subtypes: DittoQueryArgumentsInvalidException - If the query string is not a valid DQL. DittoQueryInvalidException - If the arguments dictionary is not valid (contains unsupported types). DittoQueryNotSupportedException - If the query is not a SELECT query.

RegisterObserver() [5/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Dictionary< string, object > arguments, Func< DittoQueryResult, Task > storeObservationHandlerTask )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Action<DittoQueryResult, Action>)

Parameters

storeObservationHandlerTask

A simplified callback containing the DittoQueryResult, to be used in an async context, where signalNext is automatically called when the handler task finishes.

RegisterObserver() [6/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Func< DittoQueryResult, Task > storeObservationHandlerTask )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Func<DittoQueryResult, Task>)

Write()

unsafe List< DittoWriteTransactionResult > DittoSDK.DittoStore.Write ( Action< DittoWriteTransaction > handler )

inline

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

Parameters

handler

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

Returns

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

Property Documentation

CollectionNames

unsafe List<string> DittoSDK.DittoStore.CollectionNames

get

Gets the names of all collections known about on this device.

Note, this will return immediately what is in the store.

this[string collectionName]

DittoCollection DittoSDK.DittoStore.this[string collectionName] = new ConcurrentDictionary<DittoAttachmentFetcher, byte>()

get

Retrieve a DittoCollection. var collection = ditto.store["cars"];

Parameters

collectionName

The name of the collection.

A collection name is valid if:

• its length is less than 100
• it is not empty
• it does not contain the char '\0'
• it does not begin with "$TS_"

  Returns

  A reference to the DittoCollection.