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 javax.servlet.http;
018:
019: import java.text.MessageFormat;
020: import java.util.ResourceBundle;
021:
022: /**
023: *
024: * Creates a cookie, a small amount of information sent by a servlet to
025: * a Web browser, saved by the browser, and later sent back to the server.
026: * A cookie's value can uniquely
027: * identify a client, so cookies are commonly used for session management.
028: *
029: * <p>A cookie has a name, a single value, and optional attributes
030: * such as a comment, path and domain qualifiers, a maximum age, and a
031: * version number. Some Web browsers have bugs in how they handle the
032: * optional attributes, so use them sparingly to improve the interoperability
033: * of your servlets.
034: *
035: * <p>The servlet sends cookies to the browser by using the
036: * {@link HttpServletResponse#addCookie} method, which adds
037: * fields to HTTP response headers to send cookies to the
038: * browser, one at a time. The browser is expected to
039: * support 20 cookies for each Web server, 300 cookies total, and
040: * may limit cookie size to 4 KB each.
041: *
042: * <p>The browser returns cookies to the servlet by adding
043: * fields to HTTP request headers. Cookies can be retrieved
044: * from a request by using the {@link HttpServletRequest#getCookies} method.
045: * Several cookies might have the same name but different path attributes.
046: *
047: * <p>Cookies affect the caching of the Web pages that use them.
048: * HTTP 1.0 does not cache pages that use cookies created with
049: * this class. This class does not support the cache control
050: * defined with HTTP 1.1.
051: *
052: * <p>This class supports both the Version 0 (by Netscape) and Version 1
053: * (by RFC 2109) cookie specifications. By default, cookies are
054: * created using Version 0 to ensure the best interoperability.
055: *
056: *
057: * @author Various
058: * @version $Version$
059: *
060: */
061:
062: // XXX would implement java.io.Serializable too, but can't do that
063: // so long as sun.servlet.* must run on older JDK 1.02 JVMs which
064: // don't include that support.
065: public class Cookie implements Cloneable {
066:
067: private static final String LSTRING_FILE = "javax.servlet.http.LocalStrings";
068: private static ResourceBundle lStrings = ResourceBundle
069: .getBundle(LSTRING_FILE);
070:
071: //
072: // The value of the cookie itself.
073: //
074:
075: private String name; // NAME= ... "$Name" style is reserved
076: private String value; // value of NAME
077:
078: //
079: // Attributes encoded in the header's cookie fields.
080: //
081:
082: private String comment; // ;Comment=VALUE ... describes cookie's use
083: // ;Discard ... implied by maxAge < 0
084: private String domain; // ;Domain=VALUE ... domain that sees cookie
085: private int maxAge = -1; // ;Max-Age=VALUE ... cookies auto-expire
086: private String path; // ;Path=VALUE ... URLs that see the cookie
087: private boolean secure; // ;Secure ... e.g. use SSL
088: private int version = 0; // ;Version=1 ... means RFC 2109++ style
089:
090: /**
091: * Constructs a cookie with a specified name and value.
092: *
093: * <p>The name must conform to RFC 2109. That means it can contain
094: * only ASCII alphanumeric characters and cannot contain commas,
095: * semicolons, or white space or begin with a $ character. The cookie's
096: * name cannot be changed after creation.
097: *
098: * <p>The value can be anything the server chooses to send. Its
099: * value is probably of interest only to the server. The cookie's
100: * value can be changed after creation with the
101: * <code>setValue</code> method.
102: *
103: * <p>By default, cookies are created according to the Netscape
104: * cookie specification. The version can be changed with the
105: * <code>setVersion</code> method.
106: *
107: *
108: * @param name a <code>String</code> specifying the name of the cookie
109: *
110: * @param value a <code>String</code> specifying the value of the cookie
111: *
112: * @throws IllegalArgumentException if the cookie name contains illegal characters
113: * (for example, a comma, space, or semicolon)
114: * or it is one of the tokens reserved for use
115: * by the cookie protocol
116: * @see #setValue
117: * @see #setVersion
118: *
119: */
120:
121: public Cookie(String name, String value) {
122: if (!isToken(name)
123: || name.equalsIgnoreCase("Comment") // rfc2019
124: || name.equalsIgnoreCase("Discard") // 2019++
125: || name.equalsIgnoreCase("Domain")
126: || name.equalsIgnoreCase("Expires") // (old cookies)
127: || name.equalsIgnoreCase("Max-Age") // rfc2019
128: || name.equalsIgnoreCase("Path")
129: || name.equalsIgnoreCase("Secure")
130: || name.equalsIgnoreCase("Version")
131: || name.startsWith("$")) {
132: String errMsg = lStrings
133: .getString("err.cookie_name_is_token");
134: Object[] errArgs = new Object[1];
135: errArgs[0] = name;
136: errMsg = MessageFormat.format(errMsg, errArgs);
137: throw new IllegalArgumentException(errMsg);
138: }
139:
140: this .name = name;
141: this .value = value;
142: }
143:
144: /**
145: *
146: * Specifies a comment that describes a cookie's purpose.
147: * The comment is useful if the browser presents the cookie
148: * to the user. Comments
149: * are not supported by Netscape Version 0 cookies.
150: *
151: * @param purpose a <code>String</code> specifying the comment
152: * to display to the user
153: *
154: * @see #getComment
155: *
156: */
157:
158: public void setComment(String purpose) {
159: comment = purpose;
160: }
161:
162: /**
163: * Returns the comment describing the purpose of this cookie, or
164: * <code>null</code> if the cookie has no comment.
165: *
166: * @return a <code>String</code> containing the comment,
167: * or <code>null</code> if none
168: *
169: * @see #setComment
170: *
171: */
172:
173: public String getComment() {
174: return comment;
175: }
176:
177: /**
178: *
179: * Specifies the domain within which this cookie should be presented.
180: *
181: * <p>The form of the domain name is specified by RFC 2109. A domain
182: * name begins with a dot (<code>.foo.com</code>) and means that
183: * the cookie is visible to servers in a specified Domain Name System
184: * (DNS) zone (for example, <code>www.foo.com</code>, but not
185: * <code>a.b.foo.com</code>). By default, cookies are only returned
186: * to the server that sent them.
187: *
188: *
189: * @param pattern a <code>String</code> containing the domain name
190: * within which this cookie is visible;
191: * form is according to RFC 2109
192: *
193: * @see #getDomain
194: *
195: */
196:
197: public void setDomain(String pattern) {
198: domain = pattern.toLowerCase(); // IE allegedly needs this
199: }
200:
201: /**
202: * Returns the domain name set for this cookie. The form of
203: * the domain name is set by RFC 2109.
204: *
205: * @return a <code>String</code> containing the domain name
206: *
207: * @see #setDomain
208: *
209: */
210:
211: public String getDomain() {
212: return domain;
213: }
214:
215: /**
216: * Sets the maximum age of the cookie in seconds.
217: *
218: * <p>A positive value indicates that the cookie will expire
219: * after that many seconds have passed. Note that the value is
220: * the <i>maximum</i> age when the cookie will expire, not the cookie's
221: * current age.
222: *
223: * <p>A negative value means
224: * that the cookie is not stored persistently and will be deleted
225: * when the Web browser exits. A zero value causes the cookie
226: * to be deleted.
227: *
228: * @param expiry an integer specifying the maximum age of the
229: * cookie in seconds; if negative, means
230: * the cookie is not stored; if zero, deletes
231: * the cookie
232: *
233: *
234: * @see #getMaxAge
235: *
236: */
237:
238: public void setMaxAge(int expiry) {
239: maxAge = expiry;
240: }
241:
242: /**
243: * Returns the maximum age of the cookie, specified in seconds,
244: * By default, <code>-1</code> indicating the cookie will persist
245: * until browser shutdown.
246: *
247: *
248: * @return an integer specifying the maximum age of the
249: * cookie in seconds; if negative, means
250: * the cookie persists until browser shutdown
251: *
252: *
253: * @see #setMaxAge
254: *
255: */
256:
257: public int getMaxAge() {
258: return maxAge;
259: }
260:
261: /**
262: * Specifies a path for the cookie
263: * to which the client should return the cookie.
264: *
265: * <p>The cookie is visible to all the pages in the directory
266: * you specify, and all the pages in that directory's subdirectories.
267: * A cookie's path must include the servlet that set the cookie,
268: * for example, <i>/catalog</i>, which makes the cookie
269: * visible to all directories on the server under <i>/catalog</i>.
270: *
271: * <p>Consult RFC 2109 (available on the Internet) for more
272: * information on setting path names for cookies.
273: *
274: *
275: * @param uri a <code>String</code> specifying a path
276: *
277: *
278: * @see #getPath
279: *
280: */
281:
282: public void setPath(String uri) {
283: path = uri;
284: }
285:
286: /**
287: * Returns the path on the server
288: * to which the browser returns this cookie. The
289: * cookie is visible to all subpaths on the server.
290: *
291: *
292: * @return a <code>String</code> specifying a path that contains
293: * a servlet name, for example, <i>/catalog</i>
294: *
295: * @see #setPath
296: *
297: */
298:
299: public String getPath() {
300: return path;
301: }
302:
303: /**
304: * Indicates to the browser whether the cookie should only be sent
305: * using a secure protocol, such as HTTPS or SSL.
306: *
307: * <p>The default value is <code>false</code>.
308: *
309: * @param flag if <code>true</code>, sends the cookie from the browser
310: * to the server only when using a secure protocol;
311: * if <code>false</code>, sent on any protocol
312: *
313: * @see #getSecure
314: *
315: */
316:
317: public void setSecure(boolean flag) {
318: secure = flag;
319: }
320:
321: /**
322: * Returns <code>true</code> if the browser is sending cookies
323: * only over a secure protocol, or <code>false</code> if the
324: * browser can send cookies using any protocol.
325: *
326: * @return <code>true</code> if the browser uses a secure protocol;
327: * otherwise, <code>true</code>
328: *
329: * @see #setSecure
330: *
331: */
332:
333: public boolean getSecure() {
334: return secure;
335: }
336:
337: /**
338: * Returns the name of the cookie. The name cannot be changed after
339: * creation.
340: *
341: * @return a <code>String</code> specifying the cookie's name
342: *
343: */
344:
345: public String getName() {
346: return name;
347: }
348:
349: /**
350: *
351: * Assigns a new value to a cookie after the cookie is created.
352: * If you use a binary value, you may want to use BASE64 encoding.
353: *
354: * <p>With Version 0 cookies, values should not contain white
355: * space, brackets, parentheses, equals signs, commas,
356: * double quotes, slashes, question marks, at signs, colons,
357: * and semicolons. Empty values may not behave the same way
358: * on all browsers.
359: *
360: * @param newValue a <code>String</code> specifying the new value
361: *
362: *
363: * @see #getValue
364: * @see Cookie
365: *
366: */
367:
368: public void setValue(String newValue) {
369: value = newValue;
370: }
371:
372: /**
373: * Returns the value of the cookie.
374: *
375: * @return a <code>String</code> containing the cookie's
376: * present value
377: *
378: * @see #setValue
379: * @see Cookie
380: *
381: */
382:
383: public String getValue() {
384: return value;
385: }
386:
387: /**
388: * Returns the version of the protocol this cookie complies
389: * with. Version 1 complies with RFC 2109,
390: * and version 0 complies with the original
391: * cookie specification drafted by Netscape. Cookies provided
392: * by a browser use and identify the browser's cookie version.
393: *
394: *
395: * @return 0 if the cookie complies with the
396: * original Netscape specification; 1
397: * if the cookie complies with RFC 2109
398: *
399: * @see #setVersion
400: *
401: */
402:
403: public int getVersion() {
404: return version;
405: }
406:
407: /**
408: * Sets the version of the cookie protocol this cookie complies
409: * with. Version 0 complies with the original Netscape cookie
410: * specification. Version 1 complies with RFC 2109.
411: *
412: * <p>Since RFC 2109 is still somewhat new, consider
413: * version 1 as experimental; do not use it yet on production sites.
414: *
415: *
416: * @param v 0 if the cookie should comply with
417: * the original Netscape specification;
418: * 1 if the cookie should comply with RFC 2109
419: *
420: * @see #getVersion
421: *
422: */
423:
424: public void setVersion(int v) {
425: version = v;
426: }
427:
428: // Note -- disabled for now to allow full Netscape compatibility
429: // from RFC 2068, token special case characters
430: //
431: // private static final String tspecials = "()<>@,;:\\\"/[]?={} \t";
432:
433: private static final String tspecials = ",; ";
434:
435: /*
436: * Tests a string and returns true if the string counts as a
437: * reserved token in the Java language.
438: *
439: * @param value the <code>String</code> to be tested
440: *
441: * @return <code>true</code> if the <code>String</code> is
442: * a reserved token; <code>false</code>
443: * if it is not
444: */
445:
446: private boolean isToken(String value) {
447: int len = value.length();
448:
449: for (int i = 0; i < len; i++) {
450: char c = value.charAt(i);
451:
452: if (c < 0x20 || c >= 0x7f || tspecials.indexOf(c) != -1)
453: return false;
454: }
455: return true;
456: }
457:
458: /**
459: *
460: * Overrides the standard <code>java.lang.Object.clone</code>
461: * method to return a copy of this cookie.
462: *
463: *
464: */
465:
466: public Object clone() {
467: try {
468: return super .clone();
469: } catch (CloneNotSupportedException e) {
470: throw new RuntimeException(e.getMessage());
471: }
472: }
473: }
|