Java example source code file (httpagent.xml)

This example source code file (httpagent.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

apache, asf, cdata, defaulthttpclient, http, httpcontext, httpget, if, it, license, see, the, this, uri

The httpagent.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="httpagent">
    <title>HTTP client service
    <section>
        <title>HttpClient facade
        <para>HttpClient 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>DefaultHttpClient is the default implementation of the
                <interfacename>HttpClient 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>
        <para>DefaultHttpClient 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.
            They are executed in the same natural order as they are added to the list.</para>
        <programlisting>
        <para>DefaultHttpClient 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 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() method.
        <programlisting>
    </section>
    <section>
        <title>HttpClient parameters
        <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':
                    <para>defines whether redirects should be handled automatically. This parameter
                        expects a value of type <classname>java.lang.Boolean. If this
                        parameter is not HttpClient will handle redirects automatically.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.protocol.reject-relative-redirect':
                    <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. If this parameter is
                        not set relative redirects will be allowed.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.protocol.max-redirects':
                    <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. 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':
                    <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.
                        If this parameter is not set circular redirects will be disallowed.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.connection-manager.factory-class-name':
                    <para>defines the class name of the default
                            <interfacename>ClientConnectionManager implementation.
                        This parameter expects a value of type
                            <classname>java.lang.String. If this parameter is not set
                            <classname>SingleClientConnManager will be used per
                        default.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.virtual-host':
                    <para>defines the virtual host name to be used in the Host
                        header instead of the physical host name. This parameter expects a value of
                        type <classname>HttpHost. 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':
                    <para>defines the request headers to be sent per default with each request. This
                        parameter expects a value of type
                            <interfacename>java.util.Collection containing
                            <interfacename>Header objects.
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.default-host':
                    <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.
                </formalpara>
            </listitem>
        </itemizedlist>
    </section>
    <section>
        <title>Automcatic redirect handling
        <para>HttpClient handles all types of redirects automatically, except those explicitly
            prohibited by the HTTP specification as requiring user intervention. <literal>See
                Other</literal> (status code 303) redirects on POST and
                <literal>PUT requests are converted to GET requests as
            required by the HTTP specification.</para>
    </section>
    <section>
        <title>HTTP client and execution context
        <para>The DefaultHttpClient 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>
    </section>
</chapter>