er.extensions.migration

Class ERXMigrator

java.lang.Object

er.extensions.migration.ERXMigrator

public class ERXMigrator
extends Object

ERXMigrator provides a simple mechanism for performing database migrations (both upgrading and downgrading).

To have ERXMigrator run at the start of your application, set er.migration.migrateAtStartup = true. This will perform a migration of your EOModels using a series of provided migration classes. By default, models are migrated in the order they appear in the EOModelGroup (that is, effectively random). If you want more control over the order at startup, you can set the er.migration.modelNames property to a comma-separate list of model names. The migrator will migrate them in this order.

For each EOModel, the migrator will lookup [modelName].MigrationClassPrefix and then append version numbers to that name. For instance, if your model named "AuthModel" is being migrated, and you set AuthModel.MigrationClassPrefix=com.mdimension.migration.AuthModel, it will then look for classes named like com.mdimension.migration.AuthModel0, com.mdimension.migration.AuthModel1, etc where the number corresponds to a zero-offset migration version. If MigrationClassPrefix is not set, the migrator will assume the prefix is simply the name of the model. Migration classes are resolved like WOComponents (i.e. packageless by name).

The com.mdimension.migration.AuthModelX classes should implement the IERXMigration interface, and should at least provide an implementation of the upgrade method. If you do not provide a downgrade method, you should throw ERXMigrationFailedException when that method is called to notify the system that the requested migration cannot be performed. As an example, AuthModel1.upgrade(..) will be called to move from version 1 to version 2, and AuthModel1.downgrade(..) will be called to move from version 2 back to version 1. Your lowest version number migration should throw an ERXMigrationFailedException when its downgrade method is called.

Because of complications with database locking, the system will not autocreate tables and per-model rows for you, so if you are using JDBC migration, you should create a table named _DBUpdater with the following (approximately) create statement:

               create table _dbupdater (
                 modelname varchar(100) not null,
                 version integer not null,
                 updatelock integer not null,
                 lockowner varchar(100)
               )
 

and for each model you want to be able to migrate, you should:

               insert into _dbupdater(modelname, version, updatelock, lockowner) values ('YourModelName', -1, 0, NULL)
 

Be aware that not all databases are able to perform DDL operations in a transaction. The result of this is that if a DDL operation fails, your database may be left in an unknown state because the subsequent rollback will fail. Version numbers only increase when each migration completes sucessfully, so in this case, your migration version would be left at the previous version number.

Startup migration runs in response to the ApplicationWillFinishLaunchingNotification, so you should not access your EO's until after that notification is complete. ApplicationWillFinishLaunchingNotification is used instead of ApplicationDidFinishLaunchingNotification so that the application will not start accepting requests before migration is complete.

If you are not extending ERXApplication, you can add Migrations into your own application by adding this to your Application constructor:

 NSNotificationCenter.defaultCenter().addObserver(this, 
     new NSSelector("willFinishLaunching", ERXConstant.NotificationClassArray), 
     WOApplication.ApplicationWillFinishLaunchingNotification, null);
 

And implementing the willFinishLaunching method like this:

 public void willFinishLaunching(NSNotification n) {
     if (ERXMigrator.shouldMigrateAtStartup()) {
         new ERXMigrator(name() + "-" + number()).migrateToLatest();
     }
 }
 

Author:

mschrag

Properties

Name	Description
er.migration.migrateAtStartup	if true, migrateToLatest is automatically called at startup
er.migration.[adaptorName].lockClassName	the name of the IERXMigrationLock class to use (defaults to er.extensions.migration.ERX[adaptorName]MigrationLock)
er.migration.modelNames	a comma-separated list of model names to be migrated in a particular order. If missing, it will default to modelgroup.models() order.
er.migration.skipModelNames	a comma-separated list of model names to NOT be migrated.
[modelName].MigrationClassPrefix	the prefix of the class name to use to upgrade the model named [modelName]. Defaults to [modelName].

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	ERXMigrator.ERXMigrationAction

Field Summary

Fields

Modifier and Type	Field and Description
static int	LATEST_VERSION Symbolic version number for migrating to "the latest" version.

Constructor Summary

Constructors

Constructor and Description
ERXMigrator(String lockOwnerName) Constructs an ERXMigrator with the given lock owner.

Method Summary

Modifier and Type	Method and Description
protected void	_buildDependenciesForModel(EOModel model, int migrateToVersion, Map<String,Integer> versions, Map<IERXMigration,ERXModelVersion> migrations, NSArray<String> skipModelNames)
protected Map<IERXMigration,ERXModelVersion>	_buildDependenciesForModelsNamed(NSArray<String> modelNames, NSArray<String> skipModelNames)
protected boolean	canMigrateModel(EOModel model)
protected IERXMigrationLock	databaseLockForModel(EOModel model)
void	migrateToLatest() Migrates all models specified in the default model group to the latest versions.
protected EOEditingContext	newEditingContext() Subclasses can override this to return a different editing context.
static boolean	shouldMigrateAtStartup() Returns whether or not migration should run at startup.

Methods inherited from class java.lang.Object

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

Field Detail

LATEST_VERSION

public static final int LATEST_VERSION

Symbolic version number for migrating to "the latest" version.

See Also:

Constant Field Values

Constructor Detail

ERXMigrator

public ERXMigrator(String lockOwnerName)

Constructs an ERXMigrator with the given lock owner. For an application, the lock owner name defaults to appname-instancenumber.

Parameters:

lockOwnerName - the name of the lock owner

Method Detail

shouldMigrateAtStartup

public static boolean shouldMigrateAtStartup()

Returns whether or not migration should run at startup. Defaults to false.

Returns:

return true if migrations should run at startup

migrateToLatest

public void migrateToLatest()

Migrates all models specified in the default model group to the latest versions.

Throws:

IllegalAccessException

InstantiationException

databaseLockForModel

protected IERXMigrationLock databaseLockForModel(EOModel model)

_buildDependenciesForModelsNamed

protected Map<IERXMigration,ERXModelVersion> _buildDependenciesForModelsNamed(NSArray<String> modelNames,
                                                                              NSArray<String> skipModelNames)

canMigrateModel

protected boolean canMigrateModel(EOModel model)

_buildDependenciesForModel

protected void _buildDependenciesForModel(EOModel model,
                                          int migrateToVersion,
                                          Map<String,Integer> versions,
                                          Map<IERXMigration,ERXModelVersion> migrations,
                                          NSArray<String> skipModelNames)
                                   throws InstantiationException,
                                          IllegalAccessException

Throws:

InstantiationException

IllegalAccessException

newEditingContext

protected EOEditingContext newEditingContext()

Subclasses can override this to return a different editing context.

Returns:

EOEditingContext to be used for migration