org.unitils.dbmaintainer
Class DBMaintainer

java.lang.Object
  org.unitils.dbmaintainer.DBMaintainer

public class DBMaintainer
extends Object

A class for performing automatic maintenance of a database.
This class must be configured with implementations of a ExecutedScriptInfoSource, ScriptSource, a ScriptRunner, DBClearer, DBCleaner, ConstraintsDisabler, SequenceUpdater and a DataSetStructureGenerator

The updateDatabase() method check what is the current version of the database, and see if existing scripts have been modified. If yes, the database is cleared and all available database scripts, are executed on the database. If no existing scripts have been modified, but new scripts were added, only the new scripts are executed. Before executing an update, data from the database is removed, to avoid problems when e.g. adding a not null column.

If a database update causes an error, a UnitilsException is thrown. After a failing update, the database is always completely recreated from scratch.

After updating the database, following steps are optionally executed on the database (depending on the configuration):

• Foreign key and not null constraints are disabled.
• Sequences and identity columns that have a value lower than a configured treshold, are updated to a value equal to or larger than this treshold
• A DTD is generated that describes the database's table structure, to use in test data XML files

To obtain a properly configured DBMaintainer, invoke the constructor DBMaintainer(Properties,SQLHandler) with a TestDataSource providing access to the database and a Configuration object containing all necessary properties.

Author:

Filip Neven, Tim Ducheyne

Field Summary

protected ConstraintsDisabler	constraintsDisabler Disabler of constraints
protected DataSetStructureGenerator	dataSetStructureGenerator Database DTD generator
protected DBCleaner	dbCleaner Cleaner of the database (deletes all data from all tables before updating
protected DBClearer	dbClearer Clearer of the database (removed all tables, sequences, ...) before updating
protected boolean	disableConstraintsEnabled Indicates if foreign key and not null constraints should removed after updating the database structure
protected boolean	fromScratchEnabled Indicates whether updating the database from scratch is enabled.
protected boolean	keepRetryingAfterError Indicates whether a from scratch update should be performed when the previous update failed, but none of the scripts were modified since that last update.
static String	PROPKEY_CLEAR_DB_CODE_ENABLED Property indicating if database code should be cleared before installing a new version of the code or when updating the database from scratch
static String	PROPKEY_DB_CLEANER_ENABLED Property indicating if deleting all data from all tables before updating is enabled
static String	PROPKEY_DISABLE_CONSTRAINTS_ENABLED Property indicating if the database constraints should org disabled after updating the database
static String	PROPKEY_FROM_SCRATCH_ENABLED Property indicating if updating the database from scratch is enabled
static String	PROPKEY_GENERATE_DATA_SET_STRUCTURE_ENABLED Property that indicates if a data set DTD or XSD is to be generated or not
static String	PROPKEY_KEEP_RETRYING_AFTER_ERROR_ENABLED Property indicating if an retry of an update should only be performed when changes to script files were made
static String	PROPKEY_UPDATE_SEQUENCES_ENABLED Property indicating if the database constraints should org disabled after updating the database
protected ScriptRunner	scriptRunner Executer of the scripts
protected ScriptSource	scriptSource Provider of scripts for updating the database to a higher version
protected SequenceUpdater	sequenceUpdater Database sequence updater
protected ExecutedScriptInfoSource	versionSource Provider of the current version of the database, and means to increment it

Constructor Summary

protected	DBMaintainer() Default constructor for testing.
	DBMaintainer(Properties configuration, SQLHandler sqlHandler) Create a new instance of DBMaintainer, The concrete implementations of all helper classes are derived from the given Configuration object.

Method Summary

protected boolean	errorInIndexedScriptDuringLastUpdate(Set<ExecutedScript> alreadyExecutedScripts)
protected void	executePostProcessingScripts(List<Script> postProcessingScripts) Executes the given post processing scripts on the database.
protected void	executeScripts(List<Script> scripts) Executes the given scripts and updates the database version and state appropriatly.
protected Version	getHighestExecutedScriptVersion(Set<ExecutedScript> executedScripts)
void	resetDatabaseState() Updates the database version to the current version of the update scripts, without changing anything else in the database.
protected boolean	shouldUpdateDatabaseFromScratch(Version currentVersion, Set<ExecutedScript> alreadyExecutedScripts) Checks whether the database should be updated from scratch or just incrementally.
void	updateDatabase() Checks if the new scripts are available to update the version of the database.
protected void	updateDatabase(List<Script> scripts) Updates the state of the database using the given scripts.

Methods inherited from class java.lang.Object

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

Field Detail

PROPKEY_DB_CLEANER_ENABLED

public static final String PROPKEY_DB_CLEANER_ENABLED

Property indicating if deleting all data from all tables before updating is enabled

See Also:

Constant Field Values

PROPKEY_FROM_SCRATCH_ENABLED

public static final String PROPKEY_FROM_SCRATCH_ENABLED

Property indicating if updating the database from scratch is enabled

See Also:

Constant Field Values

PROPKEY_CLEAR_DB_CODE_ENABLED

public static final String PROPKEY_CLEAR_DB_CODE_ENABLED

Property indicating if database code should be cleared before installing a new version of the code or when updating the database from scratch

See Also:

Constant Field Values

PROPKEY_KEEP_RETRYING_AFTER_ERROR_ENABLED

public static final String PROPKEY_KEEP_RETRYING_AFTER_ERROR_ENABLED

Property indicating if an retry of an update should only be performed when changes to script files were made

See Also:

Constant Field Values

PROPKEY_DISABLE_CONSTRAINTS_ENABLED

public static final String PROPKEY_DISABLE_CONSTRAINTS_ENABLED

Property indicating if the database constraints should org disabled after updating the database

See Also:

Constant Field Values

PROPKEY_UPDATE_SEQUENCES_ENABLED

public static final String PROPKEY_UPDATE_SEQUENCES_ENABLED

Property indicating if the database constraints should org disabled after updating the database

See Also:

Constant Field Values

PROPKEY_GENERATE_DATA_SET_STRUCTURE_ENABLED

public static final String PROPKEY_GENERATE_DATA_SET_STRUCTURE_ENABLED

Property that indicates if a data set DTD or XSD is to be generated or not

See Also:

Constant Field Values

versionSource

protected ExecutedScriptInfoSource versionSource

Provider of the current version of the database, and means to increment it

scriptSource

protected ScriptSource scriptSource

Provider of scripts for updating the database to a higher version

scriptRunner

protected ScriptRunner scriptRunner

Executer of the scripts

dbClearer

protected DBClearer dbClearer

Clearer of the database (removed all tables, sequences, ...) before updating

dbCleaner

protected DBCleaner dbCleaner

Cleaner of the database (deletes all data from all tables before updating

constraintsDisabler

protected ConstraintsDisabler constraintsDisabler

Disabler of constraints

sequenceUpdater

protected SequenceUpdater sequenceUpdater

Database sequence updater

dataSetStructureGenerator

protected DataSetStructureGenerator dataSetStructureGenerator

Database DTD generator

fromScratchEnabled

protected boolean fromScratchEnabled

Indicates whether updating the database from scratch is enabled. If true, the database is cleared before updating if an already executed script is modified

disableConstraintsEnabled

protected boolean disableConstraintsEnabled

Indicates if foreign key and not null constraints should removed after updating the database structure

keepRetryingAfterError

protected boolean keepRetryingAfterError

Indicates whether a from scratch update should be performed when the previous update failed, but none of the scripts were modified since that last update. If true a new update will be tried only when changes were made to the script files

Constructor Detail

DBMaintainer

protected DBMaintainer()

Default constructor for testing.

DBMaintainer

public DBMaintainer(Properties configuration,
                    SQLHandler sqlHandler)

Create a new instance of DBMaintainer, The concrete implementations of all helper classes are derived from the given Configuration object.

Parameters:

configuration - the configuration, not null

sqlHandler - the data source, not null

Method Detail

updateDatabase

public void updateDatabase()

Checks if the new scripts are available to update the version of the database. If yes, these scripts are executed and the version number is increased. If an existing script has been modified, the database is cleared and completely rebuilt from scratch. If an error occurs with one of the scripts, a UnitilsException is thrown.

getHighestExecutedScriptVersion

protected Version getHighestExecutedScriptVersion(Set<ExecutedScript> executedScripts)

resetDatabaseState

public void resetDatabaseState()

Updates the database version to the current version of the update scripts, without changing anything else in the database. Can be used to initialize the database for future updates, knowning that the current state of the database is synchronized with the current state of the scripts.

updateDatabase

protected void updateDatabase(List<Script> scripts)

Updates the state of the database using the given scripts.

Parameters:

scripts - The scripts, not null

executeScripts

protected void executeScripts(List<Script> scripts)

Executes the given scripts and updates the database version and state appropriatly. After each successful script execution, the new version is stored in the database and marked as succesful. If a script execution fails and fromScratch is enabled, that script version is stored in the database and marked as unsuccesful. If fromScratch is not enabled, the last succesful version is stored in the database that way, the next time an update is tried, the execution restarts from the last unsuccessful script.

Parameters:

scripts - The scripts to execute, not null

executePostProcessingScripts

protected void executePostProcessingScripts(List<Script> postProcessingScripts)

Executes the given post processing scripts on the database. If not successful, the scripts update is registered as not successful, so that an update from scratch will be triggered the next time.

Parameters:

postProcessingScripts - The scripts to execute, not null

shouldUpdateDatabaseFromScratch

protected boolean shouldUpdateDatabaseFromScratch(Version currentVersion,
                                                  Set<ExecutedScript> alreadyExecutedScripts)

Checks whether the database should be updated from scratch or just incrementally. The database needs to be rebuilt in following cases:

• Some existing scripts were modified.
• The last update of the database was unsuccessful.

The database will only be rebuilt from scratch if PROPKEY_FROM_SCRATCH_ENABLED is set to true. If the PROPKEY_KEEP_RETRYING_AFTER_ERROR_ENABLED is set to false, the database will only be rebuilt again after an unsuccessful build when changes were made to the script files.

Parameters:

currentVersion - The current database version, not null

Returns:

True if a from scratch rebuild is needed, false otherwise

errorInIndexedScriptDuringLastUpdate

protected boolean errorInIndexedScriptDuringLastUpdate(Set<ExecutedScript> alreadyExecutedScripts)