0
# Apache Curator Client
1

2
Apache Curator Client is the foundational low-level API component of Apache Curator, providing essential ZooKeeper client functionality with robust connection management, retry policies, and utility classes. It serves as the stable foundation for distributed applications requiring reliable ZooKeeper coordination.
3

4
## Package Information
5

6
- **Package Name**: curator-client
7
- **Package Type**: maven
8
- **Group ID**: org.apache.curator
9
- **Language**: Java
10
- **Installation**: Add to Maven `pom.xml`:
11

12
```xml
13
<dependency>
14
    <groupId>org.apache.curator</groupId>
15
    <artifactId>curator-client</artifactId>
16
    <version>4.3.0</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
import org.apache.curator.CuratorZookeeperClient;
24
import org.apache.curator.RetryPolicy;
25
import org.apache.curator.retry.ExponentialBackoffRetry;
26
import org.apache.curator.ensemble.fixed.FixedEnsembleProvider;
27
import org.apache.curator.utils.ZKPaths;
28
import org.apache.curator.utils.PathUtils;
29
import org.apache.curator.utils.CloseableUtils;
30
import org.apache.curator.utils.ThreadUtils;
31
```
32

33
## Basic Usage
34

35
```java
36
import org.apache.curator.CuratorZookeeperClient;
37
import org.apache.curator.RetryPolicy;
38
import org.apache.curator.retry.ExponentialBackoffRetry;
39
import org.apache.curator.RetryLoop;
40

41
// Configure retry policy and create client
42
RetryPolicy retryPolicy = new ExponentialBackoffRetry(1000, 3);
43
CuratorZookeeperClient client = new CuratorZookeeperClient(
44
    "localhost:2181", 
45
    5000, 
46
    5000,
47
    null, 
48
    retryPolicy
49
);
50

51
try {
52
    // Start client connection
53
    client.start();
54
    client.blockUntilConnectedOrTimedOut();
55
    
56
    // Use retry loop for ZooKeeper operations
57
    RetryLoop retryLoop = client.newRetryLoop();
58
    while (retryLoop.shouldContinue()) {
59
        try {
60
            // Perform ZooKeeper operations with client.getZooKeeper()
61
            // ... your ZooKeeper operations here ...
62
            retryLoop.markComplete();
63
        } catch (Exception e) {
64
            retryLoop.takeException(e);
65
        }
66
    }
67
} finally {
68
    client.close();
69
}
70
```
71

72
## Architecture
73

74
Apache Curator Client is organized around several key architectural components:
75

76
- **Connection Management**: `CuratorZookeeperClient` provides robust connection handling with automatic reconnection
77
- **Retry Framework**: Comprehensive retry policies for handling transient failures in distributed environments  
78
- **Ensemble Providers**: Dynamic and static connection string management for ZooKeeper cluster discovery
79
- **Tracing System**: Pluggable metrics and tracing framework for monitoring ZooKeeper operations
80
- **Utility Classes**: Comprehensive path manipulation, resource management, and helper utilities
81

82
## Capabilities
83

84
### Client Connection Management
85

86
Core ZooKeeper client wrapper providing connection management, retry integration, and session handling for reliable distributed coordination.
87

88
```java { .api }
89
public class CuratorZookeeperClient implements Closeable {
90
    public CuratorZookeeperClient(String connectString, int sessionTimeoutMs, 
91
                                 int connectionTimeoutMs, Watcher watcher, 
92
                                 RetryPolicy retryPolicy);
93
    
94
    public void start() throws Exception;
95
    public void close() throws IOException;
96
    public boolean isConnected();
97
    public ZooKeeper getZooKeeper() throws Exception;
98
    public RetryLoop newRetryLoop();
99
}
100
```
101

102
[Client Connection Management](./client-connection.md)
103

104
### Retry Policies
105

106
Comprehensive retry policy implementations for handling transient failures and network issues in distributed ZooKeeper operations.
107

108
```java { .api }
109
public interface RetryPolicy {
110
    boolean allowRetry(int retryCount, long elapsedTimeMs, RetrySleeper sleeper);
111
}
112

113
public class ExponentialBackoffRetry implements RetryPolicy {
114
    public ExponentialBackoffRetry(int baseSleepTimeMs, int maxRetries);
115
    public ExponentialBackoffRetry(int baseSleepTimeMs, int maxRetries, int maxSleepMs);
116
}
117

118
public class RetryNTimes implements RetryPolicy {
119
    public RetryNTimes(int n, int sleepMsBetweenRetries);
120
}
121
```
122

123
[Retry Policies](./retry-policies.md)
124

125
### Ensemble Providers
126

127
Connection string providers for static and dynamic ZooKeeper cluster configuration, including integration with Netflix Exhibitor for service discovery.
128

129
```java { .api }
130
public interface EnsembleProvider extends Closeable {
131
    void start() throws Exception;
132
    String getConnectionString();
133
    void setConnectionString(String connectionString);
134
    boolean updateServerListEnabled();
135
}
136

137
public class FixedEnsembleProvider implements EnsembleProvider {
138
    public FixedEnsembleProvider(String connectionString);
139
}
140

141
public class ExhibitorEnsembleProvider implements EnsembleProvider {
142
    // Constructor and methods for dynamic ensemble discovery
143
}
144
```
145

146
[Ensemble Providers](./ensemble-providers.md)
147

148
### ZooKeeper Path Utilities
149

150
Comprehensive path manipulation utilities for ZooKeeper node operations, including path validation, tree operations, and node management.
151

152
```java { .api }
153
public class ZKPaths {
154
    public static final String PATH_SEPARATOR = "/";
155
    
156
    public static String makePath(String parent, String child);
157
    public static String getNodeFromPath(String path);
158
    public static PathAndNode getPathAndNode(String path);
159
    public static List<String> split(String path);
160
    public static void mkdirs(ZooKeeper zookeeper, String path) throws Exception;
161
    public static void deleteChildren(ZooKeeper zookeeper, String path, boolean deleteSelf) throws Exception;
162
}
163
```
164

165
[ZooKeeper Path Utilities](./path-utilities.md)
166

167
### Tracing and Metrics
168

169
Pluggable tracing framework for monitoring ZooKeeper operations, connection events, and performance metrics.
170

171
```java { .api }
172
public interface TracerDriver {
173
    void addTrace(String name, long time, TimeUnit unit);
174
    void addCount(String name, int increment);
175
}
176

177
public class TimeTrace {
178
    public TimeTrace(String name, TracerDriver driver);
179
    public void commit();
180
}
181
```
182

183
[Tracing and Metrics](./tracing-metrics.md)
184

185
### Connection Handling
186

187
Advanced connection handling policies and thread-local retry management for fine-grained control over ZooKeeper connection behavior.
188

189
```java { .api }
190
public interface ConnectionHandlingPolicy {
191
    CheckTimeoutsResult checkTimeouts() throws Exception;
192
    <T> T callWithRetry(CuratorZookeeperClient client, Callable<T> proc) throws Exception;
193
}
194

195
public class StandardConnectionHandlingPolicy implements ConnectionHandlingPolicy {
196
    // Standard connection handling implementation
197
}
198
```
199

200
[Connection Handling](./connection-handling.md)
201

202
## Types
203

204
### Core Exception Types
205

206
```java { .api }
207
public class CuratorConnectionLossException extends ConnectionLossException {
208
    // Specialized ConnectionLossException for Curator-specific timeouts
209
}
210
```
211

212
### Connection State Enumeration
213

214
```java { .api }
215
public enum ConnectionState {
216
    CONNECTED,
217
    SUSPENDED, 
218
    RECONNECTED,
219
    LOST,
220
    READ_ONLY
221
}
222
```
223

224
### Path Utilities Types
225

226
```java { .api }
227
public static class ZKPaths.PathAndNode {
228
    public String getPath();
229
    public String getNode();
230
}
231
```