Class MigrationExecutor

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

Executes configuration migrations sequentially by version.

The executor is responsible for applying migrations from a registry in the correct order, tracking progress, handling errors, and optionally creating backups or performing rollbacks.

Basic Usage

MigrationRegistry registry = MigrationRegistry.create()
    .register(new MigrateV1ToV2())
    .register(new MigrateV2ToV3());

MigrationExecutor executor = MigrationExecutor.create(registry);

Map<String, Object> data = RawYamlLoader.load(configPath);
int currentVersion = RawYamlLoader.extractVersion(data);

MigrationResult result = executor.execute(configPath, data, currentVersion, 3);
if (result.isSuccess()) {
    RawYamlLoader.save(configPath, result.data());
}

Execution Modes

The executor supports different execution modes:

  • Strict mode (default): Fails if any migration in the chain is missing
  • Lenient mode: Skips missing migrations and applies available ones
  • Dry run: Simulates migrations without modifying the data

Callbacks

Register callbacks to monitor migration progress:

executor.beforeMigration(migration -> {
    logger.info("Applying migration: " + migration.description());
});

executor.afterMigration((migration, duration) -> {
    logger.info("Completed in " + duration.toMillis() + "ms");
});
See Also:

  • Method Details

    • create

      public static MigrationExecutor create(MigrationRegistry registry)
      Creates a new migration executor with the specified registry.
      Parameters:
      registry - the migration registry to use
      Returns:
      a new executor
      Throws:
      NullPointerException - if registry is null

    • strictMode

      public MigrationExecutor strictMode(boolean strict)

      Enables or disables strict mode.

      In strict mode (default), the executor fails if any migration in the chain is missing. In lenient mode, missing migrations are skipped.

      Parameters:
      strict - true for strict mode, false for lenient mode
      Returns:
      this executor for method chaining

    • dryRun

      public MigrationExecutor dryRun(boolean dryRun)

      Enables or disables dry run mode.

      In dry run mode, migrations are executed but results are discarded. The original data is preserved. Useful for testing migrations.

      Parameters:
      dryRun - true to enable dry run mode
      Returns:
      this executor for method chaining

    • beforeMigration

      public MigrationExecutor beforeMigration(@Nullable Consumer<Migration> callback)
      Sets a callback to be invoked before each migration.
      Parameters:
      callback - the callback to invoke
      Returns:
      this executor for method chaining

    • afterMigration

      public MigrationExecutor afterMigration(@Nullable MigrationExecutor.MigrationCallback callback)
      Sets a callback to be invoked after each successful migration.
      Parameters:
      callback - the callback to invoke
      Returns:
      this executor for method chaining

    • onError

      public MigrationExecutor onError(@Nullable Consumer<MigrationException> callback)
      Sets a callback to be invoked when a migration fails.
      Parameters:
      callback - the callback to invoke
      Returns:
      this executor for method chaining

    • execute

      public MigrationResult execute(Path filePath, Map<String,Object> data, int fromVersion, int toVersion)
      Executes migrations on the provided data.
      Parameters:
      filePath - the path to the config file (for context/logging)
      data - the raw YAML data to migrate
      fromVersion - the current version of the data
      toVersion - the target version to migrate to
      Returns:
      the migration result
      Throws:
      NullPointerException - if filePath or data is null

    • execute

      public MigrationResult execute(Map<String,Object> data, int fromVersion, int toVersion)
      Executes migrations on in-memory data without a file path.
      Parameters:
      data - the raw YAML data to migrate
      fromVersion - the current version of the data
      toVersion - the target version to migrate to
      Returns:
      the migration result
      Throws:
      NullPointerException - if data is null

    • canMigrate

      public boolean canMigrate(int fromVersion, int toVersion)
      Checks if migrations can be executed for the given version range.
      Parameters:
      fromVersion - the current version
      toVersion - the target version
      Returns:
      true if all required migrations are available

    • registry

      public MigrationRegistry registry()
      Returns the registry used by this executor.
      Returns:
      the migration registry