Terracotta Sessions (TCS) Architecture
Overview
TCS and Host Container
TCS plugs in into its host container using standard Filter
interface. When TCS runs in Tomcat it plugs in as a Valve. The filter (SessionFilter class) wraps request and response into customer wrapper objects that intercept and implement all method related to HttpSession life-cycle.
TCS implements all phases of HttpSession life-cycle:
- generate session id
- write session cookie
- raise events on HttpSessionBindingListener, HttpSessionAttributeListener, and HttpSessionListener instances
- rewrite URL's to include session id when needed
- expire old stale sessions.
Major Components
Classes in TCS implementation can be divided roughly into three groups:
- TCS core classes that implement major logical pieces of TCS functionality
- distributed persistent data structure
- classes that interface with host container
We'll cover each group separately.
TCS Core Classes
The hub of TCS implementation is com.terracotta.session.TerracottaSessionManager class that handles (among others):
- session creation
- wrapping request and response objects
- getting existing session from SessionDataStore
- finding requested session id
- expiring session
- finding invalidating stale sessions
Other, more specialized, pieces of functionality are delegated to the following classes:
- com.terracotta.session.util.ConfigProperties - allows System properties overrides
- com.terracotta.session.util.DefaultContextMgr - bridge to the host container's HttpSessionContext and ServletContext
- com.terracotta.session.util.DefaultCookieWriter - responsible for writing session cookie and encoding URL's
- com.terracotta.session.util.DefaultIdGenerator - generates new session id strings
- com.terracotta.session.util.DefaultLifecycleEventMgr - raises various events on HttpSessionAttributeListener's, {{HttpSessionListener's, and HttpSessionBindingListener's
- com.terracotta.session.util.DefaultSessionId - parse and maintains session id value
- com.terracotta.session.util.DefaultWebAppConfig - bridge to the host container configuration that impacts session handling
- com.terracotta.session.util.Lock - provides a uniform way to get, or try to get, a distributed lock prior to session data modification
- com.terracotta.session.util.StandardSession - bridge between shared SessionData object and HttpSession interface
Distributed Persistent Data Structure
TCS creates two Shared Roots: SessionDataStore.store and SessionDataStore.dtmStore. The first root is a map containing SessionData objects (one for every session) with all session attributes and a few additional fields, the second root is a map containing Timestamp objects (one for every session) with estimated end-of-life time for every session. Note, the second root is not visible in the Terracotta console, as it is a low level implementation detail. SessionDataStore class controls access to both shared roots, it is also responsible for making sure that related data in those roots is maintained in synch.
TCS Host Container Facing Classes
These are the classes that must interact with the Host Container. For the most part, these classes implement interfaces from javax.servlet and javax.servlet.http packages and serve as a bridge between the servlet world and TCS Logic Classes. Classes that interface with a generic container are:
- interface com.terracotta.session.Session extends HttpSession
- class com.terracotta.session.SessionFilter implements Filter
- class com.terracotta.session.SessionRequest extends HttpServletRequestWrapper
- class com.terracotta.session.SessionResponse extends HttpServletResponseWrapper
- interface com.terracotta.session.TerracottaRequest extends HttpServletRequest
- interface com.terracotta.session.TerracottaResponse extends HttpServletResponse
Classes that interface with Tomcat 5.0.* are:
- class com.tc.tomcat50.session.SessionValve50 extends ValveBase}}
- class com.tc.tomcat50.session.SessionRequest50 extends SessionRequest implements HttpRequest
- class com.tc.tomcat50.SessionResponse50 extends SessionResponse implements HttpResponse
- class com.tc.tomcat50.session.TerracottaPipeline extends StandardPipeline
Classes that interface with Tomcat 5.5.* are:
- class com.tc.tomcat55.session.SessionValve55 extends ValveBase
- class org.apache.catalina.connector.SessionRequest55 extends Request
- class org.apache.catalina.connector.SessionResponse55 extends Response
- class com.tc.tomcat55.TerracottaPipeline extends StandardPipeline
Implementation Details
Session Id
Session id is a string of 8 or more hexadecimal characters. Default size of session id string (without server id part) is 20 hex characters.
The format of the id string is [4 random hex chars][4 sequence hex chars][(id_size - 8) random hex chars]!serverId. New Session Id's are generated by DefaultIdGenerator class. DefaultIdGenerator maintains an ever-increasing short integer nextId used in the second field of the session id string. Thus, a single JVM is guaranteed to generate (Short.MAX_VALUE - Short.MIN_VALUE) number of unique session id's. Session id's generated by different JVM's in a cluster are very unlikely to collide, but it is possible. In the future, this can be prevented by making DefaultIdGenerator.nextId field shared.
Session Id's are never reused. If request carries a session id for which a valid SessionData object is not found, a new session id (and a new SessionData object) is generated.
Session Cookie
Session Cookie is written every time a new session is created or when request jumps to another instance of container in the cluster. For a request without a valid session id, a new session is created on the first call to HttpServletRequest.getSession() method, the session cookie is written at the same time.
Session cookie fields are set to the following default values unless overridden in config :
- Cookie Name is set to JSESSIONID
- Cookie Path is set to the web application context path
- Cookie Max Age is set to -1
- Is Cookie Secure is set to false
- Cookie Domain is not set by default
- Cookie Comment is not set by default
Configuration
Usually configuration values are extracted from the host container using com.terracotta.session.WebAppConfig interface. However, most of the values can be overridden. To do this create a file called "tc.properties" and place it in the common/lib folder of the terracotta distribution. The following properties modify session behavior:
- session.id.length=[integer value]
- session.serverid=[server id to use in session cookie]
- session.cookie.domain=[string]
- session.cookie.comment=[string]
- session.cookie.secure=[true|false]
- session.cookie.maxage.seconds=[integer]
- session.cookie.name=[string]
- session.cookie.path=[string]
- session.cookie.enabled=[true|false]
- session.maxidle.seconds=[integer]
- session.tracking.enabled=[true|false]
- session.urlrewrite.enabled=[true|false]
- session.attribute.listeners=[CSV list of classes]
- session.listeners=[CSV list of classes]
- session.invalidator.sleep=[integer]
- session.request.bench.enabled = false
- session.invalidator.bench.enabled = true
Monitoring and Management
Monitoring and Management is provided through com.tc.management.beans.sessions.SessionMonitorMBean JMX Bean. Callbacks to update stats are invoked an instance of SessionMonitorMBean at key places in TerracottaSessionManager.
The following stats and operations are exposed through SessionMonitorMBean:
- Total Request Count
- Request Rate Per Second
- Created Session Count
- Session Creation Rate Per Minute
- Destroyed Session Count
- Session Destruction Rate Per Minute
- Expire Session By Id
