Library Version 12.1.3.0

Using Version-Based Consistency
Prev | Chapter 9. Consistency Guarantees | Next

## Using Version-Based Consistency

Version-based consistency is used on a per-operation basis. It ensures that a read performed on a replica is at least as current as some previous write performed on the master.

An example of how this might be used is a web application that collects some information from a customer (such as her name). It then customizes all subsequent pages presented to the customer with her name. The storage of the customer's name is a write operation that can only be performed by the master node, while subsequent page creation is performed as a read-only operation that can occur at any node in the store.

Use of this consistency policy might require that version information be transferred between processes in your application.

To create a version-based consistency policy, you use the `Consistency.Version` class. When you construct an instance of this class, you must provide the following information:

- `version`

  The `Version` that the read must match.

- `timeout`

  A `long` that describes how long the replica is permitted to wait in an attempt to meet the `version` requirement. That is, if the replica cannot immediately meet the `version` requirement, then it will wait this amount of time to see if it is updated with the required data from the master. If the replica cannot meet the requirement within the `timeout` period, a `ConsistencyException` is thrown.

- `timeoutUnit`

  A `TimeUnit` that identifies the units used by `timeout`. For example: `TimeUnit.SECONDS`.

For example, the following code performs a store write, collects the version information, then uses it to construct a version-based consistency policy.

    package kvstore.basicExample;

    import oracle.kv.KVStore;
    import oracle.kv.table.Row;
    import oracle.kv.table.Table;
    import oracle.kv.table.TableAPI;
    import oracle.kv.Version;

    ...

    // KVStore handle creation is omitted for brevity

    ...

    TableAPI tableH = kvstore.getTableAPI();
    Table myTable = tableH.getTable("myTable");

    // Get a Row instance
    Row row = myTable.createRow();

    // Now put all of the cells in the row.

    row.put("item", "Bolts");
    row.put("count1", 5);
    row.put("count2", 23);
    row.put("percentage", 0.2173913);

    // Now write the table to the store, capturing the
    // Version information as we do.

    Version matchVersion = tableH.put(row, null, null);

    Version matchVersion = kvstore.put(myKey, myValue);

At some other point in this application's code, or perhaps in another application entirely, we use the `matchVersion` captured above to create a version-based consistency policy.

    package kvstore.basicExample;

    import oracle.kv.Consistency;
    import oracle.kv.ConsistencyException;
    import oracle.kv.KVStore;
    import oracle.kv.table.PrimaryKey;
    import oracle.kv.table.ReadOptions;
    import oracle.kv.table.Row;
    import oracle.kv.table.Table;
    import oracle.kv.table.TableAPI;

    import java.util.concurrent.TimeUnit;

    ...

    // KVStore handle creation is omitted for brevity

    ...

    // Construct the PrimaryKey.

    PrimaryKey key = myTable.createPrimaryKey();
    key.put("item", "Bolts");

    // Create the consistency policy, using the
    // Version object we captured, above.
    Consistency.Version versionConsistency =
            new Consistency.Version(matchVersion,
                                    200,
                                    TimeUnit.NANOSECONDS);

    // Create a ReadOptions using our new consistency policy.
    ReadOptions ro = new ReadOptions(versionConsistency, 0, null);

    // Now perform the read.
    try {

        Row row = tableH.get(key, ro);

        // Do work with the row here
    } catch (ConsistencyException ce) {
        // The consistency guarantee was not met
    }

Prev | Up | Next
Using Time-Based Consistency | Home | Chapter 10. Durability Guarantees