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

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

static java.lang.String

DATABASE_UPDATES_LOG_FILE

Constructor Summary

DatabaseUpdater()

Method Summary

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() Looks at the current liquibase-update-to-latest.xml file returns all changesets in that file that have not been run on the database yet.
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 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

Returns:

true/false whether database updates are required

Throws:

java.lang.Exception

Expected behavior:

always have a valid update to latest file

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

Looks at the current liquibase-update-to-latest.xml file returns all changesets in that file that have not been run on the database yet.

Returns:

list of changesets that haven't been run

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