org.apache.cassandra.db.context

Class CounterContext

java.lang.Object

org.apache.cassandra.db.context.CounterContext

public class CounterContext
extends java.lang.Object

An implementation of a partitioned counter context. A context is primarily a list of tuples (counter id, clock, count) -- called shards, with some shards flagged as global or local (with special resolution rules in merge()). The data structure has two parts: a) a header containing the lists of global and local shard indexes in the body b) a list of shards -- (counter id, logical clock, count) tuples -- (the so-called 'body' below) The exact layout is: | header | body | context : |--|------|----------| ^ ^ | list of indices in the body list (2*#elt bytes) #elt in rest of header (2 bytes) Non-negative indices refer to local shards. Global shard indices are encoded as [idx + Short.MIN_VALUE], and are thus always negative. The body layout being: body: |----|----|----|----|----|----|.... ^ ^ ^ ^ ^ ^ | | count_1 | | count_2 | clock_1 | clock_2 counterid_1 counterid_2 The rules when merging two shard with the same counter id are: - global + global = keep the shard with the highest logical clock - global + local = keep the global one - global + remote = keep the global one - local + local = sum counts (and logical clocks) - local + remote = keep the local one - remote + remote = keep the shard with the highest logical clock For a detailed description of the meaning of a local and why the merging rules work this way, see CASSANDRA-1938 - specifically the 1938_discussion attachment (doesn't cover global shards, see CASSANDRA-4775 for that).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CounterContext.ContextState Helper class to work on contexts (works by iterating over them).
static class	CounterContext.Relationship

Constructor Summary

Constructors

Constructor and Description
CounterContext()

Method Summary

Modifier and Type	Method and Description
java.nio.ByteBuffer	clearAllLocal(java.nio.ByteBuffer context) Remove all the local of a context (but keep global).
java.nio.ByteBuffer	createGlobal(CounterId id, long clock, long count) Creates a counter context with a single global, 2.1+ shard (a result of increment).
java.nio.ByteBuffer	createLocal(long count) Creates a counter context with a single local shard.
java.nio.ByteBuffer	createRemote(CounterId id, long clock, long count) Creates a counter context with a single remote shard.
CounterContext.Relationship	diff(java.nio.ByteBuffer left, java.nio.ByteBuffer right) Determine the count relationship between two contexts.
int	findPositionOf(java.nio.ByteBuffer context, CounterId id) Finds the position of a shard with the given id within the context (via binary search).
ClockAndCount	getClockAndCountOf(java.nio.ByteBuffer context, CounterId id) Returns the clock and the count associated with the given counter id, or (0, 0) if no such shard is present.
ClockAndCount	getLocalClockAndCount(java.nio.ByteBuffer context) Returns the clock and the count associated with the local counter id, or (0, 0) if no such shard is present.
long	getLocalCount(java.nio.ByteBuffer context) Returns the count associated with the local counter id, or 0 if no such shard is present.
boolean	hasLegacyShards(java.nio.ByteBuffer context) Detects whether or not the context has any legacy (local or remote) shards in it.
static CounterContext	instance()
boolean	isLocal(java.nio.ByteBuffer context) Checks if a context is local
java.nio.ByteBuffer	markLocalToBeCleared(java.nio.ByteBuffer context) Mark context to delete local references afterward.
java.nio.ByteBuffer	merge(java.nio.ByteBuffer left, java.nio.ByteBuffer right) Return a context w/ an aggregated count for each counter id.
boolean	shouldClearLocal(java.nio.ByteBuffer context)
java.lang.String	toString(java.nio.ByteBuffer context) Human-readable String from context.
long	total(java.nio.ByteBuffer context) Returns the aggregated count across all counter ids.
void	updateDigest(java.security.MessageDigest message, java.nio.ByteBuffer context) Update a MessageDigest with the content of a context.
void	validateContext(java.nio.ByteBuffer context)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CounterContext

public CounterContext()

Method Detail

instance

public static CounterContext instance()

createGlobal

public java.nio.ByteBuffer createGlobal(CounterId id,
                                        long clock,
                                        long count)

Creates a counter context with a single global, 2.1+ shard (a result of increment).

createLocal

public java.nio.ByteBuffer createLocal(long count)

Creates a counter context with a single local shard. This is only used in a PartitionUpdate until the update has gone through CounterMutation.apply(), at which point all the local shard are replaced by global ones. In other words, local shards should never hit the disk or memtables. And we use this so that if an update statement has multiple increment of the same counter we properly add them rather than keeping only one of them. (this is also used for tests of compatibility with pre-2.1 counters)

createRemote

public java.nio.ByteBuffer createRemote(CounterId id,
                                        long clock,
                                        long count)

Creates a counter context with a single remote shard. For use by tests of compatibility with pre-2.1 counters only.

diff

public CounterContext.Relationship diff(java.nio.ByteBuffer left,
                                        java.nio.ByteBuffer right)

Determine the count relationship between two contexts. EQUAL: Equal set of nodes and every count is equal. GREATER_THAN: Superset of nodes and every count is equal or greater than its corollary. LESS_THAN: Subset of nodes and every count is equal or less than its corollary. DISJOINT: Node sets are not equal and/or counts are not all greater or less than. Strategy: compare node logical clocks (like a version vector).

Parameters:

left - counter context.

right - counter context.

Returns:

the Relationship between the contexts.

merge

public java.nio.ByteBuffer merge(java.nio.ByteBuffer left,
                                 java.nio.ByteBuffer right)

Return a context w/ an aggregated count for each counter id.

Parameters:

left - counter context.

right - counter context.

toString

public java.lang.String toString(java.nio.ByteBuffer context)

Human-readable String from context.

Parameters:

context - counter context.

Returns:

a human-readable String of the context.

total

public long total(java.nio.ByteBuffer context)

Returns the aggregated count across all counter ids.

Parameters:

context - a counter context

Returns:

the aggregated count represented by context

shouldClearLocal

public boolean shouldClearLocal(java.nio.ByteBuffer context)

hasLegacyShards

public boolean hasLegacyShards(java.nio.ByteBuffer context)

Detects whether or not the context has any legacy (local or remote) shards in it.

markLocalToBeCleared

public java.nio.ByteBuffer markLocalToBeCleared(java.nio.ByteBuffer context)

Mark context to delete local references afterward. Marking is done by multiply #elt by -1 to preserve header length and #elt count in order to clear all local refs later.

Parameters:

context - a counter context

Returns:

context that marked to delete local refs

clearAllLocal

public java.nio.ByteBuffer clearAllLocal(java.nio.ByteBuffer context)

Remove all the local of a context (but keep global).

Parameters:

context - a counter context

Returns:

a version of context where no shards are local.

validateContext

public void validateContext(java.nio.ByteBuffer context)
                     throws MarshalException

Throws:

MarshalException

updateDigest

public void updateDigest(java.security.MessageDigest message,
                         java.nio.ByteBuffer context)

Update a MessageDigest with the content of a context. Note that this skips the header entirely since the header information has local meaning only, while digests are meant for comparison across nodes. This means in particular that we always have: updateDigest(ctx) == updateDigest(clearAllLocal(ctx))

getLocalClockAndCount

public ClockAndCount getLocalClockAndCount(java.nio.ByteBuffer context)

Returns the clock and the count associated with the local counter id, or (0, 0) if no such shard is present.

getLocalCount

public long getLocalCount(java.nio.ByteBuffer context)

Returns the count associated with the local counter id, or 0 if no such shard is present.

isLocal

public boolean isLocal(java.nio.ByteBuffer context)

Checks if a context is local

getClockAndCountOf

public ClockAndCount getClockAndCountOf(java.nio.ByteBuffer context,
                                        CounterId id)

Returns the clock and the count associated with the given counter id, or (0, 0) if no such shard is present.

findPositionOf

public int findPositionOf(java.nio.ByteBuffer context,
                          CounterId id)

Finds the position of a shard with the given id within the context (via binary search).