Web Sessions Reference

This section contains further information on configuring and troubleshooting Terracotta Web Sessions.

Architecture of a Terracotta Cluster

The following diagram shows the architecture of a typical Terracotta-enabled web application.

The load balancer parcels out HTTP requests from the Internet to each application server. To maximize the locality of reference of the clustered HTTP session data, the load balancer uses HTTP session affinity so all requests corresponding to the same HTTP session are routed to the same application server. However, with a Terracotta-enabled web application, any application server can process any request. Terracotta Web Sessions clusters the sessions, allowing sessions to survive node hops and failures.

The application servers run both your web application and the Terracotta client software, and are called "clients" in a Terracotta cluster. As many application servers may be deployed as needed to handle your site load.

For more information on sizing and deployment concerns, see the Deployment Guide and the Operations Guide.

Additional Configuration Options

While Terracotta Web Sessions is designed for optimum performance with the configuration you set at installation, in some cases it may be necessary to use the configuration options described in the following sections.

Session Locking

By default, session locking is off in standard (non-DSO) Terracotta Web Sessions. If your application requires disabling concurrent requests in sessions, you can enable session locking.

To enable session locking in filter-based configuration, add an block as follows:

<filter>
 <filter-name>terracotta-filter</filter-name>
 <filter-class>org.terracotta.session.TerracottaContainerSpecificSessionFilter</filter-class>
 <init-param>
   <param-name>tcConfigUrl</param-name>
   <param-value>localhost:9510</param-value>
 </init-param>
 <init-param>
   <param-name>sessionLocking</param-name>
   <param-value>true</param-value>
 </init-param>
</filter>

To enable session locking in Valve-based configuration, add a sessionLocking attribute as follows:

<Valve className="com.terracotta.TerracottaContainerSpecificSessionValve" tcConfigUrl="localhost:9510" sessionLocking="true"/>

If you enable session locking, see Deadlocks When Session Locking Is Enabled.

Synchronous Writes

Synchronous write locks provide an extra layer of data protection by having a client node wait until it receives acknowledgement from the Terracotta Server Array that the changes have been committed. The client releases the write lock after receiving the acknowledgement. Enabling synchronous write locks can substantially raise latency rates, thus degrading cluster performance.

To enable synchronous writes in filter-based configuration, add an block as follows:

<filter>
 <filter-name>terracotta-filter</filter-name>
 <filter-class>org.terracotta.session.TerracottaContainerSpecificSessionFilter</filter-class>
 <init-param>
   <param-name>tcConfigUrl</param-name>
   <param-value>localhost:9510</param-value>
 </init-param>
 <init-param>
   <param-name>synchronousWrite</param-name>
   <param-value>true</param-value>
 </init-param>
</filter>

To enable synchronous writes in Valve-based configuration, add a synchronousWrite attribute as follows:

<Valve className="com.terracotta.TerracottaContainerSpecificSessionValve" tcConfigUrl="localhost:9510" synchronousWrite="true"/>

Troubleshooting

The following sections summarize common issues than can be encountered when clustering web sessions.

Sessions Time Out Unexpectedly

Sessions that are set to expire after a certain time instead seem to expire at unexpected times, and sooner than expected. This problem can occur when sessions hop between nodes that do not have the same system time. A node that receives a request for a session that originated on a different node still checks local time to validate the session, not the time on the original node. Adding the Network Time Protocol (NTP) to all nodes can help avoid system-time drift. However, note that having nodes set to different time zones can cause this problem, even with NTP.

This problem can also cause sessions to time out later than expected, although this variation can have many other causes.

Changes Not Replicated

Terracotta Web Sessions must run in serialization mode. Serialization mode is not an option as it is in the DSO version of Web Sessions. In serialization mode, sessions are still clustered, but your application must now follow the standard servlet convention on using setAttribute() for mutable objects in replicated sessions.

Tomcat 5.5 Messages Appear With Tomcat 6 Installation

If you are running Tomcat 6, you may see references to Tomcat 5.5 in the Terracotta log. This occurs because Terracotta Web Sessions run with Tomcat 6 reuses some classes from the Tomcat 5.5 Terracotta Integration Module.

Deadlocks When Session Locking Is Enabled

In some containers or frameworks, it is possible to see deadlocks when session locking is in effect. This happens when an external request is made from inside the locked session to access that same session. This type of request fails because the session is locked.

Events Not Received on Node

Most Servlet spec-defined events will work with Terracotta clustering, but the events are generated on the node where they occur. For example, if a session is created on one node and destroyed on a second node, the event is received on the second node, not the first node.