Read-Through Usage with Cache Operation

Note

This feature is only available in NCache Enterprise Edition.

This section will explain the use of Read-Through provider after configuring and deploying it. NCache supports multiple Read-Through providers with an application.

NCache provides Alachisoft.NCache.Client.DSReadOption enum to specify Read thru option in APIs.

Multiple Read-Through providers can be configured through NCache. Default Read-Through provider will be called if specific provider name is not mentioned through API. You can also use providers other than default by using provider specific overloads of APIs.

Pre-Requisites

To utilize the APIs, include the following namespace in your application:
- Alachisoft.NCache.Runtime.DatasourceProviders
- Alachisoft.NCache.Runtime.Caching
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.Exceptions
The application must be connected to cache before performing the operation.
Cache must be running.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Using Get Method

The following example retrieves an item with read-through enabled, corresponding to the specified key "Product:1001" using the Get<> method.

try
{
  // Pre-condition: Cache is already connected

  // Specify the key of the item
  string key = "Product:1001";

  // Specify the readThruOptions for read through operations
  var readThruOptions = new ReadThruOptions();
  readThruOptions.Mode = ReadMode.ReadThru;

  // Retrieve the data of the corresponding item with reads thru enabled
  Product data = cache.Get<Product>(key, readThruOptions);

  if (data != null)
  {
    // Perform operations accordingly
  }
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else
  {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
}
catch (Exception ex)
{
  // Any generic exception like ArgumentNullException or ArgumentException
}

Using ForcedRead-Through

NCache provides with an option of Forced Read-Through which forces NCache to get the data from backing source forcefully. It means that the data will not be looked upon for in the cache and will directly be fetched from the backing source.

You can enable forced read-through by specifying the ReadMode as ReadThruForced.

The following example gets an item from the cache using the ReadThruForced option by forcefully enabling read-through on it.

try
{
  // Pre-condition: Cache is already connected

  // Specify the key of the item
  string key = "Product:1001";

  // Specify the readThruOptions for read through operations
  var readThruOptions = new ReadThruOptions();
  readThruOptions.Mode = ReadMode.ReadThruForced;

  // Retrieve the data of the corresponding item with reads thru enabled
  Product data = cache.Get<Product>(key, readThruOptions);

  if (data != null)
  {
    // Perform operations accordingly
  }
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else
  {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Using Read-Through with Bulk Operations

For better understanding of the these operations review Bulk Operations.

The following example retrieves a dictionary of products corresponding to the keys specified with read-through enabled using the GetBulk method.

try
{
  // Pre-Condition: Cache is already connected

  // Create a new array of keys 
  String[] keys = new string[4];
  keys[1] = "Product:1001";
  keys[2] = "Product:1002";
  keys[3] = "Product:1003";
  keys[4] = "Product:1004";

  // Specify the readThruOptions for read through operations
  var readThruOptions = new ReadThruOptions();
  readThruOptions.Mode = ReadMode.ReadThru;

  // Retrieve the dictionary of Products with corresponding products
  IDictionary<string, Product> retrievedItems = cache.GetBulk<Product>(keys, readThruOptions);

  // IDictionary contains cached keys and values
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else
  {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Using Read-Through with CacheItem

The following example retrieves a CacheItem with read-through enabled corresponding to the key specified.

try
{
  // Pre-condition: Cache is already connected

  // Specify the key of the item
  string key = "Product:1001";

  // Specify the readThruOptions for read through operations
  var readThruOptions = new ReadThruOptions();
  readThruOptions.Mode = ReadMode.ReadThru;

  // Retrieve the data of the corresponding item with reads thru enabled
  CacheItem data = cache.GetCacheItem(key, readThruOptions);

  if (data != null)
  {
    // Perform operations accordingly
  }
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else
  {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

You can specify the default provider through NCache Web Manager or through client.ncconf file placed in the config folder of the NCache installation directory. If the provider name is not provided in both the API and client.ncconf, the default provider will automatically be used.

<cacheid="mycache" default-readthru-provider="defaultProviderName" client-cache-id="" client-cache-syncmode="optimistic" default-writethru-provider="" load-balance="True">
  ...
</cache>

CacheConnectionOptions can also be used to specify providers. NCache logs errors/exceptions in cache logs in case of an exception during loading the provided assemblies.

Additional Resources

NCache provides sample application for read-through at:

GitHub
Shipped with NCache: %NCHOME%\samples\dotnet\BackingSource