Using JSON Array as Cache Data

Note

This feature is available in NCache Enterprise and Professional editions.

JsonArray represents JArray in JSON standards in NCache’s domain mapping arrays or list like collections in NCache’s domain to JArray according to JSON conventions. JsonArray is quite similar to JsonObject, with the difference of JsonObject being a key, value pair whereas JsonArray being a collection.

The values added in JsonArray can either be JsonValue, JsonObject, JsonNull or even another JsonArray; provided it is not adding itself to itself. Furthermore, you can update and add values in JsonArray at specified indices using the indexer property. Providing value at a non-existing positive index will add at the specified index and all values from the last existing index to the new index will be JsonNull.

If a value is already present at the specific index, the new value overwrites existing value. Moreover you can also remove values from an array by specifying the values using the Remove method.

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.

Install the following NuGet package in your application.
- Alachisoft.NCache.SDK
Include the following namespace in your application:
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.JSON
- Alachisoft.NCache.Runtime.Exceptions
Cache must be JSON Serialized through NCache Web Manager.
The application must be connected to cache before performing the operation.
Cache must be running.
For API details refer to: ICache, JsonArray, Insert, Get, Remove, AddAttribute.
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.JSON.*
- import com.alachisoft.ncache.runtime.client.*
- import com.alachisoft.ncache.runtime.exceptions.*
Cache must be JSON Serialized through NCache Web Manager.
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, JsonArray, insert, get, remove, addAttribute.
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.

Get JsonArray from Json String

Similar to JsonObject, JsonArray also provides an overload where a JSON data string is passed containing a JsonArray and the instance of the JsonArray is populated as a result. In case of an invalid string; ArgumentException is thrown.

Below is an example which populates an instance of a JsonArray by passing a json data string.

.NET/.NET Core
Java

try
{
    // The data provided in the string is a JsonArray
    string jsonString = " ['ProductIDs', { 'ProductID' : 1001 }, { 'ProductID' : 1002 }, { 'ProductID' : 1003 } ]";

    // Populate an instance of the JsonArray by passing the string
    var jsonArray = new JsonArray(jsonString);

    // Use the retrieved JsonArray for further operations
}
catch (ArgumentException argumentException)
{
    // Invalid JSON string passed
}

try
{
    // The data provided in the string is a JsonArray
    String jsonString = " ['ProductIDs', { 'ProductID' : 1001 }, { 'ProductID' : 1002 }, { 'ProductID' : 1003 } ]";

    // Populate an instance of the JsonArray by passing the string
    var jsonArray = new JsonArray(jsonString);

    // Use the retrieved JsonArray for further operations
}
catch (IllegalArgumentException ex)
{
    // Invalid JSON string passed
}

Create a JsonArray

You can create a JsonArray and then add values in it. The Add method lets you add instances of JsonObject, JsonValue, JsonNull or JsonArray. It is important to note that a JsonArray cannot add itself to itself. This form of relation is not allowed at any nested level i.e., a JsonArray ‘A’ cannot add a JsonObject ‘B’ that contains ‘A’ as an attribute and so on.

The following example creates an JsonArray and add values in it.

.NET/.NET Core
Java

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

    // Create a new JsonArray
    var jsonArray = new JsonArray();

    // Get top ten products from the data source
    Product[] products = FetchTop10Products();

    // Convert these products in JsonObjects
    foreach (Product product in products)
    {
        // Create jsonObject and set its attributes
        // ProductName is string so it needs to be added with JsonValue
        var jsonProduct = new JsonObject();
        jsonProduct.AddAttribute("ProductID", product.ProductID);
        jsonProduct.AddAttribute("ProductName", (JsonValue)product.ProductName);
        jsonProduct.AddAttribute("Category", (JsonValue)product.Category);
        jsonProduct.AddAttribute("UnitPrice", product.UnitPrice);
        jsonProduct.AddAttribute("UnitsInStock", product.UnitsInStock);

        // Add jsonObjects to the jsonArray
        jsonArray.Add(jsonProduct);
    }
    // Create a unique key for the array
    string key = "Products";

    // Create a new CacheItem for product and then insert
    var cacheItem = new CacheItem(jsonArray);

    // Insert the array in the cache with the key
    cache.Insert(key, cacheItem);

}
catch(OperationFailedException ex)
{
    if (ex.ErrorCode == NCacheErrorCodes.ATTRIBUTE_ALREADY_EXISTS)
    {
        // An attribute already exists with the same name
    }
    else if (ex.ErrorCode == NCacheErrorCodes.REFERENCE_TO_SELF)
    {
        // No object can contain a reference to itself
    }
    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
    // Cache is JSON serialized

    // Create a new JsonArray
    var jsonArray = new JsonArray();

    // Get top ten products from the data source
    Product[] products = fetchTop10Products();

    // Convert these products in JsonObjects
    for (Product product: products) 
    {
        // Create jsonObject and set its attributes
        // ProductName is string so it needs to be added with JsonValue
        var 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.getUnitPrice()));
        jsonProduct.addAttribute("UnitsInStock",new JsonValue(product.getUnitsInStock()));

        // Add jsonObjects to the jsonArray
        jsonArray.add(jsonProduct);
    }

    // Create a unique key for the array
    String key = "Products";

    // Create a new CacheItem for product and then insert
    CacheItem cacheItem = new CacheItem(jsonArray);

    // Insert array in the cache with key
    cache.insert(key, cacheItem);

}
catch (OperationFailedException ex)
{
    if(ex.getErrorCode() == NCacheErrorCodes.ATTRIBUTE_ALREADY_EXISTS)
    {
        // An attribute already exists with the same name
    }
    else if (ex.getErrorCode() == NCacheErrorCodes.REFERENCE_TO_SELF)
    {
        // No object can contain a reference to itself
    }
    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
}

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

Add Value at a Particular Index

JsonArray allows you to add JSON values at specified indices via the indexer. The idea is that if an item already exists at the specified index, it will be overwritten. If the item is being assigned at a non-existing positive index, the item will be added at the specified index and all the values between the last index and the new index will be JsonNull. Note that in order to add a value at a certain index, you have to explicitly specify JsonValue class for primitive types.

The following example adds a value to the fifth index of the array. Where the last value of the array was at the third index. So the values between the second and the sixth index will be JsonNull.

.NET/.NET Core
Java

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

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

    // Create a new JSON object
    // Set attributes of the object
    var jsonProduct = new JsonObject();
    jsonProduct.AddAttribute("ProductID", product.ProductID);

    // ProductName is string so it needs to be added with JsonValue
    jsonProduct.AddAttribute("ProductName", (JsonValue)product.ProductName);
    jsonProduct.AddAttribute("Category", (JsonValue)product.Category);
    jsonProduct.AddAttribute("UnitPrice", product.UnitPrice);
    jsonProduct.AddAttribute("UnitsInStock", product.UnitsInStock);

    // Create a new JsonArray
    var array = new JsonArray();

    // Add the items to the array
    // The values at the index 3 and 4 will be JsonNull
    array.Add((JsonValue)"ProductList");
    array.Add(jsonProduct);
    array[5] = (JsonValue)2.02;
    array[6] = (JsonValue)new DateTime(2009, 10, 10);

    // Create a unique key for the array
    string key = "Products";

    // Create a new CacheItem for product and then insert
    var cacheItem = new CacheItem(array);

    // Insert the array in the cache with the key
    cache.Insert(key, cacheItem);
}
catch(OperationFailedException ex)
{
    if (ex.ErrorCode == NCacheErrorCodes.ATTRIBUTE_ALREADY_EXISTS)
    {
        // An attribute already exists with the same name
    }
    else if (ex.ErrorCode == NCacheErrorCodes.REFERENCE_TO_SELF)
    {
        // No object can contain a reference to itself
    }
    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
    // Cache is JSON serialized

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

    // Create a new JSON object
    // Set attributes of the object
    var 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.getUnitPrice()));
    jsonProduct.addAttribute("UnitsInStock",new JsonValue(product.getUnitsInStock()));

    // Create a new JsonArray
    JsonArray array = new JsonArray();

    // Add the items to the array
    // The values at the index 3 and 4 will be JsonNull
    array.add(new JsonValue("ProductList"));
    array.add(jsonProduct);
    array.setItem(5,new JsonValue(2.02));
    array.setItem(6,new JsonValue(new LocalDateTime[2009-10-10]));

    // Create a unique key for the array
    String key = "Products";

    // Create a new CacheItem for product and then insert
    var cacheItem = new CacheItem(array);

    // Insert the array in the cache with the key
    cache.insert(key, cacheItem);
}
catch (OperationFailedException ex)
{
    if(ex.getErrorCode() == NCacheErrorCodes.ATTRIBUTE_ALREADY_EXISTS)
    {
        // An attribute already exists with the same name
    }
    else if (ex.getErrorCode() == NCacheErrorCodes.REFERENCE_TO_SELF)
    {
        // No object can contain a reference to itself
    }
    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
}

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

Retrieve a JsonArray

You can get a JsonArray using the Get method. You can retrieve a whole JsonArray using this method. Given below is an example showing how to retrieve a JsonArray created previously.

.NET/.NET Core
Java

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

    // An array is already added in the cache with the values
    // Specify the key of the array
    string key = "Products";

    // Retrieve the array from the cache with the help of the key
    var array = cache.Get<JsonArray>(key);
}
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

    // An array is already added in the cache with the values
    // Specify the key of the array
    String key = "Products";

    // Retrieve the array from the cache with the help of the key
    var array = InitializeCache.cache.get(key,JsonArray.class);
}
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
}

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

Retrieve Value at a Particular Index

This value returned is of JsonValueBase type. In order to make use of it, you have to determine the right type of JSON value to which it is to be cast in order to use it. Providing a non-existent index to get the value, will throw an Index out of bound exception.

The following example adds values to the array and then remove them by specifying the index.

.NET/.NET Core
Java

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

    // Create a new JsonArray
    var array = new JsonArray();

    // Add values to the array
    var prod = new JsonObject();
    array.Add(prod);
    array.Add(20);
    array[10] = (JsonValue)new DateTime(2010, 10, 10);

    // Retrieve the value of the specified index
    JsonValueBase valueBase = array[10];

    switch (valueBase.DataType)
    {
        case JsonDataType.Object:
            // Use as JsonObject
            break;

        case JsonDataType.Array:
            // Use as JsonArray
            break;

        case JsonDataType.Null:
            // Use as JsonNull
            break;

        default:
            JsonValue value = valueBase as JsonValue;
            // Use value
            break;
    }
}
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

    // Create a new JsonArray
    var array = new JsonArray();

    // Add values to the array
    var prod = new JsonObject();
    array.add(prod);
    array.setItem(10,new JsonValue(new LocalDateTime[2010-10-10]));

    // Retrieve the value of the specified index
    JsonValueBase valueBase = array.getItem(10);
    switch(valueBase.getDataType())
    {
        case Object:
            // Use as JsonObject
            break;
        case Array:
            // Use as JsonArray
            break;
        case Null:
            // Use as JsonNull
            break;
        default:
            JsonValue value = null;
            if(valueBase instanceof JsonValue)
            {
                value = (JsonValue) valueBase;
            }
           // use value
           break;
        }
}
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
}

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

Remove Value from a JsonArray

You can remove a value from an array by specifying the value in the Remove method. This method returns a Boolean flag that can be used to determine whether the item was removed or not. You can specify the value placed at the specific index and not the index in order to remove the value from the array. Re-insert with the updated array with the removed value in the cache. You cannot remove a value at a particular index by any method. However, you can set a value at a particular index as JsonNull.

It is important to understand that remove works on data and not references. This means when removing an item with a similar item (i.e. they both contain exactly the same data) existing in the JsonArray, the item first encountered will be removed always even if you provide the same reference that was used to add the item into JsonArray.

The following example removes the value from the array previously created using the Remove method and then re-inserts the array in the cache.

.NET/.NET Core
Java

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

    // An array is already added in the cache with the values
    // Specify the key of the array
    string key = "Products";

    // Retrieve the array from the cache with the help of the key
    var array = cache.Get<JsonArray>(key);

    // Remove a product from the array
    array.Remove(jsonProduct2);

    // Create a new CacheItem for product and then insert
    var cacheItem = new CacheItem(array);

    // Re-insert the array in the cache with the value removed
    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
}

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

    // An array is already added in the cache with the values
    // Specify the key of the array
    String key = "Products";

    // Retrieve the array from the cache with the help of the key
    JsonArray array = cache.get(key,JsonArray.class);

    // Remove a product from the array
    array.remove(jsonProduct);

    // Create a new CacheItem for product and then insert
    CacheItem cacheItem = new CacheItem(array);

    // Re-insert the array in the cache with the value removed
    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 NullPointerException or IllegalArgumentException
}

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

Remove JsonNull from an Array

You can also remove JsonNull from an array. As mentioned in section “Remove Value from a JsonArray”, remove works on data and not references. Therefore, the first JsonNull encountered will be removed from JsonArray.

The following example will remove one null value from an array using the Remove method.

.NET/.NET Core
Java

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

   // An array is already added in the cache with the values
   // Specify the key of the array
   string key = "Products";

   // Retrieve the array from the cache with the help of the key
   var array = cache.Get<JsonArray>(key);

   // Remove a product from the array
   array.Remove(new JsonNull());

   // Create a new CacheItem for product and then insert
   var cacheItem = new CacheItem(array);

   // Re-insert the array in the cache with the value removed
   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
}

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

    // An array is already added in the cache with the values
    // Specify the key of the array
    String key = "Products";

    // Retrieve the array from the cache with the help of the key
    JsonArray array = InitializeCache.cache.get(key,JsonArray.class);

    // Remove a product from the array
    array.remove(new JsonNull());

    // Create a new CacheItem for product and then insert
    CacheItem cacheItem = new CacheItem(array);

    // Re-insert the array in the cache with the value removed
    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 NullPointerException or IllegalArgumentException
}

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

Additional Resources

NCache provides sample application for Cache Data as JSON on GitHub.

Using JSON Array as Cache Data

Note

Note

Pre-Requisites

Get JsonArray from Json String

Create a JsonArray

Add Value at a Particular Index

Retrieve a JsonArray

Retrieve Value at a Particular Index

Remove Value from a JsonArray

Remove JsonNull from an Array

Additional Resources

See Also