PartitionUpdate (apache-cassandra API)
Date: 2018-02-14

org.apache.cassandra.db.partitions

## Class PartitionUpdate

- java.lang.Object
- - org.apache.cassandra.db.partitions.AbstractBTreePartition
  - - org.apache.cassandra.db.partitions.PartitionUpdate

- All Implemented Interfaces:
    java.lang.Iterable<Row>, Partition

      public class PartitionUpdate
      extends AbstractBTreePartition

  Stores updates made on a partition.

  A PartitionUpdate object requires that all writes/additions are performed before we try to read the updates (attempts to write to the PartitionUpdate after a read method has been called will result in an exception being thrown). In other words, a Partition is mutable while it's written but becomes immutable as soon as it is read.

  A typical usage is to create a new update (`new PartitionUpdate(metadata, key, columns, capacity)`) and then add rows and range tombstones through the `add()` methods (the partition level deletion time can also be set with `addPartitionDeletion()`). However, there is also a few static helper constructor methods for special cases (`emptyUpdate()`, `fullPartitionDelete` and `singleRowUpdate`).

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PartitionUpdate.CounterMark` A counter mark is basically a pointer to a counter update inside this partition update.
    `static class` | `PartitionUpdate.PartitionUpdateSerializer`
    `static interface` | `PartitionUpdate.SimpleBuilder` Interface for building partition updates geared towards human.

    - ### Nested classes/interfaces inherited from class org.apache.cassandra.db.partitions.AbstractBTreePartition

      `AbstractBTreePartition.Holder, AbstractBTreePartition.SlicesIterator`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static org.slf4j.Logger` | `logger`
    `static PartitionUpdate.PartitionUpdateSerializer` | `serializer`

    - ### Fields inherited from class org.apache.cassandra.db.partitions.AbstractBTreePartition

      `EMPTY, metadata, partitionKey`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PartitionUpdate(CFMetaData metadata, java.nio.ByteBuffer key, PartitionColumns columns, int initialRowCapacity)`
    `PartitionUpdate(CFMetaData metadata, DecoratedKey key, PartitionColumns columns, int initialRowCapacity)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(RangeTombstone range)`
    `void` | `add(Row row)` Adds a row to this update.
    `void` | `addPartitionDeletion(DeletionTime deletionTime)`
    `void` | `allowNewUpdates()` If a partition update has been read (and is thus unmodifiable), a call to this method makes the update modifiable again.
    `protected boolean` | `canHaveShadowedData()`
    `java.util.List<PartitionUpdate.CounterMark>` | `collectCounterMarks()` For an update on a counter table, returns a list containing a `CounterMark` for every counter contained in the update.
    `PartitionColumns` | `columns()`
    `int` | `dataSize()` The size of the data contained in this update.
    `DeletionInfo` | `deletionInfo()`
    `static PartitionUpdate` | `emptyUpdate(CFMetaData metadata, DecoratedKey key)` Creates a empty immutable partition update.
    `static PartitionUpdate` | `fromBytes(java.nio.ByteBuffer bytes, int version, DecoratedKey key)` Deserialize a partition update from a provided byte buffer.
    `static PartitionUpdate` | `fromIterator(RowIterator iterator, ColumnFilter filter)` Turns the given iterator into an update.
    `static PartitionUpdate` | `fromIterator(UnfilteredRowIterator iterator, ColumnFilter filter)` Turns the given iterator into an update.
    `static PartitionUpdate` | `fullPartitionDelete(CFMetaData metadata, java.nio.ByteBuffer key, long timestamp, int nowInSec)` Creates a partition update that entirely deletes a given partition.
    `static PartitionUpdate` | `fullPartitionDelete(CFMetaData metadata, DecoratedKey key, long timestamp, int nowInSec)` Creates an immutable partition update that entirely deletes a given partition.
    `protected AbstractBTreePartition.Holder` | `holder()`
    `java.util.Iterator<Row>` | `iterator()` Returns an iterator that iterates over the rows of this update in clustering order.
    `long` | `maxTimestamp()` The maximum timestamp used in this update.
    `static PartitionUpdate` | `merge(java.util.List<PartitionUpdate> updates)` Merges the provided updates, yielding a new update that incorporates all those updates.
    `int` | `operationCount()` The number of "operations" contained in the update.
    `static PartitionUpdate.SimpleBuilder` | `simpleBuilder(CFMetaData metadata, java.lang.Object... partitionKeyValues)` Creates a new simple partition update builder.
    `static PartitionUpdate` | `singleRowUpdate(CFMetaData metadata, java.nio.ByteBuffer key, Row row)` Creates an immutable partition update that contains a single row update.
    `static PartitionUpdate` | `singleRowUpdate(CFMetaData metadata, DecoratedKey key, Row row)` Creates an immutable partition update that contains a single row update.
    `EncodingStats` | `stats()`
    `static java.nio.ByteBuffer` | `toBytes(PartitionUpdate update, int version)` Serialize a partition update as a byte buffer.
    `java.lang.String` | `toString()`
    `void` | `updateAllTimestamp(long newTimestamp)` Modify this update to set every timestamp for live data to `newTimestamp` and every deletion timestamp to `newTimestamp - 1`.
    `void` | `validate()` Validates the data contained in this update.

    - ### Methods inherited from class org.apache.cassandra.db.partitions.AbstractBTreePartition

      `build, build, build, getRow, hasRows, isEmpty, lastRow, metadata, partitionKey, partitionLevelDeletion, rowCount, searchIterator, staticRow, unfilteredIterator, unfilteredIterator, unfilteredIterator`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Field Detail

    - #### logger

          protected static final org.slf4j.Logger logger

    - #### serializer

          public static final PartitionUpdate.PartitionUpdateSerializer serializer

  - ### Constructor Detail

    - #### PartitionUpdate

          public PartitionUpdate(CFMetaData metadata,
                                 DecoratedKey key,
                                 PartitionColumns columns,
                                 int initialRowCapacity)

    - #### PartitionUpdate

          public PartitionUpdate(CFMetaData metadata,
                                 java.nio.ByteBuffer key,
                                 PartitionColumns columns,
                                 int initialRowCapacity)

  - ### Method Detail

    - #### emptyUpdate

          public static PartitionUpdate emptyUpdate(CFMetaData metadata,
                                                    DecoratedKey key)

      Creates a empty immutable partition update.
      Parameters:
        `metadata` - the metadata for the created update.
        `key` - the partition key for the created update.
      Returns:
        the newly created empty (and immutable) update.

    - #### fullPartitionDelete

          public static PartitionUpdate fullPartitionDelete(CFMetaData metadata,
                                                            DecoratedKey key,
                                                            long timestamp,
                                                            int nowInSec)

      Creates an immutable partition update that entirely deletes a given partition.
      Parameters:
        `metadata` - the metadata for the created update.
        `key` - the partition key for the partition that the created update should delete.
        `timestamp` - the timestamp for the deletion.
        `nowInSec` - the current time in seconds to use as local deletion time for the partition deletion.
      Returns:
        the newly created partition deletion update.

    - #### singleRowUpdate

          public static PartitionUpdate singleRowUpdate(CFMetaData metadata,
                                                        DecoratedKey key,
                                                        Row row)

      Creates an immutable partition update that contains a single row update.
      Parameters:
        `metadata` - the metadata for the created update.
        `key` - the partition key for the partition to update.
        `row` - the row for the update.
      Returns:
        the newly created partition update containing only `row`.

    - #### singleRowUpdate

          public static PartitionUpdate singleRowUpdate(CFMetaData metadata,
                                                        java.nio.ByteBuffer key,
                                                        Row row)

      Creates an immutable partition update that contains a single row update.
      Parameters:
        `metadata` - the metadata for the created update.
        `key` - the partition key for the partition to update.
        `row` - the row for the update.
      Returns:
        the newly created partition update containing only `row`.

    - #### fromIterator

          public static PartitionUpdate fromIterator(UnfilteredRowIterator iterator,
                                                     ColumnFilter filter)

      Turns the given iterator into an update.
      Parameters:
        `iterator` - the iterator to turn into updates.
        `filter` - the column filter used when querying `iterator`. This is used to make sure we don't include data for which the value has been skipped while reading (as we would then be writing something incorrect). Warning: this method does not close the provided iterator, it is up to the caller to close it.

    - #### fromIterator

          public static PartitionUpdate fromIterator(RowIterator iterator,
                                                     ColumnFilter filter)

      Turns the given iterator into an update.
      Parameters:
        `iterator` - the iterator to turn into updates.
        `filter` - the column filter used when querying `iterator`. This is used to make sure we don't include data for which the value has been skipped while reading (as we would then be writing something incorrect). Warning: this method does not close the provided iterator, it is up to the caller to close it.

    - #### canHaveShadowedData

          protected boolean canHaveShadowedData()

      Specified by:
        `canHaveShadowedData` in class `AbstractBTreePartition`

    - #### fromBytes

          public static PartitionUpdate fromBytes(java.nio.ByteBuffer bytes,
                                                  int version,
                                                  DecoratedKey key)

      Deserialize a partition update from a provided byte buffer.
      Parameters:
        `bytes` - the byte buffer that contains the serialized update.
        `version` - the version with which the update is serialized.
        `key` - the partition key for the update. This is only used if `version &lt 3.0` and can be `null` otherwise.
      Returns:
        the deserialized update or `null` if `bytes == null`.

    - #### toBytes

          public static java.nio.ByteBuffer toBytes(PartitionUpdate update,
                                                    int version)

      Serialize a partition update as a byte buffer.
      Parameters:
        `update` - the partition update to serialize.
        `version` - the version to serialize the update into.
      Returns:
        a newly allocated byte buffer containing the serialized update.

    - #### fullPartitionDelete

          public static PartitionUpdate fullPartitionDelete(CFMetaData metadata,
                                                            java.nio.ByteBuffer key,
                                                            long timestamp,
                                                            int nowInSec)

      Creates a partition update that entirely deletes a given partition.
      Parameters:
        `metadata` - the metadata for the created update.
        `key` - the partition key for the partition that the created update should delete.
        `timestamp` - the timestamp for the deletion.
        `nowInSec` - the current time in seconds to use as local deletion time for the partition deletion.
      Returns:
        the newly created partition deletion update.

    - #### merge

          public static PartitionUpdate merge(java.util.List<PartitionUpdate> updates)

      Merges the provided updates, yielding a new update that incorporates all those updates.
      Parameters:
        `updates` - the collection of updates to merge. This shouldn't be empty.
      Returns:
        a partition update that include (merge) all the updates from `updates`.

    - #### deletionInfo

          public DeletionInfo deletionInfo()

      Overrides:
        `deletionInfo` in class `AbstractBTreePartition`

    - #### updateAllTimestamp

          public void updateAllTimestamp(long newTimestamp)

      Modify this update to set every timestamp for live data to `newTimestamp` and every deletion timestamp to `newTimestamp - 1`. There is no reason to use that expect on the Paxos code path, where we need ensure that anything inserted use the ballot timestamp (to respect the order of update decided by the Paxos algorithm). We use `newTimestamp - 1` for deletions because tombstones always win on timestamp equality and we don't want to delete our own insertions (typically, when we overwrite a collection, we first set a complex deletion to delete the previous collection before adding new elements. If we were to set that complex deletion to the same timestamp that the new elements, it would delete those elements). And since tombstones always wins on timestamp equality, using -1 guarantees our deletion will still delete anything from a previous update.

    - #### operationCount

          public int operationCount()

      The number of "operations" contained in the update.

      This is used by `Memtable` to approximate how much work this update does. In practice, this count how many rows are updated and how many ranges are deleted by the partition update.

      Returns:
        the number of "operations" performed by the update.

    - #### dataSize

          public int dataSize()

      The size of the data contained in this update.
      Returns:
        the size of the data contained in this update.

    - #### columns

          public PartitionColumns columns()

      Specified by:
        `columns` in interface `Partition`
      Overrides:
        `columns` in class `AbstractBTreePartition`

    - #### holder

          protected AbstractBTreePartition.Holder holder()

      Specified by:
        `holder` in class `AbstractBTreePartition`

    - #### stats

          public EncodingStats stats()

      Specified by:
        `stats` in interface `Partition`
      Overrides:
        `stats` in class `AbstractBTreePartition`

    - #### allowNewUpdates

          public void allowNewUpdates()

      If a partition update has been read (and is thus unmodifiable), a call to this method makes the update modifiable again.

      Please note that calling this method won't result in optimal behavior in the sense that even if very little is added to the update after this call, the whole update will be sorted again on read. This should thus be used sparingly (and if it turns that we end up using this often, we should consider optimizing the behavior).

    - #### iterator

          public java.util.Iterator<Row> iterator()

      Returns an iterator that iterates over the rows of this update in clustering order.

      Note that this might trigger a sorting of the update, and as such the update will not be modifiable anymore after this call.

      Specified by:
        `iterator` in interface `java.lang.Iterable<Row>`
      Overrides:
        `iterator` in class `AbstractBTreePartition`
      Returns:
        an iterator over the rows of this update.

    - #### validate

          public void validate()

      Validates the data contained in this update.
      Throws:
        `MarshalException` - if some of the data contained in this update is corrupted.

    - #### maxTimestamp

          public long maxTimestamp()

      The maximum timestamp used in this update.
      Returns:
        the maximum timestamp used in this update.

    - #### collectCounterMarks

          public java.util.List<PartitionUpdate.CounterMark> collectCounterMarks()

      For an update on a counter table, returns a list containing a `CounterMark` for every counter contained in the update.
      Returns:
        a list with counter marks for every counter in this update.

    - #### addPartitionDeletion

          public void addPartitionDeletion(DeletionTime deletionTime)

    - #### add

          public void add(RangeTombstone range)

    - #### add

          public void add(Row row)

      Adds a row to this update. There is no particular assumption made on the order of row added to a partition update. It is further allowed to add the same row (more precisely, multiple row objects for the same clustering). Note however that the columns contained in the added row must be a subset of the columns used when creating this update.
      Parameters:
        `row` - the row to add.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `AbstractBTreePartition`

    - #### simpleBuilder

          public static PartitionUpdate.SimpleBuilder simpleBuilder(CFMetaData metadata,
                                                                    java.lang.Object... partitionKeyValues)

      Creates a new simple partition update builder.
      Parameters:
        `metadata` - the metadata for the table this is a partition of.
        `partitionKeyValues` - the values for partition key columns identifying this partition. The values for each partition key column can be passed either directly as `ByteBuffer` or using a "native" value (int for Int32Type, string for UTF8Type, ...). It is also allowed to pass a single `DecoratedKey` value directly.
      Returns:
        a newly created builder.

Copyright © 2018 The Apache Software Foundation