KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > net > CookieStore


1 /*
2  * @(#)CookieStore.java 1.3 05/11/17
3  *
4  * Copyright 2006 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.List JavaDoc;
11 import java.util.Map JavaDoc;
12
13 /**
14  * A CookieStore object represents a storage for cookie. Can store and retrieve
15  * cookies.
16  *
17  * <p>{@link CookieManager} will call <tt>CookieStore.add</tt> to save cookies
18  * for every incoming HTTP response, and call <tt>CookieStore.get</tt> to
19  * retrieve cookie for every outgoing HTTP request. A CookieStore
20  * is responsible for removing HttpCookie instances which have expired.
21  *
22  * @version 1.3, 05/11/17
23  * @author Edward Wang
24  * @since 1.6
25  */
26 public interface CookieStore {
27     /**
28      * Adds one HTTP cookie to the store. This is called for every
29      * incoming HTTP response.
30      *
31      * <p>A cookie to store may or may not be associated with an URI. If it
32      * is not associated with an URI, the cookie's domain and path attribute
33      * will indicate where it comes from. If it is associated with an URI and
34      * its domain and path attribute are not speicifed, given URI will indicate
35      * where this cookie comes from.
36      *
37      * <p>If a cookie corresponding to the given URI already exists,
38      * then it is replaced with the new one.
39      *
40      * @param uri the uri this cookie associated with.
41      * if <tt>null</tt>, this cookie will not be associated
42      * with an URI
43      * @param cookie the cookie to store
44      *
45      * @throws NullPointerException if <tt>cookie</tt> is <tt>null</tt>
46      *
47      * @see #get
48      *
49      */
50     public void add(URI JavaDoc uri, HttpCookie JavaDoc cookie);
51
52
53     /**
54      * Retrieve cookies associated with given URI, or whose domain matches the
55      * given URI. Only cookies that have not expired are returned.
56      * This is called for every outgoing HTTP request.
57      *
58      * @return an immutable list of HttpCookie,
59      * return empty list if no cookies match the given URI
60      *
61      * @throws NullPointerException if <tt>uri</tt> is <tt>null</tt>
62      *
63      * @see #add
64      *
65      */
66     public List JavaDoc<HttpCookie JavaDoc> get(URI JavaDoc uri);
67
68
69     /**
70      * Get all not-expired cookies in cookie store.
71      *
72      * @return an immutable list of http cookies;
73      * return empty list if there's no http cookie in store
74      */
75     public List JavaDoc<HttpCookie JavaDoc> getCookies();
76
77
78     /**
79      * Get all URIs which identify the cookies in this cookie store.
80      *
81      * @return an immutable list of URIs;
82      * return empty list if no cookie in this cookie store
83      * is associated with an URI
84      */
85     public List JavaDoc<URI JavaDoc> getURIs();
86     
87     
88     /**
89      * Remove a cookie from store.
90      *
91      * @param uri the uri this cookie associated with.
92      * if <tt>null</tt>, the cookie to be removed is not associated
93      * with an URI when added; if not <tt>null</tt>, the cookie
94      * to be removed is associated with the given URI when added.
95      * @param cookie the cookie to remove
96      *
97      * @return <tt>true</tt> if this store contained the specified cookie
98      *
99      * @throws NullPointerException if <tt>cookie</tt> is <tt>null</tt>
100      */
101     public boolean remove(URI JavaDoc uri, HttpCookie JavaDoc cookie);
102     
103     
104     /**
105      * Remove all cookies in this cookie store.
106      *
107      * @return <tt>true</tt> if this store changed as a result of the call
108      */
109     public boolean removeAll();
110 }
111
112
Popular Tags