A number of changes related to configuring clustering of web applications have been made for the JBoss AS 5.0.0.GA release. To summarize:
- There is no longer a need to configure a "UseJK" property on the JBoss Web service configuration to enable specialized failover handling when AJP is used. By default the session manager treats the presence of a jvmRoute attribute on the server.xml Engine element as an indication that the specialized handling is needed.
- Passivation of clustered web app sessions can be configured. See "Distributable HttpSession Passivation".
- A number of configurations that in AS 4 could only be specified on a server-wide basis can now be configured on a per-webapp basis.
- A configurable deployer has been added that supplies default values. A number of configuration elements previously on the JBoss Web service configuration have been moved to this deployer.
Configuration of how a distributable webapp's session manager should handle webapp sessions is done via a jboss-web.xml file in the war's WEB-INF directory. (That is, configuration other than adding the <distributable/> element to web.xml that tells JBoss Web that a cluster-aware session manager should be used.)
Following is an example jboss-web.xml that includes all configuration elements relevant to the clustered session manager. Note that all of these elements are optional if you are happy with the default values:
<!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 5.0//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd"> <jboss-web> <replication-config> <cache-name>custom-session-cache</cache-name> <replication-trigger>SET</replication-trigger> <replication-granularity>ATTRIBUTE</replication-granularity> <replication-field-batch-mode>true</replication-field-batch-mode> <use-jk>false</use-jk> <max-unreplicated-interval>30</max-unreplicated-interval> <snapshot-mode>instant</snapshot-mode> <snapshot-interval>1000</snapshot-interval> <session-notification-policy>org.jboss.web.tomcat.service.session.notification.IgnoreUndeployLegacyClusteredSessionNotificationPolicy</session-notification-policy> </replication-config> <max-active-sessions>10</max-active-sessions> <passivation-config> <use-session-passivation>true</use-session-passivation> <passivation-min-idle-time>120</passivation-min-idle-time> <passivation-max-idle-time>600</passivation-max-idle-time> </passivation-config> </jboss-web>
Details on the above elements:
First, the following elements are retained from the 4.x releases:
Determines when the container should consider that session data must be replicated across the cluster.
Possible values are:
1 - "SET_AND_GET"
Determines the granularity of what gets replicated if the container determines session replication is needed.
|replication-field-batch-mode||Determine whether to batch the replication when the granularity level is set to FIELD. If this is set to true, fine-grained changes made to @Replicable objects stored in the session attribute map will replicate only when the http request is finished; otherwise they replicate as they occur. Setting this to false is not advised. Default is true.|
The following replication-related settings are new in AS 5:
|cache-name||Name of the JBoss Cache configuration that should be used for storing distributable sessions and replicating them around the cluster. Allows webapp's that need different caching characteristics to specify the use of separate, differently configured, JBoss Cache instances. In AS 4 the cache to use was a server-wide configuration that could not be changed per webapp. See CacheManager service for more details. The default value is standard-session-cache if the replication-granularity is not FIELD, field-granularity-session-cache if it is.|
Whether the container should assume a JK-based software load balancer (e.g. mod_jk, mod_proxy, mod_cluster) is used for load balancing for this webapp. If set to true, the container will examine the session id associated with every request and replace the JvmRoute portion of the session id if it detects a failover.
The default value is null (i.e. unspecified), in which case the session manager will use the presence or absence of a jvmRoute configuration on its enclosing JBoss Web Engine (configured via server.xml) as indicating whether JK is used.
The only real reason to set this element is to set it to false for a particular webapp whose URL's the JK load balancer doesn't handle. Even doing that isn't really necessary.
Determines the maximum interval between requests, in seconds, after which a request will trigger replication of the session's timestamp regardless of whether the request has otherwise made the session dirty. Such replication ensures that other nodes in the cluster are aware of the most recent value for the session's timestamp and won't incorrectly expire an unreplicated session upon failover. It also results in correct values for HttpSession.getLastAccessedTime() calls following failover.
A value of 0 means the metadata will be replicated whenever the session is accessed. A value of -1 means the metadata will be replicated only if some other activity during the request (e.g. modifying an attribute) has resulted in other replication work involving the session. A positive value greater than the HttpSession.getMaxInactiveInterval() value will be treated as a likely misconfiguration and converted to 0; i.e. replicate the metadata on every request. Default value is 60.
Defines when sessions are replicated to the other nodes.
Possible values are:
1. "instant" (the default)
The typical value, "instant", replicates changes to the other nodes at the end of requests, using the request processing thread to perform the replication. In this case, the "snapshot-interval" property is ignored.
With "interval" mode, a background task is created that runs every "snapshot-interval" milliseconds, checking for modified sessions and replicating them.
Note that this property has no effect if replication-granularity is set to FIELD. If it is FIELD, "instant" mode will be used.
|snapshot-interval||Defines how often (in milliseconds) the background task that replicates modified sessions should be started for this web app. Only meaningful if snapshot-mode is set to "interval".|
Fully qualified class name of the implementation of the ClusteredSessionNotificationPolicy interface that should be used to govern whether servlet specification notifications should be emitted to any registered HttpSessionListener, HttpSessionAttributeListener and/or HttpSessionBindingListener.
Event notifications that may make sense in a non-clustered environment may or may not make sense in a clustered environment; see JBAS-5778 for an example of why a notification may not be desired. Configuring an appropriate ClusteredSessionNotificationPolicy gives the application author fine-grained control over what notifications are issued.
In AS 5.0.0.GA the default value if not explicitly set is the LegacyClusteredSessionNotificationPolicy,which implements the behavior in previous JBoss versions. In the next AS 5 release the intent is to change this to IgnoreUndeployLegacyClusteredSessionNotificationPolicy, which implements the same behavior except for in undeployment situations during which no HttpSessionListener and HttpSessionAttributeListener notifications are sent.
The max-active-sessions property limits the number of sessions for this webapp that the session manager will keep in memory at any one time. If the number of in-memory sessions is greater than or equal to this value and a request comes in to create a new session, the session manager will try to passivate sessions out of memory (if passivation is enabled.) If the number of in-memory sessions still cannot be brought below this limit, an exception will be thrown. The default value for max-active-sessions is -1, which mean no limit.
Note that the number of sessions in memory includes sessions replicated from other cluster nodes that are not being accessed on this node. Be sure to account for that when setting max-active-sessions. Note also that the number of sessions replicated from other nodes may differ greatly depending on whether buddy replication is enabled. In an 8 node cluster where each node is handling request from 100 users, with total replication each node will have 800 sessions in memory. With buddy replication with the default numBuddies setting of 1, each node will have 200 sessions in memory.
See Distributable HttpSession Passivation for details on the settings in the passivation-config section above.
JBoss AS 5 includes a special deployer that examines any webapp deployment and sets default values for any of the above properties that aren't specified in jboss-web.xml. This WebAppClusteringDefaultsDeployer is configured via the $JBOSS_HOME/server/.../deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml file. The deployer exposes setters for all of the properties described above, so changing the server-wide default for any of them is simply a matter of editing the war-deployers-jboss-beans.xml file.