Using Write-Through with Cache Operations

Note

This feature is only available in NCache Enterprise Edition.

This section explains the use of Write-Through provider after configuring and deploying it. NCache provides Alachisoft.NCache.Runtime.Caching.WriteThruOptions class to specify WriteThru options in APIs. WriteThruOptions class contains enum ReadMode which can either be WriteThru or WriteBehind explained below.

WriteThru updates data in data source synchronously after updating cache store.
WriteBehind updates data in data source asynchronously after updating cache store.

Multiple Write-Through providers can be configured through NCache. Default Write-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.

Important

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

JDK 11 is installed.
Environment variable for Java is set.

Install the following NuGet package in your application:
- Enterprise: Alachisoft.NCache.SDK
To utilize the APIs, include the following namespaces in your application:
- Alachisoft.NCache.Runtime.DatasourceProviders
- Alachisoft.NCache.Runtime.Caching
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.Exceptions
Cache must be running.
The application must be connected to cache before performing the operation.
Make sure that the data being added is serializable.
For API details refer to: CacheItem, Get, Insert(), InsertAsync(), Remove(), RemoveAsync(), IWriteThruProvider.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Add the following Maven dependencies in your pom.xml file:

<dependency>
    <groupId>com.alachisoft.ncache</groupId>
    <artifactId>ncache-client</artifactId>
    <version>x.x.x</version>
</dependency>

Import the following packages in your application:
- import com.alachisoft.ncache.runtime.exceptions.*
- import com.alachisoft.ncache.client.*
- import com.alachisoft.ncache.runtime.datasourceprovider.*
Cache must be running.
The application must be connected to cache before performing the operation.
Make sure that the data being added is serializable.
For API details refer to: CacheItem , insert(), insertAsync, remove(), removeAsync, WriteThruProvider.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Add/Update with Write-Through

The following example creates a new cacheItem and adds this item in the cache with Write-Through enabled, using the Insert() method. Using this method if the item is already present in the cache, the old value will be over-written with the new value.

.NET/.NET Core
Java

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

  // Fetch product with the given ProductID
  Product product = FetchProductByProductID(1001);

  // Specify the key of the item 
  string key = $"product.ProductID";
  product.UnitPrice = 200;

  // Create a new cacheItem with the product
  var cacheItem = new CacheItem(product);       

  // Enable write through for the cacheItem created
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.Mode = WriteMode.WriteThru;

  // Add the item in the cache with WriteThru enabled
  CacheItemVersion itemVersion = cache.Insert(key, cacheItem, writeThruOptions);
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else if (ex.ErrorCode == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED)
  {
    // Synchronization of data with backing source is failed due to any error
  }
  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
}

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

  // Fetch product with the given ProductID
  Product product = fetchProductByProductID(1001);

  // Specify the key of the item
  String key = product.getProductID();
  product.setUnitPrice(200);

  // Create a new cacheItem with the product
  var cacheItem = new CacheItem(product);

  // Enable write through for the cacheItem created
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.setMode(WriteMode.WriteThru);

  // Add the item in the cache with WriteThru enabled
  CacheItemVersion itemVersion = cache.insert(key,cacheItem,writeThruOptions);
} catch (OperationFailedException ex) {
  if (ex.getErrorCode() == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE) {
    // Backing source is not available
  } else if (ex.getErrorCode() == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED) {
    // Synchronization of data with backing source is failed due to any error
  } else {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
} catch (Exception ex) { 
  // Any generic exception like NullPointerException or IllegalArgumentException
}

Bulk Operations

Add/Update Bulk Items with Write-Through

The following example adds bulk items in the cache with Write-Through enabled, using the InsertBulk() method. If the items are already present in the cache, new values overwrite the existing values.

.NET/.NET Core
Java

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

  // Fetch all products from database
  Product[] products = FetchProductsFromDB();

  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.Mode = WriteMode.WriteThru;

  IDictionary<string, CacheItem> dictionary = new Dictionary<string, CacheItem>();
  foreach(var product in products)
  {
    string key = $"Product:{product.ProductID}";
    var cacheItem = new CacheItem(product);
    dictionary.Add(key, cacheItem);
  }

  IDictionary<string, Exception> keysFailedToUpdate = cache.InsertBulk(dictionary, writeThruOptions);
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else if (ex.ErrorCode == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED)
  {
    // Synchronization of data with backing source is failed due to any error
  }
  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
}

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

  // Fetch all products from database
  Product[] products = fetchProductsFromDB();

  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.setMode(WriteMode.WriteThru);

  HashMap<String,CacheItem> distributedMap = new HashMap<String, CacheItem>();
  for (var product: products) {
    String key = "Product:" + product.getProductID();
    var cacheItem = new CacheItem(product);
    distributedMap.put(key,cacheItem);
  }

  Map<String,Exception> keysFailedToUpdate = cache.insertBulk(distributedMap,writeThruOptions);
} catch (OperationFailedException ex) {
  if (ex.getErrorCode() == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE) {
    // Backing source is not available
  } else if (ex.getErrorCode() == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED) {
    // Synchronization of data with backing source is failed due to any error
  } else {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
} catch (Exception ex)
{
  // Any generic exception like NullPointerException or IllegalArgumentException
}

Remove Items in Bulk with Write-Through

The following example removes a bulk of items from the cache with Write-Behind enabled, using the RemoveBulk() method.

.NET/.NET Core
Java

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

  // Get Keys
  Product[] products = FetchProductsFromDB();

  // Specify keys to remove from cache 
  string[] keys = new string[products.Length];
  int index = 0;

  foreach (var product in products)
  {
    keys[index] = $"Product:{product.ProductID}";
    index++;
  }

  // Create dictionary to store removed items
  IDictionary<string, Product> removedItems = new Dictionary<string,Product>();

  // Configure write thru
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.Mode = WriteMode.WriteThru;

  // Remove items with write-behind enabled
  cache.RemoveBulk(keys, out removedItems, writeThruOptions);
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else if (ex.ErrorCode == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED)
  {
    // Synchronization of data with backing source is failed due to any error
  }
  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
}
protected void OnDataSourceItemsRemoved(IDictionary iDict)
{
  //Perform appropriate actions upon response
}

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

  // Get Keys
  Product[] products = fetchProductsFromDB();

  // Specify keys to remove from cache
  String[] keys = new String[products.length];
  int index = 0;
  for (var product: products) {
    keys[index] = "Product" + product.getProductID(); 
    index++;
  }

  // Create dictionary to store removed items
  Map<String,Product> removedItems = new HashMap<String,Product>();

  // Configure write thru 
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.setMode(WriteMode.WriteThru);

  // Remove items with write-behind enabled
  cache.removeBulk(Arrays.asList(keys),writeThruOptions,Product.class);
} catch (OperationFailedException ex) {
  if (ex.getErrorCode() == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE) {
    // Backing source is not available
  } else if (ex.getErrorCode() == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED) {
    // Synchronization of data with backing source is failed due to any error
  } else {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  } 
} catch (Exception ex) { 
  // Any generic exception like NullPointerException or IllegalArgumentException
}

Note

Use the method OnDataSourceItemsRemoved() to perform operations after data removal.

Remove an Existing Item with Write-Through

The following example removes an item from the cache with Write-Through enabled, using the Remove() method.

.NET/.NET Core
Java

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

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

  // Enable write through for the cacheItem created
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.Mode = WriteMode.WriteThru;

  // Remove the item corresponding to the key with write-through enabled
  cache.Remove(key, null, null, writeThruOptions);
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else if (ex.ErrorCode == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED)
  {
    // Synchronization of data with backing source is failed due to any error
  }
  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
}

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

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

  // Enable write through for the cacheItem created
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.setMode(WriteMode.WriteThru);

  // Remove the item corresponding to the key with write-through enabled
  cache.remove(key,writeThruOptions,Product.class);
} catch (OperationFailedException ex) {
  if (ex.getErrorCode() == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE) {
    // Backing source is not available
  } else if (ex.getErrorCode() == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED) {
    // Synchronization of data with backing source is failed due to any error
  } else {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
} catch (Exception ex) {
  // Any generic exception like NullPointerException or IllegalArgumentException
}

Asynchronous Operations

Add/Update Item with Write-Through

The following example adds item asynchronously in cache with Write-Through enabled, using the InsertAsync() method.

.NET/.NET Core
Java

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

  // Get product from database against given product ID
  Product product = FetchProductFromDB(1001);

  // Generate a unique cache key for this product
  string key = $"Product:{product.ProductID}";

  var cacheItem = new CacheItem(product);

  // Enable write behind for the cacheItem created
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.Mode = WriteMode.WriteThru;

  // Add Product object to cache
  Task task = cache.InsertAsync(key, cacheItem, writeThruOptions);
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else if (ex.ErrorCode == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED)
  {
    // Synchronization of data with backing source is failed due to any error
  }
  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
}

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

  // Get product from database against given product ID
  Product product = fetchProductFromDB(1001);

  // Generate a unique cache key for this product
  String key = "Product:" + product.getProductID();
  var cacheItem = new CacheItem(product);

  // Enable write behind for the cacheItem created
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.setMode(WriteMode.WriteThru);

  // Add Product object to cache
  FutureTask task = cache.insertAsync(key,cacheItem,writeThruOptions);
} catch (OperationFailedException ex) {
  if (ex.getErrorCode() == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE) {
    // Backing source is not available
  } else if (ex.getErrorCode() == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED) {
    // Synchronization of data with backing source is failed due to any error
  } else {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
} catch (Exception ex) {
  // Any generic exception like NullPointerException or IllegalArgumentException
}

Remove Item with Write-Through

The following example removes existing items asynchronously from the cache with Write-Through enabled, using the RemoveAsync() method.

.NET/.NET Core
Java

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

  // Unique cache key of product to remove
  string key = $"Product:{product.ProductID}";

  // Enable write behind for the cacheItem created
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.Mode = WriteMode.WriteThru;

  // Asynchronously remove items from cache
  Task<Product> task = cache.RemoveAsync<Product>(key, writeThruOptions);
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else if (ex.ErrorCode == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED)
  {
    // Synchronization of data with backing source is failed due to any error
  }
  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
}

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

  // Unique cache key of product to remove
  String key = "Product:" + product.getProductID();

  // Enable write behind for the cacheItem created
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.setMode(WriteMode.WriteThru);

  // Asynchronously remove items from cache
  FutureTask<Product> task = cache.removeAsync(key,writeThruOptions,Product.class);
} catch (OperationFailedException ex) {
  if (ex.getErrorCode() == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE) {
    // Backing source is not available
  } else if (ex.getErrorCode() == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED) {
    // Synchronization of data with backing source is failed due to any error
  } else {
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
  }
} catch (Exception ex) {
  // Any generic exception like NullPointerException or IllegalArgumentException
}

Use Data Structures with Write-Through

The following example uses different data structures with Write-Through enabled, on the specified item.

.NET/.NET Core
Java

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

  // Specify the key of the item
  string key = $"Product:{product.ProductID}";
  var dataTypeAttributes = new DataTypeAttributes();
  var writeThruOptions = new WriteThruOptions(WriteMode.WriteThru, WriteThruProviderName);

  switch(mainMenu)
  {
    case mainMenu.GetDistributedCounter:
      // Modify or add count of the corresponding item with write thru enabled
      var distributedCounter = cache.DataTypeManager.CreateCounter("counter", dataTypeAttributes, 0, writeThruOptions);

      // perform operations on counter
      break;  
    case mainMenu.GetDistributedDictionary:
      // Modify or add dictionary of the corresponding item with write thru enabled
      var distributedDictionary = cache.DataTypeManager.CreateDictionary<string, int>(key, dataTypeAttributes, writeThruOptions);

      // perform operations on dictionary
      break;
    case mainMenu.GetDistributedList:
      // Modify or add the list of the corresponding item with write thru enabled
      var distributedList = cache.DataTypeManager.CreateList<int>("list", dataTypeAttributes, writeThruOptions);

      // perform operations on list
      break;
    case mainMenu.GetDistributedQueue:
      // Modify or add the queue of the corresponding item with read thru enabled  
      var distributedQueue = cache.DataTypeManager.CreateQueue<int>("queue", dataTypeAttributes, writeThruOptions);

      // perform operations on queue
      break;
    case mainMenu.GetDistributedHashSet:
      // Modify or add the HashSet of the corresponding item with read thru enabled
     var distributedHashSet = cache.DataTypeManager.CreateHashSet<int>("hashset", dataTypeAttributes, writeThruOptions); 

      // perform operations on hashset
      break;
  }  
}
catch (OperationFailedException ex)
{
  if (ex.ErrorCode == NCacheErrorCodes.BACKING_SOURCE_NOT_AVAILABLE)
  {
    // Backing source is not available
  }
  else if (ex.ErrorCode == NCacheErrorCodes.SYNCHRONIZATION_WITH_DATASOURCE_FAILED)
  {
    // Synchronization of data with backing source is failed due to any error
  }
  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
}

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

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

  // Specify the WriteThruOptions
  var writeThruOptions = new WriteThruOptions();
  writeThruOptions.setMode(WriteMode.WriteThru);
  writeThruOptions.getWriteThruOptions().setProviderName(WriteThruProviderName);

  switch(mainMenu) {
    case GetDistributedCounter:
      // Modify or add counter of the corresponding item with write thru enabled      
      Counter distributedCounter = cache.getDataStructuresManager().createCounter("counter", 0, dataStructureAttributes, writeThruOptions);

      // Perform operations on counter
      break;  
    case GetDistributedDictionary:
      // Modify or add dictionary of the corresponding item with write thru enabled      
      DistributedMap<String,Integer> distributedMap = cache.getDataStructuresManager().createMap<String,Integer>(key, dataStructureAttributes, writeThruOptions);

      // Perform operations on dictionary
      break;
    case GetDistributedList:   
      // Modify or add list of the corresponding items with write thru enabled      
      DistributedList<String,Integer> distributedList = cache.getDataStructuresManager().createList<String,Integer>("list", dataStructureAttributes, writeThruOptions);

      // Perform operations on list
      break;
    case GetDistributedQueue:    
      // Modify or add the queue of the corresponding item with write thru enabled      
      DistributedQueue<String,Integer> distributedQueue = cache.getDataStructuresManager().createQueue<String,Integer>("queue", dataStructureAttributes, writeThruOptions);

      // Perform operations on queue    
      break;
    case GetDistributedHashSet:      
      // Modify or add the HashSet of the corresponding item with write thru enabled      
      DistributedHashSet<String,Integer> distributedHashSet = cache.getDataStructuresManager().createHashSet<String,Integer>("hashset", dataStructureAttributes, writeThruOptions);

      // Perform operations on hashset    
      break;
  } 
}
catch (OperationFailedException ex) {
  if (ex.getErrorCode() == 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 NullPointerException or IllegalArgumentException
}

Additional Resources

NCache provides sample application for Write-Through on GitHub.

Using Write-Through with Cache Operations

Note

Important

Prerequisites

Add/Update with Write-Through

Bulk Operations

Add/Update Bulk Items with Write-Through

Remove Items in Bulk with Write-Through

Note

Remove an Existing Item with Write-Through

Asynchronous Operations

Add/Update Item with Write-Through

Remove Item with Write-Through

Use Data Structures with Write-Through

Additional Resources

See Also