Using Write-Behind with Cache Operations

Note

This feature is only available in NCache Enterprise Edition.

This section explains the use of Write-Behind mode after deploying and configuring the Write-Through provider. Write-Behind updates the data source asynchronously after updating the cache store.

Important

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

JDK 11 is installed.
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, Insert, IWriteThruProvider, Remove, InsertBulk, RemoveBulk, InsertAsync, RemoveAsync.

Add/Update with Write-Behind

You can add/update cache items with or without callback in the cache along with Write-Behind enabled. Adding with callback notifies you on the type of event occurred which you register.

Add without Callback Method

The following example adds an item in the cache with Write-Behind enabled, using the Insert() method. Using this method, if an item is already present in the cache, the new value overwrites the old value.

.NET/.NET Core
Java

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

  // Specify the key of the cacheItem
  Product product = FetchProductByProductID(1001);
  string key = $"product:ProductID";
  var cacheItem = new CacheItem(product);

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

  // Add item in the cache with write-behind  
  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

  // Specify the key of the cacheItem
  String key = product.getProductID();
  var cacheItem = new CacheItem(product);

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

  // Add item in the cache with write-behind
  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
}

Note

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

Add with Callback Method

The following example adds an item in the cache with callback registered and event type of ItemAdded with Write-Behind enabled.

.NET/.NET Core
Java

// Specify the key of the cacheItem
Product product = FetchProductByProductID(1001);
string key = $"product:ProductID";
var cacheItem = new CacheItem(product);

// Enable write through for the cacheItem created
var writeThruOptions = new WriteThruOptions();
writeThruOptions.Mode = WriteMode.WriteBehind;
writeThruOptions.SetDataSourceNotification(DataSourceModifiedCallBack, EventType.ItemAdded);

// Add item in the cache with write-behind  
cache.Insert(key, cacheItem, writeThruOptions);

// Specify the key of the cacheItem
String key = product.getProductID();
var cacheItem = new CacheItem(product);

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

// assuming that DataSourceModified has been implemented as interface before
EnumSet<EventType> eventTypes = EnumSet.of(EventType.ItemAdded);
writeThruOptions.setDataSourceModificationListener(dataSourceModifiedListener, eventTypes);

// Add item in the cache with write-behind
cache.insert(key,cacheItem,writeThruOptions);

Remove Existing Data with Write-Behind

The following example removes the item from the cache with Write-Behind enabled, using the Remove method, corresponding to the key provided as well as from the data source and registers the events for the operation.

.NET/.NET Core
Java

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

// Enable write through for the cacheItem created
var writeThruOptions = new WriteThruOptions();
writeThruOptions.Mode = WriteMode.WriteBehind;
writeThruOptions.SetDataSourceNotification(DataSourceModifiedCallBack, EventType.ItemRemoved);

// Remove the item corresponding to the key with write-through enabled
cache.Remove(key, null, null, writeThruOptions);

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

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

EnumSet<EventType> eventTypes = EnumSet.of(EventType.ItemRemoved);
writeThruOptions.setDataSourceModificationListener(dataSourceModifiedListener, eventTypes);

// Remove the item corresponding to the key with write-through enabled
cache.remove(key,writeThruOptions,Product.class);

Bulk Operations

Add/Update Bulk Items with Write-Behind

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

.NET/.NET Core
Java

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

var writeThruOptions = new WriteThruOptions();
writeThruOptions.Mode = WriteMode.WriteBehind;
writeThruOptions.SetDataSourceNotification(DataSourceModifiedCallBack, EventType.ItemAdded);
writeThruOptions.SetDataSourceNotification(DataSourceModifiedCallBack, EventType.ItemUpdated);

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);

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

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

EnumSet<EventType> eventTypes = EnumSet.of(EventType.ItemAdded);
eventTypes.add(EventType.ItemUpdated);
writeThruOptions.setDataSourceModificationListener(dataSourceModifiedListener,eventTypes);

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

Map<String,Exception> keysFailedToUpdate = cache.insertBulk(distributedMap,writeThruOptions);

Remove Existing Items with Write-Behind

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

.NET/.NET Core
Java

// 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>();

var writeThruOptions = new WriteThruOptions();
writeThruOptions.Mode = WriteMode.WriteBehind;
writeThruOptions.SetDataSourceNotification(DataSourceModifiedCallBack, EventType.ItemRemoved);

// Remove items with write-behind enabled
cache.RemoveBulk(keys, out removedItems, writeThruOptions);

// 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>();

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

EnumSet<EventType> eventTypes = EnumSet.of(EventType.ItemRemoved);
writeThruOptions.setDataSourceModificationListener(dataSourceModifiedListener,eventTypes);

// Remove items with write-behind enabled
cache.removeBulk(Arrays.asList(keys),writeThruOptions,Product.class);

Note

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

Asynchronous Operations

Add/Update Item with Write-Behind

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

.NET/.NET Core
Java

// 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.WriteBehind;
writeThruOptions.SetDataSourceNotification(DataSourceModifiedCallBack, EventType.ItemAdded);

// Add Product object to cache
Task task = cache.InsertAsync(key, cacheItem, writeThruOptions);

// 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.WriteBehind);

EnumSet<EventType> eventTypes = EnumSet.of(EventType.ItemAdded);
writeThruOptions.setDataSourceModificationListener(dataSourceModifiedListener,eventTypes);

// Add Product object to cache
FutureTask task = cache.insertAsync(key,cacheItem,writeThruOptions);

Remove Item with Write-Behind

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

.NET/.NET Core
Java

// 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.WriteBehind;
writeThruOptions.SetDataSourceNotification(DataSourceModifiedCallBack, EventType.ItemRemoved);

// Asynchronously remove items from cache
Task<Product> task = cache.RemoveAsync<Product>(key, writeThruOptions);

// 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.WriteBehind);

EnumSet<EventType> eventTypes = EnumSet.of(EventType.ItemRemoved);
writeThruOptions.setDataSourceModificationListener(dataSourceModifiedListener,eventTypes);

// Asynchronously remove items from cache
FutureTask<Product> task = cache.removeAsync(key,writeThruOptions,Product.class);

Use Data Structures with Write-Behind

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

.NET/.NET Core
Java

// Specify the key of the item
string key = "Product:1001";
var dataTypeAttributes = new DataTypeAttributes();
var writeThruOptions = new WriteThruOptions(WriteMode.WriteBehind, 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;
}

// Specify the key of the item
String key = "Product:1001";
DataStructureAttributes dataStructureAttributes = new DataStructureAttributes();

// Specify the WriteThruOptions
var writeThruOptions = new WriteThruOptions();
writeThruOptions.setMode(WriteMode.WriteBehind);
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;
}

Additional Resources

NCache provides sample application for Write-Behind on GitHub.

Using Write-Behind with Cache Operations

Note

Important

Prerequisites

Add/Update with Write-Behind

Add without Callback Method

Note

Add with Callback Method

Remove Existing Data with Write-Behind

Bulk Operations

Add/Update Bulk Items with Write-Behind

Remove Existing Items with Write-Behind

Note

Asynchronous Operations

Add/Update Item with Write-Behind

Remove Item with Write-Behind

Use Data Structures with Write-Behind

Additional Resources

See Also