org.openmrs.util

Class DatabaseUpdater

java.lang.Object

org.openmrs.util.DatabaseUpdater

public class DatabaseUpdater
extends java.lang.Object

This class uses Liquibase to update the database.

See /metadata/model/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 interface	DatabaseUpdater.ChangeSetExecutorCallback Interface used for callbacks when updating the database.
static class	DatabaseUpdater.OpenMRSChangeSet Represents each change in the liquibase-update-to-latest

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DATABASE_UPDATES_LOG_FILE

Constructor Summary

Constructors

Constructor and Description
DatabaseUpdater()

Method Summary

Modifier and Type	Method and Description
static java.lang.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 void	executeChangelog(java.lang.String changelog, java.util.Map<java.lang.String,java.lang.Object> userInput) Run changesets on database using Liquibase to get the database up to the most recent version
static java.util.List<java.lang.String>	executeChangelog(java.lang.String changelog, java.util.Map<java.lang.String,java.lang.Object> userInput, DatabaseUpdater.ChangeSetExecutorCallback callback) Executes the given changelog file.
static java.util.List<java.lang.String>	executeChangelog(java.lang.String changeLogFile, java.lang.String contexts, java.util.Map<java.lang.String,java.lang.Object> userInput, DatabaseUpdater.ChangeSetExecutorCallback callback) Deprecated. use executeChangelog(String, String, Map, ChangeSetExecutorCallback, ClassLoader)
static java.util.List<java.lang.String>	executeChangelog(java.lang.String changeLogFile, java.lang.String contexts, java.util.Map<java.lang.String,java.lang.Object> userInput, DatabaseUpdater.ChangeSetExecutorCallback callback, java.lang.ClassLoader cl) This code was borrowed from the liquibase jar so that we can call the given callback function.
static java.lang.Integer	getAuthenticatedUserId()
static java.sql.Connection	getConnection() Gets a database connection for liquibase to do the updates
static java.util.List<DatabaseUpdater.OpenMRSChangeSet>	getDatabaseChanges() Looks at the current liquibase-update-to-latest.xml file and then checks the database to see if they have been run.
static java.util.List<DatabaseUpdater.OpenMRSChangeSet>	getUnrunDatabaseChanges()
static java.util.List<DatabaseUpdater.OpenMRSChangeSet>	getUnrunDatabaseChanges(java.lang.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(java.util.List<java.lang.String> warnings) This method is called by an executing custom changeset to register warning messages.
static void	setAuthenticatedUserId(java.lang.Integer userId)
static boolean	updatesRequired() Ask Liquibase if it needs to do any updates.
static boolean	updatesRequired(java.lang.String... changeLogFilenames) Ask Liquibase if it needs to do any updates
static void	writeUpdateMessagesToFile(java.lang.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

DATABASE_UPDATES_LOG_FILE

public static final java.lang.String DATABASE_UPDATES_LOG_FILE

See Also:

Constant Field Values

Constructor Detail

DatabaseUpdater

public DatabaseUpdater()

Method Detail

executeChangelog

public static void executeChangelog()
                             throws DatabaseUpdateException,
                                    InputRequiredException

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

Throws:

InputRequiredException - if the changelog file requirest some sort of user input. The error object will list of the user prompts and type of data for each prompt

DatabaseUpdateException

See Also:

#update(Map), executeChangelog(String, Map)

executeChangelog

public static void executeChangelog(java.lang.String changelog,
                                    java.util.Map<java.lang.String,java.lang.Object> userInput)
                             throws DatabaseUpdateException,
                                    InputRequiredException

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

InputRequiredException

executeChangelog

public static java.util.List<java.lang.String> executeChangelog(java.lang.String changelog,
                                                                java.util.Map<java.lang.String,java.lang.Object> userInput,
                                                                DatabaseUpdater.ChangeSetExecutorCallback callback)
                                                         throws DatabaseUpdateException,
                                                                InputRequiredException

Executes the given changelog file. This file is assumed to be on the classpath. If no file is given, the default CHANGE_LOG_FILE is ran.

Parameters:

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

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

Returns:

A list of messages or warnings generated by the executed changesets

Throws:

InputRequiredException - if the changelog file requirest some sort of user input. The error object will list of the user prompts and type of data for each prompt

DatabaseUpdateException

executeChangelog

@Deprecated
public static java.util.List<java.lang.String> executeChangelog(java.lang.String changeLogFile,
                                                                            java.lang.String contexts,
                                                                            java.util.Map<java.lang.String,java.lang.Object> userInput,
                                                                            DatabaseUpdater.ChangeSetExecutorCallback callback)
                                                                     throws java.lang.Exception

Deprecated. use executeChangelog(String, String, Map, ChangeSetExecutorCallback, ClassLoader)

Throws:

java.lang.Exception

executeChangelog

public static java.util.List<java.lang.String> executeChangelog(java.lang.String changeLogFile,
                                                                java.lang.String contexts,
                                                                java.util.Map<java.lang.String,java.lang.Object> userInput,
                                                                DatabaseUpdater.ChangeSetExecutorCallback callback,
                                                                java.lang.ClassLoader cl)
                                                         throws java.lang.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

userInput - answers given by the user

callback - the function to call after every changeset

cl - ClassLoader to use to find the changeLogFile (or null to use OpenmrsClassLoader)

Returns:

A list of messages or warnings generated by the executed changesets

Throws:

java.lang.Exception

updatesRequired

public static boolean updatesRequired()
                               throws java.lang.Exception

Ask Liquibase if it needs to do any updates. Only looks at the CHANGE_LOG_FILE

Returns:

true/false whether database updates are required

Throws:

java.lang.Exception

updatesRequired

public static boolean updatesRequired(java.lang.String... changeLogFilenames)
                               throws java.lang.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

Throws:

java.lang.Exception

allowAutoUpdate

public static java.lang.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 java.sql.Connection getConnection()
                                         throws java.lang.Exception

Gets a database connection for liquibase to do the updates

Returns:

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

Throws:

java.lang.Exception

getDatabaseChanges

@Authorized(value="View Database Changes")
public static java.util.List<DatabaseUpdater.OpenMRSChangeSet> getDatabaseChanges()
                                                                                                                      throws java.lang.Exception

Looks at the current liquibase-update-to-latest.xml file and then checks the database to see if they have been run.

Returns:

list of changesets that both have and haven't been run

Throws:

java.lang.Exception

getUnrunDatabaseChanges

@Authorized(value="View Database Changes")
public static java.util.List<DatabaseUpdater.OpenMRSChangeSet> getUnrunDatabaseChanges()
                                                                                                                           throws java.lang.Exception

Throws:

java.lang.Exception

See Also:

getUnrunDatabaseChanges(String...)

getUnrunDatabaseChanges

@Authorized(value="View Database Changes")
public static java.util.List<DatabaseUpdater.OpenMRSChangeSet> getUnrunDatabaseChanges(java.lang.String... changeLogFilenames)
                                                                                                                           throws java.lang.Exception

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:

Throws:

java.lang.Exception

getAuthenticatedUserId

public static java.lang.Integer getAuthenticatedUserId()

Returns:

the authenticatedUserId

setAuthenticatedUserId

public static void setAuthenticatedUserId(java.lang.Integer userId)

Parameters:

authenticatedUserId - the authenticatedUserId to set

reportUpdateWarnings

public static void reportUpdateWarnings(java.util.List<java.lang.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(java.lang.String text)

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

Parameters:

the - 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 thats 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