0
# Retry Policies
1

2
Comprehensive retry policy implementations for handling transient failures and network issues in distributed ZooKeeper operations. All retry policies implement the `RetryPolicy` interface and provide different strategies for timing and limiting retry attempts.
3

4
## Capabilities
5

6
### RetryPolicy Interface
7

8
Core interface that defines the contract for retry behavior in Apache Curator operations.
9

10
```java { .api }
11
/**
12
 * Interface for retry policies that determine when operations should be retried
13
 */
14
public interface RetryPolicy {
15
    /**
16
     * Determine if an operation should be retried
17
     * @param retryCount Number of retries already attempted (0-based)
18
     * @param elapsedTimeMs Total elapsed time since first attempt
19
     * @param sleeper Sleeper for implementing retry delays
20
     * @return true if retry should be attempted, false to give up
21
     */
22
    boolean allowRetry(int retryCount, long elapsedTimeMs, RetrySleeper sleeper);
23
}
24
```
25

26
### RetrySleeper Interface
27

28
Abstraction for sleeping during retry operations, allowing for custom sleep implementations and testing.
29

30
```java { .api }
31
/**
32
 * Interface for sleeping during retry operations
33
 */
34
public interface RetrySleeper {
35
    /**
36
     * Sleep for the specified duration
37
     * @param time Duration to sleep
38
     * @param unit Time unit for the duration
39
     * @throws InterruptedException if sleep is interrupted
40
     */
41
    void sleepFor(long time, TimeUnit unit) throws InterruptedException;
42
}
43
```
44

45
### Exponential Backoff Retry
46

47
Implements exponential backoff with jitter for retry delays, ideal for distributed systems to avoid thundering herd problems.
48

49
```java { .api }
50
/**
51
 * Retry policy with exponential backoff and jitter
52
 */
53
public class ExponentialBackoffRetry implements RetryPolicy {
54
    /**
55
     * Create exponential backoff retry with unlimited max sleep time
56
     * @param baseSleepTimeMs Base sleep time in milliseconds
57
     * @param maxRetries Maximum number of retry attempts
58
     */
59
    public ExponentialBackoffRetry(int baseSleepTimeMs, int maxRetries);
60
    
61
    /**
62
     * Create exponential backoff retry with bounded sleep time
63
     * @param baseSleepTimeMs Base sleep time in milliseconds
64
     * @param maxRetries Maximum number of retry attempts
65
     * @param maxSleepMs Maximum sleep time between retries
66
     */
67
    public ExponentialBackoffRetry(int baseSleepTimeMs, int maxRetries, int maxSleepMs);
68
}
69
```
70

71
**Usage Examples:**
72

73
```java
74
import org.apache.curator.retry.ExponentialBackoffRetry;
75
import org.apache.curator.CuratorZookeeperClient;
76

77
// Basic exponential backoff: 1s base, 3 retries, unbounded max sleep
78
RetryPolicy basicRetry = new ExponentialBackoffRetry(1000, 3);
79

80
// Bounded exponential backoff: 500ms base, 5 retries, max 10s sleep
81
RetryPolicy boundedRetry = new ExponentialBackoffRetry(500, 5, 10000);
82

83
// Use with client
84
CuratorZookeeperClient client = new CuratorZookeeperClient(
85
    "localhost:2181", 5000, 5000, null, basicRetry);
86
```
87

88
### Bounded Exponential Backoff Retry
89

90
Extension of exponential backoff retry with explicit bounds on sleep time to prevent extremely long delays.
91

92
```java { .api }
93
/**
94
 * Exponential backoff retry with explicit bounds on sleep time
95
 */
96
public class BoundedExponentialBackoffRetry extends ExponentialBackoffRetry {
97
    /**
98
     * Create bounded exponential backoff retry
99
     * @param baseSleepTimeMs Base sleep time in milliseconds
100
     * @param maxSleepTimeMs Maximum sleep time between retries
101
     * @param maxRetries Maximum number of retry attempts
102
     */
103
    public BoundedExponentialBackoffRetry(int baseSleepTimeMs, int maxSleepTimeMs, int maxRetries);
104
}
105
```
106

107
### Fixed Count Retry
108

109
Retry policy that attempts a fixed number of retries with constant sleep intervals.
110

111
```java { .api }
112
/**
113
 * Retry policy with fixed number of attempts and constant sleep time
114
 */
115
public class RetryNTimes implements RetryPolicy {
116
    /**
117
     * Create fixed count retry policy
118
     * @param n Number of retry attempts (after initial failure)
119
     * @param sleepMsBetweenRetries Sleep time in milliseconds between retries
120
     */
121
    public RetryNTimes(int n, int sleepMsBetweenRetries);
122
}
123
```
124

125
**Usage Examples:**
126

127
```java
128
import org.apache.curator.retry.RetryNTimes;
129

130
// Retry 3 times with 2 second intervals
131
RetryPolicy fixedRetry = new RetryNTimes(3, 2000);
132

133
// Retry 5 times with 500ms intervals  
134
RetryPolicy quickRetry = new RetryNTimes(5, 500);
135
```
136

137
### Single Retry
138

139
Simple retry policy that attempts exactly one retry with a fixed delay.
140

141
```java { .api }
142
/**
143
 * Retry policy that attempts exactly one retry
144
 */
145
public class RetryOneTime implements RetryPolicy {
146
    /**
147
     * Create single retry policy
148
     * @param sleepMsBetweenRetry Sleep time in milliseconds before retry
149
     */
150
    public RetryOneTime(int sleepMsBetweenRetry);
151
}
152
```
153

154
**Usage Examples:**
155

156
```java
157
import org.apache.curator.retry.RetryOneTime;
158

159
// Single retry after 1 second
160
RetryPolicy singleRetry = new RetryOneTime(1000);
161
```
162

163
### Indefinite Retry
164

165
Retry policy that continues retrying indefinitely until interrupted, useful for critical operations that must eventually succeed.
166

167
```java { .api }
168
/**
169
 * Retry policy that retries indefinitely until interrupted
170
 */
171
public class RetryForever implements RetryPolicy {
172
    /**
173
     * Create indefinite retry policy
174
     * @param retryIntervalMs Interval in milliseconds between retry attempts
175
     */
176
    public RetryForever(int retryIntervalMs);
177
}
178
```
179

180
**Usage Examples:**
181

182
```java
183
import org.apache.curator.retry.RetryForever;
184

185
// Retry forever with 5 second intervals
186
RetryPolicy persistentRetry = new RetryForever(5000);
187

188
// Use with critical operations that must succeed
189
CuratorZookeeperClient criticalClient = new CuratorZookeeperClient(
190
    "localhost:2181", 30000, 15000, null, persistentRetry);
191
```
192

193
### Time-Bounded Retry
194

195
Retry policy that continues retrying until a total elapsed time threshold is reached.
196

197
```java { .api }
198
/**
199
 * Retry policy that retries until total elapsed time threshold is reached
200
 */
201
public class RetryUntilElapsed implements RetryPolicy {
202
    /**
203
     * Create time-bounded retry policy
204
     * @param maxElapsedTimeMs Maximum total elapsed time for all retries
205
     * @param sleepMsBetweenRetries Sleep time in milliseconds between retries
206
     */
207
    public RetryUntilElapsed(int maxElapsedTimeMs, int sleepMsBetweenRetries);
208
}
209
```
210

211
**Usage Examples:**
212

213
```java
214
import org.apache.curator.retry.RetryUntilElapsed;
215

216
// Retry for up to 30 seconds with 2 second intervals
217
RetryPolicy timeBoundedRetry = new RetryUntilElapsed(30000, 2000);
218

219
// Use for operations with hard time limits
220
CuratorZookeeperClient timedClient = new CuratorZookeeperClient(
221
    "localhost:2181", 5000, 5000, null, timeBoundedRetry);
222
```
223

224
### Base Sleeping Retry Class
225

226
Abstract base class for retry policies that implement sleep-based retry behavior.
227

228
```java { .api }
229
/**
230
 * Abstract base class for retry policies that sleep between attempts
231
 */
232
public abstract class SleepingRetry implements RetryPolicy {
233
    // Base functionality for sleep-based retry policies
234
    // Concrete implementations provide specific sleep calculation logic
235
}
236
```
237

238
## Retry Policy Selection Guide
239

240
### ExponentialBackoffRetry
241
**Best for**: Most distributed system scenarios where you want to back off progressively
242
**Use when**: Network issues are common and you want to reduce load during outages
243

244
### RetryNTimes  
245
**Best for**: Operations with known failure patterns or when you need predictable retry behavior
246
**Use when**: You have specific SLA requirements or testing scenarios
247

248
### RetryOneTime
249
**Best for**: Quick operations where multiple retries are not cost-effective
250
**Use when**: Failures are rare and operations are lightweight
251

252
### RetryForever
253
**Best for**: Critical operations that must eventually succeed
254
**Use when**: System availability is more important than operation latency
255

256
### RetryUntilElapsed
257
**Best for**: Operations with hard time constraints or SLA requirements
258
**Use when**: You need to guarantee operation completion within a specific time window