Configuration

Adding Maven Dependencies

Note

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

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

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

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

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

Defining Filter

After adding the required libraries in your application, you need to add the filter in the deployment descriptor of your web application. The deployment descriptor is a XML file named 'web.xml' located in the WEB-INF directory under the application root directory. The class file containing the filter implementation is:

com.alachisoft.ncache.web.sessionstate.NCacheSessionStoreProvider

To ensure the correct caching of sessions, you must apply this filter as the first filter in your deployment descriptor. Filters are executed in the order they are defined in deployment descriptor.

To configure a filter, you must define it first under the <filter> tag and then provide a URL mapping for the filter using <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>

NCache Session filter can be configured with the settings specified in 'session.xml' file located at %NC_HOME%/config. You must specify configPath with filter initialization parameter in order to load the configuration settings.

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

Note

The value of 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>%NC_HOME%/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 session module as single-regional or multi-regional module.

Single-Regional Session State Provider

For single-regional session state provider specify session.xml as:

<?xml version="1.0" encoding="UTF-8"?>
<servlet-session-config>
    <cache id="demoClusteredCache"/>
    <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-Regional Session State Provider

You have to specify one 'primary' and one or more 'secondary' caches for each web farm in session.xml. The primary cache will be used for all local traffic and all secondary caches will be used when a user goes to different geography. The sid-prefix defined for each cache in the session.xml file is added to the session ID. This sid-prefix helps in directing client to the cache holding the session.

For multi-regional session module, specify following configuration in 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