Chapter 3. Developing for Oracle NoSQL Database

Table of Contents

The KVStore Handle
The KVStoreConfig Class
Using the Authentication APIs
Configuring SSL
Authenticating to the Store
Renewing Expired Login Credentials
Unauthorized Access

You access the data in the Oracle NoSQL Database KVStore using Java APIs that are provided with the product. There are two different programming paradigms that you can use to write your Oracle NoSQL Database applications. One uses a tables API, and the other offers a key/value pair API. Most customers should use the tables API because it offers important features that do not appear in the key/value pair API, such as secondary indexing. However, as of this release, the tables API does not allow you to insert Large Objects into a table. You can, however, use the LOB API alongside of the tables API.

Regardless of the API you decide to use, the provided classes and methods allow you to write data to the store, retrieve it, and delete it. You use these APIs to define consistency and durability guarantees. It is also possible to execute a sequence of store operations atomically so that all the operations succeed, or none of them do.

The rest of this book introduces the Java APIs that you use to access the store, and the concepts that go along with them. This book describes the tables API. If you prefer to use the key/value API, you should read Oracle NoSQL Database Getting Started with the Key/Value API.


Oracle NoSQL Database is tested with Java 7, and so Oracle NoSQL Database should be used only with that version of Java.

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 = {"", ""};
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 = {"", ""};
  • 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.