gov.llnl.babel.url.cookie

Class Cookie

Implemented Interfaces:
Serializable

public class Cookie
extends java.lang.Object
implements 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).

Constructor Summary

Cookie(String name, String value)
The basic cookie constructor (or should I say cutter?).

Method Summary

static String
decodeValue(String value)
Unquote special characters in value.
static String
effectiveHostname(String hostname)
Return the effective host name of a host name.
static String
encodeValue(String value)
Quote special characters in value.
boolean
equals(Cookie c)
Return true if two cookies are equal.
String
getComment()
Return the comment attribute of the cookie.
String
getDomain()
Return the domain of this cookie.
Date
getExpiration()
Return the expiration date of the cookie.
int
getMaxAge()
Return the maximum age attribute for the cookie.
String
getName()
Return the name of the cookie.
String
getPath()
Return the path attribute of the cookie.
String
getPorts()
Return the ports that the cookie is for.
String
getUrlComment()
Return the URL comment attribute of the cookie.
String
getValue()
Return the value of the cookie.
String
getVersion()
Return the cookie specification version number.
boolean
hasExpired(long currentTime)
Check if the cookie has expired.
boolean
hasValidDomain(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(String hostname, 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(String comment)
Change the comment attribute of the cookie.
void
setDiscardable(boolean discard)
Conditionally set the discard attribute of the cookie.
void
setDomain(String domain)
Set the domain of the request.
void
setMaxAge(int maxAge, Date created)
Set the maximum age and expiration date of the cookie.
void
setPath(String path)
Set the path.
void
setPorts(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(String comment)
Change the URL comment attribute of the cookie.
void
setValue(String value)
Change the value of the cookie.
void
setVersion(String version)
Set the version of the cookie protocol.
String
toString()
Create a string suitable for including in a HTTP "Cookie:" header.
static boolean
validPortList(String ports)
Returns true iff the port list is a valid list of comma separated integers.
static boolean
validToken(String tok)
Check if tok is a valid token as defined by the HTTP/1.1 spec.
static boolean
validValue(String value)
Return true if the string is valid as a cookie attribute value.

Constructor Details

Cookie

public Cookie(String name,
              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 Details

decodeValue

public static String decodeValue(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.

effectiveHostname

public static String effectiveHostname(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.

encodeValue

public static String encodeValue(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.

equals

public boolean equals(Cookie c)
Return true if two cookies are equal.

getComment

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

getDomain

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

getExpiration

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

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.

getName

public String getName()
Return the name of the cookie.
Returns:
the name of the cookie

getPath

public String getPath()
Return the path attribute of the cookie.
Returns:
a path on a particular server.

getPorts

public String getPorts()
Return the ports that the cookie is for.
Returns:
null (means no restriction on ports) or a comma separated list of ports.

getUrlComment

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

getValue

public String getValue()
Return the value of the cookie.
Returns:
value of the cookie

getVersion

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

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.

hasValidDomain

public boolean hasValidDomain(String hostname)
Check whether the domain name can be used by a particular host.

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.

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.

isRelevant

public boolean isRelevant(String hostname,
                          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.

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.

setComment

public void setComment(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

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.

setDomain

public void setDomain(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,
                      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(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(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.

setUrlComment

public void setUrlComment(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.

setValue

public void setValue(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

setVersion

public void setVersion(String version)
Set the version of the cookie protocol.
Parameters:
version - Set the version of the protocol used by this cookie.

toString

public String toString()
Create a string suitable for including in a HTTP "Cookie:" header. This assumes that the version has already been inserted.
Returns:
a string suitable to include in a "Cookie:" header

validPortList

public static boolean validPortList(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.

validToken

public static boolean validToken(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(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.