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/02/09 18:36:22 UTC
[23/47] curator git commit: docs
docs
Project: http://git-wip-us.apache.org/repos/asf/curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/6d055e96
Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/6d055e96
Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/6d055e96
Branch: refs/heads/CURATOR-3.0
Commit: 6d055e967bcf9684816baf1513f67551391c0728
Parents: 16364f3
Author: randgalt <ra...@apache.org>
Authored: Fri Jan 6 15:36:31 2017 -0500
Committer: randgalt <ra...@apache.org>
Committed: Fri Jan 6 15:36:31 2017 -0500
----------------------------------------------------------------------
.../curator/x/async/AsyncCreateBuilder.java | 67 ++++++++++++++++-
.../curator/x/async/AsyncCuratorFramework.java | 30 +++++++-
.../x/async/AsyncCuratorFrameworkDsl.java | 6 +-
.../curator/x/async/AsyncDeleteBuilder.java | 24 ++++++
.../curator/x/async/AsyncEnsemblable.java | 7 +-
.../curator/x/async/AsyncExistsBuilder.java | 23 ++----
.../curator/x/async/AsyncGetACLBuilder.java | 6 +-
.../x/async/AsyncGetChildrenBuilder.java | 6 +-
.../curator/x/async/AsyncGetConfigBuilder.java | 9 +++
.../curator/x/async/AsyncGetDataBuilder.java | 10 ++-
.../curator/x/async/AsyncMultiTransaction.java | 7 +-
.../curator/x/async/AsyncPathAndBytesable.java | 6 +-
.../apache/curator/x/async/AsyncPathable.java | 6 +-
.../curator/x/async/AsyncReconfigBuilder.java | 66 ++++++++++++++---
.../x/async/AsyncRemoveWatchesBuilder.java | 78 +++++++++++++++++++-
.../curator/x/async/AsyncSetACLBuilder.java | 18 +++++
.../curator/x/async/AsyncSetDataBuilder.java | 18 +++++
.../org/apache/curator/x/async/AsyncStage.java | 10 +++
.../curator/x/async/AsyncSyncBuilder.java | 3 +
.../x/async/AsyncTransactionCheckBuilder.java | 6 +-
.../x/async/AsyncTransactionCreateBuilder.java | 3 +
.../x/async/AsyncTransactionDeleteBuilder.java | 6 +-
.../x/async/AsyncTransactionSetDataBuilder.java | 6 +-
.../apache/curator/x/async/ExistsOption.java | 7 ++
.../x/async/details/AsyncDeleteBuilderImpl.java | 2 +-
.../x/async/details/AsyncExistsBuilderImpl.java | 20 ++---
.../details/AsyncRemoveWatchesBuilderImpl.java | 2 +-
27 files changed, 387 insertions(+), 65 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCreateBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCreateBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCreateBuilder.java
index b030fac..708ae75 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCreateBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCreateBuilder.java
@@ -24,8 +24,10 @@ import org.apache.zookeeper.data.Stat;
import java.util.List;
import java.util.Set;
-public interface AsyncCreateBuilder extends
- AsyncPathAndBytesable<AsyncStage<String>>
+/**
+ * Builder for ZNode creates
+ */
+public interface AsyncCreateBuilder extends AsyncPathAndBytesable<AsyncStage<String>>
{
/**
* Have the operation fill the provided stat object
@@ -35,17 +37,78 @@ public interface AsyncCreateBuilder extends
*/
AsyncPathAndBytesable<AsyncStage<String>> storingStatIn(Stat stat);
+ /**
+ * Use the given create mode. The default is {@link org.apache.zookeeper.CreateMode#PERSISTENT}
+ *
+ * @param createMode mode to use
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<String>> withMode(CreateMode createMode);
+ /**
+ * Set an ACL list (default is {@link org.apache.zookeeper.ZooDefs.Ids#OPEN_ACL_UNSAFE})
+ *
+ * @param aclList the ACL list to use
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<String>> withACL(List<ACL> aclList);
+ /**
+ * Options to change how the ZNode is created
+ *
+ * @param options options
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<String>> withOptions(Set<CreateOption> options);
+ /**
+ * set options and ACLs
+ *
+ * @param options options
+ * @param aclList the ACL list to use
+ * @see #withOptions(java.util.Set)
+ * @see #withACL(java.util.List)
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<String>> withOptions(Set<CreateOption> options, List<ACL> aclList);
+ /**
+ * set options, mode and ACLs
+ *
+ * @param options options
+ * @param createMode mode to use
+ * @param aclList the ACL list to use
+ * @see #withACL(java.util.List)
+ * @see #withOptions(java.util.Set)
+ * @see #withMode(org.apache.zookeeper.CreateMode)
+ * @see #withACL(java.util.List)
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<String>> withOptions(Set<CreateOption> options, CreateMode createMode, List<ACL> aclList);
+ /**
+ * set options and mode
+ *
+ * @param options options
+ * @param createMode mode to use
+ * @see #withOptions(java.util.Set)
+ * @see #withMode(org.apache.zookeeper.CreateMode)
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<String>> withOptions(Set<CreateOption> options, CreateMode createMode);
+ /**
+ * set options, mode, ACLs, and stat
+ *
+ * @param options options
+ * @param createMode mode to use
+ * @param aclList the ACL list to use
+ * @param stat the stat to have filled in
+ * @see #withOptions(java.util.Set)
+ * @see #withMode(org.apache.zookeeper.CreateMode)
+ * @see #withACL(java.util.List)
+ * @see #storingStatIn(org.apache.zookeeper.data.Stat)
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<String>> withOptions(Set<CreateOption> options, CreateMode createMode, List<ACL> aclList, Stat stat);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFramework.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFramework.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFramework.java
index 9751af6..c12a28b 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFramework.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFramework.java
@@ -23,18 +23,46 @@ import org.apache.curator.framework.api.UnhandledErrorListener;
import org.apache.curator.x.async.details.AsyncCuratorFrameworkImpl;
/**
- * Zookeeper framework-style client
+ * Zookeeper framework-style client that returns composable async operations
+ * that implement {@link java.util.concurrent.CompletionStage}
*/
public interface AsyncCuratorFramework extends AsyncCuratorFrameworkDsl
{
+ /**
+ * Takes an old-style Curator instance and returns a new async instance that
+ * wraps it. Note: the instance must have been created through a chain that
+ * leads back to {@link org.apache.curator.framework.CuratorFrameworkFactory}. i.e.
+ * you can have derived instances such as {@link org.apache.curator.framework.WatcherRemoveCuratorFramework}
+ * etc. but the original client must have been created by the Factory.
+ *
+ * @param client instance to wrap
+ * @return wrapped instance
+ */
static AsyncCuratorFramework wrap(CuratorFramework client)
{
return new AsyncCuratorFrameworkImpl(client);
}
+ /**
+ * Returns the client that was originally passed to {@link #wrap(org.apache.curator.framework.CuratorFramework)}
+ *
+ * @return original client
+ */
CuratorFramework unwrap();
+ /**
+ * Returns a facade that adds watching to any of the subsequently created builders. i.e. all
+ * operations on the WatchedAsyncCuratorFramework facade will have watchers set.
+ *
+ * @return watcher facade
+ */
WatchedAsyncCuratorFramework watched();
+ /**
+ * Returns a facade that adds the given UnhandledErrorListener to all background operations
+ *
+ * @param listener lister to use
+ * @return facade
+ */
AsyncCuratorFrameworkDsl withUnhandledErrorListener(UnhandledErrorListener listener);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFrameworkDsl.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFrameworkDsl.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFrameworkDsl.java
index 5927c22..2c777d5 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFrameworkDsl.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncCuratorFrameworkDsl.java
@@ -84,15 +84,15 @@ public interface AsyncCuratorFrameworkDsl extends WatchedAsyncCuratorFramework
AsyncTransactionOp transactionOp();
/**
- * Start a sync builder. Note: sync is ALWAYS in the background even
- * if you don't use one of the background() methods
+ * Start a sync builder
*
* @return builder object
*/
AsyncSyncBuilder sync();
/**
- * Start a remove watches builder.
+ * Start a remove watches builder
+ *
* @return builder object
*/
AsyncRemoveWatchesBuilder removeWatches();
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncDeleteBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncDeleteBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncDeleteBuilder.java
index b66d86b..e8c4ac5 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncDeleteBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncDeleteBuilder.java
@@ -20,11 +20,35 @@ package org.apache.curator.x.async;
import java.util.Set;
+/**
+ * Builder for ZNode deletions
+ */
public interface AsyncDeleteBuilder extends AsyncPathable<AsyncStage<Void>>
{
+ /**
+ * Changes the deletion options. By default, no options are used
+ *
+ * @param options set of deletion options
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> withOptions(Set<DeleteOption> options);
+ /**
+ * Set options and version.
+ *
+ * @param options set of deletion options
+ * @param version version to use
+ * @see #withOptions(java.util.Set)
+ * @see #withVersion(int)
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> withOptionsAndVersion(Set<DeleteOption> options, int version);
+ /**
+ * Changes the version number passed to the delete() method. By default, -1 is ued
+ *
+ * @param version version to use
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> withVersion(int version);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncEnsemblable.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncEnsemblable.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncEnsemblable.java
index 55aa918..b096fa1 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncEnsemblable.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncEnsemblable.java
@@ -18,12 +18,15 @@
*/
package org.apache.curator.x.async;
+/**
+ * Terminal operation for config/reconfig builders
+ */
public interface AsyncEnsemblable<T>
{
/**
- * Commit the currently building operation
+ * Commit the currently building operation and invoke ZooKeeper
*
- * @return operation result if any
+ * @return async stage
*/
T forEnsemble();
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncExistsBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncExistsBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncExistsBuilder.java
index 6f8d861..9c14076 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncExistsBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncExistsBuilder.java
@@ -18,26 +18,19 @@
*/
package org.apache.curator.x.async;
-import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.data.Stat;
+import java.util.Set;
-public interface AsyncExistsBuilder
- extends AsyncPathable<AsyncStage<Stat>>
+/**
+ * Builder for ZNode exists
+ */
+public interface AsyncExistsBuilder extends AsyncPathable<AsyncStage<Stat>>
{
/**
- * Causes any parent nodes to get created if they haven't already been
- *
- * @return this
- */
- AsyncPathable<AsyncStage<Stat>> creatingParentsIfNeeded();
-
- /**
- * Causes any parent nodes to get created using {@link CreateMode#CONTAINER} if they haven't already been.
- * IMPORTANT NOTE: container creation is a new feature in recent versions of ZooKeeper.
- * If the ZooKeeper version you're using does not support containers, the parent nodes
- * are created as ordinary PERSISTENT nodes.
+ * Use the given options. The default is to use no options
*
+ * @param options options to use
* @return this
*/
- AsyncPathable<AsyncStage<Stat>> creatingParentContainersIfNeeded();
+ AsyncPathable<AsyncStage<Stat>> withOptions(Set<ExistsOption> options);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetACLBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetACLBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetACLBuilder.java
index 5fd3685..355a498 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetACLBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetACLBuilder.java
@@ -22,8 +22,10 @@ import org.apache.zookeeper.data.ACL;
import org.apache.zookeeper.data.Stat;
import java.util.List;
-public interface AsyncGetACLBuilder extends
- AsyncPathable<AsyncStage<List<ACL>>>
+/**
+ * Builder for getAcls
+ */
+public interface AsyncGetACLBuilder extends AsyncPathable<AsyncStage<List<ACL>>>
{
/**
* Have the operation fill the provided stat object
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetChildrenBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetChildrenBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetChildrenBuilder.java
index f3eeb96..3cf671f 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetChildrenBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetChildrenBuilder.java
@@ -21,8 +21,10 @@ package org.apache.curator.x.async;
import org.apache.zookeeper.data.Stat;
import java.util.List;
-public interface AsyncGetChildrenBuilder extends
- AsyncPathable<AsyncStage<List<String>>>
+/**
+ * Builder for getChildren()
+ */
+public interface AsyncGetChildrenBuilder extends AsyncPathable<AsyncStage<List<String>>>
{
/**
* Have the operation fill the provided stat object
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetConfigBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetConfigBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetConfigBuilder.java
index a6c0b10..8e5ec48 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetConfigBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetConfigBuilder.java
@@ -20,7 +20,16 @@ package org.apache.curator.x.async;
import org.apache.zookeeper.data.Stat;
+/**
+ * Builder for getConfig()
+ */
public interface AsyncGetConfigBuilder extends AsyncEnsemblable<AsyncStage<byte[]>>
{
+ /**
+ * Have the operation fill the provided stat object
+ *
+ * @param stat the stat to have filled in
+ * @return this
+ */
AsyncEnsemblable<AsyncStage<byte[]>> storingStatIn(Stat stat);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetDataBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetDataBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetDataBuilder.java
index a3932ee..bae9b2b 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetDataBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncGetDataBuilder.java
@@ -20,8 +20,10 @@ package org.apache.curator.x.async;
import org.apache.zookeeper.data.Stat;
-public interface AsyncGetDataBuilder extends
- AsyncPathable<AsyncStage<byte[]>>
+/**
+ * Builder to get ZNode data
+ */
+public interface AsyncGetDataBuilder extends AsyncPathable<AsyncStage<byte[]>>
{
/**
* Cause the data to be de-compressed using the configured compression provider
@@ -39,9 +41,11 @@ public interface AsyncGetDataBuilder extends
AsyncPathable<AsyncStage<byte[]>> storingStatIn(Stat stat);
/**
- * Have the operation fill the provided stat object
+ * Have the operation fill the provided stat object and have the data be de-compressed
*
* @param stat the stat to have filled in
+ * @see #decompressed()
+ * @see #storingStatIn(org.apache.zookeeper.data.Stat)
* @return this
*/
AsyncPathable<AsyncStage<byte[]>> decompressedStoringStatIn(Stat stat);
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncMultiTransaction.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncMultiTransaction.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncMultiTransaction.java
index 29c20a6..8ea27a2 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncMultiTransaction.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncMultiTransaction.java
@@ -22,11 +22,14 @@ import org.apache.curator.framework.api.transaction.CuratorOp;
import org.apache.curator.framework.api.transaction.CuratorTransactionResult;
import java.util.List;
+/**
+ * Terminal operation to support multi/transactions
+ */
public interface AsyncMultiTransaction
{
/**
- * Commit the given operations as a single transaction. Create the
- * operation instances via {@link AsyncCuratorFramework#transactionOp()}
+ * Invoke ZooKeeper to commit the given operations as a single transaction. Create the
+ * operation instances via {@link org.apache.curator.x.async.AsyncCuratorFramework#transactionOp()}
*
* @param operations operations that make up the transaction.
* @return AsyncStage instance for managing the completion
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathAndBytesable.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathAndBytesable.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathAndBytesable.java
index 7ccc1a5..cdd5d76 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathAndBytesable.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathAndBytesable.java
@@ -19,14 +19,18 @@
package org.apache.curator.x.async;
+/**
+ * Terminal operation for various builders
+ */
public interface AsyncPathAndBytesable<T> extends AsyncPathable<T>
{
/**
* Commit the currently building operation using the given path and data
+ * and invoke ZooKeeper
*
* @param path the path
* @param data the data
- * @return operation result if any
+ * @return usually an async stage
*/
T forPath(String path, byte[] data);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathable.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathable.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathable.java
index f26f3ea..8396fd6 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathable.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncPathable.java
@@ -18,13 +18,17 @@
*/
package org.apache.curator.x.async;
+/**
+ * Terminal operation for various builders
+ */
public interface AsyncPathable<T>
{
/**
* Commit the currently building operation using the given path
+ * and invoke ZooKeeper
*
* @param path the path
- * @return operation result if any
+ * @return usually an async stage
*/
T forPath(String path);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncReconfigBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncReconfigBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncReconfigBuilder.java
index f7d2eba..4be4abc 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncReconfigBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncReconfigBuilder.java
@@ -21,49 +21,97 @@ package org.apache.curator.x.async;
import org.apache.zookeeper.data.Stat;
import java.util.List;
+/**
+ * Builder for reconfigs
+ */
public interface AsyncReconfigBuilder
{
/**
* Sets one or more members that are meant to be the ensemble.
- * The expected format is server.[id]=[hostname]:[peer port]:[election port]:[type];[client port]
+ * The expected format is: <code>server.[id]=[hostname]:[peer port]:[election port]:[type];[client port]</code>
*
- * @param servers The servers joining.
+ * @param servers The new server list
* @return this
*/
AsyncEnsemblable<AsyncStage<Void>> withNewMembers(List<String> servers);
+ /**
+ * Adds servers to join the ensemble and/or servers to leave the ensemble. The format for <strong>joining</strong>
+ * is: <code>server.[id]=[hostname]:[peer port]:[election port]:[type];[client port]</code>. The format
+ * for <strong>leaving</strong> is a list of server IDs.
+ *
+ * @param joining The servers joining
+ * @param leaving The servers leaving
+ * @return this
+ */
AsyncEnsemblable<AsyncStage<Void>> withJoiningAndLeaving(List<String> joining, List<String> leaving);
/**
- * Sets one or more members that are meant to be the ensemble.
- * The expected format is server.[id]=[hostname]:[peer port]:[election port]:[type];[client port]
+ * Same as {@link #withNewMembers(java.util.List)} but allows specified the configuration version to use.
+ * By default the configuration version is -1.
*
- * @param servers The servers joining.
+ * @param servers The new server list
+ * @param fromConfig the config version to use
+ * @see #withNewMembers(java.util.List)
* @return this
*/
AsyncEnsemblable<AsyncStage<Void>> withNewMembers(List<String> servers, long fromConfig);
+ /**
+ * Specify joiners, leaves and config version. By default the configuration version is -1.
+ *
+ * @param joining The servers joining
+ * @param leaving The servers leaving
+ * @param fromConfig the config version to use
+ * @see #withJoiningAndLeaving(java.util.List, java.util.List)
+ * @return this
+ */
AsyncEnsemblable<AsyncStage<Void>> withJoiningAndLeaving(List<String> joining, List<String> leaving, long fromConfig);
/**
- * Sets one or more members that are meant to be the ensemble.
- * The expected format is server.[id]=[hostname]:[peer port]:[election port]:[type];[client port]
+ * Same as {@link #withNewMembers(java.util.List)} but allows a stat to hold the stat info from "/zookeeper/config"
*
* @param servers The servers joining.
+ * @param stat stat to hold the stat value
+ * @see #withNewMembers(java.util.List)
* @return this
*/
AsyncEnsemblable<AsyncStage<Void>> withNewMembers(List<String> servers, Stat stat);
+ /**
+ * Same as {@link #withJoiningAndLeaving(java.util.List, java.util.List)}
+ * but allows a stat to hold the stat info from "/zookeeper/config"
+ *
+ * @param joining The servers joining
+ * @param leaving The servers leaving
+ * @param stat stat to hold the stat value
+ * @see #withJoiningAndLeaving(java.util.List, java.util.List)
+ * @return this
+ */
AsyncEnsemblable<AsyncStage<Void>> withJoiningAndLeaving(List<String> joining, List<String> leaving, Stat stat);
/**
- * Sets one or more members that are meant to be the ensemble.
- * The expected format is server.[id]=[hostname]:[peer port]:[election port]:[type];[client port]
+ * Same as {@link #withNewMembers(java.util.List)} with stat and config version
*
* @param servers The servers joining.
+ * @param stat stat to hold the stat value
+ * @param fromConfig the config version to use
+ * @see #withNewMembers(java.util.List, long)
+ * @see #withNewMembers(java.util.List, org.apache.zookeeper.data.Stat)
* @return this
*/
AsyncEnsemblable<AsyncStage<Void>> withNewMembers(List<String> servers, Stat stat, long fromConfig);
+ /**
+ * Same as {@link #withJoiningAndLeaving(java.util.List, java.util.List)} with stat and config version
+ *
+ * @param joining The servers joining
+ * @param leaving The servers leaving
+ * @param stat stat to hold the stat value
+ * @param fromConfig the config version to use
+ * @see #withJoiningAndLeaving(java.util.List, java.util.List, long)
+ * @see #withJoiningAndLeaving(java.util.List, java.util.List, org.apache.zookeeper.data.Stat)
+ * @return this
+ */
AsyncEnsemblable<AsyncStage<Void>> withJoiningAndLeaving(List<String> joining, List<String> leaving, Stat stat, long fromConfig);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncRemoveWatchesBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncRemoveWatchesBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncRemoveWatchesBuilder.java
index 559d826..c73569f 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncRemoveWatchesBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncRemoveWatchesBuilder.java
@@ -22,30 +22,104 @@ import org.apache.curator.framework.api.CuratorWatcher;
import org.apache.zookeeper.Watcher;
import java.util.Set;
-public interface AsyncRemoveWatchesBuilder extends
- AsyncPathable<AsyncStage<Void>>
+/**
+ * Builder for watcher removal
+ */
+public interface AsyncRemoveWatchesBuilder
{
+ /**
+ * @param watcher the watcher to remove
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removing(Watcher watcher);
+ /**
+ * @param watcher the watcher to remove
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removing(CuratorWatcher watcher);
+ /**
+ * Remove all watchers
+ *
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removingAll();
+ /**
+ * @param watcher the watcher to remove
+ * @param options watcher removal options
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removing(Watcher watcher, Set<RemoveWatcherOption> options);
+ /**
+ * @param watcher the watcher to remove
+ * @param options watcher removal options
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removing(CuratorWatcher watcher, Set<RemoveWatcherOption> options);
+ /**
+ * Remove all watchers
+ *
+ * @param options watcher removal options
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removingAll(Set<RemoveWatcherOption> options);
+ /**
+ * Remove a watcher of a given type
+ *
+ * @param watcher the watcher to remove
+ * @param watcherType watcher type
+ * @param options watcher removal options
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removing(Watcher watcher, Watcher.WatcherType watcherType, Set<RemoveWatcherOption> options);
+ /**
+ * Remove a watcher of a given type
+ *
+ * @param watcher the watcher to remove
+ * @param watcherType watcher type
+ * @param options watcher removal options
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removing(CuratorWatcher watcher, Watcher.WatcherType watcherType, Set<RemoveWatcherOption> options);
+ /**
+ * Remove all watchers of a given type
+ *
+ * @param watcherType watcher type
+ * @param options watcher removal options
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removingAll(Watcher.WatcherType watcherType, Set<RemoveWatcherOption> options);
+ /**
+ * Remove a watcher of a given type
+ *
+ * @param watcher the watcher to remove
+ * @param watcherType watcher type
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removing(Watcher watcher, Watcher.WatcherType watcherType);
+ /**
+ * Remove a watcher of a given type
+ *
+ * @param watcher the watcher to remove
+ * @param watcherType watcher type
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removing(CuratorWatcher watcher, Watcher.WatcherType watcherType);
+ /**
+ * Remove all watchers of a given type
+ *
+ * @param watcherType watcher type
+ * @return this
+ */
AsyncPathable<AsyncStage<Void>> removingAll(Watcher.WatcherType watcherType);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetACLBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetACLBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetACLBuilder.java
index 274e7b7..c2ad6be 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetACLBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetACLBuilder.java
@@ -22,9 +22,27 @@ import org.apache.zookeeper.data.ACL;
import org.apache.zookeeper.data.Stat;
import java.util.List;
+/**
+ * Builder for setting ACLs
+ */
public interface AsyncSetACLBuilder
{
+ /**
+ * Set the given ACLs
+ *
+ * @param aclList ACLs to set
+ * @return this
+ */
AsyncPathable<AsyncStage<Stat>> withACL(List<ACL> aclList);
+ /**
+ * Set the given ACLs only if the "a" version matches. By default -1 is used
+ * which matches all versions.
+ *
+ * @param aclList ACLs to set
+ * @param version "a" version
+ * @see org.apache.zookeeper.data.Stat#getAversion()
+ * @return this
+ */
AsyncPathable<AsyncStage<Stat>> withACL(List<ACL> aclList, int version);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetDataBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetDataBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetDataBuilder.java
index 90935cd..a1f0ff5 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetDataBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSetDataBuilder.java
@@ -20,6 +20,9 @@ package org.apache.curator.x.async;
import org.apache.zookeeper.data.Stat;
+/**
+ * Builder for setting ZNode data
+ */
public interface AsyncSetDataBuilder extends AsyncPathAndBytesable<AsyncStage<Stat>>
{
/**
@@ -29,7 +32,22 @@ public interface AsyncSetDataBuilder extends AsyncPathAndBytesable<AsyncStage<St
*/
AsyncPathAndBytesable<AsyncStage<Stat>> compressed();
+ /**
+ * Cause the data to be compressed using the configured compression provider.
+ * Only sets if the version matches. By default -1 is used
+ * which matches all versions.
+ *
+ * @param version version
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<Stat>> compressedWithVersion(int version);
+ /**
+ * Only sets if the version matches. By default -1 is used
+ * which matches all versions.
+ *
+ * @param version version
+ * @return this
+ */
AsyncPathAndBytesable<AsyncStage<Stat>> withVersion(int version);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncStage.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncStage.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncStage.java
index 5f83d9c..a8d594a 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncStage.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncStage.java
@@ -21,7 +21,17 @@ package org.apache.curator.x.async;
import org.apache.zookeeper.WatchedEvent;
import java.util.concurrent.CompletionStage;
+/**
+ * A {@link java.util.concurrent.CompletionStage} that is the result of most operations.
+ */
public interface AsyncStage<T> extends CompletionStage<T>
{
+ /**
+ * If the {@link org.apache.curator.x.async.WatchedAsyncCuratorFramework} facade is
+ * used (via {@link AsyncCuratorFramework#watched()}), this returns the completion
+ * stage used when the watcher is triggered
+ *
+ * @return CompletionStage for the set watcher or <code>null</code>
+ */
CompletionStage<WatchedEvent> event();
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSyncBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSyncBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSyncBuilder.java
index 9a218aa..98da505 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSyncBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncSyncBuilder.java
@@ -18,6 +18,9 @@
*/
package org.apache.curator.x.async;
+/**
+ * Builder for syncs
+ */
public interface AsyncSyncBuilder extends
AsyncPathable<AsyncStage<Void>>
{
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCheckBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCheckBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCheckBuilder.java
index eeb57e4..36b7418 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCheckBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCheckBuilder.java
@@ -20,8 +20,10 @@ package org.apache.curator.x.async;
import org.apache.curator.framework.api.transaction.CuratorOp;
-public interface AsyncTransactionCheckBuilder extends
- AsyncPathable<CuratorOp>
+/**
+ * @see org.apache.curator.x.async.AsyncTransactionOp#check()
+ */
+public interface AsyncTransactionCheckBuilder extends AsyncPathable<CuratorOp>
{
/**
* Use the given version (the default is -1)
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCreateBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCreateBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCreateBuilder.java
index d852e76..dc71881 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCreateBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionCreateBuilder.java
@@ -23,6 +23,9 @@ import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.data.ACL;
import java.util.List;
+/**
+ * @see org.apache.curator.x.async.AsyncTransactionOp#create()
+ */
public interface AsyncTransactionCreateBuilder extends AsyncPathAndBytesable<CuratorOp>
{
AsyncPathable<CuratorOp> withMode(CreateMode createMode);
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionDeleteBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionDeleteBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionDeleteBuilder.java
index f4f68d4..470690d 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionDeleteBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionDeleteBuilder.java
@@ -20,8 +20,10 @@ package org.apache.curator.x.async;
import org.apache.curator.framework.api.transaction.CuratorOp;
-public interface AsyncTransactionDeleteBuilder extends
- AsyncPathable<CuratorOp>
+/**
+ * @see org.apache.curator.x.async.AsyncTransactionOp#delete()
+ */
+public interface AsyncTransactionDeleteBuilder extends AsyncPathable<CuratorOp>
{
AsyncPathable<CuratorOp> withVersion(int version);
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionSetDataBuilder.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionSetDataBuilder.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionSetDataBuilder.java
index 8f91f10..5cfddcf 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionSetDataBuilder.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionSetDataBuilder.java
@@ -20,8 +20,10 @@ package org.apache.curator.x.async;
import org.apache.curator.framework.api.transaction.CuratorOp;
-public interface AsyncTransactionSetDataBuilder extends
- AsyncPathAndBytesable<CuratorOp>
+/**
+ * @see org.apache.curator.x.async.AsyncTransactionOp#setData()
+ */
+public interface AsyncTransactionSetDataBuilder extends AsyncPathAndBytesable<CuratorOp>
{
AsyncPathAndBytesable<CuratorOp> withVersion(int version);
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/ExistsOption.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/ExistsOption.java b/curator-x-async/src/main/java/org/apache/curator/x/async/ExistsOption.java
new file mode 100644
index 0000000..5994b96
--- /dev/null
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/ExistsOption.java
@@ -0,0 +1,7 @@
+package org.apache.curator.x.async;
+
+public enum ExistsOption
+{
+ createParentsIfNeeded,
+ createParentsAsContainers
+}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncDeleteBuilderImpl.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncDeleteBuilderImpl.java b/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncDeleteBuilderImpl.java
index 7395915..06363db 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncDeleteBuilderImpl.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncDeleteBuilderImpl.java
@@ -39,7 +39,7 @@ class AsyncDeleteBuilderImpl implements AsyncDeleteBuilder
private Set<DeleteOption> options = Collections.emptySet();
private int version = -1;
- public AsyncDeleteBuilderImpl(CuratorFrameworkImpl client, UnhandledErrorListener unhandledErrorListener)
+ AsyncDeleteBuilderImpl(CuratorFrameworkImpl client, UnhandledErrorListener unhandledErrorListener)
{
this.client = client;
this.unhandledErrorListener = unhandledErrorListener;
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncExistsBuilderImpl.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncExistsBuilderImpl.java b/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncExistsBuilderImpl.java
index e8b529a..4cf8e2d 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncExistsBuilderImpl.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncExistsBuilderImpl.java
@@ -24,7 +24,11 @@ import org.apache.curator.framework.imps.ExistsBuilderImpl;
import org.apache.curator.x.async.AsyncExistsBuilder;
import org.apache.curator.x.async.AsyncPathable;
import org.apache.curator.x.async.AsyncStage;
+import org.apache.curator.x.async.ExistsOption;
import org.apache.zookeeper.data.Stat;
+import java.util.Collections;
+import java.util.Objects;
+import java.util.Set;
import static org.apache.curator.x.async.details.BackgroundProcs.safeCall;
import static org.apache.curator.x.async.details.BackgroundProcs.safeStatProc;
@@ -34,8 +38,7 @@ class AsyncExistsBuilderImpl implements AsyncExistsBuilder
private final CuratorFrameworkImpl client;
private final UnhandledErrorListener unhandledErrorListener;
private final boolean watched;
- private boolean createParentsIfNeeded = false;
- private boolean createParentContainersIfNeeded = false;
+ private Set<ExistsOption> options = Collections.emptySet();
AsyncExistsBuilderImpl(CuratorFrameworkImpl client, UnhandledErrorListener unhandledErrorListener, boolean watched)
{
@@ -45,16 +48,9 @@ class AsyncExistsBuilderImpl implements AsyncExistsBuilder
}
@Override
- public AsyncPathable<AsyncStage<Stat>> creatingParentsIfNeeded()
+ public AsyncPathable<AsyncStage<Stat>> withOptions(Set<ExistsOption> options)
{
- createParentsIfNeeded = true;
- return this;
- }
-
- @Override
- public AsyncPathable<AsyncStage<Stat>> creatingParentContainersIfNeeded()
- {
- createParentContainersIfNeeded = true;
+ this.options = Objects.requireNonNull(options, "options cannot be null");
return this;
}
@@ -62,7 +58,7 @@ class AsyncExistsBuilderImpl implements AsyncExistsBuilder
public AsyncStage<Stat> forPath(String path)
{
BuilderCommon<Stat> common = new BuilderCommon<>(unhandledErrorListener, watched, safeStatProc);
- ExistsBuilderImpl builder = new ExistsBuilderImpl(client, common.backgrounding, common.watcher, createParentsIfNeeded, createParentContainersIfNeeded);
+ ExistsBuilderImpl builder = new ExistsBuilderImpl(client, common.backgrounding, common.watcher, options.contains(ExistsOption.createParentsIfNeeded), options.contains(ExistsOption.createParentsAsContainers));
return safeCall(common.internalCallback, () -> builder.forPath(path));
}
}
http://git-wip-us.apache.org/repos/asf/curator/blob/6d055e96/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncRemoveWatchesBuilderImpl.java
----------------------------------------------------------------------
diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncRemoveWatchesBuilderImpl.java b/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncRemoveWatchesBuilderImpl.java
index 4e6b41c..ae5bb09 100644
--- a/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncRemoveWatchesBuilderImpl.java
+++ b/curator-x-async/src/main/java/org/apache/curator/x/async/details/AsyncRemoveWatchesBuilderImpl.java
@@ -34,7 +34,7 @@ import java.util.Set;
import static org.apache.curator.x.async.details.BackgroundProcs.ignoredProc;
import static org.apache.curator.x.async.details.BackgroundProcs.safeCall;
-class AsyncRemoveWatchesBuilderImpl implements AsyncRemoveWatchesBuilder
+class AsyncRemoveWatchesBuilderImpl implements AsyncRemoveWatchesBuilder, AsyncPathable<AsyncStage<Void>>
{
private final CuratorFrameworkImpl client;
private final UnhandledErrorListener unhandledErrorListener;