android-CookieHandler、CookieManager

参考：

Android中Cookie的使用

通常来说，Http 请求 或者 返回，两两之间应该是相互独立的。然而，状态管理机制(the state management mechanism)，可以使 客户端(clients) 和 服务器(servers)可以通过把这些信息放进一个上下文变量中来实现状态信息的交换，这种方式被称作 Session.这些被用来创建 和维护session的状态信息被称作 cookie.

一个Cookie是一个数据片段，它可以被存储在浏览器的缓存中.如果你访问过一个网站，并且再次访问它的时候，这些cookie数据就可以用来识别你是一个“回头客”，说明你之前访问过该网站。Cookies使状态信息的存在成为可能，例如在线的购物车，可以将信息存储起来。一个Cookie可以短期存在，为单个web页面的session维持信息,因此 除非你关闭浏览器，否则一个cookie可以长期存在，维持信息 一个星期或者一年。

Http 状态的管理是通过java SE中的java.net.CookieHandler这个类来实现的。

一个CookieHandler对象提供了一个回调机制，这些回调机制提供给 Http 状态管理一些规则。而这些规则是在Http protocol Handler 内部实现的。

URLs 使用 HTTP 作为协议，new URL(“http://example.com“)新建一个URLs对象来作为例子，这个会使用HTTP protocol handler.这个 HTTP protocol handler回调 CookieHanlder对象的方法，如果CookieHandler中有设置的话，就可以进行状态管理。

一、CookieHandler

package java.net;

import java.util.Map;
import java.util.List;
import java.io.IOException;
import sun.security.util.SecurityConstants;

public abstract class CookieHandler {
    /**
     * The system-wide cookie handler that will apply cookies to the
     * request headers and manage cookies from the response headers.
     *
     * @see setDefault(CookieHandler)
     * @see getDefault()
     * 
     * @author Yingxian Wang
     * @since 1.5
     */
    private static CookieHandler cookieHandler;


    /**
     * Gets the system-wide cookie handler.
     */
    public synchronized static CookieHandler getDefault() {
        SecurityManager sm = System.getSecurityManager();
        if (sm != null) {
            sm.checkPermission(SecurityConstants.GET_COOKIEHANDLER_PERMISSION);
        }
        return cookieHandler;
    }


    /**
     * Sets (or unsets) the system-wide cookie handler.
     */
    public synchronized static void setDefault(CookieHandler cHandler) {
        SecurityManager sm = System.getSecurityManager();
        if (sm != null) {
            sm.checkPermission(SecurityConstants.SET_COOKIEHANDLER_PERMISSION);
        }
        cookieHandler = cHandler;
    }


    /**
     * Gets all the applicable cookies from a cookie cache for the
     * specified uri in the request header.
     */
    public abstract Map<String, List<String>> get(URI uri, Map<String, List<String>> requestHeaders)
        throws IOException;


    /**
     * Sets all the applicable cookies, examples are response header
     * fields that are named Set-Cookie2, present in the response
     * headers into a cookie cache.
     */
    public abstract void put(URI uri, Map<String, List<String>> responseHeaders)
        throws IOException;
}

CookieHandler是一个抽象类，它有两对相互对应的方法。

第一对：getDefault() 和 setDefault(cookieHandler) 方法 ,
这对方法是静态的。

getDefault() 可以知道当前的handler是否设置了cookieHandler，如果没有，返回值为null
setDefault() 可以设置自己的handler。

第二对：put(uri,responseHeader)和get(uri,requestHeaders)
这对方法是抽象方法

put(uri,responseHeader) 允许你设置所有可用的cookies 到cookies 缓存中
get(uri,requestHeaders) 从cookies缓存中得到所有可用的cookies。
这两个方法分别用在指定的URI的 response 和 request header 中，这两个方法是抽象方法，凡是实现了CookieHandler的，都需要提供内部实现。

二、CookieManager

package java.net;

import java.util.Map;
import java.util.List;
import java.util.Collections;
import java.util.Comparator;
import java.io.IOException;
import sun.util.logging.PlatformLogger;

/**
 * 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
 * policy decisions on cookie acceptance/rejection.
 * 
 *                  use
 * CookieHandler <------- HttpURLConnection
 *       ^
 *       | impl
 *       |         use
 * CookieManager -------> CookiePolicy
 *             |   use
 *             |--------> HttpCookie
 *             |              ^
 *             |              | use
 *             |   use        |
 *             |--------> CookieStore
 *                            ^
 *                            | impl
 *                            |
 *                  Internal in-memory implementation
 * </pre>
 * @see CookiePolicy
 * @author Edward Wang
 * @since 1.6
 */
public class CookieManager extends CookieHandler
{
    /* ---------------- Fields -------------- */

    private CookiePolicy policyCallback;


    private CookieStore cookieJar = null;


    /* ---------------- Ctors -------------- */


    public CookieManager() {
        this(null, null);
    }


    /**
     * Create a new cookie manager with specified cookie store and cookie policy.
     */
    public CookieManager(CookieStore store,
                         CookiePolicy cookiePolicy)
    {
        // use default cookie policy if not specify one
        policyCallback = (cookiePolicy == null) ? CookiePolicy.ACCEPT_ORIGINAL_SERVER
                                                : cookiePolicy;

        // if not specify CookieStore to use, use default one
        if (store == null) {
            cookieJar = new InMemoryCookieStore();
        } else {
            cookieJar = store;
        }
    }


    /* ---------------- Public operations -------------- */

    /**
     * To set the cookie policy of this cookie manager.
     *
     */
    public void setCookiePolicy(CookiePolicy cookiePolicy) {
        if (cookiePolicy != null) policyCallback = cookiePolicy;
    }


    /**
     * To retrieve current cookie store.
     *
     * @return  the cookie store currently used by cookie manager.
     */
    public CookieStore getCookieStore() {
        return cookieJar;
    }


    public Map<String, List<String>>
        get(URI uri, Map<String, List<String>> requestHeaders)
        throws IOException
    {
       ...
    }


    public void
        put(URI uri, Map<String, List<String>> responseHeaders)
        throws IOException
    {
        ...
    }

}

1、Default CookieManager

java.net.CookieManger提供了一个构造方法的方式来实现CookieHandler对状态的管理。这种方式对大多数人来说，已经足够了。CookieManger通过policy来划分存储的cookies，通过policy可以实现接收和拒绝cookies。

CookieManger通过java.net.CookieStore和java.net.CookiePolicy参数来进行初始化。

CookieStore 管理cookies的存储

CookiePolicy 用来决定哪些cookies应该接收存储，哪些cookies应该拒绝。

以下的代码用来展示如何创建 并且设置一个 system-wide CookieManager (系统通用的CookieManager/默认的CookieManager)

java.net.CookieManager cm = new java.net.CookieManager();
java.net.CookieHandler.setDefault(cm);

第一行代码通过调用 默认的CookieManager的构造函数来创建了一个实例

第二行通过调用CookieHandler静态方法setDefault来设置一个system-wide handler.

默认情况下 CookieManager的构造函数，通过默认的 cookie store 和 accept policy.

CookieStore 指明了任何已经接收了的HTTP cookies的存放位置，如果在构造函数中没有指明，CookieManager实例就会使用 in-memory 的CookieStore来实现。 这种实现方式，不是持久化的 只有在Java虚拟机存活的时候存在。如果用户需要一个持久化的CookieStore必须要进行自己的自定义。

CookieManager使用的默认的cookie policy 是CookiePolicy.ACCEPT_ORIGINAL_SERVER,这种policy只接收对应服务器的cookie.所以，服务器反回的response中Set-Cookie选项中必须要有domain属性，而且这个domain属性的值必须和请求的url中host相匹配。

如果用户需要使用不同的policy的话，必须要实现CookiePolicy接口，然后通过构造方法传递进去，或者通过一个已经创建的CookieManager的setCookiePolicy(cookiePolicy)方法。

2、Custom CookieManager

CookieManager 有两个方面可以进行自定义，CookiePolicy 和 CookieStore

2.1 CookiePolicy

为了使用方便，CooliePolicy定义了一下几个 预定义的规则用来接收cookies：

CookiePolicy.ACCEPT_ORIGINAL_SERVER 只接收来自对应Server的cookies.
CookiePolicy.ACCEPT_ALL 接收所有Cookies.
CookiePolicy.ACCEPT_NONE 不接收Cookies.

你也可以通过实现implementing这个shouldAccept方法来定义自己接收Cookie的规则。然后通过CookieManager的多参数构造函数将自定义的CookiePolicy传递进去，或者通过调用setCookiePolicy(cookiePolicy)方法来改变已经存在的cookie Manager.

以下就是一个拒绝接收domain在黑名单中列表中的例子，这个需要在CookiePolicy.ACCEPT_ORIGINAL_SERVER之前调用。

import java.net.*;

public class BlacklistCookiePolicy implements CookiePolicy {
    String[] blacklist;

    public BlacklistCookiePolicy(String[] list) {
        blacklist = list;
    }

    public boolean shouldAccept(URI uri, HttpCookie cookie)  {
        String host;
        try {
            host =  InetAddress.getByName(uri.getHost()).getCanonicalHostName();
        } catch (UnknownHostException e) {
            host = uri.getHost();
        }

        for (int i = 0; i<blacklist.length; i++) {
        if (HttpCookie.domainMatches(blacklist[i], host)) {
                return false;
            }
        }

        return CookiePolicy.ACCEPT_ORIGINAL_SERVER.shouldAccept(uri, cookie);
    }
}

当你创建一个 BlacklistCookiePolicy 的实例，你可以传递一个 String array 用来表示一些你不想接受cookie 的domain.

然后你将这个BlacklistCookiePolicy的实例作为CookieManager的cookie policy 设置进去，举例来说：

String[] list = new String[]{ ".example.com" };
CookieManager cm = new CookieManager(null, new BlacklistCookiePolicy(list));
CookieHandler.setDefault(cm);

以上的示例代码就不会接收以下hosts的cookie：

host.example.com 
domain.example.com

然而，示例代码会接收来自以下hosts的cookie:

example.com 
example.org 
myhost.example.org

2.2 CookieStore

CookieStore作为一个接口，它表示了一个用来存储cookies的地方。

在每一次的Http的Response中CookieManager都会把这些cookies添加到CookieStore中.

在每一次的Http的Request时，CookieManager都会从CookieStore中获取cookies.

你可以通过 implements CookieStore接口来实现自己的CookieStore，然后在CookieManger创建的时候，将自己的CookieStore传递进去，不能在CookieManger已经被创建之后，来设置 CookieStore。 但是，你可以通过调用CookieManager.getCookieStore()方法获取cookie Store的引用。这种实现CookieStore接口的做法非常实用，因为这个可以你可以借用 Java SE 提供的默认的 内存中的CookieStore的实现，然后自己完善CookieStore的功能。

举例来说，你或许想创建一个 持久的 cookie store ，能够在Java虚拟机重启后依然生效的cookie store。你的实现方式，可能如下所示：

1、任何之前存储的cookies都可以被读取进来.
2、在运行环境(Runtime)期间，cookies 存储 和 获取都是经过内存.
3、在程序退出之前，cookies 会被写出进行持久化操作。

以下这些是一个实现上述功能的不完整的例子。这个例子可以告诉你怎样利用java se中的默认的 内存中的cookie store，并且告诉你该怎么扩展他的功能。

import java.net.*;
import java.util.*;

public class PersistentCookieStore implements CookieStore, Runnable {
    CookieStore store;

    public PersistentCookieStore() {
        // get the default in memory cookie store
        store = new CookieManager().getCookieStore();

        // todo: read in cookies from persistant storage
        // and add them store

        // add a shutdown hook to write out the in memory cookies
        Runtime.getRuntime().addShutdownHook(new Thread(this)); 
    }

    public void run() {
        // todo: write cookies in store to persistent storage
    }

    public void add(URI uri, HttpCookie cookie) {
        store.add(uri, cookie);
    }

    public List<HttpCookie> get(URI uri) {
        return store.get(uri);
    }

    public List<HttpCookie> getCookies() {
        return store.getCookies();
    }

    public List<URI> getURIs() {
        return store.getURIs();
    }

    public boolean remove(URI uri, HttpCookie cookie) {
        return store.remove(uri, cookie);
    }

    public boolean removeAll()  {
        return store.removeAll();
    }
}

CookiePolicy ：管理cookies的接受还是拒绝

package java.net;

/**
 * CookiePolicy implementations decide which cookies should be accepted
 * and which should be rejected. Three pre-defined policy implementations
 * are provided, namely ACCEPT_ALL, ACCEPT_NONE and ACCEPT_ORIGINAL_SERVER.
 *
 * <p>See RFC 2965 sec. 3.3 & 7 for more detail.
 *
 * @author Edward Wang
 * @since 1.6
 */
public interface CookiePolicy {
    /**
     * One pre-defined policy which accepts all cookies.
     */
    public static final CookiePolicy ACCEPT_ALL = new CookiePolicy(){
        public boolean shouldAccept(URI uri, HttpCookie cookie) {
            return true;
        }
    };

    /**
     * One pre-defined policy which accepts no cookies.
     */
    public static final CookiePolicy ACCEPT_NONE = new CookiePolicy(){
        public boolean shouldAccept(URI uri, HttpCookie cookie) {
            return false;
        }
    };

    /**
     * One pre-defined policy which only accepts cookies from original server.
     */
    public static final CookiePolicy ACCEPT_ORIGINAL_SERVER  = new CookiePolicy(){
        public boolean shouldAccept(URI uri, HttpCookie cookie) {
            return HttpCookie.domainMatches(cookie.getDomain(), uri.getHost());
        }
    };


    /**
     * Will be called to see whether or not this cookie should be accepted.
     *
     * @param uri       the URI to consult accept policy with
     * @param cookie    the HttpCookie object in question
     * @return          <tt>true</tt> if this cookie should be accepted;
     *                  otherwise, <tt>false</tt>
     */
    public boolean shouldAccept(URI uri, HttpCookie cookie);
}

CookieStore ：决定cookies的存储，获取

package java.net;

import java.util.List;
import java.util.Map;

/**
 * A CookieStore object represents a storage for cookie. Can store and retrieve
 * cookies.
 * 
 * @author Edward Wang
 * @since 1.6
 */
public interface CookieStore {
    /**
     * Adds one HTTP cookie to the store. This is called for every
     * incoming HTTP response.
     *
     * <p>A cookie to store may or may not be associated with an URI. If it
     * is not associated with an URI, the cookie's domain and path attribute
     * will indicate where it comes from. If it is associated with an URI and
     * its domain and path attribute are not speicifed, given URI will indicate
     * where this cookie comes from.
     */
    public void add(URI uri, HttpCookie cookie);


    /**
     * Retrieve cookies associated with given URI, or whose domain matches the
     * given URI. Only cookies that have not expired are returned.
     * This is called for every outgoing HTTP request.
     *
     * @return          an immutable list of HttpCookie,
     *                  return empty list if no cookies match the given URI
     *
     * @throws NullPointerException if <tt>uri</tt> is <tt>null</tt>
     *
     * @see #add
     *
     */
    public List<HttpCookie> get(URI uri);


    /**
     * Get all not-expired cookies in cookie store.
     *
     * @return          an immutable list of http cookies;
     *                  return empty list if there's no http cookie in store
     */
    public List<HttpCookie> getCookies();


    /**
     * Get all URIs which identify the cookies in this cookie store.
     *
     * @return          an immutable list of URIs;
     *                  return empty list if no cookie in this cookie store
     *                  is associated with an URI
     */
    public List<URI> getURIs();


    /**
     * Remove a cookie from store.
     *
     * @param uri       the uri this cookie associated with.
     *                  if <tt>null</tt>, the cookie to be removed is not associated
     *                  with an URI when added; if not <tt>null</tt>, the cookie
     *                  to be removed is associated with the given URI when added.
     * @param cookie    the cookie to remove
     *
     * @return          <tt>true</tt> if this store contained the specified cookie
     *
     * @throws NullPointerException if <tt>cookie</tt> is <tt>null</tt>
     */
    public boolean remove(URI uri, HttpCookie cookie);


    /**
     * Remove all cookies in this cookie store.
     *
     * @return          <tt>true</tt> if this store changed as a result of the call
     */
    public boolean removeAll();
}