Setting Up the HTTP Module for Tomcat

To use the GemFire HTTP module with Tomcat application servers, you will need to modify Tomcat's server.xml and context.xml files.

Configuration is slightly different depending on the topology you are setting up. Refer to Common Topologies for HTTP Session Management for more information.

Peer-to-Peer Setup



To run GemFire in a peer-to-peer configuration, add the following line to Tomcat's $CATALINA_HOME$/conf/server.xml within the <Server> tag:

<Listener className="com.gemstone.gemfire.modules.session.catalina.
                         PeerToPeerCacheLifecycleListener"/>

Depending on the version of Tomcat you are using, add one of the following lines to $CATALINA_HOME$/conf/context.xml within the <Context> tag:

For Tomcat 6.0:
<Manager className="com.gemstone.gemfire.modules.session.catalina.
                         Tomcat6DeltaSessionManager"/> 
For Tomcat 7.0:
<Manager className="com.gemstone.gemfire.modules.session.catalina.
                         Tomcat7DeltaSessionManager"/> 

Without making any further configuration changes, peers attempt to locate each other using a default multicast channel (as defined by the mcast-port property found in Changing GemFire Distributed System Properties). Refer to Peer-to-peer Configuration Using Locators for information on creating and using Locators, which provide both discovery and load balancing services.

Client/Server Setup



To run GemFire in a client/server configuration, the application server will operate as a GemFire client. To do this, add the following line to $CATALINA_HOME$/conf/server.xml within the <Server> tag:

<Listener className="com.gemstone.gemfire.modules.session.catalina.
                         ClientServerCacheLifecycleListener"/>

Depending on the version of Tomcat you are using, add one of the following lines to $CATALINA_HOME$/conf/context.xml within the <Context> tag:

For Tomcat 6.0:
<Manager className="com.gemstone.gemfire.modules.session.catalina.
                         Tomcat6DeltaSessionManager"/> 
For Tomcat 7.0:
<Manager className="com.gemstone.gemfire.modules.session.catalina.
                         Tomcat7DeltaSessionManager"/> 

Since the application server operates as a GemFire client in this configuration, you must manually launch a GemFire cache server. You can do this with the following script (which should be installed into the bin subdirectory):

In Unix: 
  prompt$ ./cacheserver.sh start
  
In Windows:
  prompt> cacheserver.bat start

See Pivotal GemFire Servers for more information on using this script.

If you plan to use the deprecated cacheserver script that comes with the standalone GemFire product instead of the cacheserver script that is provided with the module, you must manually add the following JAR files and directory to the server's classpath:

whereINSTANCE_DIR is the location of the tc Server instance you created with the GemFire template. These items are automatically added to the classpath by the supplied cacheserver.sh (or cacheserver.bat) script that comes with the Tomcat HTTP Session Management module.

Without making any further configuration changes, the client and server attempt to locate each other on the same system using a default port (40404). Though useful for testing purposes, you would not normally deploy a client/server configuration in this way. Refer to Client/Server Configuration Using Locators for information on creating and using Locators, which provide both discovery and load balancing services.

Starting the Application Server

Once you've updated the configuration, you are now ready to start your tc Server or Tomcat instance. Refer to your application server documentation for starting the application server. Once started, GemFire will automatically launch within the application server process.

Note: GemFire session state management provides its own clustering functionality. If you are using GemFire, you should NOT turn on Tomcat clustering as well.

Verifying that GemFire Started

You can verify that GemFire has successfully started by inspecting the Tomcat log file. For example:

Nov 8, 2010 12:12:12 PM
com.gemstone.gemfire.modules.session.catalina.ClientServerCacheLifecycleListener
createOrRetrieveCache
INFO: Created GemFireCache[id = 2066231378; isClosing = false; 
   created = Mon Nov 08 12:12:12 PDT 2010; server = false; 
   copyOnRead = false; lockLease = 120; lockTimeout = 60]

Information is also logged within the GemFire log file, which by default is named "gemfire_modules.log".