public class Cookie extends Object
This class represents cookies in http responses; see HttpResponse.cookies().
This class is immutable.
Must be non-null and non-empty. Case sensitive.
Legal chars in cookie names:
a-z A-Z 0-9 ! # $ % & ' * + - . ^ _ ` | ~
Cookie names should be unique.
Although the full identity of a cookie is triplet {domain,path,name},
only the cookie name is sent back in http requests.
Therefor to avoid confusion, the server should not create two cookies with the same name
but different domain/path.
Must be non-null; can be empty. Case sensitive.
Legal chars in cookie values:
0x21-0x7E except " , ; \
If maxAge==null, this is a session cookie.
See also the sentinel value Cookie.SESSION.
If maxAge<=0, the client should delete the cookie immediately.
See also the sentinel value Cookie.DELETE.
If maxAge>0,
this is a persistent cookie which the client should store for the specified duration.
The precision is 1 second.
If domain==null, the cookie only applies to the request host.
For example, if the request is to "http://example.com:8080/xyz",
the response cookie only applies to future requests to example.com (not any subdomains of).
It's ok if the request host is an IP address.
The null domain is appropriate for many server apps.
If non-null, domain must be a valid domain name;
it must be the same as the request host, or a parent domain of the request host;
it cannot be a "public suffix"; it cannot be an IP address.
The cookie applies to future requests to the same domain or subdomains of.
For example, if the request is to "http://s1.example.com:8080/xyz",
these would be invalid response cookie domains:
"foo.com", ".com", "s2.example.com", ".example.com".
A valid response cookie domain would be "example.com",
in which case, the cookie applies to future requests to
"example.com", "s1.example.com", "s2.example.com", "a.b.c.example.com", etc.
The server port and the URI scheme(unless "secure=true") are irrelevant when matching a cookie with a request.
For example, if the request is to "http://example.com:8080",
the response cookie could be applicable to a future request to
"https://example.com:8433".
Domain is case insensitive; this class converts it to lower case.
We strongly recommend that apps always use "/" as the cookie path; then you don't need to read the following details.
If path==null, it's equivalent to the "default-path",
which is derived from the request URI. For example, if the request URI
is "/abc/xyz.html?q=p", the default-path for cookies is "/abc".
If non-null, path must be a valid URI path;
it must start with "/"; it must not contain ";" chars.
Path is case sensitive.
Trailing slash matters: "/abc" and "/abc/" are different cookie paths;
we recommend not to include any trailing slash.
The cookie applies to future requests that match the path (the request uri path is either the cookie path, or a sub-path of).
We strongly recommend that apps always use "/" as the cookie path, which matches all request URIs.
A boolean value.
If secure==true, the cookie only applies to HTTPS requests.
A boolean value.
| Modifier and Type | Field and Description |
|---|---|
static Duration |
SESSION
A sentinel value for cookie maxAge,
meaning the cookie is a session cookie.
|
static Duration |
DELETE
A sentinel value for cookie maxAge,
meaning the cookie should be deleted.
|
| Constructor and Description |
|---|
Cookie(String name,
String value,
Duration maxAge)
Create a cookie.
|
Cookie(String name,
String value,
Duration maxAge,
String domain,
String path,
boolean secure,
boolean httpOnly)
Create a cookie.
|
| Instance Methods | |
|---|---|
String |
name()
The name of the cookie.
|
String |
value()
The value of the cookie.
|
Duration |
maxAge()
The maxAge of the cookie.
|
String |
domain()
The domain of the cookie.
|
String |
path()
The path of the cookie.
|
boolean |
secure()
The secure property of the cookie.
|
boolean |
httpOnly()
The httpOnly property of the cookie.
|
String |
toSetCookieString()
Convert to string, as the cookie would appear in a Set-Cookie response header.
|
public String domain()
This method returns a lower case string, if domain!=null.
public boolean secure()
public boolean httpOnly()
public String toSetCookieString()
Example string:
name=value; Path=/; Expires=Fri, 21 Dec 2012 00:00:00 GMT; HttpOnly