More tests, refined tests and doc
Project: http://git-wip-us.apache.org/repos/asf/curator/repo Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/89182ed1 Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/89182ed1 Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/89182ed1 Branch: refs/heads/CURATOR-426 Commit: 89182ed11a8f6ff4fa5ec9cc955ff68241076f5d Parents: d1a6507 Author: randgalt <randg...@apache.org> Authored: Thu Jul 20 13:40:30 2017 -0500 Committer: randgalt <randg...@apache.org> Committed: Thu Jul 20 13:40:30 2017 -0500 ---------------------------------------------------------------------- .../framework/imps/CreateBuilderImpl.java | 2 + .../framework/imps/CuratorFrameworkImpl.java | 3 + .../framework/imps/WatcherRemovalManager.java | 5 + .../java/org/apache/curator/test/DummyTest.java | 30 ------ .../apache/curator/test/TestCompatibility.java | 97 +++++++++++++++++++ src/site/confluence/compatibility.confluence | 53 ++++++++-- src/site/confluence/index.confluence | 22 ++--- src/site/resources/images/arrow.png | Bin 0 -> 2159 bytes src/site/site.xml | 7 +- 9 files changed, 164 insertions(+), 55 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/curator-framework/src/main/java/org/apache/curator/framework/imps/CreateBuilderImpl.java ---------------------------------------------------------------------- diff --git a/curator-framework/src/main/java/org/apache/curator/framework/imps/CreateBuilderImpl.java b/curator-framework/src/main/java/org/apache/curator/framework/imps/CreateBuilderImpl.java index 1487d6b..11050f3 100644 --- a/curator-framework/src/main/java/org/apache/curator/framework/imps/CreateBuilderImpl.java +++ b/curator-framework/src/main/java/org/apache/curator/framework/imps/CreateBuilderImpl.java @@ -20,6 +20,7 @@ package org.apache.curator.framework.imps; import com.google.common.annotations.VisibleForTesting; +import com.google.common.base.Preconditions; import com.google.common.base.Predicate; import com.google.common.collect.Iterables; import org.apache.curator.RetryLoop; @@ -119,6 +120,7 @@ public class CreateBuilderImpl implements CreateBuilder, CreateBuilder2, Backgro @Override public CreateBuilderMain withTtl(long ttl) { + Preconditions.checkState(!client.isZk34CompatibilityMode(), "TTLs are not support when running in ZooKeeper 3.4 compatibility mode"); this.ttl = ttl; return this; } http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/curator-framework/src/main/java/org/apache/curator/framework/imps/CuratorFrameworkImpl.java ---------------------------------------------------------------------- diff --git a/curator-framework/src/main/java/org/apache/curator/framework/imps/CuratorFrameworkImpl.java b/curator-framework/src/main/java/org/apache/curator/framework/imps/CuratorFrameworkImpl.java index 00adb3e..d58c56b 100644 --- a/curator-framework/src/main/java/org/apache/curator/framework/imps/CuratorFrameworkImpl.java +++ b/curator-framework/src/main/java/org/apache/curator/framework/imps/CuratorFrameworkImpl.java @@ -472,12 +472,14 @@ public class CuratorFrameworkImpl implements CuratorFramework @Override public ReconfigBuilder reconfig() { + Preconditions.checkState(!isZk34CompatibilityMode(), "reconfig/config APIs are not support when running in ZooKeeper 3.4 compatibility mode"); return new ReconfigBuilderImpl(this); } @Override public GetConfigBuilder getConfig() { + Preconditions.checkState(!isZk34CompatibilityMode(), "reconfig/config APIs are not support when running in ZooKeeper 3.4 compatibility mode"); return new GetConfigBuilderImpl(this); } @@ -542,6 +544,7 @@ public class CuratorFrameworkImpl implements CuratorFramework @Override public RemoveWatchesBuilder watches() { + Preconditions.checkState(!isZk34CompatibilityMode(), "Remove watches APIs are not support when running in ZooKeeper 3.4 compatibility mode"); return new RemoveWatchesBuilderImpl(this); } http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/curator-framework/src/main/java/org/apache/curator/framework/imps/WatcherRemovalManager.java ---------------------------------------------------------------------- diff --git a/curator-framework/src/main/java/org/apache/curator/framework/imps/WatcherRemovalManager.java b/curator-framework/src/main/java/org/apache/curator/framework/imps/WatcherRemovalManager.java index b85675b..bdb5428 100644 --- a/curator-framework/src/main/java/org/apache/curator/framework/imps/WatcherRemovalManager.java +++ b/curator-framework/src/main/java/org/apache/curator/framework/imps/WatcherRemovalManager.java @@ -53,6 +53,11 @@ public class WatcherRemovalManager void removeWatchers() { + if ( client.isZk34CompatibilityMode() ) + { + return; + } + List<NamespaceWatcher> localEntries = Lists.newArrayList(entries); while ( localEntries.size() > 0 ) { http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/curator-test-zk34/src/test/java/org/apache/curator/test/DummyTest.java ---------------------------------------------------------------------- diff --git a/curator-test-zk34/src/test/java/org/apache/curator/test/DummyTest.java b/curator-test-zk34/src/test/java/org/apache/curator/test/DummyTest.java deleted file mode 100644 index f19a85b..0000000 --- a/curator-test-zk34/src/test/java/org/apache/curator/test/DummyTest.java +++ /dev/null @@ -1,30 +0,0 @@ -/** - * 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.test; - -import org.testng.annotations.Test; - -public class DummyTest -{ - @Test - public void dummyTest() - { - // NOP - } -} http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/curator-test-zk34/src/test/java/org/apache/curator/test/TestCompatibility.java ---------------------------------------------------------------------- diff --git a/curator-test-zk34/src/test/java/org/apache/curator/test/TestCompatibility.java b/curator-test-zk34/src/test/java/org/apache/curator/test/TestCompatibility.java new file mode 100644 index 0000000..2dd543c --- /dev/null +++ b/curator-test-zk34/src/test/java/org/apache/curator/test/TestCompatibility.java @@ -0,0 +1,97 @@ +/** + * 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.test; + +import org.apache.curator.framework.CuratorFramework; +import org.apache.curator.framework.CuratorFrameworkFactory; +import org.apache.curator.retry.RetryOneTime; +import org.apache.curator.test.compatibility.CuratorTestBase; +import org.apache.curator.utils.CloseableUtils; +import org.testng.Assert; +import org.testng.annotations.Test; + +public class TestCompatibility extends CuratorTestBase +{ + @Test + public void testAutoState() + { + CuratorFramework client = CuratorFrameworkFactory.newClient(server.getConnectString(), new RetryOneTime(1)); + Assert.assertTrue(client.isZk34CompatibilityMode()); + } + + @Test(expectedExceptions = IllegalStateException.class) + public void testTtl() throws Exception + { + CuratorFramework client = CuratorFrameworkFactory.newClient(server.getConnectString(), new RetryOneTime(1)); + client.start(); + try + { + client.create().withTtl(100).forPath("/foo"); + } + finally + { + CloseableUtils.closeQuietly(client); + } + } + + @Test(expectedExceptions = IllegalStateException.class) + public void testReconfig() throws Exception + { + CuratorFramework client = CuratorFrameworkFactory.newClient(server.getConnectString(), new RetryOneTime(1)); + client.start(); + try + { + client.reconfig().withNewMembers("a", "b"); + } + finally + { + CloseableUtils.closeQuietly(client); + } + } + + @Test(expectedExceptions = IllegalStateException.class) + public void testGetConfig() throws Exception + { + CuratorFramework client = CuratorFrameworkFactory.newClient(server.getConnectString(), new RetryOneTime(1)); + client.start(); + try + { + client.getConfig().forEnsemble(); + } + finally + { + CloseableUtils.closeQuietly(client); + } + } + + @Test(expectedExceptions = IllegalStateException.class) + public void testRemoveWatches() throws Exception + { + CuratorFramework client = CuratorFrameworkFactory.newClient(server.getConnectString(), new RetryOneTime(1)); + client.start(); + try + { + client.watches().removeAll(); + } + finally + { + CloseableUtils.closeQuietly(client); + } + } +} http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/src/site/confluence/compatibility.confluence ---------------------------------------------------------------------- diff --git a/src/site/confluence/compatibility.confluence b/src/site/confluence/compatibility.confluence index ef3324f..7dd1ce5 100644 --- a/src/site/confluence/compatibility.confluence +++ b/src/site/confluence/compatibility.confluence @@ -1,9 +1,48 @@ -h1. API Compatibility +h1. ZooKeeper Version Compatibility -A [[Clirr|http://clirr.sourceforge.net/]] report is generated for each Curator module: +While ZooKeeper 3.5.x is still considered "beta" by the ZooKeeper development team, the reality is that it is +used in production by many users. However, ZooKeeper 3.4.x is also used in production. Prior to Apache Curator +4.0, both versions of ZooKeeper were supported via two versions of Apache Curator. Starting with Curator 4.0 +both versions of ZooKeeper are supported via the same Curator libraries. + +h2. ZooKeeper 3.5.x + +* Curator 4.0 has a hard dependency on ZooKeeper 3.5.x +* If you are using ZooKeeper 3.5.x there's nothing additional to do \- just use Curator 4.0 + +h2. ZooKeeper 3.4.x + +Curator 4.0 supports ZooKeeper 3.4.x ensembles in a soft\-compatibility mode. To use this mode +you must exclude ZooKeeper when adding Curator to your dependency management tool. + +_Maven_ + +{code} +<dependency> + <groupId>org.apache.curator</groupId> + <artifactId>curator-recipes</artifactId> + <version>${curator-version}</version> + <exclusions> + <exclusion> + <groupId>org.apache.zookeeper</groupId> + <artifactId>zookeeper</artifactId> + </exclusion> + </exclusions> +</dependency> +{code} + +_Gradle_ + +{code} +compile('org.apache.curator:curator-recipes:$curatorVersion') { + exclude('org.apache.zookeeper:zookeeper') +} +{code} + +You must add a dependency on ZooKeeper 3.4.x also. + +Curator will detect which ZooKeeper library is in use and automatically set ZooKeeper 3.4 compatibility +mode as needed. In this mode, all features not supported by 3.4 are disabled. It is up to your +application code to "do the right thing" and not use these features. Use the `isZk34CompatibilityMode()` +method to determine which mode Curator is using at runtime. -* [[Curator Client Report|curator-client/clirr-report.html]] -* [[Curator Framework Report|curator-framework/clirr-report.html]] -* [[Curator Recipes Report|curator-recipes/clirr-report.html]] -* [[Curator Discovery Report|curator-x-discovery/clirr-report.html]] -* [[Curator Discovery Server Report|curator-x-discovery-server/clirr-report.html]] http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/src/site/confluence/index.confluence ---------------------------------------------------------------------- diff --git a/src/site/confluence/index.confluence b/src/site/confluence/index.confluence index f9490b4..cdd9902 100644 --- a/src/site/confluence/index.confluence +++ b/src/site/confluence/index.confluence @@ -12,14 +12,9 @@ h2. Getting Started See the page for quick start: [[Getting Started|getting-started.html]]. -h2. Components +!images/arrow.png! -|[[Recipes|curator-recipes/index.html]]|Implementations of some of the common ZooKeeper "recipes". The implementations are built on top of the Curator Framework.| -|[[Framework|curator-framework/index.html]]|The Curator Framework is a high\-level API that greatly simplifies using ZooKeeper. It adds many features that build on ZooKeeper and handles the complexity of managing connections to the ZooKeeper cluster and retrying operations.| -|[[Utilities|utilities.html]]|Various utilities that are useful when using ZooKeeper.| -|[[Client|curator-client/index.html]]|A replacement for the bundled {{ZooKeeper}} class that takes care of some low\-level housekeeping and provides some useful utilities.| -|[[Errors|errors.html]]|How Curator deals with errors, connection issues, recoverable exceptions, etc.| -|Extensions|The curator\-recipes package implements the common recipes that are described in the ZooKeeper documentation. To avoid bloating that package, recipes/applications that have a vertical appeal will be put in separate "extension" packages using the naming convention curator\-x\-name.| +Use the navigation links in the left\-nav menu for detailed information. h2. Maven / Artifacts @@ -28,20 +23,17 @@ most users, the only artifact you need is curator\-recipes. ||GroupID/Org||ArtifactID/Name||Description|| |org.apache.curator|curator\-recipes|All of the recipes. Note: this artifact has dependencies on client and framework and, so, Maven (or whatever tool you're using) should pull those in automatically.| +|org.apache.curator|curator\-async|Asynchronous DSL with O/R modeling, migrations and many other features.| |org.apache.curator|curator\-framework|The Curator Framework high level API. This is built on top of the client and should pull it in automatically.| |org.apache.curator|curator\-client|The Curator Client \- replacement for the ZooKeeper class in the ZK distribution.| |org.apache.curator|curator\-test|Contains the TestingServer, the TestingCluster and a few other tools useful for testing.| |org.apache.curator|curator\-examples|Example usages of various Curator features.| |org.apache.curator|curator\-x\-discovery|A Service Discovery implementation built on the Curator Framework.| -|org.apache.curator|curator\-x\-discovery-server|A RESTful server that can be used with Curator Discovery.| +|org.apache.curator|curator\-x\-discovery\-server|A RESTful server that can be used with Curator Discovery.| |org.apache.curator|curator\-x\-rpc|A proxy that bridges non\-java environments with the Curator framework and recipes.| -h2. Versions +h2. ZooKeeper Compatibility -The are currently two released versions of Curator, 2.x.x and 3.x.x: +Apache Curator is meant to be used with ZooKeeper 3.5\+. However, it is also compatible with ZooKeeper 3.4.x. +See [[Compatibility|compatibility.html]] for details. -* Curator 2.x.x \- compatible with both ZooKeeper 3.4.x and ZooKeeper 3.5.x -* Curator 3.x.x \- compatible only with ZooKeeper 3.5.x and includes support for new features such as dynamic reconfiguration, etc. - -ZooKeeper 3.5.x adds a number of new features including dynamic reconfiguration, watcher removal and others. The Curator 3.x.x Jira -issues tracking these features are here: [[https://issues.apache.org/jira/browse/CURATOR-159]]. http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/src/site/resources/images/arrow.png ---------------------------------------------------------------------- diff --git a/src/site/resources/images/arrow.png b/src/site/resources/images/arrow.png new file mode 100644 index 0000000..5de46be Binary files /dev/null and b/src/site/resources/images/arrow.png differ http://git-wip-us.apache.org/repos/asf/curator/blob/89182ed1/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index 8136c9a..e5ae374 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -76,6 +76,10 @@ <item name="Schema Support" href="curator-framework/schema.html"/> </menu> + <menu name="Compatibility" inherit="top"> + <item name="ZooKeeper Versions" href="compatibility.html"/> + </menu> + <menu name="Low Level" inherit="top"> <item name="Framework" href="curator-framework/index.html"/> <item name="Utilities" href="utilities.html"/> @@ -90,7 +94,6 @@ <item name="Source Code" href="source-repository.html"/> <item name="Project Team" href="team-list.html"/> <item name="Project Information" href="project-info.html"/> - <item name="API Compatibility" href="compatibility.html"/> <item name="Javadoc" href="apidocs/index.html"/> <item name="Wiki" href="https://cwiki.apache.org/confluence/display/CURATOR"/> <item name="Releases" href="https://cwiki.apache.org/confluence/display/CURATOR/Releases"/> @@ -99,8 +102,6 @@ <menu name="Extensions" inherit="top"> <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 Java 8/Async" href="curator-x-async/index.html"/> </menu> <menu name="Community" inherit="top">