Class CookieManager

public class CookieManager
extends CookieHandler

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:

use
 CookieHandler <------- HttpURLConnection
       ^
       | impl
       |         use
 CookieManager -------> CookiePolicy
             |   use
             |--------> HttpCookie
             |              ^
             |              | use
             |   use        |
             |--------> CookieStore
                            ^
                            | impl
                            |
                  Internal in-memory implementation

• 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 NetscapeCookieSotre.

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.

Constructors

CookieManager

public CookieManager()

CookieManager

public CookieManager(CookieStore store,
                     CookiePolicy cookiePolicy)

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

Parameters:

store - 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 - a CookiePolicy instance to be used by cookie manager as policy callback. if null, ACCEPT_ORIGINAL_SERVER will be used.

Methods

setCookiePolicy

public void setCookiePolicy(CookiePolicy cookiePolicy)

Parameters:

cookiePolicy - the cookie policy. Can be null, which has no effects on current cookie policy.

getCookieStore

public CookieStore getCookieStore()

To retrieve current cookie store.

Returns:

the cookie store currently used by cookie manager.

get

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

Description copied from class: CookieHandler

Specified by:

get in class CookieHandler

Parameters:

uri - a URI representing the intended use for the cookies

requestHeaders - - a Map from request header field names to lists of field values representing the current request headers

Returns:

an immutable map from state management headers, with field names "Cookie" or "Cookie2" to a list of cookies containing state information

Throws:

IOException - if an I/O error occurs

See Also:

CookieHandler.put(URI, Map)

put

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

Description copied from class: CookieHandler

Sets all the applicable cookies, examples are response header fields that are named Set-Cookie2, present in the response headers into a cookie cache.

Specified by:

put in class CookieHandler

Parameters:

uri - a URI where the cookies come from

responseHeaders - an immutable map from field names to lists of field values representing the response header fields returned

Throws:

IOException - if an I/O error occurs

See Also:

CookieHandler.get(URI, Map)