hunt.http.client.CookieStore source code

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