//
// 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.
//

=== HTTP Session Replication

Apache Karaf Cellar supports replication of the HTTP sessions on the cluster.

It means that the same web application deployed on multiple nodes in the cluster will share the same HTTP sessions
pool, allowing clients to transparently connect to any node, without losing any session state.

==== Enable Cluster HTTP Session Replication

In order to be able to be stored on the cluster, all HTTP Sessions used in your web application have to implement
Serializable interface. Any non-serializable attribute has to be flagged as transient.

You have to enable a specific filter in your application to enable the replication. See next chapter for details.

At runtime level, you just have to install `http`, `http-whiteboard`, and `cellar` features:

----
karaf@root()> feature:install http
karaf@root()> feature:install http-whiteboard
karaf@root()> feature:repo-add cellar
karaf@root()> feature:install cellar
----

==== Web Application Session Replication

In order to use HTTP session replication on the cluster, you just have to add a filter in your web application.

Basically, the `WEB-INF/web.xml` file of your web application should look like this:

----
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
	version="3.0">

	<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>false</param-value>
		</init-param>
	    <!--
	        Are you debugging? Default is false.
	    -->
		<init-param>
			<param-name>debug</param-name>
			<param-value>false</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>

</web-app>
----
