Distributable HttpSession Passivation

Version 15

Created by hmesha on Apr 7, 2006 5:19 PM. Last modified by brian.stansberry on Dec 11, 2008 2:48 AM.

HttpSession Passivation/Activation

Passivation is the process of controlling memory usage by removing relatively unused sessions from memory while storing them in persistent storage. If a passivated session is requested by a client, it can be "activated" back into memory and removed from the persistent store. Beginning with the 5.0.0 release, JBoss AS supports passivation of HttpSessions from webapps whose web.xml includes the <distributable/> tag (i.e. clustered webapps).[1]

Passivation occurs at 3 points during the lifecycle of a web application:

When the container requests the creation of a new session. If the number of currently active session exceeds a configurable limit, an attempt is made to passivate sessions to make room in memory .
Periodically (by default every ten seconds) as the JBoss Web background thread runs.
When the web application is deployed and a backup copy of sessions active on other servers is acquired by the mewly deploying web app's session manager.

A session will be passivated if one of the following holds true:

The session hasn't been used in greater than a configurable maximum idle time.
The number of active sessions exceeds a configurable maximum and the session hasn't been used in greater than a configurable minimum idle time.

In both cases, sessions are passivated on a Least Recently Used (LRU) basis.

Configuring Distributable HttpSession Passivation in your Web Application

Step 1 : Add the following to jboss-web.xml for your web application

   <max-active-sessions>20</max-active-sessions>
   <passivation-config>
      <use-session-passivation>true</use-session-passivation>
      <passivation-min-idle-time>60</passivation-min-idle-time>
      <passivation-max-idle-time>600</passivation-max-idle-time>
   </passivation-config>

max-active-sessions Determines the maximum number of active sessions allowed. If the number of sessions managed by the the session manager exceeds this value and passivation is enabled, the excess will be passivated based on the configured passivation-min-idle-time. If after passivation is completed (or if passivation is disabled), the number of active sessions still exceeds this limit, attempts to create new sessions will be rejected.[2] If set to -1 (the default), there is no limit
passivation-min-idle-time Determines the minimum time (in seconds) that a session must have been inactive before the container will consider passivating it in order to reduce the active session count below max-active-sessions. A value of -1 (the default) disables passivating sessions before passivation-max-idle-time. Neither a value of -1 nor a high value are recommended if max-active-sessions is set.
passivation-max-idle-time Determines the maximum time (in seconds) that a session can be inactive before the container should attempt to passivate it to save memory. Passivation of such sessions will take place regardless of whether the active session count exceeds max-active-sessions. Should be less than the web.xml session-timeout setting. A value of -1 (the default) disables passivation based on maximum inactivity.
use-session-passivation Determines whether session passivation will be enabled for the web application. Default is false.

Step 2 : Configure the JBoss Cache cache loader

In most cases you don't need to do anything for Step 2; the standard JBoss AS configuration for distributable session caching should suit your needs. The following is a bit more detail in case you're interested or want to change from the defaults.

HttpSession passivation relies on JBoss Cache's Cache Loader passivation for storing and retrieving the passivated sessions. Therefore the cache instance used by your webapps clustered session manager must be configured to enable Cache Loader passivaton. The basics of configuring caches for clustered webapps is covered in the CacheManager service page. Here we'll get into a few more specifics related to passivation.

The Cache Loader configuration for the standard-session-cache config is as follows:

        <property name="cacheLoaderConfig">
            <bean class="org.jboss.cache.config.CacheLoaderConfig">
                   <!-- Do not change these -->
                   <property name="passivation">true</property>
                   <property name="shared">false</property>
                   
                   <property name="individualCacheLoaderConfigs">
                     <list>
                        <bean class="org.jboss.cache.loader.FileCacheLoaderConfig">
                           <!-- Where passivated sessions are stored -->
                           <property name="location">${jboss.server.data.dir}${/}session</property>
                           <!-- Do not change these -->
                           <property name="async">false</property>
                           <property name="fetchPersistentState">true</property>
                           <property name="purgeOnStartup">true</property>
                           <property name="ignoreModifications">false</property>
                           <property name="checkCharacterPortability">false</property>
                        </bean>
                     </list>
                   </property>
            </bean>
         </property>

passivation property MUST be true
shared property MUST be false. Do not passivate sessions to a shared persistent store, otherwise if another node activates the session, it will be gone from the persistent store and also gone from memory on other nodes that have passivated it. Backup copies will be lost.
individualCacheLoaderConfigs property accepts a list of Cache Loader configurations. JBC allows you to chain cache loaders; see the JBC docs. For the session passivation use case a single cache loader is sufficient.
class attribute on a cache loader config bean MUST refer to the configuration class for a cache loader implementation (e.g. org.jboss.cache.loader.FileCacheLoaderConfig, org.jboss.cache.loader.JDBCCacheLoaderConfig). See the JBoss Cache documentation for more on the available CacheLoader implementations. If you wish to use JDBCCacheLoader (to persist to a database rather than the filesystem used by FileCacheLoader) note the comment above about the shared property. Don't use a shared database, or at least not a shared table in the database. Each node in the cluster must have its own storage location.
location property for FileCacheLoaderConfig defines the root node of the filesystem tree where passivated session should be stored. The default is to store them in your JBoss AS configuration's data directory.
async MUST be false to ensure passivated sessions are promptly written to the persistent store.
fetchPersistentState MUST be true to ensure passivated sessions are included in the set of session backup copies transferred over from other nodes when the cache starts.
purgeOnStartup should be true to ensure out-of-date session data left over from a previous shutdown of a server doesn't pollute the current data set.
ignoreModifications should be false.
checkCharacterPortability should be false as a minor performance optimization.

Refer to the JBossCache documentation for further details about Cache Loader configuration.

Configuring Server-Wide Passivation Defaults

The section on jboss-web.xml configuration above described how to configure passivation on a webapp-by-webapp basis. If you are deploying several webapps and each uses the same set of passivation configurations, you may wish to skip the jboss-web.xml configuration and just change the server-wide defaults. This can be done by uncommenting the following section in the $JBOSS_HOME/server/xxx/deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml file's WebAppClusteringDefaultsDeployer and setting the values you desire:

      <!--
      <property name="useSessionPassivation">false</property>
      <property name="passivationMaxIdleTime">-1</property>  
      <property name="passivationMinIdleTime">-1</property>
      -->

JBossDeveloper