ch.jalu.configme.migration.version

Class VersionMigrationService

java.lang.Object

ch.jalu.configme.migration.version.VersionMigrationService

All Implemented Interfaces:

MigrationService

public class VersionMigrationService
extends Object
implements MigrationService

Version-based MigrationService implementation that uses a Property<Integer> to track configuration versions, based on which it triggers migrations. The application's current configuration value is taken from the property's default value, which should be incremented whenever a new migration is desired.

To define a migration, create a new implementation of VersionMigration and provide it to this service's constructor. Ensure that each migration's starting version is unique and valid, and that the target version is not greater than the default value of the version property.

This service triggers migrations and resaves the configuration if the version read from the configuration file is not equal to the version property's default value. Migrations are applied successively from the stored version to the target version of each migration, ensuring proper migration order. For example, if a service has a migration from version 1 to 2, and one from version 2 to 3, then both migrations are run if the version in the config file is 1. On the other hand, if one migration migrates from version 1 to 3 and another one from 2 to 3, then only the former would be run in the same scenario.

Regardless of which migrations were run (or if any were run at all), the version in the config file is set to the version property's default value at the end of the execution. This ensures that invalid versions (like a value that was manually changed) are fixed. Since only known properties are saved to the config file, storing the current default value as version most appropriately reflects the structure of the configuration file.

It is recommended to create a migration for each incremental version change for simplicity (i.e. 1 to 2, 2 to 3, ...). However, you can also define non-sequential migrations: a migration can migrate from 1 to 4, another from 2 to 3, and one from 3 to 4 to migrate any older version to version 4.

Author:

gamerover98

Field Summary

Fields inherited from interface ch.jalu.configme.migration.MigrationService

MIGRATION_REQUIRED, NO_MIGRATION_NEEDED

Constructor Summary

Constructors

Constructor and Description
VersionMigrationService(@NotNull Property<Integer> versionProperty, @NotNull Iterable<VersionMigration> migrations) Constructor.
VersionMigrationService(@NotNull Property<Integer> versionProperty, VersionMigration... migrations) Constructor.

Method Summary

Modifier and Type	Method and Description
boolean	checkAndMigrate(@NotNull PropertyReader reader, @NotNull ConfigurationData configurationData) Performs the migration, returning whether a migration has been performed or not.
protected @NotNull Map<Integer,VersionMigration>	getMigrationsByStartVersion()
protected @NotNull Property<Integer>	getVersionProperty()
protected boolean	performMigrations(@NotNull PropertyReader reader, @NotNull ConfigurationData configurationData) Performs the migration by using the versioning system.
protected int	runApplicableMigrations(int readConfigVersion, @NotNull PropertyReader reader, @NotNull ConfigurationData configurationData) Runs applicable migrations successively: if a migration is found for the read config version, it is run and its target version is noted.
protected Map<Integer,VersionMigration>	validateAndGroupMigrationsByFromVersion(Iterable<VersionMigration> migrations) Validates the given migrations and returns them as a map of migration by its start version.
protected void	validateVersions(VersionMigration migration) Validates the from-version and to-version of the migration.

Methods inherited from class java.lang.Object

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

Constructor Detail

VersionMigrationService

public VersionMigrationService(@NotNull
                               @NotNull Property<Integer> versionProperty,
                               @NotNull
                               @NotNull Iterable<VersionMigration> migrations)

Constructor.

Parameters:

versionProperty - the property that contains the configuration version

migrations - all known migrations

VersionMigrationService

public VersionMigrationService(@NotNull
                               @NotNull Property<Integer> versionProperty,
                               @NotNull
                               VersionMigration... migrations)

Constructor.

Parameters:

versionProperty - the property that contains the configuration version

migrations - all known migrations

Method Detail

checkAndMigrate

public boolean checkAndMigrate(@NotNull
                               @NotNull PropertyReader reader,
                               @NotNull
                               @NotNull ConfigurationData configurationData)

Description copied from interface: MigrationService

Performs the migration, returning whether a migration has been performed or not.

Specified by:

checkAndMigrate in interface MigrationService

Parameters:

reader - reader to access the values in the configuration file

configurationData - configuration data, which knows all properties and manages their associated values

Returns:

true if a migration has been performed, false otherwise. Indicates whether the configuration data should be saved to the configuration file or not

getVersionProperty

@NotNull
protected final @NotNull Property<Integer> getVersionProperty()

getMigrationsByStartVersion

@NotNull
protected final @NotNull Map<Integer,VersionMigration> getMigrationsByStartVersion()

performMigrations

protected boolean performMigrations(@NotNull
                                    @NotNull PropertyReader reader,
                                    @NotNull
                                    @NotNull ConfigurationData configurationData)

Performs the migration by using the versioning system.

Note that the settings manager automatically saves the resource if the migration service returns MigrationService.MIGRATION_REQUIRED from checkAndMigrate(ch.jalu.configme.resource.PropertyReader, ch.jalu.configme.configurationdata.ConfigurationData).

Parameters:

reader - the reader with which the configuration file can be read

configurationData - the configuration data

Returns:

true if a migration has been performed, false otherwise (see constants on MigrationService)

runApplicableMigrations

protected int runApplicableMigrations(int readConfigVersion,
                                      @NotNull
                                      @NotNull PropertyReader reader,
                                      @NotNull
                                      @NotNull ConfigurationData configurationData)

Runs applicable migrations successively: if a migration is found for the read config version, it is run and its target version is noted. If a migration exists for the target version, it is also run, and so forth.

Parameters:

readConfigVersion - the version that was read in the configuration file

reader - the reader with which the configuration file can be read

configurationData - the configuration data

Returns:

the target version of the last migration that was run, or the read config version if no migration was run

validateAndGroupMigrationsByFromVersion

protected Map<Integer,VersionMigration> validateAndGroupMigrationsByFromVersion(Iterable<VersionMigration> migrations)

Validates the given migrations and returns them as a map of migration by its start version.

Parameters:

migrations - the migrations to validate and group

Returns:

map with all migrations by the migration's start version

validateVersions

protected void validateVersions(VersionMigration migration)

Validates the from-version and to-version of the migration.

Parameters:

migration - the migration to validate