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).