View Javadoc

    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: 480424 $
    4    * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
    5    *
    6    * ====================================================================
    7    *
    8    *  Licensed to the Apache Software Foundation (ASF) under one or more
    9    *  contributor license agreements.  See the NOTICE file distributed with
    10   *  this work for additional information regarding copyright ownership.
    11   *  The ASF licenses this file to You under the Apache License, Version 2.0
    12   *  (the "License"); you may not use this file except in compliance with
    13   *  the License.  You may obtain a copy of the License at
    14   *
    15   *      http://www.apache.org/licenses/LICENSE-2.0
    16   *
    17   *  Unless required by applicable law or agreed to in writing, software
    18   *  distributed under the License is distributed on an "AS IS" BASIS,
    19   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    20   *  See the License for the specific language governing permissions and
    21   *  limitations under the License.
    22   * ====================================================================
    23   *
    24   * This software consists of voluntary contributions made by many
    25   * individuals on behalf of the Apache Software Foundation.  For more
    26   * information on the Apache Software Foundation, please see
    27   * <http://www.apache.org/>.
    28   *
    29   */
    30
    31  package org.apache.commons.httpclient.cookie;
    32
    33  import java.util.Collection;
    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     Cookie[] match(String host, int port, String path, boolean secure,
    181         final Cookie cookies[]);
    182
    183     /**
    184      * Performs domain-match as defined by the cookie specification.
    185      * @param host The target host.
    186      * @param domain The cookie domain attribute.
    187      * @return true if the specified host matches the given domain.
    188      *
    189      * @since 3.0
    190      */
    191     boolean domainMatch(String host, String domain);
    192
    193     /**
    194      * Performs path-match as defined by the cookie specification.
    195      * @param path The target path.
    196      * @param topmostPath The cookie path attribute.
    197      * @return true if the paths match
    198      *
    199      * @since 3.0
    200      */
    201     boolean pathMatch(String path, String topmostPath);
    202
    203     /**
    204      * Create a <tt>"Cookie"</tt> header value for an array of cookies.
    205      *
    206      * @param cookie the cookie to be formatted as string
    207      * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
    208      */
    209     String formatCookie(Cookie cookie);
    210
    211     /**
    212      * Create a <tt>"Cookie"</tt> header value for an array of cookies.
    213      *
    214      * @param cookies the Cookies to be formatted
    215      * @return a string suitable for sending in a Cookie header.
    216      * @throws IllegalArgumentException if an input parameter is illegal
    217      */
    218     String formatCookies(Cookie[] cookies) throws IllegalArgumentException;
    219
    220     /**
    221      * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
    222      *
    223      * @param cookies the Cookies format into a Cookie header
    224      * @return a Header for the given Cookies.
    225      * @throws IllegalArgumentException if an input parameter is illegal
    226      */
    227     Header formatCookieHeader(Cookie[] cookies) throws IllegalArgumentException;
    228
    229     /**
    230      * Create a <tt>"Cookie"</tt> Header for single Cookie.
    231      *
    232      * @param cookie the Cookie format as a <tt>Cookie</tt> header
    233      * @return a Cookie header.
    234      * @throws IllegalArgumentException if an input parameter is illegal
    235      */
    236     Header formatCookieHeader(Cookie cookie) throws IllegalArgumentException;
    237
    238 }