Added in API level 9

CookieManager

open class CookieManager : CookieHandler
kotlin.Any
   ↳ java.net.CookieHandler
   ↳ java.net.CookieManager

CookieManager provides a concrete implementation of CookieHandler, which separates the storage of cookies from the policy surrounding accepting and rejecting cookies. A CookieManager is initialized with a CookieStore which manages storage, and a CookiePolicy object, which makes policy decisions on cookie acceptance/rejection.

The HTTP cookie management in java.net package looks like: 

<code>use
  CookieHandler &lt;------- HttpURLConnection
        ^
        | impl
        |         use
  CookieManager -------&gt; CookiePolicy
              |   use
              |--------&gt; HttpCookie
              |              ^
              |              | use
              |   use        |
              |--------&gt; CookieStore
                             ^
                             | impl
                             |
                   Internal in-memory implementation
  </code>
  • CookieHandler is at the core of cookie management. User can call CookieHandler.setDefault to set a concrete CookieHanlder implementation to be used.
  • 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 to use it.
  • 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 NetscapeCookieStore.

There're various ways user can hook up his own HTTP cookie management behavior, e.g.

  • Use CookieHandler.setDefault to set a brand new CookieHandler implementation
  • Let CookieManager be the default CookieHandler implementation, but implement user's own CookieStore and 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()));
  • Let CookieManager be the default CookieHandler implementation, but use customized 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());

The implementation conforms to RFC 2965, section 3.3.

Summary

Public constructors

Create a new cookie manager.
CookieManager(store: CookieStore!, cookiePolicy: CookiePolicy!)

Create a new cookie manager with specified cookie store and cookie policy.
Public methods
open MutableMap<String!, MutableList<String!>!>!
get(uri: URI!, requestHeaders: MutableMap<String!, MutableList<String!>!>!)
open CookieStore!

To retrieve current cookie store.
open Unit
put(uri: URI!, responseHeaders: MutableMap<String!, MutableList<String!>!>!)
open Unit
setCookiePolicy(cookiePolicy: CookiePolicy!)

To set the cookie policy of this cookie manager.
Inherited functions

Public constructors

CookieManager

Added in API level 9
CookieManager()

Create a new cookie manager.

This constructor will create new cookie manager with default cookie store and accept policy. The effect is same as CookieManager(null, null).

CookieManager

Added in API level 9
CookieManager(
    store: CookieStore!, 
    cookiePolicy: CookiePolicy!)

Create a new cookie manager with specified cookie store and cookie policy.

Parameters
store CookieStore!: a CookieStore to be used by cookie manager. if null, cookie manager will use a default one, which is an in-memory CookieStore implementation.
cookiePolicy CookiePolicy!: a CookiePolicy instance to be used by cookie manager as policy callback. if null, ACCEPT_ORIGINAL_SERVER will be used.

Public methods

get

Added in API level 9
open fun get(
    uri: URI!, 
    requestHeaders: MutableMap<String!, MutableList<String!>!>!
): MutableMap<String!, MutableList<String!>!>!
Parameters
uri URI!: a URI representing the intended use for the cookies
requestHeaders MutableMap<String!, MutableList<String!>!>!: - a Map from request header field names to lists of field values representing the current request headers
Return
MutableMap<String!, MutableList<String!>!>! an immutable map from state management headers, with field names "Cookie" or "Cookie2" to a list of cookies containing state information
Exceptions
java.io.IOException if an I/O error occurs
java.lang.IllegalArgumentException if either argument is null

getCookieStore

Added in API level 9
open fun getCookieStore(): CookieStore!

To retrieve current cookie store.

Return
CookieStore! the cookie store currently used by cookie manager.

put

Added in API level 9
open fun put(
    uri: URI!, 
    responseHeaders: MutableMap<String!, MutableList<String!>!>!
): Unit
Parameters
uri URI!: a URI where the cookies come from
responseHeaders MutableMap<String!, MutableList<String!>!>!: an immutable map from field names to lists of field values representing the response header fields returned
Exceptions
java.io.IOException if an I/O error occurs
java.lang.IllegalArgumentException if either argument is null

setCookiePolicy

Added in API level 9
open fun setCookiePolicy(cookiePolicy: CookiePolicy!): Unit

To set the cookie policy of this cookie manager.

A instance of CookieManager will have cookie policy ACCEPT_ORIGINAL_SERVER by default. Users always can call this method to set another cookie policy.

Parameters
cookiePolicy CookiePolicy!: the cookie policy. Can be null, which has no effects on current cookie policy.