Class MigrationRegistry

java.lang.Object
net.blockhost.commons.config.migration.MigrationRegistry
public final class MigrationRegistry extends Object

Registry for managing configuration migrations indexed by version.

The registry stores migrations keyed by their target version, allowing efficient lookup and sequential application of migrations from any source version to a target version.

Registration

Migrations are registered with their target version as the key:

MigrationRegistry registry = MigrationRegistry.create();

// Register individual migrations
registry.register(new MigrateV1ToV2());
registry.register(new MigrateV2ToV3());

// Or use the fluent API
registry
    .register(Migration.of(2, "Add timeout field", ctx -> {
        ctx.data().putIfAbsent("timeout", 30);
    }))
    .register(Migration.of(3, "Rename host to hostname", ctx -> {
        ctx.rename("host", "hostname");
    }));

Version Lookup

The registry provides methods to find migrations for a given version range:

// Get all migrations needed to go from version 1 to version 5
List<Migration> migrations = registry.getMigrationsInRange(1, 5);

// Check if a migration exists for a specific target version
Optional<Migration> migration = registry.get(3);

Thread Safety

The registry is thread-safe for concurrent registration and lookup operations. Use create() for a thread-safe implementation, or createNonConcurrent() for a non-thread-safe but slightly faster implementation.

See Also:

  • Method Details

    • create

      public static MigrationRegistry create()
      Creates a new thread-safe migration registry.
      Returns:
      a new empty registry

    • createNonConcurrent

      public static MigrationRegistry createNonConcurrent()

      Creates a new non-thread-safe migration registry.

      Use this when migrations are only registered during initialization and the registry won't be modified after that.

      Returns:
      a new empty registry

    • of

      public static MigrationRegistry of(Migration... migrations)
      Creates a registry pre-populated with the given migrations.
      Parameters:
      migrations - the migrations to register
      Returns:
      a new registry containing the migrations
      Throws:
      NullPointerException - if migrations is null
      IllegalArgumentException - if multiple migrations have the same target version

    • of

      public static MigrationRegistry of(Collection<? extends Migration> migrations)
      Creates a registry pre-populated with the given migrations.
      Parameters:
      migrations - the migrations to register
      Returns:
      a new registry containing the migrations
      Throws:
      NullPointerException - if migrations is null
      IllegalArgumentException - if multiple migrations have the same target version

    • register

      public MigrationRegistry register(Migration migration)

      Registers a migration.

      The migration is indexed by its Migration.targetVersion().

      Parameters:
      migration - the migration to register
      Returns:
      this registry for method chaining
      Throws:
      NullPointerException - if migration is null
      IllegalArgumentException - if a migration is already registered for the target version

    • registerOrReplace

      public @Nullable Migration registerOrReplace(Migration migration)
      Registers a migration, replacing any existing migration for the same target version.
      Parameters:
      migration - the migration to register
      Returns:
      the previously registered migration, or null if none
      Throws:
      NullPointerException - if migration is null

    • registerAll

      public MigrationRegistry registerAll(Migration... migrations)
      Registers multiple migrations.
      Parameters:
      migrations - the migrations to register
      Returns:
      this registry for method chaining
      Throws:
      NullPointerException - if migrations is null
      IllegalArgumentException - if a migration is already registered for any target version

    • registerAll

      public MigrationRegistry registerAll(Collection<? extends Migration> migrations)
      Registers multiple migrations.
      Parameters:
      migrations - the migrations to register
      Returns:
      this registry for method chaining
      Throws:
      NullPointerException - if migrations is null
      IllegalArgumentException - if a migration is already registered for any target version

    • get

      public Optional<Migration> get(int targetVersion)
      Gets the migration for a specific target version.
      Parameters:
      targetVersion - the target version
      Returns:
      an Optional containing the migration, or empty if not found

    • contains

      public boolean contains(int targetVersion)
      Checks if a migration exists for the specified target version.
      Parameters:
      targetVersion - the target version to check
      Returns:
      true if a migration is registered for that version

    • remove

      public @Nullable Migration remove(int targetVersion)
      Removes the migration for the specified target version.
      Parameters:
      targetVersion - the target version
      Returns:
      the removed migration, or null if none was registered

    • clear

      public void clear()
      Clears all registered migrations.

    • size

      public int size()
      Returns the number of registered migrations.
      Returns:
      the migration count

    • isEmpty

      public boolean isEmpty()
      Checks if the registry is empty.
      Returns:
      true if no migrations are registered

    • getAllMigrations

      public List<Migration> getAllMigrations()
      Returns all registered migrations in version order.
      Returns:
      an unmodifiable list of migrations sorted by target version

    • getAllVersions

      public List<Integer> getAllVersions()
      Returns all registered target versions in ascending order.
      Returns:
      an unmodifiable set of target versions

    • getHighestVersion

      public Optional<Integer> getHighestVersion()
      Gets the highest registered target version.
      Returns:
      an Optional containing the highest version, or empty if registry is empty

    • getLowestVersion

      public Optional<Integer> getLowestVersion()
      Gets the lowest registered target version.
      Returns:
      an Optional containing the lowest version, or empty if registry is empty

    • getMigrationsInRange

      public List<Migration> getMigrationsInRange(int fromVersion, int toVersion)

      Gets all migrations needed to migrate from one version to another.

      Returns migrations where sourceVersion < targetVersion <= toVersion, ensuring migrations are applicable for configs at the given source version.

      Parameters:
      fromVersion - the current config version (exclusive - migrations after this)
      toVersion - the target version (inclusive)
      Returns:
      a list of migrations in version order
      Throws:
      MigrationException - if fromVersion >= toVersion

    • findMissingMigrations

      public List<Integer> findMissingMigrations(int fromVersion, int toVersion)

      Validates that all migrations needed to go from one version to another exist.

      This checks that there are no gaps in the migration chain.

      Parameters:
      fromVersion - the starting version
      toVersion - the target version
      Returns:
      a list of missing version numbers, empty if chain is complete

    • hasCompleteMigrationChain

      public boolean hasCompleteMigrationChain(int fromVersion, int toVersion)
      Checks if the registry has a complete migration chain between two versions.
      Parameters:
      fromVersion - the starting version
      toVersion - the target version
      Returns:
      true if migrations exist for all versions in the range

    • immutableCopy

      public MigrationRegistry immutableCopy()
      Creates an immutable copy of this registry.
      Returns:
      a new immutable registry with the same migrations

    • toString

      public String toString()
      Overrides:
      toString in class Object