Key Dependency Types and Usage

Note

This feature is only available in NCache Enterprise Edition.

There are situations when you want to keep a relationship among related cache data e.g. an order depends on a product. If the product is no longer available, all the dependent orders need to be removed too. Here you can use key dependency to maintain this relationship. Key dependency creates a dependency relationship between cached items.

Note

The dependent item is removed in case of two types of modifications in the master key:

Update
Remove

In NCache, dependent cache items and the ones on which others depend are aware of this relationship. So when an item on which other items depend is removed, all dependent items will be removed. However vice versa is not possible, i.e. on removal of the orders, which has dependency on any other item e.g. products, products will not be removed.

Key(s) can have two types of dependencies:

Multilevel Dependency

A cache item can have a dependency on any number of other items in the cache; resulting in the formation of a chain. The relation in this case will be 1:1 relationship.

For example, there are three data sets in a cache i.e. Products, Orders and OrderDetails. For an order placed on a particular product, the key of the OrderDetails depends on the key of the Orders. Similarly the key of the Orders depends on the key of the Products.

Which means that if the Product is deleted the Order and the OrderDetails are also deleted. The following diagram depicts the scenario visually.

Using Multilevel key Dependency in NCache

Multiple Dependency

A single item can depend on more than one items in the cache. Similarly that item may depend on further multiple items. This may result in a 1:n relationship between the items.

For example in a cache, if an Order is placed by a Customer which contains a product, the Order depends on the Customer as well as the Product. Similarly, the OrderDetails depend on the Orders. The following diagram depicts the whole scenario visually.

Using Multiple key dependency in NCache

Here if Customer is deleted, Orders as well as OrderDetails get deleted. Similarly if the Product is deleted, Orders as well as OrderDetails get deleted.

Note

Only the existing keys in cache can be specified for key dependency. Nonexistent key specified for key dependency will result in OperationFailedException whereas an object can be specified as being dependent on another key at the time of addition.

Pre-Requisites

Install the following NuGet packages in your application:
- Alachisoft.NCache.SDK
Include the following namespace in your application:
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.Dependencies
- 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.
For API details, refer to: ICache, CacheItem, CacheItemAttributes, Dependency, UpdateAttributes.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Add the following Maven dependencies in your pom.xml file:

<dependency>
    <groupId>com.alachisoft.ncache</groupId>
    <artifactId>ncache-client</artifactId>
    <version>5.2.0</version>
</dependency>

Import the following packages in your application:
- import com.alachisoft.ncache.client.*;
- import com.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.
For API details, refer to: Cache,CacheItem, CacheItemAttributes, setDependency, updateAttributes.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Include the following modules in your application:
- const ncache = require('ncache-client')
The application must be connected to cache before performing the operation.
Cache must be running.
For API details, refer to: Cache, CacheItem, CacheItemAttributes, setDependency, updateAttributes.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Add CacheItem to Cache with Key Dependency

CacheItem is a custom class provided by NCache which can be used to add data to the cache and also lets you set additional metadata associated with an object of this class. This metadata defines the properties of the item like dependencies, expirations and more.

The Add method adds a new item in the cache whereas the Insert method adds a new item with dependency and if the item already exists in the cache it overwrites its properties.

Important

Note that this API also specifies cache item priority for eviction as well as expiration, so the value for that parameter has been passed as Default, as it is not discussed here.

The following example adds a CacheItem order to the cache using the Insert method, which is dependent on the customer in the cache which means as soon as the customer is updated or deleted, the order of the customer is already deleted from the cache.

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

      // Customer with CustomerID "ALFKI" exists in the cache
      Customer customer = FetchCustomerByCustomerID("ALFKI");

      // Specify the key of the item
      string customerKey = "Customer: ALFKI";

      // Get order against the customer from cache
      Order order = FetchOrderByCustomerId("ALFKI");

      // Generate a unique key for order
      string orderKey = $"Order:{order.OrderID}";

      // Create a new CacheItem for this order
      var cacheItem = new CacheItem(order);

      // Create a new dependncy on customer
      cacheItem.Dependency = new KeyDependency(customerKey);

      // Add/Update item with keydependency
      cache.Insert(orderKey, cacheItem);

      // For successful addition of cacheitem with dependency
      // Update the key and check if cacheitem is present in cache
      // This can be done by using
      // Cache.Contains()
      // Count
}
catch (OperationFailedException ex)
{
      // NCache specific exception

      if (ex.ErrorCode == NCacheErrorCodes.DEPENDENCY_KEY_NOT_FOUND)
      {
            // The dependent item does not exist in the cache
      }
      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 
{
      // Precondition: Cache is already connected

      // Get customer from database against given customerId 
      Customer customer = fetchCustomerFromDb(customerId);

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

      // Get orders against the customer from the cache
      Order order = fetchOrdersByCustomerId(customerId);

      // Generate a unique key for order
      String orderKey = "Order:" + order.orderId;

      // Create a new cache item for this order
      CacheItem cacheItem = new CacheItem(order);

      // Create key dependency
      cacheItem.setDependency(KeyDependency(customerKey));

      // Insert cache item with key dependency 
      cache.insert(orderKey, cacheItem);

      // For successful addition of cacheItem with dependency 
      // update the key and check if cacheItem is present in the cache
} 
catch (OperationFailedException ex) 
{
      // NCache specific exception

      if (ex.getErrorCode() == NCacheErrorCodes.DEPENDENCY_KEY_NOT_FOUND) 
      {
            // The dependent item does not exist in the cache
      } 
      else 
      {
            // Exception can occur due to:
            // Connection Failures 
            // Operation Timeout
            // Operation performed during state transfer    
      }
}
catch (Exception ex) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

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

      // Customer "ALFKI" already exists in the cache
      let customer = new Customer(this.customerId);
      customer = await this.fetchCustomerByCustomerId(this.customerId);

      // Create unique key for this customer
      let customerKey = "Customer:" + customer.CustomerId;

      // Get orders against the customer from cache
      let orders = await this.fetchOrdersByCustomerId(this.customerId);

      // Create a unique key for this order
      let orderKey = "Order:" + orders.OrderId;

      // Create a new cacheItem for this order
      var cacheItem = new ncache.CacheItem(orders);

      // Create a new key dependency on customer
      cacheItem.setDependency(new KeyDependency(customerKey));

      // Add/update item in the cache with key dependency 
      this.cache.insert(orderKey, cacheItem);

      // For successful addition of cacheitem with dependency
      // Update the key and check if cacheitem is present in cache
}
catch (error) 
{
    // Handle any errors
}

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 Key Dependency on Multiple Keys

You can also add key dependency to an item which is dependent on multiple keys. This way a single item can be dependent on multiple items using the Add or Insert method.

The Add method adds a new item in the cache whereas the Insert method adds a new item with dependency and if the item already exists in the cache it overwrites its properties.

Important

Note that this API also specifies cache item priority for eviction as well as expiration, so the value for that parameter has been passed as Default, as it is not discussed here.

The following example adds employee's data in the cache with the dependency of the employee on the territories. If any territory gets updated or deleted from the cache, the employee automatically gets deleted.

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

      // Get product from database against given ProductID
      Employee employee = FetchEmployeeByID(1);

      // Generate a unique cache key for this product
      string key = $"Employee:{employee.EmployeeID}";

      // Territories with the keys exist in the cache
      string territoryKey1 = "Territory: Westboro";
      string territoryKey2 = "Territory: Bedford";

      // Insert the keys of the territories in an array
      string[] territories = new string[1];
      territories[0] = territoryKey1;
      territories[1] = territoryKey2;

      // Create a new cacheItem containing employee
      var cacheItem = new CacheItem(employee);

      // Add KeyDependency to employee on territories
      cacheItem.Dependency = new KeyDependency(territories);

      // Add CacheItem with key dependecy on territories
      cache.Insert(key, cacheItem);

      // For successful addition of item with dependency
      // Update or remove the keys 
      // Verify if dependent key is present
}
catch (OperationFailedException ex)
{
      // NCache specific exception

      if (ex.ErrorCode == NCacheErrorCodes.DEPENDENCY_KEY_NOT_FOUND)
      {
            // The dependent item does not exist in the cache
      }
      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 
{
      // Precondition: Cache is already connected

      // Get employee from database against given employeeId
      Employee employee = fetchEmployeeFromDb(employeeId);

      // Generate a unique cache key for this employee
      String key = "Employee:" + employee.employeeId;

      // Territories with the keys exist in the cache
      String territoryKey1 = "Territory: Westboro";
      STring territoryKey2 = "Territory: Bedford";

      // Insert the keys of the territories in an array 
      String[] territories = new String[1];
      territories[0] = territoryKey1;
      territories[1] = territoryKey2;

      // Create a new cache item containing employee
      CacheItem cacheItem = new CacheItem(employee);

      // Add key dependency to employee on territories 
      cacheItem.setDependency(KeyDependency(Arrays.asList(territories)));

      // Add cache item with key dependency on territories 
      cache.insert(key, cacheItem);

      // For successful insertion of item with dependency
      // Update or remove the keys
      // Verify if dependent key is present 
}
catch (OperationFailedException ex) 
{
      // NCache specific exception

      if (ex.getErrorCode() == NCacheErrorCodes.DEPENDENCY_KEY_NOT_FOUND) 
      {
            // The dependent item does not exist in the cache
      } 
      else 
      {
            // Exception can occur due to:
            // Connection Failures 
            // Operation Timeout
            // Operation performed during state transfer    
      }
} 
catch (Exception ex) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

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

      // Get product from database against productId
      let product = await this.fetchProductFromDb(this.productId);

      // Create unique cache key for this product
      let key = "Product:" + product.ProductID;

      // Territories with the keys exist in the cache
      let territoryKey1 = "Territory: Chai";
      let territoryKey2 = "Territory: Tofu";

      // Insert territory keys to the cache
      let territories = new String[2];
      territories[0] = territoryKey1;
      territories[1] = territoryKey2;

      // Create a new cache item containing product
      let cacheItem = new ncache.CacheItem(product);

      // Add key dependency to employee on territories
      cacheItem.setDependency(new KeyDependency(territories));

      // Add cache item with dependency in the cache
      this.cache.insert(key, cacheItem);

      // For successful addition of item with dependency
      // Update or remove the keys 
      // Verify if dependent key is present
}
catch (error) 
{
    // Handle any errors
}

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 Key Dependency to Existing Cache Item

NCache also provides you with the ease of adding key dependency to an item already present in cache, without re-inserting it into the cache.

This is done through CacheItemAttribute class, which has the property of Dependency to be set against CacheItem. The attribute is then set against the existing key of the item, using the UpdateAttributes method of Cache class.

The following example shows that an order as well as a customer is already present in the cache without dependency and dependency is added on the order using UpdateAttributes such that if the customer is updated or removed in the cache, the order is automatically removed.

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

      // Pre-condition: Both the items already exist in cache
      string customerKey = "Customer: ALFKI";
      string orderKey = "Order: 1001";

      // Create a key dependency where order is dependent on customer
      var dependency = new KeyDependency(customerKey);

      // Create a CacheItemAttribute for dependency
      var attr = new CacheItemAttributes();
      attr.Dependency = dependency;

      // Set the attribute of dependency against the order
      cache.UpdateAttributes(orderKey, attr);

      // Monitor/Verify dependency through either:
      // PerfMon Counters or cache API
}
catch (OperationFailedException ex)
{
      // NCache specific exception

      if (ex.ErrorCode == NCacheErrorCodes.DEPENDENCY_KEY_NOT_FOUND)
      {
            // The dependent item does not exist in the cache
      }
      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 
{
      // Precondition: Cache is already connected

      // Precondition: Both items already exist in the cache
      String customerKey = "Customer: ALFKI";
      String orderKey = "Order: 1001";

      // Create a key dependency where order is dependent on customer
      KeyDependency dependency = new KeyDependency(customerKey);

      // Create a CacheItemAttribute for dependency
      CacheItemAttributes attributes = new CacheItemAttributes();
      attributes.setDependency(dependency);

      // Set the attribute of dependency against the order
      cache.updateAttributes(orderKey, attributes);

      // Verify dependency through PerfMon counters or API
} 
catch (OperationFailedException ex) 
{
      // NCache specific exception
      if (ex.getErrorCode() == NCacheErrorCodes.DEPENDENCY_KEY_NOT_FOUND) 
      {
            // The dependent item does not exist in the cache
      } 
      else 
      {
            // Exception can occur due to:
            // Connection Failures
            // Operation Timeout
            // Operation performed during state transfer
      }
} 
catch (Exception ex) 
{
    // Any generic exception like IllegalArgumentException or NullPointerException
}

// This is an async method
try 
{
      // precondition: cache is connected

      // Precondition: both the items already exist in the cache 
      let customerKey = "Customer: ALFKI";
      let orderKey = "Order: 1001";

      // create key dependency where order is dependent on customer
      let dependency = new KeyDependency(customerKey);

      // Create a CacheItemAttributes for dependency
      let attributes = new ncache.CacheItemAttributes();
      attributes.setDependency(dependency);

      // Set the attributes of dependency against the order
      this.cache.updateAttributes(orderKey, attributes);

      // verify dependency through PerfMon counters or API
}
catch (error) 
{
    // Handle any errors
}

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 Key Dependency on GitHub.

Key Dependency Types and Usage

Note

Note

Note

Pre-Requisites

Add CacheItem to Cache with Key Dependency

Important

Add Key Dependency on Multiple Keys

Important

Add Key Dependency to Existing Cache Item

Additional Resources

See also