Class MigrationContext

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

Holds the state and data for a configuration migration.

The migration context provides access to the raw YAML data being migrated, along with metadata about the migration process. It also provides utility methods for common migration operations like getting nested values, renaming fields, and type-safe value extraction.

Data Access

The data() method returns a mutable map that migrations can modify directly:

@Override
public void migrate(MigrationContext context) {
    Map<String, Object> data = context.data();
    data.put("newField", "value");
    data.remove("oldField");
}

Nested Data Access

Use getNestedMap(String) and getNestedValue(String, String, Class) to safely access nested structures:

@Override
public void migrate(MigrationContext context) {
    // Safely get nested map, creating it if it doesn't exist
    Map<String, Object> database = context.getOrCreateNestedMap("database");
    database.put("poolSize", 10);

    // Safely get a nested value with type casting
    Optional<String> host = context.getNestedValue("database", "host", String.class);
}

Immutability

The context itself is immutable (file path and current version cannot change), but the data map is mutable to allow migrations to transform it.

See Also:

  • Method Details

    • of

      public static MigrationContext of(Path filePath, Map<String,Object> data, int currentVersion, int targetVersion)
      Creates a new migration context.
      Parameters:
      filePath - the path to the configuration file
      data - the raw YAML data
      currentVersion - the current version
      targetVersion - the target version
      Returns:
      a new migration context
      Throws:
      NullPointerException - if filePath or data is null

    • ofData

      public static MigrationContext ofData(Map<String,Object> data, int currentVersion, int targetVersion)
      Creates a migration context without a file path (for in-memory migrations).
      Parameters:
      data - the raw YAML data
      currentVersion - the current version
      targetVersion - the target version
      Returns:
      a new migration context
      Throws:
      NullPointerException - if data is null

    • filePath

      public Path filePath()
      Returns the path to the configuration file being migrated.
      Returns:
      the file path, or an empty path for in-memory migrations

    • data

      public Map<String,Object> data()

      Returns the mutable map containing the YAML data.

      Migrations should modify this map directly to transform the data.

      Returns:
      the data map

    • currentVersion

      public int currentVersion()

      Returns the version the data is currently at.

      This is the version before any migrations in the current batch are applied.

      Returns:
      the current version

    • targetVersion

      public int targetVersion()
      Returns the target version to migrate to.
      Returns:
      the target version

    • get

      public <T> Optional<T> get(String key, Class<T> type)
      Gets a value from the data map with type casting.
      Type Parameters:
      T - the value type
      Parameters:
      key - the key to look up
      type - the expected type
      Returns:
      an Optional containing the value if present and of correct type

    • getString

      public Optional<String> getString(String key)
      Gets a string value from the data map.
      Parameters:
      key - the key to look up
      Returns:
      an Optional containing the string value if present

    • getInt

      public Optional<Integer> getInt(String key)

      Gets an integer value from the data map.

      Handles both Integer and other Number types.

      Parameters:
      key - the key to look up
      Returns:
      an Optional containing the integer value if present

    • getBoolean

      public Optional<Boolean> getBoolean(String key)
      Gets a boolean value from the data map.
      Parameters:
      key - the key to look up
      Returns:
      an Optional containing the boolean value if present

    • getList

      public Optional<List<Object>> getList(String key)
      Gets a list value from the data map.
      Parameters:
      key - the key to look up
      Returns:
      an Optional containing the list if present

    • getNestedMap

      public Optional<Map<String,Object>> getNestedMap(String key)
      Gets a nested map from the data.
      Parameters:
      key - the key for the nested map
      Returns:
      an Optional containing the nested map if present

    • getOrCreateNestedMap

      public Map<String,Object> getOrCreateNestedMap(String key)

      Gets or creates a nested map in the data.

      If the key doesn't exist, a new LinkedHashMap is created and added.

      Parameters:
      key - the key for the nested map
      Returns:
      the existing or newly created nested map
      Throws:
      MigrationException - if the key exists but is not a map

    • getNestedValue

      public <T> Optional<T> getNestedValue(String mapKey, String valueKey, Class<T> type)
      Gets a value from a nested map.
      Type Parameters:
      T - the value type
      Parameters:
      mapKey - the key for the nested map
      valueKey - the key within the nested map
      type - the expected type
      Returns:
      an Optional containing the value if present

    • rename

      public boolean rename(String oldKey, String newKey)

      Renames a key in the data map.

      If the old key doesn't exist, this method does nothing. If the new key already exists, it will be overwritten.

      Parameters:
      oldKey - the current key name
      newKey - the new key name
      Returns:
      true if the key was renamed, false if the old key didn't exist

    • renameNested

      public boolean renameNested(String mapKey, String oldKey, String newKey)
      Renames a key within a nested map.
      Parameters:
      mapKey - the key for the nested map
      oldKey - the current key name within the nested map
      newKey - the new key name within the nested map
      Returns:
      true if the key was renamed, false otherwise

    • setDefault

      public boolean setDefault(String key, @Nullable Object value)
      Sets a value in the data map if the key is not already present.
      Parameters:
      key - the key
      value - the default value
      Returns:
      true if the value was set, false if the key already existed

    • moveToNested

      public boolean moveToNested(String sourceKey, String targetMapKey, String targetKey)
      Moves a value from one location to a nested map.
      Parameters:
      sourceKey - the source key in the root map
      targetMapKey - the key for the target nested map
      targetKey - the key within the target nested map
      Returns:
      true if the value was moved, false if source didn't exist

    • moveFromNested

      public boolean moveFromNested(String sourceMapKey, String sourceKey, String targetKey)
      Moves a value from a nested map to the root map.
      Parameters:
      sourceMapKey - the key for the source nested map
      sourceKey - the key within the source nested map
      targetKey - the target key in the root map
      Returns:
      true if the value was moved, false otherwise

    • copyData

      public Map<String,Object> copyData()

      Creates a copy of the current data.

      Useful for creating backups before risky transformations.

      Returns:
      a deep copy of the data map

    • toString

      public String toString()
      Overrides:
      toString in class Object