Repository: curator Updated Branches: refs/heads/CURATOR-421 ecbd38664 -> d80651a7a
added some doc Project: http://git-wip-us.apache.org/repos/asf/curator/repo Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/4f12abcd Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/4f12abcd Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/4f12abcd Branch: refs/heads/CURATOR-421 Commit: 4f12abcdc0c61cae52099f47f158433ebe09326c Parents: ecbd386 Author: randgalt <[email protected]> Authored: Fri Jul 14 10:48:47 2017 -0500 Committer: randgalt <[email protected]> Committed: Fri Jul 14 10:48:47 2017 -0500 ---------------------------------------------------------------------- .../x/async/modeled/migrations/MetaData.java | 9 ++++ .../x/async/modeled/migrations/Migration.java | 17 +++++++ .../modeled/migrations/MigrationManager.java | 48 +++++++++++++++++--- .../async/modeled/migrations/MigrationSet.java | 13 ++++++ 4 files changed, 81 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/curator/blob/4f12abcd/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MetaData.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MetaData.java b/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MetaData.java index c2878e2..da40a5b 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MetaData.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MetaData.java @@ -20,6 +20,9 @@ package org.apache.curator.x.async.modeled.migrations; import java.util.Objects; +/** + * The meta data of a single migration + */ public class MetaData { private final String migrationId; @@ -36,11 +39,17 @@ public class MetaData this.migrationVersion = migrationVersion; } + /** + * @return The ID of the migration that was applied + */ public String getMigrationId() { return migrationId; } + /** + * @return the version of the migration that was applied + */ public int getMigrationVersion() { return migrationVersion; http://git-wip-us.apache.org/repos/asf/curator/blob/4f12abcd/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/Migration.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/Migration.java b/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/Migration.java index 63a7a7d..b456580 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/Migration.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/Migration.java @@ -23,14 +23,31 @@ import java.util.List; import java.util.Objects; import java.util.function.Supplier; +/** + * Models a single migration/transition + */ public interface Migration { + /** + * @return the unique ID for this migration + */ String id(); + /** + * @return the version of this migration + */ int version(); + /** + * @return the operations to execute in a transaction + */ List<CuratorOp> operations(); + static Migration build(String id, Supplier<List<CuratorOp>> operationsProc) + { + return build(id, 1, operationsProc); + } + static Migration build(String id, int version, Supplier<List<CuratorOp>> operationsProc) { Objects.requireNonNull(id, "id cannot be null"); http://git-wip-us.apache.org/repos/asf/curator/blob/4f12abcd/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationManager.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationManager.java b/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationManager.java index bfb9707..01de2f8 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationManager.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationManager.java @@ -42,6 +42,9 @@ import java.util.stream.Collectors; import static org.apache.curator.x.async.AsyncWrappers.*; +/** + * Manages migrations + */ public class MigrationManager { private final AsyncCuratorFramework client; @@ -52,6 +55,16 @@ public class MigrationManager private static final String META_DATA_NODE_NAME = "meta-"; + /** + * Jackson usage: See the note in {@link org.apache.curator.x.async.modeled.JacksonModelSerializer} regarding how the Jackson library is specified in Curator's Maven file. + * Unless you are not using Jackson pass <code>JacksonModelSerializer.build(MetaData.class)</code> for <code>metaDataSerializer</code> + * + * @param client the curator client + * @param lockPath base path for locks used by the manager + * @param metaDataSerializer JacksonModelSerializer.build(MetaData.class) + * @param executor the executor to use + * @param lockMax max time to wait for locks + */ public MigrationManager(AsyncCuratorFramework client, ZPath lockPath, ModelSerializer<MetaData> metaDataSerializer, Executor executor, Duration lockMax) { this.client = Objects.requireNonNull(client, "client cannot be null"); @@ -61,12 +74,13 @@ public class MigrationManager this.lockMax = Objects.requireNonNull(lockMax, "lockMax cannot be null"); } - public CompletionStage<List<MetaData>> metaData(ZPath metaDataPath) - { - ModeledFramework<MetaData> modeled = getMetaDataClient(metaDataPath); - return ZNode.models(modeled.childrenAsZNodes()); - } - + /** + * Process the given migration set + * + * @param set the set + * @return completion stage. If there is a migration-specific error, the stage will be completed + * exceptionally with {@link org.apache.curator.x.async.modeled.migrations.MigrationException}. + */ public CompletionStage<Void> migrate(MigrationSet set) { String lockPath = this.lockPath.child(set.id()).fullPath(); @@ -75,6 +89,28 @@ public class MigrationManager return lockStage.thenCompose(__ -> runMigrationInLock(lock, set)); } + /** + * Utility to return the meta data from previous migrations + * + * @param set the set + * @return stage + */ + public CompletionStage<List<MetaData>> metaData(MigrationSet set) + { + ModeledFramework<MetaData> modeled = getMetaDataClient(set.metaDataPath()); + return ZNode.models(modeled.childrenAsZNodes()); + } + + /** + * Can be overridden to change how the comparison to previous migrations is done. The default + * version ensures that the meta data from previous migrations matches the current migration + * set exactly (by order and version). If there is a mismatch, <code>MigrationException</code> is thrown. + * + * @param set the migration set being applied + * @param sortedMetaData previous migration meta data (may be empty) + * @return the list of actual migrations to perform. The filter can return any value here or an empty list. + * @throws MigrationException errors + */ protected List<Migration> filter(MigrationSet set, List<MetaData> sortedMetaData) throws MigrationException { if ( sortedMetaData.size() > set.migrations().size() ) http://git-wip-us.apache.org/repos/asf/curator/blob/4f12abcd/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationSet.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationSet.java b/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationSet.java index 0a0dbe0..c4cd90e 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationSet.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/modeled/migrations/MigrationSet.java @@ -23,12 +23,25 @@ import org.apache.curator.x.async.modeled.ZPath; import java.util.List; import java.util.Objects; +/** + * Models a set of migrations. Each individual migration is applied + * in a transaction. + */ public interface MigrationSet { + /** + * @return the unique ID for this migration set + */ String id(); + /** + * @return where to store the meta data for this migration set + */ ZPath metaDataPath(); + /** + * @return list of migrations in the order that they should be applied + */ List<Migration> migrations(); static MigrationSet build(String id, ZPath metaDataPath, List<Migration> migrations)
