• Webinars
  • Docs
  • Download
  • Blogs
  • Contact Us
Try Free
Show / Hide Table of Contents

Counter Behavior and Usage in Cache

Note

This feature is only available in the NCache Enterprise Edition.

A counter is a single long value data structure stored in the cache. You can increment, decrement, lock, 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

  • .NET/.NET Core
  • Java
  • Scala
  • Node.js
  • Python
  • To learn about the standard prerequisites required to work with all NCache client side features please refer to the given page on Client Side API Prerequisites.
  • For API details, refer to: ICache, ICounter, IDataTypeManager, CreateCounter, SetValue, Increment, IncrementBy, Decrement, DecrementBy, GetCounter, ICollectionManager, RegisterNotification, DataTypeDataNotificationCallback, EventType, DataTypeEventDataFilter, Lock, Unlock.
  • To learn about the standard prerequisites required to work with all NCache client side features please refer to the given page on Client Side API Prerequisites.
  • For API details, refer to: Cache, Counter, getDataStructuresManager, createCounter, getCounter, setValue, increment, incrementBy, decrement, decrementBy, EventType, getEventType, DataStructureDataChangeListener, onDataStructureChanged, DataStructureEventArg, DataTypeEventDataFilter, getCollectionItem, lock, unlock.

-To learn about the standard prerequisites required to work with all NCache client side features please refer to the given page on Client Side API Prerequisites.

  • For API details refer to: Cache, Counter, DataStructureManager, getDataStructuresManager, createCounter, increment, DataStructureEventArg, getEventType, DataStructureDataChangeListener, onDataStructureChanged, getCollectionItem.
  • To learn about the standard prerequisites required to work with all NCache client side features please refer to the given page on Client Side API Prerequisites.
  • For API details, refer to: Cache, Counter, DataStructureManager, getDataStructuresManager, createCounter, getCounter, setValue, increment, incrementBy, decrement, decrementBy, EventType , DataStructureDataChangeListener, addChangeListener, DataTypeEventDataFilter, DataStructureEventArg, getEventType, getCollectionItem.
  • To learn about the standard prerequisites required to work with all NCache client side features please refer to the given page on Client Side API Prerequisites.
  • For API details refer to: Cache, Counter, DataStructureManager, get_data_structures_manager, create_counter, get_counter, increment, get_event_type, DataTypeEventDataFilter, EventDataFilter.

Create Counter

The following code sample shows how a counter can be created in the cache using CreateCounter against the cache key SubscriptionCounter.

Tip

You can also configure searchable attributes such as Groups/Tags/Named Tags and invalidation attributes such as Expiration/Eviction/Dependency while creating a data structure.

  • .NET/.NET Core
  • Java
  • Scala
  • Node.js
  • Python
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
}
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
    }
}
// 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

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. It then, increments its value using Increment or IncrementBy and decrements its value using Decrement or DecrementBy.

  • .NET/.NET Core
  • Java
  • Scala
  • Node.js
  • Python
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
}
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
    }
}
// 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
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

  • .NET/.NET Core
  • Java
  • Scala
  • Node.js
  • Python
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
}
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
    }
}
// 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

Specify Callback for Event Notification

  • .NET/.NET Core
  • Java
  • Scala
  • Node.js
  • Python
private void DataTypeDataNotificationCallback(string collectionName, DataTypeEventArg collectionEventArgs)
{
    switch (collectionEventArgs.EventType)
    {
        case EventType.ItemAdded:
            // Item has been added to the collection
        break;
        case EventType.ItemUpdated:
            if (collectionEventArgs.CollectionItem != null)
            {
                // Item has been updated in the collection
                // Perform operations
            }
        break;
        case EventType.ItemRemoved:
            // Item has been removed from the collection
        break;
    }
}
DataStructureDataChangeListener dataStructureListener = new DataStructureDataChangeListener() {
    @Override
    public void onDataStructureChanged(String collection, DataStructureEventArg dataStructureEventArg) {
        switch (dataStructureEventArg.getEventType()) {
            case ItemAdded:
                // Item has been added to the collection
            break;
            case ItemUpdated:
                if (dataStructureEventArg.getCollectionItem() != null) {
                    //Item has been updated in the collection
                    // perform operations
                }
            break;
            case ItemRemoved:
                //Item has been removed from the collection
            break;
        }
    }
};
class 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

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

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().

  • .NET/.NET Core
  • Java
  • Scala
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
    }
}

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

Back to top Copyright © 2017 Alachisoft