Library Version 12.1.3.0

Chapter 3. Developing for Oracle NoSQL Database
Prev |  | Next

## Chapter 3. Developing for Oracle NoSQL Database

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.

### Note

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 = {"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.

Prev |  | Next
kvlite Utility Command Line Parameter Options | Home | Using the Authentication APIs