Skip to main content

Recipe: Path Cache

Description

A Path Cache is used to watch a ZNode. Whenever a child is added, updated or removed, the Path Cache will change its state to contain the current set of children, the children's data and the children's state.

Participating Classes

  • PathChildrenCache
  • PathChildrenCacheEvent
  • PathChildrenCacheListener
  • ChildData

Creating a PathChildrenCache

// Parameters:
// client - the client
// path - path to watch
// cacheData - if true, node contents are cached in addition to the stat
public PathChildrenCache(CuratorFramework client, String path, boolean cacheData);

General Usage

The cache must be started by calling start(). Call close() when you are through with the cache.

There are two versions of start(). The no-arg version gives default behavior. The other version takes an enumeration that allows you to control how the initial cache is warmed:

public enum StartMode {
/**
* cache will _not_ be primed. i.e. it will start empty and you will receive
* events for all nodes added, etc.
*/
NORMAL,

/**
* rebuild() will be called before this method returns in
* order to get an initial view of the node.
*/
BUILD_INITIAL_CACHE,

/**
* After cache is primed with initial values (in the background) a
* PathChildrenCacheEvent.Type.INITIALIZED event will be posted
*/
POST_INITIALIZED_EVENT
}

At any time, call getCurrentData() to get the current state of the cache. You can also register to be notified when a change occurs by calling getListenable() and then:

// Add a change listener
// Parameters:
// listener - the listener
public void addListener(PathChildrenCacheListener listener)

Error Handling

PathChildrenCache instances internally monitor a ConnectionStateListener. If the connection state changes, the cache is reset (the PathChildrenCacheListener will receive a RESET).