    1   /*
    2    * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/cookie/CookieSpec.java,v 1.11 2004/09/14 20:11:31 olegk Exp $
    3    * $Revision: 5562 $
    4    * $Date: 2007-11-16 00:53:10 +0000 (Fri, 16 Nov 2007) $
    5    *
    6    * ====================================================================
    7    *
    8    *  Copyright 2002-2004 The Apache Software Foundation
    9    *
    10   *  Licensed under the Apache License, Version 2.0 (the "License");
    11   *  you may not use this file except in compliance with the License.
    12   *  You may obtain a copy of the License at
    13   *
    14   *      http://www.apache.org/licenses/LICENSE-2.0
    15   *
    16   *  Unless required by applicable law or agreed to in writing, software
    17   *  distributed under the License is distributed on an "AS IS" BASIS,
    18   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    19   *  See the License for the specific language governing permissions and
    20   *  limitations under the License.
    21   * ====================================================================
    22   *
    23   * This software consists of voluntary contributions made by many
    24   * individuals on behalf of the Apache Software Foundation.  For more
    25   * information on the Apache Software Foundation, please see
    26   * <http://www.apache.org/>.
    27   *
    28   */
    29
    30  package org.apache.commons.httpclient.cookie;
    31
    32  import java.util.Collection;
    33  import java.util.SortedMap; // <- IA/HERITRIX CHANGE
    34
    35  import org.apache.commons.httpclient.Header;
    36  import org.apache.commons.httpclient.NameValuePair;
    37  import org.apache.commons.httpclient.Cookie;
    38
    39  /***
    40   * Defines the cookie management specification.
    41   * <p>Cookie management specification must define
    42   * <ul>
    43   *   <li> rules of parsing "Set-Cookie" header
    44   *   <li> rules of validation of parsed cookies
    45   *   <li>  formatting of "Cookie" header
    46   * </ul>
    47   * for a given host, port and path of origin
    48   *
    49   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
    50   * @author <a href="mailto:jsdever@apache.org">Jeff Dever</a>
    51   *
    52   * @since 2.0
    53   */
    54  public interface CookieSpec {
    55
    56      /*** Path delimiter */
    57      static final String PATH_DELIM = "/";
    58
    59      /*** Path delimiting charachter */
    60      static final char PATH_DELIM_CHAR = PATH_DELIM.charAt(0);
    61
    62      /***
    63        * Parse the <tt>"Set-Cookie"</tt> header value into Cookie array.
    64        *
    65        * <p>This method will not perform the validation of the resultant
    66        * {@link Cookie}s</p>
    67        *
    68        * @see #validate(String, int, String, boolean, Cookie)
    69        *
    70        * @param host the host which sent the <tt>Set-Cookie</tt> header
    71        * @param port the port which sent the <tt>Set-Cookie</tt> header
    72        * @param path the path which sent the <tt>Set-Cookie</tt> header
    73        * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
    74        *  was received over secure conection
    75        * @param header the <tt>Set-Cookie</tt> received from the server
    76        * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie value
    77        * @throws MalformedCookieException if an exception occurs during parsing
    78        * @throws IllegalArgumentException if an input parameter is illegal
    79        */
    80      Cookie[] parse(String host, int port, String path, boolean secure,
    81        final String header)
    82        throws MalformedCookieException, IllegalArgumentException;
    83
    84      /***
    85        * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies.
    86        *
    87        * <p>This method will not perform the validation of the resultant
    88        * {@link Cookie}s</p>
    89        *
    90        * @see #validate(String, int, String, boolean, Cookie)
    91        *
    92        * @param host the host which sent the <tt>Set-Cookie</tt> header
    93        * @param port the port which sent the <tt>Set-Cookie</tt> header
    94        * @param path the path which sent the <tt>Set-Cookie</tt> header
    95        * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
    96        *  was received over secure conection
    97        * @param header the <tt>Set-Cookie</tt> received from the server
    98        * @return an array of <tt>Cookie</tt>s parsed from the header
    99        * @throws MalformedCookieException if an exception occurs during parsing
    100       * @throws IllegalArgumentException if an input parameter is illegal
    101       */
    102     Cookie[] parse(String host, int port, String path, boolean secure,
    103       final Header header)
    104       throws MalformedCookieException, IllegalArgumentException;
    105
    106     /***
    107       * Parse the cookie attribute and update the corresponsing Cookie
    108       *  properties.
    109       *
    110       * @param attribute cookie attribute from the <tt>Set-Cookie</tt>
    111       * @param cookie the to be updated
    112       * @throws MalformedCookieException if an exception occurs during parsing
    113       * @throws IllegalArgumentException if an input parameter is illegal
    114       */
    115     void parseAttribute(NameValuePair attribute, Cookie cookie)
    116       throws MalformedCookieException, IllegalArgumentException;
    117
    118     /***
    119       * Validate the cookie according to validation rules defined by the
    120       *  cookie specification.
    121       *
    122       * @param host the host from which the {@link Cookie} was received
    123       * @param port the port from which the {@link Cookie} was received
    124       * @param path the path from which the {@link Cookie} was received
    125       * @param secure <tt>true</tt> when the {@link Cookie} was received
    126       *  using a secure connection
    127       * @param cookie the Cookie to validate
    128       * @throws MalformedCookieException if the cookie is invalid
    129       * @throws IllegalArgumentException if an input parameter is illegal
    130       */
    131     void validate(String host, int port, String path, boolean secure,
    132       final Cookie cookie)
    133       throws MalformedCookieException, IllegalArgumentException;
    134
    135
    136     /***
    137      * Sets the {@link Collection} of date patterns used for parsing. The String patterns must be
    138      * compatible with {@link java.text.SimpleDateFormat}.
    139      *
    140      * @param datepatterns collection of date patterns
    141      */
    142     void setValidDateFormats(Collection datepatterns);
    143
    144     /***
    145      * Returns the {@link Collection} of date patterns used for parsing. The String patterns are compatible
    146      * with the {@link java.text.SimpleDateFormat}.
    147      *
    148      * @return collection of date patterns
    149      */
    150     Collection getValidDateFormats();
    151
    152     /***
    153      * Determines if a Cookie matches a location.
    154      *
    155      * @param host the host to which the request is being submitted
    156      * @param port the port to which the request is being submitted
    157      * @param path the path to which the request is being submitted
    158      * @param secure <tt>true</tt> if the request is using a secure connection
    159      * @param cookie the Cookie to be matched
    160      *
    161      * @return <tt>true</tt> if the cookie should be submitted with a request
    162      *  with given attributes, <tt>false</tt> otherwise.
    163      */
    164     boolean match(String host, int port, String path, boolean secure,
    165         final Cookie cookie);
    166
    167     /***
    168      * Determines which of an array of Cookies matches a location.
    169      *
    170      * @param host the host to which the request is being submitted
    171      * @param port the port to which the request is being submitted
    172      *  (currenlty ignored)
    173      * @param path the path to which the request is being submitted
    174      * @param secure <tt>true</tt> if the request is using a secure protocol
    175      * @param cookies an array of <tt>Cookie</tt>s to be matched
    176      *
    177      * @return <tt>true</tt> if the cookie should be submitted with a request
    178      *  with given attributes, <tt>false</tt> otherwise.
    179      *
    180 // BEGIN IA/HERITRIX CHANGES
    181      * @deprecated use match(String, int, String, boolean, SortedMap)
    182 // END IA/HERITRIX CHANGES
    183      */
    184     Cookie[] match(String host, int port, String path, boolean secure,
    185         final Cookie cookies[]);
    186
    187 // BEGIN IA/HERITRIX CHANGES
    188     /***
    189      * Determines which of an array of Cookies matches a location.
    190      *
    191      * If the SortedMap comes from an HttpState and is not itself
    192      * thread-safe, it may be necessary to synchronize on the HttpState
    193      * instance to protect against concurrent modification.
    194      *
    195      * @param host the host to which the request is being submitted
    196      * @param port the port to which the request is being submitted
    197      *  (currenlty ignored)
    198      * @param path the path to which the request is being submitted
    199      * @param secure <tt>true</tt> if the request is using a secure protocol
    200      * @param cookies SortedMap of <tt>Cookie</tt>s to be matched
    201      *
    202      * @return <tt>true</tt> if the cookie should be submitted with a request
    203      *  with given attributes, <tt>false</tt> otherwise.
    204      */
    205     Cookie[] match(String domain, int port, String path, boolean secure, SortedMap cookiesMap);
    206 // END IA/HERITRIX CHANGES
    207
    208     /***
    209      * Performs domain-match as defined by the cookie specification.
    210      * @param host The target host.
    211      * @param domain The cookie domain attribute.
    212      * @return true if the specified host matches the given domain.
    213      *
    214      * @since 3.0
    215      */
    216     boolean domainMatch(String host, String domain);
    217
    218     /***
    219      * Performs path-match as defined by the cookie specification.
    220      * @param path The target path.
    221      * @param topmostPath The cookie path attribute.
    222      * @return true if the paths match
    223      *
    224      * @since 3.0
    225      */
    226     boolean pathMatch(String path, String topmostPath);
    227
    228     /***
    229      * Create a <tt>"Cookie"</tt> header value for an array of cookies.
    230      *
    231      * @param cookie the cookie to be formatted as string
    232      * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
    233      */
    234     String formatCookie(Cookie cookie);
    235
    236     /***
    237      * Create a <tt>"Cookie"</tt> header value for an array of cookies.
    238      *
    239      * @param cookies the Cookies to be formatted
    240      * @return a string suitable for sending in a Cookie header.
    241      * @throws IllegalArgumentException if an input parameter is illegal
    242      */
    243     String formatCookies(Cookie[] cookies) throws IllegalArgumentException;
    244
    245     /***
    246      * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
    247      *
    248      * @param cookies the Cookies format into a Cookie header
    249      * @return a Header for the given Cookies.
    250      * @throws IllegalArgumentException if an input parameter is illegal
    251      */
    252     Header formatCookieHeader(Cookie[] cookies) throws IllegalArgumentException;
    253
    254     /***
    255      * Create a <tt>"Cookie"</tt> Header for single Cookie.
    256      *
    257      * @param cookie the Cookie format as a <tt>Cookie</tt> header
    258      * @return a Cookie header.
    259      * @throws IllegalArgumentException if an input parameter is illegal
    260      */
    261     Header formatCookieHeader(Cookie cookie) throws IllegalArgumentException;
    262
    263 }