Changing the Default GemFire Configuration in the AppServers Module

By default, the AppServers module will run GemFire automatically with preconfigured settings. You can change these GemFire settings.

Here are the default settings:
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, or set up a multi-site configuration. This section describes how to change these configuration values.

Note: You cannot override region attributes on the cache server when using the HTTP Session Management Module. You must place all region attribute definitions in the region attributes template that you customize in your application server. See Overriding Region Attributes for more information.

Changing GemFire Distributed System Properties

To edit GemFire system properties (such as how GemFire members locate each other), you must add properties to GemFire Session Filter definition in the application's web.xml file. As mentioned above, this can be done by using the -p option to the modify_war script. All GemFire system properties should be prefix with the string gemfire.property. For example:
  • -p gemfire.property.mcast-port=0
  • -p gemfire.property.locators=hostname[10334]
  • -p gemfire.property.cache-xml-file=/u01/weblogic/conf/cache.xml.
<filter>
    <filter-name>gemfire-session-filter</filter-name>
    <filter-class>
      com.gemstone.gemfire.modules.session.filter.SessionCachingFilter
    </filter-class>
    <init-param>
        <param-name>cache-type</param-name>
        <param-value>client-server</param-value>
    </init-param>
    <init-param>
        <param-name>gemfire.property.mcast-port</param-name>
        <param-value>0</param-value>
    </init-param>
    <init-param>
        <param-name>gemfire.property.locators</param-name>
        <param-value>hostname[10334]</param-value>
    </init-param>
    <init-param>
        <param-name>gemfire.property.cache-xml-file</param-name>
        <param-value>/u01/weblogic/conf/cache.xml</param-value>
    </init-param>
</filter>

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.

The list of configurable 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.

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. For more information about managing the heap, refer to Heap Use and Management.

Note: It is important to note that the GemFire Distributed System is a singleton within the entire application server JVM. As such it is important to ensure that different web applications, within the same container, set (or expect) the same cache configuration. When the application server starts, the first web application to start that uses GemFire Session Caching will determine the overall configuration of the distributed system since it will trigger the creation of the distributed system.

Changing Cache Configuration Properties

To edit GemFire cache properties (such as the name and the characteristics of the cache region), you must configure these using a filter initialization parameter prefix of gemfire.cache with the modify_war script. For example:

-p gemfire.cache.region_name=custom_sessions

<filter>
    <filter-name>gemfire-session-filter</filter-name>
    <filter-class>
      com.gemstone.gemfire.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.cache.region_name</param-name>
        <param-value>custom_sessions</param-value>
    </init-param>
</filter>

The following parameters are the cache configuration parameters that can be added to the filter definition as initialization parameters.

enable_debug_listener

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());
enable_gateway_replication

Whether to enable a gateway; if this parameter is set to true, a GatewayHub must be configured; see Multisite Setup for more information.

Default: false

The GemFire API equivalent to setting this parameter:

// Create factory
AttributesFactory factory = ...; 
<or> RegionFactory factory = ...;
// Set enable gateway
factory.setEnableGateway(true); 
enable_local_cache

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)
region_attributes_id

Specifies the region shortcut; for more information refer to 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); 
region_name

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); 
session_delta_policy

Replication policy for session attributes.

Default: delta_queued

Delta replication can be configured to occur immediately when HttpSession.setAttribute() is called (delta_immediate) or when the HTTP request has completed processing (delta_queued). If the latter mode is configured, all attribute updates for a particular request are 'batched' and multiple updates to the same attribute are collapsed. Depending on the number of attributes updates within a given request, delta_queued may provide a significant performance gain. For complete session attribute integrity across the cache, delta_immediate is recommended. Note that this option is specific to this module and there is no equivalent GemFire API to enable it.

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