Class MigrationException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
net.blockhost.commons.config.migration.MigrationException
All Implemented Interfaces:
Serializable
public class MigrationException extends RuntimeException

Exception thrown when a configuration migration fails.

This exception is used throughout the migration system to indicate various failure conditions, including:

  • YAML parsing errors: When a configuration file contains invalid YAML syntax
  • Version errors: When the version field is missing, invalid, or out of range
  • Migration errors: When a migration fails to transform the data correctly
  • I/O errors: When reading or writing configuration files fails

Exception Chaining

MigrationException supports exception chaining to preserve the original cause. Always include the original exception when wrapping lower-level errors:

try {
    // Some operation that might fail
} catch (IOException e) {
    throw new MigrationException("Failed to read config file", e);
}

Usage in Migrations

When implementing a Migration, throw this exception to abort the migration process and trigger rollback (if enabled):

@Override
public void migrate(MigrationContext context) {
    Object oldValue = context.data().get("oldField");
    if (oldValue == null) {
        throw new MigrationException("Required field 'oldField' is missing");
    }
    // Continue with migration...
}
See Also:

  • Constructor Details

    • MigrationException

      public MigrationException(String message)
      Creates a new migration exception with the specified message.
      Parameters:
      message - the detail message describing the failure

    • MigrationException

      public MigrationException(String message, Throwable cause)
      Creates a new migration exception with the specified message and cause.
      Parameters:
      message - the detail message describing the failure
      cause - the underlying cause of the failure

    • MigrationException

      public MigrationException(Throwable cause)

      Creates a new migration exception with the specified cause.

      The detail message is set to the cause's message.

      Parameters:
      cause - the underlying cause of the failure

  • Method Details

    • versionMismatch

      public static MigrationException versionMismatch(int currentVersion, int expectedVersion)
      Creates a migration exception indicating a version mismatch.
      Parameters:
      currentVersion - the current version found in the config
      expectedVersion - the version that was expected
      Returns:
      a new MigrationException with a descriptive message

    • missingMigration

      public static MigrationException missingMigration(int fromVersion, int toVersion)
      Creates a migration exception indicating a missing migration.
      Parameters:
      fromVersion - the source version
      toVersion - the target version
      Returns:
      a new MigrationException with a descriptive message

    • invalidVersionRange

      public static MigrationException invalidVersionRange(int fromVersion, int toVersion)
      Creates a migration exception indicating an invalid version range.
      Parameters:
      fromVersion - the source version
      toVersion - the target version
      Returns:
      a new MigrationException with a descriptive message

    • migrationFailed

      public static MigrationException migrationFailed(int version, Throwable cause)
      Creates a migration exception indicating a migration failure at a specific version.
      Parameters:
      version - the version where migration failed
      cause - the underlying cause
      Returns:
      a new MigrationException with a descriptive message