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");