All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class javax.servlet.http.Cookie

Object
   |
   +----javax.servlet.http.Cookie

public class Cookie

extends Object

implements Cloneable

Cookies are named, and have a single value. They may have optional attributes, including a comment presented to the user, path and domain qualifiers for which hosts see the cookie, a maximum age, and a version. Current web browsers often have bugs in how they treat those attributes, so interoperability can be improved by not relying on them heavily.

Cookies are assigned by servers, using fields added to HTTP response headers. In this API, cookies are saved one at a time into such HTTP response headers, using the javax.servlet.http.HttpServletResponse.addCookie method. User agents are expected to support twenty cookies per host, of at least four kilobytes each; use of large numbers of cookies is discouraged.

Cookies are passed back to those servers using fields added to HTTP request headers. In this API, HTTP request fields are retrieved using the cookie module's javax.servlet.http.HttpServletRequest.getCookies method. This returns all of the cookies found in the request. Several cookies with the same name can be returned; they have different path attributes, but those attributes will not be visible when using "old format" cookies.

Cookies affect the caching of the web pages used to set their values. At this time, none of the sophisticated HTTP/1.1 cache control models are supported by this class. Standard HTTP/1.0 caches will not cache pages which contain cookies created by this class.

Cookies are being standardized by the IETF. This class supports the original Cookie specification (from Netscape Communications Corp.) as well as the updated RFC 2109 specification. By default, cookies are stored using the original specification. This promotes maximal interoperability; an updated RFC will provide better interoperability by defining a new HTTP header field for setting cookies.

Version:

1.31, 10/08/97

javax.servlet.http.Cookie(String, String)

Defines a cookie with an initial name/value pair.

clone()

Returns a copy of this object.

getComment()

Returns the comment describing the purpose of this cookie, or null if no such comment has been defined.

getDomain()

Returns the domain of this cookie.

getMaxAge()

Returns the maximum specified age of the cookie.

getName()

Returns the name of the cookie.

getPath()

Returns the prefix of all URLs for which this cookie is targetted.

getSecure()

Returns the value of the 'secure' flag.

getValue()

Returns the value of the cookie.

getVersion()

Returns the version of the cookie.

setComment(String)

If a user agent (web browser) presents this cookie to a user, the cookie's purpose will be described using this comment.

setDomain(String)

This cookie should be presented only to hosts satisfying this domain name pattern.

setMaxAge(int)

Sets the maximum age of the cookie.

setPath(String)

This cookie should be presented only with requests beginning with this URL.

setSecure(boolean)

Indicates to the user agent that the cookie should only be sent using a secure protocol (https).

setValue(String)

Sets the value of the cookie.

setVersion(int)

Sets the version of the cookie protocol used when this cookie saves itself.

public Cookie(String name,
              String value)

Defines a cookie with an initial name/value pair. The name must be an HTTP/1.1 "token" value; alphanumeric ASCII strings work. Names starting with a "$" character are reserved by RFC 2109.

Parameters:

name - name of the cookie

value - value of the cookie

Throws: IllegalArgumentException

if the cookie name is not an HTTP/1.1 "token", or if it is one of the tokens reserved for use by the cookie protocol

public java.lang.Object clone()

Returns a copy of this object.

Overrides:

clone in class Object

public java.lang.String getComment()

Returns the comment describing the purpose of this cookie, or null if no such comment has been defined.

See Also:

setComment

public java.lang.String getDomain()

Returns the domain of this cookie.

See Also:

setDomain

public int getMaxAge()

Returns the maximum specified age of the cookie. If none was specified, a negative value is returned, indicating the default behaviour described with setMaxAge.

See Also:

setMaxAge

public java.lang.String getName()

Returns the name of the cookie. This name may not be changed after the cookie is created.

public java.lang.String getPath()

Returns the prefix of all URLs for which this cookie is targetted.

See Also:

setPath

public boolean getSecure()

Returns the value of the 'secure' flag.

See Also:

setSecure

public java.lang.String getValue()

Returns the value of the cookie.

See Also:

setValue

public int getVersion()

Returns the version of the cookie. Version 1 complies with RFC 2109, version 0 indicates the original version, as specified by Netscape. Newly constructed cookies use version 0 by default, to maximize interoperability. Cookies provided by a user agent will identify the cookie version used by the browser.

See Also:

setVersion

public void setComment(String purpose)

If a user agent (web browser) presents this cookie to a user, the cookie's purpose will be described using this comment. This is not supported by version zero cookies.

See Also:

getComment

public void setDomain(String pattern)

This cookie should be presented only to hosts satisfying this domain name pattern. Read RFC 2109 for specific details of the syntax. Briefly, a domain name name begins with a dot (".foo.com") and means that hosts in that DNS zone ("www.foo.com", but not "a.b.foo.com") should see the cookie. By default, cookies are only returned to the host which saved them.

See Also:

getDomain

public void setMaxAge(int expiry)

Sets the maximum age of the cookie. The cookie will expire after that many seconds have passed. Negative values indicate the default behaviour: the cookie is not stored persistently, and will be deleted when the user agent (web browser) exits. A zero value causes the cookie to be deleted.

See Also:

getMaxAge

public void setPath(String uri)

This cookie should be presented only with requests beginning with this URL. Read RFC 2109 for a specification of the default behaviour. Basically, URLs in the same "directory" as the one which set the cookie, and in subdirectories, can all see the cookie unless a different path is set.

See Also:

getPath

public void setSecure(boolean flag)

Indicates to the user agent that the cookie should only be sent using a secure protocol (https). This should only be set when the cookie's originating server used a secure protocol to set the cookie's value.

See Also:

getSecure

public void setValue(String newValue)

Sets the value of the cookie. BASE64 encoding is suggested for use with binary values.

With version zero cookies, you need to be careful about the kinds of values you use. Values with various special characters (whitespace, brackets and parentheses, the equals sign, comma, double quote, slashes, question marks, the "at" sign, colon, and semicolon) should be avoided. Empty values may not behave the same way on all browsers.

See Also:

getValue

public void setVersion(int v)

Sets the version of the cookie protocol used when this cookie saves itself. Since the IETF standards are still being finalized, consider version 1 as experimental; do not use it (yet) on production sites.

See Also:

getVersion

All Packages  Class Hierarchy  This Package  Previous  Next  Index