You need to work with a system that uses cookies to store state, and you need to be able to set cookies as well as keep track of cookies set by the server.

HttpClient handles cookies automatically. If you need to keep track of a cookie set by the server, simply use the same instance of HttpClient for each request in a session. If you need to set a cookie, create an instance of Cookie, and add it to HttpState. The following example sends a Cookie to the server:

               import java.io.IOException;
import org.apache.commons.httpclient.Cookie;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpException;
import org.apache.commons.httpclient.HttpMethod;
import org.apache.commons.httpclient.methods.GetMethod;

HttpClient client = new HttpClient( );
    
System.out.println( "Making Request without Cookie: " );
makeRequest(client);
            
System.out.println( "Making Request with Cookie: " );
Cookie cookie = new Cookie(".discursive.com", "test_cookie", 
                           "hello", "/", null, false );
client.getState( ).addCookie( cookie );
makeRequest(client);

private 
               static 
               void makeRequest(HttpClient client)
    throws IOException, HttpException {
    String url = "http://www.discursive.com/cgi-bin/jccook/cookie_test.cgi";
    HttpMethod method = new GetMethod( url );
    client.executeMethod( method );
    String response = method.getResponseBodyAsString( );
    System.out.println( response );
    method.releaseConnection( );
    method.recycle( );
}

This example hits a CGI script that tests for the presence of a cookie named test_cookie. One request is made without the cookie and another request is made with the cookie. The following output is produced:

Making Request without Cookie: 
<h1>test_cookie NOT PRESENT</h1>

Making Request with Cookie: 
<h1>test_cookie PRESENT</h1 >

Cookies are used by a number of application servers to manage user sessions; JSESSIONID cookies are used by most J2EE application servers and servlet containers to keep track of a session. Because HttpClient automatically handles cookies, if a server sets a cookie, it will be added to the HttpState instance associated with HttpClient. If you need to get a list of cookies associated with an HttpState, call getCookies( ) to obtain an array of Cookie objects. The following code retrieves an array of Cookie objects, printing the domain, path, name, and value of each Cookie:

HttpClient client = new HttpClient( );

// execute some methods...

Cookie[] cookies = client.getState( ).getCookies( );
for( int i = 0; i < cookies; i++ ) {
    Cookie cookie = cookies[i];
    String domain = cookie.getDomain( );
    String path = cookie.getPath( );
    String name = cookie.getName( );
    String value = cookie.getValue( );
    System.out.println( "Cookie: " + domain + ", " + path + ", " +
                        name + ", " + value );
}

There are two different approaches to cookies floating around the internet: Netscape Draft Specification and RFC 2109. Some servers use the Netscape Draft and others use RFC 2109; because of this, HttpClient offers a COMPATIBILITY mode that should work with most servers. The default cookie policy for HttpClient is the RFC_2109 policy. If you are having problems with cookies, change the cookie policy to the COMPATIBILITY policy, which is a public static int in the CookiePolicy class. To change the cookie policy, call setCookiePolicy() on the HttpState associated with HttpClient, as follows:

HttpClient client = new HttpClient( );

// To use a Compatability policy
client.getState( ).setCookiePolicy(CookiePolicy.COMPATIBILITY);

// To use a Netscape Draft policy
client.getState( ).setCookiePolicy(CookiePolicy.NETSCAPE_DRAFT);

// To use a RFC 2109 policy - this is the default
client.getState( ).setCookiePolicy(CookiePolicy.RFC2109);

There is also a third approach—outlined in RFC 2965—which supercedes RFC 2109. However, there is no code-level support for this third approach in commons yet.

The original cookie specification was written by Netscape, and it can be found at http://wp.netscape.com/newsref/std/cookie_spec.html. RFC 2109 (HTTP State Management Mechanism) is available at http://www.zvon.org/tmRFC/RFC2109/Output/, and the newer RFC 2965 (HTTP State Management Mechanism) can be found at http://www.zvon.org/tmRFC/RFC2965/Output/. Currently, HttpClient does not support the RFC 2965 standard.