Dictionary Behavior and Usage in Cache

Note

This feature is only available in NCache Enterprise Edition.

A dictionary in NCache is an extension of the .NET IDictionary, which also provides additional properties. A dictionary is an unordered data type, which provides a mapping of string keys against the values. For example, a dictionary can be used to store the products information of all the products in a superstore, against their productID as the dictionary entry key.

NCache further enhances this dictionary by providing NCache specific features such as expiration, dependency, groups and more to the dictionary.

Since NCache Dictionary is an extension of the .NET Framework IDictionary, you can still use all methods exposed by IDictionary along with NCache's methods which are cache-specific. This ensures familiarity and flexibility with the existing framework.

Behavior

• A dictionary value can be of any primitive type or custom object.
• A dictionary key can only be of string type.
• Duplicate dictionary keys are not allowed.
• A dictionary of CacheItem and nested dictionary are not supported yet.
• Dictionary is named; you need to provide a unique cache key for each dictionary.

Pre-requisites

• Include the following namespaces in your application:
  • Alachisoft.NCache.Client.DataTypes
  • Alachisoft.NCache.Client.DataTypes.Collections
  • Alachisoft.NCache.Client
  • Alachisoft.NCache.Runtime.Exceptions
• The application must be connected to cache before performing the operation.
• Cache must be running.
• To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Create Dictionary and Add Data

The following code sample shows how a dictionary of <string, Product> type can be created using CreateDictionary in cache against the cache key "ProductDictionary" without any additional parameters. The key must be unique. Data is then populated in the dictionary using Add.

Tip

You can also configure searchable attributes such as groups/tags/named tags and invalidation attributes such as expiration/eviction/dependency while creating a data type.

try
{
    // Pre-condition: Cache must be connected

    // Specify unique cache key for dictionary
    string key = "ProductDictionary";

    // Create dictionary of Product type
    IDistributedDictionary<string, Product> dictionary = 
                                            cache.DataTypeManager
                                            .CreateDictionary<string, Product>(key);

    // Adding products to dictionary
    Product[] products = FetchProducts();

    foreach(var product in products)
    {
        // Add products
        string productKey = $"Product:{product.ProductID}";
        dictionary.Add(productKey, product);
    }

    // Check if the dictionary exists in cache
    // using cache.Contains() or cache.Count
}
catch (OperationFailedException ex)
{
    // NCache specific exception

    if(ex.ErrorCode == NCacheErrorCodes.KEY_ALREADY_EXISTS)
    {
        // The specified key already exists in cache,
        // Either remove the existing object from cache
        // Or specify another key
    }
    else if (ex.ErrorCode == NCacheErrorCodes.CACHEITEM_IN_DATA_STRUCTURES)
    {
        // Data structures cannot be of CacheItem type
        // CacheItems cannot be added in data structures
    }
    else
    {
        // NCache specific exception
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException 
}

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

Fetch Dictionary from Cache

You can fetch a dictionary from cache using GetDictionary, which takes a cache key as parameter. This key is the name of the dictionary which is specified during dictionary creation.

Warning

If the item being fetched is not of Dictionary type, a Type mismatch exception is thrown.

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

    // Dictionary with this key already exists in cache
    string key = "ProductDictionary";

    // Get dictionary and show items of dictionary
    IDistributedDictionary<string, Product> retrievedDictionary =
                                            cache.DataTypeManager
                                            .GetDictionary<string, Product>(key);

    if (retrievedDictionary != null)
    {
        foreach (var item in retrievedDictionary)
        {
            // Perform operations
        }
    }
    else
    {
       // Dictionary does not exist
    }
}
catch (OperationFailedException ex)
{
    // NCache specific exception

    if(ex.ErrorCode == NCacheErrorCodes.NOT_A_DICTIONARY)
    {
        // Item being fetched is not of Dictionary type;
        // Cache key corresponds to an item of different data type
    }
    else
    {
        // NCache specific exception
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

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

Fetch Values of Specific Dictionary Keys

You can get values only of dictionary entries using Get. The following code sample uses the dictionary instance from the example for adding data to dictionary, and gets values against the keys specified.

Note

If no value exists against the key specified, null is returned.

 try
{
    // Pre-condition: Cache is already connected
    // Dictionary exists in cache

    // Create list of keys to fetch corresponding values
    var keys = new List<string>();
    keys.Add("Product:1001");
    keys.Add("Product:1002");
    keys.Add("Product:1003");

    // Get values against keys
    // "dictionary" instance was created while creating dictionary
    ICollection<Product> values = dictionary.Get(keys);

    foreach (var value in values)
    {
        // Perform operations
    }
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

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

Insert Data to Existing Dictionary

Data can be inserted into an existing dictionary using Insert. The following code sample fetches new products from the data source and inserts them into a dictionary already existing in cache.

Note

If keys already exist, this will overwrite the values in the dictionary.

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

    // Dictionary with this key already exists in cache
    string key = "ProductDictionary";

    // Get dictionary to insert more values
    IDistributedDictionary<string, Product> retrievedDictionary =  cache.DataTypeManager.GetDictionary<string, Product>(key);

    // Create dictionary of new products to be added
    IDictionary<string, Product> newProducts = new Dictionary<string, Product>();

    Product[] products = FetchProducts();

    foreach (var product in products)
    {
        // Add new products 
        string productKey = $"Product:{product.ProductID}";

        newProducts.Add(productKey, product);
    }

    // Append dictionary entries to existing dictionary
    retrievedDictionary.Insert(newProducts);

    // You can verify using retrievedDictionary.Count
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

Remove Items from Dictionary

Items can be removed from a dictionary against a given collection of keys. The following code sample removes the dictionary entities for the expired products using Remove.

Note

If key specified to be removed does not exist, nothing is returned. You can verify number of keys returned using the return type of Remove.

Tip

To remove the whole dictionary from cache, refer to the Remove Data Structures From Cache page.

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

    // Dictionary with this key already exists in cache
    string key = "ProductDictionary";

    // Get dictionary and show items of dictionary
    IDistributedDictionary<string, Product> retrievedDictionary =
                                            cache.DataTypeManager
                                            .GetDictionary<string, Product>(key);

    // Create list of keys to remove
    List<string> keysToRemove = FetchExpiredProducts();

    // Number of keys removed is returned
    int itemsRemoved = retrievedDictionary.Remove(keysToRemove);
}
catch (OperationFailedException ex)
{
    // NCache specific exception

    if(ex.ErrorCode == 45009)
    {
        // Item being fetched is not of Dictionary type;
        // Cache key corresponds to an item of different data type
    }
    else
    {
        // NCache specific exception
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (Exception ex)
{
    // Any generic exception like ArgumentNullException or ArgumentException
}

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

Event Notifications on Dictionary

You can register cache events as well as data type events on a data type such as dictionary. For behavior, refer to the Feature Wise behavior topic.

The following code sample registers a cache event of ItemAdded and ItemUpdated as well as registers an event for ItemAdded and ItemUpdated on the dictionary in cache.

Once a dictionary is created in cache, an ItemAdded cache level event is fired. However, once an item is added to dictionary, an ItemAdded data type event is fired, and an ItemUpdated cache level event is fired.

Register Event on Dictionary Created

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

    // Unique cache key for dictionary
    string key = "ProductDictionary";

    // Create dictionary of Product type
    IDistributedDictionary<string, Product> dictionary = cache.DataTypeManager.CreateDictionary<string, Product>(key);

    // Register ItemAdded, ItemUpdated, ItemRemoved events on dictionary created
    // DataTypeNotificationCallback is callback method specified
    dictionary.RegisterNotification(DataTypeDataNotificationCallback, EventType.ItemAdded | 
            EventType.ItemUpdated | EventType.ItemRemoved,
            DataTypeEventDataFilter.Data);

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

Specify Callback for Event Notification

private void DataTypeDataNotificationCallback(string collectionName, DataTypeEventArg collectionEventArgs)
{
    switch (collectionEventArgs.EventType)
    {
        case EventType.ItemAdded:
            // Item has been added to the collection
            break;

        case EventType.ItemUpdated:
            if (collectionEventArgs.CollectionItem != null)
            {
                // Item has been updated in the collection
                // Perform operations
            }
            break;

        case EventType.ItemRemoved:
            // Item has been removed from the collection
            break;
    }
}  

Locking Dictionary

Dictionary can be explicitly locked and unlocked to ensure data consistency. The following code sample creates a dictionary and locks it for a period of 10 seconds using Lock() and then unlocks it using Unlock().

try
{
    // Pre-conditions: Cache is already connected 
    // Dictionary exists with key "ProductDictionary"

    // Cache Key
    string key = "ProductDictionary";

    // Get dictionary
    IDistributedDictionary<string, Product> dictionary =
                                            cache.DataTypeManager
                                            .GetDictionary<string, Product>(key);

    bool isLocked = dictionary.Lock(TimeSpan.FromSeconds(10));

    if (isLocked)
    {
        // Dictionary is successfully locked for 10 seconds
        // Unless explicitly unlocked
    }
    else
    {
        // Dictionary is not locked because either:
        // Dictionary is not present in the cache
        // Dictionary is already locked
    }

    dictionary.Unlock();
}
catch (OperationFailedException ex)
{
    // NCache specific exception
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any other generic exception like ArgumentNullException or ArgumentException
}

Additional Resources

NCache provides sample application for Dictionary datatypes at:

• GitHub
• Shipped with NCache: %NCHOME%\samples\dotnet\DataTypes\DistributedDictionary

See Also

Using List in Cache
Queue Behavior and Usage in Cache
Sets Behavior and Usage in Cache
Using Counter in Cache
Configure Searchable Attributes
Configure Invalidation Attributes
Query on Data Structures
Remove Data Structure from Cache