View Javadoc

1   /*
2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/oac.hc3x/trunk/src/java/org/apache/commons/httpclient/cookie/CookieSpec.java $
3    * $Revision: 1425331 $
4    * $Date: 2012-12-22 19:29:41 +0100 (Sat, 22 Dec 2012) $
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 }