1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30 package org.apache.commons.httpclient.cookie;
31
32 import java.util.Collection;
33
34 import org.apache.commons.httpclient.Header;
35 import org.apache.commons.httpclient.NameValuePair;
36 import org.apache.commons.httpclient.Cookie;
37
38 /***
39 * Defines the cookie management specification.
40 * <p>Cookie management specification must define
41 * <ul>
42 * <li> rules of parsing "Set-Cookie" header
43 * <li> rules of validation of parsed cookies
44 * <li> formatting of "Cookie" header
45 * </ul>
46 * for a given host, port and path of origin
47 *
48 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
49 * @author <a href="mailto:jsdever@apache.org">Jeff Dever</a>
50 *
51 * @since 2.0
52 */
53 public interface CookieSpec {
54
55 /*** Path delimiter */
56 static final String PATH_DELIM = "/";
57
58 /*** Path delimiting charachter */
59 static final char PATH_DELIM_CHAR = PATH_DELIM.charAt(0);
60
61 /***
62 * Parse the <tt>"Set-Cookie"</tt> header value into Cookie array.
63 *
64 * <p>This method will not perform the validation of the resultant
65 * {@link Cookie}s</p>
66 *
67 * @see #validate(String, int, String, boolean, Cookie)
68 *
69 * @param host the host which sent the <tt>Set-Cookie</tt> header
70 * @param port the port which sent the <tt>Set-Cookie</tt> header
71 * @param path the path which sent the <tt>Set-Cookie</tt> header
72 * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
73 * was received over secure conection
74 * @param header the <tt>Set-Cookie</tt> received from the server
75 * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie value
76 * @throws MalformedCookieException if an exception occurs during parsing
77 * @throws IllegalArgumentException if an input parameter is illegal
78 */
79 Cookie[] parse(String host, int port, String path, boolean secure,
80 final String header)
81 throws MalformedCookieException, IllegalArgumentException;
82
83 /***
84 * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies.
85 *
86 * <p>This method will not perform the validation of the resultant
87 * {@link Cookie}s</p>
88 *
89 * @see #validate(String, int, String, boolean, Cookie)
90 *
91 * @param host the host which sent the <tt>Set-Cookie</tt> header
92 * @param port the port which sent the <tt>Set-Cookie</tt> header
93 * @param path the path which sent the <tt>Set-Cookie</tt> header
94 * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
95 * was received over secure conection
96 * @param header the <tt>Set-Cookie</tt> received from the server
97 * @return an array of <tt>Cookie</tt>s parsed from the header
98 * @throws MalformedCookieException if an exception occurs during parsing
99 * @throws IllegalArgumentException if an input parameter is illegal
100 */
101 Cookie[] parse(String host, int port, String path, boolean secure,
102 final Header header)
103 throws MalformedCookieException, IllegalArgumentException;
104
105 /***
106 * Parse the cookie attribute and update the corresponsing Cookie
107 * properties.
108 *
109 * @param attribute cookie attribute from the <tt>Set-Cookie</tt>
110 * @param cookie the to be updated
111 * @throws MalformedCookieException if an exception occurs during parsing
112 * @throws IllegalArgumentException if an input parameter is illegal
113 */
114 void parseAttribute(NameValuePair attribute, Cookie cookie)
115 throws MalformedCookieException, IllegalArgumentException;
116
117 /***
118 * Validate the cookie according to validation rules defined by the
119 * cookie specification.
120 *
121 * @param host the host from which the {@link Cookie} was received
122 * @param port the port from which the {@link Cookie} was received
123 * @param path the path from which the {@link Cookie} was received
124 * @param secure <tt>true</tt> when the {@link Cookie} was received
125 * using a secure connection
126 * @param cookie the Cookie to validate
127 * @throws MalformedCookieException if the cookie is invalid
128 * @throws IllegalArgumentException if an input parameter is illegal
129 */
130 void validate(String host, int port, String path, boolean secure,
131 final Cookie cookie)
132 throws MalformedCookieException, IllegalArgumentException;
133
134
135 /***
136 * Sets the {@link Collection} of date patterns used for parsing. The String patterns must be
137 * compatible with {@link java.text.SimpleDateFormat}.
138 *
139 * @param datepatterns collection of date patterns
140 */
141 void setValidDateFormats(Collection datepatterns);
142
143 /***
144 * Returns the {@link Collection} of date patterns used for parsing. The String patterns are compatible
145 * with the {@link java.text.SimpleDateFormat}.
146 *
147 * @return collection of date patterns
148 */
149 Collection getValidDateFormats();
150
151 /***
152 * Determines if a Cookie matches a location.
153 *
154 * @param host the host to which the request is being submitted
155 * @param port the port to which the request is being submitted
156 * @param path the path to which the request is being submitted
157 * @param secure <tt>true</tt> if the request is using a secure connection
158 * @param cookie the Cookie to be matched
159 *
160 * @return <tt>true</tt> if the cookie should be submitted with a request
161 * with given attributes, <tt>false</tt> otherwise.
162 */
163 boolean match(String host, int port, String path, boolean secure,
164 final Cookie cookie);
165
166 /***
167 * Determines which of an array of Cookies matches a location.
168 *
169 * @param host the host to which the request is being submitted
170 * @param port the port to which the request is being submitted
171 * (currenlty ignored)
172 * @param path the path to which the request is being submitted
173 * @param secure <tt>true</tt> if the request is using a secure protocol
174 * @param cookies an array of <tt>Cookie</tt>s to be matched
175 *
176 * @return <tt>true</tt> if the cookie should be submitted with a request
177 * with given attributes, <tt>false</tt> otherwise.
178 */
179 Cookie[] match(String host, int port, String path, boolean secure,
180 final Cookie cookies[]);
181
182 /***
183 * Performs domain-match as defined by the cookie specification.
184 * @param host The target host.
185 * @param domain The cookie domain attribute.
186 * @return true if the specified host matches the given domain.
187 *
188 * @since 3.0
189 */
190 boolean domainMatch(String host, String domain);
191
192 /***
193 * Performs path-match as defined by the cookie specification.
194 * @param path The target path.
195 * @param topmostPath The cookie path attribute.
196 * @return true if the paths match
197 *
198 * @since 3.0
199 */
200 boolean pathMatch(String path, String topmostPath);
201
202 /***
203 * Create a <tt>"Cookie"</tt> header value for an array of cookies.
204 *
205 * @param cookie the cookie to be formatted as string
206 * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
207 */
208 String formatCookie(Cookie cookie);
209
210 /***
211 * Create a <tt>"Cookie"</tt> header value for an array of cookies.
212 *
213 * @param cookies the Cookies to be formatted
214 * @return a string suitable for sending in a Cookie header.
215 * @throws IllegalArgumentException if an input parameter is illegal
216 */
217 String formatCookies(Cookie[] cookies) throws IllegalArgumentException;
218
219 /***
220 * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
221 *
222 * @param cookies the Cookies format into a Cookie header
223 * @return a Header for the given Cookies.
224 * @throws IllegalArgumentException if an input parameter is illegal
225 */
226 Header formatCookieHeader(Cookie[] cookies) throws IllegalArgumentException;
227
228 /***
229 * Create a <tt>"Cookie"</tt> Header for single Cookie.
230 *
231 * @param cookie the Cookie format as a <tt>Cookie</tt> header
232 * @return a Cookie header.
233 * @throws IllegalArgumentException if an input parameter is illegal
234 */
235 Header formatCookieHeader(Cookie cookie) throws IllegalArgumentException;
236
237 }