Add/Update Cache Data with Tags

Note

This feature is only available in NCache Enterprise Edition.

NCache allows the user to create tags and then add items to the cache with tags. The user can also add tag through CacheItem. Moreover, the tags can be updated as well as new tags can be appended to an already existing tag list.

Pre-Requisites

• .NET/.NET Core
• Java

• Include the following namespace in your application:
  • Alachisoft.NCache.Client
  • Alachisoft.NCache.Runtime.Caching
  • Alachisoft.NCache.Runtime.Exceptions
• 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.

Tag Data

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

Warning

• If the key already exists, an exception will be thrown.
• Providing Null tag array will throw an ArgumentNullException.

The following example adds a CacheItem containing the object customer to the cache using the Insert method. It then sets an additional tag property against it by adding the tags tags. In the java section, the setTags property of the CacheItem adds tags with it and then the CacheItem is added in the cache using the add method.

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.

• .NET/.NET Core
• Java

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}";

    // Specify Tags
    Tag[] tags = new Tag[2];
    tags[0] = new Tag("East Coast Customers");
    tags[1] = new Tag("Important Customers");

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

    // Setting the tag property of the cacheItem
    cacheItem.Tags = tags;

    // Add customer object to cache
    CacheItemVersion version = cache.Add(key, cacheItem);

    // CacheItem added successfully
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    if(ex.ErrorCode == NCacheErrorCodes.KEY_ALREADY_EXISTS)
    {
        // An item with the same key already exists
    }
    else
    {
        // Exception can occur due to:
        // Connection Failures 
        // Operation Timeout
        // Operation performed during state transfer
    }
}
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.

Update Data with Tags

Updating tags through CacheItem requires the item to be first fetched, its tags to be modified and then re-inserted to the cache using the Insert method. In java, the item with new tags is reinserted in the cache using the insert method.

Following example first fetches the CacheItem, creates a tag list with the new tags and then re-inserts the CacheItem in the cache along with the modified tag list. Hence, overrides the value of existing tags.

Warning

Providing Null tag array will throw an ArgumentNullException.

• .NET/.NET Core
• Java

try
{
    // Get cache item from cache against given key
    string key = "ALFKI";
    var cacheItem = cache.GetCacheItem(key);

    // Create new Tag array
    Tag[] newTags = new Tag[2];

    // Specify Tags
    newTags[0] = new Tag("US Customers");
    newTags[1] = new Tag("VIP Customers");

    // Updates the tags with the new tags
    // Overrides the value of the existing tags
    cacheItem.Tags = newTags;

    //Re-inserts the cacheItem into cache with modified tags
    cache.Insert(key, cacheItem);   
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
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.

Append Tags to Already Existing Tags

If there is a need to append a new tag to the already present tags or if a tag needs to be removed from the already present tags, the operation would require manipulating the tags array. For this purpose, create a new list with the tags to append and copy that list to the array containing the tags already. This way a new tag would be added to the array containing the tags previously created without affecting them.

Following example appends new tags to already existing tag list tags.

Warning

Providing Null tag array will throw an ArgumentNullException.

try
{
    // Get customer from database against the given key
    string key = "ALFKI";
    CacheItem cachedCustomer = cache.GetCacheItem(key);

    var customerTags = new List<Tag>();

    // Initialize the list with existing tags
    customerTags = new List<Tag>(cachedCustomer.Tags);

    // Add new tags to existing list of tags
    customerTags.Add(new Tag("VIP Cutsomers"));
    customerTags.Add(new Tag("US Customers"));

    // Assign newly built tag list to the   cached customer object.
    cachedCustomer.Tags = customerTags.ToArray();

    // Update the modified customer object in cache
    cache.Insert(key, cachedCustomer);
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures 
    // Operation Timeout
    // Operation performed during state transfer
}
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.

Additional Resources

NCache provides sample application for Tags at:

• GitHub
• Shipped with NCache: %NCHOME%\samples\dotnet\GroupsAndTags

See Also

Use Groups for Logical Data Grouping
Retrieve Cache Data with Tags
Remove Cache Data with Tags
Search Tag Data in Cache with SQL
Delete Tag Data from Cache with SQL
Named Tags with Cache Data