0
# Core Framework Operations
1

2
Main CuratorFramework interface providing all fundamental ZooKeeper operations through fluent builder APIs including create, delete, exists, getData, setData, getChildren, ACL management, and configuration operations.
3

4
## Imports
5

6
```java
7
import org.apache.curator.framework.CuratorFramework;
8
import org.apache.curator.framework.api.*;
9
import org.apache.curator.framework.state.ConnectionStateListener;
10
import org.apache.curator.framework.listen.Listenable;
11
import org.apache.zookeeper.AddWatchMode;
12
import java.util.concurrent.CompletableFuture;
13
import java.util.concurrent.TimeUnit;
14
```
15

16
## Capabilities
17

18
### CuratorFramework Interface
19

20
The main interface that provides access to all ZooKeeper operations through a fluent, builder-based API.
21

22
```java { .api }
23
/**
24
 * Zookeeper framework-style client
25
 */
26
public interface CuratorFramework extends Closeable {
27
    /**
28
     * Start the client. Most mutator methods will not work until the client is started
29
     */
30
    void start();
31
    
32
    /**
33
     * Stop the client
34
     */
35
    void close();
36
    
37
    /**
38
     * Returns the state of this instance
39
     * @return state
40
     */
41
    CuratorFrameworkState getState();
42
    
43
    /**
44
     * Return true if the client is started, not closed, etc.
45
     * @return true/false
46
     * @deprecated use getState() instead
47
     */
48
    @Deprecated
49
    boolean isStarted();
50
    
51
    /**
52
     * Block until a connection to ZooKeeper is available or the maxWaitTime has been exceeded
53
     * @param maxWaitTime The maximum wait time
54
     * @param units The time units for the maximum wait time
55
     * @return True if connection has been established, false otherwise
56
     * @throws InterruptedException If interrupted while waiting
57
     */
58
    boolean blockUntilConnected(int maxWaitTime, TimeUnit units) throws InterruptedException;
59
    
60
    /**
61
     * Block until a connection to ZooKeeper is available
62
     * @throws InterruptedException If interrupted while waiting
63
     */
64
    void blockUntilConnected() throws InterruptedException;
65
    
66
    /**
67
     * Create all nodes in the specified path as containers if they don't already exist
68
     * @param path path to create
69
     * @throws Exception errors
70
     */
71
    void createContainers(String path) throws Exception;
72
    
73
    /**
74
     * Returns a facade of the current instance that uses the specified namespace
75
     * @param newNamespace the new namespace or null for none
76
     * @return facade
77
     */
78
    CuratorFramework usingNamespace(String newNamespace);
79
    
80
    /**
81
     * Return the current namespace or "" if none
82
     * @return namespace
83
     */
84
    String getNamespace();
85
    
86
    /**
87
     * Return the managed zookeeper client
88
     * @return client
89
     */
90
    CuratorZookeeperClient getZookeeperClient();
91
    
92
    /**
93
     * Returns a facade that tracks watchers created and allows one-shot removal
94
     * @return facade
95
     */
96
    WatcherRemoveCuratorFramework newWatcherRemoveCuratorFramework();
97
    
98
    /**
99
     * Return the configured error policy
100
     * @return error policy
101
     */
102
    ConnectionStateErrorPolicy getConnectionStateErrorPolicy();
103
    
104
    /**
105
     * Return this instance's schema set
106
     * @return schema set
107
     */
108
    SchemaSet getSchemaSet();
109
    
110
    /**
111
     * Return whether compression is enabled by default
112
     * @return if compression is enabled
113
     */
114
    boolean compressionEnabled();
115
    
116
    /**
117
     * Run code safely from ZooKeeper's event thread
118
     * @param runnable proc to call from a safe internal thread
119
     * @return a CompletableFuture that can be used to monitor when the call is complete
120
     */
121
    CompletableFuture<Void> runSafe(Runnable runnable);
122
    
123
    // Builder methods for operations
124
    CreateBuilder create();
125
    DeleteBuilder delete();
126
    ExistsBuilder checkExists();
127
    GetDataBuilder getData();
128
    SetDataBuilder setData();
129
    GetChildrenBuilder getChildren();
130
    GetACLBuilder getACL();
131
    SetACLBuilder setACL();
132
    ReconfigBuilder reconfig();
133
    GetConfigBuilder getConfig();
134
    SyncBuilder sync();
135
    WatchesBuilder watchers();
136
    @Deprecated RemoveWatchesBuilder watches();
137
    CuratorMultiTransaction transaction();
138
    TransactionOp transactionOp();
139
    
140
    // Listener methods
141
    Listenable<ConnectionStateListener> getConnectionStateListenable();
142
    Listenable<CuratorListener> getCuratorListenable();
143
    Listenable<UnhandledErrorListener> getUnhandledErrorListenable();
144
    
145
    // Additional utility methods
146
    ZookeeperCompatibility getZookeeperCompatibility();
147
    QuorumVerifier getCurrentConfig();
148
    default CompletableFuture<Void> postSafeNotify(Object monitorHolder);
149
}
150
```
151

152
### Create Operations
153

154
Builder for creating ZooKeeper nodes with various options including create modes, ACLs, protection, and parent creation.
155

156
```java { .api }
157
/**
158
 * Start a create builder
159
 * @return builder object
160
 */
161
CreateBuilder create();
162

163
public interface CreateBuilder extends CreateBuilderMain, CreateBuilder2 {
164
    /**
165
     * Create builder with TTL support
166
     * @param ttl TTL in milliseconds for TTL nodes
167
     * @return builder
168
     */
169
    CreateBuilderMain withTtl(long ttl);
170
    
171
    /**
172
     * Use setData if node already exists
173
     * @return builder
174
     */
175
    CreateBuilder2 orSetData();
176
    
177
    /**
178
     * Use setData with version if node already exists
179
     * @param version version to use for setData
180
     * @return builder
181
     */
182
    CreateBuilder2 orSetData(int version);
183
}
184

185
public interface CreateBuilderMain {
186
    /**
187
     * Create parent nodes if needed
188
     * @return builder
189
     */
190
    ProtectACLCreateModeStatPathAndBytesable<String> creatingParentsIfNeeded();
191
    
192
    /**
193
     * Create parent containers if needed
194
     * @return builder
195
     */
196
    ProtectACLCreateModeStatPathAndBytesable<String> creatingParentContainersIfNeeded();
197
    
198
    /**
199
     * Use protected mode (creates node with GUID prefix)
200
     * @return builder
201
     */
202
    ACLCreateModeStatBackgroundPathAndBytesable<String> withProtection();
203
    
204
    /**
205
     * Use protected ephemeral sequential mode
206
     * @return builder
207
     * @deprecated Use withProtection().withMode(CreateMode.EPHEMERAL_SEQUENTIAL)
208
     */
209
    @Deprecated
210
    ACLPathAndBytesable<String> withProtectedEphemeralSequential();
211
}
212
```
213

214
**Usage Examples:**
215

216
```java
217
// Simple node creation
218
client.create().forPath("/my/path", "data".getBytes());
219

220
// Create with parents
221
client.create()
222
      .creatingParentsIfNeeded()
223
      .forPath("/my/deep/path", "data".getBytes());
224

225
// Create ephemeral sequential node
226
client.create()
227
      .withMode(CreateMode.EPHEMERAL_SEQUENTIAL)
228
      .forPath("/my/sequence", "data".getBytes());
229

230
// Create with protection and ACL
231
List<ACL> acls = Arrays.asList(new ACL(ZooDefs.Perms.ALL, ZooDefs.Ids.AUTH_IDS));
232
client.create()
233
      .withProtection()
234
      .withACL(acls)
235
      .withMode(CreateMode.PERSISTENT)
236
      .forPath("/protected/path", "data".getBytes());
237

238
// Create in background
239
client.create()
240
      .creatingParentsIfNeeded()
241
      .inBackground((curatorFramework, curatorEvent) -> {
242
          System.out.println("Created: " + curatorEvent.getPath());
243
      })
244
      .forPath("/async/path", "data".getBytes());
245
```
246

247
### Delete Operations
248

249
Builder for deleting ZooKeeper nodes with options for recursive deletion, version checking, and guaranteed execution.
250

251
```java { .api }
252
/**
253
 * Start a delete builder
254
 * @return builder object
255
 */
256
DeleteBuilder delete();
257

258
public interface DeleteBuilder extends DeleteBuilderMain, Backgroundable<ErrorListenerPathable<Void>> {
259
    // Inherits methods from DeleteBuilderMain and Backgroundable
260
}
261

262
public interface DeleteBuilderMain extends GuaranteeableDeletable, ChildrenDeletable {
263
    /**
264
     * Delete with specific version
265
     * @param version version to match
266
     * @return builder
267
     */
268
    Pathable<Void> withVersion(int version);
269
    
270
    /**
271
     * Guarantee deletion even if connection problems occur
272
     * @return builder
273
     */
274
    GuaranteeableDeletable guaranteed();
275
    
276
    /**
277
     * Delete children if needed (recursive delete)
278
     * @return builder
279
     */
280
    ChildrenDeletable deletingChildrenIfNeeded();
281
    
282
    /**
283
     * Quietly ignore NoNode errors
284
     * @return builder
285
     */
286
    Pathable<Void> quietly();
287
}
288
```
289

290
**Usage Examples:**
291

292
```java
293
// Simple deletion
294
client.delete().forPath("/my/path");
295

296
// Recursive deletion
297
client.delete()
298
      .deletingChildrenIfNeeded()
299
      .forPath("/my/path");
300

301
// Delete with version check
302
client.delete()
303
      .withVersion(2)
304
      .forPath("/versioned/path");
305

306
// Guaranteed deletion (survives connection issues)
307
client.delete()
308
      .guaranteed()
309
      .deletingChildrenIfNeeded()
310
      .forPath("/important/path");
311

312
// Delete in background
313
client.delete()
314
      .deletingChildrenIfNeeded()
315
      .inBackground()
316
      .forPath("/async/delete");
317
```
318

319
### Exists Operations
320

321
Builder for checking node existence with optional watcher registration and stat retrieval.
322

323
```java { .api }
324
/**
325
 * Start an exists builder
326
 * @return builder object
327
 */
328
ExistsBuilder checkExists();
329

330
public interface ExistsBuilder extends ExistsBuilderMain, ACLable<ExistsBuilderMain> {
331
    // Inherits methods from ExistsBuilderMain and ACLable
332
}
333

334
public interface ExistsBuilderMain extends 
335
    Watchable<BackgroundPathable<Stat>>, 
336
    BackgroundPathable<Stat>,
337
    ACLableExistBuilderMain {
338
    
339
    /**
340
     * Create parent containers if needed before checking
341
     * @return builder
342
     */
343
    ACLableExistBuilderMain creatingParentContainersIfNeeded();
344
}
345
```
346

347
**Usage Examples:**
348

349
```java
350
// Check if node exists
351
Stat stat = client.checkExists().forPath("/my/path");
352
if (stat != null) {
353
    System.out.println("Node exists with version: " + stat.getVersion());
354
}
355

356
// Check with watcher
357
Stat stat2 = client.checkExists()
358
                   .usingWatcher(watchedEvent -> {
359
                       System.out.println("Node changed: " + watchedEvent.getPath());
360
                   })
361
                   .forPath("/watched/path");
362

363
// Check in background
364
client.checkExists()
365
      .inBackground((curatorFramework, curatorEvent) -> {
366
          Stat stat = curatorEvent.getStat();
367
          if (stat != null) {
368
              System.out.println("Node exists: " + curatorEvent.getPath());
369
          }
370
      })
371
      .forPath("/async/check");
372
```
373

374
### Get Data Operations
375

376
Builder for retrieving data from ZooKeeper nodes with optional decompression, stat retrieval, and watcher registration.
377

378
```java { .api }
379
/**
380
 * Start a get data builder
381
 * @return builder object
382
 */
383
GetDataBuilder getData();
384

385
public interface GetDataBuilder extends 
386
    GetDataWatchBackgroundStatable, 
387
    Watchable<GetDataWatchBackgroundStatable>,
388
    Backgroundable<GetDataBackgroundStatable>,
389
    Decompressible<GetDataWatchBackgroundStatable> {
390
    
391
    /**
392
     * Get data with decompression
393
     * @return builder
394
     */
395
    GetDataWatchBackgroundStatable decompressed();
396
    
397
    /**
398
     * Store stat information in provided Stat object
399
     * @param stat Stat object to store information
400
     * @return builder
401
     */
402
    GetDataWatchBackgroundStatable storingStatIn(Stat stat);
403
}
404
```
405

406
**Usage Examples:**
407

408
```java
409
// Simple get data
410
byte[] data = client.getData().forPath("/my/path");
411
System.out.println("Data: " + new String(data));
412

413
// Get data with stat
414
Stat stat = new Stat();
415
byte[] data2 = client.getData()
416
                     .storingStatIn(stat)
417
                     .forPath("/my/path");
418

419
// Get data with watcher
420
byte[] data3 = client.getData()
421
                     .usingWatcher(watchedEvent -> {
422
                         System.out.println("Data changed: " + watchedEvent.getPath());
423
                     })
424
                     .forPath("/watched/path");
425

426
// Get compressed data
427
byte[] compressedData = client.getData()
428
                              .decompressed()
429
                              .forPath("/compressed/path");
430

431
// Get data in background
432
client.getData()
433
      .inBackground((curatorFramework, curatorEvent) -> {
434
          byte[] data = curatorEvent.getData();
435
          System.out.println("Got data: " + new String(data));
436
      })
437
      .forPath("/async/path");
438
```
439

440
### Set Data Operations
441

442
Builder for setting data on ZooKeeper nodes with optional compression, version checking, and stat retrieval.
443

444
```java { .api }
445
/**
446
 * Start a set data builder
447
 * @return builder object
448
 */
449
SetDataBuilder setData();
450

451
public interface SetDataBuilder extends 
452
    SetDataBackgroundVersionable, 
453
    Backgroundable<SetDataBackgroundVersionable>,
454
    Compressible<SetDataBackgroundVersionable> {
455
    
456
    /**
457
     * Set data with compression
458
     * @return builder
459
     */
460
    SetDataBackgroundVersionable compressed();
461
    
462
    /**
463
     * Set data with version check
464
     * @param version version to match
465
     * @return builder
466
     */
467
    SetDataBackgroundVersionable withVersion(int version);
468
}
469
```
470

471
**Usage Examples:**
472

473
```java
474
// Simple set data
475
client.setData().forPath("/my/path", "new data".getBytes());
476

477
// Set data with version check
478
client.setData()
479
      .withVersion(3)
480
      .forPath("/versioned/path", "updated data".getBytes());
481

482
// Set compressed data
483
client.setData()
484
      .compressed()
485
      .forPath("/compressed/path", largeData);
486

487
// Set data in background
488
client.setData()
489
      .inBackground((curatorFramework, curatorEvent) -> {
490
          System.out.println("Data set for: " + curatorEvent.getPath());
491
      })
492
      .forPath("/async/path", "async data".getBytes());
493
```
494

495
### Get Children Operations
496

497
Builder for retrieving child nodes with optional watcher registration and background execution.
498

499
```java { .api }
500
/**
501
 * Start a get children builder
502
 * @return builder object
503
 */
504
GetChildrenBuilder getChildren();
505

506
public interface GetChildrenBuilder extends 
507
    Watchable<BackgroundPathable<List<String>>>,
508
    BackgroundPathable<List<String>>,
509
    Statable<Watchable<BackgroundPathable<List<String>>>> {
510
    
511
    /**
512
     * Store stat information in provided Stat object
513
     * @param stat Stat object to store information
514
     * @return builder
515
     */
516
    Watchable<BackgroundPathable<List<String>>> storingStatIn(Stat stat);
517
}
518
```
519

520
**Usage Examples:**
521

522
```java
523
// Get children
524
List<String> children = client.getChildren().forPath("/my/path");
525
for (String child : children) {
526
    System.out.println("Child: " + child);
527
}
528

529
// Get children with watcher
530
List<String> children2 = client.getChildren()
531
                               .usingWatcher(watchedEvent -> {
532
                                   System.out.println("Children changed: " + watchedEvent.getPath());
533
                               })
534
                               .forPath("/watched/path");
535

536
// Get children with stat
537
Stat stat = new Stat();
538
List<String> children3 = client.getChildren()
539
                               .storingStatIn(stat)
540
                               .forPath("/my/path");
541

542
// Get children in background
543
client.getChildren()
544
      .inBackground((curatorFramework, curatorEvent) -> {
545
          List<String> children = curatorEvent.getChildren();
546
          System.out.println("Children count: " + children.size());
547
      })
548
      .forPath("/async/path");
549
```
550

551
### ACL Operations
552

553
Builders for getting and setting Access Control Lists on ZooKeeper nodes.
554

555
```java { .api }
556
/**
557
 * Start a get ACL builder
558
 * @return builder object
559
 */
560
GetACLBuilder getACL();
561

562
/**
563
 * Start a set ACL builder
564
 * @return builder object
565
 */
566
SetACLBuilder setACL();
567

568
public interface GetACLBuilder extends 
569
    BackgroundPathable<List<ACL>>, 
570
    Statable<Pathable<List<ACL>>> {
571
    
572
    /**
573
     * Store stat information in provided Stat object
574
     * @param stat Stat object to store information
575
     * @return builder
576
     */
577
    Pathable<List<ACL>> storingStatIn(Stat stat);
578
}
579

580
public interface SetACLBuilder extends 
581
    ACLVersionBackgroundPathable, 
582
    Backgroundable<ACLVersionPathable> {
583
    
584
    /**
585
     * Set ACL with version check
586
     * @param version version to match
587
     * @return builder
588
     */
589
    ACLPathable<Stat> withVersion(int version);
590
    
591
    /**
592
     * Specify the ACL list to set
593
     * @param aclList ACL list
594
     * @return builder
595
     */
596
    VersionPathAndBytesable<Stat> withACL(List<ACL> aclList);
597
}
598
```
599

600
**Usage Examples:**
601

602
```java
603
// Get ACL
604
List<ACL> acls = client.getACL().forPath("/my/path");
605
for (ACL acl : acls) {
606
    System.out.println("ACL: " + acl);
607
}
608

609
// Set ACL
610
List<ACL> newAcls = Arrays.asList(
611
    new ACL(ZooDefs.Perms.READ, ZooDefs.Ids.ANYONE_ID_UNSAFE),
612
    new ACL(ZooDefs.Perms.ALL, ZooDefs.Ids.AUTH_IDS)
613
);
614
client.setACL()
615
      .withACL(newAcls)
616
      .forPath("/my/path");
617

618
// Set ACL with version
619
client.setACL()
620
      .withVersion(2)
621
      .withACL(newAcls)
622
      .forPath("/versioned/path");
623
```
624

625
### Sync Operations
626

627
Builder for synchronizing with ZooKeeper to ensure client has latest data.
628

629
```java { .api }
630
/**
631
 * Start a sync builder
632
 * @return builder object
633
 */
634
SyncBuilder sync();
635

636
public interface SyncBuilder extends BackgroundPathable<Void> {
637
    // Sync is always performed in background
638
}
639
```
640

641
**Usage Examples:**
642

643
```java
644
// Sync operation
645
client.sync().forPath("/my/path");
646

647
// Sync with callback
648
client.sync()
649
      .inBackground((curatorFramework, curatorEvent) -> {
650
          System.out.println("Sync completed for: " + curatorEvent.getPath());
651
      })
652
      .forPath("/my/path");
653
```
654

655
### Configuration Operations (ZooKeeper 3.5+)
656

657
Builders for getting and reconfiguring ZooKeeper ensemble configuration.
658

659
```java { .api }
660
/**
661
 * Start a get config builder
662
 * @return builder object
663
 */
664
GetConfigBuilder getConfig();
665

666
/**
667
 * Start a reconfig builder
668
 * @return builder object
669
 */
670
ReconfigBuilder reconfig();
671

672
public interface GetConfigBuilder extends 
673
    WatchBackgroundEnsembleable<byte[]>,
674
    Watchable<WatchBackgroundEnsembleable<byte[]>>,
675
    Backgroundable<WatchBackgroundEnsembleable<byte[]>>,
676
    Statable<WatchBackgroundEnsembleable<byte[]>> {
677
    
678
    /**
679
     * Store stat information in provided Stat object
680
     * @param stat Stat object to store information
681
     * @return builder
682
     */
683
    WatchBackgroundEnsembleable<byte[]> storingStatIn(Stat stat);
684
}
685

686
public interface ReconfigBuilder extends ReconfigBuilderMain, Backgroundable<ErrorListenerReconfigBuilderMain> {
687
    // Reconfiguration operations for ensemble management
688
}
689
```
690

691
### Synchronization Operations
692

693
Builder for synchronizing with ZooKeeper server to ensure local view is up-to-date.
694

695
```java { .api }
696
/**
697
 * Start a sync builder. Note: sync is ALWAYS in the background even
698
 * if you don't use one of the background() methods
699
 * @return builder object
700
 */
701
SyncBuilder sync();
702

703
public interface SyncBuilder extends BackgroundPathable<Void> {
704
    // Synchronization operations are always background
705
}
706
```
707

708
### Advanced Watcher Management (ZooKeeper 3.6+)
709

710
Enhanced watcher builders for newer ZooKeeper versions supporting persistent watches.
711

712
```java { .api }
713
/**
714
 * Start a watch builder. Supported only when ZooKeeper JAR of version 3.6 or
715
 * above is used, throws IllegalStateException for ZooKeeper JAR 3.5 or below
716
 * @return builder object
717
 * @throws IllegalStateException ZooKeeper JAR is 3.5 or below
718
 */
719
WatchesBuilder watchers();
720

721
/**
722
 * Start a remove watches builder (deprecated - use watchers())
723
 * @return builder object
724
 * @deprecated use watchers() in ZooKeeper 3.6+
725
 */
726
@Deprecated
727
RemoveWatchesBuilder watches();
728

729
public interface WatchesBuilder extends RemoveWatchesBuilder {
730
    /**
731
     * Start an add watch operation
732
     * @return builder
733
     */
734
    AddWatchBuilder add();
735
}
736

737
public interface AddWatchBuilder extends AddWatchBuilder2 {
738
    /**
739
     * The mode to use. By default, AddWatchMode.PERSISTENT_RECURSIVE is used
740
     * @param mode mode to use
741
     * @return this
742
     */
743
    AddWatchBuilder2 withMode(AddWatchMode mode);
744
}
745
```
746

747