Synopsis
Class Name: javax.servlet.http.Cookie
Superclass: java.lang.Object
Immediate Subclasses: None
Interfaces Implemented: java.lang.Cloneable
Availability: Servlet API 2.0 and later
Description
The Cookie class provides an easy way for servlets to read, create, and manipulate HTTP-style cookies, which allow servlets to store small amounts of data on the client. Cookies are generally used for session tracking or storing small amounts of user-specific configuration information. For more information, consult Chapter 7.
A servlet uses the getCookies( ) method of HttpServletRequest to retrieve cookies submitted as part of a client request. The addCookie( ) method of HttpServletResponse sends a new cookie to the browser. Because cookies are set using HTTP headers, addCookie( ) must be called before the response is committed.
The getXXX() methods are rarely used because when a cookie is sent to the server, it contains only its name, value, and version. If you set an attribute on a cookie received from the client, you must add it to the response for the change to take effect, and you should take care that all attributes except name, value, and version are reset on the cookie as well.
This class supports both the Netscape cookie specification and RFC 2109.
Class Summary
public class Cookie implements java.lang.Cloneable { // Constructors public Cookie(String name, String value); // Instance methods public Object clone(); public String getComment(); public String getDomain(); public int getMaxAge(); public String getName(); public String getPath(); public boolean getSecure(); public String getValue(); public int getVersion(); public void setComment(String purpose); public void setDomain(String pattern); public void setMaxAge(int expiry); public void setPath(String uri); public void setSecure(boolean flag); public void setValue(String newValue); public void setVersion(int v); } Constructors
Cookie()
public Cookie(String name, String value)
- Description
-
Constructs a new cookie with an initial name and value. The rules for valid names and values are given in Netscape's cookie specification and RFC 2109.
Instance Methods
clone()
public Object clone()
- Description
-
Overrides the standard clone( ) method to return a copy of this object (a duplicate cookie).
getComment()
public String getComment()
- Description
-
Returns the comment associated with the cookie. This information is available only right after the comment has been set; when the cookie is returned by the client this information is not included.
getDomain()
public String getDomain()
- Description
-
Returns the domain limitation associated with this cookie. This information is available only right after the domain has been set; when the cookie is returned by the client this information is not included.
getMaxAge()
public int getMaxAge()
- Description
-
Returns the maximum age allowed for this cookie. This information is available only right after the maximum age has been set; when the cookie is returned by the client this information is not included.
getName()
public String getName()
- Description
-
Returns the name of this cookie.
getPath()
public String getPath()
- Description
-
Returns the path limitation for this servlet. This information is available only right after the path has been set; when the cookie is returned by the client this information is not included.
getSecure()
public boolean getSecure()
- Description
-
Returns true if this cookie requires a secure connection, false otherwise. This information is available only right after the flag has been set; when the cookie is returned by the client this information is not included.
getValue()
public String getValue()
- Description
-
Returns the value of this cookie, in string format.
getVersion()
public int getVersion()
- Description
-
Returns the version of this cookie.
setComment()
public void setComment(String purpose)
- Description
-
Sets the comment field of the cookie. A comment describes the intended purpose of a cookie. A web browser may choose to display this text to the user. Comments are not supported by Version 0 cookies.
setDomain()
public void setDomain(String pattern)
- Description
-
Specifies a domain restriction pattern. A domain pattern specifies the servers that should see a cookie. By default, cookies are returned only to the host that saved them. Specifying a domain name pattern overrides this. The pattern must begin with a dot and must contain at least two dots. A pattern matches only one entry beyond the initial dot. For example, .foo.com is valid and matches www.foo.com and upload.foo.com but not www.upload.foo.com. For details on domain patterns, see Netscape's cookie specification and RFC 2109.
setMaxAge()
public void setMaxAge(int expiry)
- Description
-
Specifies the maximum age of the cookie in seconds before it expires. A negative value indicates the default, that the cookie should expire when the browser exits. A zero value tells the browser to delete the cookie immediately.
setPath()
public void setPath(String uri)
- Description
-
Specifies a path for the cookie, which is the subset of URIs to which a cookie should be sent. By default, cookies are sent to the page that set the cookie and to all the pages in that directory or under that directory. For example, if /servlet/CookieMonster sets a cookie, the default path is /servlet. That path indicates the cookie should be sent to /servlet/Elmo and to /servlet/subdir/BigBird but not to the /Oscar.html servlet alias or to any CGI programs under /cgi-bin. A path set to "/" causes a cookie to be sent to all the pages on a server. A cookie's path must be such that it includes the servlet that set the cookie.
setSecure()
public void setSecure(boolean flag)
- Description
-
The secure flag indicates whether the cookie should be sent only over a secure channel, such as SSL. This value defaults to false.
setValue()
public void setValue(String newValue)
- Description
-
Assigns a new value to a cookie. With Version 0 cookies, values should not contain the following: whitespace, brackets, parentheses, equals signs, commas, double quotes, slashes, question marks, at signs, colons, or semicolons. Empty values may not behave the same way on all browsers.
setVersion()
public void setVersion(int v)
- Description
-
Servlets can send and receive cookies formatted to match either Netscape persistent cookies (Version 0) or the newer, somewhat experimental, RFC 2109 cookies (Version 1). Newly constructed cookies default to Version 0 to maximize interoperability. When using Version 1 cookies the servlet container may also send a Version 0 style cookie with the same name and value for backward compatibility.
