or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-factory.mdcore-operations.mdevents-state.mdindex.mdschema-validation.mdtransactions.mdwatchers.md
tile.json

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

High-level API that greatly simplifies using ZooKeeper.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.apache.curator/curator-framework@5.9.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-curator--curator-framework@5.9.0

index.mddocs/

Apache Curator Framework

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.

Package Information

  • Package Name: curator-framework
  • Package Type: maven
  • Group ID: org.apache.curator
  • Artifact ID: curator-framework
  • Language: Java
  • Installation: 
    <dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-framework</artifactId>
    <version>5.9.0</version>
</dependency>

Core Imports

import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.CuratorFrameworkFactory;
import org.apache.curator.RetryPolicy;
import org.apache.curator.retry.ExponentialBackoffRetry;

Basic Usage

import org.apache.curator.framework.CuratorFramework;
import org.apache.curator.framework.CuratorFrameworkFactory;
import org.apache.curator.retry.ExponentialBackoffRetry;
import org.apache.curator.framework.state.ConnectionState;
import org.apache.curator.framework.state.ConnectionStateListener;

public class BasicCuratorExample {
    public static void main(String[] args) throws Exception {
        // Create retry policy
        RetryPolicy retryPolicy = new ExponentialBackoffRetry(1000, 3);
        
        // Create and start the client
        CuratorFramework client = CuratorFrameworkFactory.newClient(
            "localhost:2181", 
            retryPolicy
        );
        client.start();
        
        // Wait for connection
        client.blockUntilConnected();
        
        // Basic operations
        // Create a node
        client.create()
               .creatingParentsIfNeeded()
               .forPath("/my/path", "some data".getBytes());
        
        // Get data from a node
        byte[] data = client.getData().forPath("/my/path");
        System.out.println("Data: " + new String(data));
        
        // Set data on a node
        client.setData().forPath("/my/path", "updated data".getBytes());
        
        // Delete a node
        client.delete()
               .deletingChildrenIfNeeded()
               .forPath("/my/path");
        
        // Close the client
        client.close();
    }
}

Architecture

Apache Curator Framework is built around several key architectural patterns:

  • Builder Pattern: Fluent, type-safe API construction through extensive builder interfaces
  • Factory Pattern: Centralized client configuration via CuratorFrameworkFactory
  • Listener Pattern: Event-driven programming with connection state and curator event listeners
  • Facade Pattern: Simplified interface over complex ZooKeeper operations with automatic path management
  • Command Pattern: Background operations with callbacks and error handling
  • Namespace Pattern: Automatic path prefixing for multi-tenant applications

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.

Capabilities

Client Factory and Configuration

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

public static CuratorFramework newClient(String connectString, RetryPolicy retryPolicy);
public static CuratorFramework newClient(String connectString, int sessionTimeoutMs, int connectionTimeoutMs, RetryPolicy retryPolicy);
public static CuratorFrameworkFactory.Builder builder();

public static class Builder {
    public CuratorFramework build();
    public CuratorTempFramework buildTemp();
    public Builder connectString(String connectString);
    public Builder sessionTimeoutMs(int sessionTimeoutMs);
    public Builder connectionTimeoutMs(int connectionTimeoutMs);
    public Builder retryPolicy(RetryPolicy retryPolicy);
    public Builder namespace(String namespace);
    public Builder authorization(String scheme, byte[] auth);
    public Builder compressionProvider(CompressionProvider compressionProvider);
    public Builder enableCompression();
    public Builder aclProvider(ACLProvider aclProvider);
    public Builder canBeReadOnly(boolean canBeReadOnly);
    public Builder schemaSet(SchemaSet schemaSet);
}

Client Factory and Configuration

Core Framework Operations

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

public interface CuratorFramework extends Closeable {
    void start();
    void close();
    CuratorFrameworkState getState();
    
    CreateBuilder create();
    DeleteBuilder delete();
    ExistsBuilder checkExists();
    GetDataBuilder getData();
    SetDataBuilder setData();
    GetChildrenBuilder getChildren();
    GetACLBuilder getACL();
    SetACLBuilder setACL();
    ReconfigBuilder reconfig();
    GetConfigBuilder getConfig();
    
    CuratorFramework usingNamespace(String newNamespace);
    String getNamespace();
    boolean blockUntilConnected(int maxWaitTime, TimeUnit units);
    void createContainers(String path) throws Exception;
}

Core Framework Operations

Transaction Support

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.

public interface CuratorMultiTransaction {
    CuratorMultiTransactionMain forOperations(CuratorOp... operations);
    CuratorMultiTransactionMain forOperations(Iterable<CuratorOp> operations);
}

public interface TransactionOp {
    TransactionCreateBuilder<CuratorOp> create();
    TransactionDeleteBuilder<CuratorOp> delete();
    TransactionSetDataBuilder<CuratorOp> setData();
    TransactionCheckBuilder<CuratorOp> check();
}

public class CuratorTransactionResult {
    public OperationType getType();
    public String getForPath();
    public String getResultPath();
    public Stat getResultStat();
    public int getError();
}

Transaction Support

Event and State Management

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.

public interface CuratorEvent {
    CuratorEventType getType();
    int getResultCode();
    String getPath();
    Object getContext();
    Stat getStat();
    byte[] getData();
    String getName();
    List<String> getChildren();
    List<ACL> getACLList();
    WatchedEvent getWatchedEvent();
}

public enum ConnectionState {
    CONNECTED, SUSPENDED, RECONNECTED, LOST, READ_ONLY;
    boolean isConnected();
}

public interface ConnectionStateListener {
    void stateChanged(CuratorFramework client, ConnectionState newState);
}

public interface CuratorListener {
    void eventReceived(CuratorFramework client, CuratorEvent event);
}

Event and State Management

Watcher Management

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.

public interface CuratorWatcher {
    void process(WatchedEvent event) throws Exception;
}

public interface WatchesBuilder extends RemoveWatchesBuilder {
    // ZooKeeper 3.6+ persistent watch support
}

public interface RemoveWatchesBuilder {
    RemoveWatchesLocal ofType(RemoveWatchesType type);
    BackgroundPathable<Void> usingWatcher(Watcher watcher);
    BackgroundPathable<Void> usingWatcher(CuratorWatcher watcher);
}

public interface WatcherRemoveCuratorFramework extends CuratorFramework {
    void removeWatchers();
}

Watcher Management

Schema Validation

Optional schema validation system for enforcing data structure and path constraints on ZooKeeper nodes, providing data integrity and consistency guarantees in distributed applications.

public class SchemaSet {
    public static SchemaSet getDefaultSchemaSet();
    public Schema getSchema(String path);
    public Schema getNamedSchema(String name);
    public Collection<Schema> getSchemas();
    public String toDocumentation();
}

public class Schema {
    public String getName();
    public String getPath();
    public Pattern getPathRegex();
    public SchemaValidator getSchemaValidator();
    public String toDocumentation();
}

public interface SchemaValidator {
    boolean isValid(String path, byte[] data, Stat stat);
}

public class SchemaBuilder {
    public SchemaBuilder name(String name);
    public SchemaBuilder path(String path);
    public SchemaBuilder pathRegex(String pathRegex);
    public SchemaBuilder dataValidator(SchemaValidator validator);
    public Schema build();
}

Schema Validation

Types

Core Types

public class AuthInfo {
    public AuthInfo(String scheme, byte[] auth);
    public String getScheme();
    public byte[] getAuth();
}

public enum CuratorFrameworkState {
    LATENT, STARTED, STOPPED
}

public enum CuratorEventType {
    CREATE, DELETE, EXISTS, GET_DATA, SET_DATA, CHILDREN,
    SYNC, GET_ACL, SET_ACL, TRANSACTION, GET_CONFIG, RECONFIG,
    WATCHED, REMOVE_WATCHES, ADD_WATCH, CLOSING
}

public enum OperationType {
    CREATE, DELETE, SET_DATA, CHECK
}

public enum RemoveWatchesType {
    Any, Data, Child
}

Exception Types

public class CuratorClosedException extends IllegalStateException {
    // Thrown when operations attempted on closed client
}

public class SchemaViolation extends IllegalArgumentException {
    // Thrown when schema validation fails
}

Provider Interfaces

public interface ACLProvider {
    List<ACL> getDefaultAcl();
    List<ACL> getAclForPath(String path);
}

public interface CompressionProvider {
    byte[] compress(String path, byte[] data) throws Exception;
    byte[] decompress(String path, byte[] compressedData) throws Exception;
}