org.apache.commons.httpclient.cookie

Interface CookieSpec

All Known Implementing Classes:

CookieSpecBase, IgnoreCookiesSpec

public interface CookieSpec

Defines the cookie management specification.

Cookie management specification must define

• rules of parsing "Set-Cookie" header
• rules of validation of parsed cookies
• formatting of "Cookie" header

for a given host, port and path of origin

Since:

2.0

Author:

Oleg Kalnichevski, Jeff Dever

Field Summary

Fields

Modifier and Type	Field and Description
static String	PATH_DELIM Path delimiter
static char	PATH_DELIM_CHAR Path delimiting charachter

Method Summary

Methods

Modifier and Type	Method and Description
boolean	domainMatch(String host, String domain) Performs domain-match as defined by the cookie specification.
String	formatCookie(Cookie cookie) Create a "Cookie" header value for an array of cookies.
org.apache.commons.httpclient.Header	formatCookieHeader(Cookie cookie) Create a "Cookie" Header for single Cookie.
org.apache.commons.httpclient.Header	formatCookieHeader(Cookie[] cookies) Create a "Cookie" Header for an array of Cookies.
String	formatCookies(Cookie[] cookies) Create a "Cookie" header value for an array of cookies.
Collection<String>	getValidDateFormats() Returns the Collection of date patterns used for parsing.
boolean	match(String host, int port, String path, boolean secure, Cookie cookie) Determines if a Cookie matches a location.
Cookie[]	match(String host, int port, String path, boolean secure, Cookie[] cookies) Deprecated. use match(String, int, String, boolean, SortedMap) // END IA/HERITRIX CHANGES
Cookie[]	match(String domain, int port, String path, boolean secure, SortedMap<String,Cookie> cookiesMap) Determines which of an array of Cookies matches a location.
Cookie[]	parse(String host, int port, String path, boolean secure, org.apache.commons.httpclient.Header header) Parse the "Set-Cookie" Header into an array of Cookies.
Cookie[]	parse(String host, int port, String path, boolean secure, String header) Parse the "Set-Cookie" header value into Cookie array.
void	parseAttribute(org.apache.commons.httpclient.NameValuePair attribute, Cookie cookie) Parse the cookie attribute and update the corresponsing Cookie properties.
boolean	pathMatch(String path, String topmostPath) Performs path-match as defined by the cookie specification.
void	setValidDateFormats(Collection<String> datepatterns) Sets the Collection of date patterns used for parsing.
void	validate(String host, int port, String path, boolean secure, Cookie cookie) Validate the cookie according to validation rules defined by the cookie specification.

Field Detail

PATH_DELIM

static final String PATH_DELIM

Path delimiter

See Also:

Constant Field Values

PATH_DELIM_CHAR

static final char PATH_DELIM_CHAR

Path delimiting charachter

Method Detail

parse

Cookie[] parse(String host,
             int port,
             String path,
             boolean secure,
             String header)
               throws org.apache.commons.httpclient.cookie.MalformedCookieException,
                      IllegalArgumentException

Parse the "Set-Cookie" header value into Cookie array.

This method will not perform the validation of the resultant Cookies

Parameters:

host - the host which sent the Set-Cookie header

port - the port which sent the Set-Cookie header

path - the path which sent the Set-Cookie header

secure - true when the Set-Cookie header was received over secure conection

header - the Set-Cookie received from the server

Returns:

an array of Cookies parsed from the Set-Cookie value

Throws:

MalformedCookieException - if an exception occurs during parsing

IllegalArgumentException - if an input parameter is illegal

See Also:

validate(String, int, String, boolean, Cookie)

parse

Cookie[] parse(String host,
             int port,
             String path,
             boolean secure,
             org.apache.commons.httpclient.Header header)
               throws org.apache.commons.httpclient.cookie.MalformedCookieException,
                      IllegalArgumentException

Parse the "Set-Cookie" Header into an array of Cookies.

This method will not perform the validation of the resultant Cookies

Parameters:

host - the host which sent the Set-Cookie header

port - the port which sent the Set-Cookie header

path - the path which sent the Set-Cookie header

secure - true when the Set-Cookie header was received over secure conection

header - the Set-Cookie received from the server

Returns:

an array of Cookies parsed from the header

Throws:

MalformedCookieException - if an exception occurs during parsing

IllegalArgumentException - if an input parameter is illegal

See Also:

validate(String, int, String, boolean, Cookie)

parseAttribute

void parseAttribute(org.apache.commons.httpclient.NameValuePair attribute,
                  Cookie cookie)
                    throws org.apache.commons.httpclient.cookie.MalformedCookieException,
                           IllegalArgumentException

Parse the cookie attribute and update the corresponsing Cookie properties.

Parameters:

attribute - cookie attribute from the Set-Cookie

cookie - the to be updated

Throws:

MalformedCookieException - if an exception occurs during parsing

IllegalArgumentException - if an input parameter is illegal

validate

void validate(String host,
            int port,
            String path,
            boolean secure,
            Cookie cookie)
              throws org.apache.commons.httpclient.cookie.MalformedCookieException,
                     IllegalArgumentException

Validate the cookie according to validation rules defined by the cookie specification.

Parameters:

host - the host from which the Cookie was received

port - the port from which the Cookie was received

path - the path from which the Cookie was received

secure - true when the Cookie was received using a secure connection

cookie - the Cookie to validate

Throws:

MalformedCookieException - if the cookie is invalid

IllegalArgumentException - if an input parameter is illegal

setValidDateFormats

void setValidDateFormats(Collection<String> datepatterns)

Sets the Collection of date patterns used for parsing. The String patterns must be compatible with SimpleDateFormat.

Parameters:

datepatterns - collection of date patterns

getValidDateFormats

Collection<String> getValidDateFormats()

Returns the Collection of date patterns used for parsing. The String patterns are compatible with the SimpleDateFormat.

Returns:

collection of date patterns

match

boolean match(String host,
            int port,
            String path,
            boolean secure,
            Cookie cookie)

Determines if a Cookie matches a location.

Parameters:

host - the host to which the request is being submitted

port - the port to which the request is being submitted

path - the path to which the request is being submitted

secure - true if the request is using a secure connection

cookie - the Cookie to be matched

Returns:

true if the cookie should be submitted with a request with given attributes, false otherwise.

match

Cookie[] match(String host,
             int port,
             String path,
             boolean secure,
             Cookie[] cookies)

Deprecated. use match(String, int, String, boolean, SortedMap) // END IA/HERITRIX CHANGES

Determines which of an array of Cookies matches a location.

Parameters:

host - the host to which the request is being submitted

port - the port to which the request is being submitted (currenlty ignored)

path - the path to which the request is being submitted

secure - true if the request is using a secure protocol

cookies - an array of Cookies to be matched

Returns:

true if the cookie should be submitted with a request with given attributes, false otherwise. // BEGIN IA/HERITRIX CHANGES

match

Cookie[] match(String domain,
             int port,
             String path,
             boolean secure,
             SortedMap<String,Cookie> cookiesMap)

Determines which of an array of Cookies matches a location. If the SortedMap comes from an HttpState and is not itself thread-safe, it may be necessary to synchronize on the HttpState instance to protect against concurrent modification.

Parameters:

host - the host to which the request is being submitted

port - the port to which the request is being submitted (currently ignored)

path - the path to which the request is being submitted

secure - true if the request is using a secure protocol

cookies - SortedMap of Cookies to be matched

Returns:

true if the cookie should be submitted with a request with given attributes, false otherwise.

domainMatch

boolean domainMatch(String host,
                  String domain)

Performs domain-match as defined by the cookie specification.

Parameters:

host - The target host.

domain - The cookie domain attribute.

Returns:

true if the specified host matches the given domain.

Since:

3.0

pathMatch

boolean pathMatch(String path,
                String topmostPath)

Performs path-match as defined by the cookie specification.

Parameters:

path - The target path.

topmostPath - The cookie path attribute.

Returns:

true if the paths match

Since:

3.0

formatCookie

String formatCookie(Cookie cookie)

Create a "Cookie" header value for an array of cookies.

Parameters:

cookie - the cookie to be formatted as string

Returns:

a string suitable for sending in a "Cookie" header.

formatCookies

String formatCookies(Cookie[] cookies)
                     throws IllegalArgumentException

Create a "Cookie" header value for an array of cookies.

Parameters:

cookies - the Cookies to be formatted

Returns:

a string suitable for sending in a Cookie header.

Throws:

IllegalArgumentException - if an input parameter is illegal

formatCookieHeader

org.apache.commons.httpclient.Header formatCookieHeader(Cookie[] cookies)
                                                        throws IllegalArgumentException

Create a "Cookie" Header for an array of Cookies.

Parameters:

cookies - the Cookies format into a Cookie header

Returns:

a Header for the given Cookies.

Throws:

IllegalArgumentException - if an input parameter is illegal

formatCookieHeader

org.apache.commons.httpclient.Header formatCookieHeader(Cookie cookie)
                                                        throws IllegalArgumentException

Create a "Cookie" Header for single Cookie.

Parameters:

cookie - the Cookie format as a Cookie header

Returns:

a Cookie header.

Throws:

IllegalArgumentException - if an input parameter is illegal