Interface IPersistentDataStore
Interface for a data store that holds feature flags and related data in a serialized form.
Inherited Members
Namespace: LaunchDarkly.Sdk.Server.Subsystems
Assembly: LaunchDarkly.ServerSdk.dll
Syntax
public interface IPersistentDataStore : IDisposableRemarks
This interface should be used for database integrations, or any other data store implementation that stores data in some external service. The SDK will take care of converting between its own internal data model and a serialized string form; the data store interacts only with the serialized form.
The SDK will also provide its own caching layer on top of the persistent data store; the data store implementation should not provide caching, but simply do every query or update that the SDK tells it to do.
Implementations must be thread-safe.
Implementations that use a task-based asynchronous pattern can use IPersistentDataStoreAsync instead.
Conceptually, each item in the store is a DataStoreTypes.SerializedItemDescriptor which always has a version number, and can represent either a serialized object or a placeholder (tombstone) for a deleted item. There are two approaches a persistent store implementation can use for persisting this data:
- Preferably, it should store the version number and the Deleted state separately so that the object does not need to be fully deserialized to read them. In this case, deleted item placeholders can ignore the value of SerializedItem on writes and can set it to null on reads. The store should never call Deserialize(string) or Serialize(ItemDescriptor) in this case.
- If that isn't possible, then the store should simply persist the exact string from SerializedItem on writes, and return the persisted string on reads -- setting Version to zero and Deleted to false. The string is guaranteed to provide the SDK with enough information to infer the version and the deleted state. On updates, the store will have to call Deserialize(string) in order to inspect the version number of the existing item if any.
Error handling is defined as follows: if any data store operation encounters a database error, or is otherwise unable to complete its task, it should throw an exception to make the SDK aware of this. The SDK will log the exception and will assume that the data store is now in a non-operational state; the SDK will then start polling IsStoreAvailable() to determine when the store has started working again.
Methods
| Edit this page View SourceGet(DataKind, string)
Retrieves an item from the specified collection, if available.
Declaration
DataStoreTypes.SerializedItemDescriptor? Get(DataStoreTypes.DataKind kind, string key)Parameters
| Type | Name | Description |
|---|---|---|
| DataStoreTypes.DataKind | kind | specifies which collection to use |
| string | key | the unique key of the item within that collection |
Returns
| Type | Description |
|---|---|
| DataStoreTypes.SerializedItemDescriptor? | a versioned item that contains the stored data (or placeholder for deleted data); null if the key is unknown |
Remarks
If the key is not known at all, the method should return null. Otherwise, it should return a DataStoreTypes.SerializedItemDescriptor as follows:
- If the version number and deletion state can be determined without fully deserializing the item, then the store should set those properties in the DataStoreTypes.SerializedItemDescriptor (and can set SerializedItem to null for deleted items).
- Otherwise, it should simply set SerializedItem to the exact string that was persisted, and can leave the other properties as zero/false. The SDK will inspect the properties of the item after deserializing it to fill in the rest of the information.
GetAll(DataKind)
Retrieves all items from the specified collection.
Declaration
DataStoreTypes.KeyedItems<DataStoreTypes.SerializedItemDescriptor> GetAll(DataStoreTypes.DataKind kind)Parameters
| Type | Name | Description |
|---|---|---|
| DataStoreTypes.DataKind | kind | specifies which collection to use |
Returns
| Type | Description |
|---|---|
| DataStoreTypes.KeyedItems<DataStoreTypes.SerializedItemDescriptor> | a collection of key-value pairs; the ordering is not significant |
Remarks
If the store contains placeholders for deleted items, it should include them in the results, not filter them out. See Get(DataKind, string) for how to set the properties of the DataStoreTypes.SerializedItemDescriptor for each item.
Init(FullDataSet<SerializedItemDescriptor>)
Overwrites the store's contents with a set of items for each collection.
Declaration
void Init(DataStoreTypes.FullDataSet<DataStoreTypes.SerializedItemDescriptor> allData)Parameters
| Type | Name | Description |
|---|---|---|
| DataStoreTypes.FullDataSet<DataStoreTypes.SerializedItemDescriptor> | allData | a list of DataStoreTypes.DataKind instances and their corresponding data sets |
Remarks
All previous data should be discarded, regardless of versioning.
The update should be done atomically. If it cannot be done atomically, then the store must first add or update each item in the same order that they are given in the input data, and then delete any previously stored items that were not in the input data.
Initialized()
Returns true if this store has been initialized.
Declaration
bool Initialized()Returns
| Type | Description |
|---|---|
| bool | true if the store has been initialized |
Remarks
In a shared data store, the implementation should be able to detect this state even if Init(FullDataSet<SerializedItemDescriptor>) was called in a different process, i.e. it must query the underlying data store in some way. The method does not need to worry about caching this value; the SDK will call it rarely.
IsStoreAvailable()
Tests whether the data store seems to be functioning normally.
Declaration
bool IsStoreAvailable()Returns
| Type | Description |
|---|---|
| bool | true if the underlying data store is reachable |
Remarks
This should not be a detailed test of different kinds of operations, but just the smallest possible operation to determine whether (for instance) we can reach the database.
Whenever one of the store's other methods throws an exception, the SDK will assume that it
may have become unavailable (e.g. the database connection was lost). The SDK will then call
IsStoreAvailable() at intervals until it returns true.
Upsert(DataKind, string, SerializedItemDescriptor)
Updates or inserts an item in the specified collection. For updates, the object will only be updated if the existing version is less than the new version.
Declaration
bool Upsert(DataStoreTypes.DataKind kind, string key, DataStoreTypes.SerializedItemDescriptor item)Parameters
| Type | Name | Description |
|---|---|---|
| DataStoreTypes.DataKind | kind | specifies which collection to use |
| string | key | the unique key for the item within that collection |
| DataStoreTypes.SerializedItemDescriptor | item | the item to insert or update |
Returns
| Type | Description |
|---|---|
| bool | true if the item was updated; false if it was not updated because the store contains an equal or greater version |
Remarks
The SDK may pass an DataStoreTypes.ItemDescriptor that contains a null, to represent a placeholder for a deleted item. In that case, assuming the version is greater than any existing version of that item, the store should retain that placeholder rather than simply not storing anything.