Add Maven Dependencies and Data Filter for Java Sessions

This page provides the steps required to add Maven Dependencies and defining filter for single-site and multi-site session providers to configure Web Sessions with NCache.

Adding Maven Dependencies for Java Sessions

When using the NCache session caching module with Tomcat version 10 or lower, the user needs to add the following Maven dependencies to their pom.xml file:

<dependency>
    <groupId>com.alachisoft.ncache</groupId>
    <artifactId>ncache-javax-sessions</artifactId>
    <version>x.x.x</version>
</dependency>

For Tomcat version 10+, add the following Maven <dependency> in the pom.xml file.

<dependency>
    <groupId>com.alachisoft.ncache</groupId>
    <artifactId>ncache-sessions</artifactId>
    <version>x.x.x</version>
</dependency>

It will add all the .jar files to your project.

Note

To use Maven packages for the NCache Professional, change the <artifactId> as shown in: <artifactId>ncache-professional-sessions</artifactId>.

Defining Filter for Java Sessions

After adding the required Maven dependencies to your application, you need to add the filter in the deployment descriptor of your web application. The deployment descriptor is an XML file named web.xml located in the WEB-INF directory under the application root directory. To ensure correct session caching, apply this as the first filter in your deployment descriptor (as filters execute in the order defined in the deployment descriptor). The class file containing the filter implementation is as shown below:

com.alachisoft.ncache.web.sessionstate.NCacheSessionStoreProvider

To configure a filter, you must define it first under the <filter> tag and then provide a URL mapping for the filter using the <filter-mapping> tag. The following filter configuration means that the filter will be applied to all the URLs in a web application.

<filter>
    <filter-name>NCacheSessionProvider</filter-name>
    <filter-class>com.alachisoft.ncache.web.session.NCacheSessionProvider</filter-class>
</filter>
<filter-mapping>
    <filter-name>NCacheSessionProvider</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

You can configure the NCache session filter with the settings specified in the session.xml file located at %NCHOME%/config. You must specify the configPath with the filter initialization parameter to load the configuration settings.

<init-param>
    <param-name>configPath</param-name>
    <param-value>%NCHOME%/config</param-value>
</init-param>

Note

The value of the configPath must be the installation directory of NCache.

The following is an example of how the deployment descriptor should look like after defining the filter.

<session-config>
    <session-timeout>30</session-timeout>
</session-config>
<filter>
    <filter-name>NCacheSessionProvider</filter-name>
    <filter-class>com.alachisoft.ncache.web.session.NCacheSessionProvider</filter-class>
    <init-param>
        <param-name>configPath</param-name>
        <param-value>%NCHOME%/config</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>NCacheSessionProvider</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
<welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
</welcome-file-list>

You can configure the session module as single-regional or multi-regional.

Single-Site Session State Provider

For a single-regional session state provider, specify the session.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<servlet-session-config>
    <cache id="demoCache"/>
    <log log-props="log4j.properties"/>
    <locking enable-session-locking="true" retries-count="2" retry-interval="500ms" lock-timeout="36000ms" empty-session-when-locked="false"/>
</servlet-session-config>

Multi-Site Session State Provider

You have to specify one primary and one secondary caches for each web farm in the session.xml file. The primary cache will be used for all local traffic and all the secondary caches will be used when a user is redirected to a different region. The sid-prefix defined for each cache in the session.xml file is added to the session id. This sid-prefix helps direct the client to the cache holding the session.

For the multi-regional session module, specify the following configuration in the session.xml file:

<servlet-session-config>
    <log log-props="log4j.properties"/>
    <locking enable-session-locking="true" retries-count="2" retry-interval="500ms" lock-timeout="36000ms" empty-session-when-locked="false"/>
    <multi-site-cache>
        <primary-cache id="LondonCache" sid-prefix="LDNC"/>
        <secondary-cache id="TokyoCache" sid-prefix="TKYC"/>
        <secondary-cache id="NewYorkCache" sid-prefix="NYKC"/>
    </multi-site-cache>
</servlet-session-config>

See Also

Deploying Application
Multi-site Java Session Support
Error Logging