You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2009/07/08 21:07:17 UTC
svn commit: r792267 [2/2] - in /httpcomponents/httpclient/trunk: ./
src/docbkx/
Added: httpcomponents/httpclient/trunk/src/docbkx/httpagent.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/httpagent.xml?rev=792267&view=auto
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/httpagent.xml (added)
+++ httpcomponents/httpclient/trunk/src/docbkx/httpagent.xml Wed Jul 8 19:07:17 2009
@@ -0,0 +1,203 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!--
+ ====================================================================
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ ====================================================================
+-->
+<chapter>
+ <title>HTTP client service</title>
+ <section>
+ <title>HttpClient facade</title>
+ <para><interfacename>HttpClient</interfacename> interface represents the most essential
+ contract for HTTP request execution. It imposes no restrictions or particular details on
+ the request execution process and leaves the specifics of connection management, state
+ management, authentication and redirect handling up to individual implementations. This
+ should make it easier to decorate the interface with additional functionality such as
+ response content caching.</para>
+ <para><classname>DefaultHttpClient</classname> is the default implementation of the
+ <interfacename>HttpClient</interfacename> interface. This class acts as a facade to
+ a number of special purpose handler or strategy interface implementations responsible
+ for handling of a particular aspect of the HTTP protocol such as redirect or
+ authentication handling or making decision about connection persistence and keep alive
+ duration. This enables the users to selectively replace default implementation of those
+ aspects with custom, application specific ones.</para>
+ <programlisting><![CDATA[
+DefaultHttpClient httpclient = new DefaultHttpClient();
+
+httpclient.setKeepAliveStrategy(new DefaultConnectionKeepAliveStrategy() {
+
+ @Override
+ public long getKeepAliveDuration(
+ HttpResponse response,
+ HttpContext context) {
+ long keepAlive = super.getKeepAliveDuration(response, context);
+ if (keepAlive == -1) {
+ // Keep connections alive 5 seconds if a keep-alive value
+ // has not be explicitly set by the server
+ keepAlive = 5000;
+ }
+ return keepAlive;
+ }
+
+});
+]]></programlisting>
+ <para><classname>DefaultHttpClient</classname> also maintains a list of protocol
+ interceptors intended for processing outgoing requests and incoming responses and
+ provides methods for managing those interceptors. New protocol interceptors can be
+ introduced to the protocol processor chain or removed from it if needed. Internally
+ protocol interceptors are stored in a simple <classname>java.util.ArrayList</classname>.
+ They are executed in the same natural order as they are added to the list.</para>
+ <programlisting><![CDATA[
+DefaultHttpClient httpclient = new DefaultHttpClient();
+httpclient.removeRequestInterceptorByClass(RequestUserAgent.class);
+httpclient.addRequestInterceptor(new HttpRequestInterceptor() {
+
+ public void process(
+ HttpRequest request, HttpContext context)
+ throws HttpException, IOException {
+ request.setHeader(HTTP.USER_AGENT, "My-own-client");
+ }
+
+});
+]]></programlisting>
+ <para><classname>DefaultHttpClient</classname> is thread safe. It is recommended that the
+ same instance of this class is reused for multiple request executions. When an instance
+ of <classname>DefaultHttpClient</classname> is no longer needed and is about to go out
+ of scope the connection manager associated with it must be shut down by calling the
+ <methodname>ClientConnectionManager#shutdown()</methodname> method.</para>
+ <programlisting><![CDATA[
+HttpClient httpclient = new DefaultHttpClient();
+// Do something useful
+httpclient.getConnectionManager().shutdown();
+]]></programlisting>
+ </section>
+ <section>
+ <title>HttpClient parameters</title>
+ <para>These are parameters that be used to customize the behaviour of the default HttpClient
+ implementation:</para>
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>'http.protocol.handle-redirects':</title>
+ <para>defines whether redirects should be handled automatically. This parameter
+ expects a value of type <classname>java.lang.Boolean</classname>. If this
+ parameter is not HttpClient will handle redirects automatically.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.protocol.reject-relative-redirect':</title>
+ <para>defines whether relative redirects should be rejected. HTTP specification
+ requires the location value be an absolute URI. This parameter expects a
+ value of type <classname>java.lang.Boolean</classname>. If this parameter is
+ not set relative redirects will be allowed.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.protocol.max-redirects':</title>
+ <para>defines the maximum number of redirects to be followed. The limit on
+ number of redirects is intended to prevent infinite loops caused by broken
+ server side scripts. This parameter expects a value of type
+ <classname>java.lang.Integer</classname>. If this parameter is not set
+ no more than 100 redirects will be allowed.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.protocol.allow-circular-redirects':</title>
+ <para>defines whether circular redirects (redirects to the same location) should
+ be allowed. The HTTP spec is not sufficiently clear whether circular
+ redirects are permitted, therefore optionally they can be enabled. This
+ parameter expects a value of type <classname>java.lang.Boolean</classname>.
+ If this parameter is not set circular redirects will be disallowed.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.connection-manager.factory-class-name':</title>
+ <para>defines the class name of the default
+ <interfacename>ClientConnectionManager</interfacename> implementation.
+ This parameter expects a value of type
+ <classname>java.lang.String</classname>. If this parameter is not set
+ <classname>SingleClientConnManager</classname> will be used per
+ default.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.virtual-host':</title>
+ <para>defines the virtual host name to be used in the <literal>Host</literal>
+ header instead of the physical host name. This parameter expects a value of
+ type <classname>HttpHost</classname>. If this parameter is not set name or
+ IP address of the target host will be used.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.default-headers':</title>
+ <para>defines the request headers to be sent per default with each request. This
+ parameter expects a value of type
+ <interfacename>java.util.Collection</interfacename> containing
+ <interfacename>Header</interfacename> objects.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.default-host':</title>
+ <para>defines the default host. The default value will be used if the target
+ host is not explicitly specified in the request URI (relative URIs). This
+ parameter expects a value of type <classname>HttpHost</classname>.</para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Automcatic redirect handling</title>
+ <para>HttpClient handles all types of redirects automatically, except those explicitly
+ prohibited by the HTTP specification as requiring user intervention. Redirects on
+ <literal>POST</literal> and <literal>PUT</literal> requests are converted to
+ <literal>GET</literal> requests as required by the HTTP specification.</para>
+ </section>
+ <section>
+ <title>HTTP client and execution context</title>
+ <para>The <classname>DefaultHttpClient</classname> treats HTTP requests as immutable objects
+ that are never supposed to change in the course of request execution. Instead, it
+ creates a private mutable copy of the original request object, whose properties can be
+ updated depending on the execution context. Therefore the final request properties such
+ as the target host and request URI can be determined by examining the content of the
+ local HTTP context after the request has been executed.</para>
+ <programlisting><![CDATA[
+DefaultHttpClient httpclient = new DefaultHttpClient();
+
+HttpContext localContext = new BasicHttpContext();
+HttpGet httpget = new HttpGet("http://localhost:8080/");
+HttpResponse response = httpclient.execute(httpget, localContext);
+HttpHost target = (HttpHost) localContext.getAttribute(
+ ExecutionContext.HTTP_TARGET_HOST);
+HttpUriRequest req = (HttpUriRequest) localContext.getAttribute(
+ ExecutionContext.HTTP_REQUEST);
+
+System.out.println("Target host: " + target);
+System.out.println("Final request URI: " + req.getURI());
+System.out.println("Final request method: " + req.getMethod());
+]]></programlisting>
+ </section>
+</chapter>
Propchange: httpcomponents/httpclient/trunk/src/docbkx/httpagent.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: httpcomponents/httpclient/trunk/src/docbkx/index.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/index.xml?rev=792267&r1=792266&r2=792267&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/index.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/index.xml Wed Jul 8 19:07:17 2009
@@ -62,5 +62,10 @@
<xi:include href="preface.xml"/>
<xi:include href="fundamentals.xml"/>
-
+ <xi:include href="connmgmt.xml"/>
+ <xi:include href="statemgmt.xml"/>
+ <xi:include href="authentication.xml"/>
+ <xi:include href="httpagent.xml"/>
+ <xi:include href="advanced.xml"/>
+
</book>
Modified: httpcomponents/httpclient/trunk/src/docbkx/preface.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/preface.xml?rev=792267&r1=792266&r2=792267&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/preface.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/preface.xml Wed Jul 8 19:07:17 2009
@@ -48,7 +48,7 @@
<listitem>
<para>
Client-side HTTP transport library based on <ulink
- url="http://hc.apache.org/httpcomponents-core/index.html/">HttpCore</ulink>
+ url="http://hc.apache.org/httpcomponents-core/index.html">HttpCore</ulink>
</para>
</listitem>
<listitem>
Added: httpcomponents/httpclient/trunk/src/docbkx/statemgmt.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/statemgmt.xml?rev=792267&view=auto
==============================================================================
--- httpcomponents/httpclient/trunk/src/docbkx/statemgmt.xml (added)
+++ httpcomponents/httpclient/trunk/src/docbkx/statemgmt.xml Wed Jul 8 19:07:17 2009
@@ -0,0 +1,392 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!--
+ ====================================================================
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ ====================================================================
+-->
+<chapter>
+ <title>HTTP state management</title>
+ <para>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.</para>
+ <para>Netscape Communications, at that time a leading 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 standardise 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.</para>
+ <section>
+ <title>HTTP cookies</title>
+ <para>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.</para>
+ <para>HttpClient uses <interfacename>Cookie</interfacename> interface to represent an
+ abstract cookie token. In its simples 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 maximum period of time the cookie is valid for.</para>
+ <para><interfacename>SetCookie</interfacename> interface represents a
+ <literal>Set-Cookie</literal> response header sent by the origin server to the HTTP
+ agent in order to maintain a conversational state.
+ <interfacename>SetCookie2</interfacename> interface extends SetCookie with
+ <literal>Set-Cookie2</literal> specific methods.</para>
+ <para><interfacename>ClientCookie</interfacename> interface extends
+ <interfacename>Cookie</interfacename> 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
+ <literal>Cookie</literal> header because some cookie specifications require that the
+ <literal>Cookie</literal> header should include certain attributes only if they were
+ specified in the <literal>Set-Cookie</literal> or <literal>Set-Cookie2</literal>
+ header.</para>
+ <section>
+ <title>Cookie versions</title>
+ <para>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.</para>
+ <para>Here is an example of re-creating a Netscape cookie:</para>
+ <programlisting><![CDATA[
+BasicClientCookie netscapeCookie = new BasicClientCookie("name", "value");
+netscapeCookie.setVersion(0);
+netscapeCookie.setDomain(".mycompany.com");
+netscapeCookie.setPath("/");
+]]></programlisting>
+ <para>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:</para>
+ <programlisting><![CDATA[
+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");
+]]></programlisting>
+ <para>Here is an example of re-creating a <literal>Set-Cookie2</literal> compliant
+ cookie. Please note that standard compliant cookie must retain all attributes as
+ sent by the origin server:</para>
+ <programlisting><![CDATA[
+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");
+]]></programlisting>
+ </section>
+ </section>
+ <section>
+ <title>Cookie specifications</title>
+ <para><interfacename>CookieSpec</interfacename> interface represents a cookie management
+ specification. Cookie management specification is expected to enforce:</para>
+ <itemizedlist>
+ <listitem>
+ <para>rules of parsing <literal>Set-Cookie</literal> and optionally
+ <literal>Set-Cookie2</literal> headers.</para>
+ </listitem>
+ <listitem>
+ <para>rules of validation of parsed cookies.</para>
+ </listitem>
+ <listitem>
+ <para>formatting of <literal>Cookie</literal> header for a given host, port and path
+ of origin.</para>
+ </listitem>
+ </itemizedlist>
+ <para>HttpClient ships with several <interfacename>CookieSpec</interfacename>
+ implementations:</para>
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>Netscape draft:</title>
+ <para>This specification conforms to the original draft specification published
+ by Netscape Communications. It should be avoided unless absolutely necessary
+ for compatibility with legacy code.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>RFC 2109:</title>
+ <para>Older version of the official HTTP state management specification
+ superseded by RFC 2965.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>RFC 2965:</title>
+ <para>The official HTTP state management specification.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Browser compatibility:</title>
+ <para>This implementations strives to closely mimic (mis)behavior of common web
+ browser applications such as Microsoft Internet Explorer and Mozilla
+ FireFox.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>Best match:</title>
+ <para>'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.</para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ <para>It is strongly recommended to use the <literal>Best Match</literal> policy and let
+ HttpClient pick up an appropriate compliance level at runtime based on the execution
+ context.</para>
+ </section>
+ <section>
+ <title>HTTP cookie and state management parameters</title>
+ <para>These are parameters that be used to customize HTTP state management and behaviour of
+ individual cookie specifications:</para>
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>'http.protocol.cookie-datepatterns':</title>
+ <para>defines valid date patterns to be used for parsing non-standard
+ <literal>expires</literal> attribute. Only required for compatibility
+ with non-compliant servers that still use <literal>expires</literal> defined
+ in the Netscape draft instead of the standard <literal>max-age</literal>
+ attribute. This parameter expects a value of type
+ <interfacename>java.util.Collection</interfacename>. The collection
+ elements must be of type <classname>java.lang.String</classname> compatible
+ with the syntax of <classname>java.text.SimpleDateFormat</classname>. If
+ this parameter is not set the choice of a default value is
+ <interfacename>CookieSpec</interfacename> implementation specific.
+ Please note this parameter applies</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.protocol.single-cookie-header':</title>
+ <para>defines whether cookies should be forced into a single
+ <literal>Cookie</literal> request header. Otherwise, each cookie is
+ formatted as a separate <literal>Cookie</literal> header. This parameter
+ expects a value of type <classname>java.lang.Boolean</classname>. If this
+ parameter is not set the choice of a default value is CookieSpec
+ implementation specific. 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.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.protocol.cookie-policy':</title>
+ <para>defines the name of a cookie specification to be used for HTTP state
+ management. This parameter expects a value of type
+ <classname>java.lang.String</classname>. If this parameter is not set
+ valid date patterns are <interfacename>CookieSpec</interfacename>
+ implementation specific.</para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Cookie specification registry</title>
+ <para>HttpClient maintains a registry of available cookie specifications using
+ <classname>CookieSpecRegistry</classname> class. The following specifications are
+ registered per default:</para>
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>compatibility:</title>
+ <para> Browser compatibility (lenient policy).</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>netscape:</title>
+ <para>Netscape draft.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>rfc2109:</title>
+ <para>RFC 2109 (outdated strict policy).</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>rfc2965:</title>
+ <para>RFC 2965 (standard conformant strict policy).</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>best-match:</title>
+ <para>Best match meta-policy.</para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Choosing cookie policy</title>
+ <para>Cookie policy can be set at the HTTP client and overridden on the HTTP request level
+ if required.</para>
+ <programlisting><![CDATA[
+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);
+]]></programlisting>
+ </section>
+ <section>
+ <title>Custom cookie policy</title>
+ <para>In order to implement a custom cookie policy one should create a custom implementation
+ of <interfacename>CookieSpec</interfacename> interface, create a
+ <interfacename>CookieSpecFactory</interfacename> 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 the standard cookie specifications.</para>
+ <programlisting><![CDATA[
+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");
+]]></programlisting>
+ </section>
+ <section>
+ <title>Cookie persistence</title>
+ <para>HttpClient can work with any physical representation of a persistent cookie store that
+ implements the <interfacename>CookieStore</interfacename> interface. The default
+ <interfacename>CookieStore</interfacename> implementation called
+ <classname>BasicClientCookie</classname> is a simple implementation backed by a
+ <classname>java.util.ArrayList</classname>. Cookies stored in an
+ <classname>BasicClientCookie</classname> object are lost when the container object
+ get garbage collected. Users can provide more complex implementations if
+ necessary.</para>
+ <programlisting><![CDATA[
+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);
+]]></programlisting>
+ </section>
+ <section>
+ <title>HTTP state management and execution context</title>
+ <para>In the course of HTTP request execution HttpClient adds the following state management
+ related objects to the execution context:</para>
+ <itemizedlist>
+ <listitem>
+ <formalpara>
+ <title>'http.cookiespec-registry':</title>
+ <para><classname>CookieSpecRegistry</classname> instance representing the actual
+ cookie specification registry. The value of this attribute set in the local
+ context takes precedence over the default one.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.cookie-spec':</title>
+ <para><interfacename>CookieSpec</interfacename> instance representing the actual
+ cookie specification.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.cookie-origin':</title>
+ <para><classname>CookieOrigin</classname> instance representing the actual
+ details of the origin server.</para>
+ </formalpara>
+ </listitem>
+ <listitem>
+ <formalpara>
+ <title>'http.cookie-store':</title>
+ <para><interfacename>CookieStore</interfacename> instance represents the actual
+ cookie store. The value of this attribute set in the local context takes
+ precedence over the default one.</para>
+ </formalpara>
+ </listitem>
+ </itemizedlist>
+ <para>The local <interfacename>HttpContext</interfacename> object can be used to customize
+ the HTTP state management context prior to request execution or examine its state after
+ the request has been executed:</para>
+ <programlisting><![CDATA[
+HttpClient httpclient = new DefaultHttpClient();
+HttpContext localContext = new BasicHttpContext();
+HttpGet httpget = new HttpGet("http://localhost:8080/");
+HttpResponse response = httpclient.execute(httpget, localContext);
+
+CookieOrigin cookieOrigin = (CookieOrigin) localContext.getAttribute(
+ ClientContext.COOKIE_ORIGIN);
+System.out.println("Cookie origin: " + cookieOrigin);
+CookieSpec cookieSpec = (CookieSpec) localContext.getAttribute(
+ ClientContext.COOKIE_SPEC);
+System.out.println("Cookie spec used: " + cookieSpec);
+]]></programlisting>
+ </section>
+ <section>
+ <title>Per user / thread state management</title>
+ <para>One can use an individual local execution context in order to implement per user (or
+ per 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.</para>
+ <programlisting><![CDATA[
+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);
+]]></programlisting>
+ </section>
+</chapter>
Propchange: httpcomponents/httpclient/trunk/src/docbkx/statemgmt.xml
------------------------------------------------------------------------------
svn:eol-style = native