Package space.arim.dazzleconf.migration

Interface MigrateSource<C>

Type Parameters:
C - the config type
All Known Implementing Classes:
MigrateFromConfiguration
public interface MigrateSource<C>
A source for an old configuration version.

A migration source is responsible for loading the old version, checking whether it is applicable, and if so, returning it.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    MigrateSource.Filter<C_OLD>
    A filter for old configuration versions.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NonNull MigrateSource<C>
    addFilter(@NonNull MigrateSource.Filter<C> filter)
    Returns a new migration source, with the given filter applied.
    @NonNull LoadResult<@NonNull C>
    load(@NonNull MigrateContext migrateContext)
    Attempts to load this configuration version.
    void
    onCompletion()
    Signals that the migration was fully completed.

  • Method Details

    • load

      @NonNull LoadResult<@NonNull C> load(@NonNull MigrateContext migrateContext)
      Attempts to load this configuration version.

      If the old version isn't detectable or in usable, returns an error.

      Updated paths

      If the loading the old configuration produced any new keys, or updated existing ones, the implementor should use the migration context's load listener to flag these updates. UpdateReason.MIGRATED should be used for all key updates.

      Importantly, updates should only be flagged when the implementation is sure it will return a success value, and after filters have been applied. Please see MigrateFromConfiguration for a reference implementation.

      Parameters:
      migrateContext - migration context to use if necessary
      Returns:
      the old configuration version, or an error if not found and usable
      Throws:
      UncheckedIOException - upon an I/O failure

    • onCompletion

      void onCompletion()
      Signals that the migration was fully completed.

      This means that the old config version may not be necessary to keep around. It might be time to delete, or move to a different place (like config_old.yml) for archival purposes.

      Throws:
      UncheckedIOException - upon an I/O failure

    • addFilter

      @NonNull MigrateSource<C> addFilter(@NonNull MigrateSource.Filter<C> filter)
      Returns a new migration source, with the given filter applied.

      Values from the original load(MigrateContext) will be passed through the filter, and if the filter returns false, the resulting load(MigrateContext) will return an empty error instead.

      Parameters:
      filter - the source filter to apply
      Returns:
      a new migration source, taking into account the filter
      Throws:
      UnsupportedOperationException - if the implementation does not support adding filters