You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@curator.apache.org by ra...@apache.org on 2017/07/18 13:16:30 UTC
[08/23] curator git commit: added some doc
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/master
Commit: 4f12abcdc0c61cae52099f47f158433ebe09326c
Parents: ecbd386
Author: randgalt <ra...@apache.org>
Authored: Fri Jul 14 10:48:47 2017 -0500
Committer: randgalt <ra...@apache.org>
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)