LATEST VERSION: 8.2.7 - CHANGELOG
Pivotal GemFire® v8.2

Changing the Default GemFire Configuration in the Tomcat Module

Changing the Default GemFire Configuration in the Tomcat Module

By default, the Tomcat module will run GemFire automatically with pre-configured settings. You can change these GemFire settings.

Here are the default settings:
  • GemFire peer-to-peer members are discovered using a default multicast channel.
  • GemFire locators are not used for member discovery.
  • The region name is set to gemfire_modules_sessions.
  • The cache region is replicated for peer-to-peer configurations and partitioned (with redundancy turned on) for client/server configurations.
  • GemFire clients have local caching turned on and when the local cache needs to evict data, it will evict least-recently-used (LRU) data first.
Note: On the application server side, the default inactive interval for session expiration is set to 30 minutes. To change this value, refer to Session Expiration.

However, you may want to change this default configuration. For example, you might want to change the region from replicated to partitioned, or use locators for discovery. This section describes how to change these configuration values.

Changing GemFire Distributed System Properties

To edit GemFire system properties (such as how GemFire members locate each other), you must add properties to Tomcat's server.xml file. When adding properties, use the following syntax:

<Listener 
  className="com.gemstone.gemfire.modules.session.catalina.xxxLifecycleListener"
  name="value" 
  name="value" 
  ...
/> 

In the preceding code snippet, xxxLifecycleListener is either a PeerToPeerCacheLifecycleListener or a ClientServerCacheLifecycleListener depending on your configuration; name is the property name and value is the property value. For example:

<Listener className="com.gemstone.gemfire.modules.session.catalina.
      PeerToPeerCacheLifecycleListener" 
  cache-xml-file="cache-peer.xml" 
  mcast-port=0
  locators="hostname[10334]" 
/> 

This example specifies that the filename for GemFire's cache xml configuration is cache-peer.xml and that a locator can be found at "hostname:10334". Note that when using a locator, you must turn off multicast discovery by setting the mcast-port property to 0. Locators are explained in more detail in Common GemFire Configuration Changes in Tomcat.

The list of configurable Tomcat's server.xml system properties include any of the properties that can be specified in GemFire's gemfire.properties file. The following list contains some of the more common parameters that can be configured.

Parameter Description Default
cache-xml-file name of the cache configuration file cache-peer.xml for peer-to-peer, cache-client.xml for client/server
locators (only for peer-to-peer config) list of locators (host[port]) used by GemFire members to discover each other; if this value is empty, then multicast discovery will take place instead; when using a locator, you should turn off multicast discovery by setting mcast-port to 0 and you must manually start the locator using a command such as "gemfire start-locator"; refer to " Peer-to-peer Configuration Using Locators" for more information empty string (i.e. use multicast instead)
log-file name of the GemFire log file gemfire_modules.log
mcast-port (only for peer-to-peer config) port used by GemFire members to discover each other using multicast networking; when using locators in place of multicast, this value should be disabled by setting it to 0 10334
statistic-archive-file name of the GemFire statistics file gemfire_modules.gfs
statistic-sampling-enabled whether GemFire statistics sampling is enabled false

For more information on these properties, along with the full list of properties, refer to gemfire.properties and gfsecurity.properties (GemFire Properties).

In addition to the standard GemFire system properties, the following cache-specific properties can also be configured with the LifecycleListener.

Parameter Description Default
criticalHeapPercentage percentage of heap at which updates to the cache are refused 0 (disabled)
evictionHeapPercentage percentage of heap at which session eviction begins 80.0
rebalance whether a rebalance of the cache should be done when the application server instance is started false

Although these properties are not part of the standard GemFire system properties, they apply to the entire JVM instance and are therefore also handled by the LifecycleListener. For more information about managing the heap, refer to Heap Use and Management.

Changing Cache Configuration Properties

To edit GemFire cache properties (such as the name and the characteristics of the cache region), you must add these properties to Tomcat's context.xml file. When adding properties, unless otherwise specified, use the following syntax:

<Manager 
  className="com.gemstone.gemfire.modules.session.catalina.Tomcat7DeltaSessionManager"
  name="value" 
  name="value" 
  ...
/> 

In the preceding code snippet, name is the property name and value is the property value. For example:

<Manager className="com.gemstone.gemfire.modules.session.catalina.
      Tomcat7DeltaSessionManager" 
  regionAttributesId="PARTITION_REDUNDANT" 
  regionName="my_region" 
/> 

This example creates a partitioned region by the name of "my_region".

The following parameters are the cache configuration parameters that can be added to Tomcat's context.xml file.

CommitSessionValve

Whether to wait until the end of the HTTP request to save all session attribute changes to the GemFire cache; if the configuration line is present in the application's context.xml file, then only one put will be performed into the cache for the session per HTTP request. If the configuration line is not included, then the session is saved each time the setAttribute or removeAttribute method is invoked. As a consequence, multiple puts are performed into the cache during a single session. This configuration setting is recommended for any applications that modify the session frequently during a single HTTP request.

Default: Set

To disable this configuration, remove or comment out the following line from Tomcat's context.xml file.

<Valve className="com.gemstone.gemfire.modules.session.catalina.CommitSessionValve"/>
enableDebugListener

Whether to enable a debug listener in the session region; if this parameter is set to true, info-level messages are logged to the GemFire log when sessions are created, updated, invalidated or expired

Default: false

The GemFire API equivalent to setting this parameter:

// Create factory
AttributesFactory factory = ...; <or> RegionFactory factory = ...;
// Add cache listener
factory.addCacheListener(new DebugCacheListener());
enableLocalCache

Whether a local cache is enabled. If this parameter is set to true, the app server load balancer should be configured for sticky session mode

Default: false for peer-to-peer, true for client/server

The GemFire API equivalent to setting this parameter:

// For peer-to-peer members: 
Cache.createRegionFactory (REPLICATE_PROXY) 
// For client members: 
ClientCache.createClientRegionFactory(CACHING_PROXY_HEAP_LRU)
regionAttributesId

Specifies the region shortcut. For more information see Region Shortcuts and Custom Named Region Attributes; when using a partitioned region attribute, it is recommended that you use PARTITION_REDUNDANT (rather than PARTITION) to ensure that the failure of a server does not result in lost session data

Default: REPLICATE for peer-to-peer, PARTITION_REDUNDANT for client/server

The GemFire API equivalent to setting this parameter:

// Creates a region factory for the specified region shortcut 
Cache.createRegionFactory(regionAttributesId); 
regionName

Name of the region

Default: gemfire_modules_sessions

The GemFire API equivalent to setting this parameter:

// Creates a region with the specified name 
RegionFactory.create(regionName); 

Refer to Cache Management for more information about configuring the cache.