Client Connection Management

/**
 * Main ZooKeeper client wrapper providing connection management and retry functionality
 */
public class CuratorZookeeperClient implements Closeable {
    /**
     * Create client with connection string and retry policy
     * @param connectString ZooKeeper connection string (host:port)
     * @param sessionTimeoutMs Session timeout in milliseconds
     * @param connectionTimeoutMs Connection timeout in milliseconds  
     * @param watcher Optional watcher for connection events
     * @param retryPolicy Retry policy for failed operations
     */
    public CuratorZookeeperClient(String connectString, int sessionTimeoutMs, 
                                 int connectionTimeoutMs, Watcher watcher, 
                                 RetryPolicy retryPolicy);
    
    /**
     * Create client with ensemble provider for dynamic connection strings
     * @param ensembleProvider Provider for ZooKeeper connection strings
     * @param sessionTimeoutMs Session timeout in milliseconds
     * @param connectionTimeoutMs Connection timeout in milliseconds
     * @param watcher Optional watcher for connection events
     * @param retryPolicy Retry policy for failed operations
     */
    public CuratorZookeeperClient(EnsembleProvider ensembleProvider, int sessionTimeoutMs,
                                 int connectionTimeoutMs, Watcher watcher,
                                 RetryPolicy retryPolicy);
    
    /**
     * Create client with custom ZooKeeper factory and read-only support
     * @param zookeeperFactory Factory for creating ZooKeeper instances
     * @param ensembleProvider Provider for ZooKeeper connection strings
     * @param sessionTimeoutMs Session timeout in milliseconds
     * @param connectionTimeoutMs Connection timeout in milliseconds
     * @param watcher Optional watcher for connection events
     * @param retryPolicy Retry policy for failed operations
     * @param canBeReadOnly Whether client can connect in read-only mode
     */
    public CuratorZookeeperClient(ZookeeperFactory zookeeperFactory, EnsembleProvider ensembleProvider,
                                 int sessionTimeoutMs, int connectionTimeoutMs, Watcher watcher,
                                 RetryPolicy retryPolicy, boolean canBeReadOnly);
    
    /**
     * Create client with custom connection handling policy
     * @param zookeeperFactory Factory for creating ZooKeeper instances
     * @param ensembleProvider Provider for ZooKeeper connection strings
     * @param sessionTimeoutMs Session timeout in milliseconds
     * @param connectionTimeoutMs Connection timeout in milliseconds
     * @param watcher Optional watcher for connection events
     * @param retryPolicy Retry policy for failed operations
     * @param canBeReadOnly Whether client can connect in read-only mode
     * @param connectionHandlingPolicy Policy for connection handling behavior
     */
    public CuratorZookeeperClient(ZookeeperFactory zookeeperFactory, EnsembleProvider ensembleProvider,
                                 int sessionTimeoutMs, int connectionTimeoutMs, Watcher watcher,
                                 RetryPolicy retryPolicy, boolean canBeReadOnly,
                                 ConnectionHandlingPolicy connectionHandlingPolicy);
    
    /**
     * Create client with all configuration parameters
     * @param zookeeperFactory Factory for creating ZooKeeper instances
     * @param ensembleProvider Provider for ZooKeeper connection strings
     * @param sessionTimeoutMs Session timeout in milliseconds
     * @param connectionTimeoutMs Connection timeout in milliseconds
     * @param waitForShutdownTimeoutMs Timeout for shutdown operations
     * @param watcher Optional watcher for connection events
     * @param retryPolicy Retry policy for failed operations
     * @param canBeReadOnly Whether client can connect in read-only mode
     * @param connectionHandlingPolicy Policy for connection handling behavior
     */
    public CuratorZookeeperClient(ZookeeperFactory zookeeperFactory, EnsembleProvider ensembleProvider,
                                 int sessionTimeoutMs, int connectionTimeoutMs, int waitForShutdownTimeoutMs,
                                 Watcher watcher, RetryPolicy retryPolicy, boolean canBeReadOnly,
                                 ConnectionHandlingPolicy connectionHandlingPolicy);
    
    /**
     * Start the client connection to ZooKeeper
     * @throws Exception if connection cannot be established
     */
    public void start() throws Exception;
    
    /**
     * Close the client and release resources
     * @throws IOException if close operation fails
     */
    public void close() throws IOException;
    
    /**
     * Close the client with custom shutdown timeout
     * @param waitForShutdownTimeoutMs Timeout for shutdown operations in milliseconds
     */
    public void close(int waitForShutdownTimeoutMs);
    
    /**
     * Check if client is currently connected to ZooKeeper
     * @return true if connected, false otherwise
     */
    public boolean isConnected();
    
    /**
     * Block current thread until connected or timeout occurs
     * @return true if connected, false if timed out
     * @throws InterruptedException if interrupted while waiting
     */
    public boolean blockUntilConnectedOrTimedOut() throws InterruptedException;
    
    /**
     * Get the underlying ZooKeeper client instance
     * @return ZooKeeper client for direct operations
     * @throws Exception if client is not available
     */
    public ZooKeeper getZooKeeper() throws Exception;
    
    /**
     * Create a new retry loop for ZooKeeper operations
     * @return RetryLoop instance for operation retry handling
     */
    public RetryLoop newRetryLoop();
    
    /**
     * Create a session fail retry loop for session failure scenarios
     * @param mode Retry mode (RETRY or FAIL)
     * @return SessionFailRetryLoop instance
     */
    public SessionFailRetryLoop newSessionFailRetryLoop(SessionFailRetryLoop.Mode mode);
}

import org.apache.curator.CuratorZookeeperClient;
import org.apache.curator.RetryPolicy;
import org.apache.curator.retry.ExponentialBackoffRetry;

// Basic client setup
RetryPolicy retryPolicy = new ExponentialBackoffRetry(1000, 3);
CuratorZookeeperClient client = new CuratorZookeeperClient(
    "localhost:2181,localhost:2182,localhost:2183", 
    5000,  // session timeout
    5000,  // connection timeout
    null,  // watcher
    retryPolicy
);

// Start and use client
try {
    client.start();
    
    // Wait for connection
    if (client.blockUntilConnectedOrTimedOut()) {
        System.out.println("Connected to ZooKeeper");
        
        // Access ZooKeeper instance for operations
        ZooKeeper zk = client.getZooKeeper();
        // ... perform operations ...
    }
} finally {
    client.close();
}

/**
 * Abstract base class for retry loop implementations
 */
public abstract class RetryLoop {
    /**
     * Execute a callable with retry logic
     * @param client CuratorZookeeperClient instance
     * @param proc Callable to execute with retry
     * @return Result of successful callable execution
     * @throws Exception if all retries are exhausted
     */
    public static <T> T callWithRetry(CuratorZookeeperClient client, Callable<T> proc) throws Exception;
    
    /**
     * Check if ZooKeeper return code indicates retry should be attempted
     * @param rc ZooKeeper operation return code
     * @return true if operation should be retried
     */
    public static boolean shouldRetry(int rc);
    
    /**
     * Check if exception indicates operation should be retried
     * @param exception Exception from ZooKeeper operation
     * @return true if operation should be retried for this exception
     */
    public static boolean isRetryException(Throwable exception);
    
    /**
     * Get default retry sleeper implementation
     * @return Default RetrySleeper instance
     */
    public static RetrySleeper getDefaultRetrySleeper();
}

import org.apache.curator.RetryLoop;

// Using static retry method
String result = RetryLoop.callWithRetry(client, () -> {
    // ZooKeeper operation that may fail
    return client.getZooKeeper().getData("/some/path", false, null);
});

// Manual retry loop
RetryLoop retryLoop = client.newRetryLoop();
while (retryLoop.shouldContinue()) {
    try {
        // ZooKeeper operations
        client.getZooKeeper().create("/test", "data".getBytes(), ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT);
        retryLoop.markComplete();
    } catch (Exception e) {
        retryLoop.takeException(e);
    }
}

/**
 * Retry loop specialized for handling session failures
 */
public class SessionFailRetryLoop {
    /**
     * Mode enumeration for session failure handling
     */
    public enum Mode {
        /** Retry operations after session failure */
        RETRY,
        /** Fail immediately on session failure */
        FAIL
    }
    
    /**
     * Exception thrown when session failure occurs in FAIL mode
     */
    public static class SessionFailedException extends Exception {
        // Exception for session failure scenarios
    }
    
    /**
     * Execute callable with session failure retry logic
     * @param client CuratorZookeeperClient instance
     * @param mode Session failure handling mode
     * @param proc Callable to execute
     * @return Result of successful execution
     * @throws Exception if operation fails or session fails in FAIL mode
     */
    public static <T> T callWithRetry(CuratorZookeeperClient client, Mode mode, Callable<T> proc) throws Exception;
}

import org.apache.curator.SessionFailRetryLoop;

// Retry on session failure
String data = SessionFailRetryLoop.callWithRetry(client, SessionFailRetryLoop.Mode.RETRY, () -> {
    return new String(client.getZooKeeper().getData("/important/data", false, null));
});

// Fail immediately on session failure
try {
    SessionFailRetryLoop.callWithRetry(client, SessionFailRetryLoop.Mode.FAIL, () -> {
        client.getZooKeeper().setData("/critical/path", newData, -1);
        return null;
    });
} catch (SessionFailRetryLoop.SessionFailedException e) {
    // Handle session failure
    System.err.println("Session failed, cannot continue");
}

/**
 * Enumeration of possible ZooKeeper connection states
 */
public enum ConnectionState {
    /** Successfully connected to ZooKeeper */
    CONNECTED,
    /** Connection temporarily suspended */
    SUSPENDED,
    /** Reconnected after suspension */
    RECONNECTED,
    /** Connection permanently lost */
    LOST,
    /** Connected in read-only mode */
    READ_ONLY
}