0
# Apache Curator Framework
1
2
Apache Curator Framework is a high-level Java client library for Apache ZooKeeper that provides a comprehensive set of APIs and utilities to greatly simplify the use of ZooKeeper in distributed applications. The framework abstracts away the complexity of ZooKeeper's low-level operations, offering robust connection management with automatic retry policies, session state handling, and built-in recipes for common distributed computing patterns.
3
4
## Package Information
5
6
- **Package Name**: curator-framework
7
- **Package Type**: maven
8
- **Group ID**: org.apache.curator
9
- **Artifact ID**: curator-framework
10
- **Language**: Java
11
- **Installation**:
12
```xml
13
<dependency>
14
<groupId>org.apache.curator</groupId>
15
<artifactId>curator-framework</artifactId>
16
<version>5.9.0</version>
17
</dependency>
18
```
19
20
## Core Imports
21
22
```java
23
import org.apache.curator.framework.CuratorFramework;
24
import org.apache.curator.framework.CuratorFrameworkFactory;
25
import org.apache.curator.RetryPolicy;
26
import org.apache.curator.retry.ExponentialBackoffRetry;
27
```
28
29
## Basic Usage
30
31
```java
32
import org.apache.curator.framework.CuratorFramework;
33
import org.apache.curator.framework.CuratorFrameworkFactory;
34
import org.apache.curator.retry.ExponentialBackoffRetry;
35
import org.apache.curator.framework.state.ConnectionState;
36
import org.apache.curator.framework.state.ConnectionStateListener;
37
38
public class BasicCuratorExample {
39
public static void main(String[] args) throws Exception {
40
// Create retry policy
41
RetryPolicy retryPolicy = new ExponentialBackoffRetry(1000, 3);
42
43
// Create and start the client
44
CuratorFramework client = CuratorFrameworkFactory.newClient(
45
"localhost:2181",
46
retryPolicy
47
);
48
client.start();
49
50
// Wait for connection
51
client.blockUntilConnected();
52
53
// Basic operations
54
// Create a node
55
client.create()
56
.creatingParentsIfNeeded()
57
.forPath("/my/path", "some data".getBytes());
58
59
// Get data from a node
60
byte[] data = client.getData().forPath("/my/path");
61
System.out.println("Data: " + new String(data));
62
63
// Set data on a node
64
client.setData().forPath("/my/path", "updated data".getBytes());
65
66
// Delete a node
67
client.delete()
68
.deletingChildrenIfNeeded()
69
.forPath("/my/path");
70
71
// Close the client
72
client.close();
73
}
74
}
75
```
76
77
## Architecture
78
79
Apache Curator Framework is built around several key architectural patterns:
80
81
- **Builder Pattern**: Fluent, type-safe API construction through extensive builder interfaces
82
- **Factory Pattern**: Centralized client configuration via `CuratorFrameworkFactory`
83
- **Listener Pattern**: Event-driven programming with connection state and curator event listeners
84
- **Facade Pattern**: Simplified interface over complex ZooKeeper operations with automatic path management
85
- **Command Pattern**: Background operations with callbacks and error handling
86
- **Namespace Pattern**: Automatic path prefixing for multi-tenant applications
87
88
The framework provides robust connection management, automatic retry mechanisms, schema validation, and comprehensive transaction support, making it the foundation for building reliable distributed systems with ZooKeeper.
89
90
## Capabilities
91
92
### Client Factory and Configuration
93
94
Factory for creating and configuring CuratorFramework instances with comprehensive options for connection management, authentication, compression, namespacing, and error handling policies.
95
96
```java { .api }
97
public static CuratorFramework newClient(String connectString, RetryPolicy retryPolicy);
98
public static CuratorFramework newClient(String connectString, int sessionTimeoutMs, int connectionTimeoutMs, RetryPolicy retryPolicy);
99
public static CuratorFrameworkFactory.Builder builder();
100
101
public static class Builder {
102
public CuratorFramework build();
103
public CuratorTempFramework buildTemp();
104
public Builder connectString(String connectString);
105
public Builder sessionTimeoutMs(int sessionTimeoutMs);
106
public Builder connectionTimeoutMs(int connectionTimeoutMs);
107
public Builder retryPolicy(RetryPolicy retryPolicy);
108
public Builder namespace(String namespace);
109
public Builder authorization(String scheme, byte[] auth);
110
public Builder compressionProvider(CompressionProvider compressionProvider);
111
public Builder enableCompression();
112
public Builder aclProvider(ACLProvider aclProvider);
113
public Builder canBeReadOnly(boolean canBeReadOnly);
114
public Builder schemaSet(SchemaSet schemaSet);
115
}
116
```
117
118
[Client Factory and Configuration](./client-factory.md)
119
120
### Core Framework Operations
121
122
Main CuratorFramework interface providing all fundamental ZooKeeper operations through fluent builder APIs including create, delete, exists, getData, setData, getChildren, ACL management, and configuration operations.
123
124
```java { .api }
125
public interface CuratorFramework extends Closeable {
126
void start();
127
void close();
128
CuratorFrameworkState getState();
129
130
CreateBuilder create();
131
DeleteBuilder delete();
132
ExistsBuilder checkExists();
133
GetDataBuilder getData();
134
SetDataBuilder setData();
135
GetChildrenBuilder getChildren();
136
GetACLBuilder getACL();
137
SetACLBuilder setACL();
138
ReconfigBuilder reconfig();
139
GetConfigBuilder getConfig();
140
141
CuratorFramework usingNamespace(String newNamespace);
142
String getNamespace();
143
boolean blockUntilConnected(int maxWaitTime, TimeUnit units);
144
void createContainers(String path) throws Exception;
145
}
146
```
147
148
[Core Framework Operations](./core-operations.md)
149
150
### Transaction Support
151
152
Multi-operation transaction capabilities enabling atomic operations across multiple ZooKeeper nodes with support for create, delete, setData, and check operations within a single transaction context.
153
154
```java { .api }
155
public interface CuratorMultiTransaction {
156
CuratorMultiTransactionMain forOperations(CuratorOp... operations);
157
CuratorMultiTransactionMain forOperations(Iterable<CuratorOp> operations);
158
}
159
160
public interface TransactionOp {
161
TransactionCreateBuilder<CuratorOp> create();
162
TransactionDeleteBuilder<CuratorOp> delete();
163
TransactionSetDataBuilder<CuratorOp> setData();
164
TransactionCheckBuilder<CuratorOp> check();
165
}
166
167
public class CuratorTransactionResult {
168
public OperationType getType();
169
public String getForPath();
170
public String getResultPath();
171
public Stat getResultStat();
172
public int getError();
173
}
174
```
175
176
[Transaction Support](./transactions.md)
177
178
### Event and State Management
179
180
Comprehensive event handling and connection state management with listeners for background operations, connection state changes, and unhandled errors, providing robust monitoring and error handling capabilities.
181
182
```java { .api }
183
public interface CuratorEvent {
184
CuratorEventType getType();
185
int getResultCode();
186
String getPath();
187
Object getContext();
188
Stat getStat();
189
byte[] getData();
190
String getName();
191
List<String> getChildren();
192
List<ACL> getACLList();
193
WatchedEvent getWatchedEvent();
194
}
195
196
public enum ConnectionState {
197
CONNECTED, SUSPENDED, RECONNECTED, LOST, READ_ONLY;
198
boolean isConnected();
199
}
200
201
public interface ConnectionStateListener {
202
void stateChanged(CuratorFramework client, ConnectionState newState);
203
}
204
205
public interface CuratorListener {
206
void eventReceived(CuratorFramework client, CuratorEvent event);
207
}
208
```
209
210
[Event and State Management](./events-state.md)
211
212
### Watcher Management
213
214
Enhanced watcher lifecycle management with support for both traditional ZooKeeper watchers and newer persistent watches, including automatic cleanup and removal capabilities for reliable resource management.
215
216
```java { .api }
217
public interface CuratorWatcher {
218
void process(WatchedEvent event) throws Exception;
219
}
220
221
public interface WatchesBuilder extends RemoveWatchesBuilder {
222
// ZooKeeper 3.6+ persistent watch support
223
}
224
225
public interface RemoveWatchesBuilder {
226
RemoveWatchesLocal ofType(RemoveWatchesType type);
227
BackgroundPathable<Void> usingWatcher(Watcher watcher);
228
BackgroundPathable<Void> usingWatcher(CuratorWatcher watcher);
229
}
230
231
public interface WatcherRemoveCuratorFramework extends CuratorFramework {
232
void removeWatchers();
233
}
234
```
235
236
[Watcher Management](./watchers.md)
237
238
### Schema Validation
239
240
Optional schema validation system for enforcing data structure and path constraints on ZooKeeper nodes, providing data integrity and consistency guarantees in distributed applications.
241
242
```java { .api }
243
public class SchemaSet {
244
public static SchemaSet getDefaultSchemaSet();
245
public Schema getSchema(String path);
246
public Schema getNamedSchema(String name);
247
public Collection<Schema> getSchemas();
248
public String toDocumentation();
249
}
250
251
public class Schema {
252
public String getName();
253
public String getPath();
254
public Pattern getPathRegex();
255
public SchemaValidator getSchemaValidator();
256
public String toDocumentation();
257
}
258
259
public interface SchemaValidator {
260
boolean isValid(String path, byte[] data, Stat stat);
261
}
262
263
public class SchemaBuilder {
264
public SchemaBuilder name(String name);
265
public SchemaBuilder path(String path);
266
public SchemaBuilder pathRegex(String pathRegex);
267
public SchemaBuilder dataValidator(SchemaValidator validator);
268
public Schema build();
269
}
270
```
271
272
[Schema Validation](./schema-validation.md)
273
274
## Types
275
276
### Core Types
277
278
```java { .api }
279
public class AuthInfo {
280
public AuthInfo(String scheme, byte[] auth);
281
public String getScheme();
282
public byte[] getAuth();
283
}
284
285
public enum CuratorFrameworkState {
286
LATENT, STARTED, STOPPED
287
}
288
289
public enum CuratorEventType {
290
CREATE, DELETE, EXISTS, GET_DATA, SET_DATA, CHILDREN,
291
SYNC, GET_ACL, SET_ACL, TRANSACTION, GET_CONFIG, RECONFIG,
292
WATCHED, REMOVE_WATCHES, ADD_WATCH, CLOSING
293
}
294
295
public enum OperationType {
296
CREATE, DELETE, SET_DATA, CHECK
297
}
298
299
public enum RemoveWatchesType {
300
Any, Data, Child
301
}
302
```
303
304
### Exception Types
305
306
```java { .api }
307
public class CuratorClosedException extends IllegalStateException {
308
// Thrown when operations attempted on closed client
309
}
310
311
public class SchemaViolation extends IllegalArgumentException {
312
// Thrown when schema validation fails
313
}
314
```
315
316
### Provider Interfaces
317
318
```java { .api }
319
public interface ACLProvider {
320
List<ACL> getDefaultAcl();
321
List<ACL> getAclForPath(String path);
322
}
323
324
public interface CompressionProvider {
325
byte[] compress(String path, byte[] data) throws Exception;
326
byte[] decompress(String path, byte[] compressedData) throws Exception;
327
}
328
```