RFC2965Spec (HttpClient Library (Version 3.1))
Date: 2019-09-02

org.apache.commons.httpclient.cookie

## Class RFC2965Spec

- java.lang.Object
- - org.apache.commons.httpclient.cookie.CookieSpecBase
  - - org.apache.commons.httpclient.cookie.RFC2965Spec

- All Implemented Interfaces:
    CookieSpec, CookieVersionSupport

      public class RFC2965Spec
      extends CookieSpecBase
      implements CookieVersionSupport

  RFC 2965 specific cookie management functions.

  Since:
    3.1
  Author:
    jain.samit@gmail.com (Samit Jain)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `SET_COOKIE2_KEY` Cookie Response Header name for cookies processed by this spec.

    - ### Fields inherited from class org.apache.commons.httpclient.cookie.CookieSpecBase

      `LOG`

    - ### Fields inherited from interface org.apache.commons.httpclient.cookie.CookieSpec

      `PATH_DELIM, PATH_DELIM_CHAR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RFC2965Spec()` Default constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `domainMatch(java.lang.String host, java.lang.String domain)` Performs domain-match as defined by the RFC2965.
    `protected CookieAttributeHandler` | `findAttribHandler(java.lang.String name)` Finds an attribute handler `CookieAttributeHandler` for the given attribute.
    `java.lang.String` | `formatCookie(Cookie cookie)` Return a string suitable for sending in a `"Cookie"` header as defined in RFC 2965
    `java.lang.String` | `formatCookies(Cookie[] cookies)` Create a RFC 2965 compliant `"Cookie"` header value containing all `Cookie`s suitable for sending in a `"Cookie"` header
    `protected CookieAttributeHandler` | `getAttribHandler(java.lang.String name)` Gets attribute handler `CookieAttributeHandler` for the given attribute.
    `protected java.util.Iterator` | `getAttribHandlerIterator()`
    `int` | `getVersion()`
    `Header` | `getVersionHeader()`
    `boolean` | `match(java.lang.String host, int port, java.lang.String path, boolean secure, Cookie cookie)` Return `true` if the cookie should be submitted with a request with given attributes, `false` otherwise.
    `Cookie[]` | `parse(java.lang.String host, int port, java.lang.String path, boolean secure, Header header)` Parses the Set-Cookie2 value into an array of `Cookie`s.
    `Cookie[]` | `parse(java.lang.String host, int port, java.lang.String path, boolean secure, java.lang.String header)` Parses the Set-Cookie value into an array of `Cookie`s.
    `void` | `parseAttribute(NameValuePair attribute, Cookie cookie)` Parse RFC 2965 specific cookie attribute and update the corresponsing `Cookie` properties.
    `protected void` | `registerAttribHandler(java.lang.String name, CookieAttributeHandler handler)`
    `void` | `validate(java.lang.String host, int port, java.lang.String path, boolean secure, Cookie cookie)` Performs RFC 2965 compliant `Cookie` validation

    - ### Methods inherited from class org.apache.commons.httpclient.cookie.CookieSpecBase

      `formatCookieHeader, formatCookieHeader, getValidDateFormats, match, pathMatch, setValidDateFormats`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SET_COOKIE2_KEY

          public static final java.lang.String SET_COOKIE2_KEY

      Cookie Response Header name for cookies processed by this spec.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RFC2965Spec

          public RFC2965Spec()

      Default constructor

  - ### Method Detail

    - #### registerAttribHandler

          protected void registerAttribHandler(java.lang.String name,
                                               CookieAttributeHandler handler)

    - #### findAttribHandler

          protected CookieAttributeHandler findAttribHandler(java.lang.String name)

      Finds an attribute handler `CookieAttributeHandler` for the given attribute. Returns `null` if no attribute handler is found for the specified attribute.
      Parameters:
        `name` - attribute name. e.g. Domain, Path, etc.
      Returns:
        an attribute handler or `null`

    - #### getAttribHandler

          protected CookieAttributeHandler getAttribHandler(java.lang.String name)

      Gets attribute handler `CookieAttributeHandler` for the given attribute.
      Parameters:
        `name` - attribute name. e.g. Domain, Path, etc.
      Throws:
        `java.lang.IllegalStateException` - if handler not found for the specified attribute.

    - #### getAttribHandlerIterator

          protected java.util.Iterator getAttribHandlerIterator()

    - #### parse

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

      Parses the Set-Cookie2 value into an array of `Cookie`s.

      The syntax for the Set-Cookie2 response header is:

           set-cookie      =    "Set-Cookie2:" cookies
           cookies         =    1#cookie
           cookie          =    NAME "=" VALUE * (";" cookie-av)
           NAME            =    attr
           VALUE           =    value
           cookie-av       =    "Comment" "=" value
                           |    "CommentURL" "=" <"> http_URL <">
                           |    "Discard"
                           |    "Domain" "=" value
                           |    "Max-Age" "=" value
                           |    "Path" "=" value
                           |    "Port" [ "=" <"> portlist <"> ]
                           |    "Secure"
                           |    "Version" "=" 1*DIGIT
           portlist        =       1#portnum
           portnum         =       1*DIGIT

      Specified by:
        `parse` in interface `CookieSpec`
      Overrides:
        `parse` in class `CookieSpecBase`
      Parameters:
        `host` - the host from which the `Set-Cookie2` value was received
        `port` - the port from which the `Set-Cookie2` value was received
        `path` - the path from which the `Set-Cookie2` value was received
        `secure` - `true` when the `Set-Cookie2` value was received over secure conection
        `header` - the `Set-Cookie2` `Header` received from the server
      Returns:
        an array of `Cookie`s parsed from the Set-Cookie2 value
      Throws:
        `MalformedCookieException` - if an exception occurs during parsing
      See Also:
        `CookieSpec.validate(String, int, String, boolean, Cookie)`

    - #### parse

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

      Description copied from class: `CookieSpecBase`
      Parses the Set-Cookie value into an array of `Cookie`s.

      The syntax for the Set-Cookie response header is:

           set-cookie      =    "Set-Cookie:" cookies
           cookies         =    1#cookie
           cookie          =    NAME "=" VALUE * (";" cookie-av)
           NAME            =    attr
           VALUE           =    value
           cookie-av       =    "Comment" "=" value
                           |    "Domain" "=" value
                           |    "Max-Age" "=" value
                           |    "Path" "=" value
                           |    "Secure"
                           |    "Version" "=" 1*DIGIT

      Specified by:
        `parse` in interface `CookieSpec`
      Overrides:
        `parse` in class `CookieSpecBase`
      Parameters:
        `host` - the host from which the `Set-Cookie` value was received
        `port` - the port from which the `Set-Cookie` value was received
        `path` - the path from which the `Set-Cookie` value was received
        `secure` - `true` when the `Set-Cookie` value 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
      See Also:
        `parse(String, int, String, boolean, org.apache.commons.httpclient.Header)`

    - #### parseAttribute

          public void parseAttribute(NameValuePair attribute,
                                     Cookie cookie)
                              throws MalformedCookieException

      Parse RFC 2965 specific cookie attribute and update the corresponsing `Cookie` properties.
      Specified by:
        `parseAttribute` in interface `CookieSpec`
      Overrides:
        `parseAttribute` in class `CookieSpecBase`
      Parameters:
        `attribute` - `NameValuePair` cookie attribute from the `Set-Cookie2` header.
        `cookie` - `Cookie` to be updated
      Throws:
        `MalformedCookieException` - if an exception occurs during parsing

    - #### validate

          public void validate(java.lang.String host,
                               int port,
                               java.lang.String path,
                               boolean secure,
                               Cookie cookie)
                        throws MalformedCookieException

      Performs RFC 2965 compliant `Cookie` validation
      Specified by:
        `validate` in interface `CookieSpec`
      Overrides:
        `validate` in class `CookieSpecBase`
      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 an exception occurs during validation

    - #### match

          public boolean match(java.lang.String host,
                               int port,
                               java.lang.String path,
                               boolean secure,
                               Cookie cookie)

      Return `true` if the cookie should be submitted with a request with given attributes, `false` otherwise.
      Specified by:
        `match` in interface `CookieSpec`
      Overrides:
        `match` in class `CookieSpecBase`
      Parameters:
        `host` - the host to which the request is being submitted
        `port` - the port to which the request is being submitted (ignored)
        `path` - the path to which the request is being submitted
        `secure` - `true` if the request is using a secure connection
        `cookie` - `Cookie` to be matched
      Returns:
        true if the cookie matches the criterium

    - #### formatCookie

          public java.lang.String formatCookie(Cookie cookie)

      Return a string suitable for sending in a `"Cookie"` header as defined in RFC 2965
      Specified by:
        `formatCookie` in interface `CookieSpec`
      Overrides:
        `formatCookie` in class `CookieSpecBase`
      Parameters:
        `cookie` - a `Cookie` to be formatted as string
      Returns:
        a string suitable for sending in a `"Cookie"` header.

    - #### formatCookies

          public java.lang.String formatCookies(Cookie[] cookies)

      Create a RFC 2965 compliant `"Cookie"` header value containing all `Cookie`s suitable for sending in a `"Cookie"` header
      Specified by:
        `formatCookies` in interface `CookieSpec`
      Overrides:
        `formatCookies` in class `CookieSpecBase`
      Parameters:
        `cookies` - an array of `Cookie`s to be formatted
      Returns:
        a string suitable for sending in a Cookie header.

    - #### domainMatch

          public boolean domainMatch(java.lang.String host,
                                     java.lang.String domain)

      Performs domain-match as defined by the RFC2965.

      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.)
      Specified by:
        `domainMatch` in interface `CookieSpec`
      Overrides:
        `domainMatch` in class `CookieSpecBase`
      Parameters:
        `host` - host name where cookie is received from or being sent to.
        `domain` - The cookie domain attribute.
      Returns:
        true if the specified host matches the given domain.

    - #### getVersion

          public int getVersion()

      Specified by:
        `getVersion` in interface `CookieVersionSupport`

    - #### getVersionHeader

          public Header getVersionHeader()

      Specified by:
        `getVersionHeader` in interface `CookieVersionSupport`

Copyright (c) 1999-2005 - Apache Software Foundation