The KVStore Handle

In order to perform store access of any kind, you must obtain a KVStore handle. You obtain a KVStore handle by using the KVStoreFactory.getStore() method.

When you get a KVStore handle, you must provide a KVStoreConfig object. This object identifies important properties about the store that you are accessing. We describe the KVStoreConfig class next in this chapter, but at a minimum you must use this class to identify:

  • The name of the store. The name provided here must be identical to the name used when the store was installed.

  • The network contact information for one or more helper hosts. These are the network name and port information for nodes currently belonging to the store. Multiple nodes can be identified using an array of strings. You can use one or many. Many does not hurt. The downside of using one is that the chosen host may be temporarily down, so it is a good idea to use more than one.

In addition to the KVStoreConfig class object, you can also provide a PasswordCredentials class object to KVStoreFactory.getStore(). You do this if you are using a store that has been configured to require authentication. See Using the Authentication APIs for more information.

For a store that does not require authentication, you obtain a store handle like this:

package kvstore.basicExample;

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

...

String[] hhosts = {"n1.example.org:5088", "n2.example.org:4129"};
KVStoreConfig kconfig = new KVStoreConfig("exampleStore", hhosts);
KVStore kvstore = KVStoreFactory.getStore(kconfig); 

The KVStoreConfig Class

The KVStoreConfig class is used to describe properties about a KVStore handle. Most of the properties are optional; those that are required are provided when you construct a class instance.

The properties that you can provide using KVStoreConfig are:

  • Consistency

    Consistency is a property that describes how likely it is that a record read from a replica node is identical to the same record stored on a master node. For more information, see Consistency Guarantees.

  • Durability

    Durability is a property that describes how likely it is that a write operation performed on the master node will not be lost if the master node is lost or is shut down abnormally. For more information, see Durability Guarantees.

  • Helper Hosts

    Helper hosts are hostname/port pairs that identify where nodes within the store can be contacted. Multiple hosts can be identified using an array of strings. Typically an application developer will obtain these hostname/port pairs from the store's deployer and/or administrator. For example:

    String[] hhosts = {"n1.example.org:3333", "n2.example.org:3333"};
  • Request Timeout

    Configures the amount of time the KVStore handle will wait for an operation to complete before it times out.

  • Store name

    Identifies the name of the store.

  • Password credentials and optionally a reauthentication handler

    See the next section on authentication.