Changing the Default VMware Tanzu GemFire in Session Management for AppServers

This topic explains how to set up the VMware Tanzu GemFire Session Management for AppServers.

To use the extension, you must modify your application’s web.xml files. Configuration is slightly different depending on the topology you use.

For more information, see Common Topologies for HTTP Session Management.

Modifying the war file can be done manually or with the modify_war script. To see the command line options for the modify_war script, invoke:

$ modify_war -h

Manual Configuration

To modify your war or ear file manually, make the following updates:

web.xml must have a filter added as follows. If you have your own filters, the GemFire Extension filter must be the first one.

<filter>
    <filter-name>gemfire-session-filter</filter-name>
    <filter-class>
        org.apache.geode.modules.session.filter.SessionCachingFilter
    </filter-class>
    <init-param>
        <param-name>cache-type</param-name>
        <param-value>peer-to-peer</param-value>
    </init-param>
    <init-param>
        <param-name>gemfire.property.locators</param-name>
        <param-value>localhost[10334]</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>gemfire-session-filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Add the following jar files from the AppServer.zip to the WEB-INF/lib directory of the war:
- gemfire-modules jar
- gemfire-modules-session-internal jar
- gemfire-modules-session jar
- slf4j-api jar
- slf4j-jdk14 jar
Add the following jar files from the $GEODE/lib directory to the WEB-INF/lib directory of the war, where $GEODE is set to the Tanzu GemFire product installation:
- antlr jar
- commons-io jar
- commons-lang jar
- commons-validator jar
- fastutil jar
- gemfire-common jar
- gemfire-core jar
- gemfire-deployment-legacy jar
- gemfire-management jar
- gemfire-logging jar
- gemfire-serialization jar
- gemfire-membership jar
- gemfire-tcp-server jar
- javax.transaction-api jar
- jgroups jar
- log4j-api jar
- log4j-core jar
- log4j-jul jar
- micrometer-core jar
- shiro-core jar

If you are deploying an ear file:

Copy all the dependent files, given above, to the lib directory of the ear.

Modify each embedded war file’s manifest by adding a Class-Path entry which references the shared jars added in the previous step. For example:

Manifest-Version: 1.0
Built-By: joe
Build-Jdk: 1.8.0_77
Created-By: Apache Maven
Archiver-Version: Plexus Archiver
Class-Path: lib/gemfire-modules-1.13.3.jar
lib/gemfire-modules-session-internal-1.0.0.jar
lib/gemfire-modules-session-1.0.0.jar
lib/slf4j-api-1.7.7.jar
lib/slf4j-jdk14-1.7.7.jar
lib/antlr-2.7.7.jar
lib/gemfire-membership.1.0.0.jar
lib/gemfire-tcp.1.0.0.jar
lib/fastutil-7.0.2.jar
lib/gemfire-core-1.0.0.jar
lib/gemfire-common.1.0.0.jar
lib/gemfire-management.1.0.0.jar
lib/gemfire-logging.1.0.0.jar
lib/gemfire-serialization.1.0.0.jar
lib/javax.transaction-api-1.3.jar
lib/jgroups-3.6.8.Final.jar
lib/log4j-api-2.5.jar
lib/log4j-core-2.5.jar
lib/log4j-jul-2.5.jar

Peer-to-Peer Setup

peer-to-peer setup

To run Tanzu GemFire in a peer-to-peer configuration, use the modify_war script with options -t peer-to-peer, -p gemfire.property.locators=localhost[10334], and -p gemfire.propery.cache-xml-file=<moduleDir>/conf/cache-peer.xml to result in the following web.xml content:

<filter>
    <filter-name>gemfire-session-filter</filter-name>
    <filter-class>
        org.apache.geode.modules.session.filter.SessionCachingFilter
    </filter-class>
    <init-param>
        <param-name>cache-type</param-name>
        <param-value>peer-to-peer</param-value>
    </init-param>
    <init-param>
        <param-name>gemfire.property.locators</param-name>
        <param-value>localhost[10334]</param-value>
    </init-param>
</filter>

Client/Server Setup

client/server setup

To run Tanzu GemFire in a client/server configuration, you make the application server operate as a Tanzu GemFire client. Use the -t client-server option to the modify_war script. This adds the following filter to application server’s web.xml file:

To run Tanzu GemFire in a client/server configuration, you make the application server operate as a Tanzu GemFire client. Use the modify_war script with options -t client-server and -p gemfire.property.cache-xml-file=<module dir>/conf/cache-client.xml to result in the following web.xml content:

<filter>
    <filter-name>gemfire-session-filter</filter-name>
    <filter-class>
        org.apache.geode.modules.session.filter.SessionCachingFileter
    </filter-class>
    <init-param>
        <param-name>cache-type</param-name>
        <param-value>client-server</param-value>
    </init-param>
    <init-param>
        <param-name>gemfire.property.cache-xml-file</param-name>
        <param-value>module dir/conf/cache-client.xml</param-value>
    </init-param>
</filter>

The cache-client.xml file contains a <pool> element pointing at the locator. Its default value is localhost[10334].

Starting the Application Server

After you update the configuration, you are now ready to start your application server instance. Instantiate the locator first:

$ gfsh start locator --name=locator1

Then start the server:

$ gfsh start server \
    --name=server1 \
    --server-port=0 \
    --locators=localhost[10334] \
    --classpath=<moduleDir>/lib/gemfire-modules-1.13.3.jar:\
<moduleDir>/lib/gemfire-modules-session-internal-1.0.0.jar

Once the application server is started, the Tanzu GemFire client will automatically launch within the application server process.

Verifying that Tanzu GemFire Started

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

info 2016/04/18 10:04:18.685 PDT <localhost-startStop-2> tid=0x1a]
Initializing Tanzu GemFire Modules
Java version:   1.0.0 user1 041816 2016-11-18 08:46:17 -0700
javac 1.8.0_361
Native version: native code unavailable
Source revision: 19dd8eb1907e0beb2aa3e0a17d5f12c6cbec6968
Source repository: develop
Running on: /192.0.2.0, 8 cpu(s), x86_64 Mac OS X 10.11.4

Information is also logged within the Tanzu GemFire log file, which by default is named gemfire_modules.<date>.log.