curator-recipes/src/site/confluence/path-cache.confluence

h1. Path Cache

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

h2. Participating Classes
* PathChildrenCache
* PathChildrenCacheEvent
* PathChildrenCacheListener
* ChildData

h2. Usage
h3. Creating a PathChildrenCache
{code}
public PathChildrenCache(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
{code}

h2. 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:

{code}
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
}
{code}

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:
{code}
public void addListener(PathChildrenCacheListener listener)
     Add a change listener
Parameters:
listener - the listener
{code}

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