Package net.blockhost.commons.config.migration

@NullMarked package net.blockhost.commons.config.migration

Configuration migration framework for versioned YAML configurations.

This package provides a complete solution for managing configuration schema changes over time. It allows you to define migrations that transform configuration data from older versions to newer versions, ensuring backward compatibility as your application evolves.

Overview

The migration system is built around these core components:

Component	Purpose
Migration	Defines a single migration step between versions
MigrationContext	Provides access to config data and utility methods
MigrationRegistry	Stores and manages registered migrations
MigrationExecutor	Executes migrations in sequence
ConfigMigrator	High-level API combining all components
RawYamlLoader	Low-level YAML loading/saving with SnakeYAML

Quick Start

1. Define a versioned configuration

Extend VersionAwareConfiguration to add version tracking:

@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);
    }
}

2. Create migrations

Implement Migration or use the factory methods:

Migration addTimeout = Migration.of(2, "Add timeout field", ctx -> {
    ctx.setDefault("timeout", 30);
});

Migration renameHost = Migration.of(3, "Rename host to hostname", ctx -> {
    ctx.rename("host", "hostname");
});

3. Configure and use the migrator

ConfigMigrator migrator = ConfigMigrator.builder()
    .createBackups(true)
    .register(addTimeout)
    .register(renameHost)
    .beforeMigration(m -> logger.info("Applying: " + m.description()))
    .build();

// Load config with automatic migration
ServerConfig config = migrator.migrateAndLoad(
    configPath,
    ServerConfig.class,
    ServerConfig.CURRENT_VERSION
);

Migration Implementation

Migrations transform raw YAML data represented as Map<String, Object>:

public class MigrateV2ToV3 implements Migration {

    @Override
    public int targetVersion() {
        return 3;
    }

    @Override
    public String description() {
        return "Reorganize database settings into nested structure";
    }

    @Override
    public void migrate(MigrationContext context) {
        // Move flat fields into a nested 'database' section
        context.moveToNested("dbHost", "database", "host");
        context.moveToNested("dbPort", "database", "port");
        context.moveToNested("dbName", "database", "name");

        // Add new field with default
        context.getOrCreateNestedMap("database")
            .putIfAbsent("poolSize", 10);
    }
}

Version Semantics

• Version 0 indicates a config without version tracking (legacy)
• Version 1 is typically the first tracked version
• Migrations are applied sequentially: 1 -> 2 -> 3 -> ...
• The Migration.sourceVersion() defaults to targetVersion - 1
• After migration, the version field is automatically updated

Error Handling

Migrations can fail for various reasons. The system provides:

• MigrationException for all migration-related errors
• MigrationResult to inspect success/failure details
• Optional backup creation before migration
• Detailed step-by-step progress tracking

MigrationResult result = migrator.migrate(configPath, 5);
if (!result.isSuccess()) {
    MigrationException error = result.error().orElseThrow();
    logger.error("Migration failed at version " + result.toVersion(), error);

    // Restore from backup if needed
}

Thread Safety

• MigrationRegistry is thread-safe for concurrent access
• MigrationExecutor and ConfigMigrator are not thread-safe
• Create separate executor/migrator instances for concurrent use

See Also:

• VersionAwareConfiguration
• ConfigLoader

Related Packages

Package

Description

net.blockhost.commons.config

Quick Start Basic Configuration Define your configuration class using ConfigLib annotations: @Configuration public class MyPluginConfig { @Comment("The server host address") private String host = "localhost"; @Comment("The server port") private int port = 3306; @Comment("Database settings") private DatabaseSettings database = new DatabaseSettings(); } Load your configuration: Path configPath = plugin.getDataFolder().toPath().resolve("config.yml"); var properties = ConfigLoader.defaultPropertiesBuilder().build(); MyPluginConfig config = ConfigLoader.loadOrCreate(configPath, MyPluginConfig.class, properties); Versioned Configuration with Migration For configurations that may change over time, use VersionAwareConfiguration:

Class	Description
ConfigMigrator	High-level API for migrating configuration files.
ConfigMigrator.Builder	Builder for creating ConfigMigrator instances.
Migration	Represents a single configuration migration step from one version to the next.
Migration.MigrationAction	Functional interface for migration actions.
MigrationContext	Holds the state and data for a configuration migration.
MigrationException	Exception thrown when a configuration migration fails.
MigrationExecutor	Executes configuration migrations sequentially by version.
MigrationExecutor.MigrationCallback	Callback interface for post-migration notifications.
MigrationRegistry	Registry for managing configuration migrations indexed by version.
MigrationResult	Encapsulates the outcome of a configuration migration operation.
MigrationResult.Builder	Builder for creating migration results incrementally.
MigrationResult.Failure	Represents a failed migration result.
MigrationResult.MigrationStep	Represents a single migration step that was applied.
MigrationResult.Success	Represents a successful migration result.
RawYamlLoader	Utility class for loading and saving raw YAML files as Map structures.