org.openmrs.util

Class DatabaseUpdater

java.lang.Object

org.openmrs.util.DatabaseUpdater

public class DatabaseUpdater
extends Object

This class uses Liquibase to update the database.

See src/main/resources/liquibase-update-to-latest.xml for the changes. This class will also run arbitrary liquibase xml files on the associated database as well. Details for the database are taken from the openmrs runtime properties.

Since:

1.5

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DatabaseUpdater.OpenMRSChangeSet Represents each change in the files referenced by liquibase-update-to-latest

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONTEXT
static String	DATABASE_UPDATES_LOG_FILE

Constructor Summary

Constructors

Constructor and Description
DatabaseUpdater()

Method Summary

Modifier and Type	Method and Description
static Boolean	allowAutoUpdate() Indicates whether automatic database updates are allowed by this server.
static void	executeChangelog() Convenience method to run the changesets using Liquibase to bring the database up to a version compatible with the code
static List<String>	executeChangelog(String changelog, ChangeSetExecutorCallback callback) Executes the given changelog file.
static List<String>	executeChangelog(String changeLogFile, liquibase.Contexts contexts, ChangeSetExecutorCallback callback, ClassLoader cl) This code was borrowed from the liquibase jar so that we can call the given callback function.
static void	executeChangelog(String changelog, Map<String,Object> userInput) Deprecated. as of 2.4 see executeChangelog(String, ChangeSetExecutorCallback)
static Integer	getAuthenticatedUserId()
static Connection	getConnection() Gets a database connection for liquibase to do the updates
static List<DatabaseUpdater.OpenMRSChangeSet>	getDatabaseChanges() Returns all change sets defined by (a) the Liquibase snapshot files that had been used to initialise the OpenMRS database and (b) the Liquibase update files that that are applicable on top of the snapshot version.
static List<DatabaseUpdater.OpenMRSChangeSet>	getUnrunDatabaseChanges(LiquibaseProvider liquibaseProvider) Returns a list of Liquibase change sets were not run yet.
static List<DatabaseUpdater.OpenMRSChangeSet>	getUnrunDatabaseChanges(String... changeLogFilenames) Looks at the specified liquibase change log files and returns all changesets in the files that have not been run on the database yet.
static boolean	isLocked() This method currently checks the liquibasechangeloglock table to see if there is a row with a lock in it.
static void	releaseDatabaseLock() This method releases the liquibase db lock after a crashed database update.
static void	reportUpdateWarnings(List<String> warnings) This method is called by an executing custom changeset to register warning messages.
static void	setAuthenticatedUserId(Integer userId)
static boolean	updatesRequired() Ask Liquibase if it needs to do any updates.
static boolean	updatesRequired(String... changeLogFilenames) Ask Liquibase if it needs to do any updates
static void	writeUpdateMessagesToFile(String text) This method writes the given text to the database updates log file located in the application data directory.

Methods inherited from class java.lang.Object

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

Field Detail

CONTEXT

public static final String CONTEXT

See Also:

Constant Field Values

DATABASE_UPDATES_LOG_FILE

public static final String DATABASE_UPDATES_LOG_FILE

See Also:

Constant Field Values

Constructor Detail

DatabaseUpdater

public DatabaseUpdater()

Method Detail

executeChangelog

public static void executeChangelog()
                             throws DatabaseUpdateException

Convenience method to run the changesets using Liquibase to bring the database up to a version compatible with the code

Throws:

DatabaseUpdateException

executeChangelog

@Deprecated
public static void executeChangelog(String changelog,
                                                Map<String,Object> userInput)
                                         throws DatabaseUpdateException

Deprecated. as of 2.4 see executeChangelog(String, ChangeSetExecutorCallback)

Run changesets on database using Liquibase to get the database up to the most recent version

Parameters:

changelog - the liquibase changelog file to use (or null to use the default file)

userInput - nullable map from question to user answer. Used if a call to update(null) threw an InputRequiredException

Throws:

DatabaseUpdateException - if an error occurs

executeChangelog

public static List<String> executeChangelog(String changelog,
                                            ChangeSetExecutorCallback callback)
                                     throws DatabaseUpdateException

Executes the given changelog file. This file is assumed to be on the classpath.

Parameters:

changelog - The string filename of a liquibase changelog xml file to run

Returns:

A list of messages or warnings generated by the executed changesets

Throws:

DatabaseUpdateException

executeChangelog

public static List<String> executeChangelog(String changeLogFile,
                                            liquibase.Contexts contexts,
                                            ChangeSetExecutorCallback callback,
                                            ClassLoader cl)
                                     throws Exception

This code was borrowed from the liquibase jar so that we can call the given callback function.

Parameters:

changeLogFile - the file to execute

contexts - the liquibase changeset context

callback - the function to call after every changeset

Returns:

A list of messages or warnings generated by the executed changesets

Throws:

Exception

updatesRequired

public static boolean updatesRequired()
                               throws Exception

Ask Liquibase if it needs to do any updates.

Returns:

true/false whether database updates are required

Throws:

Exception - when an exception is raised while processing Liquibase changelog files

updatesRequired

public static boolean updatesRequired(String... changeLogFilenames)
                               throws Exception

Ask Liquibase if it needs to do any updates

Parameters:

changeLogFilenames - the filenames of all files to search for unrun changesets

Returns:

true/false whether database updates are required Should always have a valid update to latest file

Throws:

Exception

allowAutoUpdate

public static Boolean allowAutoUpdate()

Indicates whether automatic database updates are allowed by this server. Automatic updates are disabled by default. In order to enable automatic updates, the admin needs to add 'auto_update_database=true' to the runtime properties file.

Returns:

true/false whether the 'auto_update_database' has been enabled.

getConnection

public static Connection getConnection()
                                throws Exception

Gets a database connection for liquibase to do the updates

Returns:

a java.sql.connection based on the current runtime properties

Throws:

Exception

getDatabaseChanges

public static List<DatabaseUpdater.OpenMRSChangeSet> getDatabaseChanges()
                                                                 throws Exception

Returns all change sets defined by (a) the Liquibase snapshot files that had been used to initialise the OpenMRS database and (b) the Liquibase update files that that are applicable on top of the snapshot version.

Returns:

list of change sets that both have and haven't been run

Throws:

Exception

getUnrunDatabaseChanges

public static List<DatabaseUpdater.OpenMRSChangeSet> getUnrunDatabaseChanges(LiquibaseProvider liquibaseProvider)
                                                                      throws Exception

Returns a list of Liquibase change sets were not run yet.

Parameters:

liquibaseProvider - provides access to a Liquibase instance

Returns:

list of change sets that were not run yet.

Throws:

Exception

getUnrunDatabaseChanges

public static List<DatabaseUpdater.OpenMRSChangeSet> getUnrunDatabaseChanges(String... changeLogFilenames)

Looks at the specified liquibase change log files and returns all changesets in the files that have not been run on the database yet. If no argument is specified, then it looks at the current liquibase-update-to-latest.xml file

Parameters:

changeLogFilenames - the filenames of all files to search for unrun changesets

Returns:

list of change sets

getAuthenticatedUserId

public static Integer getAuthenticatedUserId()

Returns:

the authenticatedUserId

setAuthenticatedUserId

public static void setAuthenticatedUserId(Integer userId)

Parameters:

userId - the authenticatedUserId to set

reportUpdateWarnings

public static void reportUpdateWarnings(List<String> warnings)

This method is called by an executing custom changeset to register warning messages.

Parameters:

warnings - list of warnings to append to the end of the current list

writeUpdateMessagesToFile

public static void writeUpdateMessagesToFile(String text)

This method writes the given text to the database updates log file located in the application data directory.

Parameters:

text - text to be written to the file

releaseDatabaseLock

public static void releaseDatabaseLock()
                                throws liquibase.exception.LockException

This method releases the liquibase db lock after a crashed database update. First, it checks whether "liquibasechangeloglock" table exists in db. If so, it will check whether the database is locked. If that is also true, this means that last attempted db update crashed.

This should only be called if the user is sure that no one else is currently running database updates. This method should be used if there was a db crash while updates were being written and the lock table was never cleaned up.

Throws:

liquibase.exception.LockException

isLocked

public static boolean isLocked()

This method currently checks the liquibasechangeloglock table to see if there is a row with a lock in it. This uses the liquibase API to do this

Returns:

true if database is currently locked