Database Session Persistence

Database Session Persistence

This feature enables persistence of HTTP sessions to a datasource using JDBC. Persisting HTTP session data to a database allows recovery of the data after a server restart or unexpected server failure. Failover of HTTP sessions can be achieved by configuring multiple servers to persist data to the same location

Enable this feature

To enable the Database Session Persistence feature, add the following element declaration inside the featureManager element in the server.xml file:
<feature>sessionDatabase-1.0</feature>

Developing a feature that depends on this feature

If we are developing a feature that depends on the Database Session Persistence feature, include the following item in the Subsystem-Content header in the feature manifest file for the new feature:
com.ibm.websphere.appserver.sessionDatabase-1.0; type="osgi.subsystem.feature"

Features that this feature enables

Java Database Connectivity 4.0

Feature configuration elements

We can use the following elements in the server.xml file to configure the Database Session Persistence feature:

httpSession

httpSessionDatabase

httpSession

Configuration for HTTP session management.

Attribute name Data type Default value Description
allowOverflow boolean true Allows the number of sessions in memory to exceed the value of the Max in-memory session count property.
alwaysEncodeUrl boolean false The Servlet 2.5 specification specifies to not encode the URL on a response.encodeURL call if it is not necessary. To support backward compatibility when URL encoding is enabled, set this property to true to call the encodeURL method. The URL is always encoded, even if the browser supports cookies.
cloneId string The clone identifier of the cluster member. Within a cluster, this identifier must be unique to maintain session affinity. When set, this name overwrites the default name generated by the server.
cloneSeparator string : The single character used to separate the session identifier from the clone identifier in session cookies. The default value should usually be used. On some Wireless Application Protocol (WAP) devices, a colon (:) is not allowed, so a plus sign (+) should be used instead. Different values should rarely be used. We should understand the clone character requirements of other products running on the system before using this property to change the clone separator character. The fact that any character can be specified as the value for this property does not imply that the character we specify will function correctly. This fact also does not imply that IBM is responsible for fixing any problem that might arise from using an alternative character.
cookieDomain string Domain field of a session tracking cookie.
cookieHttpOnly boolean true That session cookies include the HttpOnly field. Browsers that support the HttpOnly field do not enable cookies to be accessed by client-side scripts. Using the HttpOnly field will help prevent cross-site scripting attacks.
cookieMaxAge A period of time with second precision -1 Maximum amount of time that a cookie can reside on the client browser. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
cookieName string JSESSIONID A unique name for a session management cookie.
cookiePath string / A cookie is sent to the URL designated in the path.
cookieSecure boolean false That the session cookies include the secure field.
cookiesEnabled boolean true That session tracking uses cookies to carry session identifiers.
debugCrossover boolean false Enable this option to perform additional checks to verify that only the session associated with the request is accessed or referenced, and log messages if any discrepancies are detected. Disable this option to skip the additional checks.
forceInvalidationMultiple int 3 If the requests normally are not bound by a response time limit, specify 0 to indicate that the session manager should wait indefinitely until a request is complete before attempting to invalidate the session. Otherwise, set this property to a positive integer to delay the invalidation of active sessions. Active timed out sessions will not be invalidated by the first invalidation interval pass, but will be invalidated by the interval pass based on this value. For example, a value of 2 would invalidate an active session on the second invalidation interval pass after the session timeout has expired.
idLength int 23 Length of the session identifier.
idReuse boolean false In a multi-JVM environment that is not configured for session persistence, setting this property to "true" enables the session manager to use the same session information for all of a user's requests even if the web applications that are handling these requests are governed by different JVMs. The default value for this property is false. Set this property to true to enable the session manager to use the session identifier sent from a browser to preserve session data across web applications running in an environment that is not configured for session persistence.
invalidateOnUnauthorizedSessionRequestException boolean false Set this property to true if, in response to an unauthorized request, we want the session manager to invalidate a session instead of issuing an UnauthorizedSessionRequestException. When a session is invalidated, the requester can create a new session, but does not have access to any of the previously saved session data. This allows a single user to continue processing requests to other applications after a logout while still protecting session data.
invalidationTimeout A period of time with second precision 30m Amount of time a session can go unused before it is no longer valid. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
maxInMemorySessionCount int 1000 Maximum number of sessions to maintain in memory for each web module.
noAdditionalInfo boolean false Forces removal of information that is not needed in session identifiers.
protocolSwitchRewritingEnabled boolean false Adds the session identifier to a URL when the URL requires a switch from HTTP to HTTPS or from HTTPS to HTTP.
reaperPollInterval A period of time with second precision -1 The wake-up interval, in seconds, for the process that removes invalid sessions. The minimum value is 30 seconds. If a value less than the minimum is entered, an appropriate value is automatically determined and used. This value overrides the default installation value, which is between 30 and 360 seconds, based off the session timeout value. Because the default session timeout is 30 minutes, the reaper interval is usually between 2 and 3 minutes. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
rewriteId string jsessionid Use this property to change the key used with URL rewriting.
securityIntegrationEnabled boolean true Enables security integration, which causes the session management facility to associate the identity of users with their HTTP sessions.
securityUserIgnoreCase boolean false Indicates that the session security identity and the client security identity should be considered a match even if their cases are different. For example, when this property is set to true, the session security identity USER1 matches the client security identities User1 and user1.
sslTrackingEnabled boolean false That session tracking uses SSL information as a session identifier.
urlRewritingEnabled boolean false That the session management facility uses rewritten URLs to carry the session identifiers.
useContextRootAsCookiePath boolean false That the cookie path equals the context root of the web module instead of /

httpSessionDatabase

Controls how HTTP sessions are persisted to a database.

Attribute name Data type Default value Description
dataSourceRef string The identifier of the data source the session manager should use to persist HTTP session data.
db2RowSize

32KB

4KB

8KB

16KB

4KB Table space page size configured for the sessions table, if using a DB2 database. Increasing this value can improve database performance in some environments.

32KB

Use a table space page size of 32 KB. We must additionally create a DB2 buffer pool and table space, and specify 32KB as the page size for both. Also specify the name of the table space we created.

4KB

Use the default table space page size of 4 KB. You do not need to create a DB2 buffer pool or table space, and we do not need to specify a table space name.

8KB

Use a table space page size of 8 KB. We must additionally create a DB2 buffer pool and table space, and specify 8KB as the page size for both. Also specify the name of the table space we created.

16KB

Use a table space page size of 16 KB. We must additionally create a DB2 buffer pool and table space, and specify 16KB as the page size for both. Also specify the name of the table space we created.

noAffinitySwitchBack boolean false Set this property to "true" to maintain affinity to the new member even after original one comes back up. When a cluster member fails, its requests routed to a different cluster member, and sessions are activated in that other member. Thus, session affinity is maintained to the new member, and when failed cluster member comes back up, the requests for sessions that were created in the original cluster member are routed back to it. Allowed values are true or false, with the default being false. Set this property to true when we have distributed sessions configured with time-based write. Note that this property has no affect on the behavior when distributed sessions are not enabled.
onlyCheckInCacheDuringPreInvoke boolean false A value of true indicates that the last access time of a session should only be updated if a request gets the session. A value of false indicates that the last access time of a session should be updated upon every request. Changing this value can improve performance in some environments.
optimizeCacheIdIncrements boolean true If the user's browser session is moving back and forth across multiple web applications, we might see extra persistent store activity as the in-memory sessions for a web module are refreshed from the persistent store. As a result, the cache identifiers are continually increasing and the in-memory session attributes are overwritten by those of the persistent copy. Set this property to true to prevent the cache identifiers from continually increasing. A value of true indicates that the session manager should assess whether the in-memory session for a web module is older than the copy in persistent store. If the configuration is a cluster, ensure that the system times of each cluster member are as identical as possible.
scheduleInvalidation boolean false Enable this option to reduce the number of database updates required to keep the HTTP sessions alive. Specify the two hours of a day when there is the least activity in the application server. When this option is disabled, the invalidator process runs every few minutes to remove invalidated HTTP sessions.
scheduleInvalidationFirstHour int 0 Indicates the first hour during which the invalidated sessions are cleared from the persistent store. Specify this value as an integer between 0 and 23. This value is valid only when schedule invalidation is enabled.
scheduleInvalidationSecondHour int 0 Indicates the second hour during which the invalidated sessions are cleared from the persistent store. Specify this value as an integer between 0 and 23. This value is valid only when schedule invalidation is enabled.
skipIndexCreation boolean false Set this property to "true" to disable index creation on server startup. This custom property should only be used to manually create our own database indices for session persistence. However, IBM recommends that you let session manager create database indices. Before enabling this property, verify the correct index does exist on the session database.
tableName string sessions The database table name.
tableSpaceName string Table space to be used for the sessions table. This value is only required when the DB2 Row Size is greater than 4KB.
useInvalidatedId boolean true Set this property to "true" to reuse the incoming identifier if the session with that identifier was recently invalidated. This is a performance optimization because it prevents checking the persistent store.
useMultiRowSchema boolean false When enabled, each session data attribute is placed in a separate row in the database, allowing larger amounts of data to be stored for each session. This configuration can yield better performance when session attributes are very large and few changes are required to the session attributes. When disabled, all session data attributes are placed in the same row for each session.
useOracleBlob boolean false Set this property to "true" to create the database table using the Binary Large Object (BLOB) data type for the medium column. This value increases performance of persistent sessions when Oracle databases are used. Due to an Oracle restriction, BLOB support requires use of the Oracle Call Interface (OCI) database driver for more than 4000 bytes of data. Also ensure that a new sessions table is created before the server is restarted by dropping the old sessions table or by changing the datasource definition to reference a database that does not contain a sessions table.
usingCustomSchemaName boolean false Set this property to "true" if we are using DB2 for session persistence and the currentSchema property is set in the data source.
writeContents

ALL_SESSION_ATTRIBUTES

ONLY_UPDATED_ATTRIBUTES

ONLY_UPDATED_ATTRIBUTES Specifies how much session data should be written to the persistent store. By default, only updated attributes are written, but all attributes can be written instead (regardless of whether or not they changed).

ALL_SESSION_ATTRIBUTES

All attributes are written to the persistent store.

ONLY_UPDATED_ATTRIBUTES

Only updated attributes are written to the persistent store.

writeFrequency

TIME_BASED_WRITE

END_OF_SERVLET_SERVICE

MANUAL_UPDATE

END_OF_SERVLET_SERVICE Specifies when session data is written to the persistent store. By default, session data is written to the persistent store after the servlet completes execution. Changing this value can improve performance in some environments.

TIME_BASED_WRITE

Session data is written to the persistent store based on the specified write interval value.

END_OF_SERVLET_SERVICE

Session data is written to the persistent store after the servlet completes execution.

MANUAL_UPDATE

A programmatic sync on the IBMSession object is required to write the session data to the persistent store.

writeInterval A period of time with second precision 2m Number of seconds that should pass before writing session data to the persistent store. The default is 120 seconds. This value is only used when a time based write frequency is enabled. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

Attribute name	Data type	Default value	Description
allowOverflow	boolean	true	Allows the number of sessions in memory to exceed the value of the Max in-memory session count property.
alwaysEncodeUrl	boolean	false	The Servlet 2.5 specification specifies to not encode the URL on a response.encodeURL call if it is not necessary. To support backward compatibility when URL encoding is enabled, set this property to true to call the encodeURL method. The URL is always encoded, even if the browser supports cookies.
cloneId	string		The clone identifier of the cluster member. Within a cluster, this identifier must be unique to maintain session affinity. When set, this name overwrites the default name generated by the server.
cloneSeparator	string	:	The single character used to separate the session identifier from the clone identifier in session cookies. The default value should usually be used. On some Wireless Application Protocol (WAP) devices, a colon (:) is not allowed, so a plus sign (+) should be used instead. Different values should rarely be used. We should understand the clone character requirements of other products running on the system before using this property to change the clone separator character. The fact that any character can be specified as the value for this property does not imply that the character we specify will function correctly. This fact also does not imply that IBM is responsible for fixing any problem that might arise from using an alternative character.
cookieDomain	string		Domain field of a session tracking cookie.
cookieHttpOnly	boolean	true	That session cookies include the HttpOnly field. Browsers that support the HttpOnly field do not enable cookies to be accessed by client-side scripts. Using the HttpOnly field will help prevent cross-site scripting attacks.
cookieMaxAge	A period of time with second precision	-1	Maximum amount of time that a cookie can reside on the client browser. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
cookieName	string	JSESSIONID	A unique name for a session management cookie.
cookiePath	string	/	A cookie is sent to the URL designated in the path.
cookieSecure	boolean	false	That the session cookies include the secure field.
cookiesEnabled	boolean	true	That session tracking uses cookies to carry session identifiers.
debugCrossover	boolean	false	Enable this option to perform additional checks to verify that only the session associated with the request is accessed or referenced, and log messages if any discrepancies are detected. Disable this option to skip the additional checks.
forceInvalidationMultiple	int	3	If the requests normally are not bound by a response time limit, specify 0 to indicate that the session manager should wait indefinitely until a request is complete before attempting to invalidate the session. Otherwise, set this property to a positive integer to delay the invalidation of active sessions. Active timed out sessions will not be invalidated by the first invalidation interval pass, but will be invalidated by the interval pass based on this value. For example, a value of 2 would invalidate an active session on the second invalidation interval pass after the session timeout has expired.
idLength	int	23	Length of the session identifier.
idReuse	boolean	false	In a multi-JVM environment that is not configured for session persistence, setting this property to "true" enables the session manager to use the same session information for all of a user's requests even if the web applications that are handling these requests are governed by different JVMs. The default value for this property is false. Set this property to true to enable the session manager to use the session identifier sent from a browser to preserve session data across web applications running in an environment that is not configured for session persistence.
invalidateOnUnauthorizedSessionRequestException	boolean	false	Set this property to true if, in response to an unauthorized request, we want the session manager to invalidate a session instead of issuing an UnauthorizedSessionRequestException. When a session is invalidated, the requester can create a new session, but does not have access to any of the previously saved session data. This allows a single user to continue processing requests to other applications after a logout while still protecting session data.
invalidationTimeout	A period of time with second precision	30m	Amount of time a session can go unused before it is no longer valid. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
maxInMemorySessionCount	int	1000	Maximum number of sessions to maintain in memory for each web module.
noAdditionalInfo	boolean	false	Forces removal of information that is not needed in session identifiers.
protocolSwitchRewritingEnabled	boolean	false	Adds the session identifier to a URL when the URL requires a switch from HTTP to HTTPS or from HTTPS to HTTP.
reaperPollInterval	A period of time with second precision	-1	The wake-up interval, in seconds, for the process that removes invalid sessions. The minimum value is 30 seconds. If a value less than the minimum is entered, an appropriate value is automatically determined and used. This value overrides the default installation value, which is between 30 and 360 seconds, based off the session timeout value. Because the default session timeout is 30 minutes, the reaper interval is usually between 2 and 3 minutes. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.
rewriteId	string	jsessionid	Use this property to change the key used with URL rewriting.
securityIntegrationEnabled	boolean	true	Enables security integration, which causes the session management facility to associate the identity of users with their HTTP sessions.
securityUserIgnoreCase	boolean	false	Indicates that the session security identity and the client security identity should be considered a match even if their cases are different. For example, when this property is set to true, the session security identity USER1 matches the client security identities User1 and user1.
sslTrackingEnabled	boolean	false	That session tracking uses SSL information as a session identifier.
urlRewritingEnabled	boolean	false	That the session management facility uses rewritten URLs to carry the session identifiers.
useContextRootAsCookiePath	boolean	false	That the cookie path equals the context root of the web module instead of /

Attribute name	Data type	Default value	Description
dataSourceRef	string		The identifier of the data source the session manager should use to persist HTTP session data.
db2RowSize	32KB 4KB 8KB 16KB	4KB	Table space page size configured for the sessions table, if using a DB2 database. Increasing this value can improve database performance in some environments. 32KB Use a table space page size of 32 KB. We must additionally create a DB2 buffer pool and table space, and specify 32KB as the page size for both. Also specify the name of the table space we created. 4KB Use the default table space page size of 4 KB. You do not need to create a DB2 buffer pool or table space, and we do not need to specify a table space name. 8KB Use a table space page size of 8 KB. We must additionally create a DB2 buffer pool and table space, and specify 8KB as the page size for both. Also specify the name of the table space we created. 16KB Use a table space page size of 16 KB. We must additionally create a DB2 buffer pool and table space, and specify 16KB as the page size for both. Also specify the name of the table space we created.
noAffinitySwitchBack	boolean	false	Set this property to "true" to maintain affinity to the new member even after original one comes back up. When a cluster member fails, its requests routed to a different cluster member, and sessions are activated in that other member. Thus, session affinity is maintained to the new member, and when failed cluster member comes back up, the requests for sessions that were created in the original cluster member are routed back to it. Allowed values are true or false, with the default being false. Set this property to true when we have distributed sessions configured with time-based write. Note that this property has no affect on the behavior when distributed sessions are not enabled.
onlyCheckInCacheDuringPreInvoke	boolean	false	A value of true indicates that the last access time of a session should only be updated if a request gets the session. A value of false indicates that the last access time of a session should be updated upon every request. Changing this value can improve performance in some environments.
optimizeCacheIdIncrements	boolean	true	If the user's browser session is moving back and forth across multiple web applications, we might see extra persistent store activity as the in-memory sessions for a web module are refreshed from the persistent store. As a result, the cache identifiers are continually increasing and the in-memory session attributes are overwritten by those of the persistent copy. Set this property to true to prevent the cache identifiers from continually increasing. A value of true indicates that the session manager should assess whether the in-memory session for a web module is older than the copy in persistent store. If the configuration is a cluster, ensure that the system times of each cluster member are as identical as possible.
scheduleInvalidation	boolean	false	Enable this option to reduce the number of database updates required to keep the HTTP sessions alive. Specify the two hours of a day when there is the least activity in the application server. When this option is disabled, the invalidator process runs every few minutes to remove invalidated HTTP sessions.
scheduleInvalidationFirstHour	int	0	Indicates the first hour during which the invalidated sessions are cleared from the persistent store. Specify this value as an integer between 0 and 23. This value is valid only when schedule invalidation is enabled.
scheduleInvalidationSecondHour	int	0	Indicates the second hour during which the invalidated sessions are cleared from the persistent store. Specify this value as an integer between 0 and 23. This value is valid only when schedule invalidation is enabled.
skipIndexCreation	boolean	false	Set this property to "true" to disable index creation on server startup. This custom property should only be used to manually create our own database indices for session persistence. However, IBM recommends that you let session manager create database indices. Before enabling this property, verify the correct index does exist on the session database.
tableName	string	sessions	The database table name.
tableSpaceName	string		Table space to be used for the sessions table. This value is only required when the DB2 Row Size is greater than 4KB.
useInvalidatedId	boolean	true	Set this property to "true" to reuse the incoming identifier if the session with that identifier was recently invalidated. This is a performance optimization because it prevents checking the persistent store.
useMultiRowSchema	boolean	false	When enabled, each session data attribute is placed in a separate row in the database, allowing larger amounts of data to be stored for each session. This configuration can yield better performance when session attributes are very large and few changes are required to the session attributes. When disabled, all session data attributes are placed in the same row for each session.
useOracleBlob	boolean	false	Set this property to "true" to create the database table using the Binary Large Object (BLOB) data type for the medium column. This value increases performance of persistent sessions when Oracle databases are used. Due to an Oracle restriction, BLOB support requires use of the Oracle Call Interface (OCI) database driver for more than 4000 bytes of data. Also ensure that a new sessions table is created before the server is restarted by dropping the old sessions table or by changing the datasource definition to reference a database that does not contain a sessions table.
usingCustomSchemaName	boolean	false	Set this property to "true" if we are using DB2 for session persistence and the currentSchema property is set in the data source.
writeContents	ALL_SESSION_ATTRIBUTES ONLY_UPDATED_ATTRIBUTES	ONLY_UPDATED_ATTRIBUTES	Specifies how much session data should be written to the persistent store. By default, only updated attributes are written, but all attributes can be written instead (regardless of whether or not they changed). ALL_SESSION_ATTRIBUTES All attributes are written to the persistent store. ONLY_UPDATED_ATTRIBUTES Only updated attributes are written to the persistent store.
writeFrequency	TIME_BASED_WRITE END_OF_SERVLET_SERVICE MANUAL_UPDATE	END_OF_SERVLET_SERVICE	Specifies when session data is written to the persistent store. By default, session data is written to the persistent store after the servlet completes execution. Changing this value can improve performance in some environments. TIME_BASED_WRITE Session data is written to the persistent store based on the specified write interval value. END_OF_SERVLET_SERVICE Session data is written to the persistent store after the servlet completes execution. MANUAL_UPDATE A programmatic sync on the IBMSession object is required to write the session data to the persistent store.
writeInterval	A period of time with second precision	2m	Number of seconds that should pass before writing session data to the persistent store. The default is 120 seconds. This value is only used when a time based write frequency is enabled. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. We can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.