Appengine Counter Usage

Appengine-counter relies on an instance of ShardedCounterService to act as an intermediary between the Google Cloud infrastructure and your application for counting purposes. Note that ShardedCounterService extends CounterService, which holds most of the methods defined by the service. These services allows you to retrieve the current count of a counter, as well as increment, decrement, and reset a counter.

This page assumes you have properly configured appengine-counter. If you need more details about setup or configuration please see the Getting Started page.

Construct a ShardedCounterService

First, you'll want to construct an instance of ShardedCounterService. There are several ways to do this, but the most straightforward is as follows:

final ShardedCounterService shardedCounterService = new ShardedCounterServiceImpl();

Create a Counter

To create a counter, use the CounterService like this:

final Counter counter = shardedCounterService.createCounter("my-counter");
// count will be zero right after creation...
final BigInteger count = counter.getCount();

Note that all counters in a given Datastore Namespace will use the counter name as a unique identifier. So, be careful to choose a naming convention will support your use-case. For example, if you wanted to track the number of "likes" on a photo and a video, you might choose a naming convention like "likes-per-photo-{photo-id}" vs "likes-per-video-{video-id}".

Get a Counter's Count

To get the count of a counter, use the CounterService like this:

final Optional<Counter> optCounter = shardedCounterService.getCounter("my-counter-name");
if(optCounter.isPresent())
{
    final BigInteger count = optCounter.get().getCount();
}

NOTE: Since any given counter is actually just a collection of counter shards living inside of the Google Cloud Datastore, the CounterService only has a snapshot of a given counter's "count" at any given moment.

Increment a Counter

To increment a counter, use the CounterService like this:

CounterOperation counterOperation = shardedCounterService.increment("my-counter-name", 2L);

Though rarely needed, you can directly increment a counter's shards if you know the unique identifier of the shard. Here's an example that increments shard number 0 using a UUID to identify the operation for later:

CounterOperation counterOperation = shardedCounterService.increment("my-counter-name", 2L, 0, UUID.randomUUID());

The counterOperation returned by an increment or decrement object allows you to determine if an increment or decrement has been applied. You can use the counter service to load these objects for later usage:

shardedCounterService.getCounterOperation( "my-counter-name", CounterShardData.computeShardIndex(counterOperation.getCounterShardDataKey()) counterOperation.getOperationUuid() );

Decrement a Counter

To decrement a counter, use the CounterService like this:

shardedCounterService.decrement("my-counter-name", 2L);

Though rarely needed, you can actually directly decrement a counter's shards if you know the unique identifier of the shard. Here's an example that decrements 8 from shard number 0 using a UUID to identify the operation for later:

shardedCounterService.decrement("my-counter-name", 8L, 0, UUID.randomUUID());

Reset a Counter

To reset a counter, use the CounterService like this:

shardedCounterService.reset("my-counter-name");

Note that this operation is not consistent, and merely performs a get-count operation, then reduces the counter by that amount. If another operation increments or decrements the counter during this process, the reset operation may not yield a counter with an exact count of zero.

Delete a Counter

To delete a counter, use the CounterService like this:

shardedCounterService.delete("my-counter-name");