from http://hc.apache.org/httpcomponents-client-ga/tutorial/html/statemgmt.html
3.1. HTTP cookies
An HTTP cookie is a token or short packet of state information that the HTTP agent and the target server can exchange to maintain a session. Netscape engineers used to refer to it as a "magic cookie" and the name stuck.
HttpClient uses the Cookie
interface to represent an abstract cookie token. In its simplest form an HTTP cookie is merely a name / value pair. Usually an HTTP cookie also contains a number of attributes such as version, a domain for which is valid, a path that specifies the subset of URLs on the origin server to which this cookie applies, and the maximum period of time for which the cookie is valid.
The SetCookie
interface represents a Set-Cookie
response header sent by the origin server to the HTTP agent in order to maintain a conversational state. TheSetCookie2
interface extends SetCookie with Set-Cookie2
specific methods.
The ClientCookie
interface extends Cookie
interface with additional client specific functionality such as the ability to retrieve original cookie attributes exactly as they were specified by the origin server. This is important for generating theCookie
header because some cookie specifications require that theCookie
header should include certain attributes only if they were specified in theSet-Cookie
or Set-Cookie2
header.
Cookies compatible with Netscape draft specification but non-compliant with the official specification are considered to be of version 0. Standard compliant cookies are expected to have version 1. HttpClient may handle cookies differently depending on the version.
Here is an example of re-creating a Netscape cookie:
BasicClientCookie netscapeCookie = new BasicClientCookie("name", "value"); netscapeCookie.setVersion(0); netscapeCookie.setDomain(".mycompany.com"); netscapeCookie.setPath("/");
Here is an example of re-creating a standard cookie. Please note that standard compliant cookie must retain all attributes as sent by the origin server:
BasicClientCookie stdCookie = new BasicClientCookie("name", "value"); stdCookie.setVersion(1); stdCookie.setDomain(".mycompany.com"); stdCookie.setPath("/"); stdCookie.setSecure(true); // Set attributes EXACTLY as sent by the server stdCookie.setAttribute(ClientCookie.VERSION_ATTR, "1"); stdCookie.setAttribute(ClientCookie.DOMAIN_ATTR, ".mycompany.com");
Here is an example of re-creating a Set-Cookie2
compliant cookie. Please note that standard compliant cookie must retain all attributes as sent by the origin server:
BasicClientCookie2 stdCookie = new BasicClientCookie2("name", "value"); stdCookie.setVersion(1); stdCookie.setDomain(".mycompany.com"); stdCookie.setPorts(new int[] {80,8080}); stdCookie.setPath("/"); stdCookie.setSecure(true); // Set attributes EXACTLY as sent by the server stdCookie.setAttribute(ClientCookie.VERSION_ATTR, "1"); stdCookie.setAttribute(ClientCookie.DOMAIN_ATTR, ".mycompany.com"); stdCookie.setAttribute(ClientCookie.PORT_ATTR, "80,8080");
The CookieSpec
interface represents a cookie management specification. The cookie management specification is expected to enforce:
-
rules of parsing
Set-Cookie
and optionallySet-Cookie2
headers. -
rules of validation of parsed cookies.
-
formatting of
Cookie
header for a given host, port and path of origin.
HttpClient ships with several CookieSpec
implementations:
-
Netscape draft: This specification conforms to the original draft specification published by Netscape Communications. It should be avoided unless absolutely necessary for compatibility with legacy code.
-
Standard: RFC 2965 HTTP state management specification.
-
Browser compatibility: This implementation strives to closely mimic the (mis)behavior of common web browser applications such as Microsoft Internet Explorer and Mozilla FireFox.
-
Best match: 'Meta' cookie specification that picks up a cookie policy based on the format of cookies sent with the HTTP response. It basically aggregates all above implementations into one class.
-
Ignore cookies: All cookies are ignored.
It is strongly recommended to use the Best Match
policy and let HttpClient pick up an appropriate compliance level at runtime based on the execution context.
Cookie policy can be set at the HTTP client and overridden on the HTTP request level if required.
RequestConfig globalConfig = RequestConfig.custom() .setCookieSpec(CookieSpecs.BEST_MATCH) .build(); CloseableHttpClient httpclient = HttpClients.custom() .setDefaultRequestConfig(globalConfig) .build(); RequestConfig localConfig = RequestConfig.copy(globalConfig) .setCookieSpec(CookieSpecs.BROWSER_COMPATIBILITY) .build(); HttpGet httpGet = new HttpGet("/"); httpGet.setConfig(localConfig);
In order to implement a custom cookie policy one should create a custom implementation of theCookieSpec
interface, create a CookieSpecProvider
implementation to create and initialize instances of the custom specification and register the factory with HttpClient. Once the custom specification has been registered, it can be activated the same way as a standard cookie specification.
CookieSpecProvider easySpecProvider = new CookieSpecProvider() { public CookieSpec create(HttpContext context) { return new BrowserCompatSpec() { @Override public void validate(Cookie cookie, CookieOrigin origin) throws MalformedCookieException { // Oh, I am easy } }; } }; Registry<CookieSpecProvider> r = RegistryBuilder.<CookieSpecProvider>create() .register(CookieSpecs.BEST_MATCH, new BestMatchSpecFactory()) .register(CookieSpecs.BROWSER_COMPATIBILITY, new BrowserCompatSpecFactory()) .register("easy", easySpecProvider) .build(); RequestConfig requestConfig = RequestConfig.custom() .setCookieSpec("easy") .build(); CloseableHttpClient httpclient = HttpClients.custom() .setDefaultCookieSpecRegistry(r) .setDefaultRequestConfig(requestConfig) .build();
HttpClient can work with any physical representation of a persistent cookie store that implements theCookieStore
interface. The default CookieStore
implementation called BasicCookieStore
is a simple implementation backed by ajava.util.ArrayList
. Cookies stored in an BasicClientCookie
object are lost when the container object get garbage collected. Users can provide more complex implementations if necessary.
// Create a local instance of cookie store CookieStore cookieStore = new BasicCookieStore(); // Populate cookies if needed BasicClientCookie cookie = new BasicClientCookie("name", "value"); cookie.setVersion(0); cookie.setDomain(".mycompany.com"); cookie.setPath("/"); cookieStore.addCookie(cookie); // Set the store CloseableHttpClient httpclient = HttpClients.custom() .setDefaultCookieStore(cookieStore) .build();
In the course of HTTP request execution HttpClient adds the following state management related objects to the execution context:
-
Lookup
instance representing the actual cookie specification registry. The value of this attribute set in the local context takes precedence over the default one. -
CookieSpec
instance representing the actual cookie specification. -
CookieOrigin
instance representing the actual details of the origin server. -
CookieStore
instance representing the actual cookie store. The value of this attribute set in the local context takes precedence over the default one.
The local HttpContext
object can be used to customize the HTTP state management context prior to request execution, or to examine its state after the request has been executed. One can also use separate execution contexts in order to implement per user (or per thread) state management. A cookie specification registry and cookie store defined in the local context will take precedence over the default ones set at the HTTP client level
CloseableHttpClient httpclient = <...> Lookup<CookieSpecProvider> cookieSpecReg = <...> CookieStore cookieStore = <...> HttpClientContext context = HttpClientContext.create(); context.setCookieSpecRegistry(cookieSpecReg); context.setCookieStore(cookieStore); HttpGet httpget = new HttpGet("http://somehost/"); CloseableHttpResponse response1 = httpclient.execute(httpget, context); <...> // Cookie origin details CookieOrigin cookieOrigin = context.getCookieOrigin(); // Cookie spec used CookieSpec cookieSpec = context.getCookieSpec();