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.Collections;
33 import java.util.HashMap;
34 import java.util.Map;
35
36 import org.apache.commons.logging.Log;
37 import org.apache.commons.logging.LogFactory;
38
39 /***
40 * Cookie management policy class. The cookie policy provides corresponding
41 * cookie management interfrace for a given type or version of cookie.
42 * <p>RFC 2109 specification is used per default. Other supported specification
43 * can be chosen when appropriate or set default when desired
44 * <p>The following specifications are provided:
45 * <ul>
46 * <li><tt>BROWSER_COMPATIBILITY</tt>: compatible with the common cookie
47 * management practices (even if they are not 100% standards compliant)
48 * <li><tt>NETSCAPE</tt>: Netscape cookie draft compliant
49 * <li><tt>RFC_2109</tt>: RFC2109 compliant (default)
50 * </ul>
51 *
52 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
53 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
54 *
55 * @since 2.0
56 */
57 public abstract class CookiePolicy {
58
59 private static Map SPECS = Collections.synchronizedMap(new HashMap());
60
61 /***
62 * The policy that provides high degree of compatibilty
63 * with common cookie management of popular HTTP agents.
64 *
65 * @since 3.0
66 */
67 public static final String BROWSER_COMPATIBILITY = "compatibility";
68
69 /***
70 * The Netscape cookie draft compliant policy.
71 *
72 * @since 3.0
73 */
74 public static final String NETSCAPE = "netscape";
75
76 /***
77 * The RFC 2109 compliant policy.
78 *
79 * @since 3.0
80 */
81 public static final String RFC_2109 = "rfc2109";
82
83 /***
84 * The policy that ignores cookies.
85 *
86 * @since 3.0
87 */
88 public static final String IGNORE_COOKIES = "ignoreCookies";
89
90 /***
91 * The default cookie policy.
92 *
93 * @since 3.0
94 */
95 public static final String DEFAULT = "default";
96
97 static {
98 CookiePolicy.registerCookieSpec(DEFAULT, new RFC2109Spec());
99 CookiePolicy.registerCookieSpec(RFC_2109, new RFC2109Spec());
100 CookiePolicy.registerCookieSpec(BROWSER_COMPATIBILITY, new CookieSpecBase());
101 CookiePolicy.registerCookieSpec(NETSCAPE, new NetscapeDraftSpec());
102 CookiePolicy.registerCookieSpec(IGNORE_COOKIES, new IgnoreCookiesSpec());
103 }
104
105 /***
106 * The <tt>COMPATIBILITY</tt> policy provides high compatibilty
107 * with common cookie management of popular HTTP agents.
108 *
109 * @deprecated Use {@link #BROWSER_COMPATIBILITY}
110 */
111 public static final int COMPATIBILITY = 0;
112
113 /***
114 * The <tt>NETSCAPE_DRAFT</tt> Netscape draft compliant policy.
115 *
116 * @deprecated Use {@link #NETSCAPE}
117 */
118 public static final int NETSCAPE_DRAFT = 1;
119
120 /***
121 * The <tt>RFC2109</tt> RFC 2109 compliant policy.
122 *
123 * @deprecated Use {@link #RFC_2109}
124 */
125 public static final int RFC2109 = 2;
126
127 /***
128 * The default cookie policy.
129 *
130 * @deprecated Use {@link #DEFAULT}
131 */
132 private static int defaultPolicy = RFC2109;
133
134 /*** Log object. */
135 protected static final Log LOG = LogFactory.getLog(CookiePolicy.class);
136
137 /***
138 * Registers a new {@link CookieSpec cookie specification} with the given identifier.
139 * If a specification with the given ID already exists it will be overridden.
140 * This ID is the same one used to retrieve the {@link CookieSpec cookie specification}
141 * from {@link #getCookieSpec(String)}.
142 *
143 * @param id the identifier for this specification
144 * @param spec the {@link CookieSpec cookie specification} to register
145 *
146 * @see #getCookieSpec(String)
147 *
148 * @since 3.0
149 */
150 public static void registerCookieSpec(final String id, final CookieSpec spec) {
151 if (id == null) {
152 throw new IllegalArgumentException("Id may not be null");
153 }
154 if (spec == null) {
155 throw new IllegalArgumentException("Cookie spec may not be null");
156 }
157 SPECS.put(id, spec);
158 }
159
160 /***
161 * Unregisters the {@link CookieSpec cookie specification} with the given ID.
162 *
163 * @param id the ID of the {@link CookieSpec cookie specification} to unregister
164 *
165 * @since 3.0
166 */
167 public static void unregisterCookieSpec(final String id) {
168 if (id == null) {
169 throw new IllegalArgumentException("Id may not be null");
170 }
171 SPECS.remove(id);
172 }
173
174 /***
175 * Gets the {@link CookieSpec cookie specification} with the given ID.
176 *
177 * @param id the {@link CookieSpec cookie specification} ID
178 *
179 * @return {@link CookieSpec cookie specification}
180 *
181 * @throws IllegalStateException if a policy with the ID cannot be found
182 *
183 * @since 3.0
184 */
185 public static CookieSpec getCookieSpec(final String id)
186 throws IllegalStateException {
187
188 if (id == null) {
189 throw new IllegalArgumentException("Id may not be null");
190 }
191 CookieSpec cookiespec = (CookieSpec)SPECS.get(id);
192 if (cookiespec == null) {
193 throw new IllegalStateException("Unsupported cookie spec '" + id + "'");
194 }
195 return cookiespec;
196 }
197
198 /***
199 * @return default cookie policy
200 * <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
201 *
202 * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
203 * @see #DEFAULT
204 */
205 public static int getDefaultPolicy() {
206 return defaultPolicy;
207 }
208
209
210 /***
211 * @param policy new default cookie policy
212 * <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
213 *
214 * @deprecated Use {@link CookiePolicy#registerCookieSpec(String, CookieSpec)}
215 */
216 public static void setDefaultPolicy(int policy) {
217 defaultPolicy = policy;
218 }
219
220 /***
221 * @param policy cookie policy to get the CookieSpec for
222 * @return cookie specification interface for the given policy
223 * <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
224 *
225 * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
226 */
227 public static CookieSpec getSpecByPolicy(int policy) {
228 switch(policy) {
229 case COMPATIBILITY:
230 return new CookieSpecBase();
231 case NETSCAPE_DRAFT:
232 return new NetscapeDraftSpec();
233 case RFC2109:
234 return new RFC2109Spec();
235 default:
236 return getDefaultSpec();
237 }
238 }
239
240
241 /***
242 * Returns {@link CookieSpec cookie specification} registered as {@link #DEFAULT}.
243 * If no default {@link CookieSpec cookie specification} has been registered,
244 * {@link RFC2109Spec RFC2109 specification} is returned.
245 *
246 * @return default {@link CookieSpec cookie specification}
247 *
248 * @see #DEFAULT
249 */
250 public static CookieSpec getDefaultSpec() {
251 try {
252 return getCookieSpec(DEFAULT);
253 } catch (IllegalStateException e) {
254 LOG.warn("Default cookie policy is not registered");
255 return new RFC2109Spec();
256 }
257 }
258
259
260 /***
261 * Gets the CookieSpec for a particular cookie version.
262 *
263 * <p>Supported versions:
264 * <ul>
265 * <li><tt>version 0</tt> corresponds to the Netscape draft
266 * <li><tt>version 1</tt> corresponds to the RFC 2109
267 * <li>Any other cookie value coresponds to the default spec
268 * <ul>
269 *
270 * @param ver the cookie version to get the spec for
271 * @return cookie specification interface intended for processing
272 * cookies with the given version
273 *
274 * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
275 */
276 public static CookieSpec getSpecByVersion(int ver) {
277 switch(ver) {
278 case 0:
279 return new NetscapeDraftSpec();
280 case 1:
281 return new RFC2109Spec();
282 default:
283 return getDefaultSpec();
284 }
285 }
286
287 /***
288 * @return cookie specification interface that provides high compatibilty
289 * with common cookie management of popular HTTP agents
290 *
291 * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
292 */
293 public static CookieSpec getCompatibilitySpec() {
294 return getSpecByPolicy(COMPATIBILITY);
295 }
296 }