<title>Persistent and Distributed Sessions</title>

Sessions can now 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.

<section title='File Based'>

<ul>
<li>For single-server configurations
<li>Useful in development when classes change often
</ul>

<p/>Persistent sessions are configured in the <var/web-app/>.
File-based sessions use <var/file-store/>

<example>
&lt;web-app>
  &lt;session-config>
    &lt;file-store>WEB-INF/sessions&lt;/file-store>
  &lt;/session-config>
&lt;/web-app>
</example>

<p/>Sessions are stored as files in the <var/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.

<p/>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.

</section>

<section title="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.

<p/>Load balancing with multiple machines either uses <var/sticky sessions/> or
<var/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.

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

<subsection title="Symmetrical Sessions">

<p/>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 <var/always-load-session/> attribute described below.
Each request must load the most up-to-date version of the session.

<p/>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.

</subsection>
<subsection title="Sticky Sessions">

<p/>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.

<p/>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.

</subsection>

</section>

<section title="Database Based">

<p/>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.

<p/>The database must be specified using a <var/resource-ref/>.
The database store will automatically
create a <var/session/> table.

<example>
&lt;web-app>
  &lt;session-config>
    &lt;jdbc-store>test&lt;/jdbc-store>
    &lt;always-save-session/>
  &lt;/session-config>
&lt;/web-app>
</example>

<deftable>
<tr><td>data-source<td>data source name for the table
<tr><td>table-name<td>database table for the session data
<tr><td>blob-type<td>database type for a blob
<tr><td>timestamp-type<td>database type for a blob
<tr><td>session-timeout<td>cleanup time
</deftable>

<example>
CREATE TABLE session (
  id VARCHAR(64) NOT NULL,
  data BLOB,
  mod_time TIMESTAMP,
  PRIMARY KEY(id)
)
</example>
</section>

<section title='always-load-session'>

<p/>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 <var/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.

</section>

<section title='always-save-session'>

<p/>By default, Resin only saves session data when you add new values
to the session object, i.e. if the request calls <var/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.

<p/>With <var/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.

</section>

<section title="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.

<p/>The configuration is in the <var/web-app/>

<example>
&lt;web-app>
  &lt;session-config>
    &lt;tcp-store/>
  &lt;/session-config>
&lt;/web-app>
</example>

<p/>The &lt;srun> and &lt;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.

<p/>In conjunction with the <var/always-load-session/> flag,
symmetric (non-sticky) load-balanced servers can now use the tcp-ring.

<example title="Symmetric load-balanced servers">
&lt;http-server>
  &lt;http id='a' port='80'/>
  &lt;srun id='a' host='host-a' port='6802'/>

  &lt;http id='b' port='80'/>
  &lt;srun id='b' host='host-b' port='6802'/>

  &lt;host id=''>
  &lt;web-app id=''>

  &lt;session-config>
    &lt;tcp-store/>
    &lt;always-load-session/>
  &lt;/session-config>

  &lt;/web-app>
  &lt;/host>
&lt;/http-server>
</example>

</section>
