Embedding KVLocal in your Java Application

Make sure that the kvstore.jar file is included in your application's CLASSPATH. The kvstore.jar file is available as part of Oracle NoSQL Database software. You can download it from Oracle Technology Network.

Create KVLocalConfig Object

Create an object of the KVLocalConfig class. This class represents the configuration parameters used by KVLocal. KVLocalConfig class contains two builders: InetBuilder and UnixDomainBuilder. The InetBuilder is the builder to construct a KVLocalConfig instance using TCP/IP sockets, and the UnixDomainBuilder is the builder to construct a KVLocalConfig instance using Unix domain sockets.

KVLocal supports the following configuration parameters.

Parameter	Description
StoreName If not set, defaults to `kvstore`. Example: `InetBuilder.setStoreName("nosql")` `UnixDomainBuilder.setStoreName("nosql")`	Name of the KVLocal instance.
HostName (For `InetBuilder`) If not set, defaults to `localhost`. (For `UnixDomainBuilder`) Defaults to `unix_domain:<KVROOT>/sockets/sock` and is non-modifiable. Example: `InetBuilder.setHostName("nosql.app.com");`	The network address to use to reach the host when using `InetBuilder` for KVLocal instance. You cannot set this parameter when using `UnixDomainBuilder`.
Port If not set, defaults to `5000`. Example: `InetBuilder.setPort(5500);`	The TCP/IP port on which the client APIs communicate with the KVLocal instance. You can change this parameter only if you are using `InetBuilder`. When using Unix domain sockets, it does not represent a TCP/IP port. However, the default value of `5000` must be specified with the `-port` flag when connecting to the Admin CLI.
enableSecurity (For `InetBuilder`) If not set, defaults to `true`. (For `UnixDomainBuilder`) Defaults to `false` and is non-modifiable. Example: `InetBuilder.enableSecurity(false);`	Determines whether it is a secure or non-secure KVLocal store. For `UnixDomainBuilder`, the value of this parameter is always false, and you cannot modify it. The reason being the Unix domain sockets configurations are inherently secure for communication.
StorageSize If not set, defaults to `10`. Example: To set the storage size to `80` GB `InetBuilder.setStorageSize(80);` `UnixDomainBuilder.setStorageSize(80);`	The maximum amount of available disk space in GB for a KVLocal database. If the KVLocal database exceeds its disk usage threshold value (excluding 5 GB of free space), KVLocal suspends all write operations on the host system until you remove sufficient data to satisfy the threshold requirement. If you set storage directory size to 0, KVLocal opportunistically uses all the available space, excluding 5 GB free disk space.
MemoryMB If not set, defaults to `8192`. The minimum value for this parameter is `48`. Example: To set the memory size to `85` MB `InetBuilder.setMemoryMB(85);` `UnixDomainBuilder.setMemoryMB(85);`	AAmount of memory size in MB of the Java heap used to run the embedded KVLocal database. The Java heap size here refers to the Java heap size of the child process and not of the JVM process that is running the application. Note: Ensure that the host machine has enough memory available to create the JVM with the requested heap size.

KVLocalConfig instance using TCP/IP sockets
KVLocalConfig instance using Unix domain sockets

For a secure KVLocal

import oracle.kv.KVLocalConfig;
/* Create a KVLocalConfig object with TCP sockets */
KVLocalConfig config = new KVLocalConfig.InetBuilder("rootDir")
                        .build();

For a non-secure KVLocal

import oracle.kv.KVLocalConfig;
/* Create a KVLocalConfig object with port number 6000 and security not enabled */
KVLocalConfig config = new kvlocalConfig.InetBuilder("rootDir")
                        .setPort(6000)
                        .enableSecurity(false)
                        .build();

rootDir is where the kvroot directory should reside. It refers to the absolute path to the directory where Oracle NoSQL Database data is stored, for example, /home/kvstore.

If you enable security for KVLocal, a security file (user.security) gets generated under the kvroot directory when you start KVLocal. If a kvstore already exists (in other words, the kvroot directory already exists), KVLocal uses the security file present in the existing kvroot directory to secure the kvstore.

import oracle.kv.KVLocalConfig;
/* Create a KVLocalConfig object with Unix domain sockets */
KVLocalConfig config = new KVLocalConfig.UnixDomainBuilder("rootDir")
                        .build();

rootDir is where the kvroot directory should reside. It refers to the absolute path to the directory where Oracle NoSQL Database data is stored, for example, /home/kvstore.

When you use Unix domain sockets, socket files get created under the kvroot directory. These socket files are used for communication between the server (KVLocal) and the client (user application). For example, if your kvroot directory is /home/kvroot, the full path to one such Unix domain socket file is: /home/kvroot/sockets/sock-5000

Invoke KVLocal Start and Stop APIs

The KVLocal class provides APIs to start or stop the embedded NoSQL database instance. In your application, invoke the start or stop APIs and get the handle to kvstore.

Note:

One application (in other words, one JVM) can manage only one KVLocal store. The second KVLocal instantiation within the same JVM throws the exception "The KVLocal has already been initialized.".

The KVLocal class provides following APIs to start or stop KVLocal instance and get the handle to the kvstore.

Method Name	Description
start(KVLocalConfig config)	Starts a KVLocal instance.
startExistingStore(String rootDir)	Starts KVLocal instance from the existing root directory.
stop()	Stops the running instance of KVLocal.
KVStore getStore()	Gets a store handle to a running KVLocal instance. A new store handle gets created as needed on the first call to this method. All subsequent calls return the existing store handle. If the existing store handle is cleaned up by invocation of the `KVLocal.closeStore()` method, the next call to this method creates a new store handle again. Note: The application must invoke `KVLocal.closeStore()` method when it is done accessing the store to free up resources associated with the store handle. DO NOT invoke `KVStore.close()` method, because it does not free up all the resources associated with the store handle and makes the store handle non-functional.

Using TCP/IP sockets
Using Unix domain sockets

import oracle.kv.KVLocalConfig;
import oracle.kv.KVLocal;
/* Create a KVLocal object and pass the KVLocal configuration parameters to the object */
KVLocalConfig config = new KVLocalConfig.InetBuilder("rootDir")
                        .build();
/* Start KVLocal*/
KVLocal local = KVLocal.start(config);
/* Get a handle to kvstore */
KVStore storeHandle = local.getStore();
/* Use existing key/value APIs to write to kvstore */
storeHandle.put(Key,Value);
ValueVersion valueVersion = storeHandle.get(Key.createKey(key));
/* Close kvstore */
KVLocal.closeStore();
/* Stop kvstore */
local.stop();

rootDir is where the kvroot directory should reside. It refers to the absolute path to the directory where Oracle NoSQL Database data is stored, for example, /home/kvstore.

import oracle.kv.KVLocalConfig;
import oracle.kv.KVLocal;
/* Create a KVLocal object and pass the KVLocal configuration parameters to the object */
KVLocalConfig config = new KVLocalConfig.UnixDomainBuilder("rootDir")
                        .build();
/* Start KVLocal*/
KVLocal local = KVLocal.start(config);
/* Get a handle to kvstore */
KVStore storeHandle = local.getStore();
/* Use existing key/value APIs to write to kvstore */
storeHandle.put(Key,Value);
ValueVersion valueVersion = storeHandle.get(Key.createKey(key));
/* Close kvstore */
KVLocal.closeStore();
/* Stop kvstore */
local.stop();

rootDir is where the kvroot directory should reside. It refers to the absolute path to the directory where Oracle NoSQL Database data is stored, for example, /home/kvstore.