0
# Cookie Management
1

2
Cookie handling and session management providing automatic cookie processing, manual cookie manipulation, and session persistence for maintaining authentication and state across page navigations.
3

4
## Capabilities
5

6
### Cookie Manager Configuration
7

8
Configure cookie behavior and access the cookie management system.
9

10
```java { .api }
11
/**
12
 * Get the cookie manager for this client
13
 * @return CookieManager instance for this WebClient
14
 */
15
public CookieManager getCookieManager();
16

17
/**
18
 * Set a custom cookie manager
19
 * @param manager custom CookieManager implementation
20
 */
21
public void setCookieManager(CookieManager manager);
22
```
23

24
**Usage Examples:**
25

26
```java
27
WebClient webClient = new WebClient();
28
CookieManager cookieManager = webClient.getCookieManager();
29

30
// Enable/disable cookie processing
31
cookieManager.setCookiesEnabled(true);
32
```
33

34
### Cookie Manipulation
35

36
Add, remove, and query cookies programmatically.
37

38
```java { .api }
39
public class CookieManager {
40
    /**
41
     * Enable or disable automatic cookie handling
42
     * @param enabled true to process cookies automatically
43
     */
44
    public void setCookiesEnabled(boolean enabled);
45
    
46
    /**
47
     * Check if cookie processing is enabled
48
     * @return true if cookies are being processed
49
     */
50
    public boolean isCookiesEnabled();
51
    
52
    /**
53
     * Get all cookies currently stored
54
     * @return Set of Cookie objects
55
     */
56
    public Set<Cookie> getCookies();
57
    
58
    /**
59
     * Add a cookie to the cookie store
60
     * @param cookie Cookie object to add
61
     */
62
    public void addCookie(Cookie cookie);
63
    
64
    /**
65
     * Remove a specific cookie from the store
66
     * @param cookie Cookie object to remove
67
     */
68
    public void removeCookie(Cookie cookie);
69
    
70
    /**
71
     * Clear all expired cookies from the store
72
     * @param date current date for expiration check
73
     */
74
    public void clearExpired(Date date);
75
    
76
    /**
77
     * Remove all cookies from the store
78
     */
79
    public void clearCookies();
80
    
81
    /**
82
     * Get cookies for a specific domain
83
     * @param domain the domain to filter by
84
     * @return Set of cookies for the specified domain
85
     */
86
    public Set<Cookie> getCookies(String domain);
87
}
88
```
89

90
**Usage Examples:**
91

92
```java
93
CookieManager cookieManager = webClient.getCookieManager();
94

95
// Add a session cookie
96
Cookie sessionCookie = new Cookie("example.com", "sessionId", "abc123");
97
cookieManager.addCookie(sessionCookie);
98

99
// Add an authentication cookie with path and expiration
100
Date expiry = new Date(System.currentTimeMillis() + 86400000); // 24 hours
101
Cookie authCookie = new Cookie("example.com", "authToken", "xyz789");
102
authCookie.setPath("/api");
103
authCookie.setExpires(expiry);
104
authCookie.setSecure(true);
105
cookieManager.addCookie(authCookie);
106

107
// Get all cookies
108
Set<Cookie> allCookies = cookieManager.getCookies();
109
for (Cookie cookie : allCookies) {
110
    System.out.println(cookie.getName() + " = " + cookie.getValue());
111
}
112

113
// Get cookies for specific domain
114
Set<Cookie> domainCookies = cookieManager.getCookies("example.com");
115

116
// Clear expired cookies
117
cookieManager.clearExpired(new Date());
118

119
// Remove all cookies
120
cookieManager.clearCookies();
121
```
122

123
### Cookie Object
124

125
Individual cookie properties and manipulation.
126

127
```java { .api }
128
public class Cookie {
129
    /**
130
     * Create a basic cookie
131
     * @param domain the domain this cookie belongs to
132
     * @param name the cookie name
133
     * @param value the cookie value
134
     */
135
    public Cookie(String domain, String name, String value);
136
    
137
    /**
138
     * Create a cookie with path specification
139
     * @param domain the domain this cookie belongs to
140
     * @param name the cookie name
141
     * @param value the cookie value
142
     * @param path the cookie path
143
     * @param expires expiration date, null for session cookie
144
     * @param secure whether cookie requires HTTPS
145
     */
146
    public Cookie(String domain, String name, String value, String path, Date expires, boolean secure);
147
    
148
    /**
149
     * Get the cookie name
150
     * @return the cookie name
151
     */
152
    public String getName();
153
    
154
    /**
155
     * Get the cookie value
156
     * @return the cookie value
157
     */
158
    public String getValue();
159
    
160
    /**
161
     * Set the cookie value
162
     * @param value the new cookie value
163
     */
164
    public void setValue(String value);
165
    
166
    /**
167
     * Get the cookie domain
168
     * @return the domain this cookie applies to
169
     */
170
    public String getDomain();
171
    
172
    /**
173
     * Set the cookie domain
174
     * @param domain the domain this cookie applies to
175
     */
176
    public void setDomain(String domain);
177
    
178
    /**
179
     * Get the cookie path
180
     * @return the path this cookie applies to
181
     */
182
    public String getPath();
183
    
184
    /**
185
     * Set the cookie path
186
     * @param path the path this cookie applies to
187
     */
188
    public void setPath(String path);
189
    
190
    /**
191
     * Get the cookie expiration date
192
     * @return expiration date, or null for session cookies
193
     */
194
    public Date getExpires();
195
    
196
    /**
197
     * Set the cookie expiration date
198
     * @param expires expiration date, null for session cookie
199
     */
200
    public void setExpires(Date expires);
201
    
202
    /**
203
     * Check if cookie requires HTTPS
204
     * @return true if cookie is secure
205
     */
206
    public boolean isSecure();
207
    
208
    /**
209
     * Set whether cookie requires HTTPS
210
     * @param secure true to require HTTPS
211
     */
212
    public void setSecure(boolean secure);
213
    
214
    /**
215
     * Check if cookie is HTTP-only (not accessible from JavaScript)
216
     * @return true if cookie is HTTP-only
217
     */
218
    public boolean isHttpOnly();
219
    
220
    /**
221
     * Set whether cookie is HTTP-only
222
     * @param httpOnly true to make cookie HTTP-only
223
     */
224
    public void setHttpOnly(boolean httpOnly);
225
    
226
    /**
227
     * Check if cookie has expired
228
     * @return true if cookie has expired
229
     */
230
    public boolean isExpired();
231
    
232
    /**
233
     * Check if cookie has expired relative to a specific date
234
     * @param date the reference date for expiration check
235
     * @return true if cookie has expired
236
     */
237
    public boolean isExpired(Date date);
238
}
239
```
240

241
**Usage Examples:**
242

243
```java
244
// Create basic session cookie
245
Cookie sessionCookie = new Cookie("example.com", "sessionId", "abc123");
246

247
// Create secure authentication cookie
248
Cookie authCookie = new Cookie("api.example.com", "token", "secure_token_value");
249
authCookie.setPath("/api");
250
authCookie.setSecure(true);
251
authCookie.setHttpOnly(true);
252

253
// Set expiration for 1 hour from now
254
Date expiry = new Date(System.currentTimeMillis() + 3600000);
255
authCookie.setExpires(expiry);
256

257
// Cookie properties
258
String name = authCookie.getName();         // "token"
259
String value = authCookie.getValue();       // "secure_token_value"
260
String domain = authCookie.getDomain();     // "api.example.com"
261
String path = authCookie.getPath();         // "/api"
262
boolean secure = authCookie.isSecure();     // true
263
boolean httpOnly = authCookie.isHttpOnly(); // true
264
boolean expired = authCookie.isExpired();   // false (assuming current time)
265

266
// Modify cookie
267
authCookie.setValue("new_token_value");
268
authCookie.setPath("/");
269
```
270

271
### Session Management
272

273
Common patterns for managing user sessions and authentication cookies.
274

275
**Usage Examples:**
276

277
```java
278
WebClient webClient = new WebClient();
279
CookieManager cookieManager = webClient.getCookieManager();
280

281
// Automated login with session management
282
HtmlPage loginPage = webClient.getPage("https://example.com/login");
283
HtmlForm loginForm = loginPage.getFormByName("loginForm");
284
loginForm.getInputByName("username").setValue("myuser");
285
loginForm.getInputByName("password").setValue("mypass");
286

287
// Submit login form - cookies are automatically captured
288
HtmlPage welcomePage = loginForm.submit();
289

290
// Check that session cookies were set
291
Set<Cookie> cookies = cookieManager.getCookies("example.com");
292
boolean hasSessionCookie = cookies.stream()
293
    .anyMatch(cookie -> "sessionId".equals(cookie.getName()));
294

295
if (hasSessionCookie) {
296
    System.out.println("Successfully logged in with session");
297
    
298
    // Navigate to protected pages - session cookies are automatically sent
299
    HtmlPage profilePage = webClient.getPage("https://example.com/profile");
300
    HtmlPage settingsPage = webClient.getPage("https://example.com/settings");
301
}
302

303
// Manually add authentication cookie for API access
304
Cookie apiToken = new Cookie("api.example.com", "X-Auth-Token", "bearer_token_123");
305
apiToken.setPath("/api/v1");
306
apiToken.setSecure(true);
307
cookieManager.addCookie(apiToken);
308

309
// API requests will automatically include the cookie
310
WebRequest apiRequest = new WebRequest(new URL("https://api.example.com/api/v1/data"));
311
Page apiResponse = webClient.getPage(apiRequest);
312
```
313

314
### Cookie Persistence
315

316
Handle cookie storage and restoration across WebClient sessions.
317

318
**Usage Examples:**
319

320
```java
321
// Save cookies to restore in future sessions
322
WebClient webClient = new WebClient();
323
// ... perform operations that set cookies ...
324

325
Set<Cookie> savedCookies = webClient.getCookieManager().getCookies();
326

327
// Later: restore cookies in new WebClient session  
328
WebClient newWebClient = new WebClient();
329
CookieManager newCookieManager = newWebClient.getCookieManager();
330

331
for (Cookie cookie : savedCookies) {
332
    if (!cookie.isExpired()) {
333
        newCookieManager.addCookie(cookie);
334
    }
335
}
336

337
// The new client now has access to the previous session's cookies
338
```