NamedCacheSetBackingStoreAdapter Method

ScaleOut Software NamedCache API
Specifies a class that can be used by the NamedCache to automatically interact with an external data source (a database, typically) for read-through, write-through, refresh-ahead, and write-behind operations.

Namespace:  Soss.Client
Assembly:  soss_namedcache (in soss_namedcache.dll) Version:

public void SetBackingStoreAdapter(
	IBackingStore backingStore,
	BackingStorePolicy backingStorePolicy


Type: Soss.ClientIBackingStore
An IBackingStore instance that implements custom logic for the retrieval and storage of objects in a database or other persistent data store. Setting this parameter to null indicates that this client should not perform any backing store operations.
Type: Soss.ClientBackingStorePolicy
Contains options to control how a named cache interacts with a backing store.

InvalidOperationExceptionThrown if the named cache has been configured to use GeoServer pull replication through a call to SetRemoteStores(RemoteStoreCollection)

Use the SetBackingStoreAdapter(IBackingStore, BackingStorePolicy) method to enable read-through, write-through, refresh-ahead, and write-behind behavior when ScaleOut StateServer is being used as a cache for a persistent backing store (such as a database). If backing store operations are enabled on a NamedCache, then every instance of the client application that uses that NamedCache will need to register an IBackingStore adapter instance using this method. Clients that fail to register an adapter will not handle backing store operations assigned to them, resulting in lost backing store updates and retrievals.

If read-through operations are enabled in the specified backingStorePolicy parameter, it is not desirable for every client process to simultaneously query the database when a cache miss occurs. The read-through operations will affect the behavior of the NamedCache's Retrieve(CachedObjectId, Boolean), Get(CachedObjectId), and ItemCachedObjectId methods when a cache miss occurs. The first client to perform a retrieval operation on an object that is missing from the cache will have its Load(CachedObjectId) implementation invoked. While the backing store is being queried, other clients requesting this object will repeatedly poll until the object has been inserted into the cache. The frequency of the polling behavior is controlled through the ReadPendingRetryInterval and MaxReadThroughPendingAttempts properties.

Unlike read-through and write-through operations (which are enabled on an entire NamedCache through the backingStorePolicy parameter), the asynchronous write-behind and refresh-ahead operations must be enabled on an object-by-object basis when they are first created in the ScaleOut StateServer cache. Use the BackingStoreMode property to enable write-behind or refresh-ahead operations for an object. The BackingStoreInterval property controls the interval between asynchronous backing store events.

The asynchronous write-behind and refresh-ahead operations are timed events that occur periodically. These operations internally make use of ScaleOut StateServer's event notification feature and use the same server infrastructure that implements the ObjectExpired event. In a server farm that is running multiple ScaleOut StateServer hosts, it is not possible to predict which host will be asked to perform any given refresh-ahead or write-behind operation. This allows ScaleOut StateServer to maximize performance by distributing backing store operations across the server farm. Again, it is important to have the IBackingStore adapter implementation registered in each client application to ensure that a backing store operation is not lost. If the server farm is accessed solely by remote clients, there must be at least as many active remote clients as there are ScaleOut hosts; this ensures that all ScaleOut hosts are able to notify clients about backing store operations.

It is possible to avoid having to register an IBackingStore adapter on remote client machines, but this is not a typical configuration. In situations where the remote client machines do not have access to the backing store but the ScaleOut StateServer host machines do have access, it is permitted to avoid registering an IBackingStore adapter on the remote clients (by passing null into the backingStore parameter) if and only if client applications are running locally on all of the ScaleOut StateServer hosts to handle backing store operations. All instances of those local client applications must register an IBackingStore adapter, otherwise backing store events will be lost. In this configuration, all expiration and backing store events will be directed to the ScaleOut StateServer hosts in the current version; this limitation will be removed in a future version.

This method can be called repeatedly to change the API's behavior.

Backing store operations cannot be used in conjunction with GeoServer pull replication.

See Also