Class ConfigMigrator

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

High-level API for migrating configuration files.

ConfigMigrator combines RawYamlLoader, MigrationRegistry, and MigrationExecutor into a simple, easy-to-use API for migrating VersionAwareConfiguration files.

Basic Usage

// Create a migrator with your migrations
ConfigMigrator migrator = ConfigMigrator.builder()
    .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");
    }))
    .build();

// Migrate and load config
MyConfig config = migrator.migrateAndLoad(configPath, MyConfig.class);

Backup Support

The migrator can create backups before applying migrations:

ConfigMigrator migrator = ConfigMigrator.builder()
    .createBackups(true)              // Enable backups
    .backupSuffix(".backup")          // Customize suffix (default: .bak)
    .register(...)
    .build();

Migration Callbacks

Monitor migration progress with callbacks:

ConfigMigrator migrator = ConfigMigrator.builder()
    .beforeMigration(m -> logger.info("Applying: " + m.description()))
    .afterMigration((m, ctx) -> logger.info("Applied migration to v" + m.targetVersion()))
    .onError(e -> logger.error("Migration failed", e))
    .register(...)
    .build();

Complete Example

@Configuration
public class ServerConfig extends VersionAwareConfiguration {
    private static final int CURRENT_VERSION = 3;

    private String hostname = "localhost";
    private int port = 25565;
    private int timeout = 30;

    public ServerConfig() {
        super(CURRENT_VERSION);
    }
}

// Setup migrator
ConfigMigrator migrator = ConfigMigrator.builder()
    .createBackups(true)
    .register(Migration.of(2, "Add timeout", ctx -> {
        ctx.setDefault("timeout", 30);
    }))
    .register(Migration.of(3, "Rename host to hostname", ctx -> {
        ctx.rename("host", "hostname");
    }))
    .build();

// Load with automatic migration
Path configPath = dataFolder.resolve("config.yml");
ServerConfig config = migrator.migrateAndLoad(configPath, ServerConfig.class, 3);
See Also:

  • Method Details

    • builder

      public static ConfigMigrator.Builder builder()
      Creates a new migrator builder.
      Returns:
      a new builder

    • of

      public static ConfigMigrator of(Migration... migrations)
      Creates a simple migrator with the given migrations.
      Parameters:
      migrations - the migrations to register
      Returns:
      a new migrator

    • migrateAndLoad

      public <T extends VersionAwareConfiguration> T migrateAndLoad(Path path, Class<T> configClass, int targetVersion)

      Migrates a configuration file to the target version and loads it.

      This is the primary method for loading versioned configurations. It:

      1. Loads the raw YAML data
      2. Reads the current version
      3. Applies necessary migrations
      4. Saves the migrated data
      5. Syncs the configuration (adds new fields, removes obsolete ones)
      6. Loads the configuration using ConfigLib
      7. If an env prefix is set, environment variables with that prefix override config values

      The sync step ensures that even if a migration is imperfect, any new fields added to the Java class will be written to the file with their default values.

      Type Parameters:
      T - the configuration type
      Parameters:
      path - the path to the configuration file
      configClass - the configuration class (must extend VersionAwareConfiguration)
      targetVersion - the target version to migrate to
      Returns:
      the loaded and migrated configuration
      Throws:
      MigrationException - if migration or loading fails
      NullPointerException - if any parameter is null

    • migrateAndLoad

      public <T extends VersionAwareConfiguration> T migrateAndLoad(Path path, Class<T> configClass, int targetVersion, de.exlll.configlib.YamlConfigurationProperties properties)
      Migrates a configuration file to the target version and loads it with custom properties.
      Type Parameters:
      T - the configuration type
      Parameters:
      path - the path to the configuration file
      configClass - the configuration class
      targetVersion - the target version to migrate to
      properties - custom ConfigLib properties
      Returns:
      the loaded and migrated configuration
      Throws:
      MigrationException - if migration or loading fails

    • migrate

      public MigrationResult migrate(Path path, int targetVersion)

      Migrates a configuration file to the target version.

      This method only performs migration without loading the result into a typed class. Use this when you need more control over the process or want to inspect the migration result before loading.

      Parameters:
      path - the path to the configuration file
      targetVersion - the target version to migrate to
      Returns:
      the migration result
      Throws:
      NullPointerException - if path is null

    • migrateData

      public MigrationResult migrateData(Map<String,Object> data, int fromVersion, int toVersion)
      Migrates in-memory data without file I/O.
      Parameters:
      data - the raw YAML data to migrate
      fromVersion - the current version
      toVersion - the target version
      Returns:
      the migration result
      Throws:
      NullPointerException - if data is null

    • needsMigration

      public boolean needsMigration(Path path, int targetVersion)
      Checks if migrations are needed for a configuration file.
      Parameters:
      path - the path to the configuration file
      targetVersion - the target version
      Returns:
      true if the file needs migration
      Throws:
      NullPointerException - if path is null

    • getVersion

      public Optional<Integer> getVersion(Path path)
      Gets the current version of a configuration file.
      Parameters:
      path - the path to the configuration file
      Returns:
      an Optional containing the version, or empty if file doesn't exist
      Throws:
      NullPointerException - if path is null

    • canMigrate

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

    • registry

      public MigrationRegistry registry()
      Returns the migration registry.
      Returns:
      the registry