0
# Path Caching
1

2
Caching mechanisms for ZooKeeper paths to improve performance and reduce network overhead. Provides various caching strategies including path children caching, tree caching, and node caching with event notifications for cache updates.
3

4
## Capabilities
5

6
### PathChildrenCache
7

8
Caches the children of a ZooKeeper path and provides notifications when children are added, updated, or removed.
9

10
```java { .api }
11
/**
12
 * Caches children of a path and notifies of changes
13
 */
14
public class PathChildrenCache implements Closeable {
15
    /**
16
     * Create a new PathChildrenCache
17
     * @param client the curator client
18
     * @param path the path to cache children for
19
     * @param cacheData true to cache node data, false for just paths
20
     */
21
    public PathChildrenCache(CuratorFramework client, String path, boolean cacheData);
22
    
23
    /**
24
     * Start the cache
25
     * @throws Exception if cache cannot be started
26
     */
27
    public void start() throws Exception;
28
    
29
    /**
30
     * Start the cache with a specific mode
31
     * @param mode how to initialize the cache
32
     * @throws Exception if cache cannot be started
33
     */
34
    public void start(StartMode mode) throws Exception;
35
    
36
    /**
37
     * Get current cached children data
38
     * @return list of current children
39
     */
40
    public List<ChildData> getCurrentData();
41
    
42
    /**
43
     * Get current data for a specific child path
44
     * @param fullPath full path of the child
45
     * @return child data or null if not found
46
     */
47
    public ChildData getCurrentData(String fullPath);
48
    
49
    /**
50
     * Add a listener for cache events
51
     * @param listener the listener to add
52
     */
53
    public void getListenable().addListener(PathChildrenCacheListener listener);
54
    
55
    /**
56
     * Close the cache
57
     */
58
    public void close() throws IOException;
59
}
60

61
/**
62
 * Start modes for PathChildrenCache
63
 */
64
public enum StartMode {
65
    /** Start normally, don't populate cache until first event */
66
    NORMAL,
67
    /** Build initial cache by querying ZooKeeper */
68
    BUILD_INITIAL_CACHE,
69
    /** Build initial cache in background */
70
    POST_INITIALIZED_EVENT
71
}
72

73
/**
74
 * Listener interface for path children cache events
75
 */
76
public interface PathChildrenCacheListener {
77
    /**
78
     * Called when a cache event occurs
79
     * @param client the curator client
80
     * @param event the cache event
81
     */
82
    void childEvent(CuratorFramework client, PathChildrenCacheEvent event) throws Exception;
83
}
84

85
/**
86
 * Represents cached data for a child node
87
 */
88
public class ChildData {
89
    /**
90
     * Get the full path of this child
91
     */
92
    public String getPath();
93
    
94
    /**
95
     * Get the stat information for this child
96
     */
97
    public Stat getStat();
98
    
99
    /**
100
     * Get the data bytes for this child
101
     */
102
    public byte[] getData();
103
}
104
```
105

106
**Usage Example:**
107

108
```java
109
PathChildrenCache cache = new PathChildrenCache(client, "/app/workers", true);
110

111
cache.getListenable().addListener(new PathChildrenCacheListener() {
112
    @Override
113
    public void childEvent(CuratorFramework client, PathChildrenCacheEvent event) throws Exception {
114
        switch (event.getType()) {
115
            case CHILD_ADDED:
116
                System.out.println("Child added: " + event.getData().getPath());
117
                break;
118
            case CHILD_UPDATED:
119
                System.out.println("Child updated: " + event.getData().getPath());
120
                break;
121
            case CHILD_REMOVED:
122
                System.out.println("Child removed: " + event.getData().getPath());
123
                break;
124
        }
125
    }
126
});
127

128
cache.start(StartMode.BUILD_INITIAL_CACHE);
129

130
// Cache now tracks all children of /app/workers
131
List<ChildData> currentChildren = cache.getCurrentData();
132
```
133

134
### TreeCache
135

136
Caches an entire tree of ZooKeeper nodes, providing notifications for any changes within the tree.
137

138
```java { .api }
139
/**
140
 * Caches a complete tree of ZooKeeper nodes
141
 */
142
public class TreeCache implements Closeable {
143
    /**
144
     * Create a new TreeCache
145
     * @param client the curator client
146
     * @param path the root path to cache
147
     */
148
    public TreeCache(CuratorFramework client, String path);
149
    
150
    /**
151
     * Start the cache
152
     * @throws Exception if cache cannot be started
153
     */
154
    public void start() throws Exception;
155
    
156
    /**
157
     * Get current children at a specific path
158
     * @param fullPath the path to get children for
159
     * @return map of child name to child data
160
     */
161
    public Map<String, ChildData> getCurrentChildren(String fullPath);
162
    
163
    /**
164
     * Get current data for a specific path
165
     * @param fullPath the path to get data for
166
     * @return child data or null if not found
167
     */
168
    public ChildData getCurrentData(String fullPath);
169
    
170
    /**
171
     * Add a listener for cache events
172
     * @param listener the listener to add
173
     */
174
    public void getListenable().addListener(TreeCacheListener listener);
175
    
176
    /**
177
     * Close the cache
178
     */
179
    public void close() throws IOException;
180
}
181

182
/**
183
 * Listener interface for tree cache events
184
 */
185
public interface TreeCacheListener {
186
    /**
187
     * Called when a tree event occurs
188
     * @param client the curator client
189
     * @param event the tree event
190
     */
191
    void childEvent(CuratorFramework client, TreeCacheEvent event) throws Exception;
192
}
193
```
194

195
### NodeCache
196

197
Caches data for a single ZooKeeper node and provides notifications when the node changes.
198

199
```java { .api }
200
/**
201
 * Caches data for a single node
202
 */
203
public class NodeCache implements Closeable {
204
    /**
205
     * Create a new NodeCache
206
     * @param client the curator client
207
     * @param path the path to cache
208
     * @param dataIsCompressed true if node data is compressed
209
     */
210
    public NodeCache(CuratorFramework client, String path, boolean dataIsCompressed);
211
    
212
    /**
213
     * Start the cache
214
     * @throws Exception if cache cannot be started
215
     */
216
    public void start() throws Exception;
217
    
218
    /**
219
     * Start the cache with initial data loading
220
     * @param buildInitial true to load initial data
221
     * @throws Exception if cache cannot be started
222
     */
223
    public void start(boolean buildInitial) throws Exception;
224
    
225
    /**
226
     * Get current cached data
227
     * @return current node data or null if not cached
228
     */
229
    public ChildData getCurrentData();
230
    
231
    /**
232
     * Add a listener for node changes
233
     * @param listener the listener to add
234
     */
235
    public void getListenable().addListener(NodeCacheListener listener);
236
    
237
    /**
238
     * Close the cache
239
     */
240
    public void close() throws IOException;
241
}
242

243
/**
244
 * Listener interface for node cache events
245
 */
246
public interface NodeCacheListener {
247
    /**
248
     * Called when node data changes
249
     */
250
    void nodeChanged() throws Exception;
251
}
252
```
253

254
**Combined Caching Example:**
255

256
```java
257
// Cache a specific configuration node
258
NodeCache configCache = new NodeCache(client, "/app/config", false);
259
configCache.getListenable().addListener(new NodeCacheListener() {
260
    @Override
261
    public void nodeChanged() throws Exception {
262
        ChildData data = configCache.getCurrentData();
263
        if (data != null) {
264
            String config = new String(data.getData());
265
            System.out.println("Configuration updated: " + config);
266
            reloadConfiguration(config);
267
        }
268
    }
269
});
270
configCache.start(true);
271

272
// Cache all service instances
273
PathChildrenCache serviceCache = new PathChildrenCache(client, "/app/services", true);
274
serviceCache.getListenable().addListener(new PathChildrenCacheListener() {
275
    @Override
276
    public void childEvent(CuratorFramework client, PathChildrenCacheEvent event) throws Exception {
277
        if (event.getType() == PathChildrenCacheEvent.Type.CHILD_ADDED) {
278
            String servicePath = event.getData().getPath();
279
            String serviceData = new String(event.getData().getData());
280
            System.out.println("New service registered: " + servicePath + " -> " + serviceData);
281
            registerService(servicePath, serviceData);
282
        }
283
    }
284
});
285
serviceCache.start(StartMode.BUILD_INITIAL_CACHE);
286

287
// Cache entire application tree
288
TreeCache appCache = new TreeCache(client, "/app");
289
appCache.getListenable().addListener(new TreeCacheListener() {
290
    @Override
291
    public void childEvent(CuratorFramework client, TreeCacheEvent event) throws Exception {
292
        switch (event.getType()) {
293
            case NODE_ADDED:
294
                System.out.println("Node added in app tree: " + event.getData().getPath());
295
                break;
296
            case NODE_UPDATED:
297
                System.out.println("Node updated in app tree: " + event.getData().getPath());
298
                break;
299
            case NODE_REMOVED:
300
                System.out.println("Node removed from app tree: " + event.getData().getPath());
301
                break;
302
        }
303
    }
304
});
305
appCache.start();
306
```