001 /*
002 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.net;
027
028 import java.util.List;
029 import java.util.Map;
030
031 /**
032 * A CookieStore object represents a storage for cookie. Can store and retrieve
033 * cookies.
034 *
035 * <p>{@link CookieManager} will call <tt>CookieStore.add</tt> to save cookies
036 * for every incoming HTTP response, and call <tt>CookieStore.get</tt> to
037 * retrieve cookie for every outgoing HTTP request. A CookieStore
038 * is responsible for removing HttpCookie instances which have expired.
039 *
040 * @version 1.9, 07/05/05
041 * @author Edward Wang
042 * @since 1.6
043 */
044 public interface CookieStore {
045 /**
046 * Adds one HTTP cookie to the store. This is called for every
047 * incoming HTTP response.
048 *
049 * <p>A cookie to store may or may not be associated with an URI. If it
050 * is not associated with an URI, the cookie's domain and path attribute
051 * will indicate where it comes from. If it is associated with an URI and
052 * its domain and path attribute are not speicifed, given URI will indicate
053 * where this cookie comes from.
054 *
055 * <p>If a cookie corresponding to the given URI already exists,
056 * then it is replaced with the new one.
057 *
058 * @param uri the uri this cookie associated with.
059 * if <tt>null</tt>, this cookie will not be associated
060 * with an URI
061 * @param cookie the cookie to store
062 *
063 * @throws NullPointerException if <tt>cookie</tt> is <tt>null</tt>
064 *
065 * @see #get
066 *
067 */
068 public void add(URI uri, HttpCookie cookie);
069
070 /**
071 * Retrieve cookies associated with given URI, or whose domain matches the
072 * given URI. Only cookies that have not expired are returned.
073 * This is called for every outgoing HTTP request.
074 *
075 * @return an immutable list of HttpCookie,
076 * return empty list if no cookies match the given URI
077 *
078 * @throws NullPointerException if <tt>uri</tt> is <tt>null</tt>
079 *
080 * @see #add
081 *
082 */
083 public List<HttpCookie> get(URI uri);
084
085 /**
086 * Get all not-expired cookies in cookie store.
087 *
088 * @return an immutable list of http cookies;
089 * return empty list if there's no http cookie in store
090 */
091 public List<HttpCookie> getCookies();
092
093 /**
094 * Get all URIs which identify the cookies in this cookie store.
095 *
096 * @return an immutable list of URIs;
097 * return empty list if no cookie in this cookie store
098 * is associated with an URI
099 */
100 public List<URI> getURIs();
101
102 /**
103 * Remove a cookie from store.
104 *
105 * @param uri the uri this cookie associated with.
106 * if <tt>null</tt>, the cookie to be removed is not associated
107 * with an URI when added; if not <tt>null</tt>, the cookie
108 * to be removed is associated with the given URI when added.
109 * @param cookie the cookie to remove
110 *
111 * @return <tt>true</tt> if this store contained the specified cookie
112 *
113 * @throws NullPointerException if <tt>cookie</tt> is <tt>null</tt>
114 */
115 public boolean remove(URI uri, HttpCookie cookie);
116
117 /**
118 * Remove all cookies in this cookie store.
119 *
120 * @return <tt>true</tt> if this store changed as a result of the call
121 */
122 public boolean removeAll();
123 }
|