KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > environment > http > HttpCookie


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