CookieSpec (HttpClient Library (Version 3.1))
Date: 2019-01-01

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

  - 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 java.lang.String` | `PATH_DELIM` Path delimiter
    `static char` | `PATH_DELIM_CHAR` Path delimiting charachter

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `domainMatch(java.lang.String host, java.lang.String domain)` Performs domain-match as defined by the cookie specification.
    `java.lang.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.
    `java.lang.String` | `formatCookies(Cookie[] cookies)` Create a `"Cookie"` header value for an array of cookies.
    `java.util.Collection` | `getValidDateFormats()` Returns the `Collection` of date patterns used for parsing.
    `boolean` | `match(java.lang.String host, int port, java.lang.String path, boolean secure, Cookie cookie)` Determines if a Cookie matches a location.
    `Cookie[]` | `match(java.lang.String host, int port, java.lang.String path, boolean secure, Cookie[] cookies)` Determines which of an array of Cookies matches a location.
    `Cookie[]` | `parse(java.lang.String host, int port, java.lang.String path, boolean secure, Header header)` Parse the `"Set-Cookie"` Header into an array of Cookies.
    `Cookie[]` | `parse(java.lang.String host, int port, java.lang.String path, boolean secure, java.lang.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(java.lang.String path, java.lang.String topmostPath)` Performs path-match as defined by the cookie specification.
    `void` | `setValidDateFormats(java.util.Collection datepatterns)` Sets the `Collection` of date patterns used for parsing.
    `void` | `validate(java.lang.String host, int port, java.lang.String path, boolean secure, Cookie cookie)` Validate the cookie according to validation rules defined by the cookie specification.

- - ### Field Detail

    - #### PATH_DELIM

          static final java.lang.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(java.lang.String host,
                         int port,
                         java.lang.String path,
                         boolean secure,
                         java.lang.String header)
                  throws MalformedCookieException,
                         java.lang.IllegalArgumentException

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

      This method will not perform the validation of the resultant `Cookie`s

      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 `Cookie`s parsed from the Set-Cookie value
      Throws:
        `MalformedCookieException` - if an exception occurs during parsing
        `java.lang.IllegalArgumentException` - if an input parameter is illegal
      See Also:
        `validate(String, int, String, boolean, Cookie)`

    - #### parse

          Cookie[] parse(java.lang.String host,
                         int port,
                         java.lang.String path,
                         boolean secure,
                         Header header)
                  throws MalformedCookieException,
                         java.lang.IllegalArgumentException

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

      This method will not perform the validation of the resultant `Cookie`s

      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 `Cookie`s parsed from the header
      Throws:
        `MalformedCookieException` - if an exception occurs during parsing
        `java.lang.IllegalArgumentException` - if an input parameter is illegal
      See Also:
        `validate(String, int, String, boolean, Cookie)`

    - #### parseAttribute

          void parseAttribute(NameValuePair attribute,
                              Cookie cookie)
                       throws MalformedCookieException,
                              java.lang.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
        `java.lang.IllegalArgumentException` - if an input parameter is illegal

    - #### validate

          void validate(java.lang.String host,
                        int port,
                        java.lang.String path,
                        boolean secure,
                        Cookie cookie)
                 throws MalformedCookieException,
                        java.lang.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
        `java.lang.IllegalArgumentException` - if an input parameter is illegal

    - #### setValidDateFormats

          void setValidDateFormats(java.util.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

          java.util.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(java.lang.String host,
                        int port,
                        java.lang.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(java.lang.String host,
                         int port,
                         java.lang.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 `Cookie`s to be matched
      Returns:
        `true` if the cookie should be submitted with a request with given attributes, `false` otherwise.

    - #### domainMatch

          boolean domainMatch(java.lang.String host,
                              java.lang.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(java.lang.String path,
                            java.lang.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

          java.lang.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

          java.lang.String formatCookies(Cookie[] cookies)
                                  throws java.lang.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:
        `java.lang.IllegalArgumentException` - if an input parameter is illegal

    - #### formatCookieHeader

          Header formatCookieHeader(Cookie[] cookies)
                             throws java.lang.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:
        `java.lang.IllegalArgumentException` - if an input parameter is illegal

    - #### formatCookieHeader

          Header formatCookieHeader(Cookie cookie)
                             throws java.lang.IllegalArgumentException

      Create a `"Cookie"` Header for single Cookie.
      Parameters:
        `cookie` - the Cookie format as a `Cookie` header
      Returns:
        a Cookie header.
      Throws:
        `java.lang.IllegalArgumentException` - if an input parameter is illegal

Copyright (c) 1999-2005 - Apache Software Foundation