Table of Contents
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 key/value API. If you prefer to use the tables API, you should read Oracle NoSQL Database Getting Started with the Tables API.
Oracle NoSQL Database is tested with Java 7, and so Oracle NoSQL Database should be used only with that version of Java.
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 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.