1 /* 2 * Copyright (c) 2005, 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 <tt>CookieStore.add</tt> to save cookies 36 * for every incoming HTTP response, and call <tt>CookieStore.get</tt> 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 speicifed, 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 <tt>null</tt>, this cookie will not be associated 59 * with an URI 60 * @param cookie the cookie to store 61 * 62 * @throws NullPointerException if <tt>cookie</tt> is <tt>null</tt> 63 * 64 * @see #get 65 * 66 */ add(URI uri, HttpCookie cookie)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 * @throws NullPointerException if <tt>uri</tt> is <tt>null</tt> 79 * 80 * @see #add 81 * 82 */ get(URI uri)83 public List<HttpCookie> get(URI uri); 84 85 86 /** 87 * Get all not-expired cookies in cookie store. 88 * 89 * @return an immutable list of http cookies; 90 * return empty list if there's no http cookie in store 91 */ getCookies()92 public List<HttpCookie> getCookies(); 93 94 95 /** 96 * Get all URIs which identify the cookies in this cookie store. 97 * 98 * @return an immutable list of URIs; 99 * return empty list if no cookie in this cookie store 100 * is associated with an URI 101 */ getURIs()102 public List<URI> getURIs(); 103 104 105 /** 106 * Remove a cookie from store. 107 * 108 * @param uri the uri this cookie associated with. 109 * if <tt>null</tt>, the cookie to be removed is not associated 110 * with an URI when added; if not <tt>null</tt>, the cookie 111 * to be removed is associated with the given URI when added. 112 * @param cookie the cookie to remove 113 * 114 * @return <tt>true</tt> if this store contained the specified cookie 115 * 116 * @throws NullPointerException if <tt>cookie</tt> is <tt>null</tt> 117 */ remove(URI uri, HttpCookie cookie)118 public boolean remove(URI uri, HttpCookie cookie); 119 120 121 /** 122 * Remove all cookies in this cookie store. 123 * 124 * @return <tt>true</tt> if this store changed as a result of the call 125 */ removeAll()126 public boolean removeAll(); 127 } 128