org.apache.commons.httpclient
Class Cookie

java.lang.Object
  |
  +--org.apache.commons.httpclient.NameValuePair
        |
        +--org.apache.commons.httpclient.Cookie

public class Cookie

extends NameValuePair

implements Serializable, Comparator

An HTTP "magic-cookie", as specified in RFC 2109.

Version:

$Revision: 1.38.2.1 $ $Date: 2003/07/07 19:11:00 $

Author:

B.C. Holmes, Park, Sung-Gu, Doug Sale, Rod Waldhoff, dIon Gillard, Sean C. Sullivan, John Evans, Marc A. Saegesser, Oleg Kalnichevski, Mike Bowler

See Also:

Serialized Form

Constructor Summary

Cookie()
Create a cookie.

Cookie(String domain, String name, String value)
Create a cookie.

Cookie(String domain, String name, String value, String path, Date expires, boolean secure)
Create a cookie.

Cookie(String domain, String name, String value, String path, int maxAge, boolean secure)
Create a cookie.

Method Summary

int	compare(Object o1, Object o2) Compares two cookies to determine order for cookie header.
static Header	createCookieHeader(String domain, int port, String path, boolean secure, Cookie[] cookies) Deprecated. use CookieSpec interface
static Header	createCookieHeader(String domain, int port, String path, boolean secure, Date now, Cookie[] cookies) Deprecated. use CookieSpec interface
static Header	createCookieHeader(String domain, String path, boolean secure, Cookie[] cookies) Deprecated. use CookieSpec interface
static Header	createCookieHeader(String domain, String path, Cookie[] cookies) Deprecated. use CookieSpec interface
boolean	equals(Object obj) Two cookies are equal if the name, path and domain match.
String	getComment() Returns the comment describing the purpose of this cookie, or null if no such comment has been defined.
String	getDomain() Returns my domain.
Date	getExpiryDate() Returns my expiration Date, or null if none exists.
String	getPath()
boolean	getSecure()
int	getVersion()
int	hashCode() Returns a hash code in keeping with the Object.hashCode() general hashCode contract.
boolean	isDomainAttributeSpecified() Returns true if cookie's domain was set via a Domain attribute in the set-cookie header.
boolean	isExpired() Return true if this cookie has expired.
boolean	isExpired(Date now) Return true if this cookie has expired according to the time passed in.
boolean	isPathAttributeSpecified() Returns true if cookie's path was set via a Path attribute in the set-cookie header.
boolean	isPersistent() Returns false if I should be discarded at the end of the "session"; true otherwise.
boolean	matches(String domain, int port, String path, boolean secure) Deprecated. use CookieSpec interface
boolean	matches(String domain, int port, String path, boolean secure, Date date) Deprecated. use CookieSpec interface
static Cookie[]	parse(String domain, int port, String path, boolean secure, Header setCookie) Deprecated. use CookieSpec interface
static Cookie[]	parse(String domain, int port, String path, Header setCookie) Deprecated. use CookieSpec interface
static Cookie[]	parse(String domain, String path, boolean secure, Header setCookie) Deprecated. use CookieSpec interface
static Cookie[]	parse(String domain, String path, Header setCookie) Deprecated. use CookieSpec interface
void	setComment(String comment) If a user agent (web browser) presents this cookie to a user, the cookie's purpose will be described using this comment.
void	setDomain(String domain) Sets my domain.
void	setDomainAttributeSpecified(boolean value) Indicates whether the cookie had a domain specified in a Domain attribute in the set-cookie header.
void	setExpiryDate(Date expiryDate) Expiration setter.
void	setPath(String path) Sets my path.
void	setPathAttributeSpecified(boolean value) Indicates whether the cookie had a path specified in a Path attribute in the set-cookie header.
void	setSecure(boolean secure) Set my secure flag.
void	setVersion(int version) Set the version of the HTTP cookie specification I report.
String	toExternalForm() Return a string suitable for sending in a Cookie header.
String	toString() Return a String representation of me.

Methods inherited from class org.apache.commons.httpclient.NameValuePair

getName, getValue, setName, setValue

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Cookie

public Cookie()

Create a cookie. Default constructor The new cookie is assigned

Cookie

public Cookie(String domain,
              String name,
              String value)

Create a cookie.

Parameters:

name - the cookie name

value - the cookie value

domain - the host this cookie will be sent to

Cookie

public Cookie(String domain,
              String name,
              String value,
              String path,
              Date expires,
              boolean secure)

Create a cookie.

Parameters:

name - the cookie name

value - the cookie value

domain - the host this cookie will be sent to

path - the path prefix for which this cookie will be sent

expires - the Date at which this cookie expires, or null if the cookie expires at the end of the session

secure - if true this cookie will only be sent over secure connections

Cookie

public Cookie(String domain,
              String name,
              String value,
              String path,
              int maxAge,
              boolean secure)

Create a cookie.

Parameters:

name - the cookie name

value - the cookie value

domain - the host this cookie will be sent to

path - the path prefix for which this cookie will be sent

maxAge - the number of seconds for which this cookie is valid. maxAge is expected to be a non-negative number. -1 signifies that the cookie should never expire.

secure - if true this cookie will only be sent over secure connections

Method Detail

getComment

public String getComment()

Returns the comment describing the purpose of this cookie, or null if no such comment has been defined.

See Also:

setComment(String)

setComment

public void setComment(String comment)

If a user agent (web browser) presents this cookie to a user, the cookie's purpose will be described using this comment.

See Also:

getComment()

getExpiryDate

public Date getExpiryDate()

Returns my expiration Date, or null if none exists.

Note: the object returned by this method is considered immutable. Changing it (e.g. using setTime()) could result in undefined behaviour. Do so at your peril.

Returns:

my expiration Date, or null.

See Also:

setExpiryDate(java.util.Date)

setExpiryDate

public void setExpiryDate(Date expiryDate)

Expiration setter.

Netscape's original proposal defined an Expires header that took a date value in a fixed-length variant format in place of Max-Age:
Wdy, DD-Mon-YY HH:MM:SS GMT
Note that the Expires date format contains embedded spaces, and that "old" cookies did not have quotes around values. Clients that implement to this specification should be aware of "old" cookies and Expires.

Note: the object returned by this method is considered immutable. Changing it (e.g. using setTime()) could result in undefined behaviour. Do so at your peril.

Parameters:

expiryDate - the Date after which this cookie is no longer valid.

See Also:

getExpiryDate()

isPersistent

public boolean isPersistent()

Returns false if I should be discarded at the end of the "session"; true otherwise.

Returns:

false if I should be discarded at the end of the "session"; true otherwise

getDomain

public String getDomain()

Returns my domain.

See Also:

setDomain(java.lang.String)

setDomain

public void setDomain(String domain)

Sets my domain.

I should be presented only to hosts satisfying this domain name pattern. Read RFC 2109 for specific details of the syntax. Briefly, a domain name name begins with a dot (".foo.com") and means that hosts in that DNS zone ("www.foo.com", but not "a.b.foo.com") should see the cookie. By default, cookies are only returned to the host which saved them.

See Also:

getDomain()

getPath

public String getPath()

Returns:

my path.

See Also:

setPath(java.lang.String)

setPath

public void setPath(String path)

Sets my path.

I should be presented only with requests beginning with this path. See RFC 2109 for a specification of the default behaviour. Basically, URLs in the same "directory" as the one which set the cookie, and in subdirectories, can all see the cookie unless a different path is set.

See Also:

getPath()

getSecure

public boolean getSecure()

Returns:

true if this cookie should only be sent over secure connections.

See Also:

setSecure(boolean)

setSecure

public void setSecure(boolean secure)

Set my secure flag.

When true the cookie should only be sent using a secure protocol (https). This should only be set when the cookie's originating server used a secure protocol to set the cookie's value.

See Also:

getSecure()

getVersion

public int getVersion()

Returns:

the version of the HTTP cookie specification that I use.

See Also:

setVersion(int)

setVersion

public void setVersion(int version)

Set the version of the HTTP cookie specification I report.

The current implementation only sends version 1 cookies. (See RFC 2109 for details.)

See Also:

getVersion()

isExpired

public boolean isExpired()

Return true if this cookie has expired.

Returns:

true if I have expired.

isExpired

public boolean isExpired(Date now)

Return true if this cookie has expired according to the time passed in.

Parameters:

now - The current time.

Returns:

true if I have expired.

setPathAttributeSpecified

public void setPathAttributeSpecified(boolean value)

Indicates whether the cookie had a path specified in a Path attribute in the set-cookie header. This value is important for generating the cookie header because RFC 2109 sec. 4.3.4 says that the cookie header should only include a $Path attribute if the cookie's path was specified in the set-cookie header.

Parameters:

value - True if the cookie's path came from a Path attribute.

See Also:

isPathAttributeSpecified()

isPathAttributeSpecified

public boolean isPathAttributeSpecified()

Returns true if cookie's path was set via a Path attribute in the set-cookie header.

Returns:

True if cookie's path was specified in the set-cookie header.

See Also:

setPathAttributeSpecified(boolean)

setDomainAttributeSpecified

public void setDomainAttributeSpecified(boolean value)

Indicates whether the cookie had a domain specified in a Domain attribute in the set-cookie header. This value is important for generating the cookie header because RFC 2109 sec. 4.3.4 says that the cookie header should only include a $Domain attribute if the cookie's domain was specified in the set-cookie header.

Parameters:

value - True if the cookie's domain came from a Domain attribute.

See Also:

isDomainAttributeSpecified()

isDomainAttributeSpecified

public boolean isDomainAttributeSpecified()

Returns true if cookie's domain was set via a Domain attribute in the set-cookie header.

Returns:

True if cookie's domain was specified in the set-cookie header.

See Also:

setDomainAttributeSpecified(boolean)

hashCode

public int hashCode()

Returns a hash code in keeping with the Object.hashCode() general hashCode contract.

Overrides:

hashCode in class NameValuePair

Returns:

A hash code

equals

public boolean equals(Object obj)

Two cookies are equal if the name, path and domain match.

Specified by:

equals in interface Comparator

Overrides:

equals in class NameValuePair

Parameters:

obj - The object to compare against.

Returns:

true if the two objects are equal.

toExternalForm

public String toExternalForm()

Return a string suitable for sending in a Cookie header.

Returns:

a string suitable for sending in a Cookie header.

matches

public boolean matches(String domain,
                       int port,
                       String path,
                       boolean secure,
                       Date date)

Deprecated. use CookieSpec interface

Return true if I should be submitted with a request with given attributes, false otherwise.

Parameters:

domain - the host to which the request is being submitted

port - the port to which the request is being submitted (currently ignored)

path - the path to which the request is being submitted

secure - true if the request is using the HTTPS protocol

date - the time at which the request is submitted

Returns:

true if the cookie matches

matches

public boolean matches(String domain,
                       int port,
                       String path,
                       boolean secure)

Deprecated. use CookieSpec interface

Return true if I should be submitted with a request with given attributes, false otherwise.

Parameters:

domain - the host to which the request is being submitted

port - the port to which the request is being submitted (currently ignored)

path - the path to which the request is being submitted

secure - True if this cookie has the secure flag set

Returns:

true if I should be submitted as above.

createCookieHeader

public static Header createCookieHeader(String domain,
                                        String path,
                                        Cookie[] cookies)

Deprecated. use CookieSpec interface

Create a Cookie header containing all non-expired cookies in cookies, associated with the given domain and path, assuming the connection is not secure.

If no cookies match, returns null.

Parameters:

domain - The domain

path - The path

cookies - The cookies to use

Returns:

The new header.

createCookieHeader

public static Header createCookieHeader(String domain,
                                        String path,
                                        boolean secure,
                                        Cookie[] cookies)
                                 throws IllegalArgumentException

Deprecated. use CookieSpec interface

Create a Cookie header containing all non-expired cookies in cookies, associated with the given domain, path and https setting.

If no cookies match, returns null.

Parameters:

domain - The domain

path - The path

secure - True if this cookie has the secure flag set

cookies - The cookies to use.

Returns:

The new header

Throws:

IllegalArgumentException - if domain or path is null

createCookieHeader

public static Header createCookieHeader(String domain,
                                        int port,
                                        String path,
                                        boolean secure,
                                        Cookie[] cookies)
                                 throws IllegalArgumentException

Deprecated. use CookieSpec interface

Create a Cookie header containing all non-expired cookies in cookies, associated with the given domain, port, path and https setting.

If no cookies match, returns null.

Parameters:

domain - The domain

port - The port

path - The path

secure - True if this cookie has the secure flag set

cookies - The cookies to use.

Returns:

The new header

Throws:

IllegalArgumentException - if domain or path is null

createCookieHeader

public static Header createCookieHeader(String domain,
                                        int port,
                                        String path,
                                        boolean secure,
                                        Date now,
                                        Cookie[] cookies)
                                 throws IllegalArgumentException

Deprecated. use CookieSpec interface

Create a Cookie header containing all cookies in cookies, associated with the given domain, port, path and https setting, and which are not expired according to the given date.

If no cookies match, returns null.

Parameters:

domain - The domain

port - The port

path - The path

secure - True if this cookie has the secure flag set

now - The date to check for expiry

cookies - The cookies to use.

Returns:

The new header

Throws:

IllegalArgumentException - if domain or path is null

compare

public int compare(Object o1,
                   Object o2)

Compares two cookies to determine order for cookie header.

Most specific should be first.

This method is implemented so a cookie can be used as a comparator for a SortedSet of cookies. Specifically it's used above in the createCookieHeader method.

The compare only compares the path of the cookie, see section 4.3.4 of RFC2109

Specified by:

compare in interface Comparator

Parameters:

o1 - The first object to be compared

o2 - The second object to be compared

Returns:

See Comparator.compare(Object,Object)

toString

public String toString()

Return a String representation of me.

Overrides:

toString in class NameValuePair

See Also:

toExternalForm()

parse

public static Cookie[] parse(String domain,
                             int port,
                             String path,
                             Header setCookie)
                      throws HttpException,
                             IllegalArgumentException

Deprecated. use CookieSpec interface

Parses the Set-Cookie Header into an array of Cookies, assuming that the cookies were recieved on an insecure channel.

Parameters:

domain - the domain from which the Header was received

port - the port from which the Header was received (currently ignored)

path - the path from which the Header was received

setCookie - the Set-Cookie Header received from the server

Returns:

an array of Cookies parsed from the Set-Cookie Header

Throws:

HttpException - if an exception occurs during parsing

IllegalArgumentException - if domain or path are null

parse

public static Cookie[] parse(String domain,
                             String path,
                             Header setCookie)
                      throws HttpException,
                             IllegalArgumentException

Deprecated. use CookieSpec interface

Parses the Set-Cookie Header into an array of Cookies, assuming that the cookies were recieved on an insecure channel.

Parameters:

domain - the domain from which the Header was received

path - the path from which the Header was received

setCookie - the Set-Cookie Header received from the server

Returns:

an array of Cookies parsed from the Set-Cookie Header

Throws:

HttpException - if an exception occurs during parsing

IllegalArgumentException - if domain or path are null

parse

public static Cookie[] parse(String domain,
                             String path,
                             boolean secure,
                             Header setCookie)
                      throws HttpException,
                             IllegalArgumentException

Deprecated. use CookieSpec interface

Parses the Set-Cookie Header into an array of Cookies.

Parameters:

domain - the domain from which the Header was received

path - the path from which the Header was received

secure - true when the header was recieved over a secure channel

setCookie - the Set-Cookie Header received from the server

Returns:

an array of Cookies parsed from the Set-Cookie Header

Throws:

HttpException - if an exception occurs during parsing

IllegalArgumentException - if domain or path are null

parse

public static Cookie[] parse(String domain,
                             int port,
                             String path,
                             boolean secure,
                             Header setCookie)
                      throws HttpException

Deprecated. use CookieSpec interface

Parses the Set-Cookie Header into an array of Cookies.

The syntax for the Set-Cookie response header is:

 set-cookie      =    "Set-Cookie:" cookies
 cookies         =    1#cookie
 cookie          =    NAME "=" VALUE * (";" cookie-av)
 NAME            =    attr
 VALUE           =    value
 cookie-av       =    "Comment" "=" value
                 |    "Domain" "=" value
                 |    "Max-Age" "=" value
                 |    "Path" "=" value
                 |    "Secure"
                 |    "Version" "=" 1*DIGIT
 

Parameters:

domain - the domain from which the Header was received

port - The port from which the Header was received.

path - the path from which the Header was received

secure - true when the Header was received over HTTPS

setCookie - the Set-Cookie Header received from the server

Returns:

an array of Cookies parsed from the Set-Cookie Header

Throws:

HttpException - if an exception occurs during parsing