Class Sparksee

java.lang.Object
com.sparsity.sparksee.gdb.Sparksee
All Implemented Interfaces:
Closeable, AutoCloseable
public class Sparksee extends Object implements 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 Details

    • Version

      public static String Version
      Sparksee version.

      Sparksee version.

  • Constructor Details

    • Sparksee

      public Sparksee(SparkseeConfig config)
      Creates a new instance.

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

  • Method Details

    • restoreEncryptedBackup

      public Database restoreEncryptedBackup(String path, String backupFile, SparkseeConfig config, String keyInHex, String ivInHex) throws RuntimeException, FileNotFoundException
      Restores a Database from an encrypted backup file.

      See the Graph class EncryptedBackup method. Errorfor other issues.

      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:
      RuntimeException - null
      FileNotFoundException - If the given file cannot be created, or the exported data file does not exists.

    • resizeInMemoryPool

      public void resizeInMemoryPool(long newCapacity) throws RuntimeException
      Resizes the in memory pool allocator.

      sparksee::gdb::SystemError

      Parameters:
      newCapacity - The new capacity of the in memory pool allocator
      Throws:
      RuntimeException - null

    • create

      public Database create(String path, String alias, SparkseeConfig config) throws RuntimeException, FileNotFoundException
      Creates a new Database instance.

      Errorfor other issues.

      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:
      RuntimeException - null
      FileNotFoundException - If the given file cannot be created.

    • verifyChecksums

      public boolean verifyChecksums(String path) throws RuntimeException, 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:
      RuntimeException - null
      FileNotFoundException - null

    • removeChecksums

      public boolean removeChecksums(String path) throws RuntimeException, 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:
      RuntimeException - null
      FileNotFoundException - null

    • restore

      public Database restore(String path, String backupFile) throws RuntimeException, FileNotFoundException
      Restores a Database from a backup file.

      See the Graph class Backup method. Errorfor other issues.

      Parameters:
      path - [in] Database storage file.
      backupFile - [in] The Backup file to be restored.
      Returns:
      A Database instance.
      Throws:
      RuntimeException - null
      FileNotFoundException - If the given file cannot be created, or the exported data file does not exists.

    • addChecksums

      public boolean addChecksums(String path) throws RuntimeException, 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:
      RuntimeException - null
      FileNotFoundException - null

    • rebuildDatabase

      public void rebuildDatabase(String path, SparkseeConfig config, boolean minimizeDisk) throws RuntimeException, FileNotFoundException
      Rebuild the database from scratch with the same data.

      It will create a new database on the same file with the same data but rebuilt from scratch, so the internal OIDs may change and the storage usage may be compacted.

      It's the equivalent to extract a backup of the data and restore it. This operation can take a long time and the result file should be smaller than the original if there had been data removals or the data was not loaded in the most optimal order. But the file size could also end up being slightly bigger the the original in some cases (the data creation in the database was optimal and nothing had beed removed).

      WARNING: If anything goes wrong while the database is being rebuilt you may lose the database. The data should not be lost, but it may require an additional process to recover it.

      To avoid data loss, the next open after a failed rebuild operation will attempt to automatically recover the database by the fastest solution available (restoring the original file, finishing the almost completed rebuild or restoring a backup).

      The source database is also kept until the rebuilt database is available to reduce the recovery time after a rebuild failure and avoid data loss risks. But if reducing the temporary disk usage is more important, you can use the minimizeDisk to delete it as soon as possible instead.

      The final rebuilt database size will be the same whether you use the minimizeDisk argument or not.

      Parameters:
      path - [In] The Sparksee database to rebuild.
      config - [in] Use a specific configuration instead of the one in this Sparksee.
      minimizeDisk - [in] Use less temporary disk space.
      Throws:
      RuntimeException - null
      FileNotFoundException - null

    • restoreEncryptedBackup

      public Database restoreEncryptedBackup(String path, String backupFile, String keyInHex, String ivInHex) throws RuntimeException, FileNotFoundException
      Restores a Database from an encrypted backup file.

      See the Graph class EncryptedBackup method. Errorfor other issues.

      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:
      RuntimeException - null
      FileNotFoundException - If the given file cannot be created, or the exported data file does not exists.

    • decrypt

      public boolean decrypt(String path) throws RuntimeException, 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:
      RuntimeException - null
      FileNotFoundException - null

    • restore

      public Database restore(String path, String backupFile, SparkseeConfig config) throws RuntimeException, FileNotFoundException
      Restores a Database from a backup file.

      See the Graph class Backup method. Errorfor other issues.

      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:
      RuntimeException - null
      FileNotFoundException - If the given file cannot be created, or the exported data file does not exists.

    • create

      public Database create(String path, String alias) throws RuntimeException, FileNotFoundException
      Creates a new Database instance.

      Errorfor other issues.

      Parameters:
      path - [in] Database storage file.
      alias - [in] Database alias name.
      Returns:
      A Database instance.
      Throws:
      RuntimeException - null
      FileNotFoundException - If the given file cannot be created.

    • open

      public Database open(String path, boolean readOnly) throws RuntimeException, FileNotFoundException
      Opens an existing Database instance.

      Errorfor other issues.

      Parameters:
      path - [in] Database storage file.
      readOnly - [in] If TRUE, open Database in read-only mode.
      Returns:
      A Database instance.
      Throws:
      RuntimeException - null
      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:

    • open

      public Database open(String path, boolean readOnly, SparkseeConfig config) throws RuntimeException, 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. Errorfor other issues.

      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:
      RuntimeException - null
      FileNotFoundException - If the given file does not exist.

    • encrypt

      public boolean encrypt(String path) throws RuntimeException, FileNotFoundException
      Converts a database WITHOUT encryption into an encrypted database.

      Any error found is logged. The database (and it's recovery log if present) 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:
      RuntimeException - null
      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 AutoCloseable
      Specified by:
      close in interface Closeable

    • getInMemoryPoolCapacity

      public long getInMemoryPoolCapacity()
      Gets the capacity of the in-memory pool (in Megabytes).

      Returns:
      Returns the capacity of the in memory pool