oracle.kv

## Class Consistency.Version

- java.lang.Object
- - oracle.kv.Consistency
  - - oracle.kv.Consistency.Version

- All Implemented Interfaces:
    Serializable, oracle.kv.impl.util.FastExternalizable
  Enclosing class:
    Consistency

      public static class Consistency.Version
      extends Consistency

  A consistency policy which ensures that the environment on a Replica node is at least as current as denoted by the specified Key-Value pair `Version`.

  The version of a Key-Value pair represents a point in the serialized transaction schedule created by the master. In other words, the version is like a bookmark, representing a particular transaction commit in the replication stream. The Replica ensures that the commit identified by the `Version` has been executed before allowing the transaction on the Replica to proceed.

  For example, suppose the application is a web application. Each request to the web server consists of an update operation followed by read operations (say from the same client). The read operations naturally expect to see the data from the updates executed by the same request. However, the read operations might have been routed to a Replica node that did not execute the update.

  In such a case, the update request would generate a `Version`, which would be resubmitted by the browser, and then passed via a `Consistency.Version` object with subsequent read requests to the KV Store. The read request may be directed by the KV Store's load balancer to any one of the available Replicas. If the Replica servicing the request is already current (with respect to the version token), it will immediately execute the transaction and satisfy the request. If not, the transaction will stall until the Replica replay has caught up and the change is available at that node.

  ### Consistency Timeout

  This class has a `timeout` attribute that controls how long a Replica may wait for the desired consistency to be achieved before giving up.

  All KVStore read operations support a Consistency specification, as well as a separate operation timeout. The KVStore client driver implements a read operation by choosing a node (usually a Replica) from the proper replication group, and sending it a request. If the Replica cannot guarantee the desired Consistency within the Consistency timeout, it replies to the request with a failure indication. If there is still time remaining within the operation timeout, the client driver picks another node and tries the request again (transparent to the application).

  It makes sense to think of the operation timeout as the maximum amount of time the application is willing to wait for the operation to complete. The Consistency timeout is like a performance hint to the implementation, suggesting that it can generally expect that a healthy Replica usually should be able to become consistent within the given amount of time, and that if it doesn't, then it is probably more likely worth the overhead of abandoning the request attempt and retrying with a different replica. Note that for the Consistency timeout to be meaningful it must be smaller than the operation timeout.

  Choosing a value for the operation timeout depends on the needs of the application. Finding a good Consistency timeout value is more likely to depend on observations made of real system performance.

  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class oracle.kv.Consistency

      `Consistency.Time, Consistency.Version`

  - ### Field Summary

    - ### Fields inherited from class oracle.kv.Consistency

      `ABSOLUTE, NONE_REQUIRED, NONE_REQUIRED_NO_MASTER`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Consistency.Version(Version version, long timeout, TimeUnit timeoutUnit)` Defines how current a Replica needs to be in terms of a specific write operation that was previously completed.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object obj)`
    `String` | `getName()` Returns the name used to identify the policy.
    `long` | `getTimeout(TimeUnit unit)` Return the timeout specified when creating this consistency policy.
    `Version` | `getVersion()` Return the `Version` used to create this consistency policy.
    `int` | `hashCode()`
    `String` | `toString()`

    - ### Methods inherited from class oracle.kv.Consistency

      `fromByteArray, toByteArray`

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

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

    - ### Methods inherited from interface oracle.kv.impl.util.FastExternalizable

      `writeFastExternal`

- - ### Constructor Detail

    - #### Consistency.Version

          public Consistency.Version(Version version,
                             long timeout,
                             TimeUnit timeoutUnit)

      Defines how current a Replica needs to be in terms of a specific write operation that was previously completed. An operation on a Replica that uses this consistency policy is allowed to start only after the transaction identified by the `version` has been committed on the Replica. The transaction will wait for at most `timeout` for the Replica to catch up. If the Replica has not caught up in this period, the client method will throw a `ConsistencyException`.
      Parameters:
        `version` - the token identifying the transaction.
        `timeout` - the maximum amount of time that the transaction start will wait to allow the Replica to catch up.
        `timeoutUnit` - the `TimeUnit` for the timeout parameter.

  - ### Method Detail

    - #### getName

          public String getName()

      Description copied from class: `Consistency`
      Returns the name used to identify the policy.
      Specified by:
        `getName` in class `Consistency`

    - #### getVersion

          public Version getVersion()

      Return the `Version` used to create this consistency policy.

    - #### getTimeout

          public long getTimeout(TimeUnit unit)

      Return the timeout specified when creating this consistency policy.
      Parameters:
        `unit` - the `TimeUnit` of the returned value.
      Returns:
        the timeout specified when creating this consistency policy

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright (c) 2011, 2014 Oracle and/or its affiliates. All rights reserved.