com.sonalb.net.http.cookie
Class RFC2965CookieParser

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

All Implemented Interfaces:

CookieParser

public class RFC2965CookieParser
extends java.lang.Object
implements CookieParser

Implementation for CookieParser that conforms to cookie specification RFC-2965.

Author:

Sonal Bansal

Constructor Summary

RFC2965CookieParser()

Method Summary

boolean	allowedCookie(Cookie c, java.net.URL url) Checks whether a request to the given URL is allowed to return the specified Cookie.
static boolean	domainMatch(java.net.URL url, java.lang.String domain) Performs "domain matching" of URL host/domain to cookie domain, for Version 1 cookies as specified by RFC 2965.
Header	getCookieHeaders(CookieJar cj) Converts the Cookies in the CookieJar to a set of headers suitable to be sent along with an HTTP request.
static boolean	isRFC2965CookieString(java.lang.String c) Determines whether a cookie string is for Version 0 or Version 1 cookie.
CookieJar	parseCookies(Header header, java.net.URL url) Converts the headers in an HTTP response into a CookieJar of Cookie objects.
static CookieJar	parseSetCookieV0(Header responseHeader, java.net.URL url, boolean bStrict) Parses headers into Version 1 Cookies.
static CookieJar	parseSetCookieV1(Header responseHeader, java.net.URL url, boolean bStrict) Parses headers into Version 1 Cookies.
static Cookie	parseSingleCookieV0(java.lang.String s, java.net.URL url, boolean bStrict) Converts a single cookie-string into a Cookie object, for Version 0
static Cookie	parseSingleCookieV1(java.lang.String s, java.net.URL url, boolean bStrict) Converts a single cookie-string into a Cookie object, for Version 1
static boolean	pathMatch(java.net.URL url, java.lang.String path) Performs "path matching" of URL to cookie path, as specified by RFC 2965.
static boolean	portMatch(java.net.URL url, java.lang.String portList) Performs "port matching" of URL to cookie portlist, for Version 1 cookies, as specified by RFC 2965.
boolean	sendCookieWithURL(Cookie c, java.net.URL url, boolean bRespectExpires) Determines whether a Cookie is eligible to be sent alongwith the request for a given URL.
static CookieJar	sortCookiesByPathSpecificity(CookieJar cj) Sorts the Cookies in the input CookieJar, with the cookie having most specific path attribute first.
static boolean	tailMatch(java.net.URL url, java.lang.String domain) Performs "tail matching" of URL host/domain to cookie domain, for Version 0 cookies as specified by Netscape's draft.
static java.lang.String	toCookieHeaderForm(Cookie c, boolean bIncludeVersion) Converts a single Cookie to a form suitable for sending with a request, back to the server.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RFC2965CookieParser

public RFC2965CookieParser()

Method Detail

getCookieHeaders

public Header getCookieHeaders(CookieJar cj)

Description copied from interface: CookieParser

Converts the Cookies in the CookieJar to a set of headers suitable to be sent along with an HTTP request.

Specified by:

getCookieHeaders in interface CookieParser

allowedCookie

public boolean allowedCookie(Cookie c,
                             java.net.URL url)

Description copied from interface: CookieParser

Checks whether a request to the given URL is allowed to return the specified Cookie.

Specified by:

allowedCookie in interface CookieParser

parseCookies

public CookieJar parseCookies(Header header,
                              java.net.URL url)
                       throws MalformedCookieException

Description copied from interface: CookieParser

Converts the headers in an HTTP response into a CookieJar of Cookie objects.

Specified by:

parseCookies in interface CookieParser

Throws:

MalformedCookieException

sendCookieWithURL

public boolean sendCookieWithURL(Cookie c,
                                 java.net.URL url,
                                 boolean bRespectExpires)

Determines whether a Cookie is eligible to be sent alongwith the request for a given URL. This method may or may not take into consideration the lifetime (indicated by cookie parameters). It discerns between Version 0 (Netscape) and Version 1 (RFC 2965) cookies. For Version 0 cookies, the relevant portion of Netscape's draft:

"When searching the cookie list for valid cookies, a comparison of the domain attributes of the cookie is made with the Internet domain name of the host from which the URL will be fetched. If there is a tail match, then the cookie will go through path matching to see if it should be sent."

For Version 1 cookies, the relevant portion of Netscape's draft:

"The user agent applies the following rules to choose applicable cookie-values to send in Cookie request headers from among all the cookies it has received.

Domain Selection
The origin server's effective host name MUST domain-match the Domain attribute of the cookie.

Port Selection
There are three possible behaviors, depending on the Port attribute in the Set-Cookie2 response header:

1. By default (no Port attribute), the cookie MAY be sent to any port.
2. If the attribute is present but has no value (e.g., Port), the cookie MUST only be sent to the request-port it was received from.
3. If the attribute has a port-list, the cookie MUST only be returned if the new request-port is one of those listed in port-list.

Path Selection
The request-URI MUST path-match the Path attribute of the cookie.

Max-Age Selection
Cookies that have expired should have been discarded and thus are not forwarded to an origin server."

Note: For both Versions 0 and 1 cookies, if the cookie is marked as "secure", it can be sent only over a secure transport. This implementation considers HTTPS and SHTTP protocols as secure.

Specified by:

sendCookieWithURL in interface CookieParser

Parameters:

c - the Cookie to be tested.

url - the URL for which to test.

bRespectExpires - whether or not to take expiry information into consideration.

Throws:

java.lang.IllegalArgumentException - Thrown if the input Cookie is not valid, that is, it is incomplete.

See Also:

pathMatch(java.net.URL, java.lang.String), tailMatch(java.net.URL, java.lang.String), domainMatch(java.net.URL, java.lang.String), portMatch(java.net.URL, java.lang.String), Cookie.hasExpired(), Cookie.isValid()

sortCookiesByPathSpecificity

public static CookieJar sortCookiesByPathSpecificity(CookieJar cj)

Sorts the Cookies in the input CookieJar, with the cookie having most specific path attribute first. This is used while determining the order in which cookies must be sent back to the server.

Note: The input CookieJar is NOT modified, instead, a new CookieJar is returned with the sorted Cookies.

Parameters:

cj - the CookieJar with the cookies to be sorted.

See Also:

CookieJar

pathMatch

public static boolean pathMatch(java.net.URL url,
                                java.lang.String path)

Performs "path matching" of URL to cookie path, as specified by RFC 2965. The URL's path is obtained by URL.getPath(). The relevant portion of RFC 2965 :

"For two strings that represent paths, P1 and P2, P1 path-matches P2 if P2 is a prefix of P1 (including the case where P1 and P2 string-compare equal). Thus, the string /tec/waldo path-matches /tec."

Parameters:

url - the URL which must be matched.

path - the cookie path.

Returns:

true if the URL path-matched the cookie path; false otherwise.

See Also:

URL

tailMatch

public static boolean tailMatch(java.net.URL url,
                                java.lang.String domain)

Performs "tail matching" of URL host/domain to cookie domain, for Version 0 cookies as specified by Netscape's draft. The URL's host is obtained by URL.getHost(). The relevant portion of Netscape's draft :

""Tail matching" means that domain attribute is matched against the tail of the fully qualified domain name of the host. A domain attribute of "acme.com" would match host names "anvil.acme.com" as well as "shipping.crate.acme.com".

Only hosts within the specified domain can set a cookie for a domain and domains must have at least two (2) or three (3) periods in them to prevent domains of the form: ".com", ".edu", and "va.us". Any domain that fails within one of the seven special top level domains listed below only require two periods. Any other domain requires at least three. The seven special top level domains are: "COM", "EDU", "NET", "ORG", "GOV", "MIL", and "INT"".

Parameters:

url - the URL which must be matched.

domain - the cookie domain.

Returns:

true if the URL tail-matched the cookie domain; false otherwise.

See Also:

URL

domainMatch

public static boolean domainMatch(java.net.URL url,
                                  java.lang.String domain)

Performs "domain matching" of URL host/domain to cookie domain, for Version 1 cookies as specified by RFC 2965. The URL's host is obtained by URL.getHost(). The relevant portion of RFC 2965 :

"Host names can be specified either as an IP address or a HDN [host domain name] string. Sometimes we compare one host name with another. (Such comparisons SHALL be case-insensitive.) Host A's name domain-matches host B's if

     *  their host name strings string-compare equal; or
     *  A is a HDN string and has the form NB, where N is a non-empty 
        name string, B has the form .B', and B' is a HDN string. 
        (So, x.y.com domain-matches .Y.com but not Y.com.)

Note that domain-match is not a commutative operation: a.b.c.com domain-matches .c.com, but not the reverse."

Parameters:

url - the URL which must be matched.

domain - the cookie domain.

Returns:

true if the URL domain-matched the cookie domain; false otherwise.

See Also:

URL

portMatch

public static final boolean portMatch(java.net.URL url,
                                      java.lang.String portList)

Performs "port matching" of URL to cookie portlist, for Version 1 cookies, as specified by RFC 2965. The given URL port-matches the given portlist, if the port returned by URL.getPort() exists in the portlist. The portlist itself is a comma-separated list of allowed ports for that cookie. If URL.getPort() returns a value less than 0, the default port of 80 is assumed.

Parameters:

url - the URL which must be matched.

portList - the comma-separated list of acceptable ports.

Returns:

true if the URL port exists in portList, or if portList is empty; false otherwise.

See Also:

URL

toCookieHeaderForm

public static java.lang.String toCookieHeaderForm(Cookie c,
                                                  boolean bIncludeVersion)

Converts a single Cookie to a form suitable for sending with a request, back to the server.

Parameters:

c - the Cookie to be converted

bIncludeVersion - whether the version number should be included

Returns:

the String representing the formatted Cookie

parseSetCookieV1

public static final CookieJar parseSetCookieV1(Header responseHeader,
                                               java.net.URL url,
                                               boolean bStrict)
                                        throws MalformedCookieException

Parses headers into Version 1 Cookies.

Throws:

MalformedCookieException

parseSetCookieV0

public static final CookieJar parseSetCookieV0(Header responseHeader,
                                               java.net.URL url,
                                               boolean bStrict)
                                        throws MalformedCookieException

Parses headers into Version 1 Cookies.

Throws:

MalformedCookieException

parseSingleCookieV0

public static Cookie parseSingleCookieV0(java.lang.String s,
                                         java.net.URL url,
                                         boolean bStrict)
                                  throws MalformedCookieException

Converts a single cookie-string into a Cookie object, for Version 0

Throws:

MalformedCookieException

parseSingleCookieV1

public static Cookie parseSingleCookieV1(java.lang.String s,
                                         java.net.URL url,
                                         boolean bStrict)
                                  throws MalformedCookieException

Converts a single cookie-string into a Cookie object, for Version 1

Throws:

MalformedCookieException

isRFC2965CookieString

public static boolean isRFC2965CookieString(java.lang.String c)
                                     throws MalformedCookieException

Determines whether a cookie string is for Version 0 or Version 1 cookie.

Throws:

MalformedCookieException