There are 3 http cookie specifications: + *
There are 3 HTTP cookie specifications: *
* Netscape draft* - *
* RFC 2109 - @@ -50,25 +48,19 @@ * http://www.ietf.org/rfc/rfc2965.txt *
HttpCookie class can accept all these 3 forms of syntax. + *
HttpCookie class can accept all these 3 forms of syntax. * * @author Edward Wang * @since 1.6 */ public final class HttpCookie implements Cloneable { - /* ---------------- Fields -------------- */ + // ---------------- Fields -------------- - // // The value of the cookie itself. - // - - private String name; // NAME= ... "$Name" style is reserved + private final String name; // NAME= ... "$Name" style is reserved private String value; // value of NAME - // // Attributes encoded in the header's cookie fields. - // - private String comment; // Comment=VALUE ... describes cookie's use private String commentURL; // CommentURL="http URL" ... describes cookie's use private boolean toDiscard; // Discard ... discard cookie unconditionally @@ -80,70 +72,61 @@ private boolean httpOnly; // HttpOnly ... i.e. not accessible to scripts private int version = 1; // Version=1 ... RFC 2965 style - // // Hold the creation time (in seconds) of the http cookie for later // expiration calculation - // - private long whenCreated = 0; + private final long whenCreated; - - // // Since the positive and zero max-age have their meanings, // this value serves as a hint as 'not specify max-age' - // private final static long MAX_AGE_UNSPECIFIED = -1; - - // // date formats used by Netscape's cookie draft // as well as formats seen on various sites - // private final static String[] COOKIE_DATE_FORMATS = { "EEE',' dd-MMM-yyyy HH:mm:ss 'GMT'", "EEE',' dd MMM yyyy HH:mm:ss 'GMT'", "EEE MMM dd yyyy HH:mm:ss 'GMT'Z" }; - // // constant strings represent set-cookie header token - // private final static String SET_COOKIE = "set-cookie:"; private final static String SET_COOKIE2 = "set-cookie2:"; - - /* ---------------- Ctors -------------- */ + // ---------------- Ctors -------------- /** * Constructs a cookie with a specified name and value. * - *
The name must conform to RFC 2965. That means it can contain + *
The name must conform to RFC 2965. That means it can contain * only ASCII alphanumeric characters and cannot contain commas, * semicolons, or white space or begin with a $ character. The cookie's * name cannot be changed after creation. * - *
The value can be anything the server chooses to send. Its + *
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.
+ * {@code setValue} method.
*
- *
By default, cookies are created according to the RFC 2965 + *
By default, cookies are created according to the RFC 2965
* cookie specification. The version can be changed with the
- * The form of the domain name is specified by RFC 2965. A domain
- * name begins with a dot ( The form of the domain name is specified by RFC 2965. A domain
+ * name begins with a dot ({@code .foo.com}) and means that
* the cookie is visible to servers in a specified Domain Name System
- * (DNS) zone (for example, A positive value indicates that the cookie will expire
+ * 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.
+ * 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 zero, the cookie
- * should be discarded immediately;
- * otherwise, the cookie's max age is unspecified.
+ * @param expiry
+ * an integer specifying the maximum age of the cookie in seconds;
+ * if zero, the cookie should be discarded immediately; otherwise,
+ * the cookie's max age is unspecified.
*
- * @see #getMaxAge
- *
+ * @see #getMaxAge
*/
public void setMaxAge(long expiry) {
maxAge = expiry;
}
-
-
-
/**
- * Returns the maximum age of the cookie, specified in seconds.
- * By default, The cookie is visible to all the pages in the directory
+ * 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.
*
- * Consult RFC 2965 (available on the Internet) for more
+ * Consult RFC 2965 (available on the Internet) for more
* information on setting path names for cookies.
*
- *
- * @param uri a The default value is The default value is {@code false}.
*
- * @param flag If 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.
+ * 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 This concept is described in the cookie specification.
+ * This concept is described in the cookie specification.
* To understand the concept, some terminologies need to be defined first:
* Host A's name domain-matches host B's if:
* The result is true only if two cookies
- * come from same domain (case-insensitive),
- * have same name (case-insensitive),
- * and have same path (case-sensitive).
+ * The result is {@code true} only if two cookies come from same domain
+ * (case-insensitive), have same name (case-insensitive), and have same path
+ * (case-sensitive).
*
- * @return true if 2 http cookies equal to each other;
- * otherwise, false
+ * @return {@code true} if two HTTP cookies equal to each other;
+ * otherwise, {@code false}
*/
@Override
public boolean equals(Object obj) {
@@ -825,19 +702,17 @@
Objects.equals(getPath(), other.getPath());
}
-
/**
- * Return hash code of this http cookie. The result is the sum of
- * hash code value of three significant components of this cookie:
- * name, domain, and path.
- * That is, the hash code is the value of the expression:
+ * Returns the hash code of this HTTP cookie. The result is the sum of
+ * hash code value of three significant components of this cookie: name,
+ * domain, and path. That is, the hash code is the value of the expression:
* setVersion method.
+ * {@code setVersion} method.
*
*
- * @param name a String specifying the name of the cookie
+ * @param name
+ * a {@code String} specifying the name of the cookie
*
- * @param value a String specifying the value of the cookie
+ * @param value
+ * a {@code String} specifying the value of the cookie
*
- * @throws IllegalArgumentException if the cookie name contains illegal characters
- * or it is one of the tokens reserved for use
- * by the cookie protocol
- * @throws NullPointerException if name is null
+ * @throws IllegalArgumentException
+ * if the cookie name contains illegal characters or it is one of
+ * the tokens reserved for use by the cookie protocol
+ * @throws NullPointerException
+ * if {@code name} is {@code null}
+ *
* @see #setValue
* @see #setVersion
- *
*/
-
public HttpCookie(String name, String value) {
name = name.trim();
if (name.length() == 0 || !isToken(name) || isReserved(name)) {
@@ -159,23 +142,25 @@
portlist = null;
}
-
/**
* Constructs cookies from set-cookie or set-cookie2 header string.
* RFC 2965 section 3.2.2 set-cookie2 syntax indicates that one header line
* may contain more than one cookie definitions, so this is a static
* utility method instead of another constructor.
*
- * @param header a String specifying the set-cookie header.
- * The header should start with "set-cookie", or "set-cookie2"
- * token; or it should have no leading token at all.
- * @return a List of cookie parsed from header line string
- * @throws IllegalArgumentException if header string violates the cookie
- * specification's syntax, or the cookie
- * name contains llegal characters, or
- * the cookie name is one of the tokens
- * reserved for use by the cookie protocol
- * @throws NullPointerException if the header string is null
+ * @param header
+ * a {@code String} specifying the set-cookie header. The header
+ * should start with "set-cookie", or "set-cookie2" token; or it
+ * should have no leading token at all.
+ *
+ * @return a List of cookie parsed from header line string
+ *
+ * @throws IllegalArgumentException
+ * if header string violates the cookie specification's syntax, or
+ * the cookie name contains illegal characters, or the cookie name
+ * is one of the tokens reserved for use by the cookie protocol
+ * @throws NullPointerException
+ * if the header string is {@code null}
*/
public static ListString specifying the comment
- * to display to the user
+ * @param purpose
+ * a {@code String} specifying the comment to display to the user
*
- * @see #getComment
- *
+ * @see #getComment
*/
-
public void setComment(String purpose) {
comment = purpose;
}
-
-
-
/**
* Returns the comment describing the purpose of this cookie, or
- * null if the cookie has no comment.
- *
- * @return a String containing the comment,
- * or null if none
+ * {@code null} if the cookie has no comment.
*
- * @see #setComment
+ * @return a {@code String} containing the comment, or {@code null} if none
*
+ * @see #setComment
*/
-
public String getComment() {
return comment;
}
-
/**
- *
- * Specifies a comment url that describes a cookie's purpose.
- * The comment url is useful if the browser presents the cookie
- * to the user. Comment url is RFC 2965 only.
+ * Specifies a comment URL that describes a cookie's purpose.
+ * The comment URL is useful if the browser presents the cookie
+ * to the user. Comment URL is RFC 2965 only.
*
- * @param purpose a String specifying the comment url
- * to display to the user
+ * @param purpose
+ * a {@code String} specifying the comment URL to display to the user
*
- * @see #getCommentURL
- *
+ * @see #getCommentURL
*/
-
public void setCommentURL(String purpose) {
commentURL = purpose;
}
-
-
-
/**
- * Returns the comment url describing the purpose of this cookie, or
- * null if the cookie has no comment url.
+ * Returns the comment URL describing the purpose of this cookie, or
+ * {@code null} if the cookie has no comment URL.
*
- * @return a String containing the comment url,
- * or null if none
+ * @return a {@code String} containing the comment URL, or {@code null}
+ * if none
*
- * @see #setCommentURL
- *
+ * @see #setCommentURL
*/
-
public String getCommentURL() {
return commentURL;
}
-
/**
* Specify whether user agent should discard the cookie unconditionally.
* This is RFC 2965 only attribute.
*
- * @param discard true indicates to discard cookie unconditionally
+ * @param discard
+ * {@code true} indicates to discard cookie unconditionally
*
- * @see #getDiscard
+ * @see #getDiscard
*/
-
public void setDiscard(boolean discard) {
toDiscard = discard;
}
-
-
-
/**
- * Return the discard attribute of the cookie
+ * Returns the discard attribute of the cookie
*
- * @return a boolean to represent this cookie's discard attribute
+ * @return a {@code boolean} to represent this cookie's discard attribute
*
- * @see #setDiscard
+ * @see #setDiscard
*/
-
public boolean getDiscard() {
return toDiscard;
}
-
/**
* Specify the portlist of the cookie, which restricts the port(s)
* to which a cookie may be sent back in a Cookie header.
*
- * @param ports a String specify the port list, which is
- * comma seperated series of digits
- * @see #getPortlist
+ * @param ports
+ * a {@code String} specify the port list, which is comma separated
+ * series of digits
+ *
+ * @see #getPortlist
*/
-
public void setPortlist(String ports) {
portlist = ports;
}
-
-
-
/**
- * Return the port list attribute of the cookie
+ * Returns the port list attribute of the cookie
*
- * @return a String contains the port list
- * or null if none
- * @see #setPortlist
+ * @return a {@code String} contains the port list or {@code null} if none
+ *
+ * @see #setPortlist
*/
-
public String getPortlist() {
return portlist;
}
/**
- *
* Specifies the domain within which this cookie should be presented.
*
- * .foo.com) and means that
+ * www.foo.com, but not
- * a.b.foo.com). By default, cookies are only returned
+ * (DNS) zone (for example, {@code www.foo.com}, but not
+ * {@code a.b.foo.com}). By default, cookies are only returned
* to the server that sent them.
*
- *
- * @param pattern a String containing the domain name
- * within which this cookie is visible;
- * form is according to RFC 2965
+ * @param pattern
+ * a {@code String} containing the domain name within which this
+ * cookie is visible; form is according to RFC 2965
*
- * @see #getDomain
- *
+ * @see #getDomain
*/
-
public void setDomain(String pattern) {
if (pattern != null)
domain = pattern.toLowerCase();
@@ -396,261 +344,187 @@
domain = pattern;
}
-
-
-
-
/**
- * Returns the domain name set for this cookie. The form of
- * the domain name is set by RFC 2965.
- *
- * @return a String containing the domain name
+ * Returns the domain name set for this cookie. The form of the domain name
+ * is set by RFC 2965.
*
- * @see #setDomain
+ * @return a {@code String} containing the domain name
*
+ * @see #setDomain
*/
-
public String getDomain() {
return domain;
}
-
/**
* Sets the maximum age of the cookie in seconds.
*
- * -1 indicating the cookie will persist
- * until browser shutdown.
- *
+ * Returns the maximum age of the cookie, specified in seconds. By default,
+ * {@code -1} indicating the cookie will persist until browser shutdown.
*
- * @return an integer specifying the maximum age of the
- * cookie in seconds
- *
+ * @return an integer specifying the maximum age of the cookie in seconds
*
- * @see #setMaxAge
- *
+ * @see #setMaxAge
*/
-
public long getMaxAge() {
return maxAge;
}
-
-
-
/**
- * Specifies a path for the cookie
- * to which the client should return the cookie.
+ * Specifies a path for the cookie to which the client should return
+ * the cookie.
*
- * String specifying a path
- *
+ * @param uri
+ * a {@code String} specifying a path
*
- * @see #getPath
- *
+ * @see #getPath
*/
-
public void setPath(String uri) {
path = uri;
}
-
-
-
/**
- * Returns the path on the server
- * to which the browser returns this cookie. The
- * cookie is visible to all subpaths on the server.
+ * 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 String specifying a path that contains
- * a servlet name, for example, /catalog
+ * @return a {@code String} specifying a path that contains a servlet name,
+ * for example, /catalog
*
- * @see #setPath
- *
+ * @see #setPath
*/
-
public String getPath() {
return path;
}
-
-
-
-
/**
* Indicates whether the cookie should only be sent using a secure protocol,
* such as HTTPS or SSL.
*
- * false.
+ * true, the cookie can only be sent over
- * a secure protocol like https.
- * If false, it can be sent over any protocol.
+ * @param flag
+ * If {@code true}, the cookie can only be sent over a secure
+ * protocol like HTTPS. If {@code false}, it can be sent over
+ * any protocol.
*
- * @see #getSecure
- *
+ * @see #getSecure
*/
-
public void setSecure(boolean flag) {
secure = flag;
}
-
-
-
/**
- * Returns true if sending this cookie should be
- * restricted to a secure protocol, or false if the
- * it can be sent using any protocol.
+ * Returns {@code true} if sending this cookie should be restricted to a
+ * secure protocol, or {@code false} if the it can be sent using any
+ * protocol.
*
- * @return false if the cookie can be sent over
- * any standard protocol; otherwise, true
+ * @return {@code false} if the cookie can be sent over any standard
+ * protocol; otherwise, true
*
- * @see #setSecure
- *
+ * @see #setSecure
*/
-
public boolean getSecure() {
return secure;
}
-
-
-
-
/**
* Returns the name of the cookie. The name cannot be changed after
* creation.
*
- * @return a String specifying the cookie's name
- *
+ * @return a {@code String} specifying the cookie's name
*/
-
public String getName() {
return name;
}
-
-
-
-
/**
- *
* 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.
*
- * String specifying the new value
- *
+ * @param newValue
+ * a {@code String} specifying the new value
*
- * @see #getValue
- *
+ * @see #getValue
*/
-
public void setValue(String newValue) {
value = newValue;
}
-
-
-
/**
* Returns the value of the cookie.
*
- * @return a String containing the cookie's
- * present value
+ * @return a {@code String} containing the cookie's present value
*
- * @see #setValue
- *
+ * @see #setValue
*/
-
public String getValue() {
return value;
}
-
-
-
/**
- * Returns the version of the protocol this cookie complies
- * with. Version 1 complies with RFC 2965/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.
+ * Returns the version of the protocol this cookie complies with. Version 1
+ * complies with RFC 2965/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 2965/2109
+ * @return 0 if the cookie complies with the original Netscape
+ * specification; 1 if the cookie complies with RFC 2965/2109
*
- * @see #setVersion
- *
+ * @see #setVersion
*/
-
public int getVersion() {
return version;
}
-
-
-
/**
* 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 2965/2109.
*
- *
- * @param v 0 if the cookie should comply with
- * the original Netscape specification;
- * 1 if the cookie should comply with RFC 2965/2109
+ * @param v
+ * 0 if the cookie should comply with the original Netscape
+ * specification; 1 if the cookie should comply with RFC 2965/2109
*
- * @throws IllegalArgumentException if v is neither 0 nor 1
+ * @throws IllegalArgumentException
+ * if {@code v} is neither 0 nor 1
*
- * @see #getVersion
- *
+ * @see #getVersion
*/
-
public void setVersion(int v) {
if (v != 0 && v != 1) {
throw new IllegalArgumentException("cookie version should be 0 or 1");
@@ -664,11 +538,11 @@
* attribute. This means that the cookie should not be accessible to
* scripting engines, like javascript.
*
- * @return {@code true} if this cookie should be considered http only.
- * @see #setHttpOnly(boolean)
+ * @return {@code true} if this cookie should be considered HTTPOnly
+ *
+ * @see #setHttpOnly(boolean)
*/
- public boolean isHttpOnly()
- {
+ public boolean isHttpOnly() {
return httpOnly;
}
@@ -677,24 +551,25 @@
* {@code true} it means the cookie should not be accessible to scripting
* engines like javascript.
*
- * @param httpOnly if {@code true} make the cookie HTTP only, i.e.
- * only visible as part of an HTTP request.
- * @see #isHttpOnly()
+ * @param httpOnly
+ * if {@code true} make the cookie HTTP only, i.e. only visible as
+ * part of an HTTP request.
+ *
+ * @see #isHttpOnly()
*/
- public void setHttpOnly(boolean httpOnly)
- {
+ public void setHttpOnly(boolean httpOnly) {
this.httpOnly = httpOnly;
}
/**
- * The utility method to check whether a host name is in a domain
- * or not.
+ * The utility method to check whether a host name is in a domain or not.
*
- *
* effective host name = hostname if host name contains dot
*
- * or = hostname.local if not
+ *
+ * or = hostname.local if not
*
*
- * @param domain the domain name to check host name with
- * @param host the host name in question
- * @return true if they domain-matches; false if not
+ * @param domain
+ * the domain name to check host name with
+ *
+ * @param host
+ * the host name in question
+ *
+ * @return {@code true} if they domain-matches; {@code false} if not
*/
public static boolean domainMatches(String domain, String host) {
if (domain == null || host == null)
@@ -745,7 +624,8 @@
if (embeddedDotInDomain == 0)
embeddedDotInDomain = domain.indexOf('.', 1);
if (!isLocalDomain
- && (embeddedDotInDomain == -1 || embeddedDotInDomain == domain.length() - 1))
+ && (embeddedDotInDomain == -1 ||
+ embeddedDotInDomain == domain.length() - 1))
return false;
// if the host name contains no dot and the domain name
@@ -779,7 +659,6 @@
return false;
}
-
/**
* Constructs a cookie header string representation of this cookie,
* which is in the format defined by corresponding cookie specification,
@@ -796,17 +675,15 @@
}
}
-
/**
- * Test the equality of two http cookies.
+ * Test the equality of two HTTP cookies.
*
- *
@@ -731,9 +606,13 @@
* host is example.local, and example.local domain-matches .local.
*
* getName().toLowerCase().hashCode()
*
- * @return this http cookie's hash code
+ * @return this HTTP cookie's hash code
*/
@Override
public int hashCode() {
@@ -851,7 +726,7 @@
/**
* Create and return a copy of this object.
*
- * @return a clone of this http cookie
+ * @return a clone of this HTTP cookie
*/
@Override
public Object clone() {
@@ -862,8 +737,7 @@
}
}
-
- /* ---------------- Private operations -------------- */
+ // ---------------- Private operations --------------
// Note -- disabled for now to allow full Netscape compatibility
// from RFC 2068, token special case characters
@@ -872,15 +746,14 @@
private static final String tspecials = ",;";
/*
- * Tests a string and returns true if the string counts as a
- * token.
- *
- * @param value the
* + getDomain().toLowerCase().hashCode()
* + getPath().hashCode()
* String to be tested
+ * Tests a string and returns true if the string counts as a token.
*
- * @return true if the String is
- * a token; false if it is not
+ * @param value
+ * the {@code String} to be tested
+ *
+ * @return {@code true} if the {@code String} is a token;
+ * {@code false} if it is not
*/
-
private static boolean isToken(String value) {
int len = value.length();
@@ -893,11 +766,12 @@
return true;
}
-
/*
- * @param name the name to be tested
- * @return true if the name is reserved by cookie
- * specification, false if it is not
+ * @param name
+ * the name to be tested
+ *
+ * @return {@code true} if the name is reserved by cookie specification,
+ * {@code false} if it is not
*/
private static boolean isReserved(String name) {
if (name.equalsIgnoreCase("Comment")
@@ -919,16 +793,16 @@
return false;
}
-
/*
* Parse header string to cookie object.
*
- * @param header header string; should contain only one NAME=VALUE pair
+ * @param header
+ * header string; should contain only one NAME=VALUE pair
*
- * @return an HttpCookie being extracted
+ * @return an HttpCookie being extracted
*
- * @throws IllegalArgumentException if header string violates the cookie
- * specification
+ * @throws IllegalArgumentException
+ * if header string violates the cookie specification
*/
private static HttpCookie parseInternal(String header)
{
@@ -974,69 +848,97 @@
return cookie;
}
-
/*
* assign cookie attribute value to attribute name;
* use a map to simulate method dispatch
*/
static interface CookieAttributeAssignor {
- public void assign(HttpCookie cookie, String attrName, String attrValue);
+ public void assign(HttpCookie cookie,
+ String attrName,
+ String attrValue);
}
- static java.util.Map