## HTTPClient
Class CookieModule

    java.lang.Object
      HTTPClient.CookieModule

All Implemented Interfaces:
  HTTPClientModule, HTTPClientModuleConstants

public class CookieModule
extends Object
implements HTTPClientModule

This module handles Netscape cookies (also called Version 0 cookies) and Version 1 cookies. Specifically is reads the Set-Cookie and Set-Cookie2 response headers and sets the Cookie and Cookie2 headers as neccessary.

The accepting and sending of cookies is controlled by a CookiePolicyHandler. This allows you to fine tune your privacy preferences. A cookie is only added to the cookie list if the handler allows it, and a cookie from the cookie list is only sent if the handler allows it.

This module expects to be the only one handling cookies. Specifically, it will remove any Cookie and Cookie2 header fields found in the request, and it will remove the Set-Cookie and Set-Cookie2 header fields in the response (after processing them). In order to add cookies to a request or to prevent cookies from being sent, you can use the `addCookie` and `removeCookie` methods to manipulate the module's list of cookies.

A cookie jar can be used to store cookies between sessions. This file is read when this class is loaded and is written when the application exits; only cookies from the default context are saved. The name of the file is controlled by the system property HTTPClient.cookies.jar and defaults to a system dependent name. The reading and saving of cookies is enabled by setting the system property HTTPClient.cookies.save to true.

Since:
  V0.3
See Also:
  Netscape's cookie spec, HTTP State Management Mechanism spec

Field Summary

Fields inherited from interface HTTPClient.HTTPClientModuleConstants
`REQ_CONTINUE, REQ_NEWCON_RST, REQ_NEWCON_SND, REQ_RESPONSE, REQ_RESTART, REQ_RETURN, REQ_SHORTCIRC, RSP_CONTINUE, RSP_NEWCON_REQ, RSP_NEWCON_SND, RSP_REQUEST, RSP_RESTART, RSP_SEND, RSP_SHORTCIRC`

Constructor Summary
`(package private)` `CookieModule()`

Method Summary
`static void` `addCookie(Cookie cookie)` Add the specified cookie to the list of cookies in the default context.
`static void` `addCookie(Cookie cookie, Object context)` Add the specified cookie to the list of cookies for the specified context.
`static void` `discardAllCookies()` Discard all cookies for all contexts.
`static void` `discardAllCookies(Object context)` Discard all cookies for the given context.
`static Cookie[]` `listAllCookies()` List all stored cookies for all contexts.
`static Cookie[]` `listAllCookies(Object context)` List all stored cookies for a given context.
`static void` `removeCookie(Cookie cookie)` Remove the specified cookie from the list of cookies in the default context.
`static void` `removeCookie(Cookie cookie, Object context)` Remove the specified cookie from the list of cookies for the specified context.
`int` `requestHandler(Request req, Response[] resp)` Invoked by the HTTPClient.
`void` `responsePhase1Handler(Response resp, RoRequest req)` Invoked by the HTTPClient.
`int` `responsePhase2Handler(Response resp, Request req)` Invoked by the HTTPClient.
`void` `responsePhase3Handler(Response resp, RoRequest req)` Invoked by the HTTPClient.
`static CookiePolicyHandler` `setCookiePolicyHandler(CookiePolicyHandler handler)` Sets a new cookie policy handler.
`void` `trailerHandler(Response resp, RoRequest req)` Invoked by the HTTPClient.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### CookieModule

    CookieModule()

Method Detail

### requestHandler

    public int requestHandler(Request req,
                              Response[] resp)

  Invoked by the HTTPClient.

  Specified by:
    `requestHandler` in interface `HTTPClientModule`
  Parameters:
    `req` - the request - may be modified as needed
    `resp` - the response if the status is REQ_RESPONSE or REQ_RETURN
  Returns:
    status code REQ_XXX specifying further action

### responsePhase1Handler

    public void responsePhase1Handler(Response resp,
                                      RoRequest req)
                               throws IOException

  Invoked by the HTTPClient.

  Specified by:
    `responsePhase1Handler` in interface `HTTPClientModule`
  Parameters:
    `resp` - the response - may be modified
    `req` - the original request
  Throws:
    `IOException` - if an IOException occurs on the socket

### responsePhase2Handler

    public int responsePhase2Handler(Response resp,
                                     Request req)

  Invoked by the HTTPClient.

  Specified by:
    `responsePhase2Handler` in interface `HTTPClientModule`
  Parameters:
    `resp` - the response - may be modified
    `req` - the request; if the status is RSP_REQUEST then this must contain the new request; however do not modify this if you don't return a RSP_REQUEST status.
  Returns:
    status code RSP_XXX specifying further action

### responsePhase3Handler

    public void responsePhase3Handler(Response resp,
                                      RoRequest req)

  Invoked by the HTTPClient.

  Specified by:
    `responsePhase3Handler` in interface `HTTPClientModule`
  Parameters:
    `resp` - the response - may be modified
    `req` - the original request

### trailerHandler

    public void trailerHandler(Response resp,
                               RoRequest req)
                        throws IOException

  Invoked by the HTTPClient.

  Specified by:
    `trailerHandler` in interface `HTTPClientModule`
  Parameters:
    `resp` - the response
    `req` - the request
  Throws:
    `IOException` - if an IOException occurs on the socket

### discardAllCookies

    public static void discardAllCookies()

  Discard all cookies for all contexts. Cookies stored in persistent storage are not affected.

### discardAllCookies

    public static void discardAllCookies(Object context)

  Discard all cookies for the given context. Cookies stored in persistent storage are not affected.

  Parameters:
    `context` - the context Object

### listAllCookies

    public static Cookie[] listAllCookies()

  List all stored cookies for all contexts.

  Returns:
    an array of all Cookies
  Since:
    V0.3-1

### listAllCookies

    public static Cookie[] listAllCookies(Object context)

  List all stored cookies for a given context.

  Parameters:
    `context` - the context Object.
  Returns:
    an array of Cookies
  Since:
    V0.3-1

### addCookie

    public static void addCookie(Cookie cookie)

  Add the specified cookie to the list of cookies in the default context. If a compatible cookie (as defined by Cookie.equals()) already exists in the list then it is replaced with the new cookie.

  Parameters:
    `cookie` - the Cookie to add
  Since:
    V0.3-1

### addCookie

    public static void addCookie(Cookie cookie,
                                 Object context)

  Add the specified cookie to the list of cookies for the specified context. If a compatible cookie (as defined by Cookie.equals()) already exists in the list then it is replaced with the new cookie.

  Parameters:
    `cookie` - the cookie to add
    `context` - the context Object.
  Since:
    V0.3-1

### removeCookie

    public static void removeCookie(Cookie cookie)

  Remove the specified cookie from the list of cookies in the default context. If the cookie is not found in the list then this method does nothing.

  Parameters:
    `cookie` - the Cookie to remove
  Since:
    V0.3-1

### removeCookie

    public static void removeCookie(Cookie cookie,
                                    Object context)

  Remove the specified cookie from the list of cookies for the specified context. If the cookie is not found in the list then this method does nothing.

  Parameters:
    `cookie` - the cookie to remove
    `context` - the context Object
  Since:
    V0.3-1

### setCookiePolicyHandler

    public static CookiePolicyHandler setCookiePolicyHandler(CookiePolicyHandler handler)

  Sets a new cookie policy handler. This handler will be called for each cookie that a server wishes to set and for each cookie that this module wishes to send with a request. In either case the handler may allow or reject the operation. If you wish to blindly accept and send all cookies then just disable the handler with `CookieModule.setCookiePolicyHandler(null);`.

  At initialization time a default handler is installed. This handler allows all cookies to be sent. For any cookie that a server wishes to be set two lists are consulted. If the server matches any host or domain in the reject list then the cookie is rejected; if the server matches any host or domain in the accept list then the cookie is accepted (in that order). If no host or domain match is found in either of these two lists and user interaction is allowed then a dialog box is poped up to ask the user whether to accept or reject the cookie; if user interaction is not allowed the cookie is accepted.

  The accept and reject lists in the default handler are initialized at startup from the two properties HTTPClient.cookies.hosts.accept and HTTPClient.cookies.hosts.reject. These properties must contain a "|" separated list of host and domain names. All names beginning with a "." are treated as domain names, all others as host names. An empty string will match all hosts. The two lists are further expanded if the user chooses one of the "Accept All from Domain" or "Reject All from Domain" buttons in the dialog box.

  Note: the default handler does not implement the rules concerning unverifiable transactions (section 3.3.6, RFC-2965). The reason for this is simple: the default handler knows nothing about the application using this client, and it therefore does not have enough information to determine when a request is verifiable and when not. You are therefore encouraged to provide your own handler which implements section 3.3.6 (use the `CookiePolicyHandler.sendCookie` method for this).

  Parameters:
    `handler` - the new policy handler
  Returns:
    the previous policy handler