Update/Insert Data in Cache

NCache provides the linearly scalable Insert method and its overloads to support high-performance data updates. This API guarantees data consistency by overwriting existing items or atomically adding new entries if the key does not exist. By using Insert, applications reduce network serialization overhead and improve overall system throughput.

Prerequisites

Before using the NCache Client-side APIs, ensure that the following prerequisites are fulfilled:

How to Update Object in Cache

The Insert method is the standard approach for basic synchronization between your application layer and the distributed store. You can update a custom object in the cache using various overloads of the Insert method. This returns a CacheItemVersion.

Important
  • If the key already exists, it will overwrite the existing cache item with the same key.
  • If the key does not exist, the operation adds the item to the cache instead.
Note

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

The following example gets the values of an existing object and inserts it against the same key into the cache. If the key does not exist, it adds it to the cache.

try
{
  // Precondition: Cache is already connected
  string customerKey = $"Customer:ALFKI";

  // Get updated customer from database against given customer key
  Customer customer = FetchCustomerFromDB(customerKey);

  // Insert Customer object to cache
  CacheItemVersion version = cache.Insert(customerKey, customer);

  // Item updated in cache successfully
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

How to Update Object With Expiration

CacheItem is a custom class provided by NCache that can be used to add data to the cache and also lets you set additional specifications associated with an object as properties of this class.

The CacheItem is updated in the cache against a unique key. By assigning expiration policies to a CacheItem, the cache enables automated memory management, preventing any outdated or stale data to persist in the cache.

Important
  • If the key already exists, it will overwrite the existing cache item with the same key.
  • If the key does not exist, the operation adds the item to the cache instead.

The following example gets updated values of an existing CacheItem and inserts it against the same key into the cache. If the key does not exist, it adds it to the cache.

// Precondition: Cache is already connected
string customerKey = $"Customer:ALFKI";

// Get the customer from the database
Customer customer = FetchCustomerFromDB(customerKey);

// Update Customer's Phone
customer.Phone = "0921-12 34 65";

// Create CacheItem
CacheItem cacheItem = new CacheItem(customer);
cacheItem.Expiration = new Expiration(ExpirationType.Sliding, TimeSpan.FromMinutes(5));

// Update customer in DB and Cache
if (UpdateDB(customer))
{
    cache.Insert(customerKey, cacheItem);
}

How to Update Bulk Items in Cache

The InsertBulk API is essential for high-load scenarios, as it significantly reduces network round-trips by combining multiple update operations into a single network packet.

InsertBulk updates an array of Cache​Item to the cache against the corresponding key. The method returns a dictionary of all the keys that failed to update, along with the failure reason.

Important

If any keys fail to update, their reasons of failure will be returned as an IDictionary.

The following code example fetches an array of Customers from the database. The Customers are then inserted to the cache as a dictionary of keys and CacheItem using InsertBulk.

// Precondition: Cache is already connected
// Create an array of all Customer Keys
String[] keys = new String[]
{
    "Customer:ALFKI", "Customer:ANATR", "Customer:ANTON", "Customer:AROUT", "Customer:BERGS"
};

// Get items from cache
IDictionary<string, Customer> itemsFetched = cache.GetBulk<Customer>(keys);

// Create a dictionary to store updated items
IDictionary<string, CacheItem> itemsUpdated = new Dictionary<string, CacheItem>();

// Update postal codes of dictionary items
foreach (KeyValuePair<string, Customer> item in itemsFetched)
{
    // Update Postal Code
    item.Value.PostalCode = "05023";

    // Create CacheItem of updated Customer object
    CacheItem updatedCacheItem = new CacheItem(item.Value);

    // Add CacheItem to dictionary
    itemsUpdated.Add(item.Key,updatedCacheItem);
}

if (UpdateDB(itemsUpdated))
{
    // Insert updated bulk items to Cache
    IDictionary<string, Exception> keysFailedToInsert = cache.InsertBulk(itemsUpdated);

    if (keysFailedToInsert.Count > 0)
    {
        foreach (KeyValuePair<string, Exception> keyFailedToInsert in keysFailedToInsert)
            Console.WriteLine($"Could not update Item {keyFailedToInsert.Key} in cache due to error : {keyFailedToInsert.Value}");
    }
}

How to Update Objects with Asynchronous API

InsertAsync prevents thread-pool starvation by offloading cache operations to background threads, allowing the application to remain responsive during high-latency network events.

InsertAsync returns the object of the Task class which can further be used according to the business needs of the client application.

// Precondition: Cache is already connected
string customerKey = $"Customer:ALFKI";

// Get customer from database if not found in cache
if (customer == null)
{
    Customer customer = FetchCustomerFromDB("ALFKI");
}

// Update customer's Phone
customer.Phone = "12345-6789";

// Update customer in DB and Cache
if (UpdateDB(customer))
{
    // Adding item asynchronously.
    Task<CacheItemVersion> task = cache.InsertAsync(customerKey, customer);

    // This task object can be used as per your business needs
    if (task.IsCompleted)
    {
        // Get CacheItemVersion object from task result
        CacheItemVersion version = task.Result;
        Console.WriteLine($"Item {customer.CustomerID} has been updated with version {version.Version}.");
    }
}

Additional Resources

NCache provides a sample application for Basic Operations on GitHub.

See Also

.NET: Alachisoft.NCache.Client namespace.
Java: com.alachisoft.ncache.client namespace.
Python: ncache.client class.
Node.js: Cache class.