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
```