Reference Guide

Getting Started

Virtual Hosts
Distributed Sessions
EJB Clients
 Persistent and Distributed Sessions


Sessions can be persistent across server restarts, including application restarts when classes change. During development, for example, using file-based persistent sessions will let you work with a single session even while you're modifying servlet classes.

File Based

  • For single-server configurations
  • Useful in development when classes change often

Persistent sessions are configured in the web-app. File-based sessions use file-store.


Sessions are stored as files in the file-store directory. When the session changes, the updates will be written to the file. After Resin loads an Application, it will load the stored sessions.

In general, file-based persistence is less useful in multi-server environments. Although a network filesystem such as NFS will allow all the servers to access the same filesystem, it's not designed for the fine-grained access. For example, NFS will cache pages. So if one server modifies the page, e.g. a session value, the other servers may not see the change for several seconds.

Distributed Sessions

Distributed sessions are intrinsically more complicated than single-server sessions. Single-server session can be implemented as a simple memory-based Hashtable. Distributed sessions must communicate between machines to ensure the session state remains consistent.

Load balancing with multiple machines either uses sticky sessions or symmetrical sessions. Sticky sessions put more intelligence on the load balancer, and symmetrical sessions puts more intelligence on the JVMs. The choice of which to use depends on what kind of hardware you have, how many machines you're using and how you use sessions.

Distributed sessions can use a database as a backing store, or they can distribute the backup among all the servers using TCP.

Symmetrical Sessions

Symmetrical sessions happen with dumb load balancers like DNS round-robin. A single session may bounce from machine A to machine B and back to machine B. For JDBC sessions, the symmetrical session case needs the always-load-session attribute described below. Each request must load the most up-to-date version of the session.

Distributed sessions in a symmetrical environment are required to make sessions work at all. Otherwise the state will end up spread across the JVMs. However, because each request must update its session information, it is less efficient than sticky sessions.

Sticky Sessions

Sticky sessions require more intelligence on the load-balancer, but are easier for the JVM. Once a session starts, the load-balancer will always send it to the same JVM. Resin's load balancing, for example, encodes the session id as 'aaaXXX' and 'baaXXX'. The 'aaa' session will always go to JVM-a and 'baa' will always go to JVM-b.

Distributed sessions with a sticky session environment add reliability. If JVM-a goes down, JVM-b can pick up the session without the user noticing any change. In addition, distributed sticky sessions are more efficient. The distributor only needs to update sessions when they change. So if you update the session once when the user logs in, the distributed sessions can be very efficient.


Symmetrical sessions must use the 'always-load-session' flag to update each session data on each request. always-load-session is only needed for jdbc-store sessions. tcp-store sessions use a more-sophisticated protocol that eliminates the need for always-load-session, so tcp-store ignores the always-load-session flag.

The always-load-session attribute forces sessions to check the store for each request. By default, sessions are only loaded from persistent store when they are created. In a configuration with multiple symmetric web servers, sessions can be loaded on each request to ensure consistency.


By default, Resin only saves session data when you add new values to the session object, i.e. if the request calls setAttribute. This may be insufficient when storing large objects. For example, if you change an internal field of a large object, Resin will not automatically detect that change and will not save the session object.

With always-save-session Resin will always write the session to the store at the end of each request. Although this is less efficient, it guarantees that updates will get stored in the backup after each request.

TCP Distributed Sessions

More sophisticated than the Database sessions is the TCP-ring distributed sessions. With TCP distribution, the servers are arranged in a ring. Each session belongs to a single JVM, say JVM-c. The next JVM becomes the backup, e.g. JVM-d.

Because the storage is distributed across several machines, instead of tied to a single database server, the load is more fairly distributed. Also, because the sessions are distributed in a ring, there is no longer a single point of failure.

The configuration is in the web-app.


The <srun> and <srun-backup> hosts are treated as a ring. Each host will use the following host as a backup. When the session changes, the updates will be sent to the following host. When the host starts, it looks up old sessions in the following host before using its own saved state.

Symmetric load-balanced servers
  <http id='a' port='80'/>
  <srun id='a' host='host-a' port='6802'/>

  <http id='b' port='80'/>
  <srun id='b' host='host-b' port='6802'/>

  <host id=''>
  <web-app id=''>



More details on the tcp-based sessions are in the TCP-sessions page.

Database Based

Database backed sessions are the easiest to understand. Session data gets serialized and stored in a database. The advantage of database-backed sessions is it's simplicity. The disadvantage is that the database is often the performance bottleneck of the system. By adding load to an already-loaded system, you may harm performance. One way around that bottleneck is to use a small, quick database like MySQL for your session store and save the "Big Iron" database like Oracle for your core database needs.

The database must be specified using a resource-ref. The database store will automatically create a session table.


data-sourcedata source name for the table
table-namedatabase table for the session data
blob-typedatabase type for a blob
timestamp-typedatabase type for a blob
session-timeoutcleanup time

CREATE TABLE persistent_session (
  data BLOB,
  mod_time TIMESTAMP,

Copyright © 1998-2002 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.