hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r792267 [2/2] - in /httpcomponents/httpclient/trunk: ./ src/docbkx/
Date Wed, 08 Jul 2009 19:07:17 GMT
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



Mime
View raw message