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;
018:
019: /**
020: *
021: * Creates a cookie, a small amount of information sent by a servlet to
022: * a Web browser, saved by the browser, and later sent back to the server.
023: * A cookie's value can uniquely
024: * identify a client, so cookies are commonly used for session management.
025: *
026: * <p>A cookie has a name, a single value, and optional attributes
027: * such as a comment, path and domain qualifiers, a maximum age, and a
028: * version number. Some Web browsers have bugs in how they handle the
029: * optional attributes, so use them sparingly to improve the interoperability
030: * of your servlets.
031: *
032: * <p>The servlet sends cookies to the browser by using the
033: * {@link Response#addCookie(Cookie)} method, which adds
034: * fields to HTTP response headers to send cookies to the
035: * browser, one at a time. The browser is expected to
036: * support 20 cookies for each Web server, 300 cookies total, and
037: * may limit cookie size to 4 KB each.
038: *
039: * <p>The browser returns cookies to the servlet by adding
040: * fields to HTTP request headers. Cookies can be retrieved
041: * from a request by using the {@link Request#getCookies()} method.
042: * Several cookies might have the same name but different path attributes.
043: *
044: * <p>Cookies affect the caching of the Web pages that use them.
045: * HTTP 1.0 does not cache pages that use cookies created with
046: * this class. This class does not support the cache control
047: * defined with HTTP 1.1.
048: *
049: * <p>This class supports both the Version 0 (by Netscape) and Version 1
050: * (by RFC 2109) cookie specifications. By default, cookies are
051: * created using Version 0 to ensure the best interoperability.
052: *
053: *
054: * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
055: * @version CVS $Id: Cookie.java 433543 2006-08-22 06:22:54Z crossley $
056: *
057: */
058:
059: public interface Cookie {
060:
061: /**
062: *
063: * Specifies a comment that describes a cookie's purpose.
064: * The comment is useful if the browser presents the cookie
065: * to the user. Comments
066: * are not supported by Netscape Version 0 cookies.
067: *
068: * @param purpose a <code>String</code> specifying the comment
069: * to display to the user
070: *
071: * @see #getComment()
072: *
073: */
074:
075: void setComment(String purpose);
076:
077: /**
078: * Returns the comment describing the purpose of this cookie, or
079: * <code>null</code> if the cookie has no comment.
080: *
081: * @return a <code>String</code> containing the comment,
082: * or <code>null</code> if none
083: *
084: * @see #setComment(String)
085: *
086: */
087:
088: String getComment();
089:
090: /**
091: *
092: * Specifies the domain within which this cookie should be presented.
093: *
094: * <p>The form of the domain name is specified by RFC 2109. A domain
095: * name begins with a dot (<code>.foo.com</code>) and means that
096: * the cookie is visible to servers in a specified Domain Name System
097: * (DNS) zone (for example, <code>www.foo.com</code>, but not
098: * <code>a.b.foo.com</code>). By default, cookies are only returned
099: * to the server that sent them.
100: *
101: *
102: * @param pattern a <code>String</code> containing the domain name
103: * within which this cookie is visible;
104: * form is according to RFC 2109
105: *
106: * @see #getDomain()
107: *
108: */
109:
110: void setDomain(String pattern);
111:
112: /**
113: * Returns the domain name set for this cookie. The form of
114: * the domain name is set by RFC 2109.
115: *
116: * @return a <code>String</code> containing the domain name
117: *
118: * @see #setDomain(String)
119: *
120: */
121:
122: String getDomain();
123:
124: /**
125: * Sets the maximum age of the cookie in seconds.
126: *
127: * <p>A positive value indicates that the cookie will expire
128: * after that many seconds have passed. Note that the value is
129: * the <i>maximum</i> age when the cookie will expire, not the cookie's
130: * current age.
131: *
132: * <p>A negative value means
133: * that the cookie is not stored persistently and will be deleted
134: * when the Web browser exits. A zero value causes the cookie
135: * to be deleted.
136: *
137: * @param expiry an integer specifying the maximum age of the
138: * cookie in seconds; if negative, means
139: * the cookie is not stored; if zero, deletes
140: * the cookie
141: *
142: *
143: * @see #getMaxAge()
144: *
145: */
146:
147: void setMaxAge(int expiry);
148:
149: /**
150: * Returns the maximum age of the cookie, specified in seconds,
151: * By default, <code>-1</code> indicating the cookie will persist
152: * until browser shutdown.
153: *
154: *
155: * @return an integer specifying the maximum age of the
156: * cookie in seconds; if negative, means
157: * the cookie persists until browser shutdown
158: *
159: *
160: * @see #setMaxAge(int)
161: *
162: */
163:
164: int getMaxAge();
165:
166: /**
167: * Specifies a path for the cookie
168: * to which the client should return the cookie.
169: *
170: * <p>The cookie is visible to all the pages in the directory
171: * you specify, and all the pages in that directory's subdirectories.
172: * A cookie's path must include the servlet that set the cookie,
173: * for example, <i>/catalog</i>, which makes the cookie
174: * visible to all directories on the server under <i>/catalog</i>.
175: *
176: * <p>Consult RFC 2109 (available on the Internet) for more
177: * information on setting path names for cookies.
178: *
179: *
180: * @param uri a <code>String</code> specifying a path
181: *
182: *
183: * @see #getPath()
184: *
185: */
186:
187: void setPath(String uri);
188:
189: /**
190: * Returns the path on the server
191: * to which the browser returns this cookie. The
192: * cookie is visible to all subpaths on the server.
193: *
194: *
195: * @return a <code>String</code> specifying a path that contains
196: * a servlet name, for example, <i>/catalog</i>
197: *
198: * @see #setPath(String)
199: *
200: */
201:
202: String getPath();
203:
204: /**
205: * Indicates to the browser whether the cookie should only be sent
206: * using a secure protocol, such as HTTPS or SSL.
207: *
208: * <p>The default value is <code>false</code>.
209: *
210: * @param flag if <code>true</code>, sends the cookie from the browser
211: * to the server using only when using a secure protocol;
212: * if <code>false</code>, sent on any protocol
213: *
214: * @see #getSecure()
215: *
216: */
217:
218: void setSecure(boolean flag);
219:
220: /**
221: * Returns <code>true</code> if the browser is sending cookies
222: * only over a secure protocol, or <code>false</code> if the
223: * browser can send cookies using any protocol.
224: *
225: * @return <code>true</code> if the browser can use
226: * any standard protocol; otherwise, <code>false</code>
227: *
228: * @see #setSecure(boolean)
229: *
230: */
231:
232: boolean getSecure();
233:
234: /**
235: * Returns the name of the cookie. The name cannot be changed after
236: * creation.
237: *
238: * @return a <code>String</code> specifying the cookie's name
239: *
240: */
241:
242: String getName();
243:
244: /**
245: *
246: * Assigns a new value to a cookie after the cookie is created.
247: * If you use a binary value, you may want to use BASE64 encoding.
248: *
249: * <p>With Version 0 cookies, values should not contain white
250: * space, brackets, parentheses, equals signs, commas,
251: * double quotes, slashes, question marks, at signs, colons,
252: * and semicolons. Empty values may not behave the same way
253: * on all browsers.
254: *
255: * @param newValue a <code>String</code> specifying the new value
256: *
257: *
258: * @see #getValue()
259: * @see Cookie
260: *
261: */
262:
263: void setValue(String newValue);
264:
265: /**
266: * Returns the value of the cookie.
267: *
268: * @return a <code>String</code> containing the cookie's
269: * present value
270: *
271: * @see #setValue(String)
272: * @see Cookie
273: *
274: */
275:
276: String getValue();
277:
278: /**
279: * Returns the version of the protocol this cookie complies
280: * with. Version 1 complies with RFC 2109,
281: * and version 0 complies with the original
282: * cookie specification drafted by Netscape. Cookies provided
283: * by a browser use and identify the browser's cookie version.
284: *
285: *
286: * @return 0 if the cookie complies with the
287: * original Netscape specification; 1
288: * if the cookie complies with RFC 2109
289: *
290: * @see #setVersion(int)
291: *
292: */
293:
294: int getVersion();
295:
296: /**
297: * Sets the version of the cookie protocol this cookie complies
298: * with. Version 0 complies with the original Netscape cookie
299: * specification. Version 1 complies with RFC 2109.
300: *
301: * <p>Since RFC 2109 is still somewhat new, consider
302: * version 1 as experimental; do not use it yet on production sites.
303: *
304: *
305: * @param v 0 if the cookie should comply with
306: * the original Netscape specification;
307: * 1 if the cookie should comply with RFC 2109
308: *
309: * @see #getVersion()
310: *
311: */
312:
313: void setVersion(int v);
314:
315: }
|