Added doc
Project: http://git-wip-us.apache.org/repos/asf/curator/repo Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/42d2f457 Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/42d2f457 Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/42d2f457 Branch: refs/heads/CURATOR-3.0 Commit: 42d2f4577f2103ab3f522634c66941ea4521c25a Parents: 649c441 Author: randgalt <randg...@apache.org> Authored: Sat Jan 21 17:57:04 2017 -0500 Committer: randgalt <randg...@apache.org> Committed: Sat Jan 21 17:57:04 2017 -0500 ---------------------------------------------------------------------- .../org/apache/curator/x/async/AsyncResult.java | 2 +- .../src/site/confluence/index.confluence | 48 ++++++++++++++++++++ 2 files changed, 49 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/curator/blob/42d2f457/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncResult.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncResult.java b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncResult.java index 5c99480..c264269 100644 --- a/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncResult.java +++ b/curator-x-async/src/main/java/org/apache/curator/x/async/AsyncResult.java @@ -27,7 +27,7 @@ import java.util.concurrent.CompletionStage; * <p> * Utility that combines the value, the ZooKeeper result code and the exception in one object * allowing you to not worry about exceptional completions. i.e. the {@link java.util.concurrent.CompletionStage} - * retured by {@link org.apache.curator.x.async.AsyncResult#of(AsyncStage)} always completes successfully with an + * returned by {@link org.apache.curator.x.async.AsyncResult#of(AsyncStage)} always completes successfully with an * {@link org.apache.curator.x.async.AsyncResult} object. * </p> * http://git-wip-us.apache.org/repos/asf/curator/blob/42d2f457/curator-x-async/src/site/confluence/index.confluence ---------------------------------------------------------------------- diff --git a/curator-x-async/src/site/confluence/index.confluence b/curator-x-async/src/site/confluence/index.confluence index ca3c07e..c946805 100644 --- a/curator-x-async/src/site/confluence/index.confluence +++ b/curator-x-async/src/site/confluence/index.confluence @@ -96,6 +96,37 @@ stage.event().exceptionally(e -> { }); {code} +h4. AsyncResult + +As a convenience, you can use {{AsyncResult}} to combine ZooKeeper method value, the ZooKeeper result +code and any exception in one object allowing you to not worry about exceptional completions. i.e. the {{CompletionStage}} +retured by {{AsyncResult.of()}} always completes successfully with an AsyncResult object. + +AsyncResult has methods to get either the method result (a path, Stat, etc.), a KeeperException code +or a general exception: + +{code} +Optional<T> getValue(); + +KeeperException.Code getCode(); + +Optional<Throwable> getException(); +{code} + +Use AsyncResult by wrapping an {{AsyncStage}} value. i.e. + +{code} +CompletionStage<AsyncResult<Stat>> resultStage = AsyncResult.of(async.checkExists().forPath(path)); +resultStage.thenAccept(result -> { + if ( result.getValue().isPresent() ) { + // ... + } else if ( result.getCode() == KeeperException.Code.NOAUTH ) { + // ... + } + // etc. +}); +{code} + h2. Examples h4. Create a sequential ZNode @@ -132,6 +163,23 @@ async.create().withOptions(EnumSet.of(doProtected)).forPath(path).handle((actual ---- +h4. Simplied usage via AsyncResult + +{code} +AsyncResult.of(async.create().withOptions(EnumSet.of(doProtected)).forPath(path)).thenAccept(result -> { + if ( result.getRawValue() != null ) + { + // result.getRawValue() is the path created + } + else + { + // ... + } +}); +{code} + +---- + h4. Using executors Your completion routines can operate in a separate thread if you provide an executor.