KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > net > CookieHandler


1 /*
2  * @(#)CookieHandler.java 1.4 03/08/09
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.net;
9
10 import java.util.Map JavaDoc;
11 import java.util.List JavaDoc;
12 import java.io.IOException JavaDoc;
13 import sun.security.util.SecurityConstants;
14
15 /**
16  * A CookieHandler object provides a callback mechanism to hook up a
17  * HTTP state management policy implementation into the HTTP protocol
18  * handler. The HTTP state management mechanism specifies a way to
19  * create a stateful session with HTTP requests and responses.
20  *
21  * <p>A system-wide CookieHandler that to used by the HTTP protocol
22  * handler can be registered by doing a
23  * CookieHandler.setDefault(CookieHandler). The currently registered
24  * CookieHandler can be retrieved by calling
25  * CookieHandler.getDefault().
26  *
27  * For more information on HTTP state management, see <a
28  * HREF="http://www.ietf.org/rfc/rfc2965.txt""><i>RFC&nbsp;2965: HTTP
29  * State Management Mechanism</i></a>
30  *
31  * @version 1.4, 03/08/09
32  * @author Yingxian Wang
33  * @since 1.5
34  */
35 public abstract class CookieHandler {
36     /**
37      * The system-wide cookie handler that will apply cookies to the
38      * request headers and manage cookies from the response headers.
39      *
40      * @see setDefault(CookieHandler)
41      * @see getDefault()
42      */
43     private static CookieHandler JavaDoc cookieHandler;
44
45     /**
46      * Gets the system-wide cookie handler.
47      *
48      * @return the system-wide cookie handler; A null return means
49      * there is no system-wide cookie handler currently set.
50      * @throws SecurityException
51      * If a security manager has been installed and it denies
52      * {@link NetPermission}<tt>("getCookieHandler")</tt>
53      * @see #setDefault(CookieHandler)
54      */
55     public synchronized static CookieHandler JavaDoc getDefault() {
56     SecurityManager JavaDoc sm = System.getSecurityManager();
57     if (sm != null) {
58         sm.checkPermission(SecurityConstants.GET_COOKIEHANDLER_PERMISSION);
59     }
60     return cookieHandler;
61     }
62
63     /**
64      * Sets (or unsets) the system-wide cookie handler.
65      *
66      * Note: non-standard http protocol handlers may ignore this setting.
67      *
68      * @param cHandler The HTTP cookie handler, or
69      * <code>null</code> to unset.
70      * @throws SecurityException
71      * If a security manager has been installed and it denies
72      * {@link NetPermission}<tt>("setCookieHandler")</tt>
73      * @see #getDefault()
74      */
75     public synchronized static void setDefault(CookieHandler JavaDoc cHandler) {
76     SecurityManager JavaDoc sm = System.getSecurityManager();
77     if (sm != null) {
78         sm.checkPermission(SecurityConstants.SET_COOKIEHANDLER_PERMISSION);
79     }
80     cookieHandler = cHandler;
81     }
82
83     /**
84      * Gets all the applicable cookies from a cookie cache for the
85      * specified uri in the request header.
86      *
87      * HTTP protocol implementers should make sure that this method is
88      * called after all request headers related to choosing cookies
89      * are added, and before the request is sent.
90      *
91      * @param uri a <code>URI</code> to send cookies to in a request
92      * @param requestHeaders - a Map from request header
93      * field names to lists of field values representing
94      * the current request headers
95      * @return an immutable map from state management headers, with
96      * field names "Cookie" or "Cookie2" to a list of
97      * cookies containing state information
98      *
99      * @throws IOException if an I/O * error occurs
100      * @throws IllegalArgumentException if either argument is null
101      * @see #put(URI, Map)
102      */
103     public abstract Map JavaDoc<String JavaDoc, List JavaDoc<String JavaDoc>>
104     get(URI JavaDoc uri, Map JavaDoc<String JavaDoc, List JavaDoc<String JavaDoc>> requestHeaders)
105         throws IOException JavaDoc;
106  
107     /**
108      * Sets all the applicable cookies, examples are response header
109      * fields that are named Set-Cookie2, present in the response
110      * headers into a cookie cache.
111      *
112      * @param uri a <code>URI</code> where the cookies come from
113      * @param responseHeaders an immutable map from field names to
114      * lists of field values representing the response
115      * header fields returned
116      * @throws IOException if an I/O error occurs
117      * @throws IllegalArgumentException if either argument is null
118      * @see #get(URI, Map)
119      */
120     public abstract void
121     put(URI JavaDoc uri, Map JavaDoc<String JavaDoc, List JavaDoc<String JavaDoc>> responseHeaders)
122     throws IOException JavaDoc;
123 }
124
Popular Tags