RepairSession (apache-cassandra API)
Date: 2018-02-12

org.apache.cassandra.repair

## Class RepairSession

- java.lang.Object
- - com.google.common.util.concurrent.AbstractFuture<RepairSessionResult>
  - - org.apache.cassandra.repair.RepairSession

- All Implemented Interfaces:
    com.google.common.util.concurrent.ListenableFuture<RepairSessionResult>, java.util.concurrent.Future<RepairSessionResult>, IEndpointStateChangeSubscriber, IFailureDetectionEventListener

      public class RepairSession
      extends com.google.common.util.concurrent.AbstractFuture<RepairSessionResult>
      implements IEndpointStateChangeSubscriber, IFailureDetectionEventListener

  Coordinates the (active) repair of a token range. A given RepairSession repairs a set of replicas for a given range on a list of column families. For each of the column family to repair, RepairSession creates a `RepairJob` that handles the repair of that CF. A given RepairJob has the 2 main phases:
  1. Validation phase: the job requests merkle trees from each of the replica involves (`ValidationTask`) and waits until all trees are received (in validationComplete()).
  2. Synchronization phase: once all trees are received, the job compares each tree with all the other using a so-called `SyncTask`. If there is difference between 2 trees, the concerned SyncTask will start a streaming of the difference between the 2 endpoint concerned.
  The job is done once all its SyncTasks are done (i.e. have either computed no differences or the streaming they started is done (syncComplete())). A given session will execute the first phase (validation phase) of each of it's job sequentially. In other words, it will start the first job and only start the next one once that first job validation phase is complete. This is done so that the replica only create one merkle tree at a time, which is our way to ensure that such creation starts roughly at the same time on every node (see CASSANDRA-2816). However the synchronization phases are allowed to run concurrently (with each other and with validation phases). A given RepairJob has 2 modes: either sequential or not (isSequential flag). If sequential, it will requests merkle tree creation from each replica in sequence (though in that case we still first send a message to each node to flush and snapshot data so each merkle tree creation is still done on similar data, even if the actual creation is not done simulatneously). If not sequential, all merkle tree are requested in parallel. Similarly, if a job is sequential, it will handle one SyncTask at a time, but will handle all of them in parallel otherwise.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `java.util.Set<java.net.InetAddress>` | `endpoints`
    `java.lang.String` | `keyspace`
    `RepairParallelism` | `parallelismDegree`
    `java.util.UUID` | `parentRepairSession`
    `Range<Token>` | `range` Range to repair

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RepairSession(java.util.UUID parentRepairSession, java.util.UUID id, Range<Token> range, java.lang.String keyspace, RepairParallelism parallelismDegree, java.util.Set<java.net.InetAddress> endpoints, long repairedAt, java.lang.String... cfnames)` Create new repair session.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `beforeChange(java.net.InetAddress endpoint, EndpointState currentState, ApplicationState newStateKey, VersionedValue newValue)`
    `void` | `convict(java.net.InetAddress endpoint, double phi)` Convict the specified endpoint.
    `void` | `forceShutdown(java.lang.Throwable reason)` clear all RepairJobs and terminate this session.
    `java.util.UUID` | `getId()`
    `Range<Token>` | `getRange()`
    `void` | `onAlive(java.net.InetAddress endpoint, EndpointState state)`
    `void` | `onChange(java.net.InetAddress endpoint, ApplicationState state, VersionedValue value)`
    `void` | `onDead(java.net.InetAddress endpoint, EndpointState state)`
    `void` | `onJoin(java.net.InetAddress endpoint, EndpointState epState)` Use to inform interested parties about the change in the state for specified endpoint
    `void` | `onRemove(java.net.InetAddress endpoint)`
    `void` | `onRestart(java.net.InetAddress endpoint, EndpointState epState)` Called whenever a node is restarted.
    `void` | `start(com.google.common.util.concurrent.ListeningExecutorService executor)` Start RepairJob on given ColumnFamilies.
    `void` | `syncComplete(RepairJobDesc desc, NodePair nodes, boolean success)` Notify this session that sync completed/failed with given `NodePair`.
    `void` | `terminate()`
    `void` | `validationComplete(RepairJobDesc desc, java.net.InetAddress endpoint, MerkleTree tree)` Receive merkle tree response or failed response from `endpoint` for current repair job.
    `void` | `waitForSync(Pair<RepairJobDesc,NodePair> key, RemoteSyncTask task)`
    `void` | `waitForValidation(Pair<RepairJobDesc,java.net.InetAddress> key, ValidationTask task)`

    - ### Methods inherited from class com.google.common.util.concurrent.AbstractFuture

      `addListener, cancel, get, get, interruptTask, isCancelled, isDone, set, setException, wasInterrupted`

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

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

- - ### Field Detail

    - #### parentRepairSession

          public final java.util.UUID parentRepairSession

    - #### keyspace

          public final java.lang.String keyspace

    - #### parallelismDegree

          public final RepairParallelism parallelismDegree

    - #### range

          public final Range<Token> range

      Range to repair

    - #### endpoints

          public final java.util.Set<java.net.InetAddress> endpoints

  - ### Constructor Detail

    - #### RepairSession

          public RepairSession(java.util.UUID parentRepairSession,
                               java.util.UUID id,
                               Range<Token> range,
                               java.lang.String keyspace,
                               RepairParallelism parallelismDegree,
                               java.util.Set<java.net.InetAddress> endpoints,
                               long repairedAt,
                               java.lang.String... cfnames)

      Create new repair session.
      Parameters:
        `parentRepairSession` - the parent sessions id
        `id` - this sessions id
        `range` - range to repair
        `keyspace` - name of keyspace
        `parallelismDegree` - specifies the degree of parallelism when calculating the merkle trees
        `endpoints` - the data centers that should be part of the repair; null for all DCs
        `repairedAt` - when the repair occurred (millis)
        `cfnames` - names of columnfamilies

  - ### Method Detail

    - #### getId

          public java.util.UUID getId()

    - #### getRange

          public Range<Token> getRange()

    - #### waitForValidation

          public void waitForValidation(Pair<RepairJobDesc,java.net.InetAddress> key,
                                        ValidationTask task)

    - #### waitForSync

          public void waitForSync(Pair<RepairJobDesc,NodePair> key,
                                  RemoteSyncTask task)

    - #### validationComplete

          public void validationComplete(RepairJobDesc desc,
                                         java.net.InetAddress endpoint,
                                         MerkleTree tree)

      Receive merkle tree response or failed response from `endpoint` for current repair job.
      Parameters:
        `desc` - repair job description
        `endpoint` - endpoint that sent merkle tree
        `tree` - calculated merkle tree, or null if validation failed

    - #### syncComplete

          public void syncComplete(RepairJobDesc desc,
                                   NodePair nodes,
                                   boolean success)

      Notify this session that sync completed/failed with given `NodePair`.
      Parameters:
        `desc` - synced repair job
        `nodes` - nodes that completed sync
        `success` - true if sync succeeded

    - #### start

          public void start(com.google.common.util.concurrent.ListeningExecutorService executor)

      Start RepairJob on given ColumnFamilies. This first validates if all replica are available, and if they are, creates RepairJobs and submit to run on given executor.
      Parameters:
        `executor` - Executor to run validation

    - #### terminate

          public void terminate()

    - #### forceShutdown

          public void forceShutdown(java.lang.Throwable reason)

      clear all RepairJobs and terminate this session.
      Parameters:
        `reason` - Cause of error for shutdown

    - #### onJoin

          public void onJoin(java.net.InetAddress endpoint,
                             EndpointState epState)

      Description copied from interface: `IEndpointStateChangeSubscriber`
      Use to inform interested parties about the change in the state for specified endpoint
      Specified by:
        `onJoin` in interface `IEndpointStateChangeSubscriber`
      Parameters:
        `endpoint` - endpoint for which the state change occurred.
        `epState` - state that actually changed for the above endpoint.

    - #### beforeChange

          public void beforeChange(java.net.InetAddress endpoint,
                                   EndpointState currentState,
                                   ApplicationState newStateKey,
                                   VersionedValue newValue)

      Specified by:
        `beforeChange` in interface `IEndpointStateChangeSubscriber`

    - #### onChange

          public void onChange(java.net.InetAddress endpoint,
                               ApplicationState state,
                               VersionedValue value)

      Specified by:
        `onChange` in interface `IEndpointStateChangeSubscriber`

    - #### onAlive

          public void onAlive(java.net.InetAddress endpoint,
                              EndpointState state)

      Specified by:
        `onAlive` in interface `IEndpointStateChangeSubscriber`

    - #### onDead

          public void onDead(java.net.InetAddress endpoint,
                             EndpointState state)

      Specified by:
        `onDead` in interface `IEndpointStateChangeSubscriber`

    - #### onRemove

          public void onRemove(java.net.InetAddress endpoint)

      Specified by:
        `onRemove` in interface `IEndpointStateChangeSubscriber`

    - #### onRestart

          public void onRestart(java.net.InetAddress endpoint,
                                EndpointState epState)

      Description copied from interface: `IEndpointStateChangeSubscriber`
      Called whenever a node is restarted. Note that there is no guarantee when that happens that the node was previously marked down. It will have only if `state.isAlive() == false` as `state` is from before the restarted node is marked up.
      Specified by:
        `onRestart` in interface `IEndpointStateChangeSubscriber`

    - #### convict

          public void convict(java.net.InetAddress endpoint,
                              double phi)

      Description copied from interface: `IFailureDetectionEventListener`
      Convict the specified endpoint.
      Specified by:
        `convict` in interface `IFailureDetectionEventListener`
      Parameters:
        `endpoint` - endpoint to be convicted
        `phi` - the value of phi with with ep was convicted

Copyright © 2018 The Apache Software Foundation