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/01/02 02:22:38 UTC

curator git commit: Add docs, more refactoring, final testing, etc.

Repository: curator
Updated Branches:
  refs/heads/persistent-watch 8565de6d7 -> 2148b6d1a


Add docs, more refactoring, final testing, etc.


Project: http://git-wip-us.apache.org/repos/asf/curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/2148b6d1
Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/2148b6d1
Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/2148b6d1

Branch: refs/heads/persistent-watch
Commit: 2148b6d1a829c2efd0309e2914b755ce9ebff003
Parents: 8565de6
Author: randgalt <ra...@apache.org>
Authored: Sun Jan 1 21:22:32 2017 -0500
Committer: randgalt <ra...@apache.org>
Committed: Sun Jan 1 21:22:32 2017 -0500

----------------------------------------------------------------------
 .../framework/recipes/watch/CacheAction.java    | 28 +++++-
 .../framework/recipes/watch/CacheEvent.java     | 21 +++++
 .../framework/recipes/watch/CacheListener.java  | 25 ++++++
 .../framework/recipes/watch/CacheSelector.java  |  4 +-
 .../framework/recipes/watch/CacheSelectors.java | 70 ++++++++++++++-
 .../framework/recipes/watch/CachedNode.java     | 15 ++++
 .../recipes/watch/CachedNodeComparator.java     | 10 +++
 .../recipes/watch/CachedNodeComparators.java    | 33 +++++--
 .../framework/recipes/watch/CuratorCache.java   | 42 ++++-----
 .../recipes/watch/CuratorCacheBase.java         | 35 ++------
 .../recipes/watch/CuratorCacheBuilder.java      | 92 ++++++++++++++++++++
 .../recipes/watch/InternalCuratorCache.java     |  6 +-
 .../recipes/watch/InternalNodeCache.java        |  2 +-
 .../recipes/watch/PersistentWatcher.java        | 27 +++++-
 .../recipes/watch/BaseTestTreeCache.java        |  2 +-
 .../framework/recipes/watch/TestNodeCache.java  | 25 +++---
 .../watch/TestSingleLevelCuratorCache.java      |  2 +-
 .../framework/recipes/watch/TestTreeCache.java  |  4 +-
 18 files changed, 356 insertions(+), 87 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheAction.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheAction.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheAction.java
index b39457a..57a48f1 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheAction.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheAction.java
@@ -18,11 +18,37 @@
  */
 package org.apache.curator.framework.recipes.watch;
 
+import org.apache.zookeeper.data.Stat;
+
+/**
+ * storage options for cached nodes
+ *
+ * @see CacheSelector#actionForPath(String, String)
+ */
 public enum CacheAction
 {
+    /**
+     * The node will not be stored - i.e. the node is not cached at all
+     */
     NOT_STORED,
+
+    /**
+     * Only the node's path is stored
+     */
     PATH_ONLY,
+
+    /**
+     * The node and its {@link Stat} are stored
+     */
     STAT_ONLY,
+
+    /**
+     * The node, its {@link Stat} and data are stored
+     */
     STAT_AND_DATA,
-    STAT_AND_COMPRESSED_DATA
+
+    /**
+     * The node, its {@link Stat} and data (uncompressed) are stored
+     */
+    STAT_AND_UNCOMPRESSED_DATA
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheEvent.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheEvent.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheEvent.java
index 4310d73..8193dad 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheEvent.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheEvent.java
@@ -18,10 +18,31 @@
  */
 package org.apache.curator.framework.recipes.watch;
 
+/**
+ * Cache change event types
+ */
 public enum CacheEvent
 {
+    /**
+     * A node was added to the cache that wasn't previously in the cache
+     */
     NODE_CREATED,
+
+    /**
+     * A node was removed from the cache
+     */
     NODE_DELETED,
+
+    /**
+     * A node in the cache was changed due to the {@link CachedNodeComparator} signifying
+     * a difference
+     */
     NODE_CHANGED,
+
+    /**
+     * The cache was refreshed to a call to one of the refresh() methods, server reconnection,
+     * etc. NOTE: this event is only sent if {@link CuratorCacheBuilder#sendingRefreshEvents(boolean)}
+     * is true (default is <code>true</code>).
+     */
     CACHE_REFRESHED
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheListener.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheListener.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheListener.java
index 7a2a6a5..7f9adc2 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheListener.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheListener.java
@@ -18,7 +18,32 @@
  */
 package org.apache.curator.framework.recipes.watch;
 
+/**
+ * Functor for listening for events on a cache
+ */
 public interface CacheListener
 {
+    /**
+     * <p>
+     *     A event was posted for the cache. The meaning of the other arguments depends on the event
+     *     type
+     * </p>
+     *
+     * <p>
+     *     <code>path</code> is generally the affected path. For {@link CacheEvent#CACHE_REFRESHED}
+     *     it will be the path will be the path passed to the refresh() method used or the main path
+     *     used to construct the cache.
+     * </p>
+     *
+     * <p>
+     *     For {@link CacheEvent#NODE_CREATED} and {@link CacheEvent#NODE_CHANGED}
+     *     <code>affectedNode</code> is the new value of the node. For {@link CacheEvent#NODE_DELETED}
+     *     <code>affectedNode</code> is the value of the node being deleted.
+     * </p>
+     *
+     * @param event the event
+     * @param path the path of the event
+     * @param affectedNode the affected node value
+     */
     void process(CacheEvent event, String path, CachedNode affectedNode);
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelector.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelector.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelector.java
index 6d1f50f..36a7225 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelector.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelector.java
@@ -59,11 +59,11 @@ public interface CacheSelector
     boolean traverseChildren(String basePath, String fullPath);
 
     /**
-     * Return true if this node should be returned from the cache
+     * Return how/if this node should stored in the cache
      *
      * @param basePath the main path of the cache
      * @param fullPath full path of the ZNode
-     * @return true/false
+     * @return caching action
      */
     CacheAction actionForPath(String basePath, String fullPath);
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelectors.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelectors.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelectors.java
index bbe27e9..ab22f7a 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelectors.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CacheSelectors.java
@@ -18,12 +18,16 @@
  */
 package org.apache.curator.framework.recipes.watch;
 
+import org.apache.curator.framework.recipes.cache.PathChildrenCache;
 import org.apache.curator.utils.ZKPaths;
 
+/**
+ * Pre-built caching selectors
+ */
 public class CacheSelectors
 {
     private static final CacheSelector statAndData = new StandardCacheSelector(CacheAction.STAT_AND_DATA);
-    private static final CacheSelector compressedStatAndData = new StandardCacheSelector(CacheAction.STAT_AND_COMPRESSED_DATA);
+    private static final CacheSelector uncompressedStatAndData = new StandardCacheSelector(CacheAction.STAT_AND_UNCOMPRESSED_DATA);
     private static final CacheSelector statOnly = new StandardCacheSelector(CacheAction.STAT_ONLY);
     private static final CacheSelector pathOnly = new StandardCacheSelector(CacheAction.PATH_ONLY);
 
@@ -107,41 +111,101 @@ public class CacheSelectors
         }
     }
 
+    /**
+     * Returns a cache selector that stores stat and data and processes the entire tree
+     * from the root path given to the cache builder
+     *
+     * @return selector
+     */
     public static CacheSelector statAndData()
     {
         return statAndData;
     }
 
-    public static CacheSelector compressedStatAndData()
+    /**
+     * Returns a cache selector that stores stat and uncompressed data and processes the entire tree
+     * from the root path given to the cache builder
+     *
+     * @return selector
+     */
+    public static CacheSelector uncompressedStatAndData()
     {
-        return compressedStatAndData;
+        return uncompressedStatAndData;
     }
 
+    /**
+     * Returns a cache selector that stores only the stat and processes the entire tree
+     * from the root path given to the cache builder
+     *
+     * @return selector
+     */
     public static CacheSelector statOnly()
     {
         return statOnly;
     }
 
+    /**
+     * Returns a cache selector that stores only the path and processes the entire tree
+     * from the root path given to the cache builder
+     *
+     * @return selector
+     */
     public static CacheSelector pathOnly()
     {
         return pathOnly;
     }
 
+    /**
+     * A selector that stores stat and data for the immediate child of the root path
+     * given to the cache builder (exclusive of the root itself). This selector emulates
+     * the deprecated {@link PathChildrenCache}
+     *
+     * @return selector
+     */
+    @SuppressWarnings("deprecation")
     public static CacheSelector singleLevel()
     {
         return new SingleLevelCacheSelector(CacheAction.STAT_AND_DATA);
     }
 
+    /**
+     * A selector that returns <code>cacheAction</code> for the immediate child of the root path
+     * given to the cache builder (exclusive of the root itself). This selector emulates
+     * the deprecated {@link PathChildrenCache}
+     *
+     * @param cacheAction the action to return
+     * @return selector
+     */
+    @SuppressWarnings("deprecation")
     public static CacheSelector singleLevel(CacheAction cacheAction)
     {
         return new SingleLevelCacheSelector(cacheAction);
     }
 
+    /**
+     * A selector that stores stat and data at a maximum depth to explore/watch.
+     * A {@code maxDepth} of {@code 0} will watch only
+     * the root node; a {@code maxDepth} of {@code 1} will watch the
+     * root node and its immediate children
+     *
+     * @param maxDepth depth to use
+     * @return selector
+     */
     public static CacheSelector maxDepth(int maxDepth)
     {
         return maxDepth(maxDepth, CacheAction.STAT_AND_DATA);
     }
 
+    /**
+     * A selector that returns <code>cacheAction</code> at a maximum depth to explore/watch.
+     * A {@code maxDepth} of {@code 0} will watch only
+     * the root node; a {@code maxDepth} of {@code 1} will watch the
+     * root node and its immediate children
+     *
+     * @param cacheAction the action to return
+     * @param maxDepth depth to use
+     * @return selector
+     */
     public static CacheSelector maxDepth(int maxDepth, CacheAction cacheAction)
     {
         return new MaxDepthCacheSelector(maxDepth, cacheAction);

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNode.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNode.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNode.java
index 0f1caeb..f3cd18a 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNode.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNode.java
@@ -22,6 +22,9 @@ import org.apache.zookeeper.data.Stat;
 import java.util.Arrays;
 import java.util.Objects;
 
+/**
+ * Represents the data for a cached node
+ */
 public class CachedNode
 {
     private final Stat stat;
@@ -29,16 +32,28 @@ public class CachedNode
 
     private static final byte[] defaultData = new byte[0];
 
+    /**
+     * Creates an empty node
+     */
     public CachedNode()
     {
         this(new Stat(), defaultData);
     }
 
+    /**
+     * A node with a stat but empty data
+     *
+     * @param stat the stat
+     */
     public CachedNode(Stat stat)
     {
         this(stat, defaultData);
     }
 
+    /**
+     * @param stat the stat
+     * @param data uncompressed data. If <code>null</code> an empty array is substituted.
+     */
     public CachedNode(Stat stat, byte[] data)
     {
         this.stat = Objects.requireNonNull(stat, "stat cannot be null");

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparator.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparator.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparator.java
index 34d86ad..2ffd8ab 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparator.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparator.java
@@ -18,7 +18,17 @@
  */
 package org.apache.curator.framework.recipes.watch;
 
+/**
+ * Provides for alternate methods of node comparison
+ */
 public interface CachedNodeComparator
 {
+    /**
+     * Return true if the two nodes should be considered the same
+     *
+     * @param n1 node 1
+     * @param n2 node 2
+     * @return true/false
+     */
     boolean isSame(CachedNode n1, CachedNode n2);
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparators.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparators.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparators.java
index b54d443..79c90f0 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparators.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CachedNodeComparators.java
@@ -20,6 +20,9 @@ package org.apache.curator.framework.recipes.watch;
 
 import java.util.Arrays;
 
+/**
+ * Pre-built node comparators for common uses
+ */
 public class CachedNodeComparators
 {
     private static final CachedNodeComparator dataOnly = new CachedNodeComparator()
@@ -51,9 +54,9 @@ public class CachedNodeComparators
 
     private static boolean sameType(long e1, long e2)
     {
-        boolean e1Is = (e1 > 0);
-        boolean e2Is = (e2 > 0);
-        return e1Is == e2Is;
+        boolean e1IsEphemeral = (e1 > 0);
+        boolean e2IsEphemeral = (e2 > 0);
+        return e1IsEphemeral == e2IsEphemeral;
     }
 
     private static boolean firstCheck(CachedNode n1, CachedNode n2)
@@ -70,19 +73,35 @@ public class CachedNodeComparators
         return true;
     }
 
+    /**
+     * Returns a comparator that only compares the byte array of the node, ignoring the Stat
+     *
+     * @return data only comparator
+     */
     public static CachedNodeComparator dataOnly()
     {
         return dataOnly;
     }
 
-    public static CachedNodeComparator deep()
+    /**
+     * Returns a comparator that compares the byte array of the node, and the ephemeralOwner
+     * of the Stat. i.e. the data must match and the ephemeral type must be the same
+     *
+     * @return data and type comparator
+     */
+    public static CachedNodeComparator dataAndType()
     {
-        return deep;
+        return dataAndType;
     }
 
-    public static CachedNodeComparator dataAndType()
+    /**
+     * Returns a comparator that compares the byte array of the node and the stat
+     *
+     * @return deep comparator
+     */
+    public static CachedNodeComparator deep()
     {
-        return dataAndType;
+        return deep;
     }
 
     private CachedNodeComparators()

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCache.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCache.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCache.java
index f22563e..e97157e 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCache.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCache.java
@@ -52,15 +52,17 @@ public interface CuratorCache extends Closeable
 
     /**
      * force-fill the cache by getting all applicable nodes. The returned latch
-     * can be used to check/block for completion.
+     * can be used to check/block for completion. If the cache is set to send refresh
+     * events, one will be posted when this refresh has completed.
      *
      * @return a latch that signals when the refresh is complete
      */
     CountDownLatch refreshAll();
 
     /**
-     * Refresh the given cached node The returned latch
-     * can be used to check/block for completion.
+     * Refresh the given cached node. The returned latch
+     * can be used to check/block for completion. If the cache is set to send refresh
+     * events, one will be posted when this refresh has completed.
      *
      * @param path node full path
      * @return a latch that signals when the refresh is complete
@@ -81,7 +83,8 @@ public interface CuratorCache extends Closeable
     void clearAll();
 
     /**
-     * Return true if there is a cached node at the given path
+     * Return true if there is a cached node at the given path.
+     * Concurrent changes may not be immediately reflected.
      *
      * @param path node full path
      * @return true/false
@@ -96,15 +99,8 @@ public interface CuratorCache extends Closeable
     Collection<String> paths();
 
     /**
-     * Returns the set of child node names of the given node
-     *
-     * @param path node full path
-     * @return child names
-     */
-    Collection<String> childNamesAtPath(String path);
-
-    /**
-     * Returns an immutable map of child node names of the given node and the data at that node
+     * Returns an immutable map of child node names of the given node and the data at that node.
+     * Concurrent changes may not be immediately reflected.
      *
      * @param path node full path
      * @return child nodes
@@ -112,14 +108,16 @@ public interface CuratorCache extends Closeable
     Map<String, CachedNode> childrenAtPath(String path);
 
     /**
-     * Return the node data stored for the main path (the path passed to the builder) in the cache or null
+     * Return the node data stored for the main path (the path passed to the builder) in the cache or null.
+     * Concurrent changes may not be immediately reflected.
      *
      * @return node data or null
      */
     CachedNode getMain();
 
     /**
-     * Return the node data stored for the path in the cache or null
+     * Return the node data stored for the path in the cache or null.
+     * Concurrent changes may not be immediately reflected.
      *
      * @param path node full path
      * @return node data or null
@@ -127,21 +125,15 @@ public interface CuratorCache extends Closeable
     CachedNode get(String path);
 
     /**
-     * Returns an unmodifiable collection of node values in the cache.
-     *
-     * @return node values
-     */
-    Collection<CachedNode> getAll();
-
-    /**
-     * Return an unmodifiable map of the node entries in the cache
+     * Return an unmodifiable map of the node entries in the cache.
+     * Concurrent changes may not be immediately reflected.
      *
      * @return map
      */
     Map<String, CachedNode> view();
 
     /**
-     * Returns true if the cache is currently empty. Use the result only as a reference. Concurrent
+     * Returns true if the cache is currently empty. Concurrent
      * changes may not be immediately reflected.
      *
      * @return true/false
@@ -149,7 +141,7 @@ public interface CuratorCache extends Closeable
     boolean isEmpty();
 
     /**
-     * Returns the number of nodes int the cache. Use the result only as a reference. Concurrent
+     * Returns the number of nodes in the cache. Use the result only as a reference. Concurrent
      * changes may not be immediately reflected.
      *
      * @return true/false

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBase.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBase.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBase.java
index 2e8e5be..e4a6de4 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBase.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBase.java
@@ -20,9 +20,7 @@ package org.apache.curator.framework.recipes.watch;
 
 import com.google.common.base.Function;
 import com.google.common.base.Preconditions;
-import com.google.common.base.Predicates;
 import com.google.common.cache.Cache;
-import com.google.common.collect.Collections2;
 import com.google.common.collect.ImmutableMap;
 import org.apache.curator.framework.listen.Listenable;
 import org.apache.curator.framework.listen.ListenerContainer;
@@ -113,30 +111,17 @@ abstract class CuratorCacheBase implements CuratorCache
     }
 
     @Override
-    public Collection<String> childNamesAtPath(final String basePath)
-    {
-        Function<String, String> function = new Function<String, String>()
-        {
-            @Override
-            public String apply(String path)
-            {
-                ZKPaths.PathAndNode pathAndNode = ZKPaths.getPathAndNode(path);
-                return (pathAndNode.getPath().equals(basePath) && !path.equals(basePath)) ? pathAndNode.getNode() : null;   // must special case "root" as parent of root is root
-            }
-        };
-        return Collections2.filter(Collections2.transform(paths(), function), Predicates.notNull());
-    }
-
-    @Override
-    public Map<String, CachedNode> childrenAtPath(String path)
+    public Map<String, CachedNode> childrenAtPath(String basePath)
     {
         ImmutableMap.Builder<String, CachedNode> builder = ImmutableMap.builder();
-        for ( String name : childNamesAtPath(path) )
+        for ( Map.Entry<String, CachedNode> entry : cache.asMap().entrySet() )
         {
-            CachedNode node = cache.asMap().get(ZKPaths.makePath(path, name));
-            if ( node != null )
+            String path = entry.getKey();
+            CachedNode node = entry.getValue();
+            ZKPaths.PathAndNode pathAndNode = ZKPaths.getPathAndNode(path);
+            if ( (pathAndNode.getPath().equals(basePath) && !path.equals(basePath)) )
             {
-                builder.put(name, node);
+                builder.put(pathAndNode.getNode(), node);
             }
         }
         return builder.build();
@@ -154,12 +139,6 @@ abstract class CuratorCacheBase implements CuratorCache
         return cache.asMap().get(path);
     }
 
-    @Override
-    public final Collection<CachedNode> getAll()
-    {
-        return Collections.unmodifiableCollection(cache.asMap().values());
-    }
-
     /**
      * As a memory optimization, you can clear the cached data bytes for a node. Subsequent
      * calls to {@link CachedNode#getData()} for this node will return <code>null</code>.

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBuilder.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBuilder.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBuilder.java
index effa4e0..be4e815 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBuilder.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/CuratorCacheBuilder.java
@@ -24,6 +24,9 @@ import org.apache.curator.framework.CuratorFramework;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * Factory for building cache instances
+ */
 public class CuratorCacheBuilder
 {
     private final CuratorFramework client;
@@ -36,11 +39,24 @@ public class CuratorCacheBuilder
     private CachedNodeComparator nodeComparator = CachedNodeComparators.dataAndType();
     private CacheSelector cacheSelector = CacheSelectors.statAndData();
 
+    /**
+     * Start a new builder for the given client and main path
+     *
+     * @param client the client
+     * @param path the base path for the cache
+     * @return builder
+     */
     public static CuratorCacheBuilder builder(CuratorFramework client, String path)
     {
         return new CuratorCacheBuilder(client, path);
     }
 
+    /**
+     * Return a new cache based on the current values of the builder. Note: the cache must
+     * be started before use and closed when done.
+     *
+     * @return cache instance
+     */
     public CuratorCache build()
     {
         if ( singleNodeCacheAction != null )
@@ -52,11 +68,22 @@ public class CuratorCacheBuilder
         return new InternalCuratorCache(client, path, cacheSelector, nodeComparator, cacheBuilder.<String, CachedNode>build(), sendRefreshEvents, refreshOnStart, sortChildren);
     }
 
+    /**
+     * Single node caches can be optimized. Call this method to only watch/cache a single node
+     *
+     * @return this
+     */
     public CuratorCacheBuilder forSingleNode()
     {
         return forSingleNode(CacheAction.STAT_AND_DATA);
     }
 
+    /**
+     * Single node caches can be optimized. Call this method to only watch/cache a single node
+     *
+     * @param cacheAction caching action to use
+     * @return this
+     */
     public CuratorCacheBuilder forSingleNode(CacheAction cacheAction)
     {
         cacheSelector = null;
@@ -64,54 +91,119 @@ public class CuratorCacheBuilder
         return this;
     }
 
+    /**
+     * By default, values in the cache use hard references. Calling this method changes to weak
+     * references.
+     *
+     * @return this
+     */
     public CuratorCacheBuilder usingWeakValues()
     {
         cacheBuilder = cacheBuilder.weakValues();
         return this;
     }
 
+    /**
+     * By default, values in the cache use hard references. Calling this method changes to soft
+     * references.
+     *
+     * @return this
+     */
     public CuratorCacheBuilder usingSoftValues()
     {
         cacheBuilder = cacheBuilder.softValues();
         return this;
     }
 
+    /**
+     * By default, values in the cache never expire. Calling this method specifies that each entry
+     * should be automatically removed from the cache once a fixed duration has elapsed after
+     * the entry's creation, or the most recent replacement of its value.
+     *
+     * @param duration the length of time after an entry is created that it should be automatically
+     *     removed
+     * @param unit the unit that {@code duration} is expressed in
+     * @return this
+     */
     public CuratorCacheBuilder thatExpiresAfterWrite(long duration, TimeUnit unit)
     {
         cacheBuilder = cacheBuilder.expireAfterWrite(duration, unit);
         return this;
     }
 
+    /**
+     * By default, values in the cache never expire. Calling this method specifies that each entry
+     * should be automatically removed from the cache once a fixed duration has elapsed after the
+     * entry's creation, the most recent replacement of its value, or its last access.
+     *
+     * @param duration the length of time after an entry is last accessed that it should be
+     *     automatically removed
+     * @param unit the unit that {@code duration} is expressed in
+     * @return this
+     */
     public CuratorCacheBuilder thatExpiresAfterAccess(long duration, TimeUnit unit)
     {
         cacheBuilder = cacheBuilder.expireAfterAccess(duration, unit);
         return this;
     }
 
+    /**
+     * Changes whether or not {@link CacheEvent#CACHE_REFRESHED} events are sent to
+     * {@link CacheListener}s. The default is <code>true</code>
+     *
+     * @param sendRefreshEvents true/false
+     * @return this
+     */
     public CuratorCacheBuilder sendingRefreshEvents(boolean sendRefreshEvents)
     {
         this.sendRefreshEvents = sendRefreshEvents;
         return this;
     }
 
+    /**
+     * Changes whether or not a refresh is done when the cache is started.  The default is <code>true</code>
+     *
+     * @param refreshOnStart true/false
+     * @return this
+     */
     public CuratorCacheBuilder refreshingWhenStarted(boolean refreshOnStart)
     {
         this.refreshOnStart = refreshOnStart;
         return this;
     }
 
+    /**
+     * Changes whether or not children are sorted when notifying. i.e. notifications of added nodes
+     * come in sorted order. The default is <code>true</code>
+     *
+     * @param sortChildren true/false
+     * @return this
+     */
     public CuratorCacheBuilder sortingChildren(boolean sortChildren)
     {
         this.sortChildren = sortChildren;
         return this;
     }
 
+    /**
+     * Changes which comparator is used to determine whether a node has changed or not.
+     * The default is {@link CachedNodeComparators#dataAndType}
+     *
+     * @param nodeComparator new comparator
+     * @return this
+     */
     public CuratorCacheBuilder withNodeComparator(CachedNodeComparator nodeComparator)
     {
         this.nodeComparator = Objects.requireNonNull(nodeComparator, "nodeComparator cannot be null");
         return this;
     }
 
+    /**
+     * Changes which cache selector is used. The default is {@link CacheSelectors#statAndData}
+     *
+     * @param cacheSelector new selector
+     * @return this
+     */
     public CuratorCacheBuilder withCacheSelector(CacheSelector cacheSelector)
     {
         this.cacheSelector = Objects.requireNonNull(cacheSelector, "cacheSelector cannot be null");

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalCuratorCache.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalCuratorCache.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalCuratorCache.java
index d26d6df..d8c3b11 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalCuratorCache.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalCuratorCache.java
@@ -229,7 +229,7 @@ class InternalCuratorCache extends CuratorCacheBase implements Watcher
                 break;
             }
 
-            case STAT_AND_COMPRESSED_DATA:
+            case STAT_AND_UNCOMPRESSED_DATA:
             {
                 try
                 {
@@ -262,7 +262,7 @@ class InternalCuratorCache extends CuratorCacheBase implements Watcher
 
     private void checkDeletedChildren(String path, List<String> children)
     {
-        Collection<String> namesAtPath = childNamesAtPath(path);
+        Collection<String> namesAtPath = childrenAtPath(path).keySet();
         Sets.SetView<String> deleted = Sets.difference(Sets.newHashSet(namesAtPath), Sets.newHashSet(children));
         for ( String deletedName : deleted )
         {
@@ -294,7 +294,7 @@ class InternalCuratorCache extends CuratorCacheBase implements Watcher
             }
 
             case STAT_AND_DATA:
-            case STAT_AND_COMPRESSED_DATA:
+            case STAT_AND_UNCOMPRESSED_DATA:
             {
                 putNode = newNode;
                 break;

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalNodeCache.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalNodeCache.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalNodeCache.java
index 0dd6789..c1f60da 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalNodeCache.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/InternalNodeCache.java
@@ -193,7 +193,7 @@ class InternalNodeCache extends CuratorCacheBase
                             break;
                         }
 
-                        case STAT_AND_COMPRESSED_DATA:
+                        case STAT_AND_UNCOMPRESSED_DATA:
                         {
                             refresher.increment();
                             client.getData().decompressed().usingWatcher(watcher).inBackground(backgroundCallback, refresher).forPath(path);

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/PersistentWatcher.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/PersistentWatcher.java b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/PersistentWatcher.java
index b25983f..5fad690 100644
--- a/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/PersistentWatcher.java
+++ b/curator-recipes/src/main/java/org/apache/curator/framework/recipes/watch/PersistentWatcher.java
@@ -32,13 +32,20 @@ import org.apache.curator.utils.ThreadUtils;
 import org.apache.zookeeper.KeeperException;
 import org.apache.zookeeper.WatchedEvent;
 import org.apache.zookeeper.Watcher;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import java.io.Closeable;
 import java.util.Objects;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicReference;
 
+/**
+ * A managed persisten watcher. The watch will be managed such that it stays set through
+ * connection lapses, etc.
+ */
 public class PersistentWatcher implements Closeable
 {
+    private final Logger log = LoggerFactory.getLogger(getClass());
     private final AtomicReference<State> state = new AtomicReference<>(State.LATENT);
     private final ListenerContainer<Watcher> listeners = new ListenerContainer<>();
     private final AtomicBoolean isSet = new AtomicBoolean(false);
@@ -105,12 +112,19 @@ public class PersistentWatcher implements Closeable
         CLOSED
     }
 
+    /**
+     * @param client client
+     * @param basePath path to set the watch on
+     */
     public PersistentWatcher(CuratorFramework client, String basePath)
     {
         this.client = Objects.requireNonNull(client, "client cannot be null");
         this.basePath = Objects.requireNonNull(basePath, "basePath cannot be null");
     }
 
+    /**
+     * Start watching
+     */
     public void start()
     {
         Preconditions.checkState(state.compareAndSet(State.LATENT, State.STARTED), "Already started");
@@ -118,6 +132,9 @@ public class PersistentWatcher implements Closeable
         reset();
     }
 
+    /**
+     * Remove the watcher
+     */
     @Override
     public void close()
     {
@@ -137,11 +154,19 @@ public class PersistentWatcher implements Closeable
         }
     }
 
+    /**
+     * Container for setting listeners
+     *
+     * @return listener container
+     */
     public Listenable<Watcher> getListenable()
     {
         return listeners;
     }
 
+    /**
+     * Called whenever the watch has been successfully set/reset
+     */
     protected void noteWatcherReset()
     {
         // provided for sub-classes to override
@@ -155,7 +180,7 @@ public class PersistentWatcher implements Closeable
         }
         catch ( Exception e )
         {
-            // TODO
+            log.error("Could not reset persistent watch at path: " + basePath, e);
         }
     }
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/BaseTestTreeCache.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/BaseTestTreeCache.java b/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/BaseTestTreeCache.java
index 8a59f88..95610f4 100644
--- a/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/BaseTestTreeCache.java
+++ b/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/BaseTestTreeCache.java
@@ -172,6 +172,6 @@ public class BaseTestTreeCache extends BaseClassForTests
         {
             names = new String[0];
         }
-        Assert.assertEquals(Sets.newHashSet(cache.childNamesAtPath(path)), Sets.newHashSet(names));
+        Assert.assertEquals(Sets.newHashSet(cache.childrenAtPath(path).keySet()), Sets.newHashSet(names));
     }
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestNodeCache.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestNodeCache.java b/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestNodeCache.java
index 7874a72..34ad6da 100644
--- a/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestNodeCache.java
+++ b/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestNodeCache.java
@@ -56,24 +56,25 @@ public class TestNodeCache extends BaseClassForTests
                 }
             });
 
-            final Semaphore semaphore = new Semaphore(0);
+            final BlockingQueue<CacheEvent> events = new LinkedBlockingQueue<>();
             cache = CuratorCacheBuilder.builder(client, "/test/foo").forSingleNode().sendingRefreshEvents(false).build();
             cache.getListenable().addListener(new CacheListener()
             {
                 @Override
                 public void process(CacheEvent event, String path, CachedNode affectedNode)
                 {
-                    semaphore.release();
+                    events.add(event);
                 }
             });
             Assert.assertTrue(timing.awaitLatch(cache.start()));
 
             Assert.assertEquals(cache.getMain().getData(), "one".getBytes());
 
+            Assert.assertEquals(events.poll(5, TimeUnit.SECONDS), CacheEvent.NODE_CREATED);
             client.delete().forPath("/test/foo");
-            Assert.assertTrue(semaphore.tryAcquire(1, 10, TimeUnit.SECONDS));
+            Assert.assertEquals(events.poll(5, TimeUnit.SECONDS), CacheEvent.NODE_DELETED);
             client.create().forPath("/test/foo", "two".getBytes());
-            Assert.assertTrue(semaphore.tryAcquire(1, 10, TimeUnit.SECONDS));
+            Assert.assertEquals(events.poll(5, TimeUnit.SECONDS), CacheEvent.NODE_CREATED);
 
             Throwable t = error.get();
             if ( t != null )
@@ -86,7 +87,7 @@ public class TestNodeCache extends BaseClassForTests
         finally
         {
             CloseableUtils.closeQuietly(cache);
-            TestCleanState.closeAndTestClean(client);
+            CloseableUtils.closeQuietly(client);
         }
     }
 
@@ -143,7 +144,7 @@ public class TestNodeCache extends BaseClassForTests
         finally
         {
             CloseableUtils.closeQuietly(cache);
-            TestCleanState.closeAndTestClean(client);
+            CloseableUtils.closeQuietly(client);
         }
     }
 
@@ -159,7 +160,6 @@ public class TestNodeCache extends BaseClassForTests
             client.create().creatingParentsIfNeeded().forPath("/test/node", "start".getBytes());
 
             cache = CuratorCacheBuilder.builder(client, "/test/node").forSingleNode().sendingRefreshEvents(false).build();
-            Assert.assertTrue(timing.awaitLatch(cache.start()));
 
             final CountDownLatch latch = new CountDownLatch(1);
             cache.getListenable().addListener(new CacheListener()
@@ -170,6 +170,7 @@ public class TestNodeCache extends BaseClassForTests
                     latch.countDown();
                 }
             });
+            Assert.assertTrue(timing.awaitLatch(cache.start()));
 
             KillSession.kill(client.getZookeeperClient().getZooKeeper());
             Thread.sleep(timing.multiple(1.5).session());
@@ -182,7 +183,7 @@ public class TestNodeCache extends BaseClassForTests
         finally
         {
             CloseableUtils.closeQuietly(cache);
-            TestCleanState.closeAndTestClean(client);
+            CloseableUtils.closeQuietly(client);
         }
     }
 
@@ -197,7 +198,6 @@ public class TestNodeCache extends BaseClassForTests
             client.create().forPath("/test");
 
             cache = CuratorCacheBuilder.builder(client, "/test/node").forSingleNode().sendingRefreshEvents(false).build();
-            Assert.assertTrue(timing.awaitLatch(cache.start()));
 
             final Semaphore semaphore = new Semaphore(0);
             cache.getListenable().addListener(new CacheListener()
@@ -208,6 +208,7 @@ public class TestNodeCache extends BaseClassForTests
                     semaphore.release();
                 }
             });
+            Assert.assertTrue(timing.awaitLatch(cache.start()));
 
             Assert.assertNull(cache.getMain());
 
@@ -226,7 +227,7 @@ public class TestNodeCache extends BaseClassForTests
         finally
         {
             CloseableUtils.closeQuietly(cache);
-            TestCleanState.closeAndTestClean(client);
+            CloseableUtils.closeQuietly(client);
         }
     }
 
@@ -241,7 +242,6 @@ public class TestNodeCache extends BaseClassForTests
             client.create().forPath("/test");
 
             cache = CuratorCacheBuilder.builder(client, "/test/node").forSingleNode().build();
-            cache.start();
 
             final BlockingQueue<CacheEvent> events = new LinkedBlockingQueue<>();
             cache.getListenable().addListener(new CacheListener()
@@ -252,12 +252,13 @@ public class TestNodeCache extends BaseClassForTests
                     events.add(event);
                 }
             });
+            cache.start();
             Assert.assertEquals(events.poll(timing.milliseconds(), TimeUnit.MILLISECONDS), CacheEvent.CACHE_REFRESHED);
         }
         finally
         {
             CloseableUtils.closeQuietly(cache);
-            TestCleanState.closeAndTestClean(client);
+            CloseableUtils.closeQuietly(client);
         }
     }
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestSingleLevelCuratorCache.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestSingleLevelCuratorCache.java b/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestSingleLevelCuratorCache.java
index 2a3591b..eb4710a 100644
--- a/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestSingleLevelCuratorCache.java
+++ b/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestSingleLevelCuratorCache.java
@@ -695,7 +695,7 @@ public class TestSingleLevelCuratorCache extends BaseClassForTests
             client.create().forPath("/test/two", "two".getBytes());
             Assert.assertTrue(latch.await(10, TimeUnit.SECONDS));
 
-            for ( CachedNode data : cache.getAll() )
+            for ( CachedNode data : cache.view().values() )
             {
                 if ( cacheData )
                 {

http://git-wip-us.apache.org/repos/asf/curator/blob/2148b6d1/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestTreeCache.java
----------------------------------------------------------------------
diff --git a/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestTreeCache.java b/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestTreeCache.java
index 7491a89..a04fb67 100644
--- a/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestTreeCache.java
+++ b/curator-recipes/src/test/java/org/apache/curator/framework/recipes/watch/TestTreeCache.java
@@ -213,7 +213,7 @@ public class TestTreeCache extends BaseTestTreeCache
         assertEvent(CacheEvent.CACHE_REFRESHED);
         assertNoMoreEvents();
 
-        Assert.assertTrue(cache.childNamesAtPath("/").contains("test"));
+        Assert.assertTrue(cache.childrenAtPath("/").keySet().contains("test"));
         assertChildNodeNames("/test", "one");
         assertChildNodeNames("/test/one");
         Assert.assertEquals(new String(cache.get("/test/one").getData()), "hey there");
@@ -232,7 +232,7 @@ public class TestTreeCache extends BaseTestTreeCache
         assertEvent(CacheEvent.CACHE_REFRESHED);
         assertNoMoreEvents();
 
-        Assert.assertTrue(cache.childNamesAtPath("/").contains("test"));
+        Assert.assertTrue(cache.childrenAtPath("/").keySet().contains("test"));
         assertChildNodeNames("/test");
         Assert.assertNull(cache.get("/test/one"));
         assertChildNodeNames("/test/one");