finished doc
Project: http://git-wip-us.apache.org/repos/asf/curator/repo Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/e7a7e538 Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/e7a7e538 Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/e7a7e538 Branch: refs/heads/CURATOR-3.0 Commit: e7a7e538617708a97edf9201aa9d287cd07e78de Parents: 6d055e9 Author: randgalt <randg...@apache.org> Authored: Fri Jan 6 15:52:41 2017 -0500 Committer: randgalt <randg...@apache.org> Committed: Fri Jan 6 15:52:41 2017 -0500 ---------------------------------------------------------------------- .../curator/x/async/AsyncDeleteBuilder.java | 2 +- .../x/async/AsyncTransactionCheckBuilder.java | 2 +- .../x/async/AsyncTransactionCreateBuilder.java | 28 ++++++++++++ .../x/async/AsyncTransactionDeleteBuilder.java | 6 +++ .../curator/x/async/AsyncTransactionOp.java | 4 +- .../x/async/AsyncTransactionSetDataBuilder.java | 18 ++++++++ .../apache/curator/x/async/CreateOption.java | 48 ++++++++++++++++++++ .../apache/curator/x/async/DeleteOption.java | 18 ++++++++ .../apache/curator/x/async/ExistsOption.java | 10 ++++ .../curator/x/async/RemoveWatcherOption.java | 19 ++++++++ .../x/async/WatchedAsyncCuratorFramework.java | 6 +-- 11 files changed, 152 insertions(+), 9 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/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 e8c4ac5..c16cbe2 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 @@ -45,7 +45,7 @@ public interface AsyncDeleteBuilder extends AsyncPathable<AsyncStage<Void>> AsyncPathable<AsyncStage<Void>> withOptionsAndVersion(Set<DeleteOption> options, int version); /** - * Changes the version number passed to the delete() method. By default, -1 is ued + * Changes the version number passed to the delete() method. By default, -1 is used * * @param version version to use * @return this http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/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 36b7418..ece505c 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 @@ -21,7 +21,7 @@ package org.apache.curator.x.async; import org.apache.curator.framework.api.transaction.CuratorOp; /** - * @see org.apache.curator.x.async.AsyncTransactionOp#check() + * @see org.apache.curator.x.async.AsyncTransactionOp#check() */ public interface AsyncTransactionCheckBuilder extends AsyncPathable<CuratorOp> { http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/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 dc71881..b39d69e 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 @@ -28,11 +28,39 @@ import java.util.List; */ public interface AsyncTransactionCreateBuilder extends AsyncPathAndBytesable<CuratorOp> { + /** + * Specify a mode for the create. The default is {@link org.apache.zookeeper.CreateMode#PERSISTENT} + * + * @param createMode mode + * @return this + */ AsyncPathable<CuratorOp> 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 + */ AsyncPathable<CuratorOp> withACL(List<ACL> aclList); + /** + * Cause the data to be compressed using the configured compression provider + * + * @return this + */ AsyncPathable<CuratorOp> compressed(); + /** + * Specify mode, acl list and compression + * + * @param createMode mode + * @param aclList the ACL list to use + * @param compressed true to compress + * @see #withMode(org.apache.zookeeper.CreateMode) + * @see #withACL(java.util.List) + * @see #compressed() + * @return this + */ AsyncPathable<CuratorOp> withOptions(CreateMode createMode, List<ACL> aclList, boolean compressed); } http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/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 470690d..c49d42e 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 @@ -25,5 +25,11 @@ import org.apache.curator.framework.api.transaction.CuratorOp; */ public interface AsyncTransactionDeleteBuilder extends AsyncPathable<CuratorOp> { + /** + * Changes the version number used. By default, -1 is used + * + * @param version version to use + * @return this + */ AsyncPathable<CuratorOp> withVersion(int version); } http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionOp.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionOp.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionOp.java index 2e2f886..a659d6f 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionOp.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncTransactionOp.java @@ -18,11 +18,9 @@ */ package org.apache.curator.x.async; -import org.apache.curator.framework.CuratorFramework; - /** * Builds operations that can be committed as a transaction - * via {@link CuratorFramework#transaction()} + * via {@link org.apache.curator.x.async.AsyncCuratorFramework#transaction()} */ public interface AsyncTransactionOp { http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/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 5cfddcf..5fce4d5 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 @@ -25,9 +25,27 @@ import org.apache.curator.framework.api.transaction.CuratorOp; */ public interface AsyncTransactionSetDataBuilder extends AsyncPathAndBytesable<CuratorOp> { + /** + * Changes the version number used. By default, -1 is used + * + * @param version version to use + * @return this + */ AsyncPathAndBytesable<CuratorOp> withVersion(int version); + /** + * Cause the data to be compressed using the configured compression provider + * + * @return this + */ AsyncPathAndBytesable<CuratorOp> compressed(); + /** + * Cause the data to be compressed using the configured compression provider. + * Also changes the version number used. By default, -1 is used + * + * @param version version to use + * @return this + */ AsyncPathAndBytesable<CuratorOp> withVersionCompressed(int version); } http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/curator-x-async/src/main/java/org/apache/curator/x/async/CreateOption.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/CreateOption.java b/curator-x-async/src/main/java/org/apache/curator/x/async/CreateOption.java index 4397b71..560c901 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/CreateOption.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/CreateOption.java @@ -18,11 +18,59 @@ */ package org.apache.curator.x.async; +/** + * Options when creating ZNodes + */ public enum CreateOption { + /** + * Causes any parent nodes to get created if they haven't already been + */ createParentsIfNeeded, + + /** + * Causes any parent nodes to get created using {@link org.apache.zookeeper.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. + */ createParentsAsContainers, + + /** + * <p> + * Hat-tip to https://github.com/sbridges for pointing this out + * </p> + * + * <p> + * It turns out there is an edge case that exists when creating sequential-ephemeral + * nodes. The creation can succeed on the server, but the server can crash before + * the created node name is returned to the client. However, the ZK session is still + * valid so the ephemeral node is not deleted. Thus, there is no way for the client to + * determine what node was created for them. + * </p> + * + * <p> + * Even without sequential-ephemeral, however, the create can succeed on the sever + * but the client (for various reasons) will not know it. + * </p> + * + * <p> + * Putting the create builder into protection mode works around this. + * The name of the node that is created is prefixed with a GUID. If node creation fails + * the normal retry mechanism will occur. On the retry, the parent path is first searched + * for a node that has the GUID in it. If that node is found, it is assumed to be the lost + * node that was successfully created on the first try and is returned to the caller. + * </p> + */ doProtected, + + /** + * Cause the data to be compressed using the configured compression provider + */ compress, + + /** + * If the ZNode already exists, Curator will instead call setData() + */ setDataIfExists } http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/curator-x-async/src/main/java/org/apache/curator/x/async/DeleteOption.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/DeleteOption.java b/curator-x-async/src/main/java/org/apache/curator/x/async/DeleteOption.java index 6a58598..1e8dfbd 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/DeleteOption.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/DeleteOption.java @@ -18,9 +18,27 @@ */ package org.apache.curator.x.async; +/** + * Options to use when deleting ZNodes + */ public enum DeleteOption { + /** + * Prevents the reporting of {@link org.apache.zookeeper.KeeperException.NoNodeException}s. + * If the ZNode doesn't exist the delete method will appear to succeed. + */ quietly, + + /** + * Will also delete children if they exist + */ deletingChildrenIfNeeded, + + /** + * Solves edge cases where an operation may succeed on the server but connection failure occurs before a + * response can be successfully returned to the client. + * + * @see org.apache.curator.framework.api.GuaranteeableDeletable + */ guaranteed } http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/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 index 5994b96..41533cf 100644 --- 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 @@ -1,7 +1,17 @@ package org.apache.curator.x.async; +/** + * Options to use when checking for ZNode existence + */ public enum ExistsOption { + /** + * see {@link org.apache.curator.x.async.CreateOption#createParentsIfNeeded} + */ createParentsIfNeeded, + + /** + * see {@link org.apache.curator.x.async.CreateOption#createParentsAsContainers} + */ createParentsAsContainers } http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/curator-x-async/src/main/java/org/apache/curator/x/async/RemoveWatcherOption.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/RemoveWatcherOption.java b/curator-x-async/src/main/java/org/apache/curator/x/async/RemoveWatcherOption.java index 0603da2..f1c01a4 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/RemoveWatcherOption.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/RemoveWatcherOption.java @@ -18,9 +18,28 @@ */ package org.apache.curator.x.async; +/** + * Options to use when removing watchers + */ public enum RemoveWatcherOption { + /** + * Solves edge cases where an operation may succeed on the server but connection failure occurs before a + * response can be successfully returned to the client. + * + * @see org.apache.curator.framework.api.GuaranteeableDeletable + */ guaranteed, + + /** + * Specify if the client should just remove client side watches if a connection to ZK + * is not available. Note that the standard Curator retry loop will not be used in t + */ local, + + /** + * Prevents the reporting of {@link org.apache.zookeeper.KeeperException.NoNodeException}s. + * If the watcher doesn't exist the remove method will appear to succeed. + */ quietly } http://git-wip-us.apache.org/repos/asf/curator/blob/e7a7e538/curator-x-async/src/main/java/org/apache/curator/x/async/WatchedAsyncCuratorFramework.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/WatchedAsyncCuratorFramework.java b/curator-x-async/src/main/java/org/apache/curator/x/async/WatchedAsyncCuratorFramework.java index 8e8618d..92ab2bb 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/WatchedAsyncCuratorFramework.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/WatchedAsyncCuratorFramework.java @@ -19,14 +19,12 @@ package org.apache.curator.x.async; /** - * Zookeeper framework-style client + * operations that support watching */ public interface WatchedAsyncCuratorFramework { /** - * Start an exists builder - * <p> - * The builder will return a Stat object as if org.apache.zookeeper.ZooKeeper.exists() were called. Thus, a null + * Start an exists builder. The builder will return a Stat object as if org.apache.zookeeper.ZooKeeper.exists() were called. Thus, a null * means that it does not exist and an actual Stat object means it does exist. * * @return builder object
