Package oracle.kv

# Class KVLocal

java.lang.Object
oracle.kv.KVLocal

public class KVLocal extends 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

  Modifier and Type
  Method
  Description
  `void`
  `closeStore()`
  Close the store handle and release resources.
  `String`
  `createSnapshot(String name)`
  Creates a new snapshot using the specified name as suffix.
  `String`
  `getHostName()`
  Returns the host name.
  `static KVLocal`
  `getKVLocal(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.
  `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.
  `String`
  `getStoreName()`
  Returns the store name.
  `boolean`
  `isRunning()`
  Whether the embedded NoSQL database instance is running.
  `boolean`
  `isSecure()`
  Returns whether security is enabled.
  `String[]`
  `listSnapshots()`
  Returns the names of all snapshots.
  `void`
  `removeSnapshot(String name)`
  Removes the named snapshot.
  `static KVLocal`
  `restoreFromSnapshot(String rootDir, String name)`
  Restores the store from a snapshot.
  `static KVLocal`
  `start(KVLocalConfig config)`
  Starts an embedded NoSQL database instance.
  `static KVLocal`
  `startExistingStore(String rootDir)`
  Starts an embedded NoSQL database instance from the root directory.
  `void`
  `stop()`
  Stops the running embedded NoSQL database instance.
  `String`
  `verifyConfiguration(boolean verbose)`
  Verifies the store configuration by iterating over components and checking their state against what the Admin database contains.
  `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 Details

  - ### 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:
      `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
      `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(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:
      `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:
      `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(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:
      `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(String rootDir, 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:
      `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 String createSnapshot(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 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(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 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 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 String getStoreName()
    Returns the store name.
    Returns:
      the store name

  - ### getHostName

    public String getHostName()
    Returns the host name.
    Returns:
      the host name

  - ### getRootDirectory

    public 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