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. For example, if an order depends on a product that is no longer available, the cache must remove all its dependents, as well. Here you can use the Key Dependency to maintain this relationship. Essentially, a 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 those on whom others depend are aware of this relationship. When the cache removes such an item on which other cache items depend, it will also remove all its dependents. However, vice versa is not possible. For example, Products will not be removed, if any of the Orders are updated or removed.

Key(s) can have two types of dependencies:

Multilevel Dependency

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

For instance, if there are three data sets in a cache - i.e., Products, Orders, and OrderDetails - 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.

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

Using Multilevel key Dependency in NCache

Multiple Dependency

A single item can depend on more than one item 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 and Product. Similarly, the OrderDetails depend on the Orders. The following diagram depicts the whole scenario visually.

Using Multiple key dependency in NCache

If the Customer is deleted, Orders and OrderDetails get deleted. Similarly, if the Product is deleted, Orders and OrderDetails get deleted.

Note

You can only specify existing keys in a cache for key dependency. A non-existent key specified for key dependency will result in OperationFailedException - whereas an object can be considered dependent on another key at the time of addition.

Prerequisites

To learn about the standard prerequisites required to work with all NCache client side features please refer to the given page on Client Side API Prerequisites.
For API details, refer to: ICache, CacheItem, CacheItemAttributes, Dependency, UpdateAttributes, Insert.

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 lets you set additional metadata associated with an object of this class. This metadata defines the item properties 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. If this CacheItem already exists in the cache, it overwrites its properties.

Important

Note that this API also specifies CacheItem priority for eviction and expiration, where the value for that parameter passes as Default.

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
{
      // Get customer from database.
      Customer customer = FetchCustomerFromDB();

      // Add customer in cache
      cache.Add(customer.CustomerID, customer);

      // Get order from customer.
      Order order = new Order
      {
            OrderID = 10248,
            OrderDate = DateTime.Now,
            ShipAddress = "Carrera 22 con Ave. Carlos Soublette #8-35"
      };
      // Save order to database.
      bool isOrderSaved = SaveOrderToDB(order);
      // Generate order Id.
      string orderKey = $"Order:{order.OrderID}";

      if (isOrderSaved)
      {
            // Generate an instance of key dependency.
            CacheDependency dependency = new Runtime.Dependencies.KeyDependency(customer.CustomerID);
            // Create CacheItem to with your desired object
            CacheItem cacheItem = new CacheItem(order);
            // Add key dependency to order
            cacheItem.Dependency = dependency;
            // Add order in cache with dependency on the customer added before
            cache.Add(orderKey, cacheItem);

      }

      OrderDetail orderDetail = new OrderDetail
      {
            OrderID = order.OrderID,
            UnitPrice = 200,
            Discount = 25.5F,
            Quantity = 10,
      };
      // Save order's detail to database.
      bool isOrderDetailSaved = SaveOrderDetailToDB(orderDetail);

      if (isOrderDetailSaved)
      {
            // Generate order detail Id.
            string orderDetailId = $"OrderDetail: {orderDetail.OrderID}";
            // Generate an instance of key dependency.
            CacheDependency dependency = new Runtime.Dependencies.KeyDependency(orderKey);
            // Create CacheItem to with your desired object
            CacheItem cacheItem = new CacheItem(orderDetail);
            // Add key dependency to order
            cacheItem.Dependency = dependency;
            // Add order in cache with dependency on the customer added before
            cache.Add(orderDetailId, cacheItem);
      }
}
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("ALFKI");

      // 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
}

try {
    // Precondition: Cache is already connected

    // Get customer from database against given customerId
    val customer = fetchCustomerFromDb("ALFKI")

    // Create a unique cache key for this customer
    val customerKey = "Customer:" + customer.getCustomerId

    // Get orders against the customer from the cache
    val order = fetchOrderByCustomerId("ALFKI")

    // Generate a unique key for order
    val orderKey = "Order:" + order.getOrderId

    // Create a new cache item for this order
    val cacheItem = 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 {
    case exception: Exception => {
      // Handle any errors
    }
}

// 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
}

try:
      # Precondition: Cache is already connected

      # Customer "ALFKI" already exists in the cache
      customer = fetch_customer_by_customer_id("ALFKI")

      # Create unique key for this customer
      customer_key = "Customer:" + customer.get_customer_id()

      # Get orders against the customer from cache
      order = fetch_order_by_customer_id(customer.get_customer_id())

      # Create a unique key for this order
      order_key = "Order:" + order.get_order_id()

      # Create a new cacheItem for this order
      cache_item = ncache.CacheItem(order)

      # Create a new key dependency on customer
      cache_item.set_dependency(ncache.KeyDependency(customer_key))

      # Add / update item in the cache with key dependency
      cache.insert(order_key, cache_item)

      # For successful addition of cacheitem with dependency
      # Update the key and check if cacheitem is present in cache
except Exception as exp:
      # Handle errors

Note

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. The following example demonstrates this.

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.

// Get customer from database.
Customer customer = FetchCustomerFromDB();
// Get product from database.
Product product = FetchProductFromDB();
// Add customer in cache.
cache.Add(customer.CustomerID, customer);
// Add product to cache.
      string productId = $"Product: {product.ProductID}";
cache.Add(productId, product);
// Get order from customer.
Order order = new Order
{
      OrderID = 10248,
      OrderDate = DateTime.Now,
      ShipAddress = "Carrera 22 con Ave. Carlos Soublette #8-35"
};
// Save order to database.
bool isOrderSaved = SaveOrderToDB(order);
// Generate order Id.
string orderKey = $"Order: {order.OrderID}";
if (isOrderSaved)
{
      string[] dependencyKeys = { productId, customer.CustomerID };
      // Generate an instance of key dependency.
      CacheDependency dependency = new Alachisoft.NCache.Runtime.Dependencies.KeyDependency(dependencyKeys);
      // Create CacheItem to with your desired object
      CacheItem cacheItem = new CacheItem(order);
      // Add key dependency to order
      cacheItem.Dependency = dependency;
      // Add order in cache with dependency on the customer added before
      cache.Add(orderKey, cacheItem);
}

OrderDetail orderDetail = new OrderDetail
{
      OrderID = order.OrderID,
      UnitPrice = 200,
      Discount = 25.5F,
      Quantity = 10,
};
// Save order's detail to database.
bool isOrderDetailSaved = SaveOrderDetailToDB(orderDetail);

if (isOrderDetailSaved)
{
      // Generate order detail Id.
      string orderDetailId = $"OrderDetail: {orderDetail.OrderID}";
      // Generate an instance of key dependency.
      CacheDependency dependency = new Alachisoft.NCache.Runtime.Dependencies.KeyDependency(orderKey);
      // Create CacheItem to with your desired object
      CacheItem cacheItem = new CacheItem(orderDetail);
      // Add key dependency to order
      cacheItem.Dependency = dependency;
      // Add order in cache with dependency on the customer added before
      cache.Add(orderDetailId, cacheItem);
}

// 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

// Get customer from database against given employeeId
val customer = fetchCustomerFromDb("ALFKI")

// Generate a unique cache key for this customer
val key = "Employee:" + customer.getCustomerId

// Territories with the keys exist in the cache
val territoryKey1 = "Territory: Westbrook"
val territoryKey2 = "Territory: Bedford"

// Insert the keys of the territories in an array
var territories: List[String] = List()
territories = territoryKey1 :: territories
territories = territoryKey2 :: territories

// Create a new cache item containing customer
val cacheItem = new CacheItem(customer)

// Add key dependency to customer on territories
cacheItem.setDependency(KeyDependency(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

// 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

# Get product from database against productId
product = fetch_product_from_db("1001")

# Create unique cache key for this product
key = "Product:" + product.get_product_id()

# Territories with the keys exist in the cache
territory_key_1 = "Territory: Chai"
territory_key_2 = "Territory: Tofu"

# Insert territory keys to the cache
territories = [
territory_key_1,
territory_key_2
]

# Create a new cache item containing product
cache_item = ncache.CacheItem(product)

# Add key dependency to employee on territories
cache_item.set_dependency(ncache.KeyDependency(territories))

# Add cache item with dependency in the cache
cache.insert(key, cache_item)

# For successful addition of item with dependency
# Update or remove the keys
# Verify if dependent key is present

Add Key Dependency to Existing Cache Item

NCache lets you add a key dependency to an item already present in the cache, without re-inserting it into the cache.

This process occurs through the 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 the Cache class.

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

string orderId = "Order: 10248";
string ProductId = "Product: 8899";

// Create a key dependency where order is dependent on product.
CacheDependency dependency = new Alachisoft.NCache.Runtime.Dependencies.KeyDependency(ProductId);

// Create a cache item attribute
CacheItemAttributes itemAttribute = new CacheItemAttributes();

// Set dependency to cache item attribute.
itemAttribute.Dependency = dependency;

// Update attribute in cache.
cache.UpdateAttributes(orderId, itemAttribute);

// 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

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

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

// Create a CacheItemAttribute for dependency
val 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

// This is an async method
// 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

# Precondition: both the items already exist in the cache
customer_key = "Customer:ALFKI"
order_key = "Order:1001"

# Create key dependency where order is dependent on customer
dependency = ncache.KeyDependency(customer_key)

# Create a CacheItemAttributes for dependency
attributes = ncache.CacheItemAttributes()
attributes.set_dependency(dependency)

# Set the attributes of dependency against the order
cache.update_attributes(order_key, attributes)

# Verify dependency through PerfMon counters or API

Additional Resources

NCache provides sample application for Key Dependency on GitHub.

Key Dependency Types and Usage

Note

Note

Note

Prerequisites

Add CacheItem to Cache with Key Dependency

Important

Note

Add Key Dependency on Multiple Keys

Important

Add Key Dependency to Existing Cache Item

Additional Resources

See also