Top Description Fields Constructors Methods
jakarta.servlet.http

public Class Cookie

Additional top-level classes in compilation unit: CookieNameValidator, RFC6265Validator.

extends Object
implements Cloneable, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, java.lang.Cloneable
Imports
java.io.Serializable, java.text.MessageFormat, java.util.BitSet, .Collections, .Locale, .Map, .ResourceBundle, .TreeMap
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.

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.

The servlet sends cookies to the browser by using the HttpServletResponse#addCookie method, which adds fields to HTTP response headers to send cookies to the browser, one at a time. The browser is expected to support 50 cookies for each domain, 3000 cookies total, and may limit cookie size to 4 KiB each.

The browser returns cookies to the servlet by adding fields to HTTP request headers. Cookies can be retrieved from a request by using the HttpServletRequest#getCookies method. Several cookies might have the same name but different path attributes.

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.

This class supports both the RFC 6265 specification.

Field Summary

Modifier and TypeField and Description
private volatile Map<String, String>
attributes

Attributes encoded in the header's cookie fields.

private static final String
DOMAIN

private static final String
HTTP_ONLY

private static final String
LSTRING_FILE

private static final ResourceBundle
LSTRINGS

private static final String
MAX_AGE

private final String
name

Cookie name.

private static final String
PATH

private static final String
SECURE

private static final long
serialVersionUID

private static final CookieNameValidator
validation

private String
value

Cookie value.

Constructor Summary

AccessConstructor and Description

Method Summary

Modifier and TypeMethod and Description
public Object
clone()

Overrides java.lang.Object.clone.

Overrides the standard java.lang.Object.clone method to return a copy of this cookie.

public boolean
equals(Object
the reference object with which to compare.
obj)

Overrides java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

public String

Returns:

Value of specified attribute
getAttribute(String
Name of attribute to return
name)

Obtain the value for a given attribute.

public Map<String, String>

Returns:

A read-only Map of attributes to values, excluding version.
getAttributes()

Obtain the Map of attributes and values (excluding version) for this cookie.

public String

Returns:

always null
getComment()
Deprecated for removal since Servlet 6.0. This is no longer required with RFC 6265

With the adoption of support for RFC 6265, this method should no longer be used.

public String

Returns:

a String containing the domain name
getDomain()

Returns the domain name set for this cookie.

public int

Returns:

an integer specifying the maximum age of the cookie in seconds; if negative, means the cookie persists until browser shutdown
getMaxAge()

Returns the maximum age of the cookie, specified in seconds, By default, -1 indicating the cookie will persist until browser shutdown.

public String

Returns:

a String specifying the cookie's name
getName()

Returns the name of the cookie.

public String

Returns:

a String specifying a path that contains a servlet name, for example, /catalog
getPath()

Returns the path on the server to which the browser returns this cookie.

public boolean

Returns:

true if the browser uses a secure protocol; otherwise, false
getSecure()

Returns true if the browser is sending cookies only over a secure protocol, or false if the browser can send cookies using any protocol.

public String

Returns:

a String containing the cookie's present value
getValue()

Returns the value of the cookie.

public int

Returns:

Always zero
getVersion()
Deprecated for removal since Servlet 6.0. This is no longer required with RFC 6265

With the adoption of support for RFC 6265, this method should no longer be used.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.

public boolean

Returns:

true if the cookie is hidden from scripts, else false
isHttpOnly()

Gets the flag that controls if this cookie will be hidden from scripts on the client side.

public void
setAttribute(String
Name of attribute to set
name, String
Value of attribute
value)

Sets the value for the given cookie attribute.

private void
setAttributeInternal(String name, String value)

public void
setComment(String
ignored
purpose)
Deprecated for removal since Servlet 6.0. This is no longer required with RFC 6265

If called, this method has no effect.

public void
setDomain(String
a String containing the domain name within which this cookie is visible
pattern)

Specifies the domain within which this cookie should be presented.

public void
setHttpOnly(boolean
The new value of the flag
httpOnly)

Sets the flag that controls if this cookie will be hidden from scripts on the client side.

public void
setMaxAge(int
an integer specifying the maximum age of the cookie in seconds; if negative, means the cookie is not stored; if zero, deletes the cookie
expiry)

Sets the maximum age of the cookie in seconds.

public void
setPath(String
a String specifying a path
uri)

Specifies a path for the cookie to which the client should return the cookie.

public void
setSecure(boolean
if true, sends the cookie from the browser to the server only when using a secure protocol; if false, sent on any protocol
flag)

Indicates to the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL.

public void
setValue(String
a String specifying the new value
newValue)

Assigns a new value to a cookie after the cookie is created.

public void
setVersion(int
Ignored
v)
Deprecated for removal since Servlet 6.0. This is no longer required with RFC 6265

If called, this method has no effect.

Inherited from java.lang.Object:
finalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

attributesback to summary
private volatile Map<String, String> attributes

Attributes encoded in the header's cookie fields.

DOMAINback to summary
private static final String DOMAIN
HTTP_ONLYback to summary
private static final String HTTP_ONLY
LSTRING_FILEback to summary
private static final String LSTRING_FILE
LSTRINGSback to summary
private static final ResourceBundle LSTRINGS
MAX_AGEback to summary
private static final String MAX_AGE
nameback to summary
private final String name

Cookie name.

PATHback to summary
private static final String PATH
SECUREback to summary
private static final String SECURE
serialVersionUIDback to summary
private static final long serialVersionUID
validationback to summary
private static final CookieNameValidator validation
valueback to summary
private String value

Cookie value.

Constructor Detail

Cookieback to summary
public Cookie(String name, String value)

Constructs a cookie with a specified name and value.

The cookie's name cannot be changed after creation.

The value can be anything the server chooses to send. Its value is probably of interest only to the server. The cookie's value can be changed after creation with the setValue method.

Parameters
name:String

a String specifying the name of the cookie

value:String

a String specifying the value of the cookie

Exceptions
IllegalArgumentException:
if the cookie name contains illegal characters
See Also
setValue

Method Detail

cloneback to summary
public Object clone()

Overrides java.lang.Object.clone.

Overrides the standard java.lang.Object.clone method to return a copy of this cookie.

Returns:Object

Doc from java.lang.Object.clone.

a clone of this instance.

Annotations
@Override
equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

  • It is reflexive: for any non-null reference value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
  • For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
obj:Object

the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getAttributeback to summary
public String getAttribute(String name)

Obtain the value for a given attribute. Values returned from this method must be consistent with the values set and returned by the attribute specific getters and setters in this class.

Parameters
name:String

Name of attribute to return

Returns:String

Value of specified attribute

Since
Servlet 6.0
getAttributesback to summary
public Map<String, String> getAttributes()

Obtain the Map of attributes and values (excluding version) for this cookie.

Returns:Map<String, String>

A read-only Map of attributes to values, excluding version.

Since
Servlet 6.0
getCommentback to summary
public String getComment()

Deprecated

for removal since Servlet 6.0.

This is no longer required with RFC 6265

With the adoption of support for RFC 6265, this method should no longer be used.

Returns:String

always null

Annotations
@Deprecated
since:Servlet 6.0
forRemoval:true
See Also
setComment
getDomainback to summary
public String getDomain()

Returns the domain name set for this cookie.

Returns:String

a String containing the domain name

See Also
setDomain
getMaxAgeback to summary
public int getMaxAge()

Returns the maximum age of the cookie, specified in seconds, By default, -1 indicating the cookie will persist until browser shutdown.

Returns:int

an integer specifying the maximum age of the cookie in seconds; if negative, means the cookie persists until browser shutdown

See Also
setMaxAge
getNameback to summary
public String getName()

Returns the name of the cookie. The name cannot be changed after creation.

Returns:String

a String specifying the cookie's name

getPathback to summary
public String getPath()

Returns the path on the server to which the browser returns this cookie. The cookie is visible to all subpaths on the server.

Returns:String

a String specifying a path that contains a servlet name, for example, /catalog

See Also
setPath
getSecureback to summary
public boolean getSecure()

Returns true if the browser is sending cookies only over a secure protocol, or false if the browser can send cookies using any protocol.

Returns:boolean

true if the browser uses a secure protocol; otherwise, false

See Also
setSecure
getValueback to summary
public String getValue()

Returns the value of the cookie.

Returns:String

a String containing the cookie's present value

See Also
setValue, Cookie
getVersionback to summary
public int getVersion()

Deprecated

for removal since Servlet 6.0.

This is no longer required with RFC 6265

With the adoption of support for RFC 6265, this method should no longer be used.

Returns:int

Always zero

Annotations
@Deprecated
since:Servlet 6.0
forRemoval:true
See Also
setVersion
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
isHttpOnlyback to summary
public boolean isHttpOnly()

Gets the flag that controls if this cookie will be hidden from scripts on the client side.

Returns:boolean

true if the cookie is hidden from scripts, else false

Since
Servlet 3.0
setAttributeback to summary
public void setAttribute(String name, String value)

Sets the value for the given cookie attribute. When a value is set via this method, the value returned by the attribute specific getter (if any) must be consistent with the value set via this method.

Parameters
name:String

Name of attribute to set

value:String

Value of attribute

Exceptions
IllegalArgumentException:
If the attribute name is null or contains any characters not permitted for use in Cookie names.
NumberFormatException:
If the attribute is known to be numerical but the provided value cannot be parsed to a number.
Since
Servlet 6.0
setAttributeInternalback to summary
private void setAttributeInternal(String name, String value)
setCommentback to summary
public void setComment(String purpose)

Deprecated

for removal since Servlet 6.0.

This is no longer required with RFC 6265

If called, this method has no effect.

Parameters
purpose:String

ignored

Annotations
@Deprecated
since:Servlet 6.0
forRemoval:true
See Also
getComment
setDomainback to summary
public void setDomain(String pattern)

Specifies the domain within which this cookie should be presented.

By default, cookies are only returned to the server that sent them.

Parameters
pattern:String

a String containing the domain name within which this cookie is visible

See Also
getDomain
setHttpOnlyback to summary
public void setHttpOnly(boolean httpOnly)

Sets the flag that controls if this cookie will be hidden from scripts on the client side.

Parameters
httpOnly:boolean

The new value of the flag

Since
Servlet 3.0
setMaxAgeback to summary
public void setMaxAge(int expiry)

Sets the maximum age of the cookie in seconds.

A positive value indicates that the cookie will expire after that many seconds have passed. Note that the value is the maximum age when the cookie will expire, not the cookie's current age.

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.

Parameters
expiry:int

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 Also
getMaxAge
setPathback to summary
public void setPath(String uri)

Specifies a path for the cookie to which the client should return the cookie.

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, /catalog, which makes the cookie visible to all directories on the server under /catalog.

Parameters
uri:String

a String specifying a path

See Also
getPath
setSecureback to summary
public void setSecure(boolean flag)

Indicates to the browser whether the cookie should only be sent using a secure protocol, such as HTTPS or SSL.

The default value is false.

Parameters
flag:boolean

if true, sends the cookie from the browser to the server only when using a secure protocol; if false, sent on any protocol

See Also
getSecure
setValueback to summary
public void setValue(String newValue)

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.

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.

Parameters
newValue:String

a String specifying the new value

See Also
getValue, Cookie
setVersionback to summary
public void setVersion(int v)

Deprecated

for removal since Servlet 6.0.

This is no longer required with RFC 6265

If called, this method has no effect.

Parameters
v:int

Ignored

Annotations
@Deprecated
since:Servlet 6.0
forRemoval:true
See Also
getVersion