Configure Hazelcast Session Replication

The Problem

When clustering, either using the deployment groups in Payara 5 or using the clusters in Payara Server 4.x and 5.x, often you will want sessions to be shared across instances, so the user won't be able to differentiate between server instances. This article will show the steps necessary to perform this.

The Solution

Step 1 - Enable Hazelcast

In Payara 5, Hazelcast is enabled by default. In Payara 4 however, Shoal clustering is still the default. In both versions you can enable Hazelcast's session replication in the admin console under Configs -> [your-config] -> Availability Service -> Web Container Availability -> Persistence Type: Hazelcast. This must be enabled for the configuration of the cluster you want the replication to happen across. For example, in Payara 4 this would be the cluster configuration, and in Payara 5 this may be either the cluster or deployment group configuration.

Step 2 - Make Application Distributable

For a deployed application to allow session replication, it must be marked as distributable. To do this, the distributable tag must be added to your application web.xml. If you don't have a web.xml deployment descriptor, it can be created in src/main/webapp/WEB-INF/web.xml.

<web-app version="3.0"
        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">
    <distributable />
</web-app>

Step 3 - Deploy Application with Availability Enabled

When deploying the application, availability must be manually enabled. When deploying from the admin console, there is a checkbox that needs to be ticked:

When deploying from the command line, there is a command flag:

asadmin deploy --availabilityenabled=true ${APPLICATION_ARTIFACT_PATH}

Step 4 - Use a Load Balancer

If the instances are on the same node, this step is unnecessary. If however they are on separate machines, or running in a containerised environment, a load balancer is required to access the instances. This is because the JSessionID cookie corresponds to a specific host, so a load balancer is needed to keep this constant. For a guide on how to configure a load balancer, see the following blog post: https://blog.payara.fish/load-balancing-across-payara-server-instances-with-apache-web-server.

Testing Session Replication

You can deploy the clusterjsp.war application (attached to this article) to test session replication. It will display the session id on the page, to help you identify if the session is replicated.

To test the session replication without a load balancer, create the instances on the same host (e.g. localhost). After this, you can visit the application on each instance in different tabs. If the session id matches, the session is being replicated.