/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.cocoon.environment; /** * * Creates a cookie, a small amount of information sent by a servlet to * a Web browser, saved by the browser, and later sent back to the server. * A cookie's value can uniquely * identify a client, so cookies are commonly used for session management. * * <p>A cookie has a name, a single value, and optional attributes * such as a comment, path and domain qualifiers, a maximum age, and a * version number. Some Web browsers have bugs in how they handle the * optional attributes, so use them sparingly to improve the interoperability * of your servlets. * * <p>The servlet sends cookies to the browser by using the * {@link Response#addCookie(Cookie)} method, which adds * fields to HTTP response headers to send cookies to the * browser, one at a time. The browser is expected to * support 20 cookies for each Web server, 300 cookies total, and * may limit cookie size to 4 KB each. * * <p>The browser returns cookies to the servlet by adding * fields to HTTP request headers. Cookies can be retrieved * from a request by using the {@link Request#getCookies()} method. * Several cookies might have the same name but different path attributes. * * <p>Cookies affect the caching of the Web pages that use them. * HTTP 1.0 does not cache pages that use cookies created with * this class. This class does not support the cache control * defined with HTTP 1.1. * * <p>This class supports both the Version 0 (by Netscape) and Version 1 * (by RFC 2109) cookie specifications. By default, cookies are * created using Version 0 to ensure the best interoperability. * * * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a> * @version CVS $Id$ * */ public interface Cookie { /** * * Specifies a comment that describes a cookie's purpose. * The comment is useful if the browser presents the cookie * to the user. Comments * are not supported by Netscape Version 0 cookies. * * @param purpose a <code>String</code> specifying the comment * to display to the user * * @see #getComment() * */ void setComment(String purpose); /** * Returns the comment describing the purpose of this cookie, or * <code>null</code> if the cookie has no comment. * * @return a <code>String</code> containing the comment, * or <code>null</code> if none * * @see #setComment(String) * */ String getComment(); /** * * Specifies the domain within which this cookie should be presented. * * <p>The form of the domain name is specified by RFC 2109. A domain * name begins with a dot (<code>.foo.com</code>) and means that * the cookie is visible to servers in a specified Domain Name System * (DNS) zone (for example, <code>www.foo.com</code>, but not * <code>a.b.foo.com</code>). By default, cookies are only returned * to the server that sent them. * * * @param pattern a <code>String</code> containing the domain name * within which this cookie is visible; * form is according to RFC 2109 * * @see #getDomain() * */ void setDomain(String pattern); /** * Returns the domain name set for this cookie. The form of * the domain name is set by RFC 2109. * * @return a <code>String</code> containing the domain name * * @see #setDomain(String) * */ String getDomain(); /** * Sets the maximum age of the cookie in seconds. * * <p>A positive value indicates that the cookie will expire * after that many seconds have passed. Note that the value is * the <i>maximum</i> age when the cookie will expire, not the cookie's * current age. * * <p>A negative value means * that the cookie is not stored persistently and will be deleted * when the Web browser exits. A zero value causes the cookie * to be deleted. * * @param expiry an integer specifying the maximum age of the * cookie in seconds; if negative, means * the cookie is not stored; if zero, deletes * the cookie * * * @see #getMaxAge() * */ void setMaxAge(int expiry); /** * Returns the maximum age of the cookie, specified in seconds, * By default, <code>-1</code> indicating the cookie will persist * until browser shutdown. * * * @return an integer specifying the maximum age of the * cookie in seconds; if negative, means * the cookie persists until browser shutdown * * * @see #setMaxAge(int) * */ int getMaxAge(); /** * Specifies a path for the cookie * to which the client should return the cookie. * * <p>The cookie is visible to all the pages in the directory * you specify, and all the pages in that directory's subdirectories. * A cookie's path must include the servlet that set the cookie, * for example, <i>/catalog</i>, which makes the cookie * visible to all directories on the server under <i>/catalog</i>. * * <p>Consult RFC 2109 (available on the Internet) for more * information on setting path names for cookies. * * * @param uri a <code>String</code> specifying a path * * * @see #getPath() * */ void setPath(String uri); /** * Returns the path on the server * to which the browser returns this cookie. The * cookie is visible to all subpaths on the server. * * * @return a <code>String</code> specifying a path that contains * a servlet name, for example, <i>/catalog</i> * * @see #setPath(String) * */ String getPath(); /** * Indicates to the browser whether the cookie should only be sent * using a secure protocol, such as HTTPS or SSL. * * <p>The default value is <code>false</code>. * * @param flag if <code>true</code>, sends the cookie from the browser * to the server using only when using a secure protocol; * if <code>false</code>, sent on any protocol * * @see #getSecure() * */ void setSecure(boolean flag); /** * Returns <code>true</code> if the browser is sending cookies * only over a secure protocol, or <code>false</code> if the * browser can send cookies using any protocol. * * @return <code>true</code> if the browser can use * any standard protocol; otherwise, <code>false</code> * * @see #setSecure(boolean) * */ boolean getSecure(); /** * Returns the name of the cookie. The name cannot be changed after * creation. * * @return a <code>String</code> specifying the cookie's name * */ String getName(); /** * * Assigns a new value to a cookie after the cookie is created. * If you use a binary value, you may want to use BASE64 encoding. * * <p>With Version 0 cookies, values should not contain white * space, brackets, parentheses, equals signs, commas, * double quotes, slashes, question marks, at signs, colons, * and semicolons. Empty values may not behave the same way * on all browsers. * * @param newValue a <code>String</code> specifying the new value * * * @see #getValue() * @see Cookie * */ void setValue(String newValue); /** * Returns the value of the cookie. * * @return a <code>String</code> containing the cookie's * present value * * @see #setValue(String) * @see Cookie * */ String getValue(); /** * Returns the version of the protocol this cookie complies * with. Version 1 complies with RFC 2109, * and version 0 complies with the original * cookie specification drafted by Netscape. Cookies provided * by a browser use and identify the browser's cookie version. * * * @return 0 if the cookie complies with the * original Netscape specification; 1 * if the cookie complies with RFC 2109 * * @see #setVersion(int) * */ int getVersion(); /** * Sets the version of the cookie protocol this cookie complies * with. Version 0 complies with the original Netscape cookie * specification. Version 1 complies with RFC 2109. * * <p>Since RFC 2109 is still somewhat new, consider * version 1 as experimental; do not use it yet on production sites. * * * @param v 0 if the cookie should comply with * the original Netscape specification; * 1 if the cookie should comply with RFC 2109 * * @see #getVersion() * */ void setVersion(int v); }