Setting Up the HTTP Module for tc Server

To set up the HTTP Module for tc Server, start a tc Server instance with the appropriate tc Server template based on your preferred topology.

Refer to Common Topologies for HTTP Session Management for more information.

Note: In the procedures that follow, you may be required to log in as root or use sudo to run the commands in Unix, especially if you installed Pivotal tc Server from RPM using yum.

Peer-to-Peer Setup

To run GemFire in a peer-to-peer configuration, create a tc Server instance using the supplied "gemfire-p2p" template:

In Unix:
  prompt$ ./tcruntime-instance.sh create my_instance_name --template gemfire-p2p

In Windows:
  prompt> tcruntime-instance.bat create my_instance_name --template gemfire-p2p

If you do not make any further configuration changes, peers attempt to locate each other using a default multicast channel. You can change the multicast port, as shown in Using a Different Multicast Port. Alternatively, peers can discover each other using locators, which provide both discovery and load balancing services. Refer to Peer-to-peer Configuration Using Locators for more information.

If you need to pin your tc Server instance to a specific version of the tc Runtime, specify the --version parameter in your command to create the tc Server instance. See Pinning a tc Server Runtime Instance to a Specific Version

Client/Server Setup

When you run GemFire in a client/server configuration, the application server (tc Server) operates as a GemFire client. Create a tc Server instance using the supplied "gemfire-cs" template:

In Unix: 
  prompt$ ./tcruntime-instance.sh create my_instance_name --template gemfire-cs

In Windows:
  prompt> tcruntime-instance.bat create my_instance_name --template gemfire-cs

Because 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 for the applicable template):

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

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:

$GEMFIRE/lib/gemfire-modules.jar
INSTANCE_DIR/lib/servlet-api.jar
INSTANCE_DIR/lib/catalina.jar
INSTANCE_DIR/bin/tomcat-util.jar
INSTANCE_DIR/bin/tomcat-juli.jar
INSTANCE_DIR/conf

where INSTANCE_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 tc Server HTTP Session Management module.

With no further configuration changes, the client and server attempt to locate each other on the same system using a default port (40404). Although this is 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.

Note: Because the client/server configuration uses a local client cache by default, it is important to set up your application server for sticky sessions so that application clients access the same application server across a session interval. See General Information on HTTP Session Management for more information.

Pinning a tc Server Runtime Instance to a Specific Version

You can pin a specific version of the tc Server runtime when creating your tc Server instance. To specify the version, use the --version parameter when executing the tcruntime-instance.sh or tcruntime-instance.bat script. For example:

In Unix:
prompt$ ./tcruntime-instance.sh create --version 6.0.32.A.RELEASE \
my_instance_name --template gemfire-cs

In Windows:
prompt> tcruntime-instance.bat create my_instance_name --template gemfire-cs

When you pin the tc Server runtime instance to a specific version, the created instance will always use the specified version, even if you install a more recent version of the tc Server runtime. If you do not specify the --version parameter, the tc Server runtime is automatically pinned to the highest version that you have installed.

To determine the list of available versions, search for INSTALL_DIR/tomcat-XXX directories where XXX follows a pattern such as 6.0.32.A.RELEASE.

Starting the Application Server

Once you've created a tc Server instance, you are ready to start the instance.

In Unix: 
  prompt$ ./tcruntime-ctl.sh my_instance_name start
  
In Windows:
  prompt> ./tcruntime-ctl.bat my_instance_name start

Refer to the tc Server documentation for more information. 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".

Configuring Non-Sticky Session Replication

Some situations require that sessions be 'non-sticky', which means that client requests can be directed to any server in a cluster of application servers instead of the same server each time. To achieve this, you must configure your deployment as described for the following topologies.

Peer-to-Peer

For peer-to-peer topologies, apply the following settings to enable non-sticky sessions to work correctly:

Java system property gemfire.loadClassOnEveryDeserialization=true. Set this property by editing the bin/setenv.sh file.
prefer.deserialized.form=false. Set this property in conf/catalina.properties.

Client-server

For client-server topologies, only the Java system property gemfire.loadClassOnEveryDeserialization=true must be set, in thebin/setenv.sh file.

Note: Non-sticky sessions cause a performance impact because sessions need to be re-created every time a request hits a different server. This may not be noticeable when the session attributes are small, but may become more evident as the session attributes increase in size and/or number.