added doxia doc
Project: http://git-wip-us.apache.org/repos/asf/curator/repo Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/908b5c6c Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/908b5c6c Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/908b5c6c Branch: refs/heads/CURATOR-3.0 Commit: 908b5c6c2768b9135de05d67ed80db8af7b310a4 Parents: e8d1352 Author: randgalt <randg...@apache.org> Authored: Sat Jan 7 11:26:35 2017 -0500 Committer: randgalt <randg...@apache.org> Committed: Sat Jan 7 11:26:35 2017 -0500 ---------------------------------------------------------------------- .../src/site/confluence/index.confluence | 97 ++++++++++++++++++++ curator-x-async/src/site/site.xml | 33 +++++++ .../curator/framework/imps/TestFramework.java | 18 ++++ .../framework/imps/TestFrameworkBackground.java | 18 ++++ .../curator/x/async/TestBasicOperations.java | 14 +++ curator-x-rpc/src/site/site.xml | 2 +- pom.xml | 2 +- src/site/site.xml | 1 + 8 files changed, 183 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/curator/blob/908b5c6c/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 new file mode 100644 index 0000000..7e1449b --- /dev/null +++ b/curator-x-async/src/site/confluence/index.confluence @@ -0,0 +1,97 @@ +h1. Curator Async + +h2. Packaging + +Curator Async is in its own package in Maven Central: curator\-x\-async + +h2. What Is a Curator Async? + +Curator Async is a brand new [DSL|https://en.wikipedia.org/wiki/Domain-specific_language] that wraps existing +{{CuratorFramework}} instances. This new DSL is entirely asynchronous and uses +[Java 8's CompletionStage|https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html] +mechanism for chaining, composing, etc. Additionally, Curator's original DSL has been cleaned up +and simplified, in particular for operations such as {{create()}}. + +With this new async DSL you can do asynchronous tasks in a more natural, functional way using +[Java 8 lambdas|https://docs.oracle.com/javase/tutorial/java/javaOO/lambdaexpressions.html]. For example: + +{code} +// let "client" be a CuratorFramework instance +AsyncCuratorFramework async = AsyncCuratorFramework.wrap(client); +async.checkExists().forPath(somePath).thenRun(() -> mySuccessOperation()); +{code} + +h2. Usage + +Note: To use Curator Async, you should be familiar with Java 8's lambdas, CompletedFuture and CompletionStage. + +Create a CuratorFramework instance in the normal way. You then wrap this instance using +AsyncCuratorFramework. i.e. + +{code} +// let "client" be a CuratorFramework instance +AsyncCuratorFramework async = AsyncCuratorFramework.wrap(client); +{code} + +AsyncCuratorFramework has most of the same builder methods that CuratorFramework does with some important +differences: + +* AsyncCuratorFramework builders return {{AsyncStage}} instances +* AsyncCuratorFramework builders have no checked exceptions +* Many of the builder methods have been simplified/clarified +* All builders invoke the asynchronous versions of ZooKeeper APIs +* Watchers also use CompletionStages \- see below for details + +h4. AsyncStage + +AsyncStage instances extend Java 8's CompletionStage. CompletionStage objects can be "completed" with a success +value or an exception. The parameterized type of the AsyncStage will +be whatever the builder used would naturally return as a success value. E.g. the async getData() builder's AsyncStage is +parameterized with {{byte[]}}. For the exception, Curator Async always uses AsyncEventException (see below). + +h4. Watchers + +ZooKeeper watchers also get the CompletionStage treatment in Curator Async. To add a watcher, call +watched() prior to starting the appropriate builders. E.g. + +{code} +async.watched().getData().forPath(path) ... +{code} + +Thus, a data watcher will be set on the specified path. You access the CompletionStage for the watcher +by using the event() method of AsyncStage. Here is a complete example: + +{code} +async.watched().getData().forPath(path).event().thenAccept(watchedEvent -> watchWasTriggered(watchedEvent)); +{code} + +ZooKeeper calls watchers when there is a connection loss. This can make using the CompletionStage +somewhat complicated (see AsyncEventException below). If you are not interested in watcher connection +problems, you can tell Curator Async to not send them by calling: + +{code} +// only complete the CompletionStage when the watcher is successfully triggered +// i.e. don't complete on connection issues +async.watched(WatchMode.successOnly)... +{code} + +h4. AsyncEventException + +When an async watcher fails the exception set in the CompletionStage will be of type {{AsyncEventException}}. +This exception allows you to see the KeeperState that caused the trigger and allows you to reset the +completion stage. Reset is needed because ZooKeeper temporarily triggers watchers when there is a connection +event. However, the watcher stays set for the original operation. Use {{AsyncEventException#reset()}} +to start a new completion stage that will wait on the next trigger of the watcher. + +E.g. + +{code} +AsyncStage stage = ... +stage.event().exceptionally(e -> { + AsyncEventException asyncEx = (AsyncEventException)e; + + ... noteAConnectionProblem ... + + asyncEx.reset().thenRun(() -> successMethod()); +}); +{code} http://git-wip-us.apache.org/repos/asf/curator/blob/908b5c6c/curator-x-async/src/site/site.xml ---------------------------------------------------------------------- diff --git a/curator-x-async/src/site/site.xml b/curator-x-async/src/site/site.xml new file mode 100644 index 0000000..63fccaa --- /dev/null +++ b/curator-x-async/src/site/site.xml @@ -0,0 +1,33 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +--> +<project xmlns="http://maven.apache.org/DECORATION/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/DECORATION/1.1.0 http://maven.apache.org/xsd/decoration-1.1.0.xsd" name="Curator Async"> + <body> + <head> + <link rel="stylesheet" href="../css/site.css" /> + <script type="text/javascript"> + $(function(){ + $('a[title="Curator RPC Proxy"]').parent().addClass("active"); + }); + </script> + </head> + </body> +</project> http://git-wip-us.apache.org/repos/asf/curator/blob/908b5c6c/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFramework.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFramework.java b/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFramework.java index cd2f598..adc85da 100644 --- a/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFramework.java +++ b/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFramework.java @@ -1,3 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ package org.apache.curator.framework.imps; import com.google.common.collect.Lists; http://git-wip-us.apache.org/repos/asf/curator/blob/908b5c6c/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFrameworkBackground.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFrameworkBackground.java b/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFrameworkBackground.java index ce41d08..52c3faa 100644 --- a/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFrameworkBackground.java +++ b/curator-x-async/src/test/java/org/apache/curator/framework/imps/TestFrameworkBackground.java @@ -1,3 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ package org.apache.curator.framework.imps; import com.google.common.collect.Lists; http://git-wip-us.apache.org/repos/asf/curator/blob/908b5c6c/curator-x-async/src/test/java/org/apache/curator/x/async/TestBasicOperations.java ---------------------------------------------------------------------- diff --git a/curator-x-async/src/test/java/org/apache/curator/x/async/TestBasicOperations.java b/curator-x-async/src/test/java/org/apache/curator/x/async/TestBasicOperations.java index d66db72..34c02aa 100644 --- a/curator-x-async/src/test/java/org/apache/curator/x/async/TestBasicOperations.java +++ b/curator-x-async/src/test/java/org/apache/curator/x/async/TestBasicOperations.java @@ -24,6 +24,7 @@ import org.apache.curator.retry.RetryOneTime; import org.apache.curator.test.BaseClassForTests; import org.apache.curator.test.Timing; import org.apache.curator.utils.CloseableUtils; +import org.apache.zookeeper.KeeperException; import org.apache.zookeeper.Watcher; import org.apache.zookeeper.data.Stat; import org.testng.Assert; @@ -91,6 +92,19 @@ public class TestBasicOperations extends BaseClassForTests } @Test + public void testException() + { + CountDownLatch latch = new CountDownLatch(1); + client.getData().forPath("/woop").exceptionally(e -> { + Assert.assertTrue(e instanceof KeeperException); + Assert.assertEquals(((KeeperException)e).code(), KeeperException.Code.NONODE); + latch.countDown(); + return null; + }); + Assert.assertTrue(timing.awaitLatch(latch)); + } + + @Test public void testWatching() { CountDownLatch latch = new CountDownLatch(1); http://git-wip-us.apache.org/repos/asf/curator/blob/908b5c6c/curator-x-rpc/src/site/site.xml ---------------------------------------------------------------------- diff --git a/curator-x-rpc/src/site/site.xml b/curator-x-rpc/src/site/site.xml index fca1e73..135c902 100644 --- a/curator-x-rpc/src/site/site.xml +++ b/curator-x-rpc/src/site/site.xml @@ -25,7 +25,7 @@ <link rel="stylesheet" href="../css/site.css" /> <script type="text/javascript"> $(function(){ - $('a[title="Curator RPC Proxy"]').parent().addClass("active"); + $('a[title="Curator Async"]').parent().addClass("active"); }); </script> </head> http://git-wip-us.apache.org/repos/asf/curator/blob/908b5c6c/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index 832fce1..b930b3b 100644 --- a/pom.xml +++ b/pom.xml @@ -61,7 +61,7 @@ <!-- versions --> <zookeeper-version>3.5.1-alpha</zookeeper-version> <maven-project-info-reports-plugin-version>2.7</maven-project-info-reports-plugin-version> - <maven-bundle-plugin-version>2.3.7</maven-bundle-plugin-version> + <maven-bundle-plugin-version>3.2.0</maven-bundle-plugin-version> <maven-javadoc-plugin-version>2.10.3</maven-javadoc-plugin-version> <doxia-module-confluence-version>1.6</doxia-module-confluence-version> <maven-license-plugin-version>1.9.0</maven-license-plugin-version> http://git-wip-us.apache.org/repos/asf/curator/blob/908b5c6c/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index c28df31..222ffde 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -94,6 +94,7 @@ <item name="Service Discovery" href="curator-x-discovery/index.html"/> <item name="Service Discovery Server" href="curator-x-discovery-server/index.html"/> <item name="Curator RPC Proxy" href="curator-x-rpc/index.html"/> + <item name="Curator Async" href="curator-x-async/index.html"/> </menu> <menu name="Community" inherit="top">