CookieManager.java revision 858
* Copyright 2005-2008 Sun Microsystems, Inc. All Rights Reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Sun designates this * particular file as subject to the "Classpath" exception as provided * by Sun in the LICENSE file that accompanied this code. * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, * CA 95054 USA or visit www.sun.com if you need additional information or * CookieManager provides a concrete implementation of {@link CookieHandler}, * which separates the storage of cookies from the policy surrounding accepting * and rejecting cookies. A CookieManager is initialized with a {@link CookieStore} * which manages storage, and a {@link CookiePolicy} object, which makes * <p> The HTTP cookie management in java.net package looks like: * CookieHandler <------- HttpURLConnection * CookieManager -------> CookiePolicy * Internal in-memory implementation * CookieHandler is at the core of cookie management. User can call * CookieHandler.setDefault to set a concrete CookieHanlder implementation * CookiePolicy.shouldAccept will be called by CookieManager.put to see whether * or not one cookie should be accepted and put into cookie store. User can use * any of three pre-defined CookiePolicy, namely ACCEPT_ALL, ACCEPT_NONE and * ACCEPT_ORIGINAL_SERVER, or user can define his own CookiePolicy implementation * and tell CookieManager to use it. * CookieStore is the place where any accepted HTTP cookie is stored in. * If not specified when created, a CookieManager instance will use an internal * in-memory implementation. Or user can implements one and tell CookieManager * Currently, only CookieStore.add(URI, HttpCookie) and CookieStore.get(URI) * are used by CookieManager. Others are for completeness and might be needed * by a more sophisticated CookieStore implementation, e.g. a NetscapeCookieSotre. * <p>There're various ways user can hook up his own HTTP cookie management behavior, e.g. * <li>Use CookieHandler.setDefault to set a brand new {@link CookieHandler} implementation * <li>Let CookieManager be the default {@link CookieHandler} implementation, * but implement user's own {@link CookieStore} and {@link CookiePolicy} * and tell default CookieManager to use them: * // this should be done at the beginning of an HTTP session * CookieHandler.setDefault(new CookieManager(new MyCookieStore(), new MyCookiePolicy())); * <li>Let CookieManager be the default {@link CookieHandler} implementation, but * use customized {@link CookiePolicy}: * // this should be done at the beginning of an HTTP session * CookieHandler.setDefault(new CookieManager()); * // this can be done at any point of an HTTP session * ((CookieManager)CookieHandler.getDefault()).setCookiePolicy(new MyCookiePolicy()); /* ---------------- Fields -------------- */ /* ---------------- Ctors -------------- */ * Create a new cookie manager. * <p>This constructor will create new cookie manager with default * cookie store and accept policy. The effect is same as * <tt>CookieManager(null, null)</tt>. * Create a new cookie manager with specified cookie store and cookie policy. * @param store a <tt>CookieStore</tt> to be used by cookie manager. * if <tt>null</tt>, cookie manager will use a default one, * which is an in-memory CookieStore implmentation. * @param cookiePolicy a <tt>CookiePolicy</tt> instance * to be used by cookie manager as policy callback. * if <tt>null</tt>, ACCEPT_ORIGINAL_SERVER will // use default cookie policy if not specify one // if not specify CookieStore to use, use default one /* ---------------- Public operations -------------- */ * To set the cookie policy of this cookie manager. * <p> A instance of <tt>CookieManager</tt> will have * cookie policy ACCEPT_ORIGINAL_SERVER by default. Users always * can call this method to set another cookie policy. * @param cookiePolicy the cookie policy. Can be <tt>null</tt>, which * has no effects on current cookie policy. * To retrieve current cookie store. * @return the cookie store currently used by cookie manager. // if there's no default CookieStore, no way for us to get any cookie // apply path-matches rule (RFC 2965 sec. 3.3.4) // and check for the possible "secure" tag (i.e. don't send // 'secure' cookies over unsecure links) // Let's check the authorize port list if it exists // apply sort rule (RFC 2965 sec. 3.3.4) // if there's no default CookieStore, no need to remember any cookie // RFC 2965 3.2.2, key must be 'Set-Cookie2' // we also accept 'Set-Cookie' here for backward compatibility // If no path is specified, then by default // the path is the directory of the page/doc // Empty port list means this should be restricted // to the incoming URI port // Only store cookies with a port list // IF the URI port is in that list, as per // RFC 2965 section 3.3.2 // invalid set-cookie header string /* ---------------- Private operations -------------- */ // to determine whether or not accept this cookie * path-matches algorithm, as defined by RFC 2965 * sort cookies with respect to their path: those with more specific Path attributes * precede those with less specific, as defined in RFC 2965 sec. 3.3.4 // Netscape cookie spec and RFC 2965 have different format of Cookie // header; RFC 2965 requires a leading $Version="1" string while Netscape // The workaround here is to add a $Version="1" string in advance // path rule only applies to the cookies with same name // those with more specific Path attributes precede those with less specific