org.apache.commons.httpclient.cookie
Interface CookieSpec

All Known Implementing Classes:
CookieSpecBase, IgnoreCookiesSpec, NetscapeDraftSpec, RFC2109Spec, RFC2965Spec

public interface CookieSpec

Defines the cookie management specification.

Cookie management specification must define

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

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 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,
               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

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

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

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

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

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)
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

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

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

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


Copyright © 2001-2008 Apache Software Foundation. All Rights Reserved.