You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Apache Wiki <wi...@apache.org> on 2009/05/13 20:22:55 UTC
[Httpcomponents Wiki] Update of "HttpClientTutorial" by OlegKalnichevski
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Httpcomponents Wiki" for change notification.
The following page has been changed by OlegKalnichevski:
http://wiki.apache.org/HttpComponents/HttpClientTutorial
------------------------------------------------------------------------------
In the course of HTTP request execution HttpClient adds the following attributes to the execution context:
- * 'http.connection' - HttpConnection instance representing the actual connection to the target server.
+ * '''http.connection''' - HttpConnection instance representing the actual connection to the target server.
- * 'http.target_host' - HttpHost instance representing the connection target.
+ * '''http.target_host''' - HttpHost instance representing the connection target.
- * 'http.proxy_host' - HttpHost instance representing the connection proxy, if used.
+ * '''http.proxy_host''' - HttpHost instance representing the connection proxy, if used.
- * 'http.request' - HttpRequest instance representing the actual HTTP request.
+ * '''http.request''' - HttpRequest instance representing the actual HTTP request.
- * 'http.response' - HttpResponse instance representing the actual HTTP response.
+ * '''http.response''' - HttpResponse instance representing the actual HTTP response.
- * 'http.request_sent' - Boolean object representing the flag indicating whether the actual request has been fully transmitted to the connection target.
+ * '''http.request_sent''' - Boolean object representing the flag indicating whether the actual request has been fully transmitted to the connection target.
For instance, in order to determine the final redirect target, one can examine the value of the 'http.target_host' attribute after the request execution:
@@ -1130, +1130 @@
= HTTP state management =
+ Originally HTTP was designed as a stateless, request / response oriented protocol that made no special provisions for stateful sessions spanning across several logically related request / response exchanges. As HTTP protocol grew in popularity and adoption more and more systems began to use it for applications it was never intended for, for instance as a transport for e-commerce applications. Thus, the support for state management became a necessity.
+
+ Netscape Communications, at that time a leadidng developer of web client and server software, implemented support for HTTP state management in their products based on a proprietary specification. Later, Netscape tried to standardize the mechanism by publishing a specification draft. Those efforts contributed to the formal specification defined through the RFC standard track. However, state management in a significant number of applications is still largely based on the Netscape draft and is incompatible with the official specification. All major developers of web browsers felt compelled to retain compatibility with those applications greatly contributing to the fragmentation of standards compliance and compatibility issues.
+
== HTTP cookies ==
- Cookie versions. cookie properties; cookie origin.
+ 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 as a "magic cookie" and the name stuck.
+
+ HttpClient uses Cookie interface to represent an abstract cookie token. In its simples form an HTTP cookie is merely a name / value pair. Usualy 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 maximum period of time the cookie is valid for.
+
+ SetCookie interface represents a {{{Set-Cookie}}} response header sent by the origin server to the HTTP agent in order to maintain a conversational state. SetCookie2 interface extends SetCookie with {{{Set-Cookie2}}} specific methods.
+
+ ClientCookie interface extends Cookie interface with additional client specific functionality such ability to retrieve original cookie attributes exactly as they were specified by the origin server. This is important for generating the {{{Cookie}}} header because some cookie specifications require that the {{{Cookie}}} header should include certain attributes only if they were specified in the {{{Set-Cookie}}} or {{{Set-Cookie2}}} header.
+ === Cookie versions ===
+
+ 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");
+ }}}
+
- == Cookie specs ==
+ == Cookie specifications ==
- === Netscape draft ===
+ CookieSpec interface represents a cookie management specification. Cookie management specification is expected to enforce:
+
+ * rules of parsing {{{Set-Cookie}}} and optionally {{{Set-Cookie2}}} headers.
+
+ * rules of validation of parsed cookies.
+
+ * formatting of {{{Cookie}}} header for a given host, port and path of origin.
- Should be avoided unless absolutely necessary for compatibility with legacy code
+ 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.
- === RFC 2109 ===
+ * '''RFC 2109''': Older version of the official HTTP state management specification superseded by RFC 2965.
- Older version of the standard supreceded by RFC 2965.
+ * '''RFC 2965''': The official HTTP state management specification.
+ * '''Browser compatiblity''': this implementations strives to closely mimic (mis)behavior of common web browser applications such as Microsoft Internet Explorer and Mozilla FireFox.
- === RFC 2965 ===
-
- The standard way of managing HTTP state. Still not very well supported and commonly used.
- === Browser compatiblity ===
+ * '''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.
+
+ 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.
- Garbage in - garbage out.
+ == HTTP cookie and state management parameters ==
- === Best match ===
-
- Picks up a cookie spec based on the properties of the HTTP request.
-
+ These are parameters that be used to customize HTTP state management and behaviour of individual cookie specifications:
+
+ * '''http.protocol.cookie-datepatterns''': defines valid date patterns to be used for parsing non-standard {{{expires}}} attribute. Only required for compatibility with non-compliant servers that still use {{{expires}}} defined in the Netscape draft instead of the standard {{{max-age}}} attribute. This parameter expects a value of type java.util.Collection. The collection elements must be of type java.lang.String compatible with the syntax of java.text.SimpleDateFormat.
+
+ * '''http.protocol.single-cookie-header''': defines whether cookies should be forced into a single {{{Cookie}}} request header. Otherwise, each cookie is formatted as a separate {{{Cookie}}} header. This parameter expects a value of type java.lang.Boolean. Please note this parameter applies to strict cookie specifications (RFC 2109 and RFC 2965) only. Browser compatibility and netscape draft policies will always put all cookies into one request header.
+
+ * '''http.protocol.cookie-policy''': defines the name of a cookie specification to be used for HTTP state management. This parameter expects a value of type java.lang.String.
+
+ == Cookie specification registry ==
+
+ HttpClient maintains a registry of available cookie specifications using CookieSpecRegistry class. The following specifications are registered per default:
+
+ * '''compatibility''': Browser compatiblity (lenient policy).
+
+ * '''netscape''': Netscape draft.
+
+ * '''rfc2109''': RFC 2109 (outdated strict policy).
+
+ * '''rfc2965''': RFC 2965 (standard conformant strict policy).
+
+ * '''best-match''': Best match meta-policy.
+
== Choosing cookie policy ==
- HTTP client level cookie policy can be overriden on the HTTP request level if required.
+ Cookie policy can be set at the HTTP client and overridden on the HTTP request level if required.
+
+ {{{
+ HttpClient httpclient = new DefaultHttpClient();
+ // force strict cookie policy per default
+ httpclient.getParams().setParameter(
+ ClientPNames.COOKIE_POLICY, CookiePolicy.RFC_2965);
+
+ HttpGet httpget = new HttpGet("http://www.broken-server.com/");
+ // Override the default policy for this request
+ httpget.getParams().setParameter(
+ ClientPNames.COOKIE_POLICY, CookiePolicy.BROWSER_COMPATIBILITY);
+ }}}
== Custom cookie policy ==
- Implementing custom CookieSpec.
+ In order to implement a custom cookie policy one should create a custom implementation of CookieSpec interface, create a CookieSpecFactory implementation to create and inialize 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 the standard cookie specifications.
+ {{{
+ CookieSpecFactory csf = new CookieSpecFactory() {
+ public CookieSpec newInstance(HttpParams params) {
+ return new BrowserCompatSpec() {
+ @Override
+ public void validate(Cookie cookie, CookieOrigin origin)
+ throws MalformedCookieException {
+ // Oh, I am easy
+ }
+ };
+ }
+ };
+
+ DefaultHttpClient httpclient = new DefaultHttpClient();
+ httpclient.getCookieSpecs().register("easy", csf);
+ httpclient.getParams().setParameter(
+ ClientPNames.COOKIE_POLICY, "easy");
+ }}}
+
+ == Cookie persistence ==
+
+ HttpClient can work with any physical representation of a persistent cookie store that implements the CookieStore interface. The default CookieStore implementation called BasicClientCookie is a simple, in-memory implementation backed by a java.util.List. Cookies stored in an BasicClientCookie object are lost when the container object get garbage collected. Users can provide more complex implementations if necessary.
+
+ {{{
+ DefaultHttpClient httpclient = new DefaultHttpClient();
+ // Create a local instance of cookie store
+ CookieStore cookieStore = new MyCookieStore();
+ // 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
+ httpclient.setCookieStore(cookieStore);
+ }}}
+
+ == HTTP state management and execution context ==
+
+ In the course of HTTP request execution HttpClient adds the following state management related objects to the execution context:
+
+ * '''http.cookiespec-registry''' - CookieSpecRegistry instance representing the actual cookie specification registry. The value of this attribute set in the local context takes precedence over the default one.
+
+ * '''http.cookie-spec''' - CookieSpec instance representing the actual cookie specification.
+
+ * '''http.cookie-origin''' - CookieOrigin instance representing the actual details of the origin server.
+
+ * '''http.cookie-store''' - CookieStore instance represents the actual cookie store. The value of this attribute set in the local context takes precedence over the default one.
+
+ === Per user / thread state management ===
+
+ One can use an individual local execution context in order to implement per user / thread state management. Cookie specification registry and cookie store defined in the local context will take precedence over the default ones set at the HTTP client level.
+
+ {{{
+ HttpClient httpclient = new DefaultHttpClient();
+ // Create a local instance of cookie store
+ CookieStore cookieStore = new BasicCookieStore();
+ // Create local HTTP context
+ HttpContext localContext = new BasicHttpContext();
+ // Bind custom cookie store to the local context
+ localContext.setAttribute(ClientContext.COOKIE_STORE, cookieStore);
+ HttpGet httpget = new HttpGet("http://www.google.com/");
+ // Pass local context as a parameter
+ HttpResponse response = httpclient.execute(httpget, localContext);
+ }}}
+
= HTTP authentication =
== User credentials ==
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org