Java example source code file (advanced.xml)

This example source code file (advanced.xml) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java tags/keywords

basichttpcontext, cdata, defaulthttpclient, http, httpcontext, httpentity, httpget, httpresponse, license, myclientconnectionoperator, override, principal, schemeregistry, the

The advanced.xml example source code

<?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 id="advanced">
    <title>Advanced topics
    <section>
        <title>Custom client connections
        <para>In certain situations it may be necessary to customize the way HTTP messages get
            transmitted across the wire beyond what is possible possible using HTTP parameters in
            order to be able to deal non-standard, non-compliant behaviours. For instance, for web
            crawlers it may be necessary to force HttpClient into accepting malformed response heads
            in order to salvage the content of the messages. </para>
        <para>Usually the process of plugging in a custom message parser or a custom connection
            implementation involves several steps:</para>
        <itemizedlist>
            <listitem>
                <para>Provide a custom LineParser /
                        <interfacename>LineFormatter interface implementation.
                    Implement message parsing / formatting logic as required.</para>
                <programlisting>
            </listitem>
            <listitem>
                <para>Provide a custom OperatedClientConnection
                    implementation. Replace default request / response parsers, request / response
                    formatters with custom ones as required. Implement different message writing /
                    reading code if necessary.</para>
                <programlisting>
            </listitem>
            <listitem>
                <para>Provide a custom ClientConnectionOperator
                    interface implementation in order to create connections of new class. Implement
                    different socket initialization code if necessary.</para>
                <programlisting>
            </listitem>
            <listitem>
                <para>Provide a custom ClientConnectionManager
                    interface implementation in order to create connection operator of new
                    class.</para>
                <programlisting>
            </listitem>
        </itemizedlist>
    </section>
    <section id="stateful_conn">
        <title>Stateful HTTP connections
        <para>While HTTP specification assumes that session state information is always embedded in
            HTTP messages in the form of HTTP cookies and therefore HTTP connections are always
            stateless, this assumption does not always hold true in real life. There are cases when
            HTTP connections are created with a particular user identity or within a particular
            security context and therefore cannot be shared with other users and can be reused by
            the same user only. Examples of such stateful HTTP connections are
                <literal>NTLM authenticated connections and SSL connections with client
            certificate authentication.</para>
        <section>
            <title>User token handler
            <para>HttpClient relies on UserTokenHandler interface to
                determine if the given execution context is user specific or not. The token object
                returned by this handler is expected to uniquely identify the current user if the
                context is user specific or to be null if the context does not contain any resources
                or details specific to the current user. The user token will be used to ensure that
                user specific resources will not be shared with or reused by other users.</para>
            <para>The default implementation of the UserTokenHandler
                interface uses an instance of Principal class to represent a state object for HTTP
                connections, if it can be obtained from the given execution context.
                    <classname>DefaultUserTokenHandler will use the user principle of
                connection based authentication schemes such as <literal>NTLM or that of
                the SSL session with client authentication turned on. If both are unavailable, null
                token will be returned.</para>
            <para>Users can provide a custom implementation if the default one does not satisfy
                their needs:</para>
            <programlisting>
        </section>
        <section>
            <title>User token and execution context
            <para>In the course of HTTP request execution HttpClient adds the following user
                identity related objects to the execution context: </para>
            <itemizedlist>
                <listitem>
                    <formalpara>
                        <title>'http.user-token':
                        <para>Object instance representing the actual user identity, usually
                            expected to be an instance of <interfacename>Principle
                            interface</para>
                    </formalpara>
                </listitem>
            </itemizedlist>
            <para>One can find out whether or not the connection used to execute the request was
                stateful by examining the content of the local HTTP context after the request has
                been executed.</para>
            <programlisting>
            <section>
                <title>Persistent stateful connections
                <para>Please note that persistent connection that carry a state object can be reused
                    only if the same state object is bound to the execution context when requests
                    are executed. So, it is really important to ensure the either same context is
                    reused for execution of subsequent HTTP requests by the same user or the user
                    token is bound to the context prior to request execution.</para>
                <programlisting>
            </section>
        </section>

    </section>

</chapter>