org.apache.curator.framework.recipes.cache

Class PathChildrenCache

java.lang.Object

org.apache.curator.framework.recipes.cache.PathChildrenCache

All Implemented Interfaces:

Closeable, AutoCloseable

public class PathChildrenCache
extends Object
implements Closeable

A utility that attempts to keep all data from all children of a ZK path locally cached. This class will watch the ZK path, respond to update/create/delete events, pull down the data, etc. You can register a listener that will get notified when changes occur.

IMPORTANT - it's not possible to stay transactionally in sync. Users of this class must be prepared for false-positives and false-negatives. Additionally, always use the version number when updating data to avoid overwriting another process' change.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PathChildrenCache.StartMode Method of priming cache on start(StartMode)

Constructor Summary

Constructors

Constructor and Description
PathChildrenCache(org.apache.curator.framework.CuratorFramework client, String path, boolean cacheData)
PathChildrenCache(org.apache.curator.framework.CuratorFramework client, String path, boolean cacheData, boolean dataIsCompressed, org.apache.curator.utils.CloseableExecutorService executorService)
PathChildrenCache(org.apache.curator.framework.CuratorFramework client, String path, boolean cacheData, boolean dataIsCompressed, ExecutorService executorService)
PathChildrenCache(org.apache.curator.framework.CuratorFramework client, String path, boolean cacheData, boolean dataIsCompressed, ThreadFactory threadFactory)
PathChildrenCache(org.apache.curator.framework.CuratorFramework client, String path, boolean cacheData, ThreadFactory threadFactory)
PathChildrenCache(org.apache.curator.framework.CuratorFramework client, String path, PathChildrenCacheMode mode) Deprecated. use PathChildrenCache(CuratorFramework, String, boolean) instead
PathChildrenCache(org.apache.curator.framework.CuratorFramework client, String path, PathChildrenCacheMode mode, ThreadFactory threadFactory) Deprecated. use PathChildrenCache(CuratorFramework, String, boolean, ThreadFactory) instead

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Clears the current data without beginning a new query and without generating any events for listeners.
void	clearAndRefresh() Clear out current data and begin a new query on the path
void	clearDataBytes(String fullPath) As a memory optimization, you can clear the cached data bytes for a node.
boolean	clearDataBytes(String fullPath, int ifVersion) As a memory optimization, you can clear the cached data bytes for a node.
void	close() Close/end the cache
protected void	ensurePath()
List<ChildData>	getCurrentData() Return the current data.
ChildData	getCurrentData(String fullPath) Return the current data for the given path.
org.apache.curator.framework.listen.ListenerContainer<PathChildrenCacheListener>	getListenable() Return the cache listenable
protected void	handleException(Throwable e) Default behavior is just to log the exception
void	rebuild() NOTE: this is a BLOCKING method.
void	rebuildNode(String fullPath) NOTE: this is a BLOCKING method.
protected void	remove(String fullPath)
void	start() Start the cache.
void	start(boolean buildInitial) Deprecated. use start(StartMode)
void	start(PathChildrenCache.StartMode mode) Start the cache.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PathChildrenCache

@Deprecated
public PathChildrenCache(org.apache.curator.framework.CuratorFramework client,
                            String path,
                            PathChildrenCacheMode mode)

Deprecated. use PathChildrenCache(CuratorFramework, String, boolean) instead

Parameters:

client - the client

path - path to watch

mode - caching mode

PathChildrenCache

@Deprecated
public PathChildrenCache(org.apache.curator.framework.CuratorFramework client,
                            String path,
                            PathChildrenCacheMode mode,
                            ThreadFactory threadFactory)

Deprecated. use PathChildrenCache(CuratorFramework, String, boolean, ThreadFactory) instead

Parameters:

client - the client

path - path to watch

mode - caching mode

threadFactory - factory to use when creating internal threads

PathChildrenCache

public PathChildrenCache(org.apache.curator.framework.CuratorFramework client,
                 String path,
                 boolean cacheData)

Parameters:

client - the client

path - path to watch

cacheData - if true, node contents are cached in addition to the stat

PathChildrenCache

public PathChildrenCache(org.apache.curator.framework.CuratorFramework client,
                 String path,
                 boolean cacheData,
                 ThreadFactory threadFactory)

Parameters:

client - the client

path - path to watch

cacheData - if true, node contents are cached in addition to the stat

threadFactory - factory to use when creating internal threads

PathChildrenCache

public PathChildrenCache(org.apache.curator.framework.CuratorFramework client,
                 String path,
                 boolean cacheData,
                 boolean dataIsCompressed,
                 ThreadFactory threadFactory)

Parameters:

client - the client

path - path to watch

cacheData - if true, node contents are cached in addition to the stat

dataIsCompressed - if true, data in the path is compressed

threadFactory - factory to use when creating internal threads

PathChildrenCache

public PathChildrenCache(org.apache.curator.framework.CuratorFramework client,
                 String path,
                 boolean cacheData,
                 boolean dataIsCompressed,
                 ExecutorService executorService)

Parameters:

client - the client

path - path to watch

cacheData - if true, node contents are cached in addition to the stat

dataIsCompressed - if true, data in the path is compressed

executorService - ExecutorService to use for the PathChildrenCache's background thread. This service should be single threaded, otherwise the cache may see inconsistent results.

PathChildrenCache

public PathChildrenCache(org.apache.curator.framework.CuratorFramework client,
                 String path,
                 boolean cacheData,
                 boolean dataIsCompressed,
                 org.apache.curator.utils.CloseableExecutorService executorService)

Parameters:

client - the client

path - path to watch

cacheData - if true, node contents are cached in addition to the stat

dataIsCompressed - if true, data in the path is compressed

executorService - Closeable ExecutorService to use for the PathChildrenCache's background thread. This service should be single threaded, otherwise the cache may see inconsistent results.

Method Detail

start

public void start()
           throws Exception

Start the cache. The cache is not started automatically. You must call this method.

Throws:

Exception - errors

start

@Deprecated
public void start(boolean buildInitial)
           throws Exception

Deprecated. use start(StartMode)

Same as start() but gives the option of doing an initial build

Parameters:

buildInitial - if true, rebuild() will be called before this method returns in order to get an initial view of the node; otherwise, the cache will be initialized asynchronously

Throws:

Exception - errors

start

public void start(PathChildrenCache.StartMode mode)
           throws Exception

Start the cache. The cache is not started automatically. You must call this method.

Parameters:

mode - Method for priming the cache

Throws:

Exception - errors

rebuild

public void rebuild()
             throws Exception

NOTE: this is a BLOCKING method. Completely rebuild the internal cache by querying for all needed data WITHOUT generating any events to send to listeners.

Throws:

Exception - errors

rebuildNode

public void rebuildNode(String fullPath)
                 throws Exception

NOTE: this is a BLOCKING method. Rebuild the internal cache for the given node by querying for all needed data WITHOUT generating any events to send to listeners.

Parameters:

fullPath - full path of the node to rebuild

Throws:

Exception - errors

close

public void close()
           throws IOException

Close/end the cache

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - errors

getListenable

public org.apache.curator.framework.listen.ListenerContainer<PathChildrenCacheListener> getListenable()

Return the cache listenable

Returns:

listenable

getCurrentData

public List<ChildData> getCurrentData()

Return the current data. There are no guarantees of accuracy. This is merely the most recent view of the data. The data is returned in sorted order.

Returns:

list of children and data

getCurrentData

public ChildData getCurrentData(String fullPath)

Return the current data for the given path. There are no guarantees of accuracy. This is merely the most recent view of the data. If there is no child with that path, null is returned.

Parameters:

fullPath - full path to the node to check

Returns:

data or null

clearDataBytes

public void clearDataBytes(String fullPath)

As a memory optimization, you can clear the cached data bytes for a node. Subsequent calls to ChildData.getData() for this node will return null.

Parameters:

fullPath - the path of the node to clear

clearDataBytes

public boolean clearDataBytes(String fullPath,
                     int ifVersion)

As a memory optimization, you can clear the cached data bytes for a node. Subsequent calls to ChildData.getData() for this node will return null.

Parameters:

fullPath - the path of the node to clear

ifVersion - if non-negative, only clear the data if the data's version matches this version

Returns:

true if the data was cleared

clearAndRefresh

public void clearAndRefresh()
                     throws Exception

Clear out current data and begin a new query on the path

Throws:

Exception - errors

clear

public void clear()

Clears the current data without beginning a new query and without generating any events for listeners.

handleException

protected void handleException(Throwable e)

Default behavior is just to log the exception

Parameters:

e - the exception

ensurePath

protected void ensurePath()
                   throws Exception

Throws:

Exception

remove

protected void remove(String fullPath)