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 * @param host the host which sent the <tt>Set-Cookie</tt> header
65 * @param port the port which sent the <tt>Set-Cookie</tt> header
66 * @param path the path which sent the <tt>Set-Cookie</tt> header
67 * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
68 * was received over secure conection
69 * @param header the <tt>Set-Cookie</tt> received from the server
70 * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie value
71 * @throws MalformedCookieException if an exception occurs during parsing
72 * @throws IllegalArgumentException if an input parameter is illegal
73 */
74 Cookie[] parse(String host, int port, String path, boolean secure,
75 final String header)
76 throws MalformedCookieException, IllegalArgumentException;
77
78 /***
79 * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies.
80 *
81 * @param host the host which sent the <tt>Set-Cookie</tt> header
82 * @param port the port which sent the <tt>Set-Cookie</tt> header
83 * @param path the path which sent the <tt>Set-Cookie</tt> header
84 * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
85 * was received over secure conection
86 * @param header the <tt>Set-Cookie</tt> received from the server
87 * @return an array of <tt>Cookie</tt>s parsed from the header
88 * @throws MalformedCookieException if an exception occurs during parsing
89 * @throws IllegalArgumentException if an input parameter is illegal
90 */
91 Cookie[] parse(String host, int port, String path, boolean secure,
92 final Header header)
93 throws MalformedCookieException, IllegalArgumentException;
94
95 /***
96 * Parse the cookie attribute and update the corresponsing Cookie
97 * properties.
98 *
99 * @param attribute cookie attribute from the <tt>Set-Cookie</tt>
100 * @param cookie the to be updated
101 * @throws MalformedCookieException if an exception occurs during parsing
102 * @throws IllegalArgumentException if an input parameter is illegal
103 */
104 void parseAttribute(NameValuePair attribute, Cookie cookie)
105 throws MalformedCookieException, IllegalArgumentException;
106
107 /***
108 * Validate the cookie according to validation rules defined by the
109 * cookie specification.
110 *
111 * @param host the host from which the {@link Cookie} was received
112 * @param port the port from which the {@link Cookie} was received
113 * @param path the path from which the {@link Cookie} was received
114 * @param secure <tt>true</tt> when the {@link Cookie} was received
115 * using a secure connection
116 * @param cookie the Cookie to validate
117 * @throws MalformedCookieException if the cookie is invalid
118 * @throws IllegalArgumentException if an input parameter is illegal
119 */
120 void validate(String host, int port, String path, boolean secure,
121 final Cookie cookie)
122 throws MalformedCookieException, IllegalArgumentException;
123
124
125 /***
126 * Sets the {@link Collection} of date patterns used for parsing. The String patterns must be
127 * compatible with {@link java.text.SimpleDateFormat}.
128 *
129 * @param datepatterns collection of date patterns
130 */
131 void setValidDateFormats(Collection datepatterns);
132
133 /***
134 * Returns the {@link Collection} of date patterns used for parsing. The String patterns are compatible
135 * with the {@link java.text.SimpleDateFormat}.
136 *
137 * @return collection of date patterns
138 */
139 Collection getValidDateFormats();
140
141 /***
142 * Determines if a Cookie matches a location.
143 *
144 * @param host the host to which the request is being submitted
145 * @param port the port to which the request is being submitted
146 * @param path the path to which the request is being submitted
147 * @param secure <tt>true</tt> if the request is using a secure connection
148 * @param cookie the Cookie to be matched
149 *
150 * @return <tt>true</tt> if the cookie should be submitted with a request
151 * with given attributes, <tt>false</tt> otherwise.
152 */
153 boolean match(String host, int port, String path, boolean secure,
154 final Cookie cookie);
155
156 /***
157 * Determines which of an array of Cookies 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 * (currenlty ignored)
162 * @param path the path to which the request is being submitted
163 * @param secure <tt>true</tt> if the request is using a secure protocol
164 * @param cookies an array of <tt>Cookie</tt>s to be matched
165 *
166 * @return <tt>true</tt> if the cookie should be submitted with a request
167 * with given attributes, <tt>false</tt> otherwise.
168 */
169 Cookie[] match(String host, int port, String path, boolean secure,
170 final Cookie cookies[]);
171
172 /***
173 * Performs domain-match as defined by the cookie specification.
174 * @param host The target host.
175 * @param domain The cookie domain attribute.
176 * @return true if the specified host matches the given domain.
177 *
178 * @since 3.0
179 */
180 boolean domainMatch(String host, String domain);
181
182 /***
183 * Performs path-match as defined by the cookie specification.
184 * @param path The target path.
185 * @param topmostPath The cookie path attribute.
186 * @return true if the paths match
187 *
188 * @since 3.0
189 */
190 boolean pathMatch(String path, String topmostPath);
191
192 /***
193 * Create a <tt>"Cookie"</tt> header value for an array of cookies.
194 *
195 * @param cookie the cookie to be formatted as string
196 * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
197 */
198 String formatCookie(Cookie cookie);
199
200 /***
201 * Create a <tt>"Cookie"</tt> header value for an array of cookies.
202 *
203 * @param cookies the Cookies to be formatted
204 * @return a string suitable for sending in a Cookie header.
205 * @throws IllegalArgumentException if an input parameter is illegal
206 */
207 String formatCookies(Cookie[] cookies) throws IllegalArgumentException;
208
209 /***
210 * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
211 *
212 * @param cookies the Cookies format into a Cookie header
213 * @return a Header for the given Cookies.
214 * @throws IllegalArgumentException if an input parameter is illegal
215 */
216 Header formatCookieHeader(Cookie[] cookies) throws IllegalArgumentException;
217
218 /***
219 * Create a <tt>"Cookie"</tt> Header for single Cookie.
220 *
221 * @param cookie the Cookie format as a <tt>Cookie</tt> header
222 * @return a Cookie header.
223 * @throws IllegalArgumentException if an input parameter is illegal
224 */
225 Header formatCookieHeader(Cookie cookie) throws IllegalArgumentException;
226
227 }