gov.llnl.babel.url.cookie

Class Cookie

java.lang.Object
- gov.llnl.babel.url.cookie.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.

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.

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.

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.

Overview Package Tree Index Deprecated About
Prev Class \| Next Class	Frames \| No Frames
Summary: Nested \| Field \| Method \| Constr	Detail: Nested \| Field \| Method \| Constr