CtrlK
BlogDocsLog inGet started
Tessl Logo

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

High-level API that greatly simplifies using ZooKeeper.

—

Pending
Overview
Eval results
Files

transactions.mddocs/

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.

Capabilities

CuratorMultiTransaction

Main interface for creating and executing multi-operation transactions, providing atomic execution of multiple ZooKeeper operations.

/**
 * Start a transaction builder
 * @return builder object
 */
CuratorMultiTransaction transaction();

/**
 * Main interface for multi-operation transactions
 */
public interface CuratorMultiTransaction extends 
    Backgroundable<ErrorListenerMultiTransactionMain>, 
    CuratorMultiTransactionMain {
    
    /**
     * Execute transaction with provided operations
     * @param operations operations to execute atomically
     * @return builder for execution
     */
    CuratorMultiTransactionMain forOperations(CuratorOp... operations);
    
    /**
     * Execute transaction with provided operations
     * @param operations operations to execute atomically
     * @return builder for execution
     */
    CuratorMultiTransactionMain forOperations(Iterable<CuratorOp> operations);
}

public interface CuratorMultiTransactionMain extends 
    Backgroundable<Collection<CuratorTransactionResult>>, 
    ErrorListenerMultiTransactionMain {
    
    /**
     * Commit/execute the transaction
     * @return results of all operations
     * @throws Exception if transaction fails
     */
    Collection<CuratorTransactionResult> commit() throws Exception;
}

Usage Examples:

import org.apache.curator.framework.api.transaction.CuratorOp;
import org.apache.curator.framework.api.transaction.CuratorTransactionResult;

// Create multiple operations
CuratorOp createOp = client.transactionOp()
                          .create()
                          .forPath("/txn/node1", "data1".getBytes());

CuratorOp setDataOp = client.transactionOp()
                           .setData()
                           .forPath("/existing/node", "new data".getBytes());

CuratorOp deleteOp = client.transactionOp()
                          .delete()
                          .forPath("/old/node");

// Execute transaction atomically
Collection<CuratorTransactionResult> results = client.transaction()
                                                     .forOperations(createOp, setDataOp, deleteOp)
                                                     .commit();

// Process results
for (CuratorTransactionResult result : results) {
    System.out.println("Operation: " + result.getType() + 
                      " Path: " + result.getForPath() + 
                      " Result: " + result.getResultPath());
}

// Background transaction
client.transaction()
      .forOperations(createOp, setDataOp)
      .inBackground((curatorFramework, curatorEvent) -> {
          Collection<CuratorTransactionResult> results = curatorEvent.getOpResults();
          System.out.println("Transaction completed with " + results.size() + " operations");
      })
      .commit();

TransactionOp Factory

Factory interface for creating reusable transaction operations that can be combined into atomic transactions.

/**
 * Allocate an operation that can be used with transaction()
 * @return operation builder
 */
TransactionOp transactionOp();

/**
 * Factory for creating reusable transaction operations
 */
public interface TransactionOp {
    /**
     * Create a create operation
     * @return create operation builder
     */
    TransactionCreateBuilder<CuratorOp> create();
    
    /**
     * Create a delete operation
     * @return delete operation builder
     */
    TransactionDeleteBuilder<CuratorOp> delete();
    
    /**
     * Create a setData operation
     * @return setData operation builder
     */
    TransactionSetDataBuilder<CuratorOp> setData();
    
    /**
     * Create a check operation
     * @return check operation builder
     */
    TransactionCheckBuilder<CuratorOp> check();
}

Transaction Create Operations

Builder for create operations within transactions, supporting all create modes and options.

public interface TransactionCreateBuilder<T> extends TransactionCreateBuilder2<T> {
    /**
     * Create with specific mode
     * @param mode create mode
     * @return builder
     */
    PathAndBytesable<T> withMode(CreateMode mode);
    
    /**
     * Create with ACL
     * @param aclList ACL list
     * @return builder
     */
    ACLCreateModePathAndBytesable<T> withACL(List<ACL> aclList);
    
    /**
     * Create with TTL (for TTL nodes)
     * @param ttl TTL in milliseconds
     * @return builder
     */
    ACLCreateModePathAndBytesable<T> withTtl(long ttl);
}

public interface TransactionCreateBuilder2<T> extends 
    ACLCreateModePathAndBytesable<T>, 
    CreateModable<ACLPathAndBytesable<T>>,
    ACLable<CreateModePathAndBytesable<T>>,
    PathAndBytesable<T> {
    
    /**
     * Create parent nodes if needed
     * @return builder
     */
    ACLCreateModePathAndBytesable<T> creatingParentsIfNeeded();
}

Usage Examples:

// Create operation in transaction
CuratorOp createOp = client.transactionOp()
                          .create()
                          .withMode(CreateMode.PERSISTENT)
                          .forPath("/txn/new-node", "initial data".getBytes());

// Create with ACL
List<ACL> acls = Arrays.asList(new ACL(ZooDefs.Perms.ALL, ZooDefs.Ids.AUTH_IDS));
CuratorOp createWithAcl = client.transactionOp()
                                .create()
                                .withACL(acls)
                                .withMode(CreateMode.PERSISTENT)
                                .forPath("/secure/node", "secure data".getBytes());

// Create ephemeral sequential
CuratorOp createSequential = client.transactionOp()
                                   .create()
                                   .withMode(CreateMode.EPHEMERAL_SEQUENTIAL)
                                   .forPath("/sequence/node-", "sequence data".getBytes());

// Create with parent creation
CuratorOp createWithParents = client.transactionOp()
                                    .create()
                                    .creatingParentsIfNeeded()
                                    .forPath("/deep/nested/path", "nested data".getBytes());

Transaction Delete Operations

Builder for delete operations within transactions, supporting version checking and recursive deletion.

public interface TransactionDeleteBuilder<T> extends 
    Pathable<T>, 
    Versionable<Pathable<T>> {
    
    /**
     * Delete with version check
     * @param version version to match
     * @return builder
     */
    Pathable<T> withVersion(int version);
    
    /**
     * Delete children if needed (recursive delete)
     * @return builder
     */
    Pathable<T> deletingChildrenIfNeeded();
}

Usage Examples:

// Simple delete operation
CuratorOp deleteOp = client.transactionOp()
                          .delete()
                          .forPath("/to/delete");

// Delete with version check
CuratorOp deleteVersioned = client.transactionOp()
                                  .delete()
                                  .withVersion(3)
                                  .forPath("/versioned/node");

// Recursive delete
CuratorOp deleteRecursive = client.transactionOp()
                                  .delete()
                                  .deletingChildrenIfNeeded()
                                  .forPath("/parent/with/children");

Transaction SetData Operations

Builder for setData operations within transactions, supporting version checking and data modification.

public interface TransactionSetDataBuilder<T> extends 
    Pathable<T>, 
    Versionable<PathAndBytesable<T>> {
    
    /**
     * Set data with version check
     * @param version version to match
     * @return builder
     */
    PathAndBytesable<T> withVersion(int version);
    
    /**
     * Set data with compression
     * @return builder
     */
    Versionable<PathAndBytesable<T>> compressed();
}

Usage Examples:

// Simple setData operation
CuratorOp setDataOp = client.transactionOp()
                           .setData()
                           .forPath("/existing/node", "new data".getBytes());

// SetData with version check
CuratorOp setDataVersioned = client.transactionOp()
                                   .setData()
                                   .withVersion(2)
                                   .forPath("/versioned/node", "updated data".getBytes());

// SetData with compression
CuratorOp setDataCompressed = client.transactionOp()
                                    .setData()
                                    .compressed()
                                    .forPath("/large/node", largeDataBytes);

Transaction Check Operations

Builder for check operations within transactions, enabling conditional transaction execution based on node version or existence.

public interface TransactionCheckBuilder<T> extends 
    Pathable<T>, 
    Versionable<Pathable<T>> {
    
    /**
     * Check that node has specific version
     * @param version expected version
     * @return builder
     */
    Pathable<T> withVersion(int version);
}

Usage Examples:

// Check node version
CuratorOp checkOp = client.transactionOp()
                         .check()
                         .withVersion(5)
                         .forPath("/important/node");

// Use check to ensure preconditions
CuratorOp checkExists = client.transactionOp()
                             .check()
                             .forPath("/must/exist");

// Conditional transaction based on checks
Collection<CuratorTransactionResult> results = client.transaction()
    .forOperations(
        checkExists,  // Ensure node exists
        client.transactionOp().setData().forPath("/must/exist", "new data".getBytes()),
        client.transactionOp().create().forPath("/related/node", "related data".getBytes())
    )
    .commit();

CuratorOp Interface

Represents a single operation within a transaction, providing access to operation details.

/**
 * Represents a single transaction operation
 */
public interface CuratorOp {
    /**
     * Get the operation type
     * @return operation type
     */
    OperationType getType();
    
    /**
     * Get the path for this operation
     * @return path
     */
    String getPath();
    
    /**
     * Get the data for this operation (if applicable)
     * @return data bytes or null
     */
    byte[] getData();
}

Transaction Results

Classes for handling transaction execution results and accessing operation outcomes.

/**
 * Result of a transaction operation
 */
public class CuratorTransactionResult {
    /**
     * Get the operation type that was executed
     * @return operation type
     */
    public OperationType getType();
    
    /**
     * Get the path that was operated on
     * @return original path
     */
    public String getForPath();
    
    /**
     * Get the actual result path (important for sequential nodes)
     * @return result path
     */
    public String getResultPath();
    
    /**
     * Get the stat information for the operation result
     * @return stat or null
     */
    public Stat getResultStat();
    
    /**
     * Get the error code for this operation (0 = success)
     * @return ZooKeeper error code
     */
    public int getError();
}

/**
 * Types of transaction operations
 */
public enum OperationType {
    CREATE, DELETE, SET_DATA, CHECK
}

/**
 * Utility class combining operation type and path
 */
public class TypeAndPath {
    /**
     * Get the operation type
     * @return operation type
     */
    public OperationType getType();
    
    /**
     * Get the path
     * @return path
     */
    public String getPath();
}

Usage Examples:

// Process transaction results
Collection<CuratorTransactionResult> results = client.transaction()
    .forOperations(createOp, setDataOp, deleteOp)
    .commit();

for (CuratorTransactionResult result : results) {
    if (result.getError() == 0) {
        System.out.println("Success: " + result.getType() + " on " + result.getForPath());
        
        // For create operations, show actual path (important for sequential nodes)
        if (result.getType() == OperationType.CREATE) {
            System.out.println("Created at: " + result.getResultPath());
        }
        
        // Show stat information if available
        Stat stat = result.getResultStat();
        if (stat != null) {
            System.out.println("Version: " + stat.getVersion());
            System.out.println("Created: " + stat.getCtime());
        }
    } else {
        System.err.println("Failed: " + result.getType() + " on " + result.getForPath() + 
                          " Error: " + result.getError());
    }
}

Legacy Transaction Interface (Deprecated)

/**
 * Start a transaction builder (deprecated)
 * @return builder object
 * @deprecated use transaction() instead
 */
@Deprecated
CuratorTransaction inTransaction();

/**
 * Legacy transaction interface
 * @deprecated use CuratorMultiTransaction instead
 */
@Deprecated
public interface CuratorTransaction extends 
    CuratorTransactionBridge, 
    CuratorTransactionFinal {
    // Legacy transaction methods
}

Install with Tessl CLI

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

docs

client-factory.md

core-operations.md

events-state.md

index.md

schema-validation.md

transactions.md

watchers.md

tile.json