Package de.xima.fc.persistence.system

Interface SystemPersistenceManager

All Known Implementing Classes:

SystemPersistenceManagerImpl

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

PERSISTENCE_UNIT_NAME

static final String PERSISTENCE_UNIT_NAME

See Also:

Constant Field Values

Method Detail

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.

The transaction stands alone: nothing takes part in it, so work done by anything this caller calls is committed or rolled back separately from it. Use the JpaTransactionRunner (or @JpaTransactional) for a transaction that other units of work take part in. Opening one while a unit of work is running is logged as a warning.

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.