1 /*
2 * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookieSpec.java,v 1.6.2.1 2003/10/04 02:31:25 mbecke Exp $
3 * $Revision: 1.6.2.1 $
4 * $Date: 2003/10/04 02:31:25 $
5 *
6 * ====================================================================
7 *
8 * The Apache Software License, Version 1.1
9 *
10 * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
11 * reserved.
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 *
17 * 1. Redistributions of source code must retain the above copyright
18 * notice, this list of conditions and the following disclaimer.
19 *
20 * 2. Redistributions in binary form must reproduce the above copyright
21 * notice, this list of conditions and the following disclaimer in
22 * the documentation and/or other materials provided with the
23 * distribution.
24 *
25 * 3. The end-user documentation included with the redistribution, if
26 * any, must include the following acknowlegement:
27 * "This product includes software developed by the
28 * Apache Software Foundation (http://www.apache.org/)."
29 * Alternately, this acknowlegement may appear in the software itself,
30 * if and wherever such third-party acknowlegements normally appear.
31 *
32 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
33 * Foundation" must not be used to endorse or promote products derived
34 * from this software without prior written permission. For written
35 * permission, please contact apache@apache.org.
36 *
37 * 5. Products derived from this software may not be called "Apache"
38 * nor may "Apache" appear in their names without prior written
39 * permission of the Apache Group.
40 *
41 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
42 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
43 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
45 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
47 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
48 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
49 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
50 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
51 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
52 * SUCH DAMAGE.
53 * ====================================================================
54 *
55 * This software consists of voluntary contributions made by many
56 * individuals on behalf of the Apache Software Foundation. For more
57 * information on the Apache Software Foundation, please see
58 * <http://www.apache.org/>.
59 *
60 * [Additional notices, if required by prior licensing conditions]
61 *
62 */
63
64 package org.apache.commons.httpclient.cookie;
65
66 import org.apache.commons.httpclient.Header;
67 import org.apache.commons.httpclient.NameValuePair;
68 import org.apache.commons.httpclient.Cookie;
69
70 /***
71 * Defines the cookie management specification.
72 * <p>Cookie management specification must define
73 * <ul>
74 * <li> rules of parsing "Set-Cookie" header
75 * <li> rules of validation of parsed cookies
76 * <li> formatting of "Cookie" header
77 * </ul>
78 * for a given host, port and path of origin
79 *
80 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
81 * @author <a href="mailto:jsdever@apache.org">Jeff Dever</a>
82 *
83 * @since 2.0
84 */
85 public interface CookieSpec {
86
87 /*** Path delimiter */
88 String PATH_DELIM = "/";
89
90 /*** Path delimiting charachter */
91 char PATH_DELIM_CHAR = PATH_DELIM.charAt(0);
92
93 /***
94 * Parse the <tt>"Set-Cookie"</tt> header value into Cookie array.
95 *
96 * @param host the host which sent the <tt>Set-Cookie</tt> header
97 * @param port the port which sent the <tt>Set-Cookie</tt> header
98 * @param path the path which sent the <tt>Set-Cookie</tt> header
99 * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
100 * was received over secure conection
101 * @param header the <tt>Set-Cookie</tt> received from the server
102 * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie value
103 * @throws MalformedCookieException if an exception occurs during parsing
104 * @throws IllegalArgumentException if an input parameter is illegal
105 */
106 Cookie[] parse(String host, int port, String path, boolean secure,
107 final String header)
108 throws MalformedCookieException, IllegalArgumentException;
109
110 /***
111 * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies.
112 *
113 * @param host the host which sent the <tt>Set-Cookie</tt> header
114 * @param port the port which sent the <tt>Set-Cookie</tt> header
115 * @param path the path which sent the <tt>Set-Cookie</tt> header
116 * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
117 * was received over secure conection
118 * @param header the <tt>Set-Cookie</tt> received from the server
119 * @return an array of <tt>Cookie</tt>s parsed from the header
120 * @throws MalformedCookieException if an exception occurs during parsing
121 * @throws IllegalArgumentException if an input parameter is illegal
122 */
123 Cookie[] parse(String host, int port, String path, boolean secure,
124 final Header header)
125 throws MalformedCookieException, IllegalArgumentException;
126
127 /***
128 * Parse the cookie attribute and update the corresponsing Cookie
129 * properties.
130 *
131 * @param attribute cookie attribute from the <tt>Set-Cookie</tt>
132 * @param cookie the to be updated
133 * @throws MalformedCookieException if an exception occurs during parsing
134 * @throws IllegalArgumentException if an input parameter is illegal
135 */
136 void parseAttribute(final NameValuePair attribute, final Cookie cookie)
137 throws MalformedCookieException, IllegalArgumentException;
138
139 /***
140 * Validate the cookie according to validation rules defined by the
141 * cookie specification.
142 *
143 * @param host the host from which the {@link Cookie} was received
144 * @param port the port from which the {@link Cookie} was received
145 * @param path the path from which the {@link Cookie} was received
146 * @param secure <tt>true</tt> when the {@link Cookie} was received
147 * using a secure connection
148 * @param cookie the Cookie to validate
149 * @throws MalformedCookieException if the cookie is invalid
150 * @throws IllegalArgumentException if an input parameter is illegal
151 */
152 void validate(String host, int port, String path, boolean secure,
153 final Cookie cookie)
154 throws MalformedCookieException, IllegalArgumentException;
155
156 /***
157 * Determines if a Cookie matches a location.
158 *
159 * @param host the host to which the request is being submitted
160 * @param port the port to which the request is being submitted
161 * @param path the path to which the request is being submitted
162 * @param secure <tt>true</tt> if the request is using a secure connection
163 * @param cookie the Cookie to be matched
164 *
165 * @return <tt>true</tt> if the cookie should be submitted with a request
166 * with given attributes, <tt>false</tt> otherwise.
167 */
168 boolean match(String host, int port, String path, boolean secure,
169 final Cookie cookie);
170
171 /***
172 * Determines which of an array of Cookies matches a location.
173 *
174 * @param host the host to which the request is being submitted
175 * @param port the port to which the request is being submitted
176 * (currenlty ignored)
177 * @param path the path to which the request is being submitted
178 * @param secure <tt>true</tt> if the request is using a secure protocol
179 * @param cookies an array of <tt>Cookie</tt>s to be matched
180 *
181 * @return <tt>true</tt> if the cookie should be submitted with a request
182 * with given attributes, <tt>false</tt> otherwise.
183 */
184 Cookie[] match(String host, int port, String path, boolean secure,
185 final Cookie cookies[]);
186
187 /***
188 * Create a <tt>"Cookie"</tt> header value for an array of cookies.
189 *
190 * @param cookie the cookie to be formatted as string
191 * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
192 */
193 String formatCookie(Cookie cookie);
194
195 /***
196 * Create a <tt>"Cookie"</tt> header value for an array of cookies.
197 *
198 * @param cookies the Cookies to be formatted
199 * @return a string suitable for sending in a Cookie header.
200 * @throws IllegalArgumentException if an input parameter is illegal
201 */
202 String formatCookies(Cookie[] cookies) throws IllegalArgumentException;
203
204 /***
205 * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
206 *
207 * @param cookies the Cookies format into a Cookie header
208 * @return a Header for the given Cookies.
209 * @throws IllegalArgumentException if an input parameter is illegal
210 */
211 Header formatCookieHeader(Cookie[] cookies) throws IllegalArgumentException;
212
213 /***
214 * Create a <tt>"Cookie"</tt> Header for single Cookie.
215 *
216 * @param cookie the Cookie format as a <tt>Cookie</tt> header
217 * @return a Cookie header.
218 * @throws IllegalArgumentException if an input parameter is illegal
219 */
220 Header formatCookieHeader(Cookie cookie) throws IllegalArgumentException;
221
222 }
This page was automatically generated by Maven