XML files for HTTP session manager configuration

When you start a container server that stores HTTP session data, you can either use the default XML files or you can specify customized XML files. These files create specific ObjectGrid names, number of replicas, and so on.

Sample files location

These XML files are packaged in wxs_install_root/ObjectGrid/session/samples for a stand-alone installation or was_root/optionalLibraries/ObjectGrid/session/samples for WebSphere® eXtreme Scale installed in a WebSphere Application Server cell.

Embedded XML package

If you are configuring an embedded scenario, the container server starts in the web container tier. Use the objectGrid.xml file and objectGridDeployment.xml file, which are provided by default. You can update these files to customize the behavior of the HTTP session manager.
Figure 1. objectGrid.xml file
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"	xmlns="http://ibm.com/ws/objectgrid/config">
	<objectGrids>
		<objectGrid name="session" txTimeout="30">
			<bean id="ObjectGridEventListener" className="com.ibm.ws.xs.sessionmanager.SessionHandleManager"/>
			<backingMap name="objectgridSessionMetadata" pluginCollectionRef="objectgridSessionMetadata" readOnly="false" 
					lockStrategy="PESSIMISTIC" ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3600" copyMode="NO_COPY"/>
			<backingMap name="objectgridSessionAttribute.*" template="true" readOnly="false" lockStrategy="PESSIMISTIC" 
					ttlEvictorType="NONE" copyMode="NO_COPY"/>
       <backingMap name="objectgridSessionTTL.*" template="true" readOnly="false" lockStrategy="PESSIMISTIC" 
					ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3600" copyMode="NO_COPY"/>
		</objectGrid>
	</objectGrids>
    <backingMapPluginCollections>
        <backingMapPluginCollection id="objectgridSessionMetadata">
            <bean id="MapEventListener" className="com.ibm.ws.xs.sessionmanager.MetadataMapListener"/>
        </backingMapPluginCollection>
    </backingMapPluginCollections>
</objectGridConfig>
Values you can change:
ObjectGrid name attribute
The value must match the following values in other configuration files:
  • The objectGridName property in the splicer.properties file that is used to splice the web application.
  • The objectgridName attribute in the objectGridDeployment.xml file.
 If you have multiple applications, and you want the session data to be stored in different data grids, those applications must have different ObjectGrid name attribute values.
ObjectGrid txTimeout attribute
This value determines how many seconds a transaction can be open before the container server triggers the transaction to time out. The default is 30 seconds, and can be changed depending on the environment. If the HTTP session persistence is configured with the replicationInterval servlet context initialization parameter value set greater than zero, transactions are batched on a thread. If the replicationInterval property is set to 0, a transaction typically starts when a web application retrieves a valid HttpSession object. The transaction commits at the end of the web application request. If your environment has requests that take longer than 30 seconds, set this value accordingly.
Values you cannot change:
ObjectGridEventListener
The ObjectGridEventListener line cannot be changed and is used internally.
objectgridSessionMetadata
The objectgridSessionMetadata line refers to the map where the HTTP session metadata is stored. There is one entry for every HTTP session stored in the data grid in this map.
objectgridSessionTTL.*
This value cannot be changed and is for future use.
objectgridSessionAttribute.*
The objectgridSessionAttribute.* text defines a dynamic map. This value is used to create the map in which HTTP session attributes are stored when the fragmentedSession parameter is set to true in the splicer.properties file. This dynamic map is called objectgridSessionAttribute. Another map is created based on this template called objectgridSessionAttributeEvicted, which stores sessions that have timed out, but the web container has not invalidated.
A time to live policy (TTL) is defined for the objectgridSessionMetadata map definition. The other map, objectgridSessionAttribute is dependant on this map and does not require a TTL parameter. For each active HTTP session, an entry gets created in the objectgridSessionMetadata map, and one entry in the objectgridSessionAttribute map for every session attribute. If an in-memory session does not exist due to an application server failure or a session is removed from the in-memory cache on the application server, the grid must initiate the session invalidation using the TTL eviction policy. At the time of eviction, the attributes are removed from the objectgridSessionAttribute map and inserted into a dynamically created map called objectgridSessionAttributeEvicted map. The data is stored in this map until an application server can remove the session and complete session invalidation. Therefore, the TTL parameter is only required in the objectgridSessionMetadata map definition.
Note: The objectgridSessionTTL is not used by WebSphere eXtreme Scale in the current release.
The MapEventListener line is internal and cannot be modified.
Figure 2. objectGridDeployment.xml file
<?xml version="1.0" encoding="UTF-8"?>
<deploymentPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/deploymentPolicy ../deploymentPolicy.xsd"
	xmlns="http://ibm.com/ws/objectgrid/deploymentPolicy">

	<objectgridDeployment objectgridName="session">
		<mapSet name="sessionMapSet" numberOfPartitions="5" minSyncReplicas="0" maxSyncReplicas="0" 
				maxAsyncReplicas="1" developmentMode="false" placementStrategy="PER_CONTAINER">
             <map ref="objectgridSessionMetadata"/>
             <map ref="objectgridSessionAttribute.*"/>
             <map ref="objectgridSessionTTL.*"/>
    </mapSet>
   </objectgridDeployment>
</deploymentPolicy>
Values you can change:
ObjectGrid name attribute
The value must match the following values in other configuration files:
  • The objectGridName property in the splicer.properties file that is used to splice the web application.
  • The ObjectGrid name attribute in the objectGrid.xml file.
 If you have multiple applications, and you want the session data to be stored in different data grids, those applications must have different ObjectGrid name attribute values.
mapSet element attributes
You can change all mapSet properties except for the placementStrategy attribute.
Name
Can be updated to any value.
numberOfPartitions
Specifies the number of primary partitions that are started in each server that is hosting the web application. As you add partitions, the data becomes more spread out in the event of a failover. The default value is 5 partitions, and is fine for most applications.
minSyncReplicas, maxSyncReplicas, and maxAsyncReplicas
Specifies the number and type of replicas that store the HTTP session data. The default is 1 asynchronous replica, which is fine for most applications. Synchronous replication occurs during the request path, which can increase the response times for your web application.
developmentMode
Informs the eXtreme Scale placement service whether the replica shards for a partition can be placed on the same node as its primary shard. You can set the value to true in a development environment, but disable this function in a production environment because a node failure could cause the loss of session data.
placementStrategy
Do not change the value of this attribute.
The rest of the file refers to the same map names as in the objectGrid.xml file. These names cannot be changed.
Values you cannot change:
  • The placementStrategy attribute on the mapSet element.

Remote XML package

When you are using the remote mode, where the containers run as stand-alone processes, you must use the objectGridStandAlone.xml file and the objectGridDeploymentStandAlone.xml file to start the processes. You can update these files to modify the configuration.
Figure 3. objectGridStandAlone.xml file
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
	xmlns="http://ibm.com/ws/objectgrid/config">
	<objectGrids>
		<objectGrid name="session" txTimeout="30">
			<bean id="ObjectGridEventListener" className="com.ibm.ws.xs.sessionmanager.SessionHandleManager"/>
            <backingMap name="objectgridSessionMetadata" pluginCollectionRef="objectgridSessionMetadata" 
							readOnly="false" lockStrategy="PESSIMISTIC" ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3600" 
							copyMode="COPY_TO_BYTES"/>
            <backingMap name="objectgridSessionAttribute.*" template="true" readOnly="false" lockStrategy="PESSIMISTIC" 
							ttlEvictorType="NONE" copyMode="COPY_TO_BYTES"/>
            <backingMap name="objectgridSessionTTL.*" template="true" readOnly="false" lockStrategy="PESSIMISTIC" 
							ttlEvictorType="LAST_ACCESS_TIME" timeToLive="3600" copyMode="COPY_TO_BYTES"/>
		</objectGrid>
	</objectGrids>
    <backingMapPluginCollections>
        <backingMapPluginCollection id="objectgridSessionMetadata">
            <bean id="MapEventListener" className="com.ibm.ws.xs.sessionmanager.MetadataMapListener"/>
        </backingMapPluginCollection>
    </backingMapPluginCollections>
</objectGridConfig>
Values you can change:
ObjectGrid name attribute
The value must match the following values in other configuration files:
  • The objectGridName property in the splicer.properties file that is used to splice the web application.
  • The objectgridName attribute in the objectGridStandAlone.xml file.
 If you have multiple applications, and you want the session data to be stored in different data grids, those applications must have different ObjectGrid name attribute values.
ObjectGrid txTimeout attribute
This value determines how many seconds a transaction can be open before the container server triggers the transaction to time out. The default is 30 seconds, and can be changed depending on the environment. If the HTTP session persistence is configured with the replicationInterval servlet context initialization parameter value set greater than zero, transactions are batched on a thread. If the replicationInterval property is set to 0, a transaction typically starts when a web application retrieves a valid HttpSession object. The transaction commits at the end of the web application request. If your environment has requests that take longer than 30 seconds, set this value accordingly.
Values you cannot change:
ObjectGridEventListener
The ObjectGridEventListener line cannot be changed and is used internally.
objectgridSessionMetadata
The objectgridSessionMetadata line refers to the map where the HTTP session metadata is stored. There is one entry for every HTTP session stored in the data grid in this map.
objectgridSessionTTL.*
This value cannot be changed and is for future use.
objectgridSessionAttribute.*
The objectgridSessionAttribute.* text defines a dynamic map. This value is used to create the map in which HTTP session attributes are stored when the fragmentedSession parameter is set to true in the splicer.properties file. This dynamic map is called objectgridSessionAttribute. Another map is created based on this template called objectgridSessionAttributeEvicted, which stores sessions that have timed out, but the web container has not invalidated.
A time to live policy (TTL) is defined for the objectgridSessionMetadata map definition. The other map, objectgridSessionAttribute is dependant on this map and does not require a TTL parameter. For each active HTTP session, an entry gets created in the objectgridSessionMetadata map, and one entry in the objectgridSessionAttribute map for every session attribute. If an in-memory session does not exist due to an application server failure or a session is removed from the in-memory cache on the application server, the grid must initiate the session invalidation using the TTL eviction policy. At the time of eviction, the attributes are removed from the objectgridSessionAttribute map and inserted into a dynamically created map called objectgridSessionAttributeEvicted map. The data is stored in this map until an application server can remove the session and complete session invalidation. Therefore, the TTL parameter is only required in the objectgridSessionMetadata map definition.
Note: The objectgridSessionTTL is not used by WebSphere eXtreme Scale in the current release.

The MetadataMapListener line is internal and cannot be modified.

Figure 4. objectGridDeploymentStandAlone.xml file
<?xml version="1.0" encoding="UTF-8"?>
<deploymentPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/objectgrid/deploymentPolicy ../deploymentPolicy.xsd"
	xmlns="http://ibm.com/ws/objectgrid/deploymentPolicy">

	<objectgridDeployment objectgridName="session">
		<mapSet name="sessionMapSet" numberOfPartitions="47" minSyncReplicas="0" maxSyncReplicas="0" 
			maxAsyncReplicas="1" developmentMode="false" placementStrategy="FIXED_PARTITIONS">
            <map ref="objectgridSessionMetadata"/>
            <map ref="objectgridSessionAttribute.*"/>
            <map ref="objectgridSessionTTL.*"/>
	    </mapSet>
    </objectgridDeployment>
</deploymentPolicy>

Values you can change:

objectgridName attribute
The value must match the following values in other configuration files:
  • The objectGridName property in the splicer.properties file that is used to splice the web application.
  • The ObjectGrid name attribute in the objectGrid.xml file.
If you have multiple applications, and you want the session data to be stored in different data grids, those applications must have different ObjectGrid name attribute values.
mapSet element attributes
You can change all mapSet properties.
Name
Can be updated to any value.
numberOfPartitions
The default fixed partition placement strategy is enabled with the FIXED_PARTITIONS setting. This setting specifies the number of total partitions that are spread across all running grid containers. The default value is 47 partitions, and is fine for most applications. If a per container placement strategy is used with the PER_CONTAINER setting, then this specifies the number of primary partitions started in each grid container. As you add partitions, the data becomes more spread out in the event of a failover. The recommended value is 5 for the per container strategy.
minSyncReplicas, maxSyncReplicas, and maxAsyncReplicas
Specifies the number of primary partitions that are started in each server that is hosting the web application. As you add partitions, the data becomes more spread out in the event of a failover. The default value is 5 partitions, and is fine for most applications.
developmentMode
Informs the eXtreme Scale placement service whether the replica shards for a partition can be placed on the same node as its primary shard. You can set the value to true in a development environment, but disable this function in a production environment because a node failure could cause the loss of session data.
placementStrategy
You can change this attribute to one of the following:
  • FIXED_PARTITIONS This is the default value and is the preferred approach for using a remote HTTP Session topology. It is required if you are using Multi-Master replication
  • PER_CONTAINER This is still a supported configuration in a remote topology.