Dictionary Behavior and Usage in Cache

Note

This feature is only available in the NCache Enterprise Edition.

A dictionary is a general-purpose data structure for storing a group of objects. It is also called a Hash, Map, and HashMap. It is an unordered data structure, which provides a mapping of string keys against the values. For example, a dictionary can be used to store the information of all the products in a superstore against their productID as the dictionary entry key.

NCache further enhances the dictionary datatype by providing NCache specific features such as Groups, Tags, Expiration, Locking, Dependencies, and more against it.

Note

In Java, a Map corresponds to a Dictionary in .NET.

Behavior

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

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, IDistributedDictionary, IDataTypeManager, CreateDictionary, IDictionary, GetDictionary, ICollectionManager, RegisterNotification, DataTypeDataNotificationCallback, EventType, DataTypeEventDataFilter, Lock, Unlock.

Create Dictionary and Add Data

The following code sample shows how a dictionary is created in the cache against the cache key ProductDictionary and then data is added in the dictionary.

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 structure.

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);
    }
}
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 
}

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

    // Specify unique cache key for map
    String key = "ProductMap";

    // Create Map of Product type
    DistributedMap<String, Product> map = cache.getDataStructuresManager().createMap(key, Product.class);

    // Adding products to map
    Product[] products = fetchProducts();
    for (var product : products) {
        // Add products
        String productKey = "Product:" + product.getProductID();
        map.put(productKey, product);
    }
} catch (OperationFailedException ex) {
    if (ex.getErrorCode() == 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.getErrorCode() == NCacheErrorCodes.CACHEITEM_IN_DATA_STRUCTURES) {
        // Data structures cannot be of CacheItem type
        // CacheItems cannot be added in data structures
    } 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 {
    // Pre-condition: Cache must be connected// Pre-condition: Cache must be connected

    // Specify unique cache key for dictionary
    val key = "ProductDictionary"

    // Create dictionary of Product type
    val dictionary = cache.getDataStructuresManager.createMap(key, classOf[Product])

    // Adding products to dictionary
    val products = fetchProducts()

    for (product <- products) { // Add products
      val productKey = "Product:" + product.getProductId
      dictionary.put(productKey, product)
    }
}
catch {
    case exception: Exception => {
      // Handle any errors
    }
}

try:
    # Pre-condition: Cache must be connected
    # Specify unique cache key for dictionary
    key = "ProductDictionary"

    # Create dictionary of Product type
    dictionary = cache.get_data_structures_manager().create_dictionary(key, Product)

    # Adding products to dictionary
    products = fetch_products()

    for product in products:
        # Add products
        product_key = "Product:" + product.get_product_id()

        dictionary.put(product_key, product)
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.

Fetch Dictionary from Cache

You can fetch a dictionary from the cache which takes a cache key as a parameter. This key is the name of the dictionary, which is specified during the 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)
    {
        // The item being fetched is not of Dictionary type
        // Cache key corresponds to an item of a different data structure
    }
    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
}

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

    // Map with this key already exists in cache
    String key = "ProductMap";

    // Get map and show items of map
    DistributedMap<String, Product> retrievedMap = cache.getDataStructuresManager().getMap(key, Product.class);
    if (retrievedMap != null) {
        for (var item : retrievedMap) {
            // Perform operations
        }
    } else {
        // Map does not exist
    }
} catch (OperationFailedException ex) {
    if (ex.getErrorCode() == NCacheErrorCodes.NOT_A_DICTIONARY) {
        // Item being fetched is not of Map/Dictionary type
        // Cache key corresponds to an item of different data structure
    } 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 {
    // Pre-condition: Cache is already connected
    // Dictionary with this key already exists in cache
    val key = "ProductDictionary"

    // Get dictionary and show items of dictionary
    val retrievedDictionary = cache.getDataStructuresManager.getMap(key, classOf[Product])

    if (retrievedDictionary != null) {
      for (item <- retrievedDictionary.iterator) {
        // Perform operations
      }
    }
    else {
      // Dictionary does not exist
    }
}
catch {
    case exception: Exception => {
      // Handle any errors
    }
}

try:
    # Pre-condition: Cache is already connected
    # Dictionary with this key already exists in cache
    key = "ProductDictionary"

    # Get dictionary and show items of dictionary
    retrieved_dictionary = cache.get_data_structures_manager().get_dictionary(key, Product)

    if retrieved_dictionary is not None:
        for item in retrieved_dictionary.get_iterator():
            # Perform operations
            print(item)
    else:
        # Dictionary does not exist
        print("Dictionary not found")
except Exception as exp:
    # Handle errors

Fetch Values of Specific Dictionary Keys

You can get values of only 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
}

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

    // Map exists in cache
    // Create list of keys to fetch corresponding values
    var keys = new ArrayList<String>();
    keys.add("Product:1001");
    keys.add("Product:1002");
    keys.add("Product:1003");

    // Get values against keys
    // "map" instance was created while creating map
    Collection<Product> values = map.get(keys);
    for (var value : 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 IllegalArgumentException or NullPointerException
}

try {
    // Pre-condition: Cache is already connected
    // Dictionary exists in cache
    // Create list of keys to fetch corresponding values
    val keys = List("Product:1001", "Product:1002", "Product:1003")

    // Get values against keys
    // "dictionary" instance was created while creating dictionary
    val values = dictionary.get(keys)

    for (value <- values) {
      // Perform operations
    }
}
catch {
    case exception: Exception => {
      // Handle any errors
    }
}

try:
    # Pre-condition: Cache is already connected
    # Dictionary exists in cache
    # Create list of keys to fetch corresponding values
    keys = [
        "Product:1001",
        "Product:1002",
        "Product:1003"
    ]

    # Get values against keys
    # "dictionary" instance was created while creating dictionary
    values = dictionary.get(keys)

    for value in values:
        # Perform operations
        print(value)
except Exception as exp:
    # Handle errors

Insert Data to Existing Dictionary

You can insert data into an existing dictionary using Insert. The following code sample fetches new products from the data source and inserts them into a dictionary that already exists within the cache.

Note

If the 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);
}
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
}

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

    // Map with this key already exists in cache
    String key = "ProductMap";

    // Get map to insert more values
    DistributedMap<String, Product> retrievedMap = cache.getDataStructuresManager().getMap(key, Product.class);

    // Create map of new products to be added
    DistributedMap<String, Product> newProducts = cache.getDataStructuresManager().getMap(key, Product.class);
    Product[] products = fetchProducts();
    for (var product : products) {

        // Add new products
        String productKey = "Product:" + product.getProductID();
        newProducts.put(productKey, product);
    }

    // Append map entries to existing map
    retrievedMap.insert(newProducts);
} catch (OperationFailedException ex) {
    // 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 {
    // Pre-condition: Cache is already connected

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

    // Get dictionary to insert more values
    val retrievedDictionary = cache.getDataStructuresManager.getMap(key, classOf[Product])

    // Create dictionary of new products to be added
    var newProducts: Map[String, Product] = Map()

    val products = fetchProducts()

    for (product <- products) { // Add new products
      val productKey = "Product:" + product.getProductId
      newProducts = newProducts + (productKey -> product)
    }
    // Append dictionary entries to existing dictionary
    retrievedDictionary.insert(newProducts)

    // You can verify using retrievedDictionary.count
}
catch {
    case exception: Exception => {
      // Handle any errors
    }
}

try:
    # Pre-condition: Cache is already connected
    # Dictionary with this key already exists in cache
    key = "ProductDictionary"

    # Get dictionary to insert more values
    retrieved_dictionary = cache.get_data_structures_manager().get_dictionary(key, Product)

    # Create dictionary of new products to be added
    new_products = {}

    products = fetch_products()

    for product in products:
        # Add new products
        product_key = "Product:" + product.get_product_id()

        new_products[product_key] = product

    # Append dictionary entries to existing dictionary
    retrieved_dictionary.insert(new_products)

    # You can verify using len(retrieved_dictionary)
except Exception as exp:
    # Handle errors

Remove Items from Dictionary

Note

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

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.

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 == NCacheErrorCodes.NOT_A_DICTIONARY)
    {
        // Item being fetched is not of Dictionary type
        // Cache key corresponds to an item of different data structure
    }
    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
}

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

    // Map with this key already exists in cache
    String key = "ProductMap";

    // Get map and show items of map
    DistributedMap<String, Product> retrievedMap = cache.getDataStructuresManager().getMap(key, Product.class);

    // Create list of keys to remove
    List<String> keysToRemove = fetchExpiredProducts();

    // Number of keys removed is returned
    int itemsRemoved = retrievedMap.remove(keysToRemove);
} catch (OperationFailedException ex) {
    if (ex.getErrorCode() == NCacheErrorCodes.NOT_A_DICTIONARY) {
        // Item being fetched is not of Map/Dictionary type
        // Cache key corresponds to an item of different data structure
    } 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 {
    // Pre-condition: Cache is already connected
    // Dictionary with this key already exists in cache
    val key = "ProductDictionary"

    // Get dictionary and show items of dictionary
    val retrievedDictionary = cache.getDataStructuresManager.getMap(key, classOf[Product])

    // Create list of keys to remove
    val keysToRemove = fetchExpiredProducts()

    // Number of keys removed is returned
    val itemsRemoved = retrievedDictionary.remove(keysToRemove)
}
catch {
    case exception: Exception => {
      // Handle any errors
    }
}

try:
    # Pre-condition: Cache is already connected
    # Dictionary with this key already exists in cache
    key = "ProductDictionary"

    # Get dictionary and show items of dictionary
    retrieved_dictionary = cache.get_data_structures_manager().get_dictionary(key, Product)

    # Create list of keys to remove
    keys_to_remove = fetch_expired_products_ids()

    # Number of keys removed is returned
    items_removed = retrieved_dictionary.remove(keys_to_remove)
except Exception as exp:
    # Handle errors

Event Notifications on Dictionary

You can register cache events, key-based events, and data structure events on a data structure such as dictionary. For behavior, refer to feature wise behavior.

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 the cache, an ItemAdded cache level event is fired. However, once an item is added to the dictionary, an ItemAdded data structure 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
}

try {
    // Precondition: Cache is already connected

    // Unique cache key for map
    String key = "ProductMap";

    // Create map of type Product
    DistributedMap<String, Product> map = cache.getDataStructuresManager().createMap(key, Product.class);

    // Create EnumSet of event types
    EnumSet<EventType> enumSet = EnumSet.of(com.alachisoft.ncache.runtime.events.EventType.ItemAdded,
            EventType.ItemUpdated, EventType.ItemRemoved);

    // Register ItemAdded, ItemUpdated, ItemRemoved events on queue created
    // dataChangeListener is the specified callback method
    DataStructureDataChangeListener dataChangeListener = dataStructureListener.onDataStructureChanged(collectionName, args);
    map.addChangeListener(dataChangeListener, enumSet, DataTypeEventDataFilter.Data);

    // Perform operations
} catch (OperationFailedException ex) {
    // 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
    // Unique cache key for dictionary
    val key = "ProductMap"

    // Initialize change listener
    val dataStructureListener = MapDataStructureChangeListener()

    // Create list of Product type
    val list = cache.getDataStructuresManager.createList(key, classOf[Product])

    // Register ItemAdded, ItemUpdated, ItemRemoved events on list created
    val enumSet = List(EventType.ItemAdded, EventType.ItemUpdated, EventType.ItemRemoved)

    dictionary.addChangeListener(dataStructureListener, enumSet, DataTypeEventDataFilter.Data)
    // Perform operations
}
catch {
    case exception: Exception => {
      // Handle any errors
    }
}

def datastructure_callback_function(collection_name, collection_event_args):
    # Perform Operations
    print("Event Fired for " + str(collection_name))

try:
    # Precondition: Cache is already connected
    # Unique cache key for dictionary
    key = "ProductDictionary"

    # Create dictionary
    product_dictionary = cache.get_data_structures_manager().create_hashset(key, int)

    # Register ItemAdded, ItemUpdated, ItemRemoved events on hashset created
    events_list = [ncache.EventType.ITEM_ADDED, ncache.EventType.ITEM_UPDATED, ncache.EventType.ITEM_REMOVED]

    product_dictionary.add_change_listener(datastructure_callback_function, events_list, ncache.DataTypeEventDataFilter.DATA)

    # Perform operations
except Exception as exp:
    # Handle errors

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

DataStructureDataChangeListener dataStructureListener = new DataStructureDataChangeListener() {
    @Override
    public void onDataStructureChanged(String collection, DataStructureEventArg dataStructureEventArg) {
        switch (dataStructureEventArg.getEventType()) {
            case ItemAdded:
                // Item has been added to the collection
            break;
            case ItemUpdated:
                if (dataStructureEventArg.getCollectionItem() != null) {
                    //Item has been updated in the collection
                    // perform operations
                }
            break;
            case ItemRemoved:
                //Item has been removed from the collection
            break;
        }
    }
};

class MapDataStructureChangeListener extends DataStructureDataChangeListener {
  override def onDataStructureChanged(collectionName: String, collectionEventArgs: DataStructureEventArg): Unit = {
    collectionEventArgs.getEventType match {
      case EventType.ItemAdded =>
      // Item has been added to the collection

      case EventType.ItemUpdated =>
        if (collectionEventArgs.getCollectionItem != null) {
          //Item has been updated in the collection
          // perform operations
        }

      case EventType.ItemRemoved =>
      //Item has been removed from the collection

    }
  }
}

def datastructure_callback_function(collection_name: str, collection_event_args: DataStructureEventArg):
    if collection_event_args.get_event_type() is ncache.EventType.ITEM_ADDED:
        # Item has been added to the collection
        print("Item added in " + collection_name)

    elif collection_event_args.get_event_type() is ncache.EventType.ITEM_UPDATED:
        # Item has been updated in the collection
        print("Item updated in " + collection_name)

    elif collection_event_args.get_event_type() is ncache.EventType.ITEM_REMOVED:
        # Item has been removed from the collection
        print("Item removed from " + collection_name)

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);

    // Lock dictionary for 10 seconds
    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
}

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

    // Map exists with key "ProductMap"
    // Cache Key
    String key = "ProductMap";

    // Get dictionary
    DistributedMap<String, Product> map = cache.getDataStructuresManager().getMap(key, Product.class);

    // Lock map for 10 seconds
    boolean isLocked = map.lock(TimeSpan.FromSeconds(10));
    if (isLocked) {
        // Map is successfully locked for 10 seconds
        // Unless explicitly unlocked
    } else {
        // Map is not locked because either:
        // Map is not present in the cache
        // Map is already locked
    }
    map.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 generic exception like IllegalArgumentException or NullPointerException
}

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

    // Get dictionary
    val productDictionary = cache.getDataStructuresManager.getMap(key, classOf[Product])

    val isLocked: Boolean = productDictionary.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
    }

    productDictionary.unlock()
}
catch {
    case exception: Exception => {
      // Handle any errors
    }
}

Additional Resources

NCache provides a sample application for the dictionary data structure on GitHub.

Dictionary Behavior and Usage in Cache

Note

Note

Behavior

Prerequisites

Create Dictionary and Add Data

Tip

Note

Fetch Dictionary from Cache

Warning

Fetch Values of Specific Dictionary Keys

Note

Insert Data to Existing Dictionary

Note

Remove Items from Dictionary

Note

Tip

Event Notifications on Dictionary

Register Event on Dictionary Created

Specify Callback for Event Notification

Locking Dictionary

Additional Resources

See Also