Cookie


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;
17  
18  /**
19   *
20   * Creates a cookie, a small amount of information sent by a servlet to
21   * a Web browser, saved by the browser, and later sent back to the server.
22   * A cookie's value can uniquely
23   * identify a client, so cookies are commonly used for session management.
24   *
25   * <p>A cookie has a name, a single value, and optional attributes
26   * such as a comment, path and domain qualifiers, a maximum age, and a
27   * version number. Some Web browsers have bugs in how they handle the
28   * optional attributes, so use them sparingly to improve the interoperability
29   * of your servlets.
30   *
31   * <p>The servlet sends cookies to the browser by using the
32   * {@link Response#addCookie(Cookie)} method, which adds
33   * fields to HTTP response headers to send cookies to the
34   * browser, one at a time. The browser is expected to
35   * support 20 cookies for each Web server, 300 cookies total, and
36   * may limit cookie size to 4 KB each.
37   *
38   * <p>The browser returns cookies to the servlet by adding
39   * fields to HTTP request headers. Cookies can be retrieved
40   * from a request by using the {@link Request#getCookies()} method.
41   * Several cookies might have the same name but different path attributes.
42   *
43   * <p>Cookies affect the caching of the Web pages that use them.
44   * HTTP 1.0 does not cache pages that use cookies created with
45   * this class. This class does not support the cache control
46   * defined with HTTP 1.1.
47   *
48   * <p>This class supports both the Version 0 (by Netscape) and Version 1
49   * (by RFC 2109) cookie specifications. By default, cookies are
50   * created using Version 0 to ensure the best interoperability.
51   *
52   *
53   * @author <a HREF="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
54   * @version CVS $Id: Cookie.java 30932 2004-07-29 17:35:38Z vgritsenko $
55   *
56   */
57  
58  public interface Cookie {
59  
60      /**
61       *
62       * Specifies a comment that describes a cookie's purpose.
63       * The comment is useful if the browser presents the cookie
64       * to the user. Comments
65       * are not supported by Netscape Version 0 cookies.
66       *
67       * @param purpose       a <code>String</code> specifying the comment
68       *              to display to the user
69       *
70       * @see #getComment()
71       *
72       */
73  
74      void setComment(String   purpose);
75  
76  
77  
78  
79      /**
80       * Returns the comment describing the purpose of this cookie, or
81       * <code>null</code> if the cookie has no comment.
82       *
83       * @return          a <code>String</code> containing the comment,
84       *              or <code>null</code> if none
85       *
86       * @see #setComment(String)
87       *
88       */
89  
90      String   getComment();
91  
92  
93  
94  
95      /**
96       *
97       * Specifies the domain within which this cookie should be presented.
98       *
99       * <p>The form of the domain name is specified by RFC 2109. A domain
100      * name begins with a dot (<code>.foo.com</code>) and means that
101      * the cookie is visible to servers in a specified Domain Name System
102      * (DNS) zone (for example, <code>www.foo.com</code>, but not
103      * <code>a.b.foo.com</code>). By default, cookies are only returned
104      * to the server that sent them.
105      *
106      *
107      * @param pattern       a <code>String</code> containing the domain name
108      *              within which this cookie is visible;
109      *              form is according to RFC 2109
110      *
111      * @see #getDomain()
112      *
113      */
114 
115     void setDomain(String   pattern);
116 
117 
118 
119 
120 
121     /**
122      * Returns the domain name set for this cookie. The form of
123      * the domain name is set by RFC 2109.
124      *
125      * @return          a <code>String</code> containing the domain name
126      *
127      * @see #setDomain(String)
128      *
129      */
130 
131     String   getDomain();
132 
133 
134 
135 
136     /**
137      * Sets the maximum age of the cookie in seconds.
138      *
139      * <p>A positive value indicates that the cookie will expire
140      * after that many seconds have passed. Note that the value is
141      * the <i>maximum</i> age when the cookie will expire, not the cookie's
142      * current age.
143      *
144      * <p>A negative value means
145      * that the cookie is not stored persistently and will be deleted
146      * when the Web browser exits. A zero value causes the cookie
147      * to be deleted.
148      *
149      * @param expiry        an integer specifying the maximum age of the
150      *              cookie in seconds; if negative, means
151      *              the cookie is not stored; if zero, deletes
152      *              the cookie
153      *
154      *
155      * @see #getMaxAge()
156      *
157      */
158 
159     void setMaxAge(int expiry);
160 
161 
162 
163 
164     /**
165      * Returns the maximum age of the cookie, specified in seconds,
166      * By default, <code>-1</code> indicating the cookie will persist
167      * until browser shutdown.
168      *
169      *
170      * @return          an integer specifying the maximum age of the
171      *              cookie in seconds; if negative, means
172      *              the cookie persists until browser shutdown
173      *
174      *
175      * @see #setMaxAge(int)
176      *
177      */
178 
179     int getMaxAge();
180 
181 
182 
183 
184     /**
185      * Specifies a path for the cookie
186      * to which the client should return the cookie.
187      *
188      * <p>The cookie is visible to all the pages in the directory
189      * you specify, and all the pages in that directory's subdirectories.
190      * A cookie's path must include the servlet that set the cookie,
191      * for example, <i>/catalog</i>, which makes the cookie
192      * visible to all directories on the server under <i>/catalog</i>.
193      *
194      * <p>Consult RFC 2109 (available on the Internet) for more
195      * information on setting path names for cookies.
196      *
197      *
198      * @param uri       a <code>String</code> specifying a path
199      *
200      *
201      * @see #getPath()
202      *
203      */
204 
205     void setPath(String   uri);
206 
207 
208 
209 
210     /**
211      * Returns the path on the server
212      * to which the browser returns this cookie. The
213      * cookie is visible to all subpaths on the server.
214      *
215      *
216      * @return      a <code>String</code> specifying a path that contains
217      *          a servlet name, for example, <i>/catalog</i>
218      *
219      * @see #setPath(String)
220      *
221      */
222 
223     String   getPath();
224 
225 
226 
227 
228 
229     /**
230      * Indicates to the browser whether the cookie should only be sent
231      * using a secure protocol, such as HTTPS or SSL.
232      *
233      * <p>The default value is <code>false</code>.
234      *
235      * @param flag  if <code>true</code>, sends the cookie from the browser
236      *          to the server using only when using a secure protocol;
237      *          if <code>false</code>, sent on any protocol
238      *
239      * @see #getSecure()
240      *
241      */
242 
243     void setSecure(boolean flag);
244 
245 
246 
247 
248     /**
249      * Returns <code>true</code> if the browser is sending cookies
250      * only over a secure protocol, or <code>false</code> if the
251      * browser can send cookies using any protocol.
252      *
253      * @return      <code>true</code> if the browser can use
254      *          any standard protocol; otherwise, <code>false</code>
255      *
256      * @see #setSecure(boolean)
257      *
258      */
259 
260     boolean getSecure();
261 
262 
263 
264 
265 
266     /**
267      * Returns the name of the cookie. The name cannot be changed after
268      * creation.
269      *
270      * @return      a <code>String</code> specifying the cookie's name
271      *
272      */
273 
274     String   getName();
275 
276 
277 
278 
279 
280     /**
281      *
282      * Assigns a new value to a cookie after the cookie is created.
283      * If you use a binary value, you may want to use BASE64 encoding.
284      *
285      * <p>With Version 0 cookies, values should not contain white
286      * space, brackets, parentheses, equals signs, commas,
287      * double quotes, slashes, question marks, at signs, colons,
288      * and semicolons. Empty values may not behave the same way
289      * on all browsers.
290      *
291      * @param newValue      a <code>String</code> specifying the new value
292      *
293      *
294      * @see #getValue()
295      * @see Cookie
296      *
297      */
298 
299     void setValue(String   newValue);
300 
301 
302 
303 
304     /**
305      * Returns the value of the cookie.
306      *
307      * @return          a <code>String</code> containing the cookie's
308      *              present value
309      *
310      * @see #setValue(String)
311      * @see Cookie
312      *
313      */
314 
315     String   getValue();
316 
317 
318 
319 
320     /**
321      * Returns the version of the protocol this cookie complies
322      * with. Version 1 complies with RFC 2109,
323      * and version 0 complies with the original
324      * cookie specification drafted by Netscape. Cookies provided
325      * by a browser use and identify the browser's cookie version.
326      *
327      *
328      * @return          0 if the cookie complies with the
329      *              original Netscape specification; 1
330      *              if the cookie complies with RFC 2109
331      *
332      * @see #setVersion(int)
333      *
334      */
335 
336     int getVersion();
337 
338 
339 
340 
341     /**
342      * Sets the version of the cookie protocol this cookie complies
343      * with. Version 0 complies with the original Netscape cookie
344      * specification. Version 1 complies with RFC 2109.
345      *
346      * <p>Since RFC 2109 is still somewhat new, consider
347      * version 1 as experimental; do not use it yet on production sites.
348      *
349      *
350      * @param v         0 if the cookie should comply with
351      *              the original Netscape specification;
352      *              1 if the cookie should comply with RFC 2109
353      *
354      * @see #getVersion()
355      *
356      */
357 
358     void setVersion(int v);
359 
360 
361 
362 }
363 
364
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags