Enum Constant Detail

• UNCOMMITTED

  public static final Consistency UNCOMMITTED

  Uncommitted eventual consistency.

  This level is only meaningful for read-only transactions; read-write transactions are always LINEARIZABLE.

  Transactions see a consistent view of the database that is either already committed or likely to be committed soon. This is the same as EVENTUAL_COMMITTED, but with the additional (unlikely) possibility that the view that the transaction sees may never actually get committed; this can only happen if there is a Raft leadership change during the transaction.

  Transactions at this level require no network communication, commit immediately, and never result in RetryTransactionExceptions. Committing a transaction at this level is actually equivalent to invoking rollback() instead of commit().

  In Raft terms, transactions are based on the latest uncommitted log entry, the commit operation does not wait for that log entry to be committed, and up-to-date reads are not guaranteed.

• EVENTUAL_COMMITTED

  public static final Consistency EVENTUAL_COMMITTED

  Committed eventual consistency.

  This level is only meaningful for read-only transactions; read-write transactions are always LINEARIZABLE.

  Transactions see a consistent, committed view of the database as it existed at some point in the "recent past". The view is not guaranteed to be up-to-date; it's only guaranteed to be as up-to-date as what was known to this node when the transaction was opened. In general (for example, if stuck in a network partition minority), the view could be from arbitrarily far in the past.

  Unlike EVENTUAL, transactions at this level require no network communication, commit immediately, and never result in RetryTransactionExceptions; however, they see a potentially older view. Compared to UNCOMMITTED, transactions at this level see a view that is potentially older, in exchange for the guarantee that it has definitely been committed.

  This consistency level is useful when it's important to allow reading the database in any situation, e.g., even when the local node is in a minority partition of the cluster. Of course, the data will only be as up-to-date as is known locally.

  In Raft terms, transactions are based on the latest committed log entry, and up-to-date reads are not guaranteed.

• EVENTUAL

  public static final Consistency EVENTUAL

  Eventual consistency.

  This level is only meaningful for read-only transactions; read-write transactions are always LINEARIZABLE.

  Transactions see a consistent, committed view of the database as it existed at some point in the "recent past". The view is not guaranteed to be up-to-date; it's only guaranteed to be as up-to-date as what was known to this node when the transaction was opened. In general (for example, if stuck in a network partition minority), the view could be from arbitrarily far in the past.

  No network traffic is generated by commit(), and transactions can never throw RetryTransactionExceptions due to read/write conflicts (i.e., stale read checks). A commit() blocks until the log entry on which the transaction is based is committed; if no concurrent write transactions are occurring, this will happen immediately.

  In Raft terms, transactions are based on the latest uncommitted log entry, the commit operation waits for that log entry to be committed, and up-to-date reads are not guaranteed.

• LINEARIZABLE

  public static final Consistency LINEARIZABLE

  Linearizable consistency.

  Transactions see a database that evolves step-wise through a global, linear sequence of atomic changes, where each change appears to have occurred instantaneously at some point in time between the start and end of the corresponding transaction.

  This is the default consistency level.

  In Raft terms, transactions are based on the latest uncommitted log entry, the commit operation waits for that log entry to be committed, and up-to-date reads are guaranteed.

Method Detail

• values

  public static Consistency[] values()

  Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

  for (Consistency c : Consistency.values())
      System.out.println(c);
  

  Returns:

  an array containing the constants of this enum type, in the order they are declared

• valueOf

  public static Consistency valueOf(String name)

  Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

  Parameters:

  name - the name of the enum constant to be returned.

  Returns:

  the enum constant with the specified name

  Throws:

  IllegalArgumentException - if this enum type has no constant with the specified name

  NullPointerException - if the argument is null

• isBasedOnCommittedLogEntry

  public boolean isBasedOnCommittedLogEntry()

  Determines the log entry on which transactions at this level are based.

  When false, transactions are based on this node's most recent log entry, whether committed or not. When true, transactions are based on this node's most recent committed log entry. The former provides a more up-to-date view, but commit() can block (and could possibly fail with a RetryTransactionException) when isWaitsForLogEntryToBeCommitted() is true. The latter, when combined with isGuaranteesUpToDateReads() being false, allows read-only transactions to commit immediately with no network traffic, even when in a minority partition.

  Returns:

  true if transactions at this level are always based on committed log entries

• isWaitsForLogEntryToBeCommitted

  public boolean isWaitsForLogEntryToBeCommitted()

  Determines whether transactions at this level block in commit() until the log entry on which they are based is committed.

  This setting has no effect if isBasedOnCommittedLogEntry() returns true, because in that case the log entry on which the transaction is based is already committed when transaction starts.

  Returns:

  true if transactions at this level wait for their base log entry to be committed

• isGuaranteesUpToDateReads

  public boolean isGuaranteesUpToDateReads()

  Determines whether transactions at this level guarantee reading the most up-to-date information.

  This setting has no effect on transactions that contain mutations; they always read the most up-to-date information.

  If this returns false, read-only transactions may read out-of-date information ("eventual consistency").

  Returns:

  true if transactions at this level guarantee up-to-date reads