more doc work
Project: http://git-wip-us.apache.org/repos/asf/curator/repo Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/b813fb35 Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/b813fb35 Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/b813fb35 Branch: refs/heads/master Commit: b813fb3502896a088c6e18a1d442bef127fe9e51 Parents: 88fee0e Author: randgalt <[email protected]> Authored: Sat Jan 7 12:27:11 2017 -0500 Committer: randgalt <[email protected]> Committed: Sat Jan 7 12:27:11 2017 -0500 ---------------------------------------------------------------------- .../src/site/confluence/index.confluence | 71 +++++++++++++++++++- 1 file changed, 70 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/curator/blob/b813fb35/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 88f649e..9c02e8e 100644 --- a/curator-x-async/src/site/confluence/index.confluence +++ b/curator-x-async/src/site/confluence/index.confluence @@ -18,7 +18,7 @@ With this new async DSL you can do asynchronous tasks in a more natural, functio {code} // let "client" be a CuratorFramework instance AsyncCuratorFramework async = AsyncCuratorFramework.wrap(client); -async.checkExists().forPath(somePath).thenRun(() -> mySuccessOperation()); +async.checkExists().forPath(somePath).thenAccept(stat -> mySuccessOperation(stat)); {code} h2. Usage @@ -95,3 +95,72 @@ stage.event().exceptionally(e -> { asyncEx.reset().thenRun(() -> successMethod()); }); {code} + +h2. Examples + +Create a sequential ZNode and, once successfully completed, set a watcher +on the ZNode. Note: this code does not deal with errors. Should a connection +problem occur or another exception occur, the completion lambda will never be called. + +{code} +async.create().withMode(PERSISTENT_SEQUENTIAL).forPath(path).thenAccept(actualPath -> + async.watched().getData().forPath(actualPath)); +{code} + +---- + +This is the canonical way to deal with AsyncStage. Use the handle() method which provides +both the success value and the exception. The exception will be non\-null on error. + +{code} +async.create().withOptions(EnumSet.of(doProtected)).forPath(path).handle((actualPath, exception) -> { + if ( exception != null ) + { + // handle problem + } + else + { + // actualPath is the path created + } + return null; +}); +{code} + +---- + +Your completion routines can operate in a separate thread if you provide an executor. + +{code} +async.create().withOptions(EnumSet.of(createParentsIfNeeded)).forPath("/a/b/c") + .thenAcceptAsync(path -> handleCreate(path), executor); +{code} + +---- + +This example shows specifying separate completion handlers for success and exception. + +{code} +AsyncStage<byte[]> stage = async.getData().forPath("/my/path"); +stage.exceptionally(e -> { + if ( e instanceof KeeperException.NoNodeException ) + { + // handle no node + } + else + { + // handle other + } + return null; +}); +stage.thenAccept(data -> processData(data)); +{code} + +---- + +CompletionStage provides a block method as well so that you can block to get the result +of an operation. i.e. this makes it possible to use the async APIs in a synchronous way. + +{code} +// NOTE: get() specifies a checked exception +async.create().forPath("/foo").toCompletableFuture().get(); +{code}
