tessl/maven-org-apache-curator--curator-framework

High-level API that greatly simplifies using ZooKeeper.

—

Pending

Overview

Eval results

Files

Core Framework Operations

Name: tessl/maven-org-apache-curator--curator-framework
Author: tessl

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

Imports

import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.api.*;
import org.apache.curator.framework.state.ConnectionStateListener;
import org.apache.curator.framework.listen.Listenable;
import org.apache.zookeeper.AddWatchMode;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

Capabilities

CuratorFramework Interface

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

/**
 * Zookeeper framework-style client
 */
public interface CuratorFramework extends Closeable {
    /**
     * Start the client. Most mutator methods will not work until the client is started
     */
    void start();
    
    /**
     * Stop the client
     */
    void close();
    
    /**
     * Returns the state of this instance
     * @return state
     */
    CuratorFrameworkState getState();
    
    /**
     * Return true if the client is started, not closed, etc.
     * @return true/false
     * @deprecated use getState() instead
     */
    @Deprecated
    boolean isStarted();
    
    /**
     * Block until a connection to ZooKeeper is available or the maxWaitTime has been exceeded
     * @param maxWaitTime The maximum wait time
     * @param units The time units for the maximum wait time
     * @return True if connection has been established, false otherwise
     * @throws InterruptedException If interrupted while waiting
     */
    boolean blockUntilConnected(int maxWaitTime, TimeUnit units) throws InterruptedException;
    
    /**
     * Block until a connection to ZooKeeper is available
     * @throws InterruptedException If interrupted while waiting
     */
    void blockUntilConnected() throws InterruptedException;
    
    /**
     * Create all nodes in the specified path as containers if they don't already exist
     * @param path path to create
     * @throws Exception errors
     */
    void createContainers(String path) throws Exception;
    
    /**
     * Returns a facade of the current instance that uses the specified namespace
     * @param newNamespace the new namespace or null for none
     * @return facade
     */
    CuratorFramework usingNamespace(String newNamespace);
    
    /**
     * Return the current namespace or "" if none
     * @return namespace
     */
    String getNamespace();
    
    /**
     * Return the managed zookeeper client
     * @return client
     */
    CuratorZookeeperClient getZookeeperClient();
    
    /**
     * Returns a facade that tracks watchers created and allows one-shot removal
     * @return facade
     */
    WatcherRemoveCuratorFramework newWatcherRemoveCuratorFramework();
    
    /**
     * Return the configured error policy
     * @return error policy
     */
    ConnectionStateErrorPolicy getConnectionStateErrorPolicy();
    
    /**
     * Return this instance's schema set
     * @return schema set
     */
    SchemaSet getSchemaSet();
    
    /**
     * Return whether compression is enabled by default
     * @return if compression is enabled
     */
    boolean compressionEnabled();
    
    /**
     * Run code safely from ZooKeeper's event thread
     * @param runnable proc to call from a safe internal thread
     * @return a CompletableFuture that can be used to monitor when the call is complete
     */
    CompletableFuture<Void> runSafe(Runnable runnable);
    
    // Builder methods for operations
    CreateBuilder create();
    DeleteBuilder delete();
    ExistsBuilder checkExists();
    GetDataBuilder getData();
    SetDataBuilder setData();
    GetChildrenBuilder getChildren();
    GetACLBuilder getACL();
    SetACLBuilder setACL();
    ReconfigBuilder reconfig();
    GetConfigBuilder getConfig();
    SyncBuilder sync();
    WatchesBuilder watchers();
    @Deprecated RemoveWatchesBuilder watches();
    CuratorMultiTransaction transaction();
    TransactionOp transactionOp();
    
    // Listener methods
    Listenable<ConnectionStateListener> getConnectionStateListenable();
    Listenable<CuratorListener> getCuratorListenable();
    Listenable<UnhandledErrorListener> getUnhandledErrorListenable();
    
    // Additional utility methods
    ZookeeperCompatibility getZookeeperCompatibility();
    QuorumVerifier getCurrentConfig();
    default CompletableFuture<Void> postSafeNotify(Object monitorHolder);
}

Create Operations

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

/**
 * Start a create builder
 * @return builder object
 */
CreateBuilder create();

public interface CreateBuilder extends CreateBuilderMain, CreateBuilder2 {
    /**
     * Create builder with TTL support
     * @param ttl TTL in milliseconds for TTL nodes
     * @return builder
     */
    CreateBuilderMain withTtl(long ttl);
    
    /**
     * Use setData if node already exists
     * @return builder
     */
    CreateBuilder2 orSetData();
    
    /**
     * Use setData with version if node already exists
     * @param version version to use for setData
     * @return builder
     */
    CreateBuilder2 orSetData(int version);
}

public interface CreateBuilderMain {
    /**
     * Create parent nodes if needed
     * @return builder
     */
    ProtectACLCreateModeStatPathAndBytesable<String> creatingParentsIfNeeded();
    
    /**
     * Create parent containers if needed
     * @return builder
     */
    ProtectACLCreateModeStatPathAndBytesable<String> creatingParentContainersIfNeeded();
    
    /**
     * Use protected mode (creates node with GUID prefix)
     * @return builder
     */
    ACLCreateModeStatBackgroundPathAndBytesable<String> withProtection();
    
    /**
     * Use protected ephemeral sequential mode
     * @return builder
     * @deprecated Use withProtection().withMode(CreateMode.EPHEMERAL_SEQUENTIAL)
     */
    @Deprecated
    ACLPathAndBytesable<String> withProtectedEphemeralSequential();
}

Usage Examples:

// Simple node creation
client.create().forPath("/my/path", "data".getBytes());

// Create with parents
client.create()
      .creatingParentsIfNeeded()
      .forPath("/my/deep/path", "data".getBytes());

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

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

// Create in background
client.create()
      .creatingParentsIfNeeded()
      .inBackground((curatorFramework, curatorEvent) -> {
          System.out.println("Created: " + curatorEvent.getPath());
      })
      .forPath("/async/path", "data".getBytes());

Delete Operations

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

/**
 * Start a delete builder
 * @return builder object
 */
DeleteBuilder delete();

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

public interface DeleteBuilderMain extends GuaranteeableDeletable, ChildrenDeletable {
    /**
     * Delete with specific version
     * @param version version to match
     * @return builder
     */
    Pathable<Void> withVersion(int version);
    
    /**
     * Guarantee deletion even if connection problems occur
     * @return builder
     */
    GuaranteeableDeletable guaranteed();
    
    /**
     * Delete children if needed (recursive delete)
     * @return builder
     */
    ChildrenDeletable deletingChildrenIfNeeded();
    
    /**
     * Quietly ignore NoNode errors
     * @return builder
     */
    Pathable<Void> quietly();
}

Usage Examples:

// Simple deletion
client.delete().forPath("/my/path");

// Recursive deletion
client.delete()
      .deletingChildrenIfNeeded()
      .forPath("/my/path");

// Delete with version check
client.delete()
      .withVersion(2)
      .forPath("/versioned/path");

// Guaranteed deletion (survives connection issues)
client.delete()
      .guaranteed()
      .deletingChildrenIfNeeded()
      .forPath("/important/path");

// Delete in background
client.delete()
      .deletingChildrenIfNeeded()
      .inBackground()
      .forPath("/async/delete");

Exists Operations

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

/**
 * Start an exists builder
 * @return builder object
 */
ExistsBuilder checkExists();

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

public interface ExistsBuilderMain extends 
    Watchable<BackgroundPathable<Stat>>, 
    BackgroundPathable<Stat>,
    ACLableExistBuilderMain {
    
    /**
     * Create parent containers if needed before checking
     * @return builder
     */
    ACLableExistBuilderMain creatingParentContainersIfNeeded();
}

Usage Examples:

// Check if node exists
Stat stat = client.checkExists().forPath("/my/path");
if (stat != null) {
    System.out.println("Node exists with version: " + stat.getVersion());
}

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

// Check in background
client.checkExists()
      .inBackground((curatorFramework, curatorEvent) -> {
          Stat stat = curatorEvent.getStat();
          if (stat != null) {
              System.out.println("Node exists: " + curatorEvent.getPath());
          }
      })
      .forPath("/async/check");

Get Data Operations

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

/**
 * Start a get data builder
 * @return builder object
 */
GetDataBuilder getData();

public interface GetDataBuilder extends 
    GetDataWatchBackgroundStatable, 
    Watchable<GetDataWatchBackgroundStatable>,
    Backgroundable<GetDataBackgroundStatable>,
    Decompressible<GetDataWatchBackgroundStatable> {
    
    /**
     * Get data with decompression
     * @return builder
     */
    GetDataWatchBackgroundStatable decompressed();
    
    /**
     * Store stat information in provided Stat object
     * @param stat Stat object to store information
     * @return builder
     */
    GetDataWatchBackgroundStatable storingStatIn(Stat stat);
}

Usage Examples:

// Simple get data
byte[] data = client.getData().forPath("/my/path");
System.out.println("Data: " + new String(data));

// Get data with stat
Stat stat = new Stat();
byte[] data2 = client.getData()
                     .storingStatIn(stat)
                     .forPath("/my/path");

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

// Get compressed data
byte[] compressedData = client.getData()
                              .decompressed()
                              .forPath("/compressed/path");

// Get data in background
client.getData()
      .inBackground((curatorFramework, curatorEvent) -> {
          byte[] data = curatorEvent.getData();
          System.out.println("Got data: " + new String(data));
      })
      .forPath("/async/path");

Set Data Operations

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

/**
 * Start a set data builder
 * @return builder object
 */
SetDataBuilder setData();

public interface SetDataBuilder extends 
    SetDataBackgroundVersionable, 
    Backgroundable<SetDataBackgroundVersionable>,
    Compressible<SetDataBackgroundVersionable> {
    
    /**
     * Set data with compression
     * @return builder
     */
    SetDataBackgroundVersionable compressed();
    
    /**
     * Set data with version check
     * @param version version to match
     * @return builder
     */
    SetDataBackgroundVersionable withVersion(int version);
}

Usage Examples:

// Simple set data
client.setData().forPath("/my/path", "new data".getBytes());

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

// Set compressed data
client.setData()
      .compressed()
      .forPath("/compressed/path", largeData);

// Set data in background
client.setData()
      .inBackground((curatorFramework, curatorEvent) -> {
          System.out.println("Data set for: " + curatorEvent.getPath());
      })
      .forPath("/async/path", "async data".getBytes());

Get Children Operations

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

/**
 * Start a get children builder
 * @return builder object
 */
GetChildrenBuilder getChildren();

public interface GetChildrenBuilder extends 
    Watchable<BackgroundPathable<List<String>>>,
    BackgroundPathable<List<String>>,
    Statable<Watchable<BackgroundPathable<List<String>>>> {
    
    /**
     * Store stat information in provided Stat object
     * @param stat Stat object to store information
     * @return builder
     */
    Watchable<BackgroundPathable<List<String>>> storingStatIn(Stat stat);
}

Usage Examples:

// Get children
List<String> children = client.getChildren().forPath("/my/path");
for (String child : children) {
    System.out.println("Child: " + child);
}

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

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

// Get children in background
client.getChildren()
      .inBackground((curatorFramework, curatorEvent) -> {
          List<String> children = curatorEvent.getChildren();
          System.out.println("Children count: " + children.size());
      })
      .forPath("/async/path");

ACL Operations

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

/**
 * Start a get ACL builder
 * @return builder object
 */
GetACLBuilder getACL();

/**
 * Start a set ACL builder
 * @return builder object
 */
SetACLBuilder setACL();

public interface GetACLBuilder extends 
    BackgroundPathable<List<ACL>>, 
    Statable<Pathable<List<ACL>>> {
    
    /**
     * Store stat information in provided Stat object
     * @param stat Stat object to store information
     * @return builder
     */
    Pathable<List<ACL>> storingStatIn(Stat stat);
}

public interface SetACLBuilder extends 
    ACLVersionBackgroundPathable, 
    Backgroundable<ACLVersionPathable> {
    
    /**
     * Set ACL with version check
     * @param version version to match
     * @return builder
     */
    ACLPathable<Stat> withVersion(int version);
    
    /**
     * Specify the ACL list to set
     * @param aclList ACL list
     * @return builder
     */
    VersionPathAndBytesable<Stat> withACL(List<ACL> aclList);
}

Usage Examples:

// Get ACL
List<ACL> acls = client.getACL().forPath("/my/path");
for (ACL acl : acls) {
    System.out.println("ACL: " + acl);
}

// Set ACL
List<ACL> newAcls = Arrays.asList(
    new ACL(ZooDefs.Perms.READ, ZooDefs.Ids.ANYONE_ID_UNSAFE),
    new ACL(ZooDefs.Perms.ALL, ZooDefs.Ids.AUTH_IDS)
);
client.setACL()
      .withACL(newAcls)
      .forPath("/my/path");

// Set ACL with version
client.setACL()
      .withVersion(2)
      .withACL(newAcls)
      .forPath("/versioned/path");

Sync Operations

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

/**
 * Start a sync builder
 * @return builder object
 */
SyncBuilder sync();

public interface SyncBuilder extends BackgroundPathable<Void> {
    // Sync is always performed in background
}

Usage Examples:

// Sync operation
client.sync().forPath("/my/path");

// Sync with callback
client.sync()
      .inBackground((curatorFramework, curatorEvent) -> {
          System.out.println("Sync completed for: " + curatorEvent.getPath());
      })
      .forPath("/my/path");

Configuration Operations (ZooKeeper 3.5+)

Builders for getting and reconfiguring ZooKeeper ensemble configuration.

/**
 * Start a get config builder
 * @return builder object
 */
GetConfigBuilder getConfig();

/**
 * Start a reconfig builder
 * @return builder object
 */
ReconfigBuilder reconfig();

public interface GetConfigBuilder extends 
    WatchBackgroundEnsembleable<byte[]>,
    Watchable<WatchBackgroundEnsembleable<byte[]>>,
    Backgroundable<WatchBackgroundEnsembleable<byte[]>>,
    Statable<WatchBackgroundEnsembleable<byte[]>> {
    
    /**
     * Store stat information in provided Stat object
     * @param stat Stat object to store information
     * @return builder
     */
    WatchBackgroundEnsembleable<byte[]> storingStatIn(Stat stat);
}

public interface ReconfigBuilder extends ReconfigBuilderMain, Backgroundable<ErrorListenerReconfigBuilderMain> {
    // Reconfiguration operations for ensemble management
}

Synchronization Operations

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

/**
 * Start a sync builder. Note: sync is ALWAYS in the background even
 * if you don't use one of the background() methods
 * @return builder object
 */
SyncBuilder sync();

public interface SyncBuilder extends BackgroundPathable<Void> {
    // Synchronization operations are always background
}

Advanced Watcher Management (ZooKeeper 3.6+)

Enhanced watcher builders for newer ZooKeeper versions supporting persistent watches.

/**
 * Start a watch builder. Supported only when ZooKeeper JAR of version 3.6 or
 * above is used, throws IllegalStateException for ZooKeeper JAR 3.5 or below
 * @return builder object
 * @throws IllegalStateException ZooKeeper JAR is 3.5 or below
 */
WatchesBuilder watchers();

/**
 * Start a remove watches builder (deprecated - use watchers())
 * @return builder object
 * @deprecated use watchers() in ZooKeeper 3.6+
 */
@Deprecated
RemoveWatchesBuilder watches();

public interface WatchesBuilder extends RemoveWatchesBuilder {
    /**
     * Start an add watch operation
     * @return builder
     */
    AddWatchBuilder add();
}

public interface AddWatchBuilder extends AddWatchBuilder2 {
    /**
     * The mode to use. By default, AddWatchMode.PERSISTENT_RECURSIVE is used
     * @param mode mode to use
     * @return this
     */
    AddWatchBuilder2 withMode(AddWatchMode mode);
}

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-curator--curator-framework

docs

tessl/maven-org-apache-curator--curator-framework

core-operations.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Core Framework Operations

Imports

Capabilities

CuratorFramework Interface

Create Operations

Delete Operations

Exists Operations

Get Data Operations

Set Data Operations

Get Children Operations

ACL Operations

Sync Operations

Configuration Operations (ZooKeeper 3.5+)

Synchronization Operations

Advanced Watcher Management (ZooKeeper 3.6+)

core-operations.mddocs/