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 org.apache.commons.httpclient.Header;
33 import org.apache.commons.httpclient.NameValuePair;
34 import org.apache.commons.httpclient.Cookie;
35
36 /***
37 * Defines the cookie management specification.
38 * <p>Cookie management specification must define
39 * <ul>
40 * <li> rules of parsing "Set-Cookie" header
41 * <li> rules of validation of parsed cookies
42 * <li> formatting of "Cookie" header
43 * </ul>
44 * for a given host, port and path of origin
45 *
46 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
47 * @author <a href="mailto:jsdever@apache.org">Jeff Dever</a>
48 *
49 * @since 2.0
50 */
51 public interface CookieSpec {
52
53 /*** Path delimiter */
54 static final String PATH_DELIM = "/";
55
56 /*** Path delimiting charachter */
57 static final char PATH_DELIM_CHAR = PATH_DELIM.charAt(0);
58
59 /***
60 * Parse the <tt>"Set-Cookie"</tt> header value into Cookie array.
61 *
62 * @param host the host which sent the <tt>Set-Cookie</tt> header
63 * @param port the port which sent the <tt>Set-Cookie</tt> header
64 * @param path the path which sent the <tt>Set-Cookie</tt> header
65 * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
66 * was received over secure conection
67 * @param header the <tt>Set-Cookie</tt> received from the server
68 * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie value
69 * @throws MalformedCookieException if an exception occurs during parsing
70 * @throws IllegalArgumentException if an input parameter is illegal
71 */
72 Cookie[] parse(String host, int port, String path, boolean secure,
73 final String header)
74 throws MalformedCookieException, IllegalArgumentException;
75
76 /***
77 * Parse the <tt>"Set-Cookie"</tt> Header into an array of Cookies.
78 *
79 * @param host the host which sent the <tt>Set-Cookie</tt> header
80 * @param port the port which sent the <tt>Set-Cookie</tt> header
81 * @param path the path which sent the <tt>Set-Cookie</tt> header
82 * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt> header
83 * was received over secure conection
84 * @param header the <tt>Set-Cookie</tt> received from the server
85 * @return an array of <tt>Cookie</tt>s parsed from the header
86 * @throws MalformedCookieException if an exception occurs during parsing
87 * @throws IllegalArgumentException if an input parameter is illegal
88 */
89 Cookie[] parse(String host, int port, String path, boolean secure,
90 final Header header)
91 throws MalformedCookieException, IllegalArgumentException;
92
93 /***
94 * Parse the cookie attribute and update the corresponsing Cookie
95 * properties.
96 *
97 * @param attribute cookie attribute from the <tt>Set-Cookie</tt>
98 * @param cookie the to be updated
99 * @throws MalformedCookieException if an exception occurs during parsing
100 * @throws IllegalArgumentException if an input parameter is illegal
101 */
102 void parseAttribute(final NameValuePair attribute, final Cookie cookie)
103 throws MalformedCookieException, IllegalArgumentException;
104
105 /***
106 * Validate the cookie according to validation rules defined by the
107 * cookie specification.
108 *
109 * @param host the host from which the {@link Cookie} was received
110 * @param port the port from which the {@link Cookie} was received
111 * @param path the path from which the {@link Cookie} was received
112 * @param secure <tt>true</tt> when the {@link Cookie} was received
113 * using a secure connection
114 * @param cookie the Cookie to validate
115 * @throws MalformedCookieException if the cookie is invalid
116 * @throws IllegalArgumentException if an input parameter is illegal
117 */
118 void validate(String host, int port, String path, boolean secure,
119 final Cookie cookie)
120 throws MalformedCookieException, IllegalArgumentException;
121
122 /***
123 * Determines if a Cookie matches a location.
124 *
125 * @param host the host to which the request is being submitted
126 * @param port the port to which the request is being submitted
127 * @param path the path to which the request is being submitted
128 * @param secure <tt>true</tt> if the request is using a secure connection
129 * @param cookie the Cookie to be matched
130 *
131 * @return <tt>true</tt> if the cookie should be submitted with a request
132 * with given attributes, <tt>false</tt> otherwise.
133 */
134 boolean match(String host, int port, String path, boolean secure,
135 final Cookie cookie);
136
137 /***
138 * Determines which of an array of Cookies matches a location.
139 *
140 * @param host the host to which the request is being submitted
141 * @param port the port to which the request is being submitted
142 * (currenlty ignored)
143 * @param path the path to which the request is being submitted
144 * @param secure <tt>true</tt> if the request is using a secure protocol
145 * @param cookies an array of <tt>Cookie</tt>s to be matched
146 *
147 * @return <tt>true</tt> if the cookie should be submitted with a request
148 * with given attributes, <tt>false</tt> otherwise.
149 */
150 Cookie[] match(String host, int port, String path, boolean secure,
151 final Cookie cookies[]);
152
153 /***
154 * Performs domain-match as defined by the cookie specification.
155 * @param host The target host.
156 * @param domain The cookie domain attribute.
157 * @return true if the specified host matches the given domain.
158 *
159 * @since 3.0
160 */
161 boolean domainMatch(final String host, final String domain);
162
163 /***
164 * Performs path-match as defined by the cookie specification.
165 * @param path The target path.
166 * @param topmostPath The cookie path attribute.
167 * @return true if the paths match
168 *
169 * @since 3.0
170 */
171 boolean pathMatch(final String path, final String topmostPath);
172
173 /***
174 * Create a <tt>"Cookie"</tt> header value for an array of cookies.
175 *
176 * @param cookie the cookie to be formatted as string
177 * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
178 */
179 String formatCookie(Cookie cookie);
180
181 /***
182 * Create a <tt>"Cookie"</tt> header value for an array of cookies.
183 *
184 * @param cookies the Cookies to be formatted
185 * @return a string suitable for sending in a Cookie header.
186 * @throws IllegalArgumentException if an input parameter is illegal
187 */
188 String formatCookies(Cookie[] cookies) throws IllegalArgumentException;
189
190 /***
191 * Create a <tt>"Cookie"</tt> Header for an array of Cookies.
192 *
193 * @param cookies the Cookies format into a Cookie header
194 * @return a Header for the given Cookies.
195 * @throws IllegalArgumentException if an input parameter is illegal
196 */
197 Header formatCookieHeader(Cookie[] cookies) throws IllegalArgumentException;
198
199 /***
200 * Create a <tt>"Cookie"</tt> Header for single Cookie.
201 *
202 * @param cookie the Cookie format as a <tt>Cookie</tt> header
203 * @return a Cookie header.
204 * @throws IllegalArgumentException if an input parameter is illegal
205 */
206 Header formatCookieHeader(Cookie cookie) throws IllegalArgumentException;
207
208 }