Add Maven Dependencies and Data Filter

Adding Maven Dependencies

The user needs to add the following Maven <dependency> in their pom.xml file while working with the NCache session caching module with a Tomcat version 10 or lesser. It will add all the .jar files to your project.

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

Note

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

Defining Filter

After adding the required libraries 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 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 or more 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 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

Conceptual Overview
Deploying Application
Multi-site Java Session Support
Error Logging