1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.cocoon.environment.http;
18
19 import org.apache.cocoon.environment.Cookie;
20
21 /**
22 *
23 * Creates a cookie, a small amount of information sent by a servlet to
24 * a Web browser, saved by the browser, and later sent back to the server.
25 * A cookie's value can uniquely
26 * identify a client, so cookies are commonly used for session management.
27 *
28 * <p>A cookie has a name, a single value, and optional attributes
29 * such as a comment, path and domain qualifiers, a maximum age, and a
30 * version number. Some Web browsers have bugs in how they handle the
31 * optional attributes, so use them sparingly to improve the interoperability
32 * of your servlets.
33 *
34 * <p>The servlet sends cookies to the browser by using the
35 * {@link HttpResponse#addCookie(Cookie)} method, which adds
36 * fields to HTTP response headers to send cookies to the
37 * browser, one at a time. The browser is expected to
38 * support 20 cookies for each Web server, 300 cookies total, and
39 * may limit cookie size to 4 KB each.
40 *
41 * <p>The browser returns cookies to the servlet by adding
42 * fields to HTTP request headers. Cookies can be retrieved
43 * from a request by using the {@link HttpRequest#getCookies()} method.
44 * Several cookies might have the same name but different path attributes.
45 *
46 * <p>Cookies affect the caching of the Web pages that use them.
47 * HTTP 1.0 does not cache pages that use cookies created with
48 * this class. This class does not support the cache control
49 * defined with HTTP 1.1.
50 *
51 * <p>This class supports both the Version 0 (by Netscape) and Version 1
52 * (by RFC 2109) cookie specifications. By default, cookies are
53 * created using Version 0 to ensure the best interoperability.
54 *
55 *
56 * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
57 * @version CVS $Id: HttpCookie.java 433543 2006-08-22 06:22:54Z crossley $
58 *
59 */
60
61 public final class HttpCookie
62 implements Cookie {
63
64 private javax.servlet.http.Cookie cookie;
65
66 public HttpCookie(String name, String value) {
67 this.cookie = new javax.servlet.http.Cookie(name, value);
68 }
69
70 public HttpCookie(javax.servlet.http.Cookie cookie) {
71 this.cookie = cookie;
72 }
73
74 public javax.servlet.http.Cookie getServletCookie() {
75 this.checkState();
76 return this.cookie;
77 }
78
79 /**
80 * Constructs a cookie with a specified name and value.
81 *
82 * <p>The name must conform to RFC 2109. That means it can contain
83 * only ASCII alphanumeric characters and cannot contain commas,
84 * semicolons, or white space or begin with a $ character. The cookie's
85 * name cannot be changed after creation.
86 *
87 * <p>The value can be anything the server chooses to send. Its
88 * value is probably of interest only to the server. The cookie's
89 * value can be changed after creation with the
90 * <code>setValue</code> method.
91 *
92 * <p>By default, cookies are created according to the Netscape
93 * cookie specification. The version can be changed with the
94 * <code>setVersion</code> method.
95 *
96 *
97 * @param name a <code>String</code> specifying the name of the cookie
98 *
99 * @param value a <code>String</code> specifying the value of the cookie
100 *
101 * @throws IllegalArgumentException if the cookie name contains illegal characters
102 * (for example, a comma, space, or semicolon)
103 * or it is one of the tokens reserved for use
104 * by the cookie protocol
105 * @see #setValue(String)
106 * @see #setVersion(int)
107 *
108 */
109
110 public void init(String name, String value) {
111 if (this.cookie == null) {
112 this.cookie = new javax.servlet.http.Cookie(name, value);
113 } else {
114 throw new IllegalStateException("Cookie is already initialised");
115 }
116 }
117
118
119 private void checkState() {
120 if (this.cookie == null) {
121 throw new IllegalStateException("Cookie is not initialised");
122 }
123 }
124
125 /**
126 *
127 * Specifies a comment that describes a cookie's purpose.
128 * The comment is useful if the browser presents the cookie
129 * to the user. Comments
130 * are not supported by Netscape Version 0 cookies.
131 *
132 * @param purpose a <code>String</code> specifying the comment
133 * to display to the user
134 *
135 * @see #getComment()
136 *
137 */
138
139 public void setComment(String purpose) {
140 this.checkState();
141 this.cookie.setComment(purpose);
142 }
143
144
145
146
147 /**
148 * Returns the comment describing the purpose of this cookie, or
149 * <code>null</code> if the cookie has no comment.
150 *
151 * @return a <code>String</code> containing the comment,
152 * or <code>null</code> if none
153 *
154 * @see #setComment(String)
155 *
156 */
157
158 public String getComment() {
159 this.checkState();
160 return this.cookie.getComment();
161 }
162
163
164
165
166 /**
167 *
168 * Specifies the domain within which this cookie should be presented.
169 *
170 * <p>The form of the domain name is specified by RFC 2109. A domain
171 * name begins with a dot (<code>.foo.com</code>) and means that
172 * the cookie is visible to servers in a specified Domain Name System
173 * (DNS) zone (for example, <code>www.foo.com</code>, but not
174 * <code>a.b.foo.com</code>). By default, cookies are only returned
175 * to the server that sent them.
176 *
177 *
178 * @param pattern a <code>String</code> containing the domain name
179 * within which this cookie is visible;
180 * form is according to RFC 2109
181 *
182 * @see #getDomain()
183 *
184 */
185
186 public void setDomain(String pattern) {
187 this.checkState();
188 this.cookie.setDomain(pattern);
189 }
190
191
192
193
194
195 /**
196 * Returns the domain name set for this cookie. The form of
197 * the domain name is set by RFC 2109.
198 *
199 * @return a <code>String</code> containing the domain name
200 *
201 * @see #setDomain(String)
202 *
203 */
204
205 public String getDomain() {
206 this.checkState();
207 return this.cookie.getDomain();
208 }
209
210
211
212
213 /**
214 * Sets the maximum age of the cookie in seconds.
215 *
216 * <p>A positive value indicates that the cookie will expire
217 * after that many seconds have passed. Note that the value is
218 * the <i>maximum</i> age when the cookie will expire, not the cookie's
219 * current age.
220 *
221 * <p>A negative value means
222 * that the cookie is not stored persistently and will be deleted
223 * when the Web browser exits. A zero value causes the cookie
224 * to be deleted.
225 *
226 * @param expiry an integer specifying the maximum age of the
227 * cookie in seconds; if negative, means
228 * the cookie is not stored; if zero, deletes
229 * the cookie
230 *
231 *
232 * @see #getMaxAge()
233 *
234 */
235
236 public void setMaxAge(int expiry) {
237 this.checkState();
238 this.cookie.setMaxAge(expiry);
239 }
240
241
242
243
244 /**
245 * Returns the maximum age of the cookie, specified in seconds,
246 * By default, <code>-1</code> indicating the cookie will persist
247 * until browser shutdown.
248 *
249 *
250 * @return an integer specifying the maximum age of the
251 * cookie in seconds; if negative, means
252 * the cookie persists until browser shutdown
253 *
254 *
255 * @see #setMaxAge(int)
256 *
257 */
258
259 public int getMaxAge() {
260 this.checkState();
261 return this.cookie.getMaxAge();
262 }
263
264
265
266
267 /**
268 * Specifies a path for the cookie
269 * to which the client should return the cookie.
270 *
271 * <p>The cookie is visible to all the pages in the directory
272 * you specify, and all the pages in that directory's subdirectories.
273 * A cookie's path must include the servlet that set the cookie,
274 * for example, <i>/catalog</i>, which makes the cookie
275 * visible to all directories on the server under <i>/catalog</i>.
276 *
277 * <p>Consult RFC 2109 (available on the Internet) for more
278 * information on setting path names for cookies.
279 *
280 *
281 * @param uri a <code>String</code> specifying a path
282 *
283 *
284 * @see #getPath()
285 *
286 */
287
288 public void setPath(String uri) {
289 this.checkState();
290 this.cookie.setPath(uri);
291 }
292
293
294
295
296 /**
297 * Returns the path on the server
298 * to which the browser returns this cookie. The
299 * cookie is visible to all subpaths on the server.
300 *
301 *
302 * @return a <code>String</code> specifying a path that contains
303 * a servlet name, for example, <i>/catalog</i>
304 *
305 * @see #setPath(String)
306 *
307 */
308
309 public String getPath() {
310 this.checkState();
311 return this.cookie.getPath();
312 }
313
314
315
316
317
318 /**
319 * Indicates to the browser whether the cookie should only be sent
320 * using a secure protocol, such as HTTPS or SSL.
321 *
322 * <p>The default value is <code>false</code>.
323 *
324 * @param flag if <code>true</code>, sends the cookie from the browser
325 * to the server using only when using a secure protocol;
326 * if <code>false</code>, sent on any protocol
327 *
328 * @see #getSecure()
329 *
330 */
331
332 public void setSecure(boolean flag) {
333 this.checkState();
334 this.cookie.setSecure(flag);
335 }
336
337
338
339
340 /**
341 * Returns <code>true</code> if the browser is sending cookies
342 * only over a secure protocol, or <code>false</code> if the
343 * browser can send cookies using any protocol.
344 *
345 * @return <code>true</code> if the browser can use
346 * any standard protocol; otherwise, <code>false</code>
347 *
348 * @see #setSecure(boolean)
349 *
350 */
351
352 public boolean getSecure() {
353 this.checkState();
354 return this.cookie.getSecure();
355 }
356
357
358
359
360
361 /**
362 * Returns the name of the cookie. The name cannot be changed after
363 * creation.
364 *
365 * @return a <code>String</code> specifying the cookie's name
366 *
367 */
368
369 public String getName() {
370 this.checkState();
371 return this.cookie.getName();
372 }
373
374
375
376
377
378 /**
379 *
380 * Assigns a new value to a cookie after the cookie is created.
381 * If you use a binary value, you may want to use BASE64 encoding.
382 *
383 * <p>With Version 0 cookies, values should not contain white
384 * space, brackets, parentheses, equals signs, commas,
385 * double quotes, slashes, question marks, at signs, colons,
386 * and semicolons. Empty values may not behave the same way
387 * on all browsers.
388 *
389 * @param newValue a <code>String</code> specifying the new value
390 *
391 *
392 * @see #getValue()
393 * @see Cookie
394 *
395 */
396
397 public void setValue(String newValue) {
398 this.checkState();
399 this.cookie.setValue(newValue);
400 }
401
402
403
404
405 /**
406 * Returns the value of the cookie.
407 *
408 * @return a <code>String</code> containing the cookie's
409 * present value
410 *
411 * @see #setValue(String)
412 * @see Cookie
413 *
414 */
415
416 public String getValue() {
417 this.checkState();
418 return this.cookie.getValue();
419 }
420
421
422
423
424 /**
425 * Returns the version of the protocol this cookie complies
426 * with. Version 1 complies with RFC 2109,
427 * and version 0 complies with the original
428 * cookie specification drafted by Netscape. Cookies provided
429 * by a browser use and identify the browser's cookie version.
430 *
431 *
432 * @return 0 if the cookie complies with the
433 * original Netscape specification; 1
434 * if the cookie complies with RFC 2109
435 *
436 * @see #setVersion(int)
437 *
438 */
439
440 public int getVersion() {
441 this.checkState();
442 return this.cookie.getVersion();
443 }
444
445
446
447
448 /**
449 * Sets the version of the cookie protocol this cookie complies
450 * with. Version 0 complies with the original Netscape cookie
451 * specification. Version 1 complies with RFC 2109.
452 *
453 * <p>Since RFC 2109 is still somewhat new, consider
454 * version 1 as experimental; do not use it yet on production sites.
455 *
456 *
457 * @param v 0 if the cookie should comply with
458 * the original Netscape specification;
459 * 1 if the cookie should comply with RFC 2109
460 *
461 * @see #getVersion()
462 *
463 */
464
465 public void setVersion(int v) {
466 this.checkState();
467 this.cookie.setVersion(v);
468 }
469
470
471
472 }
473
Save This Page