001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.environment.http;
018:
019: import org.apache.cocoon.environment.Cookie;
020:
021: /**
022: *
023: * Creates a cookie, a small amount of information sent by a servlet to
024: * a Web browser, saved by the browser, and later sent back to the server.
025: * A cookie's value can uniquely
026: * identify a client, so cookies are commonly used for session management.
027: *
028: * <p>A cookie has a name, a single value, and optional attributes
029: * such as a comment, path and domain qualifiers, a maximum age, and a
030: * version number. Some Web browsers have bugs in how they handle the
031: * optional attributes, so use them sparingly to improve the interoperability
032: * of your servlets.
033: *
034: * <p>The servlet sends cookies to the browser by using the
035: * {@link HttpResponse#addCookie(Cookie)} method, which adds
036: * fields to HTTP response headers to send cookies to the
037: * browser, one at a time. The browser is expected to
038: * support 20 cookies for each Web server, 300 cookies total, and
039: * may limit cookie size to 4 KB each.
040: *
041: * <p>The browser returns cookies to the servlet by adding
042: * fields to HTTP request headers. Cookies can be retrieved
043: * from a request by using the {@link HttpRequest#getCookies()} method.
044: * Several cookies might have the same name but different path attributes.
045: *
046: * <p>Cookies affect the caching of the Web pages that use them.
047: * HTTP 1.0 does not cache pages that use cookies created with
048: * this class. This class does not support the cache control
049: * defined with HTTP 1.1.
050: *
051: * <p>This class supports both the Version 0 (by Netscape) and Version 1
052: * (by RFC 2109) cookie specifications. By default, cookies are
053: * created using Version 0 to ensure the best interoperability.
054: *
055: *
056: * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
057: * @version CVS $Id: HttpCookie.java 433543 2006-08-22 06:22:54Z crossley $
058: *
059: */
060:
061: public final class HttpCookie implements Cookie {
062:
063: private javax.servlet.http.Cookie cookie;
064:
065: public HttpCookie(String name, String value) {
066: this .cookie = new javax.servlet.http.Cookie(name, value);
067: }
068:
069: public HttpCookie(javax.servlet.http.Cookie cookie) {
070: this .cookie = cookie;
071: }
072:
073: public javax.servlet.http.Cookie getServletCookie() {
074: this .checkState();
075: return this .cookie;
076: }
077:
078: /**
079: * Constructs a cookie with a specified name and value.
080: *
081: * <p>The name must conform to RFC 2109. That means it can contain
082: * only ASCII alphanumeric characters and cannot contain commas,
083: * semicolons, or white space or begin with a $ character. The cookie's
084: * name cannot be changed after creation.
085: *
086: * <p>The value can be anything the server chooses to send. Its
087: * value is probably of interest only to the server. The cookie's
088: * value can be changed after creation with the
089: * <code>setValue</code> method.
090: *
091: * <p>By default, cookies are created according to the Netscape
092: * cookie specification. The version can be changed with the
093: * <code>setVersion</code> method.
094: *
095: *
096: * @param name a <code>String</code> specifying the name of the cookie
097: *
098: * @param value a <code>String</code> specifying the value of the cookie
099: *
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 name, String value) {
110: if (this .cookie == null) {
111: this .cookie = new javax.servlet.http.Cookie(name, value);
112: } else {
113: throw new IllegalStateException(
114: "Cookie is already initialised");
115: }
116: }
117:
118: private void checkState() {
119: if (this .cookie == null) {
120: throw new IllegalStateException("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 purpose) {
139: this .checkState();
140: this .cookie.setComment(purpose);
141: }
142:
143: /**
144: * Returns the comment describing the purpose of this cookie, or
145: * <code>null</code> if the cookie has no comment.
146: *
147: * @return a <code>String</code> containing the comment,
148: * or <code>null</code> if none
149: *
150: * @see #setComment(String)
151: *
152: */
153:
154: public String getComment() {
155: this .checkState();
156: return this .cookie.getComment();
157: }
158:
159: /**
160: *
161: * Specifies the domain within which this cookie should be presented.
162: *
163: * <p>The form of the domain name is specified by RFC 2109. A domain
164: * name begins with a dot (<code>.foo.com</code>) and means that
165: * the cookie is visible to servers in a specified Domain Name System
166: * (DNS) zone (for example, <code>www.foo.com</code>, but not
167: * <code>a.b.foo.com</code>). By default, cookies are only returned
168: * to the server that sent them.
169: *
170: *
171: * @param pattern a <code>String</code> containing the domain name
172: * within which this cookie is visible;
173: * form is according to RFC 2109
174: *
175: * @see #getDomain()
176: *
177: */
178:
179: public void setDomain(String pattern) {
180: this .checkState();
181: this .cookie.setDomain(pattern);
182: }
183:
184: /**
185: * Returns the domain name set for this cookie. The form of
186: * the domain name is set by RFC 2109.
187: *
188: * @return a <code>String</code> containing the domain name
189: *
190: * @see #setDomain(String)
191: *
192: */
193:
194: public String getDomain() {
195: this .checkState();
196: return this .cookie.getDomain();
197: }
198:
199: /**
200: * Sets the maximum age of the cookie in seconds.
201: *
202: * <p>A positive value indicates that the cookie will expire
203: * after that many seconds have passed. Note that the value is
204: * the <i>maximum</i> age when the cookie will expire, not the cookie's
205: * current age.
206: *
207: * <p>A negative value means
208: * that the cookie is not stored persistently and will be deleted
209: * when the Web browser exits. A zero value causes the cookie
210: * to be deleted.
211: *
212: * @param expiry an integer specifying the maximum age of the
213: * cookie in seconds; if negative, means
214: * the cookie is not stored; if zero, deletes
215: * the cookie
216: *
217: *
218: * @see #getMaxAge()
219: *
220: */
221:
222: public void setMaxAge(int expiry) {
223: this .checkState();
224: this .cookie.setMaxAge(expiry);
225: }
226:
227: /**
228: * Returns the maximum age of the cookie, specified in seconds,
229: * By default, <code>-1</code> indicating the cookie will persist
230: * until browser shutdown.
231: *
232: *
233: * @return an integer specifying the maximum age of the
234: * cookie in seconds; if negative, means
235: * the cookie persists until browser shutdown
236: *
237: *
238: * @see #setMaxAge(int)
239: *
240: */
241:
242: public int getMaxAge() {
243: this .checkState();
244: return this .cookie.getMaxAge();
245: }
246:
247: /**
248: * Specifies a path for the cookie
249: * to which the client should return the cookie.
250: *
251: * <p>The cookie is visible to all the pages in the directory
252: * you specify, and all the pages in that directory's subdirectories.
253: * A cookie's path must include the servlet that set the cookie,
254: * for example, <i>/catalog</i>, which makes the cookie
255: * visible to all directories on the server under <i>/catalog</i>.
256: *
257: * <p>Consult RFC 2109 (available on the Internet) for more
258: * information on setting path names for cookies.
259: *
260: *
261: * @param uri a <code>String</code> specifying a path
262: *
263: *
264: * @see #getPath()
265: *
266: */
267:
268: public void setPath(String uri) {
269: this .checkState();
270: this .cookie.setPath(uri);
271: }
272:
273: /**
274: * Returns the path on the server
275: * to which the browser returns this cookie. The
276: * cookie is visible to all subpaths on the server.
277: *
278: *
279: * @return a <code>String</code> specifying a path that contains
280: * a servlet name, for example, <i>/catalog</i>
281: *
282: * @see #setPath(String)
283: *
284: */
285:
286: public String getPath() {
287: this .checkState();
288: return this .cookie.getPath();
289: }
290:
291: /**
292: * Indicates to the browser whether the cookie should only be sent
293: * using a secure protocol, such as HTTPS or SSL.
294: *
295: * <p>The default value is <code>false</code>.
296: *
297: * @param flag if <code>true</code>, sends the cookie from the browser
298: * to the server using only when using a secure protocol;
299: * if <code>false</code>, sent on any protocol
300: *
301: * @see #getSecure()
302: *
303: */
304:
305: public void setSecure(boolean flag) {
306: this .checkState();
307: this .cookie.setSecure(flag);
308: }
309:
310: /**
311: * Returns <code>true</code> if the browser is sending cookies
312: * only over a secure protocol, or <code>false</code> if the
313: * browser can send cookies using any protocol.
314: *
315: * @return <code>true</code> if the browser can use
316: * any standard protocol; otherwise, <code>false</code>
317: *
318: * @see #setSecure(boolean)
319: *
320: */
321:
322: public boolean getSecure() {
323: this .checkState();
324: return this .cookie.getSecure();
325: }
326:
327: /**
328: * Returns the name of the cookie. The name cannot be changed after
329: * creation.
330: *
331: * @return a <code>String</code> specifying the cookie's name
332: *
333: */
334:
335: public String getName() {
336: this .checkState();
337: return this .cookie.getName();
338: }
339:
340: /**
341: *
342: * Assigns a new value to a cookie after the cookie is created.
343: * If you use a binary value, you may want to use BASE64 encoding.
344: *
345: * <p>With Version 0 cookies, values should not contain white
346: * space, brackets, parentheses, equals signs, commas,
347: * double quotes, slashes, question marks, at signs, colons,
348: * and semicolons. Empty values may not behave the same way
349: * on all browsers.
350: *
351: * @param newValue a <code>String</code> specifying the new value
352: *
353: *
354: * @see #getValue()
355: * @see Cookie
356: *
357: */
358:
359: public void setValue(String newValue) {
360: this .checkState();
361: this .cookie.setValue(newValue);
362: }
363:
364: /**
365: * Returns the value of the cookie.
366: *
367: * @return a <code>String</code> containing the cookie's
368: * present value
369: *
370: * @see #setValue(String)
371: * @see Cookie
372: *
373: */
374:
375: public String getValue() {
376: this .checkState();
377: return this .cookie.getValue();
378: }
379:
380: /**
381: * Returns the version of the protocol this cookie complies
382: * with. Version 1 complies with RFC 2109,
383: * and version 0 complies with the original
384: * cookie specification drafted by Netscape. Cookies provided
385: * by a browser use and identify the browser's cookie version.
386: *
387: *
388: * @return 0 if the cookie complies with the
389: * original Netscape specification; 1
390: * if the cookie complies with RFC 2109
391: *
392: * @see #setVersion(int)
393: *
394: */
395:
396: public int getVersion() {
397: this .checkState();
398: return this .cookie.getVersion();
399: }
400:
401: /**
402: * Sets the version of the cookie protocol this cookie complies
403: * with. Version 0 complies with the original Netscape cookie
404: * specification. Version 1 complies with RFC 2109.
405: *
406: * <p>Since RFC 2109 is still somewhat new, consider
407: * version 1 as experimental; do not use it yet on production sites.
408: *
409: *
410: * @param v 0 if the cookie should comply with
411: * the original Netscape specification;
412: * 1 if the cookie should comply with RFC 2109
413: *
414: * @see #getVersion()
415: *
416: */
417:
418: public void setVersion(int v) {
419: this.checkState();
420: this.cookie.setVersion(v);
421: }
422:
423: }
|