com.sparsity.sparksee.gdb

Class Sparksee

java.lang.Object

com.sparsity.sparksee.gdb.Sparksee

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class Sparksee
extends java.lang.Object
implements java.io.Closeable

Sparksee class.

All Sparksee programs must have one single Sparksee instance to manage one or more Database instances.

This class allows for the creation of new Databases or open an existing one.

Author:

Sparsity Technologies http://www.sparsity-technologies.com

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	Version Sparksee version.

Constructor Summary

Constructors

Constructor and Description
Sparksee(SparkseeConfig config) Creates a new instance.

Method Summary

Modifier and Type	Method and Description
boolean	addChecksums(java.lang.String path) Converts a database WITHOUT checksums into a database WITH checksums.
void	close() Closes the Sparksee instance.
Database	create(java.lang.String path, java.lang.String alias) Creates a new Database instance.
Database	create(java.lang.String path, java.lang.String alias, SparkseeConfig config) Creates a new Database instance.
boolean	decrypt(java.lang.String path) Converts a database WITH encryption into a database WITHOUT encryption.
boolean	encrypt(java.lang.String path) Converts a database WITHOUT encryption into an encrypted database.
long	getInMemoryPoolCapacity() Gets the capacity of the in-memory pool (in Megabytes)
boolean	isClosed() Gets if Sparksee instance has been closed or not.
Database	open(java.lang.String path, boolean readOnly) Opens an existing Database instance.
Database	open(java.lang.String path, boolean readOnly, SparkseeConfig config) Opens an existing Database instance.
boolean	removeChecksums(java.lang.String path) Converts a database WITH checksums into a database WITHOUT checksums.
void	resizeInMemoryPool(long newCapacity) Resizes the in memory pool allocator.
Database	restore(java.lang.String path, java.lang.String backupFile) Restores a Database from a backup file.
Database	restore(java.lang.String path, java.lang.String backupFile, SparkseeConfig config) Restores a Database from a backup file.
Database	restoreEncryptedBackup(java.lang.String path, java.lang.String backupFile, SparkseeConfig config, java.lang.String keyInHex, java.lang.String ivInHex) Restores a Database from an encrypted backup file.
Database	restoreEncryptedBackup(java.lang.String path, java.lang.String backupFile, java.lang.String keyInHex, java.lang.String ivInHex) Restores a Database from an encrypted backup file.
boolean	verifyChecksums(java.lang.String path) Verifies the Checksum integrity of the given image file and it's recovery log file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

Version

public static java.lang.String Version

Sparksee version.

Sparksee version.

Constructor Detail

Sparksee

public Sparksee(SparkseeConfig config)

Creates a new instance.

Parameters:

config - [in/out] Sparksee configuration (may be updated).

Method Detail

restoreEncryptedBackup

public Database restoreEncryptedBackup(java.lang.String path,
                                       java.lang.String backupFile,
                                       SparkseeConfig config,
                                       java.lang.String keyInHex,
                                       java.lang.String ivInHex)
                                throws java.lang.RuntimeException,
                                       java.io.FileNotFoundException

Restores a Database from an encrypted backup file.

See the Graph class EncryptedBackup method.

Parameters:

path - [in] Database storage file.

backupFile - [in] The Backup file to be restored.

config - [in] Use a specific configuration instead of the one in this Sparksee

keyInHex - [In] The AES encryption Key of the backup file as an hexadecimal string (8, 16 or 32 bytes).

ivInHex - [In] The AES Initialization Vector of the backup file as an hexadecimal string (16 bytes).

Returns:

A Database instance.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - If the given file cannot be created, or the exported data file does not exists.

resizeInMemoryPool

public void resizeInMemoryPool(long newCapacity)
                        throws java.lang.RuntimeException

Resizes the in memory pool allocator.

Parameters:

newCapacity - The new capacity of the in memory pool allocator

Throws:

java.lang.RuntimeException - null

create

public Database create(java.lang.String path,
                       java.lang.String alias,
                       SparkseeConfig config)
                throws java.lang.RuntimeException,
                       java.io.FileNotFoundException

Creates a new Database instance.

Parameters:

path - [in] Database storage file.

alias - [in] Database alias name.

config - [in] Use a specific configuration instead of the one in this Sparksee

Returns:

A Database instance.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - If the given file cannot be created.

verifyChecksums

public boolean verifyChecksums(java.lang.String path)
                        throws java.lang.RuntimeException,
                               java.io.FileNotFoundException

Verifies the Checksum integrity of the given image file and it's recovery log file.

The main database file checksums are always checked.

When the recovery log file exists, the recovery log file is also checked for checksum and format errors.

When the checksums of the main file or the recovery file are incorrect, the funcion returns false, in any other error it throws an exception.

Any error found is logged as a WARNING.

sparksee::gdb::FileNotFoundExceptionsparksee::gdb::Error

Parameters:

path - The path to the image file

Returns:

Returns true if the checksum verification succeeded. Returns false if an invalid checksum was detected.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - null

removeChecksums

public boolean removeChecksums(java.lang.String path)
                        throws java.lang.RuntimeException,
                               java.io.FileNotFoundException

Converts a database WITH checksums into a database WITHOUT checksums.

Any error found is logged. The database (and it's recovery log if present) have checksums. sparksee::gdb::FileNotFoundExceptionsparksee::gdb::Error

Parameters:

path - The path to the database image file

Returns:

Returns true if the checksum could be removed. The errors are returned with an exception.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - null

restore

public Database restore(java.lang.String path,
                        java.lang.String backupFile)
                 throws java.lang.RuntimeException,
                        java.io.FileNotFoundException

Restores a Database from a backup file.

See the Graph class Backup method.

Parameters:

path - [in] Database storage file.

backupFile - [in] The Backup file to be restored.

Returns:

A Database instance.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - If the given file cannot be created, or the exported data file does not exists.

addChecksums

public boolean addChecksums(java.lang.String path)
                     throws java.lang.RuntimeException,
                            java.io.FileNotFoundException

Converts a database WITHOUT checksums into a database WITH checksums.

Any error found is logged. The database (and it's recovery log if present) does NOT have checksums. sparksee::gdb::FileNotFoundExceptionsparksee::gdb::Error

Parameters:

path - The path to the database image file

Returns:

Returns true if the checksum could be added or false otherwise.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - null

restoreEncryptedBackup

public Database restoreEncryptedBackup(java.lang.String path,
                                       java.lang.String backupFile,
                                       java.lang.String keyInHex,
                                       java.lang.String ivInHex)
                                throws java.lang.RuntimeException,
                                       java.io.FileNotFoundException

Restores a Database from an encrypted backup file.

See the Graph class EncryptedBackup method.

Parameters:

path - [in] Database storage file.

backupFile - [in] The Backup file to be restored.

keyInHex - [In] The AES encryption Key of the backup file as an hexadecimal string (8, 16 or 32 bytes).

ivInHex - [In] The AES Initialization Vector of the backup file as an hexadecimal string (16 bytes).

Returns:

A Database instance.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - If the given file cannot be created, or the exported data file does not exists.

decrypt

public boolean decrypt(java.lang.String path)
                throws java.lang.RuntimeException,
                       java.io.FileNotFoundException

Converts a database WITH encryption into a database WITHOUT encryption.

Any error found is logged. The database (and it's recovery log if present) is encrypted. The current encryption had been configured using SparkseeConfig. sparksee::gdb::FileNotFoundExceptionsparksee::gdb::Error

Parameters:

path - The path to the database image file

Returns:

Returns true if the database could be unencrypted. The errors are returned with an exception.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - null

restore

public Database restore(java.lang.String path,
                        java.lang.String backupFile,
                        SparkseeConfig config)
                 throws java.lang.RuntimeException,
                        java.io.FileNotFoundException

Restores a Database from a backup file.

See the Graph class Backup method.

Parameters:

path - [in] Database storage file.

backupFile - [in] The Backup file to be restored.

config - [in] Use a specific configuration instead of the one in this Sparksee

Returns:

A Database instance.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - If the given file cannot be created, or the exported data file does not exists.

create

public Database create(java.lang.String path,
                       java.lang.String alias)
                throws java.lang.RuntimeException,
                       java.io.FileNotFoundException

Creates a new Database instance.

Parameters:

path - [in] Database storage file.

alias - [in] Database alias name.

Returns:

A Database instance.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - If the given file cannot be created.

open

public Database open(java.lang.String path,
                     boolean readOnly)
              throws java.lang.RuntimeException,
                     java.io.FileNotFoundException

Opens an existing Database instance.

Parameters:

path - [in] Database storage file.

readOnly - [in] If TRUE, open Database in read-only mode.

Returns:

A Database instance.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - If the given file does not exist.

isClosed

public boolean isClosed()

Gets if Sparksee instance has been closed or not.

Returns:

TRUE if the Sparksee instance has been closed, FALSE otherwise.

See Also:

close()

open

public Database open(java.lang.String path,
                     boolean readOnly,
                     SparkseeConfig config)
              throws java.lang.RuntimeException,
                     java.io.FileNotFoundException

Opens an existing Database instance.

The provided configuration will be used for all the database settings but not for the license, which must already be properly setup in this class.

Parameters:

path - [in] Database storage file.

readOnly - [in] If TRUE, open Database in read-only mode.

config - [in] Use a specific configuration instead of the one in this Sparksee

Returns:

A Database instance.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - If the given file does not exist.

encrypt

public boolean encrypt(java.lang.String path)
                throws java.lang.RuntimeException,
                       java.io.FileNotFoundException

Converts a database WITHOUT encryption into an encrypted database.

Any error found is logged. The database (and it's recovery log if present) does is NOT encrypted. The encryption had already been configured using SparkseeConfig. sparksee::gdb::FileNotFoundExceptionsparksee::gdb::Error

Parameters:

path - The path to the database image file

Returns:

Returns true if the database could be encrypted. The errors are returned with an exception.

Throws:

java.lang.RuntimeException - null

java.io.FileNotFoundException - null

close

public void close()

Closes the Sparksee instance.

It must be called to ensure the integrity of all data.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

getInMemoryPoolCapacity

public long getInMemoryPoolCapacity()

Gets the capacity of the in-memory pool (in Megabytes)

Returns:

Returns the capacity of the in memory pool