Module java.base
Package java.net

Class CookieManager

java.lang.Object
java.net.CookieHandler
java.net.CookieManager
public class CookieManager extends CookieHandler
CookieManager提供了CookieHandler的具体实现，它将cookie的存储与接受和拒绝cookie的策略分开。CookieManager初始化时需要一个CookieStore来管理存储，以及一个CookiePolicy对象来决定cookie的接受/拒绝策略。

java.net包中的HTTP cookie管理如下：


                  使用
 CookieHandler <------- HttpURLConnection
       ^
       | 实现
       |         使用
 CookieManager -------> CookiePolicy
             |   使用
             |--------> HttpCookie
             |              ^
             |              | 使用
             |   使用        |
             |--------> CookieStore
                            ^
                            | 实现
                            |
                  内部内存实现
  • CookieHandler是cookie管理的核心。用户可以调用CookieHandler.setDefault来设置要使用的具体CookieHandler实现。
  • CookiePolicy.shouldAccept将被CookieManager.put调用，以确定是否应接受一个cookie并将其放入cookie存储中。用户可以使用三种预定义的CookiePolicy，即ACCEPT_ALL、ACCEPT_NONE和ACCEPT_ORIGINAL_SERVER，或者用户可以定义自己的CookiePolicy实现并告诉CookieManager使用它。
  • CookieStore是接受的HTTP cookie存储的地方。如果在创建时未指定，CookieManager实例将使用一个内部内存实现。用户也可以实现自己的CookieStore并告诉CookieManager使用它。
  • 目前，CookieManager仅使用CookieStore.add(URI, HttpCookie)和CookieStore.get(URI)。其他方法是为了完整性，并可能需要更复杂的CookieStore实现，例如NetscapeCookieStore。

用户可以通过各种方式连接自己的HTTP cookie管理行为，例如：

  • 使用CookieHandler.setDefault来设置全新的CookieHandler实现
  • 让CookieManager成为默认的CookieHandler实现，但实现用户自己的CookieStore和CookiePolicy，并告诉默认的CookieManager使用它们： 
           // 这应该在HTTP会话开始时完成
       CookieHandler.setDefault(new CookieManager(new MyCookieStore(), new MyCookiePolicy()));
  • 让CookieManager成为默认的CookieHandler实现，但使用自定义的CookiePolicy： 
           // 这应该在HTTP会话开始时完成
       CookieHandler.setDefault(new CookieManager());
       // 这可以在HTTP会话的任何时候完成
       ((CookieManager)CookieHandler.getDefault()).setCookiePolicy(new MyCookiePolicy());

该实现符合RFC 2965第3.3节。

自版本:
1.6
外部规范
参见:

  • Constructor Details

    • CookieManager

      public CookieManager()
      创建一个新的cookie管理器。

      此构造函数将使用默认的cookie存储和接受策略创建新的cookie管理器。效果与CookieManager(null, null)相同。

    • CookieManager

      public CookieManager(CookieStore store, CookiePolicy cookiePolicy)
      使用指定的cookie存储和cookie策略创建一个新的cookie管理器。
      参数:
      store - 要被cookie管理器使用的CookieStore。如果为null，cookie管理器将使用一个默认的内存中的CookieStore实现。
      cookiePolicy - 要被cookie管理器作为策略回调使用的CookiePolicy实例。如果为null，将使用ACCEPT_ORIGINAL_SERVER。

  • Method Details

    • setCookiePolicy

      public void setCookiePolicy(CookiePolicy cookiePolicy)
      设置此cookie管理器的cookie策略。

      CookieManager实例默认具有ACCEPT_ORIGINAL_SERVER的cookie策略。用户始终可以调用此方法来设置另一个cookie策略。

      参数:
      cookiePolicy - cookie策略。可以为null，对当前cookie策略没有影响。

    • getCookieStore

      public CookieStore getCookieStore()
      检索当前的cookie存储。
      返回:
      当前被cookie管理器使用的cookie存储。

    • get

      public Map<String,List<String>> get(URI uri, Map<String,List<String>> requestHeaders) throws IOException
      从类中复制的描述: CookieHandler
      从请求头中的cookie缓存中获取指定URI的所有适用cookie。

      作为参数传递的URI指定了cookie的预期用途。特别是，方案应反映cookie是否将通过http、https发送，或者在其他上下文中如javascript中使用。主机部分应反映cookie的目的地或在javascript中的来源。

      实现需要考虑URI和cookie属性以及安全设置，以确定应返回哪些cookie。

      HTTP协议实现者应确保在添加所有与选择cookie相关的请求头之后调用此方法，并在发送请求之前调用。

      指定者:
      get 在类 CookieHandler中
      参数:
      uri - 表示cookie预期用途的URI
      requestHeaders - 从请求头字段名称到当前请求头字段值列表的映射
      返回:
      一个不可变的状态管理头映射，字段名为"Cookie"或"Cookie2"，值为包含状态信息的cookie列表
      抛出:
      IOException - 如果发生I/O错误
      参见:

    • put

      public void put(URI uri, Map<String,List<String>> responseHeaders) throws IOException
      从类中复制的描述: CookieHandler
      将响应头中名为Set-Cookie2的字段中的所有适用cookie设置到cookie缓存中。
      指定者:
      put 在类 CookieHandler中
      参数:
      uri - cookie来源的URI
      responseHeaders - 从字段名称到返回的响应头字段值列表的不可变映射
      抛出:
      IOException - 如果发生I/O错误
      参见: