Read-through Cache Usage

This section explains the use of the Read-through cache provider after configuring and deploying it. NCache provides the Alachisoft.NCache.Runtime.Caching.ReadThruOptions class to specify Read-Thru options in API. The ReadThruOptions class contains enum ReadMode, which can either be ReadThru or ReadThruForced, explained below.

ReadThru checks for the existence of an item in the cache and if not found, fetches the data from the data source.
ReadThruForced fetches the item from a data source, regardless of its existence in the cache or not.

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

Important

For Java, before deploying your JAR files, you need to make sure that:

JDK 17 is installed.
The environment variable for Java is set.

To learn about the standard prerequisites required to work with all NCache server-side features please refer to the given page on Server Side API Prerequisites.
For API details refer to: CacheItem, Get, ReadMode, GetBulk, CacheConnectionOptions, ReadThruOptions.

Using Read-through with Get Operation

The following example retrieves an item with Read-through enabled, corresponding to the specified key using the Get method.

.NET
Java

// Pre-condition: Cache is already connected
// Specify the key of the item
string key = $"Product:{product.ProductID}";

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

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

if (data != null)
{
  // Perform operations accordingly
}

// Pre-condition: Cache is already connected
// Specify the key of the item
String key = "Product:" + product.getProductID();

// Specify the readThruOptions for Read-through operations
var readThruOptions = new ReadThruOptions(ReadMode.ReadThru);
readThruOptions.setReadMode(ReadMode.ReadThru);

// Retrieve the data of the corresponding item with read thru enabled
Product data = cache.get(key,readThruOptions,Product.class);

if (data != null) {
  // Perform operations accordingly
}

Note

To ensure the operation is fail-safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Using ForcedRead-Through

NCache provides the option of forced Read-through, through which NCache fetches the data from the data source forcefully. It means that the data will not be checked in the cache and will directly be fetched from the data 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.

.NET
Java

// Specify the key of the item
string key = $"Product:{product.ProductID}";

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

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

if (data != null)
{
  // Perform operations accordingly
}

// Specify the key of the item
String key = "Product:" + product.getProductID();

// Specify the readThruOptions for Read-through operations
var readThruOptions = new ReadThruOptions(ReadMode.ReadThruForced);
readThruOptions.setReadMode(ReadMode.ReadThruForced);

// Retrieve the data of the corresponding item with read thru enabled
Product data = cache.get(key,readThruOptions,Product.class);

if (data != null) {
  // Perform operations accordingly
}

Using Read-through with Bulk Operations

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

Tip

For a better understanding of these operations review Bulk Operations.

.NET
Java

// Create a new array of keys
String[] keys = new string[];

// 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

// Create a new array of keys
List<String> keys = new ArrayList<>();

// Specify the readThruOptions for Read-through operations
var readThruOptions = new ReadThruOptions(ReadMode.ReadThru);
readThruOptions.setReadMode(ReadMode.ReadThru);

// Retrieve the dictionary of Products using Map with corresponding products
Map<String, Product> retrievedItems = cache.getBulk(keys,readThruOptions,Product.class);

Using Read-through with CacheItem

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

.NET
Java

// Specify the key of the item
string key = $"Product:{product.ProductID}";

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

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

if (data != null)
{
  // Perform operations accordingly
}

// Specify the key of the item
String key = "Product" + product.getProductID();

// Specify the readThruOptions for Read-through operations
var readThruOptions = new ReadThruOptions(ReadMode.ReadThru);
readThruOptions.setReadMode(ReadMode.ReadThru);

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

if(data != null) {
  // Perform operations accordingly
}

Using Read-through with Data Structures

The following example retrieves a Counter, List, Queue, HashSet, and Dictionary with Read-through enabled, corresponding to the specified key.

.NET
Java

// Specify the key of the item
string key = $"Product:{product.ProductID}";

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

switch(mainMenu)
{
  case mainMenu.GetDistributedCounter:
    // Retrieve the count of the corresponding item with read thru enabled
    ICounter counter = cache.DataTypeManager.GetCounter(key, readThruOptions);
    break;
  case mainMenu.GetDistributedDictionary:
    // Retrieve dictionary of the corresponding item with read thru enabled
    IDistributedDictionary<string, object> distributedDictionary = cache.DataTypeManager.GetDictionary<string, object>(key,readThruOptions);
    break;
  case mainMenu.GetDistributedList:
    // Retrieve the list of the corresponding item with read thru enabled
    IDistributedList<object> distributedList = cache.DataTypeManager.GetList<object>(key, readThruOptions);
    break;
  case mainMenu.GetDistributedQueue:
    // Retrieve the queue of the corresponding item with read thru enabled
    IDistributedQueue<object> distributedQueue = cache.DataTypeManager.GetQueue<object>(key, readThruOptions);
    break;
  case mainMenu.GetDistributedHashSet:
    // Retrieve the HashSet of the corresponding item with read thru enabled
    IDistributedHashSet<int> distributedHashSet = cache.DataTypeManager.GetHashSet<int>(key, readThruOptions);
    break;
}

// Specify the key of the item
String key = "Product:" + product.getProductID();

// Specify the readThruOptions for Read-through operations
var readThruOptions = new ReadThruOptions(ReadMode.ReadThru);
readThruOptions.setReadMode(ReadMode.ReadThru);

switch(mainMenu) {
  case GetDistributedCounter:
    // Retrieve the count of the corresponding item with read thru enabled
    Counter counter = cache.getDataStructuresManager().getCounter(key, readThruOptions);
    break;
  case GetDistributedDictionary:
    // Retrieve dictionary of the corresponding item with read thru enabled
    DistributedDictionary distributedDictionary = cache.getDataStructuresManager().getMap(key,readThruOptions);
    break;
  case GetDistributedList:
    // Retrieve the list of the corresponding item with read thru enabled
    DistributedList distributedList = cache.getDataStructuresManager().getList(key, readThruOptions);
    break;
  case GetDistributedQueue:
    // Retrieve the queue of the corresponding item with read thru enabled
    DistributedQueue distributedQueue = cache.getDataStructuresManager().getQueue(key, readThruOptions);
    break;
  case GetDistributedHashSet:
    // Retrieve the HashSet of the corresponding item with read thru enabled
    DistributedHashSet distributedHashSet = cache.getDataStructuresManager().getHashSet(key, readThruOptions);
    break;
}

Configure Default Read-through Provider

You can specify the default provider through the NCache Management Center or through the client.ncconf file. If the provider name is not provided in both the API and client.ncconf, then default provider will automatically be used.

<cache id="demoCache" 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 provides errors in cache logs in case of an exception during the loading of the provided assemblies.

Additional Resources

NCache provides a sample application for Read-through on GitHub.