com.sonalb.net.http.cookie
Class Cookie

java.lang.Object
  com.sonalb.net.http.cookie.Cookie

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

public class Cookie
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable, java.lang.Comparable

The data structure representing a cookie. Supports both Netscape (Version 0) and RFC2965 (Version 1) cookies. The fields common to both these versions are listed below:

• NAME - Must be set, no default value
• VALUE - Default value: Empty
• Domain - Must be set, default: Local
• Path - Must be set, default: / (root)
• Secure - Optional, default: false

Author:

Sonal Bansal

See Also:

Serialized Form

Constructor Summary

Cookie(java.lang.String name, java.lang.String value, java.lang.String domain, java.lang.String path)
Creates cookie instance.

Cookie(java.lang.String name, java.lang.String value, java.net.URL requestURL)
Creates cookie instance.

Method Summary

java.lang.Object	clone()
int	compareTo(java.lang.Object o) Compares one Cookie with another.
boolean	equals(java.lang.Object obj) Checks whether two cookies are equal.
java.lang.String	getComment() Gets the comment for this cookie.
java.net.URL	getCommentURL() Gets the comment URL for this cookie.
java.lang.String	getDomain() Gets the domain in which this cookie is valid.
java.util.Date	getExpires() Gets the date-time when this cookie expires.
int	getMaxAge() Gets the amount of time this Cookie is valid, measured in seconds from the time the value was set.
java.lang.String	getName() Gets the name of this cookie.
java.lang.String	getPath() Gets the path for this cookie.
java.lang.String	getPortList() Gets the list of ports to which this cookie can be sent.
java.lang.String	getValue() Gets the value of this cookie.
java.lang.String	getVersion() Gets the version of this Cookie.
boolean	hasExpired() Checks whether this cookie's lifetime has expired or not.
boolean	hasExpired(java.util.Date d) Checks whether this cookie's lifetime has expired or not.
boolean	isDiscardable() Checks whether this cookie can be discarded once the session is over.
boolean	isSecure() Checks whether this cookie will be sent over secure channels only.
void	setComment(java.lang.String comment) Sets the comment for this cookie.
void	setCommentURL(java.net.URL url) Sets the comment URL for this cookie.
void	setDiscard(boolean bDiscard) Sets the discard status of this cookie.
void	setDomain(java.lang.String domain) Sets the domain for this Cookie.
void	setDomain(java.net.URL requestURL) Sets the domain for this Cookie.
void	setExpires(java.util.Date expires) Sets the date-time when this cookie expires.
void	setMaxAge(int maxage) Sets the lifetime of this Cookie.
void	setMaxAge(int maxage, java.util.Date base) Sets the lifetime of this Cookie.
void	setName(java.lang.String name) Sets the Cookie name.
void	setPath(java.lang.String path) Sets the path for this Cookie.
void	setPath(java.net.URL requestURL) Sets the path for this Cookie.
void	setPort(int p) Sets the port to which this cookie can be sent.
void	setPort(java.net.URL url) Sets the port to which this cookie can be sent.
void	setPortList(int[] ports) Sets the list of ports to which this Cookie can be sent.
void	setSecure(boolean bSecure) Sets whether this cookie should be sent only over secure channels.
void	setValue(java.lang.String value) Sets the Cookie value.
void	setVersion(java.lang.String version) Sets the Cookie version.
java.lang.String	toString()

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Cookie

public Cookie(java.lang.String name,
              java.lang.String value,
              java.lang.String domain,
              java.lang.String path)

Creates cookie instance.

Parameters:

name - the Cookie name

value - the Cookie value

domain - the domain in which this Cookie is valid

path - the path for this Cookie

Cookie

public Cookie(java.lang.String name,
              java.lang.String value,
              java.net.URL requestURL)

Creates cookie instance. The path and domain are picked up from the request URL.

Parameters:

name - the Cookie name

value - the Cookie value

requestURL - the request URL which resulted in this cookie being received

Method Detail

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

compareTo

public int compareTo(java.lang.Object o)

Compares one Cookie with another. The natural ordering is such that it follows the path specificity rule laid down in RFC2695. Thus more specific path ("/acme/corp") comes before ("is less than") less specific path ("/acme").

Specified by:

compareTo in interface java.lang.Comparable

setName

public void setName(java.lang.String name)

Sets the Cookie name.

Parameters:

name - the Cookie name

setValue

public void setValue(java.lang.String value)

Sets the Cookie value.

Parameters:

value - the Cookie value

setMaxAge

public void setMaxAge(int maxage)

Sets the lifetime of this Cookie. Applicable only to Version 1 cookies.

Parameters:

maxage - the number of seconds from now that this Cookie is valid (delta-t)

Throws:

java.lang.UnsupportedOperationException - when called on a Version 0 cookie

setMaxAge

public void setMaxAge(int maxage,
                      java.util.Date base)

Sets the lifetime of this Cookie. Applicable only to Version 1 cookies.

Parameters:

maxage - the number of seconds from base that this Cookie is valid (delta-t)

base - the Date from which the delta-t should be counted

Throws:

java.lang.UnsupportedOperationException - when called on a Version 0 cookie

getMaxAge

public int getMaxAge()

Gets the amount of time this Cookie is valid, measured in seconds from the time the value was set. Applicable only to Version 0 cookies.

Returns:

the delta-t that this Cookie holds valid

Throws:

java.lang.UnsupportedOperationException - if this method is called on a Version 0 cookie

setExpires

public void setExpires(java.util.Date expires)

Sets the date-time when this cookie expires. Applicable only to Version 0 cookies.

Parameters:

expires - the Date when this cookie expires

Throws:

java.lang.UnsupportedOperationException - when called on a Version 1 cookie

setVersion

public void setVersion(java.lang.String version)

Sets the Cookie version. The version determines what fields and methods are valid for a Cookie instance. It also determines the format in which the Cookie is sent with a request.

Parameters:

version - the Cookie version. Either "0" or "1"

getVersion

public java.lang.String getVersion()

Gets the version of this Cookie.

Returns:

the version; either "0" or "1"

setPath

public void setPath(java.lang.String path)

Sets the path for this Cookie.

Parameters:

path - the Path for this Cookie

setPath

public void setPath(java.net.URL requestURL)

Sets the path for this Cookie. Path is extracted from the URL.

Parameters:

requestURL - the request URL which caused this Cookie to be sent.

setDomain

public void setDomain(java.lang.String domain)

Sets the domain for this Cookie. The domain determines which hosts can receive this Cookie.

Parameters:

domain - the Cookie domain

setDomain

public void setDomain(java.net.URL requestURL)

Sets the domain for this Cookie. The domain determines which hosts can receive this Cookie.

Parameters:

requestURL - the request URL which caused this cookie to be sent

setPortList

public void setPortList(int[] ports)

Sets the list of ports to which this Cookie can be sent. Applicable only to Version 1 cookies.

Parameters:

ports - the valid ports as array of int; non-positive values ignored

Throws:

UnsupportedException - when called on a Version 0 cookie

setPort

public void setPort(int p)

Sets the port to which this cookie can be sent. Applicable only to Version 1 cookies.

Parameters:

p - the Port

Throws:

java.lang.UnsupportedOperationException - when called on a Version 0 cookie

setPort

public void setPort(java.net.URL url)

Sets the port to which this cookie can be sent. Port is extracted from URL. Applicable only to Version 1 cookies.

Parameters:

url - the request URL

Throws:

java.lang.UnsupportedOperationException - when called on a Version 0 cookie

getPortList

public java.lang.String getPortList()

Gets the list of ports to which this cookie can be sent. Applicable only to Version 1 cookies.

Returns:

the comma-separated list of valid ports

Throws:

java.lang.UnsupportedOperationException - when called on a Version 0 cookie

setSecure

public void setSecure(boolean bSecure)

Sets whether this cookie should be sent only over secure channels.

Parameters:

bSecure - secure or not ?

getName

public java.lang.String getName()

Gets the name of this cookie.

Returns:

the cookie name

getValue

public java.lang.String getValue()

Gets the value of this cookie.

Returns:

the cookie value

getComment

public java.lang.String getComment()

Gets the comment for this cookie.

Returns:

the comment

setComment

public void setComment(java.lang.String comment)

Sets the comment for this cookie. Comment has no functional value.

Parameters:

comment - the comment

setCommentURL

public void setCommentURL(java.net.URL url)

Sets the comment URL for this cookie. URL has no functional value.

Parameters:

url - the URL

getCommentURL

public java.net.URL getCommentURL()

Gets the comment URL for this cookie.

Returns:

the comment URL

getExpires

public java.util.Date getExpires()

Gets the date-time when this cookie expires. Note that this can be called on both Version 0 AND Version 1 cookies.

Returns:

the date-time when this cookie expires

isDiscardable

public boolean isDiscardable()

Checks whether this cookie can be discarded once the session is over. This is different from the lifetime of the cookie.

Returns:

discardable or not ?

setDiscard

public void setDiscard(boolean bDiscard)

Sets the discard status of this cookie. This determines whether the cookie is valid after the session is over. It is different from lifetime. Applicable only to Version 1 cookies.

Parameters:

bDiscard - discardable or not ?

Throws:

java.lang.UnsupportedOperationException - when called on a Version 0 cookie

getDomain

public java.lang.String getDomain()

Gets the domain in which this cookie is valid.

Returns:

the domain

getPath

public java.lang.String getPath()

Gets the path for this cookie.

Returns:

the path

isSecure

public boolean isSecure()

Checks whether this cookie will be sent over secure channels only.

Returns:

secure or not ?

hasExpired

public boolean hasExpired()

Checks whether this cookie's lifetime has expired or not. The lifetime has expired if:

• The Max-Age (for Version 1 cookie) was explicitly set to 0
• The delta-t seconds set by Max-Age have passed
• The date-time now is greater than what was set to be the expiry date-time

The current system time is used for lifetime calculation.
If none of these conditions are satisfied, or if no explicit lifetime information was set the cookie is deemed to not have expired.

Returns:

expired or not ?

hasExpired

public boolean hasExpired(java.util.Date d)

Checks whether this cookie's lifetime has expired or not. The lifetime has expired if:

• The Max-Age (for Version 1 cookie) was explicitly set to 0
• The delta-t seconds set by Max-Age have passed
• The date-time as specified by the input is greater than what was set to be the expiry date-time

The input date-time is used for lifetime calculation.
If none of these conditions are satisfied, or if no explicit lifetime information was set the cookie is deemed to not have expired.

Returns:

expired or not ?

equals

public boolean equals(java.lang.Object obj)

Checks whether two cookies are equal. Two cookies are deemed to be equal, when all of the following conditions are satisfied:

• They have the same name
• They have the same domain
• They have the same path

Note that the cookie value is NOT used for equality determination.

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object