<?xml version='1.0' encoding='UTF-8'?>

<!--
  ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
  ~
  ~ Licensed 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.
  -->

<simplesect version='5.0' xmlns='http://docbook.org/ns/docbook'
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
      http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd">

    <para>
    Say you have more than one web servers (A, B, C) with a load balancer in front of them. If server A goes down
    then your users on that server will be directed to one of the live servers (B or C) but their sessions will be lost!
    So we have to have all these sessions backed up somewhere if we don't want to lose the sessions upon server crashes.
    Hazelcast WM allows you to cluster user http sessions automatically. The following are required for enabling
    Hazelcast Session Clustering:
    <itemizedlist>
        <listitem>
            <para>Target application or web server should support Java 1.5+
            </para>
        </listitem>
        <listitem>
            <para>Target application or web server should support Servlet 2.4+ spec
            </para>
        </listitem>
        <listitem>
            <para>Session objects that needs to be clustered have to be Serializable
            </para>
        </listitem>
    </itemizedlist>
    Here are the steps to setup Hazelcast Session Clustering:
    <orderedlist>
        <listitem>
            <para>Put the
                <literal>hazelcast</literal>
                and
                <literal>hazelcast-wm</literal>
                jars in your
                <literal>WEB-INF/lib</literal>
                directory. Optionally if you wish to connect to a cluster as a client add
                <literal>hazelcast-client</literal>
                as well.
            </para>
        </listitem>
        <listitem>
            <para>Put the following xml into
                <literal>web.xml</literal>
                file. Make sure Hazelcast filter is placed
                before all the other filters if any; put it at the top for example.
            </para>
            <para>
                <programlisting language="xml"><![CDATA[
<filter>
    <filter-name>hazelcast-filter</filter-name>
    <filter-class>com.hazelcast.web.WebFilter</filter-class>
    <!--
        Name of the distributed map storing
        your web session objects
    -->
    <init-param>
        <param-name>map-name</param-name>
        <param-value>my-sessions</param-value>
    </init-param>
    <!--
        How is your load-balancer configured?
        stick-session means all requests of a session
        is routed to the node where the session is first created.
        This is excellent for performance.
        If sticky-session is set to false, when a session is updated
        on a node, entry for this session on all other nodes is invalidated.
        You have to know how your load-balancer is configured before
        setting this parameter. Default is true.
    -->
    <init-param>
        <param-name>sticky-session</param-name>
        <param-value>true</param-value>
    </init-param>
    <!--
        Name of session id cookie
    -->
    <init-param>
        <param-name>cookie-name</param-name>
        <param-value>hazelcast.sessionId</param-value>
    </init-param>
    <!--
        Domain of session id cookie. Default is based on incoming request.
    -->
    <init-param>
        <param-name>cookie-domain</param-name>
        <param-value>.mywebsite.com</param-value>
    </init-param>
    <!--
        Should cookie only be sent using a secure protocol? Default is false.
    -->
    <init-param>
        <param-name>cookie-secure</param-name>
        <param-value>false</param-value>
    </init-param>
    <!--
        Should HttpOnly attribute be set on cookie ? Default is false.
    -->
    <init-param>
        <param-name>cookie-http-only</param-name>
        <param-value>false</param-value>
    </init-param>
    <!--
        Are you debugging? Default is false.
    -->
    <init-param>
        <param-name>debug</param-name>
        <param-value>true</param-value>
    </init-param>
    <!--
        Configuration xml location;
            * as servlet resource OR
            * as classpath resource OR
            * as URL
        Default is one of hazelcast-default.xml
        or hazelcast.xml in classpath.
    -->
    <init-param>
        <param-name>config-location</param-name>
        <param-value>/WEB-INF/hazelcast.xml</param-value>
    </init-param>
    <!--
        Do you want to use an existing HazelcastInstance?
        Default is null.
    -->
    <init-param>
        <param-name>instance-name</param-name>
        <param-value>default</param-value>
    </init-param>
]]></programlisting>
 <!-- Splitting xml here, otherwise it won't into pdf page. -->
<programlisting language="xml"><![CDATA[
    <!--
        Do you want to connect as a client to an existing cluster?
        Default is false.
    -->
    <init-param>
        <param-name>use-client</param-name>
        <param-value>false</param-value>
    </init-param>
    <!--
        Client configuration location;
            * as servlet resource OR
            * as classpath resource OR
            * as URL
        Default is null.
    -->
    <init-param>
        <param-name>client-config-location</param-name>
        <param-value>/WEB-INF/hazelcast-client.properties</param-value>
    </init-param>
    <!--
        Do you want to shutdown HazelcastInstance during
        web application undeploy process?
        Default is true.
    -->
    <init-param>
        <param-name>shutdown-on-destroy</param-name>
        <param-value>true</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>hazelcast-filter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>INCLUDE</dispatcher>
    <dispatcher>REQUEST</dispatcher>
</filter-mapping>

<listener>
    <listener-class>com.hazelcast.web.SessionListener</listener-class>
</listener>
]]></programlisting>
            </para>
        </listitem>
        <listitem>
            <para>Package and deploy your war file as you would normally do.
            </para>
        </listitem>
    </orderedlist>

    It is that easy! All http requests will go through Hazelcast
    <literal>WebFilter</literal>
    and it will put the
    session objects into Hazelcast distributed map if needed.
    </para>

    <para>
        <emphasis role="bold">Info about sticky-sessions:</emphasis>
    </para>
    <para>
        Hazelcast holds whole session attributes in a distributed map and in local http session. Local session is required
        for fast access to data and distributed map is needed for fail-safety.
        <itemizedlist>
            <listitem>
                <para>
                    <emphasis role="italic">If sticky-session is not used, whenever a session a attribute
                    is updated in a node (in both node local session and clustered cache),
                    that attribute should be invalidated in all other nodes' local sessions,
                    because now they have dirty value. So when a request arrives one of those other nodes
                    that attribute value is fetched from clustered cache.</emphasis>
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="italic">To overcome performance penalty of sending invalidation messages during updates,
                        sticky-sessions can be used.
                        If Hazelcast knows sessions are sticky, invalidation will not be send, because Hazelcast assumes there is
                        no other local session at the moment. When a server is down, requests belonging to a session hold
                        in that server will routed to other one and that server will fetch session data from clustered cache.
                        That means using sticky-sessions, one will not suffer performance penalty of accessing clustered data
                        and can benefit recover from a server failure.</emphasis>
                </para>
            </listitem>
        </itemizedlist>
    </para>

</simplesect>