1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package java.net;
18
19import java.util.List;
20
21/**
22 * A CookieStore object is a repository for cookies.
23 *
24 * CookieManager will store cookies of every incoming HTTP response into
25 * CookieStore, and retrieve cookies for every outgoing HTTP request.Expired
26 * HttpCookies should be removed from this store by themselves.
27 *
28 * @since 1.6
29 */
30public interface CookieStore {
31
32    /**
33     * Saves a HTTP cookie to this store. This is called for every incoming HTTP
34     * response.
35     *
36     * A cookie may or may not has an associated URI. If not, the cookie's
37     * domain and path attribute will show cradleland. If there is an
38     * associated URI and no domain and path attribute are speicifed for the
39     * cookie, the given URI will indicate where this cookie comes from.
40     *
41     * If a cookie corresponding to the given URI already exists, then it is
42     * replaced with the new one.
43     *
44     * @param uri
45     *            the uri associated with the specified cookie. A null value
46     *            indicates the cookie is not associated with a URI
47     * @param cookie
48     *            the cookie to be stored
49     */
50    void add(URI uri, HttpCookie cookie);
51
52    /**
53     * Retrieves cookies that match the specified URI. Return not expired cookies.
54     * For every outgoing HTTP request, this method will be called.
55     *
56     * @param uri
57     *            the uri this cookie associated with. If null, this cookie will
58     *            not be associated with an URI
59     * @return an immutable list of HttpCookies, return empty list if no cookies
60     *         match the given URI
61     * @throws NullPointerException
62     *             if uri is null
63     */
64    List<HttpCookie> get(URI uri);
65
66    /**
67     * Get all cookies in cookie store which are not expired.
68     *
69     * @return an empty list if there's no http cookie in store, or an immutable
70     *         list of cookies
71     */
72    List<HttpCookie> getCookies();
73
74    /**
75     * Get a set of URIs, which is composed of associated URI with all the
76     * cookies in the store.
77     *
78     * @return zero-length list if no cookie in the store is associated with any
79     *         URIs, otherwise an immutable list of URIs.
80     */
81    List<URI> getURIs();
82
83    /**
84     * Remove the specified cookie from the store.
85     *
86     * @param uri
87     *            the uri associated with the specified cookie. If the cookie is
88     *            not associated with an URI when added, uri should be null;
89     *            otherwise the uri should be non-null.
90     * @param cookie
91     *            the cookie to be removed
92     * @return true if the specified cookie is contained in this store and
93     *         removed successfully
94     */
95    boolean remove(URI uri, HttpCookie cookie);
96
97    /**
98     * Clear this cookie store.
99     *
100     * @return true if any cookies were removed as a result of this call.
101     */
102    boolean removeAll();
103}
104