Package sonia.scm.migration

package sonia.scm.migration

This package holds classes for data migrations between different versions of SCM-Manager or its plugins. The central classes for this are UpdateStep and RepositoryUpdateStep. Implementations of these classes tell, what data they migrate (UpdateStepTarget.getAffectedDataType()) and to what version this data type is migrated (UpdateStepTarget.getTargetVersion()).

The data type provided by UpdateStepTarget.getAffectedDataType() can be an arbitrary string, but it is considered a best practice to use a qualified name, for example

• com.example.myPlugin.configuration for data in plugins, or
• com.cloudogu.scm.repository for core data structures.

The version provided by UpdateStepTarget.getTargetVersion() is unrelated to other versions and therefore can be chosen freely, so that a data type can be updated without in various ways independent of other data types or the official version of the plugin or the core. A coordination between different data types and their versions is only necessary, when update steps of different data types rely on each other. If a update step of data type A has to run before another step for data type B, the version number of the second step has to be greater in regards to Version.compareTo(Version).

The algorithm looks something like this:
Whenever the SCM-Manager starts,

• it creates a so called bootstrap guice context, that contains
  • a KeyGenerator,
  • the RepositoryLocationResolver,
  • an RepositoryUpdateIterator,
  • the FileSystem,
  • the CipherHandler,
  • a ConfigurationStoreFactory,
  • a ConfigurationEntryStoreFactory,
  • a DataStoreFactory,
  • a BlobStoreFactory, and
  • the PluginLoader.
  Mind, that there are no DAOs, Managers or the like available at this time!
• It then checks whether there are instances of this interface that have not run before, that is either
  • their version number given by UpdateStepTarget.getTargetVersion() is bigger than the last recorded target version of an executed update step for the data type given by UpdateStepTarget.getAffectedDataType(), or
  • there is no version number known for the given data type.
  These are the relevant update steps.
• These relevant update steps are then sorted ascending by their target version given by UpdateStepTarget.getTargetVersion().
• Finally, these sorted steps are executed one after another calling UpdateStep.doUpdate() of each global step and RepositoryUpdateStep.doUpdate(sonia.scm.migration.RepositoryUpdateContext) for each repository for repository specific update steps, updating the version for the data type accordingly (if there are both global and repository specific update steps for a data type and target version, the global step is called first).
• If all works well, SCM-Manager then creates the runtime guice context by loading all further modules.
• If any of the update steps fails, the whole process is interrupted and SCM-Manager will not start up and will not record the version number of this update step.

Mind that an implementation of this class has to be annotated with Extension, so that the step will be found.

Related Packages

Package	Description
sonia.scm	Base classes and interfaces of the SCM-Manager.

Class	Description
MigrationDAO
MigrationInfo
NamespaceUpdateContext	Data for the namespace, whose data that should be migrated.
NamespaceUpdateStep	This is the main interface for "namespace specific" data migration/update.
RepositoryUpdateContext	Data for the repository, whose data that should be migrated.
RepositoryUpdateStep	This is the main interface for "repository specific" data migration/update.
UpdateException
UpdateStep	This is the main interface for "global" data migration/update.
UpdateStepTarget	Base class for update steps, telling the target version and the affected data type.