1 /* 2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.net; 27 28 import java.util.List; 29 import java.util.Map; 30 31 /** 32 * A CookieStore object represents a storage for cookie. Can store and retrieve 33 * cookies. 34 * 35 * <p>{@link CookieManager} will call {@code CookieStore.add} to save cookies 36 * for every incoming HTTP response, and call {@code CookieStore.get} to 37 * retrieve cookie for every outgoing HTTP request. A CookieStore 38 * is responsible for removing HttpCookie instances which have expired. 39 * 40 * @author Edward Wang 41 * @since 1.6 42 */ 43 public interface CookieStore { 44 /** 45 * Adds one HTTP cookie to the store. This is called for every 46 * incoming HTTP response. 47 * 48 * <p>A cookie to store may or may not be associated with an URI. If it 49 * is not associated with an URI, the cookie's domain and path attribute 50 * will indicate where it comes from. If it is associated with an URI and 51 * its domain and path attribute are not specified, given URI will indicate 52 * where this cookie comes from. 53 * 54 * <p>If a cookie corresponding to the given URI already exists, 55 * then it is replaced with the new one. 56 * 57 * @param uri the uri this cookie associated with. 58 * if {@code null}, this cookie will not be associated 59 * with an URI 60 * @param cookie the cookie to store 61 * 62 * @throws NullPointerException if {@code cookie} is {@code null} 63 * 64 * @see #get 65 * 66 */ 67 public void add(URI uri, HttpCookie cookie); 68 69 70 /** 71 * Retrieve cookies associated with given URI, or whose domain matches the 72 * given URI. Only cookies that have not expired are returned. 73 * This is called for every outgoing HTTP request. 74 * 75 * @return an immutable list of HttpCookie, 76 * return empty list if no cookies match the given URI 77 * 78 * @param uri the uri associated with the cookies to be returned 79 * 80 * @throws NullPointerException if {@code uri} is {@code null} 81 * 82 * @see #add 83 * 84 */ 85 public List<HttpCookie> get(URI uri); 86 87 88 /** 89 * Get all not-expired cookies in cookie store. 90 * 91 * @return an immutable list of http cookies; 92 * return empty list if there's no http cookie in store 93 */ 94 public List<HttpCookie> getCookies(); 95 96 97 /** 98 * Get all URIs which identify the cookies in this cookie store. 99 * 100 * @return an immutable list of URIs; 101 * return empty list if no cookie in this cookie store 102 * is associated with an URI 103 */ 104 public List<URI> getURIs(); 105 106 107 /** 108 * Remove a cookie from store. 109 * 110 * @param uri the uri this cookie associated with. 111 * if {@code null}, the cookie to be removed is not associated 112 * with an URI when added; if not {@code null}, the cookie 113 * to be removed is associated with the given URI when added. 114 * @param cookie the cookie to remove 115 * 116 * @return {@code true} if this store contained the specified cookie 117 * 118 * @throws NullPointerException if {@code cookie} is {@code null} 119 */ 120 public boolean remove(URI uri, HttpCookie cookie); 121 122 123 /** 124 * Remove all cookies in this cookie store. 125 * 126 * @return {@code true} if this store changed as a result of the call 127 */ 128 public boolean removeAll(); 129 } 130
