When a record (that is, a key-value pair) is initially inserted in
the store, and each time it is updated, it is assigned a unique
version token. The version is always returned by the method that
wrote the record to the store (for example,
KVStore.put()). The version information is
also returned by methods that retrieve records from the store.
There are two reasons why versions might be important.
When an update or delete is to be performed, it may be
important to only perform the operation if the record's
value has not changed. This is particularly interesting in
an application where there can be multiple threads or
processes simultaneously operating on the record. In this
case, read the record, retrieving its version when you do
so. You can then perform a put operation, but only allow
the put to proceed if the version has not changed. You use
KVStore.putIfVersion() or
KVStore.deleteIfVersion()
to guarantee this.
When a client reads a value that was previously written, it may be important to ensure that the Oracle NoSQL Database node servicing the read operation has been updated with the information previously written. This can be accomplished by passing the version of the previously written value as a consistency parameter to the read operation. For more information on using consistency, see Consistency Guarantees.
Versions are managed using the Version class. In
some situations, it is returned as part of another encapsulating
class, such as KeyValueVersion or
ValueVersion.
The following code fragment retrieves a record, and then stores that record only if the version has not changed:
package kvstore.basicExample;
...
import oracle.kv.Key;
import oracle.kv.Value;
import oracle.kv.ValueVersion;
import java.util.ArrayList;
...
ArrayList<String> majorComponents = new ArrayList<String>();
ArrayList<String> minorComponents = new ArrayList<String>();
...
// Define the major and minor path components for the key
majorComponents.add("Smith");
majorComponents.add("Bob");
minorComponents.add("phonenumber");
// Create the key
Key myKey = Key.createKey(majorComponents, minorComponents);
// Now retrieve the record. Note that we do not show the creation of
// the kvstore handle here.
ValueVersion vv = kvstore.get(myKey);
Value value = vv.getValue();
Version version = vv.getVersion();
...
///////////////////////////////////////////////////////////
////////////// Do work on the value here //////////////////
///////////////////////////////////////////////////////////
...
// Put if the version is correct. Notice that here we examine
// the return code. If it is null, that means that the put was
// unsuccessful, probably because the record was changed elsewhere.
// In this case, you could retry the entire get/putIfVersion
// operation.
Version newVersion = kvstore.putIfVersion(myKey, value, version);
if (newVersion == null) {
// Unsuccessful. Someone else probably modified the record.
}