Interface SystemPersistenceManager

public interface SystemPersistenceManager
Interface for managing the persistence layer of the system database. This manager is responsible for providing access to the EntityManagerFactory and DataSource for the system database, as well as handling encryption settings, schema migrations, and other persistence-related operations. It serves as a central point for interacting with the system database and ensures that all operations are performed in a consistent and controlled manner.
Since:
8.5.0
Author:
Michael Kohlsche

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    PERSISTENCE_UNIT_NAME
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    closeEntityManagerFactory()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Will be removed in future versions.
    void
    ensureEncryptionValueExists()
    Ensures that the encryption test value is present and valid in the system database.
    DataSource
    getDataSource()
    Retrieves the DataSource for the system database.
    DataSourceEncryptionState
    getDataSourceEncryptionState(ConnectionProperties connectionProperties, char[] password, String encryptionAlgorithm)
    Checks the encryption state of the data source defined by the given connection properties.
    IDataSourceInfo
    getDataSourceInfo()
    Retrieves information about the system data source, such as database type, version, encryption settings, and other metadata.
    javax.persistence.EntityManagerFactory
    getEntityManagerFactory()
    Retrieves the EntityManagerFactory for of the system database.
    static SystemPersistenceManager
    getInstance()
    Retrieves the singleton instance of the
    void
    migrateEncryption(char[] newEncryptionPassword, String newEncryptionAlgorithm, Set<String> additionalEncryptionScopes)
    Migrates the encryption of the system data source to use a new encryption password and algorithm.
    void
    migrateSchema()
    Updates the schema of the system database to the latest version.
    void
    openEntityManagerFactory()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Will be removed in future versions.
    IJpaTransaction
    openTransaction()
    Opens a new JPA transaction for the system database.
    void
    reloadEncryptionSettings()
    Reloads the encryption settings for the system data source.
    void
    reloadEntityManagerFactory()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Will be removed in future versions.
    void
    resume()
    Resumes the system persistence layer after it has been suspended.
    void
    suspend()
    Suspends the system persistence layer, releasing any resources held by the EntityManagerFactory and DataSource.

  • Field Details

  • Method Details

    • getInstance

      static SystemPersistenceManager getInstance()
      Retrieves the singleton instance of the
      Returns:
      the singleton instance of SystemPersistenceManager
      Throws:
      IllegalStateException - if the CDI container is not available or the bean cannot be found

    • migrateEncryption

      void migrateEncryption(char[] newEncryptionPassword, String newEncryptionAlgorithm, Set<String> additionalEncryptionScopes) throws FcPersistenceException
      Migrates the encryption of the system data source to use a new encryption password and algorithm. This method should be used when changing the encryption settings for the system database. It reads all encrypted data with the old settings and re-encrypts it using the new settings.
      Parameters:
      newEncryptionPassword - the new encryption password to be used
      newEncryptionAlgorithm - the new encryption algorithm to be used
      additionalEncryptionScopes - optional scopes for encryption; can be null or empty; if null, only unscoped data will be re-encrypted. If not null, data with the specified scopes will also be re-encrypted. Example scope: "form" for form data encryption.
      Throws:
      FcPersistenceException - f there is an error during the migration process

    • reloadEncryptionSettings

      void reloadEncryptionSettings() throws FcPersistenceException
      Reloads the encryption settings for the system data source. This method should be called after changing the encryption settings (e.g., password, algorithm) to ensure that the new settings are applied and used for all subsequent database operations. This may involve reinitializing the DataSource and EntityManagerFactory to use the updated encryption configuration.
      Throws:
      FcPersistenceException - if there is an error related to the persistence layer while reloading the encryption settings, such as if the DataSource cannot be reinitialized with the new settings or if there is an error related to the database driver

    • migrateSchema

      void migrateSchema() throws SchemaMigrationException
      Updates the schema of the system database to the latest version.
      Throws:
      SchemaMigrationException - if there is an error during the schema migration process

    • ensureEncryptionValueExists

      void ensureEncryptionValueExists() throws FcPersistenceException
      Ensures that the encryption test value is present and valid in the system database.
      Throws:
      IllegalStateException - if the encryption value is missing or invalid
      FcPersistenceException - if there is an error related to the persistence layer while checking the encryption value

    • getEntityManagerFactory

      javax.persistence.EntityManagerFactory getEntityManagerFactory() throws FcPersistenceException
      Retrieves the EntityManagerFactory for of the system database. The returned EntityManagerFactory is managed by this manager and should not be closed by the caller.
      Returns:
      the EntityManagerFactory for the system database
      Throws:
      IllegalStateException - if the EntityManagerFactory cannot be created // * @throws FcDriverException if there is an error related to the database driver
      FcPersistenceException

    • openTransaction

      IJpaTransaction openTransaction() throws FcPersistenceException
      Opens a new JPA transaction for the system database. The returned IJpaTransaction represents a transaction context that must be closed by the caller to commit or roll back the transaction.
      Returns:
      a new IJpaTransaction for the system database
      Throws:
      IllegalStateException - if the entity manager is not open
      FcDriverException - if there is an error related to the database driver
      FcPersistenceException

    • getDataSource

      DataSource getDataSource() throws FcPersistenceException
      Retrieves the DataSource for the system database. The returned DataSource is managed by this manager (and underlying connection pool) and should not be closed by the caller.
      Returns:
      the DataSource for the system database
      Throws:
      IllegalStateException - if the system DataSource cannot be created
      FcDriverException - if there is an error related to the database driver
      FcPersistenceException

    • getDataSourceInfo

      IDataSourceInfo getDataSourceInfo() throws FcPersistenceException
      Retrieves information about the system data source, such as database type, version, encryption settings, and other metadata. This information can be used for diagnostics, monitoring, or to make decisions about how to interact with the database based on its capabilities and configuration.
      Returns:
      an IDataSourceInfo object containing metadata about the system data source
      Throws:
      FcPersistenceException - if there is an error while retrieving the data source information, such as if the data source cannot be accessed or if there is an error related to the database driver

    • getDataSourceEncryptionState

      DataSourceEncryptionState getDataSourceEncryptionState(ConnectionProperties connectionProperties, char[] password, String encryptionAlgorithm) throws FcPersistenceException
      Checks the encryption state of the data source defined by the given connection properties. This method verifies whether the encryption settings (password, algorithm) match those used to encrypt the data in the database.
      Parameters:
      connectionProperties - the connection properties defining the data source to check
      password - the password to check against the system data source encryption
      encryptionAlgorithm - the encryption algorithm to check against the system data source encryption
      Returns:
      the encryption state of the system data source
      Throws:
      IllegalArgumentException - if the password is null or empty
      IllegalStateException - if the system DataSource cannot be accessed
      FcDriverException - if there is an error related to the database driver
      FcPersistenceException

    • suspend

      void suspend()
      Suspends the system persistence layer, releasing any resources held by the EntityManagerFactory and DataSource. This method should be called before performing operations that require exclusive access to the database, such as schema migrations or encryption changes. After the necessary operations are completed, the resume() method should be called to reinitialize the persistence layer.

    • resume

      void resume()
      Resumes the system persistence layer after it has been suspended. This method triggers a system persistence layer check which will fire appropriate events to reinitialize the EntityManagerFactory and DataSource if they were released during suspension. This method should be called after performing operations that required exclusive access to the database, such as schema migrations or encryption changes, to restore the normal operation of the persistence layer.

    • reloadEntityManagerFactory

      @Deprecated(forRemoval=true) void reloadEntityManagerFactory()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Will be removed in future versions. Use suspend() instead to suspend the persistence context and resume() to resume it.

    • closeEntityManagerFactory

      @Deprecated(forRemoval=true) void closeEntityManagerFactory()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Will be removed in future versions. Use suspend() instead to suspend the persistence context and resume() to resume it.

    • openEntityManagerFactory

      @Deprecated(forRemoval=true) void openEntityManagerFactory()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Will be removed in future versions. Use suspend() instead to suspend the persistence context and resume() to resume it.