View Javadoc

1   /*
2    * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookiePolicy.java,v 1.14 2004/05/13 04:02:00 mbecke Exp $
3    * $Revision: 1.14 $
4    * $Date: 2004/05/13 04:02:00 $
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  
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 }