1. /*
  2. * $Header: /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 $
  3. * $Revision: 1.15 $
  4. * $Date: 2004/09/14 20:11:31 $
  5. *
  6. * ====================================================================
  7. *
  8. * Copyright 2002-2004 The Apache Software Foundation
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License");
  11. * you may not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS,
  18. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. * ====================================================================
  22. *
  23. * This software consists of voluntary contributions made by many
  24. * individuals on behalf of the Apache Software Foundation. For more
  25. * information on the Apache Software Foundation, please see
  26. * <http://www.apache.org/>.
  27. *
  28. */
  29. package org.apache.commons.httpclient.cookie;
  30. import java.util.Collections;
  31. import java.util.HashMap;
  32. import java.util.Map;
  33. import org.apache.commons.logging.Log;
  34. import org.apache.commons.logging.LogFactory;
  35. /**
  36. * Cookie management policy class. The cookie policy provides corresponding
  37. * cookie management interfrace for a given type or version of cookie.
  38. * <p>RFC 2109 specification is used per default. Other supported specification
  39. * can be chosen when appropriate or set default when desired
  40. * <p>The following specifications are provided:
  41. * <ul>
  42. * <li><tt>BROWSER_COMPATIBILITY</tt>: compatible with the common cookie
  43. * management practices (even if they are not 100% standards compliant)
  44. * <li><tt>NETSCAPE</tt>: Netscape cookie draft compliant
  45. * <li><tt>RFC_2109</tt>: RFC2109 compliant (default)
  46. * </ul>
  47. *
  48. * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
  49. * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
  50. *
  51. * @since 2.0
  52. */
  53. public abstract class CookiePolicy {
  54. private static Map SPECS = Collections.synchronizedMap(new HashMap());
  55. /**
  56. * The policy that provides high degree of compatibilty
  57. * with common cookie management of popular HTTP agents.
  58. *
  59. * @since 3.0
  60. */
  61. public static final String BROWSER_COMPATIBILITY = "compatibility";
  62. /**
  63. * The Netscape cookie draft compliant policy.
  64. *
  65. * @since 3.0
  66. */
  67. public static final String NETSCAPE = "netscape";
  68. /**
  69. * The RFC 2109 compliant policy.
  70. *
  71. * @since 3.0
  72. */
  73. public static final String RFC_2109 = "rfc2109";
  74. /**
  75. * The policy that ignores cookies.
  76. *
  77. * @since 3.0
  78. */
  79. public static final String IGNORE_COOKIES = "ignoreCookies";
  80. /**
  81. * The default cookie policy.
  82. *
  83. * @since 3.0
  84. */
  85. public static final String DEFAULT = "default";
  86. static {
  87. CookiePolicy.registerCookieSpec(DEFAULT, RFC2109Spec.class);
  88. CookiePolicy.registerCookieSpec(RFC_2109, RFC2109Spec.class);
  89. CookiePolicy.registerCookieSpec(BROWSER_COMPATIBILITY, CookieSpecBase.class);
  90. CookiePolicy.registerCookieSpec(NETSCAPE, NetscapeDraftSpec.class);
  91. CookiePolicy.registerCookieSpec(IGNORE_COOKIES, IgnoreCookiesSpec.class);
  92. }
  93. /**
  94. * The <tt>COMPATIBILITY</tt> policy provides high compatibilty
  95. * with common cookie management of popular HTTP agents.
  96. *
  97. * @deprecated Use {@link #BROWSER_COMPATIBILITY}
  98. */
  99. public static final int COMPATIBILITY = 0;
  100. /**
  101. * The <tt>NETSCAPE_DRAFT</tt> Netscape draft compliant policy.
  102. *
  103. * @deprecated Use {@link #NETSCAPE}
  104. */
  105. public static final int NETSCAPE_DRAFT = 1;
  106. /**
  107. * The <tt>RFC2109</tt> RFC 2109 compliant policy.
  108. *
  109. * @deprecated Use {@link #RFC_2109}
  110. */
  111. public static final int RFC2109 = 2;
  112. /**
  113. * The default cookie policy.
  114. *
  115. * @deprecated Use {@link #DEFAULT}
  116. */
  117. private static int defaultPolicy = RFC2109;
  118. /** Log object. */
  119. protected static final Log LOG = LogFactory.getLog(CookiePolicy.class);
  120. /**
  121. * Registers a new {@link CookieSpec cookie specification} with the given identifier.
  122. * If a specification with the given ID already exists it will be overridden.
  123. * This ID is the same one used to retrieve the {@link CookieSpec cookie specification}
  124. * from {@link #getCookieSpec(String)}.
  125. *
  126. * @param id the identifier for this specification
  127. * @param clazz the {@link CookieSpec cookie specification} class to register
  128. *
  129. * @see #getCookieSpec(String)
  130. *
  131. * @since 3.0
  132. */
  133. public static void registerCookieSpec(final String id, final Class clazz) {
  134. if (id == null) {
  135. throw new IllegalArgumentException("Id may not be null");
  136. }
  137. if (clazz == null) {
  138. throw new IllegalArgumentException("Cookie spec class may not be null");
  139. }
  140. SPECS.put(id.toLowerCase(), clazz);
  141. }
  142. /**
  143. * Unregisters the {@link CookieSpec cookie specification} with the given ID.
  144. *
  145. * @param id the ID of the {@link CookieSpec cookie specification} to unregister
  146. *
  147. * @since 3.0
  148. */
  149. public static void unregisterCookieSpec(final String id) {
  150. if (id == null) {
  151. throw new IllegalArgumentException("Id may not be null");
  152. }
  153. SPECS.remove(id.toLowerCase());
  154. }
  155. /**
  156. * Gets the {@link CookieSpec cookie specification} with the given ID.
  157. *
  158. * @param id the {@link CookieSpec cookie specification} ID
  159. *
  160. * @return {@link CookieSpec cookie specification}
  161. *
  162. * @throws IllegalStateException if a policy with the ID cannot be found
  163. *
  164. * @since 3.0
  165. */
  166. public static CookieSpec getCookieSpec(final String id)
  167. throws IllegalStateException {
  168. if (id == null) {
  169. throw new IllegalArgumentException("Id may not be null");
  170. }
  171. Class clazz = (Class)SPECS.get(id.toLowerCase());
  172. if (clazz != null) {
  173. try {
  174. return (CookieSpec)clazz.newInstance();
  175. } catch (Exception e) {
  176. LOG.error("Error initializing cookie spec: " + id, e);
  177. throw new IllegalStateException(id +
  178. " cookie spec implemented by " +
  179. clazz.getName() + " could not be initialized");
  180. }
  181. } else {
  182. throw new IllegalStateException("Unsupported cookie spec " + id);
  183. }
  184. }
  185. /**
  186. * @return default cookie policy
  187. * <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
  188. *
  189. * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
  190. * @see #DEFAULT
  191. */
  192. public static int getDefaultPolicy() {
  193. return defaultPolicy;
  194. }
  195. /**
  196. * @param policy new default cookie policy
  197. * <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
  198. *
  199. * @deprecated Use {@link CookiePolicy#registerCookieSpec(String, Class)}
  200. * @see #DEFAULT
  201. */
  202. public static void setDefaultPolicy(int policy) {
  203. defaultPolicy = policy;
  204. }
  205. /**
  206. * @param policy cookie policy to get the CookieSpec for
  207. * @return cookie specification interface for the given policy
  208. * <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
  209. *
  210. * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
  211. */
  212. public static CookieSpec getSpecByPolicy(int policy) {
  213. switch(policy) {
  214. case COMPATIBILITY:
  215. return new CookieSpecBase();
  216. case NETSCAPE_DRAFT:
  217. return new NetscapeDraftSpec();
  218. case RFC2109:
  219. return new RFC2109Spec();
  220. default:
  221. return getDefaultSpec();
  222. }
  223. }
  224. /**
  225. * Returns {@link CookieSpec cookie specification} registered as {@link #DEFAULT}.
  226. * If no default {@link CookieSpec cookie specification} has been registered,
  227. * {@link RFC2109Spec RFC2109 specification} is returned.
  228. *
  229. * @return default {@link CookieSpec cookie specification}
  230. *
  231. * @see #DEFAULT
  232. */
  233. public static CookieSpec getDefaultSpec() {
  234. try {
  235. return getCookieSpec(DEFAULT);
  236. } catch (IllegalStateException e) {
  237. LOG.warn("Default cookie policy is not registered");
  238. return new RFC2109Spec();
  239. }
  240. }
  241. /**
  242. * Gets the CookieSpec for a particular cookie version.
  243. *
  244. * <p>Supported versions:
  245. * <ul>
  246. * <li><tt>version 0</tt> corresponds to the Netscape draft
  247. * <li><tt>version 1</tt> corresponds to the RFC 2109
  248. * <li>Any other cookie value coresponds to the default spec
  249. * <ul>
  250. *
  251. * @param ver the cookie version to get the spec for
  252. * @return cookie specification interface intended for processing
  253. * cookies with the given version
  254. *
  255. * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
  256. */
  257. public static CookieSpec getSpecByVersion(int ver) {
  258. switch(ver) {
  259. case 0:
  260. return new NetscapeDraftSpec();
  261. case 1:
  262. return new RFC2109Spec();
  263. default:
  264. return getDefaultSpec();
  265. }
  266. }
  267. /**
  268. * @return cookie specification interface that provides high compatibilty
  269. * with common cookie management of popular HTTP agents
  270. *
  271. * @deprecated Use {@link CookiePolicy#getCookieSpec(String)}
  272. */
  273. public static CookieSpec getCompatibilitySpec() {
  274. return getSpecByPolicy(COMPATIBILITY);
  275. }
  276. }