java.lang.Object
- oracle.kv.KVLocal

public class KVLocal
extends java.lang.Object

KVLocal is a handle for managing embedded Oracle NoSQL Database.

Terminology:

Handle - an instance of an interface used to access the store
Embedded Oracle NoSQL database - a single-node store that is not replicated
Store - Oracle NoSQL Database physical files, including configuration files and data files
Root directory - a physical directory that contains a store
The root directory must either not exist or contain a store.

You configure, start, and stop embedded Oracle NoSQL database using KVLocal public APIs. For example:

 // Create a KVLocalConfig object with root directory specified as "rootDir"
 KVLocalConfig config = new KVLocalConfig.InetBuilder(rootDir)
                                         .build();
 // Create an embedded NoSQL database and start an instance of it
 KVLocal local = KVLocal.start(config);
 // Get a store handle to the running embedded NoSQL database
 KVStore storeHandle = local.getStore();
 // Free up resources associated with the store handle
 local.closeStore();
 // Stop the running embedded NoSQL database instance
 local.stop();

Since:: 22.1

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`closeStore()`	Close the store handle and release resources.
`java.lang.String`	`createSnapshot(java.lang.String name)`	Creates a new snapshot using the specified name as suffix.
`java.lang.String`	`getHostName()`	Returns the host name.
`static KVLocal`	`getKVLocal(java.lang.String rootDir)`	Returns an instance of KVLocal based on the root directory, which must contain an existing store.
`KVLocalConfig`	`getKVLocalConfig()`	Returns the configuration parameters.
`int`	`getMemoryMB()`	Returns the memory size in MB.
`int`	`getPort()`	Returns the port number.
`java.lang.String`	`getRootDirectory()`	Returns the directory where NoSQL Database data is placed.
`int`	`getStorageGB()`	Returns the storage directory size in GB.
`KVStore`	`getStore()`	Gets a store handle to a running embedded NoSQL database.
`java.lang.String`	`getStoreName()`	Returns the store name.
`boolean`	`isRunning()`	Whether the embedded NoSQL database instance is running.
`boolean`	`isSecure()`	Returns whether security is enabled.
`java.lang.String[]`	`listSnapshots()`	Returns the names of all snapshots.
`void`	`removeSnapshot(java.lang.String name)`	Removes the named snapshot.
`static KVLocal`	`restoreFromSnapshot(java.lang.String rootDir, java.lang.String name)`	Restores the store from a snapshot.
`static KVLocal`	`start(KVLocalConfig config)`	Starts an embedded NoSQL database instance.
`static KVLocal`	`startExistingStore(java.lang.String rootDir)`	Starts an embedded NoSQL database instance from the root directory.
`void`	`stop()`	Stops the running embedded NoSQL database instance.
`java.lang.String`	`verifyConfiguration(boolean verbose)`	Verifies the store configuration by iterating over components and checking their state against what the Admin database contains.
`java.lang.String`	`verifyData()`	Verifies store data integrity.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - start
```
public static KVLocal start(KVLocalConfig config)
```
    Starts an embedded NoSQL database instance.
    If the root directory does not exist, a new store will be created using parameters declared by KVLocalConfig. If a store already exists in the root directory, that store is opened.
    The KVLocal instance obtained by this method must be explicitly stopped using stop().
    
    Parameters:
    
    config - the KVLocal configuration parameters
    
    Returns:
    
    an instance of KVLocal
    
    Throws:
    
    java.lang.IllegalStateException - if an embedded Oracle NoSQL Database instance is already running, the root directory is not accessible, or the root directory exists but does not contain a store
    
    java.lang.IllegalArgumentException - if existing store's parameters do not match the parameters declared by KVLocalConfig
    
    KVLocalException - if an error occurs when starting the embedded NoSQL database instance
  - startExistingStore
```
public static KVLocal startExistingStore(java.lang.String rootDir)
```
    Starts an embedded NoSQL database instance from the root directory.
    The KVLocal instance obtained by this method must be explicitly stopped using stop().
    
    Parameters:
    
    rootDir - the root directory of the existing store
    
    Returns:
    
    an instance of KVLocal
    
    Throws:
    
    java.lang.IllegalStateException - if an embedded Oracle NoSQL Database instance is already running, the root directory is not accessible, the root directory's parent directory does not exist, or the root directory exists but does not contain proper files
    
    KVLocalException - if an error occurs when starting the embedded NoSQL database instance
  - stop
```
public void stop()
```
    Stops the running embedded NoSQL database instance.
    
    Throws:
    
    java.lang.IllegalStateException - if embedded NoSQL database was not started as an embedded instance
    
    KVLocalException - if an error occurs when stopping the embedded NoSQL database instance
  - isRunning
```
public boolean isRunning()
```
    Whether the embedded NoSQL database instance is running.
    
    Returns:
    
    whether the embedded NoSQL database instance is running
  - getKVLocal
```
public static KVLocal getKVLocal(java.lang.String rootDir)
```
    Returns an instance of KVLocal based on the root directory, which must contain an existing store.
    
    Parameters:
    
    rootDir - the root directory of the store
    
    Returns:
    
    an instance of KVLocal
    
    Throws:
    
    java.lang.IllegalStateException - if the store directory is not found, or the store directory is not accessible, or the root directory does not contain an existing store.
  - getStore
```
public KVStore getStore()
```
    Gets a store handle to a running embedded NoSQL database.
    A new store handle is 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 closeStore(), the next call to this method will create a new store handle again.
    The application must invoke closeStore() when it is done accessing the store to free up resources associated with the store handle. Don't invoke KVStore.close(), because it does not free up all the resources associated with the store handle and makes the store handle non-functional.
    
    Returns:
    
    an instance of KVStore
    
    Throws:
    
    FaultException - if the store is not started, or an error occurs when getting the store
    
    See Also:
    
    closeStore()
  - closeStore
```
public void closeStore()
```
    Close the store handle and release resources.
  - restoreFromSnapshot
```
public static KVLocal restoreFromSnapshot(java.lang.String rootDir,
                                          java.lang.String name)
```
    Restores the store from a snapshot.
    This method replaces the data in the root directory with the data specified in the snapshot, then starts an embedded NoSQL database instance. The KVLocal instance obtained by this method must be explicitly stopped using stop().
    
    Parameters:
    
    rootDir - the root directory of the store
    
    name - the name of the snapshot, including date and time that was generated by createSnapshot
    
    Returns:
    
    an instance of KVLocal
    
    Throws:
    
    java.lang.IllegalStateException - if an embedded NoSQL database is running, or the specified snapshot is not found, or the root directory is not accessible, or the root directory does not contain an existing store
    
    KVLocalException - if an error occurs when restoring from the snapshot
  - createSnapshot
```
public java.lang.String createSnapshot(java.lang.String name)
```
    Creates a new snapshot using the specified name as suffix.
    This method backups the storage node data files, configuration files, and adds other required files required for restore activities. The snapshot data is stored in a directory inside of the root directory. To preserve storage, invoke removeSnapshot(java.lang.String) to remove obsolete snapshots.
    
    Parameters:
    
    name - the suffix to use for the snapshot name
    
    Returns:
    
    the generated snapshot name. The generated snapshot name has date-time prefix. The date-time prefix consists of a 6-digit, year, month, day value in YYMMDD format, and a 6-digit hour, minute, seconds timestamp as HHMMSS. The date and time values are separated from each other with a dash (-), and include a dash (-) suffix before the input snapshot name.
    
    Throws:
    
    KVLocalException - if an error occurs when creating snapshot
  - listSnapshots
```
public java.lang.String[] listSnapshots()
```
    Returns the names of all snapshots.
    
    Returns:
    
    an array of names of snapshots
    
    Throws:
    
    KVLocalException - if an error occurs when listing snapshots
  - removeSnapshot
```
public void removeSnapshot(java.lang.String name)
```
    Removes the named snapshot. The method will return successfully if the named snapshot is not found.
    
    Parameters:
    
    name - the full name of the snapshot, including date and time that was generated by createSnapshot
    
    Throws:
    
    KVLocalException - if an error occurs when removing snapshot
  - verifyConfiguration
```
public java.lang.String verifyConfiguration(boolean verbose)
```
    Verifies the store configuration by iterating over components and checking their state against what the Admin database contains.
    This method checks if an embedded NoSQL database instance is running properly and healthy. If there is any configuration error, violations or warnings will be generated in the output. Violations are issues that can cause problems and should be investigated.
    
    Parameters:
    
    verbose - whether the output contains verbose output. If false, the output contains violations and warnings only.
    
    Returns:
    
    the verify configuration result in JSON format
    
    Throws:
    
    KVLocalException - if an error occurs when verifying configuration
  - verifyData
```
public java.lang.String verifyData()
```
    Verifies store data integrity.
    This method is relatively time consuming. It verifies the Log record integrity on disk and B-tree integrity in memory.
    If any service instance (such as Admin or an RN) has persistent B-tree or log corruptions, the service shuts down, and the JE (Berkeley) environment is invalidated. JE then creates a file called 7fffffff.jdb, placing it wherever other .jdb files exist in your environment. Manual administration intervention is required to recover from persistent data corruption.
    If any service instance has transient corruption, the service automatically exits. Transient corruption can be caused by a memory corruption. Restarting embedded NoSQL database instance is required to recover from transient corruption.
    
    Returns:
    
    the verify data result in JSON format. If no corruption is found, the result shows "No Btree Corruptions" and "No Log File Corruptions".
    
    Throws:
    
    KVLocalException - if an error occurs when verifying data
  - getKVLocalConfig
```
public KVLocalConfig getKVLocalConfig()
```
    Returns the configuration parameters.
    
    Returns:
    
    the configuration parameters
  - getStoreName
```
public java.lang.String getStoreName()
```
    Returns the store name.
    
    Returns:
    
    the store name
  - getHostName
```
public java.lang.String getHostName()
```
    Returns the host name.
    
    Returns:
    
    the host name
  - getRootDirectory
```
public java.lang.String getRootDirectory()
```
    Returns the directory where NoSQL Database data is placed.
    
    Returns:
    
    the directory where NoSQL Database data is placed
  - getPort
```
public int getPort()
```
    Returns the port number.
    
    Returns:
    
    the port number
  - getMemoryMB
```
public int getMemoryMB()
```
    Returns the memory size in MB. The memory size is the total RAM on the machine that can be used for the store.
    
    Returns:
    
    the memory size in MB
  - getStorageGB
```
public int getStorageGB()
```
    Returns the storage directory size in GB.
    
    Returns:
    
    the storage directory size in GB
  - isSecure
```
public boolean isSecure()
```
    Returns whether security is enabled.
    
    Returns:
    
    whether security is enabled

Class KVLocal

Method Summary

Methods inherited from class java.lang.Object

Method Detail

start

startExistingStore

stop

isRunning

getKVLocal

getStore

closeStore

restoreFromSnapshot

createSnapshot

listSnapshots

removeSnapshot

verifyConfiguration

verifyData

getKVLocalConfig

getStoreName

getHostName

getRootDirectory

getPort

getMemoryMB

getStorageGB

isSecure