Library Version 12.1.3.0

Setting Durability Guarantees
Prev | Chapter 12. Durability Guarantees | Next

## Setting Durability Guarantees

To set a durability guarantee, use the `Durability` class. When you do this, you must provide three pieces of information:

- The acknowledgment policy.

- A synchronization policy at the master node.

- A synchronization policy at the replica nodes.

The combination of policies that you use is driven by how sensitive your application might be to potential data loss, and by your write performance requirements.

For example, the fastest possible write performance can be achieved through a durability policy that requires:

- No acknowledgments.

- NO_SYNC at the master.

- NO_SYNC at the replicas.

However, this durability policy also leaves your data with the greatest risk of loss due to application or machine failure between the time the operation returns and the time when the data is written to stable storage.

On the other hand, if you want the highest possible durability guarantee, you can use:

- All replicas must acknowledge the write operation.

- SYNC at the master.

- SYNC at the replicas.

Of course, this also results in the slowest possible write performance.

Most commonly, durability policies attempt to strike a balance between write performance and data durability guarantees. For example:

- Simple majority of replicas must acknowledge the write.

- SYNC at the master.

- NO_SYNC at the replicas.

Note that you can set a default durability policy for your `KVStore` handle, but you can also override the policy on a per-operation basis for those situations where some of your data need not be as durable (or needs to be MORE durable) than the default.

For example, suppose you want an intermediate durability policy for most of your data, but sometimes you have transient or easily re-created data whose durability really is not very important. Then you would do something like this:

First, set the default durability policy for the `KVStore` handle:

    package kvstore.basicExample;

    import oracle.kv.Durability;
    import oracle.kv.KVStore;
    import oracle.kv.KVStoreConfig;
    import oracle.kv.KVStoreFactory;

    ...

    KVStoreConfig kconfig = new KVStoreConfig("exampleStore",
        "node1.example.org:5088, node2.example.org:4129");

    Durability defaultDurability =
        new Durability(Durability.SyncPolicy.SYNC,    // Master sync
                       Durability.SyncPolicy.NO_SYNC, // Replica sync
                       Durability.ReplicaAckPolicy.SIMPLE_MAJORITY);
    kconfig.setDurability(defaultDurability);

    KVStore kvstore = KVStoreFactory.getStore(kconfig);

In another part of your code, for some unusual write operations, you might then want to relax the durability guarantee so as to speed up the write performance for those specific write operations:

    package kvstore.basicExample;

    ...

    import oracle.kv.Durability;
    import oracle.kv.DurabilityException;
    import oracle.kv.Key;
    import oracle.kv.RequestTimeoutException;
    import oracle.kv.Value;
    import java.util.ArrayList;

    import org.apache.avro.Schema;
    import oracle.kv.avro.GenericAvroBinding;
    import oracle.kv.avro.GenericRecord;

    ...

    ArrayList<String> majorComponents = new ArrayList<String>();

    ...

    // Define the major and minor path components for the key
    majorComponents.add("Smith");
    majorComponents.add("Bob");

    // Create the key
    Key myKey = Key.createKey(majorComponents);

    ...

    // Binding and schema creation omitted

    ...

    final GenericRecord person = new GenericData.Record(personSchema);
    person.put("ID", 100011);
    person.put("FamiliarName", "Bob");
    person.put("Surname", "Smith");
    person.put("PrimaryPhone", "408 555 5555");

    Value myValue = binding.toValue(person);

    // Create the special durability policy
    Durability durability =
        new Durability(Durability.SyncPolicy.NO_SYNC, // Master sync
                       Durability.SyncPolicy.NO_SYNC, // Replica sync
                       Durability.ReplicaAckPolicy.NONE);

    // Now put the record. Note that we do not show the creation of the
    // kvstore handle here.
    try {
        kvstore.put(myKey, myValue,
                    null,       // ReturnValueVersion is null because
                                // we aren't using it.
                    durability, // The per-operation durability
                    0,          // Use the default request timeout
                    null);      // Use the default timeunit value
    } catch (DurabilityException de) {
        // The durability guarantee was not met
    } catch (RequestTimeoutException re) {
        // The operation was not completed within the
        // timeout value
    }

Prev | Up | Next
Setting Synchronization-Based Durability Policies | Home | Chapter 13. Executing a Sequence of Operations