public final class

HttpCookie

extends Object
implements Cloneable
java.lang.Object
   ↳ java.net.HttpCookie

Class Overview

An opaque key-value value pair held by an HTTP client to permit a stateful session with an HTTP server. This class parses cookie headers for all three commonly used HTTP cookie specifications:

  • The Netscape cookie spec is officially obsolete but widely used in practice. Each cookie contains one key-value pair and the following attributes: Domain, Expires, Path, and Secure. The version of cookies in this format is 0.

    There are no accessors for the Expires attribute. When parsed, expires attributes are assigned to the Max-Age attribute as an offset from now.

  • RFC 2109 formalizes the Netscape cookie spec. It replaces the Expires timestamp with a Max-Age duration and adds Comment and Version attributes. The version of cookies in this format is 1.
  • RFC 2965 refines RFC 2109. It adds Discard, Port, and CommentURL attributes and renames the header from Set-Cookie to Set-Cookie2. The version of cookies in this format is 1.

This implementation silently discards unrecognized attributes. In particular, the HttpOnly attribute is widely served but isn't in any of the above specs. It was introduced by Internet Explorer to prevent server cookies from being exposed in the DOM to JavaScript, etc.

Summary

Public Constructors
HttpCookie(String name, String value)
Creates a new cookie.
Public Methods
Object clone()
Creates and returns a copy of this Object.
static boolean domainMatches(String domainPattern, String host)
Returns true if host matches the domain pattern domain.
boolean equals(Object object)
Returns true if object is a cookie with the same domain, name and path.
String getComment()
Returns the Comment attribute.
String getCommentURL()
Returns the value of CommentURL attribute.
boolean getDiscard()
Returns the Discard attribute.
String getDomain()
Returns the Domain attribute.
long getMaxAge()
Returns the Max-Age attribute, in delta-seconds.
String getName()
Returns the name of this cookie.
String getPath()
Returns the Path attribute.
String getPortlist()
Returns the Port attribute, usually containing comma-separated port numbers.
boolean getSecure()
Returns the Secure attribute.
String getValue()
Returns the value of this cookie.
int getVersion()
Returns the version of this cookie.
boolean hasExpired()
Returns true if this cookie's Max-Age is 0.
int hashCode()
Returns the hash code of this HTTP cookie: 
   name.toLowerCase().hashCode()
       + (domain == null ? 0 : domain.toLowerCase().hashCode())
       + (path == null ? 0 : path.hashCode())
static List<HttpCookie> parse(String header)
Constructs a cookie from a string.
void setComment(String comment)
Set the Comment attribute of this cookie.
void setCommentURL(String commentURL)
Set the CommentURL attribute of this cookie.
void setDiscard(boolean discard)
Set the Discard attribute of this cookie.
void setDomain(String pattern)
Set the Domain attribute of this cookie.
void setMaxAge(long deltaSeconds)
Sets the Max-Age attribute of this cookie.
void setPath(String path)
Set the Path attribute of this cookie.
void setPortlist(String portList)
Set the Port attribute of this cookie.
void setSecure(boolean secure)
Sets the Secure attribute of this cookie.
void setValue(String value)
Sets the opaque value of this cookie.
void setVersion(int v)
Sets the Version attribute of the cookie.
String toString()
Returns a string representing this cookie in the format used by the Cookie header line in an HTTP request.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public HttpCookie (String name, String value)

Since: API Level 9

Creates a new cookie.

Parameters
name a non-empty string that contains only printable ASCII, no commas or semicolons, and is not prefixed with $. May not be an HTTP attribute name.
value an opaque value from the HTTP server.
Throws
IllegalArgumentException if name is invalid.

Public Methods

public Object clone ()

Since: API Level 9

Creates and returns a copy of this Object. The default implementation returns a so-called "shallow" copy: It creates a new instance of the same class and then copies the field values (including object references) from this instance to the new instance. A "deep" copy, in contrast, would also recursively clone nested objects. A subclass that needs to implement this kind of cloning should call super.clone() to create the new instance and then create deep copies of the nested, mutable objects.

Returns
  • a copy of this object.

public static boolean domainMatches (String domainPattern, String host)

Since: API Level 9

Returns true if host matches the domain pattern domain.

Parameters
domainPattern a host name (like android.com or localhost), or a pattern to match subdomains of a domain name (like .android.com). A special case pattern is .local, which matches all hosts without a TLD (like localhost).
host the host name or IP address from an HTTP request.

public boolean equals (Object object)

Since: API Level 9

Returns true if object is a cookie with the same domain, name and path. Domain and name use case-insensitive comparison; path uses a case-sensitive comparison.

Parameters
object the object to compare this instance with.
Returns
  • true if the specified object is equal to this Object; false otherwise.

public String getComment ()

Since: API Level 9

Returns the Comment attribute.

public String getCommentURL ()

Since: API Level 9

Returns the value of CommentURL attribute.

public boolean getDiscard ()

Since: API Level 9

Returns the Discard attribute.

public String getDomain ()

Since: API Level 9

Returns the Domain attribute.

public long getMaxAge ()

Since: API Level 9

Returns the Max-Age attribute, in delta-seconds.

public String getName ()

Since: API Level 9

Returns the name of this cookie.

public String getPath ()

Since: API Level 9

Returns the Path attribute. This cookie is visible to all subpaths.

public String getPortlist ()

Since: API Level 9

Returns the Port attribute, usually containing comma-separated port numbers. A null port indicates that the cookie may be sent to any port. The empty string indicates that the cookie should only be sent to the port of the originating request.

public boolean getSecure ()

Since: API Level 9

Returns the Secure attribute.

public String getValue ()

Since: API Level 9

Returns the value of this cookie.

public int getVersion ()

Since: API Level 9

Returns the version of this cookie.

public boolean hasExpired ()

Since: API Level 9

Returns true if this cookie's Max-Age is 0.

public int hashCode ()

Since: API Level 9

Returns the hash code of this HTTP cookie: 

   name.toLowerCase().hashCode()
       + (domain == null ? 0 : domain.toLowerCase().hashCode())
       + (path == null ? 0 : path.hashCode())

Returns
  • this object's hash code.

public static List<HttpCookie> parse (String header)

Since: API Level 9

Constructs a cookie from a string. The string should comply with set-cookie or set-cookie2 header format as specified in RFC 2965. Since set-cookies2 syntax allows more than one cookie definitions in one header, the returned object is a list.

Parameters
header a set-cookie or set-cookie2 header.
Returns
  • a list of constructed cookies
Throws
IllegalArgumentException if the string does not comply with cookie specification, or the cookie name contains illegal characters, or reserved tokens of cookie specification appears
NullPointerException if header is null

public void setComment (String comment)

Since: API Level 9

Set the Comment attribute of this cookie.

public void setCommentURL (String commentURL)

Since: API Level 9

Set the CommentURL attribute of this cookie.

public void setDiscard (boolean discard)

Since: API Level 9

Set the Discard attribute of this cookie.

public void setDomain (String pattern)

Since: API Level 9

Set the Domain attribute of this cookie. HTTP clients send cookies only to matching domains.

public void setMaxAge (long deltaSeconds)

Since: API Level 9

Sets the Max-Age attribute of this cookie.

public void setPath (String path)

Since: API Level 9

Set the Path attribute of this cookie. HTTP clients send cookies to this path and its subpaths.

public void setPortlist (String portList)

Since: API Level 9

Set the Port attribute of this cookie.

public void setSecure (boolean secure)

Since: API Level 9

Sets the Secure attribute of this cookie.

public void setValue (String value)

Since: API Level 9

Sets the opaque value of this cookie.

public void setVersion (int v)

Since: API Level 9

Sets the Version attribute of the cookie.

Throws
IllegalArgumentException if v is neither 0 nor 1

public String toString ()

Since: API Level 9

Returns a string representing this cookie in the format used by the Cookie header line in an HTTP request.

Returns
  • a printable representation of this object.