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

static String	PATH_DELIM Path delimiter
static char	PATH_DELIM_CHAR Path delimiting charachter

Method Summary

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.
Header	formatCookieHeader(Cookie cookie) Create a "Cookie" Header for single Cookie.
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	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) Determines which of an array of Cookies matches a location.
Cookie[]	parse(String host, int port, String path, boolean secure, 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(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 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

public static final String PATH_DELIM

Path delimiter

PATH_DELIM_CHAR

public static final char PATH_DELIM_CHAR

Path delimiting charachter

Method Detail

parse

public Cookie[] parse(String host,
                      int port,
                      String path,
                      boolean secure,
                      String header)
               throws 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

public Cookie[] parse(String host,
                      int port,
                      String path,
                      boolean secure,
                      Header header)
               throws 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

public void parseAttribute(NameValuePair attribute,
                           Cookie cookie)
                    throws 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

public void validate(String host,
                     int port,
                     String path,
                     boolean secure,
                     Cookie cookie)
              throws 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

public void setValidDateFormats(Collection 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

public Collection getValidDateFormats()

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

Returns:

collection of date patterns

match

public 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

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

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.

domainMatch

public 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

public 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

public 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

public 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

public 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

public 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