Java example source code file (statemgmt.xml)

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

basicclientcookie, cdata, cookieorigin, cookiespec, defaulthttpclient, http, httpclient, httpget, license, netscape, please, rfc, the, this

The statemgmt.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="statemgmt">
    <title>HTTP state management
    <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
        <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 Cookie 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>SetCookie interface represents a
                <literal>Set-Cookie response header sent by the origin server to the HTTP
            agent in order to maintain a conversational state.
                <interfacename>SetCookie2 interface extends SetCookie with
                <literal>Set-Cookie2 specific methods.
        <para>ClientCookie interface extends
                <interfacename>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
                <literal>Cookie header because some cookie specifications require that the
                <literal>Cookie header should include certain attributes only if they were
            specified in the <literal>Set-Cookie or Set-Cookie2
            header.</para>
        <section>
            <title>Cookie versions
            <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:
            <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>
            <para>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:</para>
            <programlisting>
        </section>
    </section>
    <section>
        <title>Cookie specifications
        <para>CookieSpec interface represents a cookie management
            specification. Cookie management specification is expected to enforce:</para>
        <itemizedlist>
            <listitem>
                <para>rules of parsing Set-Cookie and optionally
                        <literal>Set-Cookie2 headers.
            </listitem>
            <listitem>
                <para>rules of validation of parsed cookies.
            </listitem>
            <listitem>
                <para>formatting of Cookie header for a given host, port and path
                    of origin.</para>
            </listitem>
        </itemizedlist>
        <para>HttpClient ships with several CookieSpec
            implementations:</para>
        <itemizedlist>
            <listitem>
                <formalpara>
                    <title>Netscape draft:
                    <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:
                    <para>Older version of the official HTTP state management specification
                        superseded by RFC 2965.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>RFC 2965:
                    <para>The official HTTP state management specification.
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>Browser compatibility:
                    <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:
                    <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 Best Match 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
        <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':
                    <para>defines valid date patterns to be used for parsing non-standard
                            <literal>expires attribute. Only required for compatibility
                        with non-compliant servers that still use <literal>expires defined
                        in the Netscape draft instead of the standard <literal>max-age
                        attribute. This parameter expects a value of type
                            <interfacename>java.util.Collection. The collection
                        elements must be of type <classname>java.lang.String compatible
                        with the syntax of <classname>java.text.SimpleDateFormat. If
                        this parameter is not set the choice of a default value is
                            <interfacename>CookieSpec implementation specific.
                        Please note this parameter applies</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.protocol.single-cookie-header':
                    <para>defines whether cookies should be forced into a single
                            <literal>Cookie request header. Otherwise, each cookie is
                        formatted as a separate <literal>Cookie header. This parameter
                        expects a value of type <classname>java.lang.Boolean. 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':
                    <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. If this parameter is not set
                        valid date patterns are <interfacename>CookieSpec
                        implementation specific.</para>
                </formalpara>
            </listitem>
        </itemizedlist>
    </section>
    <section>
        <title>Cookie specification registry
        <para>HttpClient maintains a registry of available cookie specifications using
                <classname>CookieSpecRegistry class. The following specifications are
            registered per default:</para>
        <itemizedlist>
            <listitem>
                <formalpara>
                    <title>compatibility:
                    <para> Browser compatibility (lenient policy).
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>netscape:
                    <para>Netscape draft.
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>rfc2109:
                    <para>RFC 2109 (outdated strict policy).
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>rfc2965:
                    <para>RFC 2965 (standard conformant strict policy).
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>best-match:
                    <para>Best match meta-policy.
                </formalpara>
            </listitem>
        </itemizedlist>
    </section>
    <section>
        <title>Choosing cookie policy
        <para>Cookie policy can be set at the HTTP client and overridden on the HTTP request level
            if required.</para>
        <programlisting>
    </section>
    <section>
        <title>Custom cookie policy
        <para>In order to implement a custom cookie policy one should create a custom implementation
            of <interfacename>CookieSpec interface, create a
                <interfacename>CookieSpecFactory 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>
    </section>
    <section>
        <title>Cookie persistence
        <para>HttpClient can work with any physical representation of a persistent cookie store that
            implements the <interfacename>CookieStore interface. The default
                <interfacename>CookieStore implementation called
                <classname>BasicClientCookie is a simple implementation backed by a
                <classname>java.util.ArrayList. Cookies stored in an
                <classname>BasicClientCookie object are lost when the container object
            get garbage collected. Users can provide more complex implementations if
            necessary.</para>
        <programlisting>
    </section>
    <section>
        <title>HTTP state management and execution context
        <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':
                    <para>CookieSpecRegistry 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':
                    <para>CookieSpec instance representing the actual
                        cookie specification.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.cookie-origin':
                    <para>CookieOrigin instance representing the actual
                        details of the origin server.</para>
                </formalpara>
            </listitem>
            <listitem>
                <formalpara>
                    <title>'http.cookie-store':
                    <para>CookieStore 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 HttpContext 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>
    </section>
    <section>
        <title>Per user / thread state management
        <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>
    </section>
</chapter>