Package space.arim.dazzleconf.migration

package space.arim.dazzleconf.migration
An optional API for migrations.

Migration sources

An eternal problem, since the advent of configurations, is how to detect and update old versions. In this package, MigrateSource is trusted with both loading and detecting of usable old configuration versions.

It is imperative that MigrateSource implementations do not detect the latest, up-to-date configuration as the old version. If users of this package are not careful, they will find their configuration stuck in a loop: the library will perpetually update the old version to the new version, which is then detected as the old version, and so on.

If the migration produced any new keys, or updated existing ones, it can signal to the migration context's load listener (via MigrateContext#notifyUpdate). Migration sources areencouraged to flag these updates, even if keys might be arranged by later transitions. UpdateReason.MIGRATED is an appropriate update reason.

Transitions

After the old config is loaded, a Transition transforms it into the latest version. Transitions are designed to be infallible, so that chaining is supported.

Like the migration source, the transition can also inform the MigrateContext if it decided to update any paths. This happens frequently, for example, if keys are moved, if types are changed, or sections are expanded or consolidated. The transition should pass the old path to notifyUpdate if a key moved, and it should pass multiple old paths (calling the listener each time) if multiple are relevant.

Integration and usage

A source and a transition together comprise a Migration. Migrations are addable to a configuration at construction time, and they are used by the configureWith and configureOrFallback methods on Configuration.

Other configuration reading methods, which do not take a Backend, do not use migrations. However, library users reserve the right to call migrations directly, or to provide their own logic for handling migrations (including by using some, but not all, of the APIs in this package).