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

org.apache.cassandra.db.lifecycle

## Class LifecycleTransaction

- java.lang.Object
- - org.apache.cassandra.utils.concurrent.Transactional.AbstractTransactional
  - - org.apache.cassandra.db.lifecycle.LifecycleTransaction

- All Implemented Interfaces:
    java.lang.AutoCloseable, Transactional

      public class LifecycleTransaction
      extends Transactional.AbstractTransactional

  IMPORTANT: When this object is involved in a transactional graph, for correct behaviour its commit MUST occur before any others, since it may legitimately fail. This is consistent with the Transactional API, which permits one failing action to occur at the beginning of the commit phase, but also *requires* that the prepareToCommit() phase only take actions that can be rolled back.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `LifecycleTransaction.ReaderState`

    - ### Nested classes/interfaces inherited from interface org.apache.cassandra.utils.concurrent.Transactional

      `Transactional.AbstractTransactional`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `Tracker` | `tracker`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cancel(java.lang.Iterable<SSTableReader> cancels)` remove the readers from the set we're modifying
    `void` | `cancel(SSTableReader cancel)` remove the reader from the set we're modifying
    `void` | `checkpoint()` call when a consistent batch of changes is ready to be made atomically visible these will be exposed in the Tracker atomically, or an exception will be thrown; in this case the transaction should be rolled back
    `java.lang.Iterable<SSTableReader>` | `current()` returns the currently visible readers managed by this transaction
    `SSTableReader` | `current(SSTableReader reader)` return the current version of the provided reader, whether or not it is visible or staged; i.e.
    `java.lang.Throwable` | `doAbort(java.lang.Throwable accumulate)` undo all of the changes made by this transaction, resetting the state to its original form
    `java.lang.Throwable` | `doCommit(java.lang.Throwable accumulate)` point of no return: commit all changes, but leave all readers marked as compacting
    `protected java.lang.Throwable` | `doPostCleanup(java.lang.Throwable accumulate)` perform an exception-safe post-abort cleanup
    `void` | `doPrepare()` Do any preparatory work prior to commit.
    `static java.util.List<java.io.File>` | `getFiles(java.nio.file.Path folder, java.util.function.BiFunction<java.io.File,Directories.FileType,java.lang.Boolean> filter, Directories.OnTxnErr onTxnErr)` Get the files in the folder specified, provided that the filter returns true.
    `boolean` | `isObsolete(SSTableReader reader)` indicates if the reader has been marked for obsoletion
    `boolean` | `isOffline()`
    `org.apache.cassandra.db.lifecycle.LogTransaction` | `log()`
    `void` | `obsolete(SSTableReader reader)` mark this reader as for obsoletion : on checkpoint() the reader will be removed from the live set
    `void` | `obsoleteOriginals()` obsolete every file in the original transaction
    `static LifecycleTransaction` | `offline(OperationType operationType)` construct an empty Transaction with no existing readers
    `static LifecycleTransaction` | `offline(OperationType operationType, java.lang.Iterable<SSTableReader> readers)` construct a Transaction for use in an offline operation
    `static LifecycleTransaction` | `offline(OperationType operationType, SSTableReader reader)` construct a Transaction for use in an offline operation
    `SSTableReader` | `onlyOne()`
    `java.util.UUID` | `opId()`
    `OperationType` | `opType()`
    `java.util.Set<SSTableReader>` | `originals()` the set of readers guarded by this transaction _in their original instance/state_ call current(SSTableReader) on any reader in this set to get the latest instance
    `void` | `permitRedundantTransitions()`
    `static boolean` | `removeUnfinishedLeftovers(CFMetaData cfMetaData)`
    `static boolean` | `removeUnfinishedLeftovers(ColumnFamilyStore cfs)`
    `static void` | `rescheduleFailedDeletions()` Retry all deletions that failed the first time around (presumably b/c the sstable was still mmap'd.) Useful because there are times when we know GC has been invoked; also exposed as an mbean.
    `LifecycleTransaction` | `split(java.util.Collection<SSTableReader> readers)` remove the provided readers from this Transaction, and return a new Transaction to manage them only permitted to be called if the current Transaction has never been used
    `LifecycleTransaction.ReaderState` | `state(SSTableReader reader)`
    `java.lang.String` | `toString()`
    `void` | `trackNew(SSTable table)`
    `void` | `untrackNew(SSTable table)`
    `void` | `update(java.util.Collection<SSTableReader> readers, boolean original)`
    `void` | `update(SSTableReader reader, boolean original)` update a reader: if !original, this is a reader that is being introduced by this transaction; otherwise it must be in the originals() set, i.e.
    `static void` | `waitForDeletions()` Deletions run on the nonPeriodicTasks executor, (both failedDeletions or global tidiers in SSTableReader) so by scheduling a new empty task and waiting for it we ensure any prior deletion has completed.

    - ### Methods inherited from class org.apache.cassandra.utils.concurrent.Transactional.AbstractTransactional

      `abort, abort, close, commit, commit, doPreCleanup, finish, prepareToCommit, state`

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

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

- - ### Field Detail

    - #### tracker

          public final Tracker tracker

  - ### Method Detail

    - #### offline

          public static LifecycleTransaction offline(OperationType operationType,
                                                     SSTableReader reader)

      construct a Transaction for use in an offline operation

    - #### offline

          public static LifecycleTransaction offline(OperationType operationType,
                                                     java.lang.Iterable<SSTableReader> readers)

      construct a Transaction for use in an offline operation

    - #### offline

          public static LifecycleTransaction offline(OperationType operationType)

      construct an empty Transaction with no existing readers

    - #### log

          public org.apache.cassandra.db.lifecycle.LogTransaction log()

    - #### opType

          public OperationType opType()

    - #### opId

          public java.util.UUID opId()

    - #### doPrepare

          public void doPrepare()

      Description copied from class: `Transactional.AbstractTransactional`
      Do any preparatory work prior to commit. This method should throw any exceptions that can be encountered during the finalization of the behaviour.
      Specified by:
        `doPrepare` in class `Transactional.AbstractTransactional`

    - #### doCommit

          public java.lang.Throwable doCommit(java.lang.Throwable accumulate)

      point of no return: commit all changes, but leave all readers marked as compacting
      Specified by:
        `doCommit` in class `Transactional.AbstractTransactional`

    - #### doAbort

          public java.lang.Throwable doAbort(java.lang.Throwable accumulate)

      undo all of the changes made by this transaction, resetting the state to its original form
      Specified by:
        `doAbort` in class `Transactional.AbstractTransactional`

    - #### doPostCleanup

          protected java.lang.Throwable doPostCleanup(java.lang.Throwable accumulate)

      Description copied from class: `Transactional.AbstractTransactional`
      perform an exception-safe post-abort cleanup
      Overrides:
        `doPostCleanup` in class `Transactional.AbstractTransactional`

    - #### isOffline

          public boolean isOffline()

    - #### permitRedundantTransitions

          public void permitRedundantTransitions()

      Overrides:
        `permitRedundantTransitions` in class `Transactional.AbstractTransactional`

    - #### checkpoint

          public void checkpoint()

      call when a consistent batch of changes is ready to be made atomically visible these will be exposed in the Tracker atomically, or an exception will be thrown; in this case the transaction should be rolled back

    - #### update

          public void update(SSTableReader reader,
                             boolean original)

      update a reader: if !original, this is a reader that is being introduced by this transaction; otherwise it must be in the originals() set, i.e. a reader guarded by this transaction

    - #### update

          public void update(java.util.Collection<SSTableReader> readers,
                             boolean original)

    - #### obsolete

          public void obsolete(SSTableReader reader)

      mark this reader as for obsoletion : on checkpoint() the reader will be removed from the live set

    - #### obsoleteOriginals

          public void obsoleteOriginals()

      obsolete every file in the original transaction

    - #### current

          public java.lang.Iterable<SSTableReader> current()

      returns the currently visible readers managed by this transaction

    - #### originals

          public java.util.Set<SSTableReader> originals()

      the set of readers guarded by this transaction _in their original instance/state_ call current(SSTableReader) on any reader in this set to get the latest instance

    - #### isObsolete

          public boolean isObsolete(SSTableReader reader)

      indicates if the reader has been marked for obsoletion

    - #### current

          public SSTableReader current(SSTableReader reader)

      return the current version of the provided reader, whether or not it is visible or staged; i.e. returns the first version present by testing staged, logged and originals in order.

    - #### cancel

          public void cancel(SSTableReader cancel)

      remove the reader from the set we're modifying

    - #### cancel

          public void cancel(java.lang.Iterable<SSTableReader> cancels)

      remove the readers from the set we're modifying

    - #### split

          public LifecycleTransaction split(java.util.Collection<SSTableReader> readers)

      remove the provided readers from this Transaction, and return a new Transaction to manage them only permitted to be called if the current Transaction has never been used

    - #### onlyOne

          public SSTableReader onlyOne()

    - #### trackNew

          public void trackNew(SSTable table)

    - #### untrackNew

          public void untrackNew(SSTable table)

    - #### removeUnfinishedLeftovers

          public static boolean removeUnfinishedLeftovers(ColumnFamilyStore cfs)

    - #### removeUnfinishedLeftovers

          public static boolean removeUnfinishedLeftovers(CFMetaData cfMetaData)

    - #### getFiles

          public static java.util.List<java.io.File> getFiles(java.nio.file.Path folder,
                                                              java.util.function.BiFunction<java.io.File,Directories.FileType,java.lang.Boolean> filter,
                                                              Directories.OnTxnErr onTxnErr)

      Get the files in the folder specified, provided that the filter returns true. A filter is given each file and its type, and decides which files should be returned and which should be discarded. To classify files into their type, we read transaction log files. Should we fail to read these log files after a few times, we look at onTxnErr to determine what to do.
      Parameters:
        `folder` - - the folder to scan
        `onTxnErr` - - how to handle a failure to read a txn log file
        `filter` - - A function that receives each file and its type, it should return true to have the file returned
      Returns:
        - the list of files that were scanned and for which the filter returned true

    - #### rescheduleFailedDeletions

          public static void rescheduleFailedDeletions()

      Retry all deletions that failed the first time around (presumably b/c the sstable was still mmap'd.) Useful because there are times when we know GC has been invoked; also exposed as an mbean.

    - #### waitForDeletions

          public static void waitForDeletions()

      Deletions run on the nonPeriodicTasks executor, (both failedDeletions or global tidiers in SSTableReader) so by scheduling a new empty task and waiting for it we ensure any prior deletion has completed.

    - #### state

          public LifecycleTransaction.ReaderState state(SSTableReader reader)

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

Copyright © 2018 The Apache Software Foundation