/hazelcast-documentation/src/main/docbook/manual/content/HttpSessionClustering.xml

  1<?xml version='1.0' encoding='UTF-8'?>
  2
  3<!--
  4  ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
  5  ~
  6  ~ Licensed under the Apache License, Version 2.0 (the "License");
  7  ~ you may not use this file except in compliance with the License.
  8  ~ You may obtain a copy of the License at
  9  ~
 10  ~ http://www.apache.org/licenses/LICENSE-2.0
 11  ~
 12  ~ Unless required by applicable law or agreed to in writing, software
 13  ~ distributed under the License is distributed on an "AS IS" BASIS,
 14  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 15  ~ See the License for the specific language governing permissions and
 16  ~ limitations under the License.
 17  -->
 18
 19<simplesect version='5.0' xmlns='http://docbook.org/ns/docbook'
 20      xmlns:xi="http://www.w3.org/2001/XInclude"
 21      xmlns:xlink="http://www.w3.org/1999/xlink"
 22      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 23      xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
 24      http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd">
 25
 26    <para>
 27    Say you have more than one web servers (A, B, C) with a load balancer in front of them. If server A goes down
 28    then your users on that server will be directed to one of the live servers (B or C) but their sessions will be lost!
 29    So we have to have all these sessions backed up somewhere if we don't want to lose the sessions upon server crashes.
 30    Hazelcast WM allows you to cluster user http sessions automatically. The following are required for enabling
 31    Hazelcast Session Clustering:
 32    <itemizedlist>
 33        <listitem>
 34            <para>Target application or web server should support Java 1.5+
 35            </para>
 36        </listitem>
 37        <listitem>
 38            <para>Target application or web server should support Servlet 2.4+ spec
 39            </para>
 40        </listitem>
 41        <listitem>
 42            <para>Session objects that needs to be clustered have to be Serializable
 43            </para>
 44        </listitem>
 45    </itemizedlist>
 46    Here are the steps to setup Hazelcast Session Clustering:
 47    <orderedlist>
 48        <listitem>
 49            <para>Put the
 50                <literal>hazelcast</literal>
 51                and
 52                <literal>hazelcast-wm</literal>
 53                jars in your
 54                <literal>WEB-INF/lib</literal>
 55                directory. Optionally if you wish to connect to a cluster as a client add
 56                <literal>hazelcast-client</literal>
 57                as well.
 58            </para>
 59        </listitem>
 60        <listitem>
 61            <para>Put the following xml into
 62                <literal>web.xml</literal>
 63                file. Make sure Hazelcast filter is placed
 64                before all the other filters if any; put it at the top for example.
 65            </para>
 66            <para>
 67                <programlisting language="xml"><![CDATA[
 68<filter>
 69    <filter-name>hazelcast-filter</filter-name>
 70    <filter-class>com.hazelcast.web.WebFilter</filter-class>
 71    <!--
 72        Name of the distributed map storing
 73        your web session objects
 74    -->
 75    <init-param>
 76        <param-name>map-name</param-name>
 77        <param-value>my-sessions</param-value>
 78    </init-param>
 79    <!--
 80        How is your load-balancer configured?
 81        stick-session means all requests of a session
 82        is routed to the node where the session is first created.
 83        This is excellent for performance.
 84        If sticky-session is set to false, when a session is updated
 85        on a node, entry for this session on all other nodes is invalidated.
 86        You have to know how your load-balancer is configured before
 87        setting this parameter. Default is true.
 88    -->
 89    <init-param>
 90        <param-name>sticky-session</param-name>
 91        <param-value>true</param-value>
 92    </init-param>
 93    <!--
 94        Name of session id cookie
 95    -->
 96    <init-param>
 97        <param-name>cookie-name</param-name>
 98        <param-value>hazelcast.sessionId</param-value>
 99    </init-param>
100    <!--
101        Domain of session id cookie. Default is based on incoming request.
102    -->
103    <init-param>
104        <param-name>cookie-domain</param-name>
105        <param-value>.mywebsite.com</param-value>
106    </init-param>
107    <!--
108        Should cookie only be sent using a secure protocol? Default is false.
109    -->
110    <init-param>
111        <param-name>cookie-secure</param-name>
112        <param-value>false</param-value>
113    </init-param>
114    <!--
115        Should HttpOnly attribute be set on cookie ? Default is false.
116    -->
117    <init-param>
118        <param-name>cookie-http-only</param-name>
119        <param-value>false</param-value>
120    </init-param>
121    <!--
122        Are you debugging? Default is false.
123    -->
124    <init-param>
125        <param-name>debug</param-name>
126        <param-value>true</param-value>
127    </init-param>
128    <!--
129        Configuration xml location;
130            * as servlet resource OR
131            * as classpath resource OR
132            * as URL
133        Default is one of hazelcast-default.xml
134        or hazelcast.xml in classpath.
135    -->
136    <init-param>
137        <param-name>config-location</param-name>
138        <param-value>/WEB-INF/hazelcast.xml</param-value>
139    </init-param>
140    <!--
141        Do you want to use an existing HazelcastInstance?
142        Default is null.
143    -->
144    <init-param>
145        <param-name>instance-name</param-name>
146        <param-value>default</param-value>
147    </init-param>
148]]></programlisting>
149 <!-- Splitting xml here, otherwise it won't into pdf page. -->
150<programlisting language="xml"><![CDATA[
151    <!--
152        Do you want to connect as a client to an existing cluster?
153        Default is false.
154    -->
155    <init-param>
156        <param-name>use-client</param-name>
157        <param-value>false</param-value>
158    </init-param>
159    <!--
160        Client configuration location;
161            * as servlet resource OR
162            * as classpath resource OR
163            * as URL
164        Default is null.
165    -->
166    <init-param>
167        <param-name>client-config-location</param-name>
168        <param-value>/WEB-INF/hazelcast-client.properties</param-value>
169    </init-param>
170    <!--
171        Do you want to shutdown HazelcastInstance during
172        web application undeploy process?
173        Default is true.
174    -->
175    <init-param>
176        <param-name>shutdown-on-destroy</param-name>
177        <param-value>true</param-value>
178    </init-param>
179</filter>
180<filter-mapping>
181    <filter-name>hazelcast-filter</filter-name>
182    <url-pattern>/*</url-pattern>
183    <dispatcher>FORWARD</dispatcher>
184    <dispatcher>INCLUDE</dispatcher>
185    <dispatcher>REQUEST</dispatcher>
186</filter-mapping>
187
188<listener>
189    <listener-class>com.hazelcast.web.SessionListener</listener-class>
190</listener>
191]]></programlisting>
192            </para>
193        </listitem>
194        <listitem>
195            <para>Package and deploy your war file as you would normally do.
196            </para>
197        </listitem>
198    </orderedlist>
199
200    It is that easy! All http requests will go through Hazelcast
201    <literal>WebFilter</literal>
202    and it will put the
203    session objects into Hazelcast distributed map if needed.
204    </para>
205
206    <para>
207        <emphasis role="bold">Info about sticky-sessions:</emphasis>
208    </para>
209    <para>
210        Hazelcast holds whole session attributes in a distributed map and in local http session. Local session is required
211        for fast access to data and distributed map is needed for fail-safety.
212        <itemizedlist>
213            <listitem>
214                <para>
215                    <emphasis role="italic">If sticky-session is not used, whenever a session a attribute
216                    is updated in a node (in both node local session and clustered cache),
217                    that attribute should be invalidated in all other nodes' local sessions,
218                    because now they have dirty value. So when a request arrives one of those other nodes
219                    that attribute value is fetched from clustered cache.</emphasis>
220                </para>
221            </listitem>
222
223            <listitem>
224                <para>
225                    <emphasis role="italic">To overcome performance penalty of sending invalidation messages during updates,
226                        sticky-sessions can be used.
227                        If Hazelcast knows sessions are sticky, invalidation will not be send, because Hazelcast assumes there is
228                        no other local session at the moment. When a server is down, requests belonging to a session hold
229                        in that server will routed to other one and that server will fetch session data from clustered cache.
230                        That means using sticky-sessions, one will not suffer performance penalty of accessing clustered data
231                        and can benefit recover from a server failure.</emphasis>
232                </para>
233            </listitem>
234        </itemizedlist>
235    </para>
236
237</simplesect>