org.apache.cassandra.db.context

## Class CounterContext

- java.lang.Object
- - org.apache.cassandra.db.context.CounterContext

- All Implemented Interfaces:
    IContext

      public class CounterContext
      extends java.lang.Object
      implements IContext

  An implementation of a partitioned counter context. A context is primarily a list of tuples (counter id, clock, count) -- called shard in the following. But with some shard are flagged as delta (with special resolution rules in merge()). The data structure has two parts: a) a header containing the lists of "delta" (a list of references to the second parts) b) a list of shard -- (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) 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 counterid are: - delta + delta = sum counts (and logical clock) - delta + other = keep the delta one - other + other = keep the shard with highest logical clock For a detailed description of the meaning of a delta and why the merging rules work this way, see CASSANDRA-1938 - specifically the 1938_discussion attachment.

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

    - ### Nested classes/interfaces inherited from interface org.apache.cassandra.db.context.IContext

      `IContext.ContextRelationship`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CounterContext()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.nio.ByteBuffer` | `clearAllDelta(java.nio.ByteBuffer context)` Remove all the delta of a context (i.e, set an empty header).
    `java.nio.ByteBuffer` | `computeOldShardMerger(java.nio.ByteBuffer context, java.util.List<CounterId.CounterIdRecord> oldIds, long mergeBefore)` Compute a new context such that if applied to context yields the same total but with old local counter ids nulified and there content merged to the current localCounterId.
    `java.nio.ByteBuffer` | `create(CounterId id, long clock, long value, boolean isDelta)`
    `java.nio.ByteBuffer` | `create(long value, Allocator allocator)` Creates an initial counter context with an initial value for the local node.
    `IContext.ContextRelationship` | `diff(java.nio.ByteBuffer left, java.nio.ByteBuffer right)` Determine the count relationship between two contexts.
    `boolean` | `hasCounterId(java.nio.ByteBuffer context, CounterId id)` Checks whether the provided context has a count for the provided CounterId.
    `static CounterContext` | `instance()`
    `java.nio.ByteBuffer` | `markDeltaToBeCleared(java.nio.ByteBuffer context)` Mark context to delete delta afterward.
    `java.nio.ByteBuffer` | `merge(java.nio.ByteBuffer left, java.nio.ByteBuffer right, Allocator allocator)` Return a context w/ an aggregated count for each counter id.
    `java.nio.ByteBuffer` | `removeOldShards(java.nio.ByteBuffer context, int gcBefore)` Remove shards that have been canceled through computeOldShardMerger since a time older than gcBefore.
    `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()

    - #### create

          public java.nio.ByteBuffer create(long value,
                                   Allocator allocator)

      Creates an initial counter context with an initial value for the local node.
      Parameters:
        `value` - the value for this initial update
        `allocator` -
      Returns:
        an empty counter context.

    - #### create

          public java.nio.ByteBuffer create(CounterId id,
                                   long clock,
                                   long value,
                                   boolean isDelta)

    - #### diff

          public IContext.ContextRelationship 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).
      Specified by:
        `diff` in interface `IContext`
      Parameters:
        `left` - counter context.
        `right` - counter context.
      Returns:
        the ContextRelationship between the contexts.

    - #### merge

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

      Return a context w/ an aggregated count for each counter id.
      Specified by:
        `merge` in interface `IContext`
      Parameters:
        `left` - counter context.
        `right` - counter context.
        `allocator` - An allocator for the merged value.

    - #### toString

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

      Human-readable String from context.
      Specified by:
        `toString` in interface `IContext`
      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`

    - #### markDeltaToBeCleared

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

      Mark context to delete delta afterward. Marking is done by multiply #elt by -1 to preserve header length and #elt count in order to clear all delta later.
      Parameters:
        `context` - a counter context
      Returns:
        context that marked to delete delta

    - #### clearAllDelta

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

      Remove all the delta of a context (i.e, set an empty header).
      Parameters:
        `context` - a counter context
      Returns:
        a version of `context` where no count are a delta.

    - #### 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 a meant for comparison across nodes. This means in particular that we always have: updateDigest(ctx) == updateDigest(clearAllDelta(ctx))

    - #### hasCounterId

          public boolean hasCounterId(java.nio.ByteBuffer context,
                             CounterId id)

      Checks whether the provided context has a count for the provided CounterId. TODO: since the context is sorted, we could implement a binary search. This is however not called in any critical path and contexts will be fairly small so it doesn't matter much.

    - #### computeOldShardMerger

          public java.nio.ByteBuffer computeOldShardMerger(java.nio.ByteBuffer context,
                                                  java.util.List<CounterId.CounterIdRecord> oldIds,
                                                  long mergeBefore)

      Compute a new context such that if applied to context yields the same total but with old local counter ids nulified and there content merged to the current localCounterId.

    - #### removeOldShards

          public java.nio.ByteBuffer removeOldShards(java.nio.ByteBuffer context,
                                            int gcBefore)

      Remove shards that have been canceled through computeOldShardMerger since a time older than gcBefore. Used by compaction to strip context of unecessary information, shrinking them.

Copyright © 2014 The Apache Software Foundation