4 Coherence*Web Session Management Features

Coherence*Web can be configured in a number of ways to meet the demands of your environment. Consequently, you may need to change some of the default configuration options. The purpose of this chapter is to provide an in-depth look at the features that Coherence*Web supports so that you can make the appropriate configuration and deployment decisions.

Session Models
Session and Session Attribute Scoping
Cluster Node Isolation
Session Locking Modes
Deployment Topologies
Managing and Monitoring Applications with JMX

4.1 Session Models

A session model describes how Coherence*Web physically represents and stores session state in Coherence. Coherence*Web supports a flexible data management model for session state. The session state is managed by an HttpSessionModel object, and the list of all sessions is managed by an HttpSessionCollection object. Coherence*Web includes these different session model implementations out of the box:

Traditional Model—Stores all session state as a single entity but serializes and deserializes attributes individually.
Monolithic Model—Stores all session state as a single entity, serializing and deserializing all attributes as a single operation.
Split Model—Extends the Traditional Model but separates the larger session attributes into independent physical entities.

Figure 4-1 Traditional, Monolithic, and Split Session Models

Description of "Figure 4-1 Traditional, Monolithic, and Split Session Models"

4.1.1 Traditional Model

TraditionalHttpSessionModel and TraditionalHttpSessionCollection manage all of the HTTP session data for a particular session in a single Coherence cache entry, but manage each HTTP session attribute (particularly, its serialization and deserialization) separately.

This model is suggested for applications with relatively small HTTP session objects (10KB or less) that do not have issues with object-sharing between session attributes. (Object-sharing between session attributes occurs when multiple attributes of a session have references to the same exact object, meaning that separate serialization and deserialization of those attributes will cause multiple instances of that shared object to exist when the HTTP session is later deserialized.)

Figure 4-2 Traditional Session Model

Description of "Figure 4-2 Traditional Session Model"

4.1.2 Monolithic Model

MonolithicHttpSessionModel and MonolithicHttpSessionCollection are similar to the Traditional Model, except that they solve the shared object issue by serializing and deserializing all attributes together in a single object stream.

As a result, the Monolithic Model is often less performant than the Traditional Model.

Figure 4-3 Monolithic Session Model

Description of "Figure 4-3 Monolithic Session Model"

4.1.3 Split Model

SplitHttpSessionModel and SplitHttpSessionCollection manage the core HTTP session data such as the session ID, creation time, last access time, and so on, with all of the small session attributes in the same manner as the Traditional Model, thus ensuring high performance by keeping that block of session data small. All large attributes are split out into separate cache entries to be managed individually, thus supporting very large HTTP session objects without unduly increasing the amount of data that must be accessed and updated within the cluster on each request. In other words, only the large attributes that are modified within a particular request will incur any network overhead for their updates, and (because it uses Near Caching) the Split Model generally does not incur any network overhead for accessing either the core HTTP session data or any of the session attributes.

Figure 4-4 Split Session Model

Description of "Figure 4-4 Split Session Model"

4.1.4 Session Model Recommendations

The Split Model is the recommended session model for most applications.
The Traditional Model may be more optimal for applications that are known to have small HTTP session objects.
The Monolithic Model is designed to solve a specific class of problems related to multiple session attributes that have references to the same shared object, and that must maintain that object as a shared object.

Session Management for Clustered Applications in Getting Started with Oracle Coherence, provides information on the behavior of these models in a clustered environment.

Note:

For configuration information, see Appendix A, "Coherence*Web Configuration Parameters."

4.2 Session and Session Attribute Scoping

Coherence*Web allows fine-grained control over how both session data and session attributes are scoped (or "shared") across application boundaries:

4.2.1 Session Scoping

Coherence*Web allows session data to be shared by different Web applications deployed in the same or different Web containers. To do so, you must correctly configure the Coherence*Web cookie context parameters and make the classes of objects stored in session attributes available to each Web application.

If you are using cookies to store session IDs (that is, you are not using URL rewriting), you must set the coherence-session-cookie-path context parameter to a common context path of all Web applications that share session data. For example, if you want to share session data between two Web applications registered under the contexts paths /web/HRPortal and /web/InWeb, you should set the coherence-session-cookie-path parameter to /web. On the other hand, if the two Web applications are registered under the context paths /HRPortal and /InWeb, you should set the coherence-session-cookie-path parameter to /.

If the Web applications that you would like to share session data are deployed on different Web containers running on different machines (that are not behind a common load balancer), you must also set the coherence-session-cookie-domain parameter to a domain shared by the machines. For example, if you would like to share session data between two Web applications running on server1.mydomain.com and server2.mydomain.com, you must set the coherence-session-cookie-domain parameter to .mydomain.com.

To correctly serialize or deserialize objects stored in shared sessions, the classes of all objects stored in session attributes must be available to Web applications that share session data. For Web applications deployed on different containers, the classes may be placed in either the Web container or Web application classpath; however, for applications deployed in the same Web container, the classes must be placed in the Web container classpath. This is due to the fact that most containers load each Web application using a separate ClassLoader.

Note:

For advanced use cases where EAR cluster node-scoping or application server JVM cluster scoping is employed and you do not want session data shared across individual Web applications see "Preventing Web Applications from Sharing Session Data".

4.2.1.1 Preventing Web Applications from Sharing Session Data

Sometimes you may want to explicitly prevent HTTP session data from being shared by different Java EE applications that participate in the same Coherence cluster. For example, assume you have two applications HRPortal and InWeb that share cached data in their EJB tiers but utilize different session data. In this case, it is desirable for both applications to be part of the same Coherence cluster, but undesirable for both applications to use the same clustered service for session data.

To prevent different Java EE applications from sharing session data, specify a unique session cache service name for each application:

Locate the <service-name/> parameters in each session-cache-config.xml file found in your application.
Set the parameters to a unique value for each application.

This will force each application to use a separate clustered service for session data.
Save the modified session-cache-config.xml files.

Example 4-1 illustrates a sample session-cache-config.xml file for an HRPortal application. To prevent the HRPortal application from sharing session data with the InWeb application, rename the <service-name> parameter for the replicated scheme to be ReplicationSessionsMiscHRP. Rename the <service-name> parameter for the distributed schemes to be DistributedSessionsHRP.

Example 4-1 Configuration to Prevent Applications from Sharing Session Data

<replicated-scheme>
  <scheme-name>default-replicated</scheme-name>
  <service-name>ReplicatedSessionsMisc</service-name> // rename this to ReplicatedSessionsMiscHRP 
  <backing-map-scheme>
    <class-scheme>
      <scheme-ref>default-backing-map</scheme-ref>
    </class-scheme>
  </backing-map-scheme>
</replicated-scheme>

<distributed-scheme>
  <scheme-name>session-distributed</scheme-name>
  <service-name>DistributedSessions</service-name> // rename this to DistributedSessionsHRP
  <lease-granularity>member</lease-granularity>
  <backing-map-scheme>
    <class-scheme>
      <scheme-ref>default-backing-map</scheme-ref>
    </class-scheme>
  </backing-map-scheme>
</distributed-scheme>

<distributed-scheme>
  <scheme-name>session-certificate</scheme-name>
  <service-name>DistributedSessions</service-name> // rename this to DistributedSessionsHRP
  <lease-granularity>member</lease-granularity>
  <backing-map-scheme>
    <local-scheme>
      <scheme-ref>session-certificate-autoexpiring</scheme-ref>
    </local-scheme>
  </backing-map-scheme>
</distributed-scheme>

4.2.1.2 Keeping Session Cookies Separate

If you are using cookies to store session IDs, you must make sure that session cookies created by one application are not propagated to another application. To do this, you must set each application's session cookie domain and path in their web.xml file. The context parameter coherence-session-cookie-path sets the context path for a Web application. To prevent cookies from being propagated, be sure that no two applications share the same context path.

For example, assume you have two Web applications registered under the contexts paths /web/HRPortal and /web/InWeb. To prevent the Web applications from sharing session data through cookies, set the coherence-session-cookie-path parameter in one application's web.xml file to /web/HRPortal; set the parameter in the other application's web.xml file to /web/InWeb.

If your applications are deployed on different Web containers running on separate machines, then you can set the context parameter coherence-session-cookie-domain to ensure that they are not in the same domain.

For example, assume you have two Web applications running on server1.mydomain.com and server2.mydomain.com. To prevent session cookies from being shared between them, then set the coherence-session-cookie-domain parameter in one application's web.xml file to server1.mydomain.com; set the parameter in the other application's web.xml file to server2.mydomain.com.

4.2.2 Session Attribute Scoping

In the case where sessions are shared across Web applications there are many instances where the application may want to scope individual session attributes so that they are either globally visible (that is, all Web applications can see and modify these attributes) or scoped to an individual Web application (that is, not visible to any instance of another application).

Coherence*Web provides the ability to control this behavior by using the AttributeScopeController interface. This optional interface is used to selectively scope attributes in cases when a session may be shared across more than one application. This enables different applications to potentially use the same attribute names for application-scope state without accidentally reading, updating, or removing other applications' attributes. In addition to having application-scoped information in the session, it allows the session to contain global (unscoped) information that is readable, updatable, and removable by any of the applications that share the session.

There are two implementations of this interface available out of the box: the ApplicationScopeController and the GlobalScopeController.

4.3 Cluster Node Isolation

When using Coherence*Web there are a number of deployment options to consider, one of which is the concept of cluster node isolation.

This option determines:

The number of Coherence nodes that are created within an application server JVM.
Where the Coherence library is deployed.

Applications can be application server-scoped, EAR-scoped, or WAR-scoped. This section describes these options. For detailed information on the XML configuration for each of these options, see "Packaging Applications and Configuring Cluster Nodes".

4.3.1 Application Server-Scoped Cluster Nodes

With this configuration, all deployed applications in a container using Coherence*Web will be part of one Coherence node. This configuration will produce the smallest number of Coherence nodes in the cluster (one for each Web container JVM) and since the Coherence library (coherence.jar) is deployed in the container's classpath, only one copy of the Coherence classes will be loaded into the JVM. This minimizes the use of resources. On the other hand, since all applications are using the same cluster node, all applications will be affected if one application misbehaves.

Figure 4-5 Application Server-Scoped Cluster

Description of "Figure 4-5 Application Server-Scoped Cluster"

Requirements for using this configuration are:

Each deployed application must use the same version of Coherence and participate in the same cluster.
Objects placed in the HTTP session must have their classes in the container's classpath.

The XML configuration for application server-scoped cluster nodes is described in "Packaging and Configuring Application Server-Scoped Cluster Nodes".

Note:

The application server-scoped cluster node configuration should be considered very carefully and never used in environments where the interaction between applications is unknown or unpredictable.

An example of such an environment may be a deployment where multiple application groups are deploying applications written independently, without carefully coordinating and enforcing their conventions and naming standards. With this configuration, all applications are part of the same cluster and the likelihood of collisions between namespaces for caches, services and other configuration settings is quite high and may lead to unexpected results.

For these reasons, Oracle Coherence strongly recommends that you use EAR-scoped and WAR-scoped cluster node configurations. If you are in doubt as to which deployment topology to choose, or if this warning applies to your deployment, then do not choose the application server-scoped cluster node configuration.

4.3.2 EAR-Scoped Cluster Nodes

With this configuration, all deployed applications within each EAR will be part of one Coherence node. This configuration will produce the next smallest number of Coherence nodes in the cluster (one for each deployed EAR that uses Coherence*Web). Since the Coherence library (coherence.jar) is deployed in the application's classpath, only one copy of the Coherence classes will be loaded for each EAR. Since all Web applications in the EAR use the same cluster node, all Web applications in the EAR will be affected if one of the Web applications misbehaves.

Figure 4-6 EAR-Scoped Cluster

Description of "Figure 4-6 EAR-Scoped Cluster"

EAR-scoped cluster nodes reduce the deployment effort as no changes to the application server classpath are required. This option is also ideal if you plan on deploying only one EAR to an application server.

Requirements for using this configuration are:

The Coherence library (coherence.jar) must be deployed as part of the EAR file and listed as a Java module in META-INF/application.xml.
Objects placed into the HTTP session must have their classes deployed as a Java EAR module in a similar fashion.

The XML configuration for EAR-scoped cluster nodes is described in"Packaging and Configuring EAR-Scoped Cluster Nodes".

4.3.3 WAR-Scoped Cluster Nodes

With this configuration, each deployed Web application will be its own Coherence node. This configuration will produce the largest number of Coherence nodes in the cluster (one for each deployed WAR that uses Coherence*Web) and since the Coherence library (coherence.jar) is deployed in the Web application's classpath, there will be as many copies of the Coherence classes loaded as there are deployed WARs. This results in the largest resource utilization out of the three options. However, since each deployed Web application is its own cluster node, Web applications are completely isolated from other potentially misbehaving Web applications.

WAR scoped cluster nodes reduce the deployment effort as no changes to the application server classpath are required. This option is also ideal if you plan on deploying only one WAR to an application server.

Figure 4-7 WAR-Scoped Clusters

Description of "Figure 4-7 WAR-Scoped Clusters"

Requirements for using this configuration are:

The Coherence library (coherence.jar) must be deployed as part of the WAR file (usually in WEB-INF/lib).
Objects placed into the HTTP session must have their classes deployed as part of the WAR file (in WEB-INF/lib or WEB-INF/classes).

The XML configuration for WAR-scoped cluster nodes is described in "Packaging and Configuring WAR-Scoped Cluster Nodes".

4.4 Session Locking Modes

Oracle Coherence provides these configuration options for concurrent access to HTTP sessions.

Optimistic Locking (Default)—Allows concurrent access to a session by multiple threads in a single JVM or multiple JVMs while prohibiting concurrent modification
Member Locking—Allows concurrent access and modification of a session by multiple threads in the same JVM while prohibiting concurrent access by threads in different JVMs.
Thread Locking—Prohibits concurrent access and modification of a session by multiple threads in a single JVM or multiple JVMs.

For more information on the parameters described in this section, see Appendix A, "Coherence*Web Configuration Parameters."

4.4.1 Optimistic Locking (Default)

The Optimistic Locking mode allows multiple Web container threads in one or more JVMs to access the same session concurrently. This setting does not use explicit locking; rather an optimistic approach is used to detect and prevent concurrent updates upon completion of an HTTP request that modifies the session. When Coherence*Web detects a concurrent modification, a ConcurrentModificationException is thrown to the application; therefore an application must be prepared to handle this exception in an appropriate manner.

This mode can be configured by setting the coherence-session-member-locking parameter to false.

4.4.2 Member Locking

The Member Locking mode allows multiple Web container threads in the same JVM to access and modify the same session concurrently, but prohibits concurrent access by threads in different JVMs. This is accomplished by acquiring a member-level lock for an HTTP session at the beginning of a request and releasing the lock upon completion of the request. For more information on member-level locks, see <lease-granularity> in the distributed-scheme section of the Developer's Guide for Oracle Coherence.

This mode can be configured by setting the coherence-session-member-locking parameter to true.

4.4.3 Thread Locking

The Thread Locking mode restricts access (and modification) to a session to a single thread in a single JVM at a time. This is accomplished by acquiring both a member level and thread-level lock for an HTTP session at the beginning of a request and releasing both locks upon completion of the request. For more information on member-level locks, see <lease-granularity> in the distributed-scheme section of the Developer's Guide for Oracle Coherence.

This mode can be configured by setting the coherence-session-thread-locking parameter to true. Note that setting this to true will imply a setting of true for coherence-session-member-locking.

4.4.4 Using Locking in HTTP Sessions

Enabling Member or Thread Locking for HTTP session access indicates that Coherence*Web will acquire a cluster-wide lock for every HTTP request that requires access to a session. By default, threads that attempt to access a locked session will block until the lock can be acquired. If you want to enable a timeout for lock acquisition, you can configure it by using the tangosol.coherence.servlet.lock.timeout system property in the container's startup script (for example -Dtangosol.coherence.servlet.lock.timeout=30s).

Many Web applications do not have such a strict concurrency requirement. For these applications, using the Optimistic Locking mode has the following advantages:

The overhead of obtaining and releasing cluster wide locks for every HTTP request is eliminated.
Requests can be load balanced away from failing or unresponsive JVMs to healthy JVMs without requiring the unresponsive JVM to release the cluster-wide lock on the session.

4.4.5 Enabling Sticky Session Optimizations

If Member or Thread Locking is a requirement for a Web application that will be behind a sticky load balancer, Coherence*Web provides an optimization for obtaining the cluster-wide lock required for HTTP session access. By definition, a sticky load balancer will attempt to route a request for a given session to the JVM that initially created it. The sticky session optimizations take advantage of this behavior by retaining the cluster-wide lock for a session until the session expires. If a request for the session lands on another JVM, that JVM will ask the JVM that owns the lock to release it as soon as possible. This is implemented using an invocation service. For more information, see the SessionOwnership entry in Table B-2.

Sticky session optimization can be enabled by setting the coherence-sticky-sessions parameter to true.

4.5 Deployment Topologies

Coherence*Web supports most of the same deployment topologies that Coherence does including in-process, out-of-process (that is, client/server deployment), and bridging clients and servers over Coherence*Extend. The major supported deployment topologies are described in the following sections.

Out-of-Process
Out-of-Process with Coherence*Extend
In-Process

4.5.1 Out-of-Process

In the Out of Process deployment topology, the application servers (that is, application server tier) are configured as cache clients (that is, tangosol.coherence.distributed.localstorage=false) and there are dedicated JVMs running as cache servers, physically storing and managing the clustered data.

This approach has these benefits:

Session data storage is off-loaded from the application server tier to the cache server tier. This reduces heap usage, garbage collection times, and so on.
It allows for the two tiers to be scaled independently of one another. If more application processing power is needed, just start more application servers. If more session storage capacity is needed, just start more cache servers.

The Out-of-Process topology is the default recommendation of Oracle Coherence due to its flexibility.

Figure 4-8 Out of Process Deployment Topology

Description of "Figure 4-8 Out of Process Deployment Topology"

4.5.2 Out-of-Process with Coherence*Extend

The Out-of-Process with Coherence*Extend topology is similar to the Out-of-Process topology except that the communication between the application server tier and the cache server tier are over Coherence*Extend (TCP/IP).

This approach has the same benefits as the Out-of-Process topology and the ability to segment deployment of application servers and cache servers. This is ideal in an environment where application servers are on a network that does not support UDP. The cache servers can be set up in a separate dedicated network, with the application servers connecting to the cluster by using TCP.

Figure 4-9 Out-of-Process with Coherence*Extend Deployment Topology

Out-of-Process with Coherence*Extend Topology

Description of "Figure 4-9 Out-of-Process with Coherence*Extend Deployment Topology"

4.5.3 In-Process

The In-Process topology is not recommended for production use. This topology is supported mainly for development and testing. By storing the session data in-process with the application server, this topology is very easy to get up and running quickly for smoke tests, development and testing.

Figure 4-10 In-Process Deployment Topology

Description of "Figure 4-10 In-Process Deployment Topology"

4.6 Managing and Monitoring Applications with JMX

Note:

To enable Coherence*Web JMX Management and Monitoring, this section assumes that you have first set up the Coherence Clustered JMX Framework. To set up this framework, see the configuration and installation instructions in How to Manage Coherence with JMX in the Developer's Guide for Oracle Coherence.

The management attributes and operations for Web applications that use Coherence*Web for HTTP session management are exposed through the HttpSessionManagerMBean interface (com.tangosol.coherence.servlet.management.HttpSessionManagerMBean).

During startup, each Coherence*Web Web application registers a single instance of HttpSessionManagerMBean. The MBean is unregistered when the Web application shuts down. Table 4-1 describes the MBean's object name used for registration.

Table 4-1 Object Name for the HttpSessionManagerMBean

Managed Bean	Object Name
HttpSessionManagerMBean	type=HttpSessionManager, nodeId=cluster node id, appId=web application id

Table 4-2 describes the information that is returned by the HttpSessionManagerMBean. All of the names represent attributes, with the exception of resetStatistics, which is an operation.

Several of the MBean attributes use the following prefixes:

LocalSession—indicates a session that is not distributed to all members of the cluster. The session remains "local" to the originating server until a later point in the life of the session.
LocalAttribute—indicates a session attribute that is not distributed to all members of the cluster.
Overflow—typically, a larger and slower back-end cache that catches entries evicted from a faster front-end cache.

Table 4-2 Information Returned by the HttpSessionManagerMBean

Name	Data Type	Description
CollectionClassName	String	The fully-qualified class name of the `HttpSessionCollection` implementation in use. The `HttpSessionCollection` interface is an abstract model for a collection of `HttpSessionModel` objects. The interface is not at all concerned with how the sessions are communicated between the clients and the servers.
FactoryClassName	String	The fully-qualified class name of the `Factory` implementation in use. The `SessionHelper.Factory` is used by the `SessionHelper` to obtain objects that implement various important parts of the Servlet specification. It can be placed in front of the application in place of the application server's own objects, thus changing the "apparent implementation" of the application server itself (for example, adding clustering.)
LocalAttributeCacheName	String	The name of the local cache that stores non-distributed session attributes. If the attribute displays null then local session attribute storage is disabled.
LocalAttributeCount	Integer	The number of non-distributed session attributes stored in the local session attribute cache. If the attribute displays `-1`, then local session attribute storage is disabled.
LocalSessionCacheName	String	The name of the local cache that stores non-distributed sessions. If the attribute displays `null`, then local session storage is disabled.
LocalSessionCount	Integer	The number of non-distributed sessions stored in the local session cache. If the attribute displays `-1`, then local session storage is disabled.
OverflowAverageSize	Integer	The average size (in bytes) of the session attributes stored in the "overflow" clustered cache since the last time statistics were reset. If the attribute displays `-1`, then a `SplitHttpSessionCollection` is not in use.
OverflowCacheName	String	The name of the clustered cache that stores the "large attributes" that exceed a certain size and thus are determined to be more efficiently managed as separate cache entries and not as part of the serialized session object itself. `Null` is displayed if a `SplitHttpSessionCollection` is not in use.
OverflowMaxSize	Integer	The maximum size (in bytes) of a session attribute stored in the "overflow" clustered cache since the last time statistics were reset. The attribute displays `-1` if a `SplitHttpSessionCollection` is not in use.
OverflowThreshold	Integer	The minimum length (in bytes) that the serialized form of an attribute value must be for that attribute value to be stored in the separate "overflow" cache that is reserved for large attributes. The attribute displays `-1` if a `SplitHttpSessionCollection` is not in use.
OverflowUpdates	Integer	The number of updates to session attributes stored in the "overflow" clustered cache since the last time statistics were reset. The attribute displays `-1` if a `SplitHttpSessionCollection` is not in use.
SessionAverageLifetime	Integer	The average lifetime (in seconds) of session objects invalidated (either due to expiration or to an explicit invalidation) since the last time statistics were reset.
SessionAverageSize	Integer	The average size (in bytes) of session objects placed in the session storage clustered cache since the last time statistics were reset.
SessionCacheName	String	The name of the clustered cache that stores serialized session objects.
SessionIdLength	Integer	The length (in characters) of generated session IDs.
SessionMaxSize	Integer	The maximum size (in bytes) of a session object placed in the session storage clustered cache since the last time statistics were reset.
SessionMinSize	Integer	The minimum size (in bytes) of a session object placed in the session storage clustered cache since the last time statistics were reset.
SessionStickyCount	Integer	The number of session objects that are pinned to this instance of the Web application. The attribute displays `-1` if sticky session optimizations are disabled.
SessionTimeout	Integer	The session expiration time (in seconds). The attribute displays `-1` if sessions never expire.
SessionUpdates	Integer	The number of updates of session object stored in the session storage clustered cache since the last time statistics were reset.
ServletContextCacheName	String	The name of the clustered cache that stores javax.servlet.`ServletContext` attributes. The attribute displays `null` if the `ServletContext` is not clustered.
ServletContextName	String	The name of the Web application `ServletContext`.
resetStatistics (operation)	void	Reset the session management statistics.

Figure 4-11 illustrates the HttpSessionManagerMBean as it is displayed in the JConsole browser.

Figure 4-11 HttpSessionManagerMBean Displayed in the JConsole Browser

Http Session Manager MBean in the JConsole Browser

Description of "Figure 4-11 HttpSessionManagerMBean Displayed in the JConsole Browser"