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 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

      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