Add/Update Data in Cache with Group

NCache allows the user to add an item in cache with a certain group and sub-group. There can only be a single item associated with a single group.

Pre-Requisites for Adding Data with Groups

Include the following namespace in your application:
- Alachisoft.NCache.Web.Caching
- Alachisoft.NCache.Runtime
The application must be connected to cache before performing the operation.
Cache must be running.
Make sure that the data being added is serializable.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Add Data to Cache with Groups

Important

Group and sub group identifiers are case sensitive.
Groups and subgroups are string based identifiers only.
A group can also have no subgroup whereas every subgroup will be associated to a group.
Passing null to this API for group will throw ArgumentNullException.

The following example adds an item to cache with the data group identifier 'Important Customers' and sub group identifier 'East Coast Customers'. In this example, you can use Add operation to set group and sub-group of the item. In order to get more detail on adding data with using the Add method, please refer to Add Data to Cache section.

However, using the Insert method is a recommended approach. Using the Insert method, the item will be added in the cache with group and sub-group if no item already exists in the cache with the specified key.

Whereas the Insert operation fails if the key already exists and an exception will be thrown.

Warning

If the key already exists, an exception will be thrown.
Providing Null group or subgroup will throw an ArgumentNullException.

Tip

One quick way to verify whether item has been added is to use either properties of the Cache class:

Count returns the number of items present in the cache.
Contains verifies if a specified key exists in the cache.

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

    // Get customer from database
    Customer customer = FetchCustomerFromDB("ALFKI");

    // Create a unique cache key for this customer.
    string key = $"Customers:{customer.CustomerID}";

    // Creating groups and sub-groups
    string groupName = "Important Customers";
    string subGroupName = "East Coast Customers";

    // Adding an item with the group and sub-group
    // Item will only be added if an item does not exist
    // already with the same key
    cache.Insert(key, customer, groupName, subGroupName);

    // Item is successfully added in the cache with group and sub-group
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    if (ex.Message.Contains("Data group of the inserted item does not match the existing item's data group"))
    {
        // If the key already exists in the cache with a different
        // or NULL group/sub-group
    }
    else if(ex.Message.Contains("group must be specified for sub group"))
    {
        // If sub-group is added without a group
    }
    else
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation performed during state transfer
        // Operation Timeout
    }
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

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

Add CacheItem to Cache with Groups

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

CacheItem is added in the cache using the Insert method is a recommended approach with group and sub-group if no item already exists in the cache with the specified key.

Whereas the Insert operation fails if the key already exists and an exception will be thrown.

In the following example, data group is set by assigning it as a property of CacheItem containing the object customer.

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

    // Get customer from database against given customer ID
    Customer customer = FetchCustomerFromDB("ALFKI");

    // Create a unique cache key for this customer.
    string key = $"Customers:{customer.CustomerID}";

    // Create a new CacheItem
    CacheItem cacheItem = new CacheItem(customer);

    // Specify the group and sub-group name
    cacheItem.Group = "Important Customers";
    cacheItem.SubGroup = "East Coast Customers";

    // Add customer object to cache with group and sub-group
    // Item will only be added if a cacheItem does not exist
    // already with the same key
    CacheItemVersion version = cache.Insert(key, cacheItem);

    // cacheItem is successfully added in the cache with group and sub-group
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    if (ex.Message.Contains("Data group of the inserted item does not match the existing item's data group"))
    {
        // If the key already exists in the cache with a different
        // or NULL group/sub-group
    }
    else if(ex.Message.Contains("group must be specified for sub group"))
    {
        // If sub-group is added without adding a group
    }
    else
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation performed during state transfer
        // Operation Timeout
    }
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

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

Change Group of Items

if you add an item without any group or want to add group to an already cached item, you have to first remove that item from the cache and then insert/add that item with the desired group and sub group identifiers. Otherwise, the insert operation throws an exception saying Data group of the inserted item does not match the existing item's data group. Update method for group will be supported in the coming releases.

Change Group of a Custom Object

Group and sub-group can also be updated in an item using the Insert method. For using this approach set the group and sub-group as null which removes the group and sub-group already added in the cache and the re-insert the item in the cache with the updated group and sub-group.

In the following example, an item is added with a group and sub-group which is then removed by passing their null values using the Insert API. Item is then added again with the modified group and sub-group

try
{
    // Pre-condition: Item is already added with a group and a sub-group
    // Retrieve the item from the cache against the key
    object retItem = cache.Get(key);

    // Remove the group and sub-group by passing null values
    cache.Insert(key, retItem, null, null);

    // Specify new values for the group and sub-group
    string newGroupName = "US Customers";
    string newSubgroupName = "NewYork Customers";

    // Re-insert the item in the cache with the updated group and sub-group
    cache.Insert(key, retItem, newGroupName, newSubgroupName);

    // Item is successfully added with the updated group and sub-group
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation performed during state transfer
    // Operation Timeout
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

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

Change Group of a CacheItem

Data group can also be changed via CacheItem. CacheItem is a custom class provided by NCache which can be used to add data to the cache. CacheItem also lets you set group as property of the CacheItem.

In order to update group or sub-group of a CacheItem, set the group and/or sub-group property of the CacheItem as null and insert the item in the cache. After this, specify the updated group and sub-group of the CacheItem and then re-insert the CacheItem in the cache.

Following example updates group and sub-group in a CacheItem.

try
{
    // Pre-condtion: CacheItem is added with the group and sub-group

    // Retrieve the cacheItem from the cache
    string key = "ALFKI";
    CacheItem cacheItem = cache.GetCacheItem(key);

    // Set the group and sub-group property of cache as null
    cacheItem.Group = null;
    cacheItem.SubGroup = null;

    // Re-insert the item in the cache after the removal of group and sub-group
    cache.Insert(key, cacheItem);

    // Specify the new group and sub-group to be updated
    cacheItem.Group = "US Customers";
    cacheItem.SubGroup = "NewYork Customers";

    // Re-insert the cacheItem in the cache with updated groups and sub-groups
    cache.Insert(key, cacheItem);

    // CacheItem is successfully added in the cache with updated group and sub-group
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation performed during state transfer
    // Operation Timeout
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

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

Moreover, it is important to understand that for this strategy, if the value of group is set null, the value of subgroup must also be set as null. As well as if the value of group is set as an empty string, subgroup is ignored. Not following this will result in an exception saying group must be specified for sub group.

Add/Update Data in Cache with Group

Pre-Requisites for Adding Data with Groups

Add Data to Cache with Groups

Important

Warning

Tip

Add CacheItem to Cache with Groups

Change Group of Items

Change Group of a Custom Object

Change Group of a CacheItem

See Also