Revision: ba710b787512
Author: Jean Deruelle <[email protected]>
Date: Tue Aug 7 04:45:24 2012
Log: Update Issue 121
Fixing organization of Section 5.3 by creating a new section for Passivation
http://code.google.com/p/sipservlets/source/detail?r=ba710b787512
Added:
/docs/sources/src/main/resources/en-US/concept-section-SS_for_JBoss-Passivation_Support.xml
Modified:
/docs/sources/src/main/resources/en-US/SIP_Servlets_Server_User_Guide.xml
/docs/sources/src/main/resources/en-US/concept-section-SS_Load_Balancer.xml
/docs/sources/src/main/resources/en-US/concept-section-SS_for_JBoss-Failover_Support.xml
=======================================
--- /dev/null
+++
/docs/sources/src/main/resources/en-US/concept-section-SS_for_JBoss-Passivation_Support.xml
Tue Aug 7 04:45:24 2012
@@ -0,0 +1,205 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML
V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "SIP_Servlets_Server_User_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<!-- chapter id nickname: ssfjfs -->
+
+
+<section id="ssfjfs-SS_for_JBoss-Passivation_Support">
+ <title>SIP Session Passivation in &PLATFORM_NAME; SIP Servlets for
JBoss</title>
+ <para>
+ 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.
+ &PLATFORM_NAME; Sip Servlets supports passivation of SipSessions (and
by extension SIP Dialogs) and SipApplicationSessions sipapps whose sip.xml
includes the <literal>distributable</literal> tag (i.e. clustered sipapps).
+ </para>
+ <para>
+ Passivation occurs at 2 points during the lifecycle of a sip
application:
+</para>
+ <itemizedlist>
+ <listitem><para>
+When the container requests the creation of a new SIP Session or SIP
Application Session.
+If the number of currently active session exceeds a configurable limit, an
attempt is made to passivate sessions to make room in memory.
+</para>
+ </listitem>
+ <listitem><para>
+Periodically (by default, every ten seconds) as the JBoss Web background
thread runs.
+</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+A session will be passivated if one of the following holds true:
+</para>
+ <itemizedlist>
+ <listitem><para>
+The session hasn't been used in greater than a configurable maximum idle
time.
+</para>
+ </listitem>
+ <listitem><para>
+The number of active sessions exceeds a configurable maximum and the
session hasn't been used in greater than a configurable minimum idle time.
+</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+In both cases, sessions are passivated on a Least Recently Used (LRU)
basis.
+ </para>
+
+
+ <section
id="ssfjcs-binary-SIP_Servlets_Server_Cluster-SIP-Passivation-Configuration">
+ <title>Configuring Distributable SIP Session Passivation in your SIP
Application</title>
+ <para>
+
+ </para>
+
+<para>Step 1: Add the following to jboss-web.xml for your sip
application</para>
+ <para> </para>
+ <programlisting role="XML">
+
<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>
+ </programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>max-active-sessions</literal> Determines the maximum
number of active sessions allowed. If the number of sessions managed by 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. If set to -1 (the default), there is no limit.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>passivation-min-idle-time</literal> 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>passivation-max-idle-time</literal> 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 sip.xml session-timeout
setting. A value of -1 (the default) disables passivation based on maximum
inactivity.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>use-session-passivation</literal> Determines whether
session passivation will be enabled for the web application. Default is
false.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+
+<section
id="ssfjcs-binary-SIP_Servlets_Server_Cluster-SIP-Passivation-Configuration-Step2">
+ <title>Step 2 : Configure the JBoss Cache cache
loader</title>
+
+
+
+ <para>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.</para>
+ <para>SIP Session passivation relies on JBoss Cache's Cache Loader
passivation for storing and retrieving the passivated sessions.
+ Therefore the cache instance used by your sipapps clustered session
manager must be configured to enable Cache Loader passivaton.
+
+ The Cache Loader configuration for the
<literal>standard-session-cache</literal> config is as follows:</para>
+
+ <screen>
+ <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>
+</screen>
+
+
+
+ <itemizedlist>
+ <listitem>
+ <para>
+
<literal>passivation</literal> property MUST be true.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>shared</literal> 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>individualCacheLoaderConfigs</literal> 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>class</literal> 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>location</literal> property for FileCacheLoaderConfig
defines the root node of the filesystem tree where the passivated session
should be stored. The default is to store them in your JBoss AS
configuration's data directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>async</literal> MUST be false to ensure passivated
sessions are promptly written to the persistent store.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fetchPersistentState</literal> 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>purgeOnStartup</literal> 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+
<literal>ignoreModifications</literal> should be false.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>checkCharacterPortability</literal> should be false as a
minor performance optimization.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>Refer to the JBossCache documentation for further details about
Cache Loader configuration.</para>
+ </section>
+
+
+
+<section
id="ssfjcs-binary-SIP_Servlets_Server_Cluster-SIP-Passivation-Server-Wide-Configuration">
+ <title>Configuring Server-Wide Passivation Defaults</title>
+
+
+
+ <para>
+ The section on jboss-web.xml configuration above described how to
configure passivation on a sipapp-by-sipapp basis.
+ If you are deploying several sipapps 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:
+ </para>
+
+<screen>
+ <!--
+ <property name="useSessionPassivation">false
</property>
+ <property name="passivationMaxIdleTime">-1
</property>
+ <property name="passivationMinIdleTime">-1
</property>
+ -->
+
+</screen>
+
+
+ </section>
+ </section>
=======================================
---
/docs/sources/src/main/resources/en-US/SIP_Servlets_Server_User_Guide.xml
Wed Aug 1 06:35:26 2012
+++
/docs/sources/src/main/resources/en-US/SIP_Servlets_Server_User_Guide.xml
Tue Aug 7 04:45:24 2012
@@ -16,6 +16,7 @@
<title>Clustering and High Availability</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="concept-section-SS_for_JBoss-Clustering_Support.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="concept-section-SS_for_JBoss-Failover_Support.xml"/>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="concept-section-SS_for_JBoss-Passivation_Support.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="concept-section-SS_Load_Balancer.xml"/>
</chapter>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="concept-chapter-Enterprise-Monitoring-Operations-Management.xml"/>
=======================================
---
/docs/sources/src/main/resources/en-US/concept-section-SS_Load_Balancer.xml
Wed Aug 1 06:40:55 2012
+++
/docs/sources/src/main/resources/en-US/concept-section-SS_Load_Balancer.xml
Tue Aug 7 04:45:24 2012
@@ -86,213 +86,7 @@
<para>Uninstalling a SIP Servlets Cluster would entail deleting the
&PLATFORM_NAME; SIP Servlets Servers directories, the SIP Load Balancer
directory, and possibly removing the unused <envar>JBOSS_HOME</envar>
environment variable.</para>
- <para>
- 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.
- &PLATFORM_NAME; Sip Servlets supports passivation of SipSessions (and
by extension SIP Dialogs) and SipApplicationSessions sipapps whose sip.xml
includes the <literal>distributable</literal> tag (i.e. clustered sipapps).
- </para>
- <para>
- Passivation occurs at 2 points during the lifecycle of a sip
application:
-</para>
- <itemizedlist>
- <listitem><para>
-When the container requests the creation of a new SIP Session or SIP
Application Session.
-If the number of currently active session exceeds a configurable limit, an
attempt is made to passivate sessions to make room in memory.
-</para>
- </listitem>
- <listitem><para>
-Periodically (by default, every ten seconds) as the JBoss Web background
thread runs.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-A session will be passivated if one of the following holds true:
-</para>
- <itemizedlist>
- <listitem><para>
-The session hasn't been used in greater than a configurable maximum idle
time.
-</para>
- </listitem>
- <listitem><para>
-The number of active sessions exceeds a configurable maximum and the
session hasn't been used in greater than a configurable minimum idle time.
-</para>
- </listitem>
- </itemizedlist>
- <para>
-In both cases, sessions are passivated on a Least Recently Used (LRU)
basis.
- </para>
-
-
-
- </section>
-
-
-
- <section
id="ssfjcs-binary-SIP_Servlets_Server_Cluster-SIP-Passivation-Configuration">
- <title>Configuring Distributable SIP Session Passivation in your SIP
Application</title>
- <para>
-
- </para>
-
-<para>Step 1: Add the following to jboss-web.xml for your sip
application</para>
- <para> </para>
- <programlisting role="XML">
-
<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>
- </programlisting>
- <itemizedlist>
- <listitem>
- <para>
- <literal>max-active-sessions</literal> Determines the maximum
number of active sessions allowed. If the number of sessions managed by 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. If set to -1 (the default), there is no limit.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>passivation-min-idle-time</literal> 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.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>passivation-max-idle-time</literal> 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 sip.xml session-timeout
setting. A value of -1 (the default) disables passivation based on maximum
inactivity.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>use-session-passivation</literal> Determines whether
session passivation will be enabled for the web application. Default is
false.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
-
-<section
id="ssfjcs-binary-SIP_Servlets_Server_Cluster-SIP-Passivation-Configuration-Step2">
- <title>Step 2 : Configure the JBoss Cache cache
loader</title>
-
-
-
- <para>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.</para>
- <para>SIP Session passivation relies on JBoss Cache's Cache Loader
passivation for storing and retrieving the passivated sessions.
- Therefore the cache instance used by your sipapps clustered session
manager must be configured to enable Cache Loader passivaton.
-
- The Cache Loader configuration for the
<literal>standard-session-cache</literal> config is as follows:</para>
-
- <screen>
- <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>
-</screen>
-
-
-
- <itemizedlist>
- <listitem>
- <para>
-
<literal>passivation</literal> property MUST be true.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>shared</literal> 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.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>individualCacheLoaderConfigs</literal> 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.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>class</literal> 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.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>location</literal> property for FileCacheLoaderConfig
defines the root node of the filesystem tree where the passivated session
should be stored. The default is to store them in your JBoss AS
configuration's data directory.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>async</literal> MUST be false to ensure passivated
sessions are promptly written to the persistent store.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fetchPersistentState</literal> 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.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>purgeOnStartup</literal> 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.
- </para>
- </listitem>
- <listitem>
- <para>
-
<literal>ignoreModifications</literal> should be false.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>checkCharacterPortability</literal> should be false as a
minor performance optimization.
- </para>
- </listitem>
- </itemizedlist>
- <para>Refer to the JBossCache documentation for further details about
Cache Loader configuration.</para>
- </section>
-
-
-
-<section
id="ssfjcs-binary-SIP_Servlets_Server_Cluster-SIP-Passivation-Server-Wide-Configuration">
- <title>Configuring Server-Wide Passivation Defaults</title>
-
-
-
- <para>
- The section on jboss-web.xml configuration above described how to
configure passivation on a sipapp-by-sipapp basis.
- If you are deploying several sipapps 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:
- </para>
-
-<screen>
- <!--
- <property name="useSessionPassivation">false
</property>
- <property name="passivationMaxIdleTime">-1
</property>
- <property name="passivationMinIdleTime">-1
</property>
- -->
-
-</screen>
-
-
- </section>
-
-
-
-
-
-
-
-
+</section>
<!-- chapter id nickname: sslb --><section id="sslb-MSS_Load_Balancer">
<title>Load Balancer</title>
@@ -949,5 +743,4 @@
</section>
</section>
-m
</section>
=======================================
---
/docs/sources/src/main/resources/en-US/concept-section-SS_for_JBoss-Failover_Support.xml
Wed Aug 1 06:40:55 2012
+++
/docs/sources/src/main/resources/en-US/concept-section-SS_for_JBoss-Failover_Support.xml
Tue Aug 7 04:45:24 2012
@@ -7,7 +7,7 @@
<section id="ssfjfs-SS_for_JBoss-Failover_Support">
- <title>Detailed Information About &PLATFORM_NAME; SIP Servlets for
JBoss: Transparent Failover</title>
+ <title>Transparent Failover in &PLATFORM_NAME; SIP Servlets for
JBoss</title>
<para>A &PLATFORM_NAME; SIP Servlets Server for JBoss cluster does not
employ any standby nodes.
Typically, proxies and registrars must share the user location table by
using a database cluster.</para>
<para>The &PLATFORM_NAME; SIP Load Balancer, which is a SIP Call
ID-aware load balancer, is used as the intermediary.