org.apache.commons.httpclient
Class Cookie

java.lang.Object
  |
  +--org.apache.commons.httpclient.NameValuePair
        |
        +--org.apache.commons.httpclient.Cookie
All Implemented Interfaces:
java.io.Serializable

public class Cookie
extends NameValuePair
implements java.io.Serializable

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

Version:
$Revision: 1.9 $ $Date: 2001/10/06 00:21:27 $
Author:
B.C. Holmes, Park, Sung-Gu, Doug Sale, Rod Waldhoff
See Also:
Serialized Form

Constructor Summary
Cookie(java.lang.String domain, java.lang.String name, java.lang.String value)
          Create a cookie.
Cookie(java.lang.String domain, java.lang.String name, java.lang.String value, java.lang.String path, java.util.Date expires, boolean secure)
          Create a cookie.
Cookie(java.lang.String domain, java.lang.String name, java.lang.String value, java.lang.String path, int maxAge, boolean secure)
          Create a cookie.
 
Method Summary
static Header createCookieHeader(java.lang.String domain, int port, java.lang.String path, boolean secure, Cookie[] cookies)
          Create a Cookie header containing all non-expired cookies in cookies, associated with the given domain, port, path and https setting.
static Header createCookieHeader(java.lang.String domain, int port, java.lang.String path, boolean secure, java.util.Date now, Cookie[] cookies)
          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.
static Header createCookieHeader(java.lang.String domain, java.lang.String path, boolean secure, Cookie[] cookies)
          Deprecated. use the version which includes port number and date
static Header createCookieHeader(java.lang.String domain, java.lang.String path, Cookie[] cookies)
          Create a Cookie header containing all non-expired cookies in cookies, associated with the given domain and path, assuming the connection is not secure.
 boolean equals(java.lang.Object obj)
          Two cookies are equal if the name, path and domain match.
 java.lang.String getComment()
          Returns the comment describing the purpose of this cookie, or null if no such comment has been defined.
 java.lang.String getDomain()
          Returns my domain.
 java.util.Date getExpiryDate()
          Returns my expiration Date, or null if none exists.
 java.lang.String getPath()
          Return my path.
 boolean getSecure()
          Return whether this cookie should only be sent over secure connections.
 int getVersion()
          Return the version of the HTTP cookie specification I use.
 int hashCode()
          Returns a hash code in keeping with the general hashCode contract.
 boolean isExpired()
          Return true if I have expired.
 boolean isExpired(java.util.Date now)
          Return true if I have expired.
 boolean isPersistent()
          Returns false if I should be discarded at the end of the "session"; true otherwise.
 boolean matches(java.lang.String domain, int port, java.lang.String path, boolean secure)
          Return true if I should be submitted with a request with given attributes, false otherwise.
 boolean matches(java.lang.String domain, int port, java.lang.String path, boolean secure, java.util.Date now)
          Return true if I should be submitted with a request with given attributes, false otherwise.
static Cookie[] parse(java.lang.String domain, int port, java.lang.String path, boolean secure, Header setCookie)
          Parses the Set-Cookie Header into an array of Cookies.
static Cookie[] parse(java.lang.String domain, int port, java.lang.String path, Header setCookie)
          Parses the Set-Cookie Header into an array of Cookies, assuming that the cookies were recieved on an insecure channel.
static Cookie[] parse(java.lang.String domain, java.lang.String path, boolean secure, Header setCookie)
          Parses the Set-Cookie Header into an array of Cookies.
static Cookie[] parse(java.lang.String domain, java.lang.String path, Header setCookie)
          Parses the Set-Cookie Header into an array of Cookies, assuming that the cookies were recieved on an insecure channel.
 void setComment(java.lang.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(java.lang.String domain)
          Sets my domain.
 void setExpiryDate(java.util.Date expiryDate)
          Expiration setter.
 void setPath(java.lang.String path)
          Sets my path.
 void setSecure(boolean secure)
          Set my secure flag.
 void setVersion(int version)
          Set the version of the HTTP cookie specification I report.
 java.lang.String toExternalForm()
          Return a string suitable for sending in a Cookie header.
 java.lang.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(java.lang.String domain,
              java.lang.String name,
              java.lang.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(java.lang.String domain,
              java.lang.String name,
              java.lang.String value,
              java.lang.String path,
              java.util.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(java.lang.String domain,
              java.lang.String name,
              java.lang.String value,
              java.lang.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
secure - if true this cookie will only be sent over secure connections
Method Detail

getComment

public java.lang.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(java.lang.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 java.util.Date getExpiryDate()
Returns my expiration Date, or null if none exists.
Returns:
my expiration Date, or null.

setExpiryDate

public void setExpiryDate(java.util.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.

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

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 java.lang.String getDomain()
Returns my domain.
See Also:
setDomain(java.lang.String)

setDomain

public void setDomain(java.lang.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 java.lang.String getPath()
Return my path.
See Also:
setPath(java.lang.String)

setPath

public void setPath(java.lang.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.


getSecure

public boolean getSecure()
Return whether 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()
Return the version of the HTTP cookie specification I use.

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.)


isExpired

public boolean isExpired()
Return true if I have expired.
Returns:
true if I have expired.

isExpired

public boolean isExpired(java.util.Date now)
Return true if I have expired.
Returns:
true if I have expired.

hashCode

public int hashCode()
Returns a hash code in keeping with the general hashCode contract.
Overrides:
hashCode in class NameValuePair

equals

public boolean equals(java.lang.Object obj)
Two cookies are equal if the name, path and domain match.
Overrides:
equals in class NameValuePair
Following copied from class: org.apache.commons.httpclient.NameValuePair
Parameters:
object - the Object to compare to

toExternalForm

public java.lang.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(java.lang.String domain,
                       int port,
                       java.lang.String path,
                       boolean secure,
                       java.util.Date now)
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 (currenlty 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

matches

public boolean matches(java.lang.String domain,
                       int port,
                       java.lang.String path,
                       boolean secure)
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 (currenlty ignored)
path - the path to which the request is being submitted

createCookieHeader

public static Header createCookieHeader(java.lang.String domain,
                                        java.lang.String path,
                                        Cookie[] cookies)
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.


createCookieHeader

public static Header createCookieHeader(java.lang.String domain,
                                        java.lang.String path,
                                        boolean secure,
                                        Cookie[] cookies)
Deprecated. use the version which includes port number and date

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.


createCookieHeader

public static Header createCookieHeader(java.lang.String domain,
                                        int port,
                                        java.lang.String path,
                                        boolean secure,
                                        Cookie[] cookies)
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.


createCookieHeader

public static Header createCookieHeader(java.lang.String domain,
                                        int port,
                                        java.lang.String path,
                                        boolean secure,
                                        java.util.Date now,
                                        Cookie[] cookies)
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.


toString

public java.lang.String toString()
Return a String representation of me.
Overrides:
toString in class NameValuePair
See Also:
toExternalForm()

parse

public static Cookie[] parse(java.lang.String domain,
                             int port,
                             java.lang.String path,
                             Header setCookie)
                      throws HttpException
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

parse

public static Cookie[] parse(java.lang.String domain,
                             java.lang.String path,
                             Header setCookie)
                      throws HttpException
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

parse

public static Cookie[] parse(java.lang.String domain,
                             java.lang.String path,
                             boolean secure,
                             Header setCookie)
                      throws HttpException
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

parse

public static Cookie[] parse(java.lang.String domain,
                             int port,
                             java.lang.String path,
                             boolean secure,
                             Header setCookie)
                      throws HttpException
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
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


Copyright (c) 2001 - Apache Software Foundation