Absolute Expiration

NCache allows you to configure absolute expiration with your cache items. This will expire the items at the exact date and time specified by the client. Absolute expiration can be specified on items that are required for a limited time in the cache. For example, a company announces flash sale for 24 hours on certain products. These items can then be cached with an absolute expiration of 24 hours so they are expired from the cache as soon as the sale ends.

Moreover, this DateTime value is converted to UTC time to cater the case where the cache server and client are in different time zones. So the items will be expired at the exact time which has been specified by the user.

Warning

You can not set both Absolute and Absolute expiration together for an item. If both expirations are passed, System.ArgumentException is thrown.

Pre-requisites For Using Expirations

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

Add/Update Item with Absolute Expiration

You add/update the cache items to set expiration, using the Insert method.

The following examples provide multiple ways of adding/updating absolute expiration - these can be either user-specified values or the configured DefaultAbsolute and DefaultAbsoluteLonger values.

Important

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

Add Expiration Programmatically

You can specify absolute expiration in the API as a DateTime value. The following code associates absolute expiration with an item and adds it to the cache if the key does not exist in cache, and updates the item with expiration if the key exists. This item will expire after 5 minutes if not accessed within the duration, otherwise the item's life will be extended by another 5 minutes.

Tip

You can monitor/verify expiration through:

try
{
    // Pre-condition: 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}";

    // Adding/Updating item with absolute expiration of 5 minutes
    cache.Insert(key, product, DateTime.Now.AddMinutes(5), Cache.NoSlidingExpiration, CacheItemPriority.Default);

    // Monitor/Verify expiration through either:
    // PerfMon Counters
    // cache.Contains(key)
    // cache.Count
}
catch (OperationFailedException ex)
{
    // NCache specific exception

    // Exception can occur due to:
    // Connection Failures
    // Operation performed during state transfer
    // Operation Timeout
}
catch (Exception ex) 
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Configured Default Expirations

You can specify absolute expiration in the API using the DefaultAbsolute and DefaultAbsoluteLonger values configured in NCache Manager or config.ncconf. This provides flexibility of changing the value externally if needed, without changing the code.

The following code associates configured default expiration (DefaultAbsolute in this case) with an item and adds it to the cache if the key does not exist in cache, 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 mandatory that you enable it through NCache Manager or config.ncconf. If you pass the API for default expiration and it is not configured through NCache Manager or config.ncconf, it will not work.

Tip

You can monitor/verify expiration through:

try
{
    // Pre-condition: 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}";

    // Add/Update an item with configured DefaultAbsolute expiration
    // You can use Cache.DefaultAbsoluteLonger, if configured
    cache.Insert(key, product, Cache.DefaultAbsolute, Cache.NoSlidingExpiration, CacheItemPriority.Default);

    // Monitor/Verify expiration through either:
    // PerfMon Counters
    // cache.Contains(key)
    // cache.Count
}
catch (OperationFailedException ex)
{
    // NCache specific exception

    // Exception can occur due to:
    // Connection Failures
    // Operation performed during state transfer
    // Operation Timeout
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Set Absolute Expiration with CacheItem

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 expiration, dependencies and more. You can refer to all properties of CacheItem here.

The following example sets the value of the AbsoluteExpiration property to 5 minutes for a CacheItem and adds it to the cache if the key does not exist - and updates the item if it exists. This CacheItem will then be removed from the cache after 5 minutes.

Tip

You can monitor/verify expiration through:

try
{
    // Pre-condition: 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
    CacheItem cacheItem = new CacheItem(product);

    // Setting Absolute expiration of 5 minutes
    cacheItem.AbsoluteExpiration = DateTime.Now.AddMinutes(5);

    // Add/Update item with expiration
    cache.Insert(key, cacheItem);

    // Monitor/Verify expiration through either:
    // PerfMon Counters
    // cache.Contains(key)
    // cache.Count
}
catch (OperationFailedException ex)     
{
    // NCache specific exception

    // Exception can occur due to:
    // Connection Failures
    // Operation performed during state transfer
    // Operation Timeout
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Set Absolute Expiration to Existing Item

NCache also provides the flexibility to set Absolute expiration to an existing cache item without having to reinsert it to cache. This is done through CacheItemAttribute class, which has the AbsoluteExpiration property to be set against the cache item. This sets the exact data and time at which the item should be invalidated from the cache. The attribute is then set against the existing key of the item, using the SetAttributes method of Cache class.

The following example adds an item to cache without expiration, and then sets the absolute expiration for the item. This requires no need to add the item again to the cache.

Tip

You can monitor/verify expiration through:

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

    // Pre-condition: Item already exists in cache
    string key = "Product:1001";

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

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

    // Monitor/Verify expiration through either:
    // PerfMon Counters
    // cache.Contains(key)
    // cache.Count
}
catch (OperationFailedException ex)     
{
    // NCache specific exception

    // Exception can occur due to:
    // Connection Failures
    // Operation performed during state transfer
    // Operation Timeout
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

See Also

Sliding Expiration
Cache Data Expiration
Named Tags
Data Relationship in Cache