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