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:30 UTC
[31/47] curator git commit: added doxia doc
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 <ra...@apache.org>
Authored: Sat Jan 7 11:26:35 2017 -0500
Committer: randgalt <ra...@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">