Absolute Data Expiration in Cache

Absolute Expiration in NCache ensures data consistency by invalidating cache items at a precise, client-defined date and time. Absolute Expiration can be specified on items that are required for a limited time in the cache. For example, a company announces a flash sale for 24 hours on certain products. These items can then be cached with an Absolute Expiration of 24 hours so they are removed from the cache as soon as the sale ends.

Moreover, this DateTime value is converted to UTC time to handle scenarios where the cache server and client are in different time zones. Therefore, the items will expire at the exact time specified by the user.

Prerequisites

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

How to Add or Update Items with Absolute Expiration

Insert is the standard NCache API for synchronizing the application state with the cache. You can easily add or update cache items to set expiration, using the Insert method. The CacheItem is a custom class provided by NCache that can be used to add data to the cache and also allows you to set additional metadata associated with the object. This metadata defines the properties of the item, such as expiration, dependencies, and more.

The following example sets the value of the Expiration property to an Absolute Expiration of 5 minutes for a CacheItem. It adds the CacheItemto the cache if the key does not exist, and updates it if it does. This CacheItem will then be removed from the cache after 5 minutes.

Tip

You can monitor/verify expiration through:

  • "Cache Count" Counter in the NCache Monitor or PerfMon Counters.
  • Using cache.Contains after the expiration interval has elapsed.
  • Using cache.Count before and after specifying the expiration.
try
{
  // Precondition: Cache is already connected
  // Get product from database against given product ID
  Product product = FetchProductFromDB(1001);

  // Generate a unique cache key for this product
  string key = $"Product:{product.ProductID}";

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

  // Set Expiration TimeSpan
  var expiration = new Expiration(ExpirationType.Absolute, TimeSpan.FromMinutes(5));

  cacheItem.Expiration = expiration;

  // Add/Update item with expiration
  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 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.

How to Add or Update Items with Configured Default Expirations

Using DefaultAbsolute allows you to manage data through values configured in the NCache Management Center or config.ncconf without requiring application code redeployments. You can specify Absolute Expiration in the API using the DefaultAbsolute and DefaultAbsoluteLonger. This provides the flexibility of changing the value externally if needed, without changing the code.

The following code associates the configured Default Expiration (DefaultAbsolute in this case) with an item and adds it to the cache if the key does not exist, and updates the item with expiration if the key exists. Once the configured time has elapsed, the item is expired.

Important

To enable Default Expiration, it is required to enable it through the NCache Management Center or config.ncconf.

// Precondition: Cache is already connected
// Get product from database against given product ID
Product product = FetchProductFromDB(1001);

// Generate a unique cache key for this product
string key = $"Product:{product.ProductID}";

// Create a CacheItem instance for the product
var cacheItem = new CacheItem(product);

// Set Expiration type
var expiration = new Expiration(ExpirationType.DefaultAbsolute);

cacheItem.Expiration = expiration;

// Add/Update the item in the cache with default expiration
CacheItemVersion version = cache.Insert(key, cacheItem);

How to Set Absolute Expiration for Existing Cache Items

NCache also provides the flexibility to set Absolute Expiration on an existing cache item without having to reinsert it into the cache. This is done through the CacheItemAttributes class, which has the AbsoluteExpiration property to be set on the cache item. This sets the exact date and time at which the item should be invalidated in the cache. The attribute is then applied to the existing key of the item, using the UpdateAttributes method of ICache.

The following example sets the Absolute Expiration for an item that already exists within the cache with no expiration set. This eliminates the need to re-add or reinsert the item into the cache.

// Precondition: Cache is already connected
// Precondition: Item already exists in cache
string key = "Product:1001";

// Create a CacheItemAttribute for absolute expiration and set its value to 5 seconds
var attr = new CacheItemAttributes();
attr.AbsoluteExpiration = DateTime.Now.AddSeconds(5);

// Set Absolute Expiration of 5 seconds against existing key
cache.UpdateAttributes(key, attr);

Additional Resources

NCache provides a sample application for Absolute Expiration on GitHub.

See Also

.NET: Alachisoft.NCache.Runtime.Caching namespace.
Java: com.alachisoft.ncache.runtime.caching namespace.
Python: ncache.runtime.caching class.
Node.js: Expiration class.