Cache

Constructor

# new Cache()

Methods

# (async) add(key, item, writeThruOptions) → {CacheItemVersion}

Adds a CacheItem to the cache. It also lets you specify the WriteThruOptions. Using CacheItem, you can also specify properties for the cache items, for e.g., expiration and priority.

Parameters:

Name	Type	Default	Description
`key`	string		Unique key to identify the cache item.
`item`	CacheItem		CacheItem is to be stored in the cache.
`writeThruOptions`	WriteThruOptions	null	WriteThruOptins regarding updating the data source. This can be either WriteThru, WriteBehind or None.

Returns:

Type: CacheItemVersion

Example

const ncache  = require('ncache-client');

let cache = await ncache.CacheManager.getCache("test-Cache"); 

await cache.add('key', new ncache.CacheItem("Value"));

const cacheValue = await cache.get('key', ncache.JsonDataType.Scaler);

await cache.close();

# (async) addBulk(items, writeThruOptions) → {Map.<string, Object>}

Adds a Map of cache keys with CacheItem to the cache with the WriteThruOptions. The CacheItem contains properties to associate with the item, like expiration, dependencies and eviction information.

Parameters:

Name	Type	Default	Description
`items`	Map.<string, CacheItem>		Dictionary of keys and CacheItem. Keys must be unique.
`writeThruOptions`	WriteThruOptions	null	WriteThruOptions regarding updating data source. This can be WriteThru, WriteBehind or None.

Returns:

Dictionary of Keys along with Exception that were unable to store in cache.

Type: Map.<string, Object>

Example

//The following example demonstrates how to add items to the cache with an absolute expiration 2 minutes from now, a priority of high, 
//and that notifies the application when the item is removed from the cache.

let cache = await ncache.CacheManager.getCache("myCache");
let cacheItems = new Array[2];

let product_1 = new Product();
product_1.Id = 1;
product_1.Name = "Chai";

let product_2 = new Product();
product_2.Id = 2;
product_2.Name = "Chang";


cacheItems[0] = new CacheItem(product_1);
cacheItems[0].setExpiration(new ncache.Expiration(ncache.ExpirationType.Absolute, new ncache.TimeSpan(0, 2, 0)));
cacheItems[0].setPriority(ncache.CacheItemPriority.High);

cacheItems[1] = new CacheItem(product_2);
cacheItems[1].setExpiration(new ncache.Expiration(ncache.ExpirationType.Absolute, new ncache.TimeSpan(0, 2, 0)));
cacheItems[1].setPriority(ncache.CacheItemPriority.Normal);

let map = new Map();
map.set("Product0",cacheItems[0]);
map.set("Product1",cacheItems[1]);
    
let writeThruOptions = new ncache.WriteThruOptions(ncache.WriteMode.WriteThru, "ProdDataSource1");

await cache.addBulk(map, writeThruOptions);

# clear()

Clear the Cache

# (async) clearClientCache()

clear the client cache

# (async) close()

Closes cache connection

# (async) contains(key)

checks if the CacheItem against key is found in Cache

Parameters:

Name	Type	Description
`key`	string	The key to locate in the Cache.

Returns:

true if the Cache contains an element with the specified key; otherwise, false.

Example

//The following example demonstrates how to check for containment of an item in the Cache

let cache = await  ncache.CacheManager.getCache("myCache");

if(await cache.Contains("Product0")){
		Response.Write("Item found!");
}

# (async) containsBulk(keys)

checks if the CacheItems against keys are found in Cache

Parameters:

Name	Type	Description
`keys`	IterableIterator	collection of keys.

Returns:

Dictionary of Keys with Flag to dertermine presence of each key in cache. true if the Cache contains an element with the specified key; otherwise, false.

Example

//The following example demonstrates how to check for containment of an item in the Cache.
let cache = await CacheManager.getCache("myCache");

let keys = ["Product0","Product1"];

let result = await cache.ContainsBulk(keys);

# (async) delete(key, lockHandle, version, writeThruOptions)

Removes the specified item from the ICache. You can also specify the write option such that the item may be removed from both cache and data source. If version is specified then item will only be removed if the specified version is still the most recent version in the cache.

Parameters:

Name	Type	Description
`key`	string	Unique key of the item to be removed.
`lockHandle`	LockHandle	If the item is locked, it can be removed only if the correct lockHandle is specified. lockHandle should be the same which was used initially to lock the item, otherwise you will get the 'OperationFailedException'.
`version`	CacheItemVersion	The version of the item to be removed. The item is removed from the cache only if this is still the most recent version in the cache.
`writeThruOptions`	WriteThruOptions	WriteThruOptions regarding updating the data source. This can be either WriteThru, WriteBehind or None.

Example

//Example demonstrates how to delete a locked item in the cache with write through options.
let cache = await ncache.CacheManager.getCache("myCache");

let product = new Product();
product.Id = 1;
product.Name = "Chai";

let key = "Product0";

let version = await cache.add(key, new ncache.CacheItem(product, "FQN.Product"));

let lockHandle = new ncache.LockHandle();

let item = cache.get(key, ncache.JsonDataType.Object, null, null, true, new ncache.TimeSpan(0,0,2), lockHandle);

if (item !== null)
{
    try
    {
        let writeThruOptions = new ncache.WriteThruOptions(ncache.WriteMode.WriteThru, "ProdDataSource1");

        await cache.delete(key, ncache.JsonDataType.Object ,lockHandle, version, writeThruOptions);
    }
    catch (ex)
    {
    ...
    }
}

# (async) deleteBulk(keys, writeThruOptions)

Removes the specified items from the Cache. You can also specify the write option such that the items may be removed from both cache and data source.

Parameters:

Name	Type	Description
`keys`	IterableIterator	List of unique keys to reference the items.
`writeThruOptions`	WriteThruOptions	WriteThruOptions regarding updating the data source. This can be either WriteThru, WriteBehind or None.

# (async) get(key, classObj, version, readThruOptions, acquireLock, lockTimeout, lockHandle)

Retrieves the specified item from the Cache object, with read-through caching option available. If the option of read-through has been set, the object will be fetched from the data source if it does not exist in cache. It accepts the CacheItemVersion by reference. If null is passed for CacheItemVersion, then the version of the object from the cache is returned. If non-null CacheItemVersion is passed, then object is returned from the cache only if that is the current version of the object in the cache

Parameters:

Name	Type	Description
`key`	string	The unique identifier for the cache item to be retrieved.
`classObj`	JsonDataType	Specifies the type of value obtained from the cache.
`version`	CacheItemVersion	The version of the object.
`readThruOptions`	ReadThruOptions	ReadThruOptions to read from data source. These can be either ReadThru, ReadThruForced or None.
`acquireLock`	boolean	A flag to determine whether to acquire a lock or not.
`lockTimeout`	TimeSpan	The TimeSpan after which the lock is automatically released.
`lockHandle`	LockHandle	An instance of LockHandle to hold the lock information.

Returns:

The retrieved cache item, or a null reference if the key is not found.

Examples

//Example demonstrates how to retrieve the value cached with read thru option and version
let cache = await ncache.CacheManager.getCache("myCache");

let product = new Product();
product.Id = 1;
product.Name = "Chai";

let key = "Product0";

let version = await cache.add(key, new ncache.CacheItem(product, "FQN.Product"));

let readThruOptions = new ncache.ReadThruOptions(ncache.ReadMode.ReadThru);

let product = await cache.get(key,ncache.JsonDataType.Object, readThruOptions, version);

//Example demonstrates how to retrieve the cached value and acquire a lock at the same time for minutes.
let cache = await ncache.CacheManager.getCache("myCache");

let product = new Product();
product.Id = 1;
product.Name = "Chai";

let key = "Product0";

await cache.add(key, new ncache.CacheItem(product, "FQN.Product"));

let lockHandle = new ncache.LockHandle();
 
let cachedItem = await cache.get(key, ncache.JsonDataType.Object, null, null, true, new ncache.TimeSpan(0, 2, 0),lockHandle);

# (async) getBulk(keys, classOb, readThruOptions) → {Map.<string, CacheItem>}

Retrieves the objects from cache for the given keys as key-value pairs. Options regarding reading from data source (read-through) can be set.

Parameters:

Name	Type	Default	Description
`keys`	IterableIterator		The keys against which items are to be fetched from cache.
`classOb`	JsonDataType		Specifies the type of value obtained from the cache.
`readThruOptions`	ReadThruOptions	null	ReadThruOptions to read from data source. These can be either ReadThru, ReadThruForced or None.

Returns:

The retrieved cache items as key-value pairs.

Type: Map.<string, CacheItem>

Example

//Example demonstrates how to retrieve the value cached against multiple keys with Read through Options.
let cache = await ncache.CacheManager.getCache("myCache");

let keys = ["Product0", "Product1", "Product2"]

let readThruOptions = new ncache.ReadThruOptions(ncache.ReadMode.ReadThru);

let items = await cache.getBulk(keys, readThruOptions);

# (async) getCacheItem(key, version, readThruOptions, acquireLock, lockTimeout, lockHandle) → {CacheItem}

Parameters:

Name	Type	Description
`key`	string	Unique identifier for the cache item to be retrieved.
`version`	CacheItemVersion	The CacheItemVersion of the object.
`readThruOptions`	ReadThruOptions	ReadThruOptions regarding reading from data source. It can be either ReadThru, ReadThruForced or None.
`acquireLock`	boolean	A flag to determine whether to acquire a lock or not.
`lockTimeout`	TimeSpan	The TimeSpan after which the lock is automatically released.
`lockHandle`	LockHandle	An instance of LockHandle to hold the lock information.

Returns:

The specified CacheItem. If the key does not exist, it returns a null reference.

Type: CacheItem

Examples

//Example demonstrates how to retrieve cache item with lock handle, timeout and flag box server control.
let cache = await ncache.CacheManager.getCache("myCache");
let key = "Product0";
let lockHandle = new ncache.LockHandle();
let item = cache.getCacheItem(key, null, null, true, TimeSpan.FromSeconds(30), lockHandle);

//Example demonstrates how to retrieve the cache item with read thru option and cache item version.
let cache = await ncache.CacheManager.getCache("myCache");

let product = new Product();
product.Id = 1;
product.Name = "Chai";

let key = "Product0";

let version = await cache.add(key, new ncache.CacheItem(product, "FQN.Product"));

let readThruOptions = new ncache.ReadThruOptions(ncache.ReadMode.ReadThru);

let item = await cache.getCacheItem(key, readThruOptions, version);

# (async) getCacheItemBulk(keys, readThruOptions)

Retrieves the specified CacheItems from the Cache object. This overload also allows specifying the read-through option. If read-through is set and the object does not exist in the cache, the object will be fetched from the data source and added to the cache.

Parameters:

Name	Type	Default	Description
`keys`	IterableIterator		list of unique identifier for the cache items to be retrieved.
`readThruOptions`	ReadThruOptions	null	ReadThruOptions regarding reading from data source. It can be either ReadThru, ReadThruForced or None.

Returns:

Map<string, Exception>

Example

//Example demonstrates how to retrieve the cache items with read thru option.
let cache = await ncache.CacheManager.getCache("myCache");

let keys = 
[
    "Product0",
    "Product1",
    "Product2"
]

let readThruOptions = new ncache.ReadThruOptions(ncache.ReadMode.ReadThru);
let items = await cache.getCacheItemBulk(keys, readThruOptions);

# (async) getClientInfo() → {ClientInfo}

Displays the information related to this client.

Returns:

Type: ClientInfo

# (async) getConnectedClientList() → {Array.<ClientInfo>}

Gets the information of all connected clients to the cache.

Returns:

Type: Array.<ClientInfo>

# (async) getCount() → {long}

get number of CacheItem in Cache

Returns:

Type: long

# (async) getDataStructuresManager() → {DataStructureManager}

returns instance of {DataStructureManager}

Returns:

Type: DataStructureManager

# (async) getIfNewer(key, cls, version)

Gets an object from the cache only if a newer version of the object exists in cache.

Parameters:

Name	Type	Description
`key`	string	Unique key used to reference the desired object.
`cls`	ClassType	Specifies the type of value obtained from the cache.
`version`	CacheItemVersion	The version of the specified object.

Returns:

If a newer object exists in the cache, the object is returned. Otherwise, null is returned.

Example

//Example demonstrates how to get a newer version of the item from cache if it exists.
let cache =await ncache.CacheManager.getCache("myCache");

let product = new Product();
product.Id = 1;
product.Name = "Chai";

let key = "Product0";

let version = await cache.add(key, new ncache.CacheItem(product, "FQN.Product"));

let product = await cache.getIfNewer(key, ncache.JsonDataType.Object, version);

# (async) getIfNewerCacheItem(key, version) → {CacheItem}

Gets an CacheItem from the cache only if a newer version of the object exists in cache.

Parameters:

Name	Type	Description
`key`	string	Unique key used to reference the desired object.
`version`	CacheItemVersion	The version of the specified object.

Returns:

Type: CacheItem

# (async) getMessagingService() → {MessagingService}

returns instance of {MessagingService}

Returns:

Type: MessagingService

# (async) getNotificationService() → {NotificationService}

returns instance of {NotificationService}

Returns:

Type: NotificationService

# (async) getSearchService() → {SearchService}

returns instance of {SearchService}

Returns:

Type: SearchService

# (async) insert(key, item, writeThruOptions, lockHandle, releaseLock) → {CacheItemVersion}

Inserts a CacheItem into the cache, allowing to specify the Write-Through option

Parameters:

Name	Type	Description
`key`	string	Unique key to identify the cache item.
`item`	CacheItem	The CacheItem that is to be inserted into the cache.
`writeThruOptions`	WriteThruOptions	WriteThruOptins regarding updating the data source. This can be either WriteThru, WriteBehind or None.
`lockHandle`	LockHandle	An instance of LockHandle that holds the lock information. If the item is locked, then it can only be updated if the correct lockHandle is specified.
`releaseLock`	Boolean	A flag to determine whether or not the lock should be released after operation is performed.

Returns:

Type: CacheItemVersion

Example

const ncache  = require('ncache-client');

let cache = await ncache.CacheManager.getCache("test-Cache"); 

await cache.insert('key', new ncache.CacheItem("Value"));

const cacheValue = await cache.get('key', ncache.JsonDataType.Scaler);

await cache.close();

# (async) insertBulk(items, writeThruOptions) → {Map.<string, Object>}

Inserts a Map of cache keys with CacheItem to the cache with the WriteThruOptions. The CacheItem contains properties to associate with the item, like expiration, dependencies and eviction information.

Parameters:

Name	Type	Default	Description
`items`	Map.<string, CacheItem>		Dictionary of keys and CacheItem. Keys must be unique.
`writeThruOptions`	WriteThruOptions	null	WriteThruOptions regarding updating data source. This can be WriteThru, WriteBehind or None.

Returns:

Map of Keys along with Exception that were unable to store in cache.

Type: Map.<string, Object>

Example

//The following example demonstrates how to insert items to the cache with an absolute expiration 2 minutes from now, a priority of high, 
//and that notifies the application when the item is removed from the cache.

let cache = await ncache.CacheManager.getCache("myCache");
let cacheItems = new Array[2];

let product_1 = new Product();
product_1.Id = 1;
product_1.Name = "Chai";

let product_2 = new Product();
product_2.Id = 2;
product_2.Name = "Chang";


cacheItems[0] = new CacheItem(product_1);
cacheItems[0].setExpiration(new ncache.Expiration(ncache.ExpirationType.Absolute, new ncache.TimeSpan(0, 2, 0)));
cacheItems[0].setPriority(ncache.CacheItemPriority.High);

cacheItems[1] = new CacheItem(product_2);
cacheItems[1].setExpiration(new ncache.Expiration(ncache.ExpirationType.Absolute, new ncache.TimeSpan(0, 2, 0)));
cacheItems[1].setPriority(ncache.CacheItemPriority.Normal);

let map = new Map();
map.set("Product0",cacheItems[0]);
map.set("Product1",cacheItems[1]);
    
let writeThruOptions = new ncache.WriteThruOptions(ncache.WriteMode.WriteThru, "ProdDataSource1");

await cache.insertBulk(map, writeThruOptions);

# (async) lock(key, lockTimeout, lockHandle)

Acquires a lock on an item in the cache.

Parameters:

Name	Type	Description
`key`	string	key of cached item to be locked.
`lockTimeout`	TimeSpan	An instance of TimeSpan after which the lock is automatically released.
`lockHandle`	LockHandle	An instance of LockHandle that will be filled in with the lock information if lock is acquired successfully.

Returns:

Whether or not lock was acquired successfully.

Example

//Example demonstrates how to lock a cached item.
let key = "Product0";
let lockHandle = new ncache.LockHandle();
let locked = theCache.lock(key, new ncache.TimeSpan(0,0,10), lockHandle);
...

# (async) remove(key, cls, lockHandle, version, writeThruOptions) → {CacheItem}

Parameters:

Name	Type	Description
`key`	string	Unique key of the item to be removed.
`cls`	JsonDataType	Specifies the type of value removed from the cache.
`lockHandle`	LockHandle	If the item is locked, it can be removed only if the correct lockHandle is specified. lockHandle should be the same which was used initially to lock the item, otherwise you will get the 'OperationFailedException'.
`version`	CacheItemVersion	The version of the item to be removed. The item is removed from the cache only if this is still the most recent version in the cache.
`writeThruOptions`	WriteThruOptions	WriteThruOptions regarding updating the data source. This can be either WriteThru, WriteBehind or None.

Returns:

Type: CacheItem

Example

//Example demonstrates how to remove a locked item in the cache with write through options.
let cache = await ncache.CacheManager.getCache("myCache");

let product = new Product();
product.Id = 1;
product.Name = "Chai";

let key = "Product0";

let version = await cache.add(key, new ncache.CacheItem(product, "FQN.Product"));

let lockHandle = new ncache.LockHandle();

let item = cache.get(key, ncache.JsonDataType.Object, null, null, true, new ncache.TimeSpan(0,0,2), lockHandle);

if (item !== null)
{
    try
    {
        let writeThruOptions = new ncache.WriteThruOptions(ncache.WriteMode.WriteThru, "ProdDataSource1");

        await cache.remove(key, ncache.JsonDataType.Object ,lockHandle, version, writeThruOptions);
    }
    catch (ex)
    {
    ...
    }
}

# (async) removeBulk(keys, classOb, writeThruOptions)

Removes the specified items from the Cache. You can also specify the write option such that the items may be removed from both cache and data source.

Parameters:

Name	Type	Description
`keys`	IterableIterator	List of unique keys to reference the items.
`classOb`	JsonDataType	Specifies the type of value removed from the cache.
`writeThruOptions`	WriteThruOptions	WriteThruOptions regarding updating the data source. This can be either WriteThru, WriteBehind or None.

Returns:

Removed Object

Example

//The following example demonstrates how you can remove an item from your application's Cache object.
let cache = await ncache.CacheManager.getCache("myCache");

let keys = 
[
    "Product0",
    "Product1",
    "Product2"
];

let writeThruOptions = new ncache.WriteThruOptions(ncache.WriteMode.WriteThru, "ProdDataSource1");

await cache.removeBulk(keys, writeThruOptions);

# toString()

returns name of Cache

# (async) unlock(key, lockHandle)

Unlocks a locked cached item if the correct LockHandle is specified. If LockHandle is null Forcefully unlocks a locked cached item.

Parameters:

Name	Type	Default	Description
`key`	string		Key of the cached item to be unlocked.
`lockHandle`	LockHandle	null	An instance of LockHandle that is generated when the lock is acquired.

Example

// Following example demonstrates how to unlock a cached item.
...
let key = "Product0";
...
await cache.Unlock(key, lockHandle);
...

# (async) updateAttributes(key, attributes)

Update {CacheItemAttributes} of an existing item in cache.

Parameters:

Name	Type	Description
`key`	string	Unique key to identify the cache item.
`attributes`	CacheItemAttributes	An instance of CacheItemAttributes to update item in the cache.

Returns:

Flag that determines status of the Update operation.true if attributes of the item in cache was updated successfully and false if operation failed.

Example

// Example demonstrates how to update Absolute Expiration of 5 minutes on an existing item in cache. 

let cache = await ncache.CacheManager.getCache("myCache");

let product = new Product();
product.Id = 1;
product.Name = "Chai";

let key = "Product0";

await cache.insert(key, product);

let attributes = new ncache.CacheItemAttributes();
attributes.setAbsoluteExpiration(new Date().setMinutes(5));

if(await cache.UpdateAttributes(key, attributes)) {
...
}