Class KVLocal
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 TypeMethodDescriptionvoid
Close the store handle and release resources.createSnapshot
(String name) Creates a new snapshot using the specified name as suffix.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.Returns the configuration parameters.int
Returns the memory size in MB.int
getPort()
Returns the port number.Returns the directory where NoSQL Database data is placed.int
Returns the storage directory size in GB.getStore()
Gets a store handle to a running embedded NoSQL database.Returns the store name.boolean
Whether the embedded NoSQL database instance is running.boolean
isSecure()
Returns whether security is enabled.String[]
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.verifyConfiguration
(boolean verbose) Verifies the store configuration by iterating over components and checking their state against what the Admin database contains.Verifies store data integrity.
-
Method Details
-
start
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 storeIllegalArgumentException
- if existing store's parameters do not match the parameters declared by KVLocalConfigKVLocalException
- if an error occurs when starting the embedded NoSQL database instance
-
startExistingStore
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 filesKVLocalException
- 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 instanceKVLocalException
- 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
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
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 invokeKVStore.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
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 storename
- 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 storeKVLocalException
- if an error occurs when restoring from the snapshot
-
createSnapshot
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
Returns the names of all snapshots.- Returns:
- an array of names of snapshots
- Throws:
KVLocalException
- if an error occurs when listing snapshots
-
removeSnapshot
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
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
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
Returns the configuration parameters.- Returns:
- the configuration parameters
-
getStoreName
Returns the store name.- Returns:
- the store name
-
getHostName
Returns the host name.- Returns:
- the host name
-
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
-