gov.llnl.babel.url.cookie

Class Cookie

java.lang.Object

gov.llnl.babel.url.cookie.Cookie

All Implemented Interfaces:

java.io.Serializable

public class Cookie
extends java.lang.Object
implements java.io.Serializable

Some WWW servers will not work unless the user agent stores and returns cookies. The is part of a package to manage cookies for a Java WWW user agent. The Java user agent might be a browser, or it might be an automated URL checker (the original application area). Whatever the case may be, this class stores all the attributes of a Cookie. This implementation is based on the HTTP Working Group INTERNET DRAFT titled "HTTP State Management Mechanism" dated August 27, 1999. By design, this class does not trust its client that much. It checks to make sure that names and values are legal according to the HTTP/1.1 specification (RFC 2616).

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
Cookie(java.lang.String name, java.lang.String value) The basic cookie constructor (or should I say cutter?).

Method Summary

Methods

Modifier and Type	Method and Description
static java.lang.String	decodeValue(java.lang.String value) Unquote special characters in value.
static java.lang.String	effectiveHostname(java.lang.String hostname) Return the effective host name of a host name.
static java.lang.String	encodeValue(java.lang.String value) Quote special characters in value.
boolean	equals(Cookie c) Return true if two cookies are equal.
java.lang.String	getComment() Return the comment attribute of the cookie.
java.lang.String	getDomain() Return the domain of this cookie.
java.util.Date	getExpiration() Return the expiration date of the cookie.
int	getMaxAge() Return the maximum age attribute for the cookie.
java.lang.String	getName() Return the name of the cookie.
java.lang.String	getPath() Return the path attribute of the cookie.
java.lang.String	getPorts() Return the ports that the cookie is for.
java.lang.String	getUrlComment() Return the URL comment attribute of the cookie.
java.lang.String	getValue() Return the value of the cookie.
java.lang.String	getVersion() Return the cookie specification version number.
boolean	hasExpired(long currentTime) Check if the cookie has expired.
boolean	hasValidDomain(java.lang.String hostname) Check whether the domain name can be used by a particular host.
boolean	isDiscardable() Indicate whether the cookie should be discarded when the user agent exits.
boolean	isPortAllowed(int port) Return true iff port is allowed to send/receive this cookie.
boolean	isRelevant(java.lang.String hostname, java.lang.String path, int port) Check if the cookie should be sent with a particular request.
boolean	isSecure() Indicate whether the cookie is intended for secure connections only.
void	setComment(java.lang.String comment) Change the comment attribute of the cookie.
void	setDiscardable(boolean discard) Conditionally set the discard attribute of the cookie.
void	setDomain(java.lang.String domain) Set the domain of the request.
void	setMaxAge(int maxAge, java.util.Date created) Set the maximum age and expiration date of the cookie.
void	setPath(java.lang.String path) Set the path.
void	setPorts(java.lang.String ports) Set the ports that are allowed to get the cookie.
void	setSecure(boolean secure) Conditionally set the secure attribute of the cookie.
void	setUrlComment(java.lang.String comment) Change the URL comment attribute of the cookie.
void	setValue(java.lang.String value) Change the value of the cookie.
void	setVersion(java.lang.String version) Set the version of the cookie protocol.
java.lang.String	toString() Create a string suitable for including in a HTTP "Cookie:" header.
static boolean	validPortList(java.lang.String ports) Returns true iff the port list is a valid list of comma separated integers.
static boolean	validToken(java.lang.String tok) Check if tok is a valid token as defined by the HTTP/1.1 spec.
static boolean	validValue(java.lang.String value) Return true if the string is valid as a cookie attribute value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Cookie

public Cookie(java.lang.String name,
      java.lang.String value)
       throws CookieCrumbleException

The basic cookie constructor (or should I say cutter?).

Parameters:

name - The cookie's name. This should be a sequence of non-special, non-whitespace characters (according to the spec.

value - The cookie's value. This should be encoded as it does into a HTTP/1.1 header.

Throws:

CookieCrumbleException - indicates that name or value is illegal.

Method Detail

encodeValue

public static java.lang.String encodeValue(java.lang.String value)

Quote special characters in value. When you're putting certain value fields into a HTTP/1.1 header, the double quote and backslash characters must be quoted with a backslash.

Parameters:

value - a string of text.

Returns:

value with any " or \ characters encoded.

decodeValue

public static java.lang.String decodeValue(java.lang.String value)

Unquote special characters in value. When you take a value field from a HTTP/1.1 header, you must remove the backslash quoting to get the real value.

Parameters:

value - a string of text.

Returns:

value with any " or \ characters encoded.

validToken

public static boolean validToken(java.lang.String tok)

Check if tok is a valid token as defined by the HTTP/1.1 spec.

Parameters:

tok - a string that may or may not be a valid token.

Returns:

true means tok is a valid HTTP/1.1 token; false means tok is not a valid token.

validValue

public static boolean validValue(java.lang.String value)

Return true if the string is valid as a cookie attribute value. Specifically, this returns true if value satisfies the definition for TEXT in RFC 2616 (the HTTP/1.1 spec).

Returns:

true means that the attribute value is acceptable.

validPortList

public static boolean validPortList(java.lang.String ports)

Returns true iff the port list is a valid list of comma separated integers.

Returns:

true means that the attribute value is acceptable.

effectiveHostname

public static java.lang.String effectiveHostname(java.lang.String hostname)

Return the effective host name of a host name. If hostname doesn't have any periods in it, ".local" is appended.

Parameters:

hostname - the original host name

Returns:

if hostname doesn't have any periods in it, hostname with ".local" appended is returned; otherwise, hostname is return unmodified.

getName

public java.lang.String getName()

Return the name of the cookie.

Returns:

the name of the cookie

getValue

public java.lang.String getValue()

Return the value of the cookie.

Returns:

value of the cookie

getComment

public java.lang.String getComment()

Return the comment attribute of the cookie. Note this may be null indicating that the cookie contains no comment.

Returns:

null or a valid string containing the comment attribute.

getUrlComment

public java.lang.String getUrlComment()

Return the URL comment attribute of the cookie. Note this may be null indicating that the cookie contains no URL comment.

Returns:

null or a valid string containing the URL comment attribute.

getDomain

public java.lang.String getDomain()

Return the domain of this cookie.

Returns:

The domain of this cookie. If the client doesn't provide the domain, this will be null.

getMaxAge

public int getMaxAge()

Return the maximum age attribute for the cookie. A negative return value indicates that the cookie has no maximum age setting. A non-negative value is the maximum age in seconds from when it was created.

Returns:

the maximum age attribute of the cookie or a negative value (indicates no maximum age setting). This attribute is not useful unless you know when the cookie began.

getExpiration

public java.util.Date getExpiration()

Return the expiration date of the cookie. If the cookie has a maximum age attribute, it should have an expiration date based on the cookie's creation time and maximum age attribute.

Returns:

null if no maximum age setting; otherwise, the date and time that the cookie should cease to exist.

getPath

public java.lang.String getPath()

Return the path attribute of the cookie.

Returns:

a path on a particular server.

getPorts

public java.lang.String getPorts()

Return the ports that the cookie is for.

Returns:

null (means no restriction on ports) or a comma separated list of ports.

isSecure

public boolean isSecure()

Indicate whether the cookie is intended for secure connections only.

Returns:

true means the cookie should only be sent on a secure channel; false means the cookie can be sent on secure on unsecured channels.

isDiscardable

public boolean isDiscardable()

Indicate whether the cookie should be discarded when the user agent exits.

Returns:

true means that the cookie should be discarded when the user agent exits; false means that the cookie should be persisted until it expires.

getVersion

public java.lang.String getVersion()

Return the cookie specification version number.

Returns:

null if the client hasn't specified the cookie specification version; otherwise a string holding the cookie spec. version.

hasValidDomain

public boolean hasValidDomain(java.lang.String hostname)

Check whether the domain name can be used by a particular host.

setValue

public void setValue(java.lang.String value)
              throws CookieCrumbleException

Change the value of the cookie.

Parameters:

value - This is the value of the cookie. If the value is coming from an incomming HTTP/1.1 header, it should be run through decodeValue before passing it into here.

Throws:

CookieCrumbleException - indicates that the value is not legal

setComment

public void setComment(java.lang.String comment)
                throws CookieCrumbleException

Change the comment attribute of the cookie. The specification requires the comment to be UTF-8 encoded.

Parameters:

comment - This is the cookie's comment. If the comment is coming from an incomming HTTP/1.1 header, it should be run through decodeValue before passing it into here.

Throws:

CookieCrumbleException - indicates that the comment is not a legal value

setUrlComment

public void setUrlComment(java.lang.String comment)
                   throws CookieCrumbleException

Change the URL comment attribute of the cookie.

Parameters:

comment - This is the cookie's URL comment. If the comment is coming from an incomming HTTP/1.1 header, it should be run through decodeValue before passing it into here.

Throws:

CookieCrumbleException - The URL is not valid.

setDomain

public void setDomain(java.lang.String domain)
               throws CookieCrumbleException

Set the domain of the request. This limits which machines will be sent the cookie.

Parameters:

domain - this should be a domain name, a hostname or .local.

Throws:

CookieCrumbleException - indicates that the domain is not acceptable

setMaxAge

public void setMaxAge(int maxAge,
             java.util.Date created)
               throws CookieCrumbleException

Set the maximum age and expiration date of the cookie.

Parameters:

maxAge - a non-negative integer value indicating the maximum age in seconds

created - best estimate of when the cookie was created

Throws:

CookieCrumbleException - indicates that maxAge or created was invalid

setPath

public void setPath(java.lang.String path)
             throws CookieCrumbleException

Set the path.

Parameters:

path - the leading elements of a URL path that limits the scope of the cookie

Throws:

CookieCrumbleException - indicates that the path is invalid

setPorts

public void setPorts(java.lang.String ports)
              throws CookieCrumbleException

Set the ports that are allowed to get the cookie.

Parameters:

ports - a list of ports that are allowed to send/receive the cookie.

Throws:

CookieCrumbleException - indicates that the path is invalid

setSecure

public void setSecure(boolean secure)

Conditionally set the secure attribute of the cookie.

Parameters:

secure - true will make the cookie require a secure channel; false will allow the cookie to be communicated via unsecure channels.

setDiscardable

public void setDiscardable(boolean discard)

Conditionally set the discard attribute of the cookie.

Parameters:

discard - true will mark the cookie to be discarded while the user agent exits; false will mark the cookie to be persisted by its environment.

setVersion

public void setVersion(java.lang.String version)

Set the version of the cookie protocol.

Parameters:

version - Set the version of the protocol used by this cookie.

hasExpired

public boolean hasExpired(long currentTime)

Check if the cookie has expired.

Parameters:

currentTime - use this as the current time in milliseconds since January 1, 1970.

Returns:

true means the cookie's expiration time has past; false means the cookie has not expired.

isPortAllowed

public boolean isPortAllowed(int port)

Return true iff port is allowed to send/receive this cookie.

Parameters:

port - the port whose access should be checked.

Returns:

true means that port may receive the cookie; false means port must not receive the cookie.

equals

public boolean equals(Cookie c)

Return true if two cookies are equal.

isRelevant

public boolean isRelevant(java.lang.String hostname,
                 java.lang.String path,
                 int port)

Check if the cookie should be sent with a particular request.

Parameters:

hostname - The hostname the sent or may receive the cookie.

path - The filename of the request.

port - The port number of the request.

Returns:

true means the cookie should be sent to the server; false means the cookie must not be sent to the server.

toString

public java.lang.String toString()

Create a string suitable for including in a HTTP "Cookie:" header. This assumes that the version has already been inserted.

Overrides:

toString in class java.lang.Object

Returns:

a string suitable to include in a "Cookie:" header