Counter Behavior and Usage in Cache
Note
This feature is only available in NCache Enterprise Edition.
A counter is a single long value data structure stored in the cache which can be incremented, decremented, locked, and have events registered against it. For example, a counter can be used to store the views every time a video is viewed on a social media site. It can also be used to store subscriptions against a website where people can subscribe or unsubscribe.
NCache further enhances this counter by providing NCache specific features such as Groups, Tags, Expiration, Locking, Dependencies, and more. For example, you can specify a counter against the group SubscriptionDetails which can contain customer objects as well as the subscription counter.
Behavior
- Null is not a supported value type.
- Counters are named. Hence, you need to provide a unique cache key for a counter.
Prerequisites
- Install the following NuGet package in your application:
- Include the following namespaces in your application:
Alachisoft.NCache.Client
Alachisoft.NCache.Client.DataTypes
Alachisoft.NCache.Runtime.Exceptions
Alachisoft.NCache.Client.DataTypes.Counter
- Cache must be running.
- The application must be connected to cache before performing the operation.
- For API details, refer to: ICache, CreateCounter, Decrement, DecrementBy, GetCounter, Increment, Lock, SetValue, Unlock.
- Make sure that the data being added is serializable.
- 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 dependency in your pom.xml file:
<dependency>
<groupId>com.alachisoft.ncache</groupId>
<artifactId>ncache-client</artifactId>
<version>x.x.x</version>
</dependency>
- Import the following packages in your application:
import com.alachisoft.ncache.client.*;
import com.alachisoft.ncache.runtime.exceptions.*;
import com.alachisoft.ncache.client.datastructures.*;
- Cache must be running.
- The application must be connected to cache before performing the operation.
- For API details, refer to: Cache, createCounter, decrement, decrementBy, getCounter, increment, lock, setValue, unlock.
- Make sure that the data being added is serializable.
- 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.
- Install and include the following module in your application:
- Enterprise:
const ncache = require('ncache-client')
- Cache must be running.
- The application must be connected to cache before performing the operation.
- For API details, refer to: Cache, createCounter, decrement, decrementBy, getCounter, increment, lock, setValue, unlock.
- 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.
- Install the NCache Python client by executing the following command:
# Enterprise Client
pip install ncache-client
- Import the NCache module in your application.
- Cache must be running.
- To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
- 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-scala-client</artifactId>
<version>x.x.x</version>
</dependency>
- Import the following packages in your application:
import com.alachisoft.ncache.scala.client.*;
import com.alachisoft.ncache.scala.client.datastructures.*;
- Cache must be running.
- The application must be connected to cache before performing the operation.
- Make sure that the data being added is serializable.
- 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.
Create Counter
The following code sample shows how a counter can be created in the cache using CreateCounter
against the cache key SubscriptionCounter.
try
{
// Pre-condition: Cache must be connected
// Specify unique cache key for counter
string key = "SubscriptionCounter";
// Set initial value of counter
long initialValue = 15;
// Create counter
ICounter counter = cache.DataTypeManager.CreateCounter(key, initialValue);
}
catch (OperationFailedException ex)
{
// NCache specific exception
if(ex.ErrorCode == NCacheErrorCodes.KEY_ALREADY_EXISTS)
{
// The specified key already exists in the cache,
// Either remove the existing object from the cache
// Or specify another key
}
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 counter
String key = "SubscriptionCounter";
// Set initial value of counter
long initialValue = 15;
// Create counter
Counter counter = cache.getDataStructuresManager().createCounter(key, initialValue);
} catch (OperationFailedException ex) {
// NCache specific errors
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 {
// 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
}
// This is an async method
try {
// Pre-condition: Cache must be connected
// Specify unique cache key for counter
var key = "SubscriptionCounter";
// Set initial value of counter
var initialValue = 15;
// Create counter
var manager = await this.cache.getDataStructuresManager();
var counter = await manager.createCounter(key, initialValue);
} catch (error) {
// Handle errors
}
try:
# Pre-condition: Cache must be connected
# Specify unique cache key for counter
key = "SubscriptionCounter"
# Set initial value of counter
initial_value = 15
# Create counter
manager = cache.get_data_structures_manager()
counter = manager.create_counter(key, initial_value)
except Exception as exp:
# Handle errors
try {
// Pre-condition: Cache must be connected
// Specify unique cache key for counter
val key = "SubscriptionCounter"
// Set initial value of counter
val initialValue = 15
// Create counter
val counter = cache.getDataStructuresManager.createCounter(key, initialValue)
}
catch {
case exception: Exception => {
// Handle any 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 and Update Value of Counter
You can update the value of a counter after its creation. The following code sample fetches a counter from the cache using GetCounter
and sets its value to another value, using SetValue
. Then, increments its value using Increment
or IncrementBy
and decrements its value using Decrement
or DecrementBy
.
try
{
// Pre-condition: Cache is already connected
// Unique key for counter
string key = "SubscriptionCounter";
// Get counter against key
ICounter retrievedCounter = cache.DataTypeManager.GetCounter(key);
// Set value of counter to 100
retrievedCounter.SetValue(100);
// Increment value
long newValue = retrievedCounter.Increment();
// Decrement value
newValue = retrievedCounter.Decrement();
// Increment value by number of 10
newValue = retrievedCounter.IncrementBy(10);
// Decrement value by number of 5
newValue = retrievedCounter.DecrementBy(5);
}
catch (OperationFailedException ex)
{
// NCache specific exception
if (ex.ErrorCode == NCacheErrorCodes.NOT_A_COUNTER)
{
// Item being fetched is not of counter 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
// Unique key for counter
String key = "SubscriptionCounter";
// Get counter against key
Counter retrievedCounter = cache.getDataStructuresManager().getCounter(key);
// Set Value of counter to 100
retrievedCounter.setValue(100);
// Increment value
long newValue = retrievedCounter.increment();
// Decrement value
newValue = retrievedCounter.decrement();
// Increment value by number of 10
newValue = retrievedCounter.incrementBy(10);
// Decrement value by number of 5
newValue = retrievedCounter.decrementBy(5);
} catch (OperationFailedException ex) {
// NCache specific exception
if (ex.getErrorCode() == NCacheErrorCodes.NOT_A_COUNTER) {
// Item being fetched is not of counter 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 IllegalArgumentException or NullPointerException
}
// This is an async method
try {
// Pre-condition: Cache is already connected
// Unique key for counter
var key = "SubscriptionCounter";
// Get counter against key
var manager = await this.cache.getDataStructuresManager();
var retrievedCounter = await manager.getCounter(key);
// Set Value of counter to 100
retrievedCounter.setValue(100);
// Increment value
var newValue = retrievedCounter.increment();
// Decrement value
newValue = retrievedCounter.decrement();
// Increment value by number of 10
newValue = retrievedCounter.incrementBy(10);
// Decrement value by number of 5
newValue = retrievedCounter.decrementBy(5);
} catch (error) {
// Handle errors
}
try:
# Pre-condition: Cache is already connected
# Unique key for counter
key = "SubscriptionCounter"
# Get counter against key
manager = cache.get_data_structures_manager()
retrieved_counter = manager.get_counter(key)
# Increment value of retrievedCounter on new subscription
retrieved_counter.increment()
except Exception as exp:
# Handle errors
try {
// Pre-condition: Cache is already connected
// Unique key for counter
val key = "SubscriptionCounter"
// Get counter against key
val retrievedCounter = cache.getDataStructuresManager.getCounter(key)
// Increment value of retrievedCounter on new subscription
retrievedCounter.increment
}
catch {
case exception: Exception => {
// Handle any 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.
Event Notifications on Counters
You can register cache events, key-based events, and data structure events on a data structure such as a counter.
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 counter in the cache.
Once a counter is created in the cache, an ItemAdded
cache level event is fired. However, once an item is added to the counter, an ItemAdded
data structure event is fired, and an ItemUpdated
cache level event is fired.
Register Event on Counter Created
try
{
// Pre-condition: Cache is already connected
// Unique cache key for counter
string key = "SubscriptionCounter";
// Set initial value of counter
long initialValue = 15;
// Create counter
ICounter counter = cache.DataTypeManager.CreateCounter(key, initialValue);
// Register ItemAdded, ItemUpdated, ItemRemoved events on counter created
// DataTypeNotificationCallback is callback method specified
counter.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 counter
String key = "SubscriptionCounter";
// Set initial value of counter
long initialValue = 15;
// Create counter
Counter counter = cache.getDataStructuresManager().createCounter(key, initialValue);
// 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);
counter.addChangeListener(dataChangeListener, enumSet, 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 IllegalArgumentException or NullPointerException
}
// This is an async method
try {
// Precondition: Cache is already connected
// Unique cache key for counter
var key = "SubscriptionCounter";
// Set initial value of counter
var initialValue = 15;
// Create counter
var counter = await this.cache.getDataStructuresManager().createCounter(key, initialValue);
// Create EnumSet of event types
var enumSet = enumSet.of(
ncache.EventType.ItemAdded,
ncache.EventType.ItemUpdated,
ncache.EventType.ItemRemoved
);
// Register ItemAdded, ItemUpdated, ItemRemoved events on queue created
// dataChangeListener is the specified callback method
var dataChangeListener = dataStructureListener.onDataStructureChanged(
collectionName,
args
);
counter.addChangeListener(
dataChangeListener,
enumSet,
ncache.DataTypeEventDataFilter.Data
);
// Perform operations
} catch (error) {
// Handle 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 counter
key = "SubscriptionCounter"
# Set initial value of counter
initial_value = 15
# Create counter
counter = cache.get_data_structures_manager().create_counter(key, initial_value)
# Register ItemAdded, ItemUpdated, ItemRemoved events on hashset created
events_list = [ncache.EventType.ITEM_ADDED, ncache.EventType.ITEM_UPDATED, ncache.EventType.ITEM_REMOVED]
counter.add_change_listener(datastructure_callback_function, events_list, ncache.DataTypeEventDataFilter.DATA)
# Perform operations
except Exception as exp:
# Handle errors
try {
// Precondition: Cache is already connected
// Unique cache key for counter
val key = "IntSet"
// Initialize change listener
val dataStructureListener = CounterDataStructureChangeListener()
// Create Set of Int type
val counter = cache.getDataStructuresManager.getCounter(key)
// Register ItemAdded, ItemUpdated, ItemRemoved events on list created
val enumSet = List(EventType.ItemAdded, EventType.ItemUpdated, EventType.ItemRemoved)
counter.addChangeListener(dataStructureListener, enumSet, DataTypeEventDataFilter.Data)
// Perform operations
}
catch {
case exception: Exception => {
// Handle any 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;
}
}
};
dataStructureListener = new ncache.DataStructureDataChangeListener();
{
function onDataStructureChanged(collection, dataStructureEventArg) {
switch (dataStructureEventArg.getEventType()) {
case ncache.EventType.ItemAdded:
//Item has been added to the collection
break;
case ncache.EventType.ItemUpdated:
if (dataStructureEventArg.getCollectionItem() != null) {
//Item has been updated in the collection
// perform operations
}
break;
case ncache.EventType.ItemRemoved:
//Item has been removed from the collection
break;
}
}
}
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)
class CounterDataStructureChangeListener 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
}
}
}
Note
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
Locking Counter
Counters can be explicitly locked and unlocked to ensure data consistency. The following code sample creates a counter and locks it for a period of 10 seconds using Lock() and then unlocks it using Unlock().
try
{
// Pre-conditions: Cache is already connected
// Counter exists with key "SubscriptionCounter"
// Cache Key
string key = "SubscriptionCounter";
// Get counter against key
ICounter counter = cache.DataTypeManager.GetCounter(key);
// Lock counter for 10 seconds
bool isLocked = counter.Lock(TimeSpan.FromSeconds(10));
if (isLocked)
{
// Counter is successfully locked for 10 seconds
// Unless explicitly unlocked
}
else
{
// Counter is not locked because either:
// Counter is not present in the cache
// Counter is already locked
}
counter.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
// Counter exists with key "SubscriptionCounter"
// Cache Key
String key = "SubscriptionCounter";
// Get counter against key
Counter counter = cache.getDataStructuresManager().getCounter(key);
// Lock counter for 10 seconds
boolean isLocked = counter.lock(TimeSpan.FromSeconds(10));
if (isLocked) {
// Counter is successfully locked for 10 seconds
// Unless explicitly unlocked
} else {
// Counter is not locked because either:
// Counter is not present in the cache
// Counter is already locked
}
counter.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// Pre-conditions: Cache is already connected
// Counter exists with key "SubscriptionCounter"
// Cache Key
val key = "SubscriptionCounter"
// Get counter against key
val counter = cache.getDataStructuresManager.getCounter(key)
val isLocked = counter.lock(TimeSpan.FromSeconds(10))
if (isLocked) {
// Counter is successfully locked for 10 seconds
// Unless explicitly unlocked
}
else {
// Counter is not locked because either:
// Counter is not present in the cache
// Counter is already locked
}
counter.unlock()
}
catch {
case exception: Exception => {
// Handle any 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.
Additional Resources
NCache provides a sample application for the counter data structure on
GitHub.
See Also
Sets Behavior and Usage in Cache
Dictionary Behavior and Usage in Cache
Configure Searchable Attributes
Configure Invalidation Attributes