Retrieve Existing Cache Data

Primarily, a cache is only considered as effective as its ability to retrieve data. While NCache also supports querying the cache, it utilizes the key-value architecture of its store to maximize the ways of data retrieval. You can retrieve a single custom object, CacheItem or bulk items from the cache, using the unique key associated with the item.

NCache provides various overloads of Get() method to fetch items from the cache based on the specified key.

For example, an e-commerce site caches its best selling products, discounted products and new arrivals. When you request to view the best selling products, the information is fetched from the cache instead of accessing the database - saving network cost and time.

Get Operation Behavior

Get is a synchronous operation.
Getreturns a template type object, which needs to be casted according to your custom object.
If specified key does not exist in cache, null value is returned.
In advanced cases, if data source is configured, data will be fetched from the data source if it does not exist in cache. For more details, refer to the chapter Data Source Providers.

Note

To use Maven packages for NCache Professional Edition, change the <artifactId> as shown below:
- <artifactId>ncache-professional-client</artifactId>
To use Node.js API in NCache Professional Edition, install and include the ncache-professional-client npm package in your Node.js application.

Pre-requisites

Install the following NuGet package in your application.
- Alachisoft.NCache.SDK
Include the following namespaces in your application:
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.Exceptions
The application must be connected to cache before performing the operation.
Cache must be running.
For API details refer to: ICache, CacheItem, GetCacheItem(), Get, GetList, GetBulk(), GetCacheItemBulk
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Add the following Maven dependencies in your pom.xml file:

<dependency>
    <groupId>com.alachisoft.ncache</groupId>
    <artifactId>ncache-client</artifactId>
    <version>5.2.0</version>
</dependency>

Import the following packages in your application:
- import com.alachisoft.ncache.runtime.exceptions.*;
- import com.alachisoft.ncache.client.datastructures.*;
- import com.alachisoft.ncache.runtime.json.*;
- import com.alachisoft.ncache.client.*;
The application must be connected to cache before performing the operation.
Cache must be running.
Make sure that the data being added is serializable.
For API details refer to: Cache,CacheItem, getCacheItem(), get, getList, getBulk()
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Include the following modules in your application:
- const ncache = require('ncache-client')
The application must be connected to cache before performing the operation.
Cache must be running.
For API details refer to: Cache, CacheItem, getCacheItem, get(), getList, getBulk()
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Custom Object

You can fetch a single object from the cache using various overloads of the Get() method, by specifying the key of the cache item. The object is retrieved as a template so it needs to be type cast accordingly if it is a custom class object. For Java, Get() method is used for this purpose.

Important

If the key does not exist in cache, null value is returned.

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

The following example fetches an existing item of Product class with the specified key. Keep in mind that Get returns a template which needs to be cast accordingly, so the object is cast to Product type in this example. If the specified key does not exist in cache, null value is returned.

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

    // Get key to fetch from cache
    string key = $"Product:{product.ProductID}";

    // Get item against key from cache in template type
    var retrievedItem = cache.Get<Product>(key);         
    if (retrievedItem != null)
    {
        if (retrievedItem is Product)
        {
            // Perform operations according to business logic
        }
    }
    else
    {
        // Null returned; no key exists
    }
}
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
}

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

    // Get Product from database against given ProductID
    Product product = fetchProductFromDB(1001);

    // Get key to fetch from cache
    String key = "Product:" + product.getProductID();

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

    cache.insert(key , cacheItem);

    // Get item against key from cache in given Class type
    Product retrievedItem = cache.get(key, Product.class);
    if (retrievedItem != null)
    {
        // Perform operations according to your business logic

    }
    else
    {
        // Null returned; no key exists
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any generic exception like NullPointerException or IllegalArgumentException
}

// This is an async method
try
{
    // Pre-condition: Cache is already connected

    // Get Product from database against given ProductID
    var product = this.fetchProductFromDB(1001);

    // Get key to fetch from cache
    var key = "Product:" + this.product.getProductID();

    // Create a CacheItem
    var cacheItem = new ncache.CacheItem(product);

    await this.cache.insert(key , cacheItem);

    // Get item against key from cache in given Class type
    var retrievedItem = await this.cache.get(key, Product);

    if (retrievedItem != null)
    {
        // Perform your logic
    }
    else
    {
        // Null returned; no key exists
    }
}
catch(error)
{
    // Handle errors
}

CacheItem

CacheItem is a custom class provided by NCache which can be used to add data to the cache with additional properties associated with the data. The CacheItem is added to the cache against a unique key.

NCache allows retrieving an existing CacheItem from the cache using the dedicated GetCacheItem() API. This returns a CacheItem associated with the specified key. Its Value property encapsulates the data. For Java,getCacheItem() is used for this purpose.

Important

If the key does not exist in cache, null value is returned.

The following example retrieves an existing CacheItem with specified key and checks if the result is of Product type and type casts it accordingly.

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

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

    // Get key to fetch from cache
    string key = $"Product:{product.ProductID}";

    // Get CacheItem from cache
    var retrievedCacheItem = cache.GetCacheItem(key);

    if (retrievedCacheItem != null)
    {
        retrievedCacheItem.GetValue<Product>(); 
        // Perform operations according to your business logic
    }
    else
    {
        // Null returned; key does not exist
    }
}
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
}

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

    // Get Product from database against given ProductID
    Product product = fetchProductFromDB(1001);

    // Get key to fetch from cache
    String key = "Product:" + product.getProductID();

    // Create a CacheItem
    var cacheItem = new ncache.CacheItem(product);

    cache.insert(key , cacheItem);

    // Get CacheItem from cache
    CacheItem retrievedCacheItem = cache.getCacheItem(key);

    if (retrievedCacheItem != null)
    {
        retrievedCacheItem.getValue(Product.class);
        // Perform operations according to your business logic
    }
    else
    {
        // Null returned; key does not exist
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // Any generic exception like NullPointerException or IllegalArgumentException
}

// This is an async method
try
{
    // Pre-condition: Cache is already connected

    // Get key to fetch from cache
    var key = "Product:" + this.product.getProductID();

    // Get CacheItem from cache
    var retrievedCacheItem = this.cache.getCacheItem(key);

    // Get item against key from cache in given Class type

    if (retrievedCacheItem != null)
    {
        this.cache.getValue(Product);
        // Perform your logic
    }
    else
    {
        // Null returned; no key exists
    }
}
catch(error)
{
    // Handle errors 
}

JsonObject

Note

This feature is only available in NCache Enterprise Edition.

NCache lets you retrieve cache data as JSON. You can either retrieve a custom object as JsonObject or a JsonObject as a custom object using the Get() API. Similar to JsonObject you can retrieve JsonArray or JsonValue corresponding to a key. For more detail on the topic, please refer to the Cache Data as JSON section.

The following example adds a custom object in the cache and retrieves it as JsonObject. Similar to this you can retrieve JsonObject as custom object by providing the type in the Get() method.

.NET/.NET Core
Java

try
{
    // Pre-Condition: Cache is already connected
    // Cache is JSON serialized

    // Get Product from database against given ProductID
    Product product = FetchProductFromDB(1001);

    // Generate a unique key for this product
    string key = $"product.ProductID";

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

    // Add the object with the key specified to the cache
    cache.Insert(key, cacheItem);

    var retrievedItem = cache.Get<JsonObject>(key);
    if(retrievedItem != null)
    { 
        // Perform operations according to business logic
    }
    else
    {
        // No such item exists
    }
}
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
}

try
{
    // Pre-Condition: Cache is already connected
    // Cache is JSON serialized

    // Get Product from database against given ProductID
    Product product = fetchProductFromDB(1001);

    // Generate a unique key for this product
    String key = "Product:" + product.getProductID();

    // Create a new JSON object and set attributes
    // string values need to be added with JsonValue
    JsonObject jsonProduct = new JsonObject();
    jsonProduct.addAttribute("ProductID", new JsonValue(product.getProductID()));
    jsonProduct.addAttribute("ProductName", new JsonValue(product.getProductName()));
    jsonProduct.addAttribute("Category", new JsonValue(product.getCategory()));
    jsonProduct.addAttribute("UnitPrice", new JsonValue(product.getPrice()));
    jsonProduct.addAttribute("UnitsInStock", new JsonValue(product.getUnitsAvailable()));

    // Create a CacheItem
    var cacheItem = new ncache.CacheItem(jsonProduct);

    // Add the object with the key specified to the cache
    cache.insert(key, cacheItem);

    JsonObject retrievedItem = cache.get(key,JsonObject.class);
    if (retrievedItem != null)
    {
        // Perform operations according to business logic
    }
    else
    {
        // No such item exists
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
  // Any generic exception like NullPointerException or IllegalArgumentException
}

Data Structure

Note

This feature is only available in NCache Enterprise Edition.

You can fetch data structures from the cache using specific APIs for the data type. The following code fetches a list from cache using GetList, which takes a cache key as parameter. This key is the name of the list which is specified during list creation.

For more detail on supported data structures, please refer to the section Data Structures in Cache.

Note

In order to use data structures, the following additional namespaces must be added into your application:

Alachisoft.NCache.Client.DataTypes
Alachisoft.NCache.Client.DataTypes.Collections

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

    // List with this key already exists in cache
    string key = "ProductList";

    // Get list and show items of list
    IDistributedList<Product> retrievedList = cache.DataTypeManager.GetList<Product>(key);

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

    if (ex.ErrorCode == NCacheErrorCodes.NOT_A_LIST)
    {
        // The type of the corresponding item is not a list
    }
    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
{
    // Pre-condition: Cache is already connected

    // List with this key already exists in cache
    String key = "ProductList";

    // Get list and show items of list
    DistributedList<Product> retrievedList = cache.getDataStructuresManager().getList(key,Product.class);

    if (retrievedList != null)
    {
        for (Product item : retrievedList)
        {
            // Perform operations
        }
    }
    else
    {
        // List does not exist
    }
}
catch (OperationFailedException ex)
{
    // NCache specific exception

    if (ex.getErrorCode() == NCacheErrorCodes.NOT_A_LIST)
    {
        // The type of the corresponding item is not a list
    }
    else
    {
        // Exception can occur due to:
        // Connection Failures
        // Operation Timeout
        // Operation performed during state transfer
    }
}
catch (Exception ex)
{
   // Any generic exception like NullPointerException or IllegalArgumentException
}

// This is an async method
try
{
    // Pre-condition: Cache is already connected

    // List with this key already exists in cache
    var key = "ProductList";

    // Get list and show items of list

    //  var retrievedList = this.cache.getDataStructuresManager().createList(key);
    var ex = this.cache.getDataStructuresManager();
    var retrievedList = ex.createList(key);

    if(retrievedList != null)
    {
        retrievedList.forEach(item => {
           // Perform operations
        });
    }
    else
    {
        // list does not exist
    }
}
catch(error)
{
    // Handle errors
}

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

Bulk Items

NCache allows synchronous bulk retrieval of items in a single call to reduce network cost. Various overloads of GetBulk() method retrieve objects from the cache for the cache keys specified. Note that the value is retrieved as a template so it needs to be type casted accordingly if it is a custom class object. In case of Java, getBulk() method retrieves objects from the cache.

Important

If the keys exist in the cache a dictionary of cache items and their keys is returned.
If the key does not exist in cache, null value is returned.

Although a bulk operation is executed as a single operation, the operation itself is treated individually in the cache. For example, if a bulk of 100 items is specified and 20 of those items do not exist in the cache, the existing 80 items will be retrieved, while nothing will be returned for those 20 objects which do not exist.

The following example retrieves existing CacheItems containing objects of the Product class. The result is returned in an IDictionary of keys and values, which can be enumerated to get the actual values of the keys. Since GetBulk returns a template which needs to be casted accordingly, the object is casted to Product type in this example. If the specified key does not exist in cache, null value is returned.

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

try
{
    // Pre-condition: Cache is already connected
    Product[] products = FetchProductsFromDB();

    // Get keys to fetch from cache 
    string[] keys = new string[products.Length];
    int index = 0;

    foreach (var product in products)
    {
        keys[index] = $"Product:{product.ProductID}";
        index++;
    }

    // Get bulk from cache
    IDictionary<string, Product> retrievedItems = cache.GetBulk<Product>(keys);

    // Check if any keys have failed to be retrieved
    if (retrievedItems.Count == keys.Length)
    {
        foreach (KeyValuePair<string, Product> entry in retrievedItems)
        {
            if (entry.Value is Product)
            {
                // Perform operations according to business logic
            }
            else
            {
                // Object not of Product type
            }
        }
    }
    else
    {
        // Not all of the keys are present in cache 
    }
}
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
}

try
{
    // Pre-condition: Cache is already connected
    Product[] products = fetchProducts();

    // Get keys to fetch from cache
    ArrayList<String> keys = new ArrayList<>(products.length);

    for (Product product : products)
    {
        String key = "Product:" + product.getProductID();
        keys.add(key);
        cache.insert(key , product);
    }

    // Get bulk from cache
    java.util.Map<String, Product> retrievedItems = cache.<Product>getBulk(keys, Product.class);

    // Check if any keys have failed to be retrieved
    if (retrievedItems.size() == keys.size())
    {
        for (java.util.Map.Entry<String, Product> entry : retrievedItems.entrySet())
        {
            if (entry.getValue() != null)
            {
                // Perform operations according to business logic
            }
            else
            {
                // Object not of Product type
            }
        }
    }
    else
    {
        // Not all of the keys are present in cache
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
  // Any generic exception like NullPointerException or IllegalArgumentException
}

// This is an async method
try
{
    // Pre-condition: Cache is already connected

    // Get Product from database against given ProductID
    var products = await this.fetchProductFromDB();

    // Get keys to fetch from cache 
    var keys = [products.length];
    var index = 0;

    products.forEach(product => {

        keys[index] ="Product:" + this.product.getProductID();
        index++;

    });

    // Get bulk from cache
    var retrievedItems = await this.cache.getBulk(keys,Product);

    // Check if any keys have failed to be retrieved
    if(retrievedItems.size() == keys.length)
    {
        retrievedItems.forEach(entry => {

            if(entry.getValue() instanceof Product)
            {
                // Perform operations according to business logic
            }
            else
            {
                // Object not of Product type
            }
        });
    }
    else
    {
        // Not all of the keys are present in cache 
    }
}
catch(error)
{
    // Handle errors
}

CacheItems in Bulk

You can also retrieve CacheItems in bulk using GetCacheItemBulk method. Here is an example:

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

    // Fetch a products array
    Product[] products = FetchProductsFromDB();

    // Get keys to fetch from cache 
    string[] keys = new string[products.Length];
    int index = 0;

    foreach (var product in products)
    {
        // Using the same unique cache key for this product
        keys[index] = $"Product:{product.ProductID}";
        index++;
    }

    // Retrieve items from cache in a dictionary
    IDictionary<string, CacheItem> retrievedItems = cache.GetCacheItemBulk(keys);

    // Check if any keys have failed to be retrieved
    if (retrievedItems.Count == keys.Length)
    {
        foreach (KeyValuePair<string, CacheItem> entry in retrievedItems)
        {
            if (entry.Value is CacheItem)
            { 
                Product prod = entry.Value.GetValue<Product>();
                // Perform operations according to business logic
            }
            else
            {
                // Object not of Product type
            }
        }
    }
    else
    {
        // Not all of the keys are present in cache 
        foreach (var key in keys)
        {
            if (retrievedItems.ContainsKey(key) == false)
            {
                // This key does not exist in cache 
            }
        }
    }
}
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
}

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

    // Fetch a products array
    Product[] products = fetchProducts();

    // Get keys to fetch from cache
    ArrayList<String> keys = new ArrayList<>(products.length);

    for (Product product : products)
    {
        String key = "Product:" + product.getProductID();
        keys.add(key);
        cache.insert(key , product);
    }

    // Retrieve items from cache in a Map
    java.util.Map<String, CacheItem> retrievedItems = cache.getCacheItemBulk(keys);

    // Check if any keys have failed to be retrieved
    if (retrievedItems.size() == keys.size())
    {
        for (java.util.Map.Entry<String, CacheItem> entry : retrievedItems.entrySet())
        {
            if (entry.getValue() != null)
            {
                Product prod = entry.getValue().<Product>getValue(Product.class);

                // Perform operations according to business logic
            }
            else
            {
                // Object not of Product type
            }
        }
    }
    else
    {
        // Not all of the keys are present in cache
        for (String key : keys)
        {
            if (!retrievedItems.containsKey(key))
            {
                // This key does not exist in cache
            }
        }
    }
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{  
   // Any generic exception like NullPointerException or IllegalArgumentException
}

// This is an async method
try
{
    // Pre-condition: Cache is already connected

    // Get Product from database against given ProductID
    var products = await this.fetchProductFromDB();

    // Get keys to fetch from cache 
    var keys = [products.length];
    var index = 0;

    products.forEach(product => {
        keys[index] ="Product:" + this.product.getProductID();
        index++;
    });

    // Get bulk from cache
    var retrievedItems = this.cache.getCacheItemBulk(keys);

    // Check if any keys have failed to be retrieved
    if(retrievedItems.size() == keys.length)
    {
        retrievedItems.forEach(entry => {
            if(entry.getValue() instanceof ncache.CacheItem)
            {
                var prod = entry.getValue();

                // Perform operations according to business logic
            }
            else
            {
                // Object not of Product type
            }
        });
    }
    else
    {
        // Not all of the keys are present in cache

        keys.forEach(key => {

            if(retrievedItems.containsKey(key) == false)
            {
                //  key does not exist in cache 
            }
        }); 
    }
}
catch(error)
{
    // Handle errors
}

Additional Resources

NCache provides sample application for Basic Operations on GitHub.

Retrieve Existing Cache Data

Note

Pre-requisites

Custom Object

Important

CacheItem

Important

JsonObject

Note

Data Structure

Note

Note

Bulk Items

Important

CacheItems in Bulk

Additional Resources

See Also