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()
|
inline |
A method to reference a DittoCollection.
- Parameters
-
collectionName The name of the collection.
- Returns
- A reference to the
DittoCollection.
◆ 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()
|
inline |
Executes a DQL query and returns matching items as a query result.
- Returns
- A DittoQueryResult containing a 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]
|
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 completedfetch 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
nullwill be returned. This can happen if, for example, an invalid attachment token was provided.
◆ FetchAttachment() [2/2]
|
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 completedfetch 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()
|
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]
|
inline |
◆ RegisterObserver() [2/6]
|
inline |
◆ RegisterObserver() [3/6]
|
inline |
- Parameters
-
storeObservationHandler A simplified callback containing the DittoQueryResult, where signalNext is automatically called when the handler finishes.
◆ RegisterObserver() [4/6]
|
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
DittoStoreObserverfor 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
SELECTquery.
◆ RegisterObserver() [5/6]
|
inline |
- 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]
|
inline |
◆ Write()
|
inline |
Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.
- Parameters
-
handler An Actionthat provides access to a write transaction object that can be used to perform operations on the store.
- Returns
- A list ofDittoWriteTransactionResult objects. There is a result for each operation performed as part of the write transaction.
Property Documentation
◆ 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]
|
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.
Generated by
1.11.0