001: /*
002: * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/cookie/CookiePolicy.java,v 1.15 2004/09/14 20:11:31 olegk Exp $
003: * $Revision: 480424 $
004: * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
005: *
006: * ====================================================================
007: *
008: * Licensed to the Apache Software Foundation (ASF) under one or more
009: * contributor license agreements. See the NOTICE file distributed with
010: * this work for additional information regarding copyright ownership.
011: * The ASF licenses this file to You under the Apache License, Version 2.0
012: * (the "License"); you may not use this file except in compliance with
013: * the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing, software
018: * distributed under the License is distributed on an "AS IS" BASIS,
019: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020: * See the License for the specific language governing permissions and
021: * limitations under the License.
022: * ====================================================================
023: *
024: * This software consists of voluntary contributions made by many
025: * individuals on behalf of the Apache Software Foundation. For more
026: * information on the Apache Software Foundation, please see
027: * <http://www.apache.org/>.
028: *
029: */
030:
031: package org.apache.commons.httpclient.cookie;
032:
033: import java.util.Collections;
034: import java.util.HashMap;
035: import java.util.Map;
036:
037: import org.apache.commons.logging.Log;
038: import org.apache.commons.logging.LogFactory;
039:
040: /**
041: * Cookie management policy class. The cookie policy provides corresponding
042: * cookie management interfrace for a given type or version of cookie.
043: * <p>RFC 2109 specification is used per default. Other supported specification
044: * can be chosen when appropriate or set default when desired
045: * <p>The following specifications are provided:
046: * <ul>
047: * <li><tt>BROWSER_COMPATIBILITY</tt>: compatible with the common cookie
048: * management practices (even if they are not 100% standards compliant)
049: * <li><tt>NETSCAPE</tt>: Netscape cookie draft compliant
050: * <li><tt>RFC_2109</tt>: RFC2109 compliant (default)
051: * <li><tt>IGNORE_COOKIES</tt>: do not automcatically process cookies
052: * </ul>
053: *
054: * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
055: * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
056: *
057: * @since 2.0
058: */
059: public abstract class CookiePolicy {
060:
061: private static Map SPECS = Collections
062: .synchronizedMap(new HashMap());
063:
064: /**
065: * The policy that provides high degree of compatibilty
066: * with common cookie management of popular HTTP agents.
067: *
068: * @since 3.0
069: */
070: public static final String BROWSER_COMPATIBILITY = "compatibility";
071:
072: /**
073: * The Netscape cookie draft compliant policy.
074: *
075: * @since 3.0
076: */
077: public static final String NETSCAPE = "netscape";
078:
079: /**
080: * The RFC 2109 compliant policy.
081: *
082: * @since 3.0
083: */
084: public static final String RFC_2109 = "rfc2109";
085:
086: /**
087: * The RFC 2965 compliant policy.
088: *
089: * @since 3.0
090: */
091: public static final String RFC_2965 = "rfc2965";
092:
093: /**
094: * The policy that ignores cookies.
095: *
096: * @since 3.0
097: */
098: public static final String IGNORE_COOKIES = "ignoreCookies";
099:
100: /**
101: * The default cookie policy.
102: *
103: * @since 3.0
104: */
105: public static final String DEFAULT = "default";
106:
107: static {
108: CookiePolicy.registerCookieSpec(DEFAULT, RFC2109Spec.class);
109: CookiePolicy.registerCookieSpec(RFC_2109, RFC2109Spec.class);
110: CookiePolicy.registerCookieSpec(RFC_2965, RFC2965Spec.class);
111: CookiePolicy.registerCookieSpec(BROWSER_COMPATIBILITY,
112: CookieSpecBase.class);
113: CookiePolicy.registerCookieSpec(NETSCAPE,
114: NetscapeDraftSpec.class);
115: CookiePolicy.registerCookieSpec(IGNORE_COOKIES,
116: IgnoreCookiesSpec.class);
117: }
118:
119: /**
120: * The <tt>COMPATIBILITY</tt> policy provides high compatibilty
121: * with common cookie management of popular HTTP agents.
122: *
123: * @deprecated Use {@link #BROWSER_COMPATIBILITY}
124: */
125: public static final int COMPATIBILITY = 0;
126:
127: /**
128: * The <tt>NETSCAPE_DRAFT</tt> Netscape draft compliant policy.
129: *
130: * @deprecated Use {@link #NETSCAPE}
131: */
132: public static final int NETSCAPE_DRAFT = 1;
133:
134: /**
135: * The <tt>RFC2109</tt> RFC 2109 compliant policy.
136: *
137: * @deprecated Use {@link #RFC_2109}
138: */
139: public static final int RFC2109 = 2;
140:
141: /**
142: * The <tt>RFC2965</tt> RFC 2965 compliant policy.
143: *
144: * @deprecated Use {@link #RFC_2965}
145: */
146: public static final int RFC2965 = 3;
147:
148: /**
149: * The default cookie policy.
150: *
151: * @deprecated Use {@link #DEFAULT}
152: */
153: private static int defaultPolicy = RFC2109;
154:
155: /** Log object. */
156: protected static final Log LOG = LogFactory
157: .getLog(CookiePolicy.class);
158:
159: /**
160: * Registers a new {@link CookieSpec cookie specification} with the given identifier.
161: * If a specification with the given ID already exists it will be overridden.
162: * This ID is the same one used to retrieve the {@link CookieSpec cookie specification}
163: * from {@link #getCookieSpec(String)}.
164: *
165: * @param id the identifier for this specification
166: * @param clazz the {@link CookieSpec cookie specification} class to register
167: *
168: * @see #getCookieSpec(String)
169: *
170: * @since 3.0
171: */
172: public static void registerCookieSpec(final String id,
173: final Class clazz) {
174: if (id == null) {
175: throw new IllegalArgumentException("Id may not be null");
176: }
177: if (clazz == null) {
178: throw new IllegalArgumentException(
179: "Cookie spec class may not be null");
180: }
181: SPECS.put(id.toLowerCase(), clazz);
182: }
183:
184: /**
185: * Unregisters the {@link CookieSpec cookie specification} with the given ID.
186: *
187: * @param id the ID of the {@link CookieSpec cookie specification} to unregister
188: *
189: * @since 3.0
190: */
191: public static void unregisterCookieSpec(final String id) {
192: if (id == null) {
193: throw new IllegalArgumentException("Id may not be null");
194: }
195: SPECS.remove(id.toLowerCase());
196: }
197:
198: /**
199: * Gets the {@link CookieSpec cookie specification} with the given ID.
200: *
201: * @param id the {@link CookieSpec cookie specification} ID
202: *
203: * @return {@link CookieSpec cookie specification}
204: *
205: * @throws IllegalStateException if a policy with the ID cannot be found
206: *
207: * @since 3.0
208: */
209: public static CookieSpec getCookieSpec(final String id)
210: throws IllegalStateException {
211:
212: if (id == null) {
213: throw new IllegalArgumentException("Id may not be null");
214: }
215: Class clazz = (Class) SPECS.get(id.toLowerCase());
216:
217: if (clazz != null) {
218: try {
219: return (CookieSpec) clazz.newInstance();
220: } catch (Exception e) {
221: LOG.error("Error initializing cookie spec: " + id, e);
222: throw new IllegalStateException(id
223: + " cookie spec implemented by "
224: + clazz.getName() + " could not be initialized");
225: }
226: } else {
227: throw new IllegalStateException("Unsupported cookie spec "
228: + id);
229: }
230: }
231:
232: /**
233: * @return default cookie policy
234: *
235: * @deprecated Use {@link #getDefaultSpec()}
236: *
237: * @see #getDefaultSpec()
238: */
239: public static int getDefaultPolicy() {
240: return defaultPolicy;
241: }
242:
243: /**
244: * @param policy new default cookie policy
245: *
246: * @deprecated Use {@link CookiePolicy#registerCookieSpec(String, Class)}
247: * @see #DEFAULT
248: */
249: public static void setDefaultPolicy(int policy) {
250: defaultPolicy = policy;
251: }
252:
253: /**
254: * @param policy cookie policy to get the CookieSpec for
255: * @return cookie specification interface for the given policy
256: *
257: * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
258: */
259: public static CookieSpec getSpecByPolicy(int policy) {
260: switch (policy) {
261: case COMPATIBILITY:
262: return new CookieSpecBase();
263: case NETSCAPE_DRAFT:
264: return new NetscapeDraftSpec();
265: case RFC2109:
266: return new RFC2109Spec();
267: case RFC2965:
268: return new RFC2965Spec();
269: default:
270: return getDefaultSpec();
271: }
272: }
273:
274: /**
275: * Returns {@link CookieSpec cookie specification} registered as {@link #DEFAULT}.
276: * If no default {@link CookieSpec cookie specification} has been registered,
277: * {@link RFC2109Spec RFC2109 specification} is returned.
278: *
279: * @return default {@link CookieSpec cookie specification}
280: *
281: * @see #DEFAULT
282: */
283: public static CookieSpec getDefaultSpec() {
284: try {
285: return getCookieSpec(DEFAULT);
286: } catch (IllegalStateException e) {
287: LOG.warn("Default cookie policy is not registered");
288: return new RFC2109Spec();
289: }
290: }
291:
292: /**
293: * Gets the CookieSpec for a particular cookie version.
294: *
295: * <p>Supported versions:
296: * <ul>
297: * <li><tt>version 0</tt> corresponds to the Netscape draft
298: * <li><tt>version 1</tt> corresponds to the RFC 2109
299: * <li>Any other cookie value coresponds to the default spec
300: * <ul>
301: *
302: * @param ver the cookie version to get the spec for
303: * @return cookie specification interface intended for processing
304: * cookies with the given version
305: *
306: * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
307: */
308: public static CookieSpec getSpecByVersion(int ver) {
309: switch (ver) {
310: case 0:
311: return new NetscapeDraftSpec();
312: case 1:
313: return new RFC2109Spec();
314: default:
315: return getDefaultSpec();
316: }
317: }
318:
319: /**
320: * @return cookie specification interface that provides high compatibilty
321: * with common cookie management of popular HTTP agents
322: *
323: * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
324: */
325: public static CookieSpec getCompatibilitySpec() {
326: return getSpecByPolicy(COMPATIBILITY);
327: }
328:
329: /**
330: * Obtains the currently registered cookie policy names.
331: *
332: * Note that the DEFAULT policy (if present) is likely to be the same
333: * as one of the other policies, but does not have to be.
334: *
335: * @return array of registered cookie policy names
336: *
337: * @since 3.1
338: */
339: public static String[] getRegisteredCookieSpecs() {
340: return (String[]) SPECS.keySet().toArray(
341: new String[SPECS.size()]);
342: }
343:
344: }
|