Alachisoft NCache 4.1 - Online Documentation

NCache Java Session Module

 
NCache is an in-memory distributed caching solution developed in .NET and it has its own TCP/IP based socket protocol which allows Java applications to use NCache caching directly instead of going through any bridge.
Now, NCache also provides no-code change option for Java based web applications to store sessions in NCache by implementing session module NCacheSessionProvider as a Java filter. In order to use NCache java session module, you must be running a Servlet 2.3 compatible container (web server). You only need reference of few libraries and add a filter in web.xml of your application so that all the requests will comes to your application through NCache filter.
 
Following J2EE platforms are supported:
 
  • Tomcat
  • Web Logic
  • WebSphere
  • JBoss
 
 
Configuring application to use Java Session Module:
 
NCache provides no-code change option for Java applications for storing sessions in NCache distributed caching. Here are the steps that you need to follow to configure your Java application for using NCache as a distributed session store.
 
Adding Libraries:
 
You need to add required libraries. You can find these Java libraries at following path. %INSTALL_PATH% is the location where NCache is installed. If you are using IDE just add references to these files in the project, if you are not using IDE then you need to copy these files to 'WEB-INF/lib' folder under the application root folder.
 
On Linux: %INSTALL_PATH%/ncache/lib/
On Windows: %INSTALL_PATH%/NCache/java/lib/
 
  • NCActivate.jar (The NCache java client library to validate licensing information)
  • NCClient.jar (The NCache java client library that actually implements NCache communication protocol)
  • NCacheSessionProvider.jar (The HTTP module implementation for session caching using NCache)
  • NCRuntime.jar (The NCache java client library that implements Read-through/Write-through caching and Cache Startup operations)
  • NCSerialization.jar (The NCache java client library that actually implements dynamic compact serialization and object sharing operations)
  • javassist.jar (The NCache java 3rd party library responsible for runtime code generation)
 
Add the following to 'classes' folder in WEB-INF of your application:
 
  • javaReg.properties (The file containing licensing information. You can place this file under 'classes' directory of your web application)
 
 
Defining filter:
 
After adding required libraries in your application, you need to add the filter in the deployment descriptor of your web application. Deployment descriptor is 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.NSessionStoreProvider '.
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 create 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.sessionstate.NSessionStoreProvider </filter-class>
</filter>
 
<filter-mapping>
<filter-name> NCacheSessionProvider </filter-name>
<url-pattern> /* </url-pattern>
</filter-mapping>
 
NCache Session filter can be configured with a number of initialization parameters. The following are the required parameters.
 
<init-param>
<description> Name of running cache that will be used to persist session state.</description>
<param-name> cacheName </param-name>
<param-value> mycache </param-value>
</init-param>
<init-param>
<description> configPath is used to load the client.ncconf </description>
<param-name> configPath </param-name>
<param-value> %INSTALL_PATH%/config/ </param-value>
</init-param>
 
%INSTALL_PATH% is the location where NCache is installed.
 
Following is 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.sessionstate.NSessionStoreProvider</filter-class>
<init-param>
<description> Name of running cache that will be used to persist session state.</description>
<param-name> cacheName </param-name>
<param-value> mycache </param-value>
</init-param>
<init-param>
<description> configPath is used to load the client.ncconf </description>
<param-name> configPath </param-name>
<param-value> C:\Program Files/NCache/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>
</web-app>
 
 
Deploying application:
 
By default this sample application uses 'mycache' to store the session data. So make sure that cache 'mycache' exist in the 'client.ncconf' file located at '%INSTALL_PATH%/config/' with correct server IP Address and this cache should be started. %INSTALL_PATH% is location where NCache is installed. Following is an example of how the 'client.ncconf' should look like.
 
<?xml version = "1.0" encoding = "UTF-8"?>
<configuration>
<ncache-server connection-retries = "5" retry-interval = "1" client-request-timeout = "90" connection-timeout = "5" port = "9800"/>
<cache id = "mycache" client-cache-id = "" client-cache-syncmode = "optimistic" load-balance = "true" >
<server name = "20.200.20.41"/>
<! -- This is the server IP Address where mycache is running -- >
</cache>
</configuration>
 
Windows:
 
Follow the below mentioned steps to deploy application on the respected server.
 
 
Apache Tomcat:
 
Following instructions use tomcat version 6.0.29. Steps remain the same but the location of the files might change depending upon the version of the tomcat. For the following steps %TOMCAT_HOME% refers to the location where Tomcat is installed and %NCACHE_HOME% refers to the location where NCache is installed.
 
  1. Open the command prompt, change directory to '%TOMCAT_HOME%/bin' and execute 'shutdown.bat'. This will stop the server.
  2. NCache uses 'log4j' for logging. Place the 'log4j' at the following location.'%TOMCAT_HOME%/lib'
  3. Create a new text document with following contents and save it with the name of 'log4j.properties' in the '%TOMCAT_HOME%/lib' folder.log4j.rootLogger=DEBUG, R
    log4j.appender.R=org.apache.log4j.RollingFileAppender
    log4j.appender.R.File=${catalina.home}/logs/tomcat.log
    log4j.appender.R.MaxFileSize=10MB
    log4j.appender.R.MaxBackupIndex=10
    log4j.appender.R.layout=org.apache.log4j.PatternLayout
    log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
  4. Download the 'commons-logging-x.x.x-bin.zip' from http://commons.apache.org/logging/download_logging.cgi extract it and copy the 'commons-logging-x.x.x.jar' file into the following location.
    '%TOMCAT_HOME%/lib'
  5. Open the command prompt, change directory to '%TOMCAT_HOME%/bin' and execute 'startup.bat'. This will start the server.
  6. Move the 'GuessGame.war' file located at '%NCACHE_HOME%/samples/java/bin' to the directory '%TOMCAT_HOME%/webapps'.
  7. Open the web browser and try to access the following URL:http://host:port/GuessGame/index.jsp
    Where 'host' will be the address/IP of the machine where Tomcat is installed in case of local machine it should be 'localhost', and 'port' where Tomcat is listening the request. The default port for Tomcat is 8080.
 
WebLogic:
 
For the following steps %WEBLOGIC_HOME% refers to the location where WebLogic is installed. %DOMAIN_NAME% is the domain already created on the server. %NCACHE_HOME% refers to the location where NCache is installed.
 
  1. NCache uses 'log4j' for logging. Place the 'log4j' at the following location and restart server:
    '%WEBLOGIC_HOME%/user_projects/domains/%DOMAIN_NAME%/lib'
  2. Move the 'GuessGame.war' file located at '%NCACHE_HOME%/samples/java/bin' to the directory '%WEBLOGIC_HOME%/user_projects/domains/%DOMAIN_NAME%/autodeploy'.
  3. Open the web browser and try to access the following URL:http://host:port/GuessGame/index.jsp
    Where 'host' will be the address/IP of the machine where WebLogic is installed in case of local machine it should be 'localhost', and 'port' where WebLogic is listening the request. The default port for WebLogic is 7001.
 
WebSphere:
 
For the following steps %WEBSPHERE_HOME% refers to the location where WebSphere is installed and %NCACHE_HOME% refers to the location where NCache is installed.
 
  1. NCache uses 'log4j' for logging. Place the 'log4j' at the following location and restart server:
    '%WEBSPHERE_HOME%/AppServer/lib/ext'
  2. If WebSphere is installed properly, you will be able to access the admin console through browser with the help of the following url:http://ip-address:port/ibm/console/
    By default, 9060 is the port used by WAS. Make sure that your are using the correct port if you changed it during installation.
  3. You can go to Applications --> New Application --> New Enterprise Application.
  4. Specify the path of the 'GuessGame.war' file and click Next. You can locate the 'GuessGame.war' at the following location'%NCACHE_HOME%/samples/java/bin'
  5. Select Fast Path installation mode and click Next.
  6. Specify the Application Name and Application Directory and click Next. Both Application Name and Application Directory should be 'GuessGame'.
  7. Map the application to the server, Select 'GuessGame.war' from the list with the default settings and click Next.
  8. Map the application to the virtual host, Select 'GuessGame.war' from the list with the default settings and click Next.
  9. Map the context root to the application, type 'GuessGame' into the textbox resulting in '/GuessGame' as the contents of the textbox and click Next.
  10. Click the Finish button to complete the deployment.
  11. Go to Applications --> Application Types --> WebSphere enterprise applications.
  12. You should see the GuessGame application in the list, select the GuessGame application by clicking on the checkbox and press the start button at the top left, you should see a green icon showing that application has started.
  13. Open the web browser and try to access the following URL:http://host:port/GuessGame/index.jsp
    Where 'host' will be the address/IP of the machine where WebSphere is installed in case of local machine it should be 'localhost' and 'port' where WebSphere is listening the request. Make sure that you are using the correct port. The default port for WebSphere is 9080.
 
JBoss:
 
For the following steps %JBOSS_HOME% refers to the location where JBoss is installed and %NCACHE_HOME% refers to the location where NCache is installed.
 
  1. NCache uses 'log4j' for logging. JBoss by default uses 'log4j' for logging so no need to place it.
  2. Move the 'GuessGame.war' file located at '%NCACHE_HOME%/samples/java/bin' to the directory '%JBOSS_HOME%/server/default/deploy'.
  3. Open the web browser and try to access the following URL:http://host:port/GuessGame/index.jsp
    Where 'host' will be the address/IP of the machine where JBoss is installed in case of local machine it should be 'localhost', and 'port' where JBoss is listening the request. The default port for JBoss is 8080.
 
Linux:
 
Follow the below mentioned steps to deploy application on the respected server.
 
Apache Tomcat:
 
Following instructions use tomcat version 6.0.29. Steps remain the same but the location of the files might change depending upon the version of the tomcat. For the following steps %TOMCAT_HOME% refers to the location where Tomcat is installed and %NCACHE_HOME% refers to the location where NCache is installed.
 
  1. Open the command prompt, change directory to '%TOMCAT_HOME%/bin' and execute 'shutdown.sh'. This will stop the server.
  2. NCache uses 'log4j' for logging. Place the 'log4j' at the following location.'%TOMCAT_HOME%/lib'
  3. Create a new text document with following contents and save it with the name of 'log4j.properties' in the '%TOMCAT_HOME%/lib' folder.log4j.rootLogger=DEBUG, R
    log4j.appender.R=org.apache.log4j.RollingFileAppender
    log4j.appender.R.File=${catalina.home}/logs/tomcat.log
    log4j.appender.R.MaxFileSize=10MB
    log4j.appender.R.MaxBackupIndex=10
    log4j.appender.R.layout=org.apache.log4j.PatternLayout
    log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
  4. Download the 'commons-logging-x.x.x-bin.zip' from http://commons.apache.org/logging/download_logging.cgi
    extract it and copy the 'commons-logging-x.x.x.jar' file into the following location.
    '%TOMCAT_HOME%/lib'.
  5. Open the command prompt, change directory to '%TOMCAT_HOME%/bin' and execute 'startup.sh'. This will start the server.
  6. Move the 'GuessGame.war' file located at '%NCACHE_HOME%/samples/bin' to the directory '%TOMCAT_HOME%/webapps'.
  7. Open the web browser and try to access the following URL:http://host:port/GuessGame/index.jsp
    Where 'host' will be the address/IP of the machine where Tomcat is installed in case of local machine it should be 'localhost', and 'port' where Tomcat is listening the request. The default port for Tomcat is 8080.
 
WebLogic:
 
For the following steps %WEBLOGIC_HOME% refers to the location where WebLogic is installed. %DOMAIN_NAME% is the domain already created on the server. %NCACHE_HOME% refers to the location where NCache is installed.
 
  1. NCache uses 'log4j' for logging. Place the 'log4j' at the following location and restart server:
    '%WEBLOGIC_HOME%/user_projects/domains/%DOMAIN_NAME%/lib'
  2. Move the 'GuessGame.war' file located at '%NCACHE_HOME%/samples/bin' to the directory '%WEBLOGIC_HOME%/user_projects/domains/%DOMAIN_NAME%/autodeploy'.
  3. Open the web browser and try to access the following URL:http://host:port/GuessGame/index.jsp
    Where 'host' will be the address/IP of the machine where WebLogic is installed in case of local machine it should be 'localhost', and 'port' where WebLogic is listening the request. The default port for WebLogic is 7001.
 
JBoss:
 
For the following steps %JBOSS_HOME% refers to the location where JBoss is installed and %NCACHE_HOME% refers to the location where NCache is installed.
 
  1. NCache uses 'log4j' for logging. JBoss by default uses 'log4j' for logging so no need to place it.
  2. Move the 'GuessGame.war' file located at '%NCACHE_HOME%/samples/bin' to the directory '%JBOSS_HOME%/server/default/deploy'.
  3. Open the web browser and try to access the following URL:http://host:port/GuessGame/index.jsp
    Where 'host' will be the address/IP of the machine where JBoss is installed in case of local machine it should be 'localhost', and 'port' where JBoss is listening the request. The default port for JBoss is 8080.
 
 
See Also

 
Copyright © 2005-2012 Alachisoft. All rights reserved.