0
# Client Factory and Configuration
1

2
Factory for creating and configuring CuratorFramework instances with comprehensive options for connection management, authentication, compression, namespacing, and error handling policies.
3

4
## Capabilities
5

6
### CuratorFrameworkFactory
7

8
Main factory class for creating CuratorFramework instances with static factory methods and a comprehensive builder pattern.
9

10
```java { .api }
11
/**
12
 * Factory methods for creating framework-style clients
13
 */
14
public class CuratorFrameworkFactory {
15
    /**
16
     * Create a new client with default session timeout and default connection timeout
17
     * @param connectString list of servers to connect to
18
     * @param retryPolicy retry policy to use
19
     * @return client
20
     */
21
    public static CuratorFramework newClient(String connectString, RetryPolicy retryPolicy);
22
    
23
    /**
24
     * Create a new client
25
     * @param connectString list of servers to connect to
26
     * @param sessionTimeoutMs session timeout
27
     * @param connectionTimeoutMs connection timeout
28
     * @param retryPolicy retry policy to use
29
     * @return client
30
     */
31
    public static CuratorFramework newClient(
32
        String connectString, 
33
        int sessionTimeoutMs, 
34
        int connectionTimeoutMs, 
35
        RetryPolicy retryPolicy
36
    );
37
    
38
    /**
39
     * Create a new client with ZKClientConfig support (ZooKeeper 3.6.1+)
40
     * @param connectString list of servers to connect to
41
     * @param sessionTimeoutMs session timeout
42
     * @param connectionTimeoutMs connection timeout
43
     * @param retryPolicy retry policy to use
44
     * @param zkClientConfig ZKClientConfig
45
     * @return client
46
     */
47
    public static CuratorFramework newClient(
48
        String connectString,
49
        int sessionTimeoutMs,
50
        int connectionTimeoutMs,
51
        RetryPolicy retryPolicy,
52
        ZKClientConfig zkClientConfig
53
    );
54
    
55
    /**
56
     * Return a new builder that builds a CuratorFramework
57
     * @return new builder
58
     */
59
    public static Builder builder();
60
    
61
    /**
62
     * Return the local address as bytes that can be used as a node payload
63
     * @return local address bytes
64
     */
65
    public static byte[] getLocalAddress();
66
}
67
```
68

69
**Usage Examples:**
70

71
```java
72
import org.apache.curator.framework.CuratorFramework;
73
import org.apache.curator.framework.CuratorFrameworkFactory;
74
import org.apache.curator.retry.ExponentialBackoffRetry;
75
import org.apache.curator.retry.RetryNTimes;
76

77
// Simple client creation
78
RetryPolicy retryPolicy = new ExponentialBackoffRetry(1000, 3);
79
CuratorFramework client = CuratorFrameworkFactory.newClient(
80
    "localhost:2181", 
81
    retryPolicy
82
);
83

84
// Client with custom timeouts
85
CuratorFramework client2 = CuratorFrameworkFactory.newClient(
86
    "zk1:2181,zk2:2181,zk3:2181",
87
    30000,  // 30 second session timeout
88
    10000,  // 10 second connection timeout
89
    new RetryNTimes(5, 2000)
90
);
91
```
92

93
### CuratorFrameworkFactory.Builder
94

95
Comprehensive builder for configuring all aspects of CuratorFramework instances including connection parameters, authentication, compression, namespacing, and advanced policies.
96

97
```java { .api }
98
public static class Builder {
99
    /**
100
     * Apply the current values and build a new CuratorFramework
101
     * @return new CuratorFramework
102
     */
103
    public CuratorFramework build();
104
    
105
    /**
106
     * Apply the current values and build a new temporary CuratorFramework
107
     * @return temp instance
108
     */
109
    public CuratorTempFramework buildTemp();
110
    
111
    /**
112
     * Apply the current values and build a new temporary CuratorFramework
113
     * @param inactiveThreshold number of milliseconds of inactivity to cause connection close
114
     * @param unit threshold unit
115
     * @return temp instance
116
     */
117
    public CuratorTempFramework buildTemp(long inactiveThreshold, TimeUnit unit);
118
    
119
    /**
120
     * Set the list of servers to connect to
121
     * @param connectString list of servers to connect to
122
     * @return this
123
     */
124
    public Builder connectString(String connectString);
125
    
126
    /**
127
     * Set the list ensemble provider
128
     * @param ensembleProvider the ensemble provider to use
129
     * @return this
130
     */
131
    public Builder ensembleProvider(EnsembleProvider ensembleProvider);
132
    
133
    /**
134
     * Configure if the ensemble configuration changes will be watched
135
     * @param withEnsembleTracker use false if you want to avoid following ensemble configuration changes
136
     * @return this
137
     */
138
    public Builder ensembleTracker(boolean withEnsembleTracker);
139
    
140
    /**
141
     * @param sessionTimeoutMs session timeout
142
     * @return this
143
     */
144
    public Builder sessionTimeoutMs(int sessionTimeoutMs);
145
    
146
    /**
147
     * @param connectionTimeoutMs connection timeout
148
     * @return this
149
     */
150
    public Builder connectionTimeoutMs(int connectionTimeoutMs);
151
    
152
    /**
153
     * @param maxCloseWaitMs time to wait during close to join background threads
154
     * @return this
155
     */
156
    public Builder maxCloseWaitMs(int maxCloseWaitMs);
157
    
158
    /**
159
     * @param retryPolicy retry policy to use
160
     * @return this
161
     */
162
    public Builder retryPolicy(RetryPolicy retryPolicy);
163
    
164
    /**
165
     * @param threadFactory thread factory used to create Executor Services
166
     * @return this
167
     */
168
    public Builder threadFactory(ThreadFactory threadFactory);
169
    
170
    /**
171
     * Set namespace for all paths
172
     * @param namespace the namespace
173
     * @return this
174
     */
175
    public Builder namespace(String namespace);
176
    
177
    /**
178
     * Add connection authorization
179
     * @param scheme the scheme
180
     * @param auth the auth bytes
181
     * @return this
182
     */
183
    public Builder authorization(String scheme, byte[] auth);
184
    
185
    /**
186
     * Add connection authorization
187
     * @param authInfos list of AuthInfo objects with scheme and auth
188
     * @return this
189
     */
190
    public Builder authorization(List<AuthInfo> authInfos);
191
    
192
    /**
193
     * Set the data to use when PathAndBytesable.forPath(String) is used
194
     * @param defaultData new default data to use
195
     * @return this
196
     */
197
    public Builder defaultData(byte[] defaultData);
198
    
199
    /**
200
     * @param compressionProvider the compression provider
201
     * @return this
202
     */
203
    public Builder compressionProvider(CompressionProvider compressionProvider);
204
    
205
    /**
206
     * Enable compression by default on all read and write calls
207
     * @return this
208
     */
209
    public Builder enableCompression();
210
    
211
    /**
212
     * @param zookeeperFactory the zookeeper factory to use
213
     * @return this
214
     */
215
    public Builder zookeeperFactory(ZookeeperFactory zookeeperFactory);
216
    
217
    /**
218
     * @param aclProvider a provider for ACLs
219
     * @return this
220
     */
221
    public Builder aclProvider(ACLProvider aclProvider);
222
    
223
    /**
224
     * @param canBeReadOnly if true, allow ZooKeeper client to enter read only mode
225
     * @return this
226
     */
227
    public Builder canBeReadOnly(boolean canBeReadOnly);
228
    
229
    /**
230
     * Turn off automatic container parent creation
231
     * @return this
232
     */
233
    public Builder dontUseContainerParents();
234
    
235
    /**
236
     * Set the error policy to use
237
     * @param connectionStateErrorPolicy new error policy
238
     * @return this
239
     */
240
    public Builder connectionStateErrorPolicy(ConnectionStateErrorPolicy connectionStateErrorPolicy);
241
    
242
    /**
243
     * Set a timeout for CuratorZookeeperClient.close()
244
     * @param waitForShutdownTimeoutMs default timeout
245
     * @return this
246
     */
247
    public Builder waitForShutdownTimeoutMs(int waitForShutdownTimeoutMs);
248
    
249
    /**
250
     * Set simulated session expiration percentage
251
     * @param simulatedSessionExpirationPercent new simulated session expiration percentage
252
     * @return this
253
     */
254
    public Builder simulatedSessionExpirationPercent(int simulatedSessionExpirationPercent);
255
    
256
    /**
257
     * Set ZKClientConfig for ZooKeeper 3.6.1+
258
     * @param zkClientConfig ZKClientConfig
259
     * @return this
260
     */
261
    public Builder zkClientConfig(ZKClientConfig zkClientConfig);
262
    
263
    /**
264
     * Add an enforced schema set
265
     * @param schemaSet the schema set
266
     * @return this
267
     */
268
    public Builder schemaSet(SchemaSet schemaSet);
269
    
270
    /**
271
     * Set custom executor for safe operations
272
     * @param runSafeService executor to use for calls to notifyAll from Watcher callbacks etc
273
     * @return this
274
     */
275
    public Builder runSafeService(Executor runSafeService);
276
    
277
    /**
278
     * Sets the connection state listener manager factory
279
     * @param connectionStateListenerManagerFactory manager factory to use
280
     * @return this
281
     */
282
    public Builder connectionStateListenerManagerFactory(
283
        ConnectionStateListenerManagerFactory connectionStateListenerManagerFactory
284
    );
285
    
286
    /**
287
     * Set ZooKeeper compatibility mode
288
     * @param zookeeperCompatibility compatibility mode
289
     * @return this
290
     */
291
    public Builder zookeeperCompatibility(ZookeeperCompatibility zookeeperCompatibility);
292
}
293
```
294

295
**Usage Examples:**
296

297
```java
298
import org.apache.curator.framework.CuratorFramework;
299
import org.apache.curator.framework.CuratorFrameworkFactory;
300
import org.apache.curator.retry.ExponentialBackoffRetry;
301
import org.apache.curator.framework.state.StandardConnectionStateErrorPolicy;
302

303
// Basic builder usage
304
CuratorFramework client = CuratorFrameworkFactory.builder()
305
    .connectString("localhost:2181")
306
    .sessionTimeoutMs(30000)
307
    .connectionTimeoutMs(10000)
308
    .retryPolicy(new ExponentialBackoffRetry(1000, 3))
309
    .build();
310

311
// Advanced configuration
312
CuratorFramework advancedClient = CuratorFrameworkFactory.builder()
313
    .connectString("zk1:2181,zk2:2181,zk3:2181")
314
    .sessionTimeoutMs(60000)
315
    .connectionTimeoutMs(15000)
316
    .retryPolicy(new ExponentialBackoffRetry(1000, 5))
317
    .namespace("myapp")
318
    .authorization("digest", "user:password".getBytes())
319
    .enableCompression()
320
    .canBeReadOnly(true)
321
    .connectionStateErrorPolicy(new StandardConnectionStateErrorPolicy())
322
    .build();
323

324
// Temporary client for single operations over unreliable networks
325
CuratorTempFramework tempClient = CuratorFrameworkFactory.builder()
326
    .connectString("remote-zk:2181")
327
    .retryPolicy(new ExponentialBackoffRetry(2000, 10))
328
    .buildTemp(TimeUnit.MINUTES.toMillis(5), TimeUnit.MILLISECONDS);
329
```
330

331
### CuratorTempFramework
332

333
Limited client interface designed for single requests to ZooKeeper ensembles over failure-prone networks such as WANs, with automatic connection cleanup after periods of inactivity.
334

335
```java { .api }
336
/**
337
 * Temporary CuratorFramework instances are meant for single requests to ZooKeeper 
338
 * ensembles over a failure prone network such as a WAN
339
 */
340
public interface CuratorTempFramework {
341
    /**
342
     * Stop the client
343
     */
344
    void close();
345
    
346
    /**
347
     * Start a transaction builder
348
     * @return builder object
349
     */
350
    CuratorTransaction inTransaction();
351
    
352
    /**
353
     * Start a get data builder
354
     * @return builder object
355
     */
356
    TempGetDataBuilder getData();
357
}
358
```
359

360
### Constants and Defaults
361

362
```java { .api }
363
public class CuratorFrameworkFactory {
364
    public static final int DEFAULT_SESSION_TIMEOUT_MS = 60000;
365
    public static final int DEFAULT_CONNECTION_TIMEOUT_MS = 15000;
366
    public static final long DEFAULT_INACTIVE_THRESHOLD_MS = 180000; // 3 minutes
367
    public static final int DEFAULT_CLOSE_WAIT_MS = 1000;
368
    public static final boolean DEFAULT_WITH_ENSEMBLE_TRACKER = true;
369
}
370
```