What is the primary benefit of using Groups in NCache?

Groups allow for logical categorization of cache data. By assigning items to a group, you can perform bulk management and organizational tasks on specific datasets within the distributed cache.

Can a single cache item belong to multiple groups?

No, NCache groups have a one-to-one relationship with cache items. A single item can be associated with only one group at a time.

Should I use Add or Insert when working with Groups?

The Insert method is recommended for groups. While Add fails if a key already exists, Insert will either add the new item or update the existing item and its group metadata.

Add/Update Cache Data with Groups [Deprecated]

NCache allows users to add items in cache as part of a certain group. There can only be a single item associated with a single group. 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 a property of groups.

The CacheItem is added to the cache using the Insert method, a recommended approach with the group if no item already exists in the cache with the specified key. Whereas, the Add operation fails if the key already exists and an exception will be thrown.

Prerequisites

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

Install the following NuGet packages in your .NET client application:
- Enterprise: Alachisoft.NCache.SDK
- Open Source: Alachisoft.NCache.Opensource.SDK
Include the following namespaces in your application:
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.Exceptions
The cache must be running.
Make sure that the data being added is serializable.
Custom classes/searchable attributes must be indexed as explained in Configuring Query Indexes.
For API details, refer to: ICache, CacheItem, Add, Insert, Group, GetCacheItem.

Add the following Maven dependencies for your Java client application in pom.xml file:

<dependency>
    <groupId>com.alachisoft.ncache</groupId>
    <!--for NCache Enterprise-->
    <artifactId>ncache-client</artifactId>
    <version>x.x.x</version>
</dependency>

Import the following packages in your Java client application:
- import com.alachisoft.ncache.client.*;
- import com.alachisoft.ncache.runtime.exceptions.*;
The cache must be running.
Make sure that the data being added is serializable.
Custom classes/searchable attributes must be indexed as explained in Configuring Query Indexes.
For API details, refer to: Cache, CacheItem, insert, add, setGroup, getCacheItem.

Create a new Console Application.
Install either of the following NuGet packages in your .NET client application:
- Enterprise: Install-Package Alachisoft.NCache.SDK -Version 4.9.1.0
Make sure that the data being added is serializable.
Add NCache References by locating %NCHOME%\NCache\bin\assembly\4.0 and adding Alachisoft.NCache.Web and Alachisoft.NCache.Runtime as appropriate.
Include the Alachisoft.NCache.Web.Caching namespace in your application.
To learn more about the NCache Legacy API, please download the NCache 4.9 documents available as a .zip file on the Alachisoft Website.

Add Cache Data with Groups

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

try
{
  // Precondition: Cache is already connected

  // In an online-store, customers from different regions need to be grouped accordingly
  // A customer has signed in to the website from the East Coast region

  // Create a unique cache key for this customer
  string customerKey = $"Customer:ALFKI";

  // Get customer from cache
  Customer customer = cache.Get<Customer>(customerKey);

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

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

      // Specify the group
      cacheItem.Group = "East Coast Customers";

      // Add customer object to cache with group and metadata
      cache.Add(customerKey, cacheItem);
  }

  // CacheItem is successfully added in the cache with group
}
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
}

try
{
  // Precondition: Cache is already connected

  // In an online-store, customers from different regions need to be grouped accordingly
  // A customer has signed in to the website from the East Coast region

  // Create a unique cache key for this customer
  String customerKey = "Customer:ALFKI";

  // Get customer from cache
  Customer customer = cache.get(customerKey, Customer.class);

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

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

      // Specify the group 
      cacheItem.setGroup("East Coast Customers");

      // Add customer object to cache with group and metadata
      cache.Add(customerKey, cacheItem);
  }

  // CacheItem is successfully added in the cache with group
}
catch (Exception ex) 
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
    // Any generic exception
}

try:
    # Precondition: Cache is already connected

    # In an online-store, customers from different regions need to be grouped accordingly
    # A customer has signed in to the website from the East Coast region

    # Create a unique cache key for this customer
    customer_key = "Customer:ALFKI"

    # Get customer from cache
    cache_item = cache.get_cacheitem(customer_key)
    customer = cache_item.get_value(Customer) if cache_item else None

    # Get customer from database if not found in cache
    if customer is None:
        customer = fetch_customer_from_db("ALFKI")

        # Create CacheItem 
        cache_item = CacheItem(customer)

        # Specify the group
        cache_item.set_group("East Coast Customers")

        # Add customer object to cache with group and metadata
        cache.add(customer_key, cache_item)

    # CacheItem is successfully added in the cache with group

except Exception as error:
    print("An error occurred:", str(error))

try
{
  // Precondition: Cache is already connected
  // This is an async method

  // In an online-store, customers from different regions need to be grouped accordingly
  // A customer has signed in to the website from the East Coast region

  // Create a unique cache key for this customer
  const customerKey = "Customer:ALFKI";

  // Get customer from cache
  let cacheItem = await cache.getCacheItem(customerKey);
  let customer = cacheItem ? JSON.parse(cacheItem.getValue()) : null;

  // Get customer from database if not found in cache
  if (!customer) 
  {
      customer = fetchCustomerFromDB("ALFKI");

      // Create a new CacheItem
      cacheItem = new CacheItem(JSON.stringify(customer));

      // Step 5: Specify group
      cacheItem.setGroup("East Coast Customers");

      // Add customer object to cache with group and metadata
      await cache.add(customerKey, cacheItem);
  }


  // CacheItem is successfully added in the cache with group
}
catch(error)
{
    // Handle errors
}

// Using NCache Enterprise 4.9.1
try
{
  // Precondition: Cache is already connected
  string customerId = "ALFKI";

  // Create a unique cache key for this customer
  string customerkey = "Customer:" + customerId;

  // Get the customer from cache
  Customer customer = (Customer)cache.Get(customerkey);

  if (customer == null)
  {
      // Fetch customer from DB if not found in cache
      customer = FetchCustomerFromDB(customerId);

      // Specify the group
      string groupName = "Customer";
      string subGroupName = "East Coast";

      CacheItem cacheItem = new CacheItem(customer);
      cacheItem.Group = groupName;
      cacheItem.SubGroup = subGroupName;

      // Add customer to cache with group and subgroup
      cache.Add(customerkey, cacheItem);
  }

  // CacheItem is successfully added in the cache with group
}
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
}

Note

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

Update Group of a CacheItem

The data group of a CacheItem can also be updated. A CacheItem is a custom class provided by NCache that can be used to add data to the data cache. The CacheItem also lets you set the group as a property of the CacheItem.

The following example updates the group in a CacheItem.

// Precondition: Cache is already connected
// A customer has signed in to the website from a different region, i.e., West Coast
string customerKey = $"Customer:ALFKI";

// Retrieve the cacheItem from the cache
var cacheItem = cache.GetCacheItem(customerKey);

// Specify the new group to be updated
cacheItem.Group = "West Coast Customers";

// Reinsert the cacheItem in the cache with updated groups
cache.Insert(customerKey, cacheItem);

// CacheItem is successfully added in the cache with updated group

// Precondition: Cache is already connected
// A customer has signed in to the website from a different region, i.e., West Coast
String customerKey = "Customer:ALFKI";

// Retrieve the cacheItem from the cache
CacheItem cacheItem = cache.getCacheItem(customerKey);

// Specify the new group to be updated
cacheItem.setGroup("West Coast Customers");

// Reinsert the cacheItem in the cache with updated groups
cache.insert(customerKey, cacheItem);

// CacheItem is successfully added in the cache with updated group

# Precondition: CacheItem is added with the group
# A customer has signed in to the website from a different region, i.e., West Coast
customer_key = "Customer:ALFKI"

# Retrieve the CacheItem from the cache
cache_item = cache.get_cacheitem(customer_key)

# Specify the new group to be updated
cache_item.set_group(new_group)

# Re-insert the cacheItem into the cache with updated group
cache.insert(customer_key, cache_item)

# CacheItem is successfully added in the cache with updated group

// Precondition: Cache is already connected
// This is an async method
// A customer has signed in to the website from a different region, i.e., West Coast
const customerKey = "Customer:ALFKI";

// Retrieve the cacheItem from the cache
let cacheItem = await cache.getCacheItem(customerKey);

// Specify the new group to be updated
cacheItem.setGroup("West Coast Customers");

// Reinsert the cacheItem in the cache with updated groups
await cache.insert(customerKey, cacheItem);

// CacheItem is successfully added in the cache with updated group

Additional Resources

NCache provides a sample application for Groups on GitHub.