0
# Cookie Management
1

2
Apache HttpClient provides comprehensive HTTP cookie handling with storage, expiration management, and policy enforcement for session-based applications and web services integration.
3

4
## Cookie Interface
5

6
### Cookie
7

8
```java { .api }
9
public interface Cookie {
10
    String getName();
11
    String getValue();
12
    String getComment();
13
    String getCommentURL();
14
    Date getExpiryDate();
15
    boolean isPersistent();
16
    String getDomain();
17
    String getPath();
18
    int[] getPorts();
19
    boolean isSecure();
20
    int getVersion();
21
}
22
```
23

24
Basic interface representing an HTTP cookie with standard attributes.
25

26
### ClientCookie
27

28
```java { .api }
29
public interface ClientCookie extends Cookie {
30
    String COMMENT_ATTR = "comment";
31
    String COMMENTURL_ATTR = "commenturl";
32
    String DISCARD_ATTR = "discard";
33
    String DOMAIN_ATTR = "domain";
34
    String EXPIRES_ATTR = "expires";
35
    String MAX_AGE_ATTR = "max-age";
36
    String PATH_ATTR = "path";
37
    String PORT_ATTR = "port";
38
    String SECURE_ATTR = "secure";
39
    String VERSION_ATTR = "version";
40
    
41
    String getAttribute(String name);
42
    boolean containsAttribute(String name);
43
}
44
```
45

46
Extended cookie interface with client-specific attributes and methods.
47

48
### SetCookie
49

50
```java { .api }
51
public interface SetCookie extends Cookie {
52
    void setValue(String value);
53
    void setComment(String comment);
54
    void setExpiryDate(Date expiryDate);
55
    void setDomain(String domain);
56
    void setPath(String path);
57
    void setSecure(boolean secure);
58
    void setVersion(int version);
59
}
60
```
61

62
Interface for mutable cookies that can be modified.
63

64
### SetCookie2
65

66
```java { .api }
67
public interface SetCookie2 extends SetCookie {
68
    void setCommentURL(String commentURL);
69
    void setPorts(int[] ports);
70
    void setDiscard(boolean discard);
71
}
72
```
73

74
Extended SetCookie interface with additional RFC 2965 attributes.
75

76
## Cookie Store
77

78
### CookieStore Interface
79

80
```java { .api }
81
public interface CookieStore {
82
    void addCookie(Cookie cookie);
83
    List<Cookie> getCookies();
84
    boolean clearExpired(Date date);
85
    void clear();
86
}
87
```
88

89
Interface for storing and managing HTTP cookies.
90

91
### BasicCookieStore
92

93
```java { .api }
94
public class BasicCookieStore implements CookieStore {
95
    public BasicCookieStore();
96
    public synchronized void addCookie(Cookie cookie);
97
    public synchronized List<Cookie> getCookies();
98
    public synchronized boolean clearExpired(Date date);
99
    public synchronized void clear();
100
}
101
```
102

103
Basic thread-safe implementation of cookie store.
104

105
```java
106
CookieStore cookieStore = new BasicCookieStore();
107

108
// Add cookies manually
109
BasicClientCookie cookie = new BasicClientCookie("sessionId", "abc123");
110
cookie.setDomain("example.com");
111
cookie.setPath("/");
112
cookieStore.addCookie(cookie);
113

114
// Use with HTTP client
115
CloseableHttpClient httpClient = HttpClients.custom()
116
    .setDefaultCookieStore(cookieStore)
117
    .build();
118

119
// Cookies are automatically managed for subsequent requests
120
HttpGet httpGet = new HttpGet("https://example.com/api/data");
121
CloseableHttpResponse response = httpClient.execute(httpGet);
122
```
123

124
## Cookie Implementations
125

126
### BasicClientCookie
127

128
```java { .api }
129
public class BasicClientCookie implements SetCookie, ClientCookie {
130
    public BasicClientCookie(String name, String value);
131
    public String getName();
132
    public String getValue();
133
    public void setValue(String value);
134
    public String getComment();
135
    public void setComment(String comment);
136
    public String getCommentURL();
137
    public Date getExpiryDate();
138
    public void setExpiryDate(Date expiryDate);
139
    public boolean isPersistent();
140
    public String getDomain();
141
    public void setDomain(String domain);
142
    public String getPath();
143
    public void setPath(String path);
144
    public boolean isSecure();
145
    public void setSecure(boolean secure);
146
    public int getVersion();
147
    public void setVersion(int version);
148
    public void setAttribute(String name, String value);
149
    public String getAttribute(String name);
150
    public boolean containsAttribute(String name);
151
}
152
```
153

154
Basic implementation of a client-side cookie.
155

156
```java
157
BasicClientCookie cookie = new BasicClientCookie("username", "john");
158
cookie.setDomain("api.example.com");
159
cookie.setPath("/");
160
cookie.setExpiryDate(new Date(System.currentTimeMillis() + 3600000)); // 1 hour
161
cookie.setSecure(true);
162
```
163

164
### BasicClientCookie2
165

166
```java { .api }
167
public class BasicClientCookie2 extends BasicClientCookie implements SetCookie2 {
168
    public BasicClientCookie2(String name, String value);
169
    public int[] getPorts();
170
    public void setPorts(int[] ports);
171
    public String getCommentURL();
172
    public void setCommentURL(String commentURL);
173
    public void setDiscard(boolean discard);
174
}
175
```
176

177
RFC 2965 compliant cookie implementation with additional attributes.
178

179
## Cookie Specifications
180

181
### CookieSpec Interface
182

183
```java { .api }
184
public interface CookieSpec {
185
    int getVersion();
186
    List<Cookie> parse(Header header, CookieOrigin origin) throws MalformedCookieException;
187
    void validate(Cookie cookie, CookieOrigin origin) throws MalformedCookieException;
188
    boolean match(Cookie cookie, CookieOrigin origin);
189
    List<Header> formatCookies(List<Cookie> cookies);
190
    Header getVersionHeader();
191
}
192
```
193

194
Interface defining cookie specification behavior for parsing and formatting.
195

196
### CookieOrigin
197

198
```java { .api }
199
public final class CookieOrigin {
200
    public CookieOrigin(String host, int port, String path, boolean secure);
201
    public String getHost();
202
    public String getPath();
203
    public int getPort();
204
    public boolean isSecure();
205
}
206
```
207

208
Represents the origin context for cookie operations.
209

210
```java
211
CookieOrigin origin = new CookieOrigin("api.example.com", 443, "/", true);
212
```
213

214
### Cookie Specification Registry
215

216
```java { .api }
217
public final class CookieSpecRegistry {
218
    public CookieSpecRegistry();
219
    public void register(String name, CookieSpecFactory factory);
220
    public void unregister(String name);
221
    public CookieSpec getCookieSpec(String name, HttpParams params) throws IllegalStateException;
222
    public List<String> getSpecNames();
223
}
224
```
225

226
Registry for cookie specification factories.
227

228
### Cookie Specification Providers
229

230
```java { .api }
231
public interface CookieSpecProvider {
232
    CookieSpec create(HttpContext context);
233
}
234
```
235

236
Provider interface for creating cookie specifications.
237

238
```java
239
Registry<CookieSpecProvider> cookieSpecRegistry = RegistryBuilder.<CookieSpecProvider>create()
240
    .register(CookieSpecs.DEFAULT, new DefaultCookieSpecProvider())
241
    .register(CookieSpecs.STANDARD, new RFC6265CookieSpecProvider())
242
    .register(CookieSpecs.STANDARD_STRICT, new RFC6265CookieSpecProvider(
243
        RFC6265CookieSpecProvider.CompatibilityLevel.STRICT, null))
244
    .build();
245

246
CloseableHttpClient httpClient = HttpClients.custom()
247
    .setDefaultCookieSpecRegistry(cookieSpecRegistry)
248
    .build();
249
```
250

251
## Cookie Attribute Handlers
252

253
### CookieAttributeHandler
254

255
```java { .api }
256
public interface CookieAttributeHandler {
257
    void parse(SetCookie cookie, String value) throws MalformedCookieException;
258
    void validate(Cookie cookie, CookieOrigin origin) throws MalformedChallengeException;
259
    boolean match(Cookie cookie, CookieOrigin origin);
260
}
261
```
262

263
Interface for handling specific cookie attributes.
264

265
### CommonCookieAttributeHandler
266

267
```java { .api }
268
public interface CommonCookieAttributeHandler extends CookieAttributeHandler {
269
    String getAttributeName();
270
}
271
```
272

273
Extended interface for common cookie attribute handlers.
274

275
## Cookie Utilities
276

277
### Cookie Comparators
278

279
```java { .api }
280
public class CookieIdentityComparator implements Comparator<Cookie> {
281
    public int compare(Cookie c1, Cookie c2);
282
}
283

284
public class CookiePathComparator implements Comparator<Cookie> {
285
    public int compare(Cookie c1, Cookie c2);
286
}
287

288
public class CookiePriorityComparator implements Comparator<Cookie> {
289
    public int compare(Cookie c1, Cookie c2);
290
}
291
```
292

293
Comparators for sorting cookies by different criteria.
294

295
```java
296
List<Cookie> cookies = cookieStore.getCookies();
297
Collections.sort(cookies, new CookiePathComparator());
298
```
299

300
## Cookie Context Management
301

302
### HttpClientContext Cookie Methods
303

304
```java { .api }
305
public class HttpClientContext extends HttpCoreContext {
306
    public void setCookieStore(CookieStore cookieStore);
307
    public CookieStore getCookieStore();
308
    public void setCookieSpecRegistry(Lookup<CookieSpecProvider> cookieSpecRegistry);
309
    public Lookup<CookieSpecProvider> getCookieSpecRegistry();
310
    public void setCookieSpec(CookieSpec cookieSpec);
311
    public CookieSpec getCookieSpec();
312
}
313
```
314

315
Context methods for managing cookies in HTTP client operations.
316

317
```java
318
HttpClientContext context = HttpClientContext.create();
319
context.setCookieStore(cookieStore);
320

321
HttpGet httpGet = new HttpGet("https://api.example.com");
322
CloseableHttpResponse response = httpClient.execute(httpGet, context);
323

324
// Access cookies from the context
325
CookieStore contextCookieStore = context.getCookieStore();
326
List<Cookie> cookies = contextCookieStore.getCookies();
327
```
328

329
## Cookie Configuration
330

331
### Disabling Cookie Management
332

333
```java
334
CloseableHttpClient httpClient = HttpClients.custom()
335
    .disableCookieManagement()
336
    .build();
337
```
338

339
### Custom Cookie Store
340

341
```java
342
CookieStore customCookieStore = new BasicCookieStore();
343

344
CloseableHttpClient httpClient = HttpClients.custom()
345
    .setDefaultCookieStore(customCookieStore)
346
    .build();
347
```
348

349
### Request-Level Cookie Configuration
350

351
```java
352
RequestConfig config = RequestConfig.custom()
353
    .setCookieSpec(CookieSpecs.STANDARD)
354
    .build();
355

356
HttpGet httpGet = new HttpGet("https://api.example.com");
357
httpGet.setConfig(config);
358
```
359

360
## Types
361

362
### Cookie Specification Names
363

364
```java { .api }
365
public final class CookieSpecs {
366
    public static final String DEFAULT = "default";
367
    public static final String STANDARD = "standard";
368
    public static final String STANDARD_STRICT = "standard-strict";
369
    public static final String NETSCAPE = "netscape";
370
    public static final String IGNORE_COOKIES = "ignoreCookies";
371
}
372
```
373

374
Constants for standard cookie specification names.
375

376
### Exception Classes
377

378
```java { .api }
379
public class MalformedCookieException extends ProtocolException {
380
    public MalformedCookieException();
381
    public MalformedCookieException(String message);
382
    public MalformedCookieException(String message, Throwable cause);
383
}
384

385
public class CookieRestrictionViolationException extends MalformedCookieException {
386
    public CookieRestrictionViolationException(String message);
387
}
388
```
389

390
Exceptions thrown during cookie processing.