<document>
<header>
  <product>resin</product>
  <title>Session tags</title>
  <version>Resin 3.0</version>

  <description>
    <p>Resin adds a number of additions to the standard <var>session-config</var> tag.</p>
  </description>
</header>

<body>

<localtoc/>

<defun title="&lt;cookie-domain>">
<parents>session-config</parents>

<p>&lt;cookie-domain> configures the host domain to use for sessions,
i.e. value of the Domain cookie attributes.</p>

<p>By default, browsers only send cookies back to the exact host
which sent them.  In some virtual host cases, it makes sense to share
the same cookie value for multiple virtual hosts in the same domain.
For example, <var>caucho.com</var> might want a single cookie to be
used for both <var>gryffindor.caucho.com</var>
and <var>slytherin.caucho.com</var>.  In this case
the <code>cookie-domain</code> would be set to <var>caucho.com</var>.</p>

<example title="cookie-domain for caucho.com">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="app-tier">

  &lt;host id="caucho.com">
    &lt;host-alias>gryffindor.caucho.com&lt;/host-alias>
    &lt;host-alias>slytherin.caucho.com&lt;/host-alias>

    &lt;web-app-default>

      &lt;session-config cookie-domain="caucho.com"/>

    &lt;/web-app-default>
  &lt;/host>

&lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;cookie-length>">
<parents>session-config</parents>

<p>&lt;cookie-length> sets the length of the generated cookie
value.  In some rare cases, the cookie-length might need to be shortened
or the cookie-length might be extended to add randomness to the
cookie value.  For the most part, this value should be left alone.</p>

<default>14</default>

</defun>

<defun title="&lt;cookie-max-age>">
<parents>session-config</parents>

<p>&lt;cookie-max-age> sets how long the browser should keep the
session cookie.</p>

<p>By default, browsers keep cookies as long as they are open.  When
the browser is restarted, the cookies are dropped.  cookie-max-age
tells the browser to keep the cookie for a certain time period.
Applications can make this time "infinite" by setting a large number.</p>

</defun>

<defun title="&lt;cookie-version>">
<p>&lt;cookie-version> sets the version of the cookie spec for sessions.</p>

<default>1.0</default>
</defun>

<defun title="&lt;ignore-serialization-errors>">
<parents>session-config</parents>

<p>&lt;ignore-serialization-errors> is used with persistent sessions
in certain rare cases where some session data is serializable and other
data is not serializable.  &lt;ignore-serialization-errors> simply
skips session values which do not implement <code>java.io.Serializable</code>
when serializing the session.</p>

<default>false</default>

</defun>

<defun title="&lt;session-config>" version="Servlet 2.2">
<p>Session configuration parameters.</p>

<deftable-childtags title="Servlet 2.4 definition for session-timeout">

<tr>
  <td>session-timeout</td>
  <td>The session timeout in minutes, 0 means never timeout.</td>
  <td>30 minutes</td>
</tr>
</deftable-childtags>

<p>Resin adds a number of <var>session-config</var> tags.</p>

<deftable-childtags title="Resin extensions to session-config">
<tr>
  <td>always-load-session</td>
  <td>Reload data from the store on every request. (resin 1.2)</td>
  <td>false</td>
</tr>
<tr>
  <td>always-save-session</td>
  <td>Save session data to the store on every request. (resin 1.2)</td>
  <td>false</td>
</tr>
<tr>
  <td>cookie-version</td>
  <td>Version of the cookie spec for sessions. (resin 1.2)</td>
  <td>1.0</td>
</tr>
<tr>
  <td>cookie-domain</td>
  <td>Domain for session cookies. (resin 1.2)</td>
  <td>none</td>
</tr>
<tr>
  <td>cookie-max-age</td>
  <td>Max age for persistent session cookies. (resin 2.0)</td>
  <td>none</td>
</tr>
<tr>
  <td>cookie-length</td>
  <td>Maximum length of the cookie. (resin 2.1.1)</td>
  <td>Integer.MAX_VALUE</td>
</tr>
<tr>
  <td>enable-cookies</td>
  <td>Enable cookies for sessions. (resin 1.1)</td>
  <td>true</td>
</tr>
<tr>
  <td>enable-url-rewriting</td>
  <td>Enable URL rewriting for sessions. (resin 1.1)</td>
  <td>true</td>
</tr>
<tr>
  <td>ignore-serialization-errors</td>
  <td>When persisting a session, ignore any values which don't implement java.io.Serializable</td>
  <td>false</td>
</tr>
<tr>
  <td>invalidate-after-listener</td>
  <td>Invalidate the session after notifying session listeners.</td>
  <td>false</td>
</tr>
<tr>
  <td>reuse-session-id</td>
  <td>Reuse the session id even if the session has timed out. (resin 2.0.4)</td>
  <td>true</td>
</tr>
<tr>
  <td>save-only-on-shutdown</td>
  <td>Only save session when the application shuts down. (resin 1.2.3)</td>
  <td>false</td>
</tr>
<tr>
  <td>ssl-cookie-name</td>
  <td>Set a different cookie name to use for SSL connections, and add the
      "secure" flag when setting the cookie in the browser.</td>
  <td></td>
</tr>
<tr>
  <td>session-max</td>
  <td>Maximum active sessions</td>
  <td>4096</td>
</tr>
<tr>
  <td>use-persistent-store</td>
  <td>Uses the current <a href="resin.xtp#persistent-store">persistent-store</a> to save sessions. (resin 3.0.8)</td>
  <td>none</td>
</tr>
</deftable-childtags>

<p>By default, both <code>enable-cookies</code> and
<code>enable-url-rewriting</code> are true. To force url rewriting, you
would create a configuration like:</p>

<example>
&lt;web-app id='/'&gt;

  &lt;session-config
   enable-cookies='false'
   enable-url-rewriting='true'/&gt;

&lt;/web-app&gt;
</example>

<p>The <var>session-timeout</var> and <var>session-max</var> are usually
used together to control the number of
sessions.  Sessions are stored in an LRU cache. When the number
of sessions in the cache fills up past <var>session-max</var>, the
oldest sessions are recovered.  In addition, sessions idle for
longer than <code>session-timeout</code> are purged.</p>

<example title="using session-config and session-timeout to control the number of sessions">
&lt;web-app id='/dir'&gt;

  &lt;session-config&gt;
     &lt;!-- 2 hour timeout --&gt;
     &lt;session-timeout&gt;120&lt;/session-timeout&gt;
     &lt;session-max&gt;4096&lt;/session-max&gt;
  &lt;/session-config&gt;

&lt;/web-app&gt;
</example>

<p><var>cookie-length</var> is used to limit the maximum length for
the session's generated cookie for special situations like WAP devices.
Reducing this value reduces the randomness in the cookie and increases the
chance of session collisions.</p>

<p><var>reuse-session-id</var> defaults to true so that Resin can share the session
id amongst different web-apps.</p>

<p>The class that corresponds to &lt;session-config&gt; is <a href="javadoc|com.caucho.server.session.SessionManager|"/></p>

</defun>

<defun title="&lt;session-max>">
<parents>session-config</parents>

<p>&lt;session-max> sets the maximum number of sessions stored
in memory for a particular &lt;web-app>.  The total number of persisted
sessions may be larger.</p>

<default>4096</default>

</defun>

<defun title="&lt;save-mode>">
<parents>session-config</parents>

<p>&lt;save-mode> configures when Resin should save a persistence
session during a request.  The values are:</p>

<deftable>
<tr>
  <td>after-request</td>
  <td>Save the session after the request has been served and completed</td>
</tr>
<tr>
  <td>before-headers</td>
  <td>Save the session before sending headers to the browser</td>
</tr>
<tr>
  <td>on-shutdown</td>
  <td>Only save the session when Resin is shutting down</td>
</tr>
</deftable>

<p>In some situations, like redirects, a fast browser can send a request
back to Resin before the session is persisted with the
<var>after-request</var> save-mode.  If the server is configured
without <g>sticky sessions</g>, the load balancer might send the request
to a different server, which may not get the updated session.
In the situation, either the save-mode should be changed to
<var>before-headers</var> or sticky sessions should be enabled.</p>

<p>If the save-mode is <var>before-headers</var>, the application should
take care to make any session changes before sending data to the browser.</p>

<default>after-request</default>

</defun>

<defun title="&lt;session-timeout>">
<parents>session-config</parents>

<p>&lt;session-timeout> sets how long a &lt;web-app> should keep an
idle session before invalidating it.  The value is specified in minutes.</p>

<default>30min</default>

</defun>

</body>

</document>
