| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Session Clustering with a Database</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="session-management.html" title="Chapter 10. Session Management"><link rel="prev" href="using-persistent-sessions.html" title="Using Persistent Sessions"><link rel="next" href="session-clustering-mongodb.html" title="Session Clustering with MongoDB"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script> |
| hljs.initHighlightingOnLoad(); |
| </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small"> |
| Version: 9.3.28.v20191105</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Session Clustering with a Database</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using-persistent-sessions.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a> </td><th width="60%" align="center">Chapter 10. Session Management<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="session-clustering-mongodb.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at |
| <span class="website">www.webtide.com</span></a></h5><p> |
| private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... |
| scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development |
| </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="session-clustering-jdbc"></a>Session Clustering with a Database</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="session-clustering-jdbc.html#_configuration">Configuration</a></span></dt><dt><span class="section"><a href="session-clustering-jdbc.html#_the_jdbc_session_module">The jdbc-session Module</a></span></dt></dl></div><p>Jetty can support session clustering by persisting sessions to a shared database. |
| Each Jetty instance locally caches sessions for which it has received requests, writing any changes to the session through to the database as the request exits the server. |
| Sessions must obey the Serialization contract, and servlets must call the <code class="literal">Session.setAttribute()</code> method to ensure that changes are persisted.</p><p>The persistent session mechanism works in conjunction with a load balancer that supports stickiness. |
| Stickiness can be based on various data items, such as source IP address or characteristics of the session ID or a load-balancer specific mechanism. |
| For those load balancers that examine the session ID, the Jetty persistent session mechanism appends a node ID to the session ID, which can be used for routing.</p><p>In this type of solution, the database can become both a bottleneck and a single point of failure. |
| Jetty takes steps to reduce the load on the database (discussed below), but in a heavily loaded environment you might need to investigate other optimization strategies such as local caching and database replication. |
| You should also consult your database vendor’s documentation for information on how to ensure high availability and failover of your database.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configuration"></a>Configuration</h3></div></div></div><p>There are two components to session management in Jetty: a session ID manager and a session manager.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">The session ID manager ensures that session IDs are unique across all webapps hosted on a Jetty instance, and thus there can only be one session ID manager per Jetty instance.</li><li class="listitem">The session manager handles the session lifecycle (create/update/invalidate/expire) on behalf of a web application, so there is one session manager per web application instance.</li></ul></div><p>These managers also cooperate and collaborate with the <code class="literal">org.eclipse.jetty.server.session.SessionHandler</code> to enable cross-context dispatch.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_the_jdbc_session_module"></a>The jdbc-session Module</h3></div></div></div><p>When using the jetty distribution, to enable jdbc session persistence, you will first need to enable the jdbc-session <a class="link" href="startup-modules.html" title="Managing Startup Modules">module</a> for your <a class="link" href="quickstart-running-jetty.html#creating-jetty-base" title="Creating a new Jetty Base">base</a> using the <code class="literal">--add-to-start</code> or <code class="literal">--add-to-startd</code> argument to the <a class="link" href="startup.html#startup-overview" title="Startup Overview">start.jar</a>.</p><p>You will also find the following properties, either in your base’s start.d/jdbc-session.ini file or appended to your start.ini, depending on how you enabled the module:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>## Unique identifier for this node in the cluster |
| jetty.jdbcSession.workerName=node1 |
| |
| ##Uncomment either the datasource name or driverClass and connectionURL |
| #jetty.jdbcSession.datasource=sessions |
| jetty.jdbcSession.driverClass=org.apache.derby.jdbc.EmbeddedDriver |
| jetty.jdbcSession.connectionURL=jdbc:derby:sessions;create=true</code></pre><div class="variablelist"><dl class="variablelist"><dt><span class="term">jetty.jdbcSession.workerName</span></dt><dd>The name that uniquely identifies this node in the cluster. |
| This value will also be used by the sticky load balancer to identify the node. |
| Don’t forget to change the value of this property on <span class="strong"><strong>each</strong></span> node on which you enable jdbc session clustering.</dd><dt><span class="term">jetty.jdbcSession.scavenge</span></dt><dd>The time in seconds between sweeps of a task which scavenges old expired sessions. |
| The default is 10 minutess. |
| Increasing the frequency is not recommended as doing so increases the load on the database with very little gain.</dd><dt><span class="term">jetty.jdbcSession.datasource</span></dt><dd>The name of a <code class="literal">javax.sql.DataSource</code> that gives access to the database that holds the session information. |
| You should configure <span class="strong"><strong>either</strong></span> this or the jdbc driver information described next.</dd><dt><span class="term">jetty.jdbcSession.datasource and jetty.jdbcSession.connectionURL</span></dt><dd>This is the name of the jdbc driver class, and a jdbc connection url suitable for that driver. |
| You should configure <span class="strong"><strong>either</strong></span> this or the jdbc datasource name described above.</dd></dl></div><p>These properties are applied to the <code class="literal">JDBCSessionIdManager</code> described below.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_configuring_the_jdbcsessionidmanager"></a>Configuring the JDBCSessionIdManager</h4></div></div></div><p>The jdbc-session module will have installed file called <code class="literal">$\{jetty.home}/etc/jetty-jdbc-sessions.xml</code>. |
| This file configures an instance of the <code class="literal">JDBCSessionIdManager</code> that will be shared across all webapps deployed on that server. |
| It looks like this:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><?xml version="1.0"?> |
| <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> |
| |
| <Configure id="Server" class="org.eclipse.jetty.server.Server"> |
| |
| |
| <!-- ===================================================================== --> |
| <!-- Configure a SessionIdManager --> |
| <!-- ===================================================================== --> |
| <Set name="sessionIdManager"> |
| <New id="idMgr" class="org.eclipse.jetty.server.session.JDBCSessionIdManager"> |
| <Arg> |
| <Ref refid="Server"/> |
| </Arg> |
| <Set name="workerName"><Property name="jetty.jdbcSession.workerName" default="node1"/></Set> |
| <Set name="scavengeInterval"><Property name="jetty.jdbcSession.scavenge" default="1800"/></Set> |
| |
| <!-- ===================================================================== --> |
| <!-- Uncomment either the datasource or driver setup and configure --> |
| <!-- ===================================================================== --> |
| |
| <!-- |
| <Set name="DatasourceName"><Property name="jetty.jdbcSession.datasource" default="javax.sql.DataSource/default"/></Set> |
| --> |
| <!-- |
| <Call name="setDriverInfo"> |
| <Arg><Property name="jetty.jdbcSession.driverClass"/></Arg> |
| <Arg><Property name="jetty.jdbcSession.connectionURL"/></Arg> |
| </Call> |
| --> |
| </New> |
| </Set> |
| |
| </Configure></code></pre><p>As well as uncommenting and setting up appropriate values for the properties discussed above, you will also need to edit this file and uncomment <span class="strong"><strong>either</strong></span> the data source or the driver info elements.</p><p>As Jetty configuration files are direct mappings of XML to Java, it is straight forward to do this in code:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>Server server = new Server(); |
| ... |
| JDBCSessionIdManager idMgr = new JDBCSessionIdManager(server); |
| idMgr.setWorkerName("node1"); |
| idMgr.setDriverInfo("com.mysql.jdbc.Driver", "jdbc:mysql://127.0.0.1:3306/sessions?user=janb"); |
| idMgr.setScavengeInterval(600); |
| server.setSessionIdManager(idMgr);</code></pre><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="_configuring_the_database_schema"></a>Configuring the Database Schema</h5></div></div></div><p>You may find it necessary to change the names of the tables and columns that the JDBC Session management uses to store the session information. |
| The defaults used are:</p><div class="table"><a name="d0e10488"></a><p class="title"><b>Table 10.2. Default Values for Session Id Table</b></p><div class="table-contents"><table class="table" summary="Default Values for Session Id Table" border="1"><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th align="left" valign="top">table name</th><th align="left" valign="top">JettySessionIds</th></tr></thead><tbody><tr><td align="left" valign="top"><p>columns</p></td><td align="left" valign="top"><p>id</p></td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="d0e10508"></a><p class="title"><b>Table 10.3. Default Values for Session Table</b></p><div class="table-contents"><table class="table" summary="Default Values for Session Table" border="1"><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th align="left" valign="top">table name</th><th align="left" valign="top">JettySessions</th></tr></thead><tbody><tr><td align="left" valign="top"><p>columns</p></td><td align="left" valign="top"><p>rowId, sessionId, contextPath, virtualHost, lastNode, |
| accessTime, lastAccessTime, createTime, cookieTime, lastSavedTime, |
| expiryTime, maxInterval, map</p></td></tr></tbody></table></div></div><br class="table-break"><p>To change these values, use the <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.3.28.v20191105/org/eclipse/jetty/server/session/SessionIdTableSchema.html" target="_top">org.eclipse.jetty.server.session.SessionIdTableSchema</a> and <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.3.28.v20191105/org/eclipse/jetty/server/session/SessionTableSchema.html" target="_top">org.eclipse.jetty.server.session.SessionTableSchema</a> classes. |
| These classes have getter/setter methods for the table name and all columns.</p><p>Here’s an example of changing the name of <code class="literal">JettySessionsId</code> table and its single column. |
| This example will use java code, but as explained above, you may also do this via a Jetty xml configuration file:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>JDBCSessionIdManager idManager = new JDBCSessionIdManager(server); |
| |
| SessionIdTableSchema idTableSchema = new SessionIdTableSchema(); |
| idTableSchema.setTableName("mysessionids"); |
| idTableSchema.setIdColumn("theid"); |
| idManager.setSessionIdTableSchema(idTableSchema);</code></pre><p>In a similar fashion, you can change the names of the table and columns for the <code class="literal">JettySessions</code> table. |
| <span class="strong"><strong>Note</strong></span> that both the <code class="literal">SessionIdTableSchema</code> and the <code class="literal">SessionTableSchema</code> instances are set on the <code class="literal">JDBCSessionIdManager</code> class.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>JDBCSessionIdManager idManager = new JDBCSessionIdManager(server); |
| |
| SessionTableSchema sessionTableSchema = new SessionTableSchema(); |
| sessionTableSchema.setTableName("mysessions"); |
| sessionTableSchema.setIdColumn("mysessionid"); |
| sessionTableSchema.setAccessTimeColumn("atime"); |
| sessionTableSchema.setContextPathColumn("cpath"); |
| sessionTableSchema.setCookieTimeColumn("cooktime"); |
| sessionTableSchema.setCreateTimeColumn("ctime"); |
| sessionTableSchema.setExpiryTimeColumn("extime"); |
| sessionTableSchema.setLastAccessTimeColumn("latime"); |
| sessionTableSchema.setLastNodeColumn("lnode"); |
| sessionTableSchema.setLastSavedTimeColumn("lstime"); |
| sessionTableSchema.setMapColumn("mo"); |
| sessionTableSchema.setMaxIntervalColumn("mi"); |
| idManager.setSessionTableSchema(sessionTableSchema);</code></pre></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_configuring_the_jdbcsessionmanager"></a>Configuring the JDBCSessionManager</h4></div></div></div><p>As mentioned elsewhere, there should be one <code class="literal">JDBCSessionManager</code> per context (e.g. webapp). |
| It will need to reference the single <code class="literal">JDBCSessionIdManager</code> configured previously for the Server.</p><p>The way you configure a <code class="literal">JDBCSessionManager</code> depends on whether you’re configuring from a context xml file, a <code class="literal">jetty-web.xml</code> file or code. |
| The basic difference is how you get a reference to the Jetty <code class="literal">org.eclipse.jetty.server.Server</code> instance.</p><p>From a context xml file, you reference the Server instance as a Ref:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code> <Ref id="Server"> |
| <Call id="idMgr" name="getSessionIdManager"/> |
| </Ref> |
| <Set name="sessionHandler"> |
| <New class="org.eclipse.jetty.server.session.SessionHandler"> |
| <Arg> |
| <New id="jdbcmgr" class="org.eclipse.jetty.server.session.JDBCSessionManager"> |
| <Set name="sessionIdManager"> |
| <Ref id="idMgr"/> |
| </Set> |
| </New> |
| </Arg> |
| </New> |
| </Set></code></pre><p>From a <code class="literal">WEB-INF/jetty-web.xml</code> file, you can reference the Server instance directly:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code><Get name="server"> |
| <Get id="idMgr" name="sessionIdManager"/> |
| </Get> |
| <Set name="sessionHandler"> |
| <New class="org.eclipse.jetty.server.session.SessionHandler"> |
| <Arg> |
| <New class="org.eclipse.jetty.server.session.JDBCSessionManager"> |
| <Set name="sessionIdManager"> |
| <Ref id="idMgr"/> |
| </Set> |
| </New> |
| </Arg> |
| </New> |
| </Set></code></pre><p>If you’re embedding this in code:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>//assuming you have already set up the JDBCSessionIdManager as shown earlier |
| //and have a reference to the Server instance: |
| |
| WebAppContext wac = new WebAppContext(); |
| ... //configure your webapp context |
| JDBCSessionManager jdbcMgr = new JDBCSessionManager(); |
| jdbcMgr.setSessionIdManager(server.getSessionIdManager()); |
| SessionHandler sessionHandler = new SessionHandler(jdbcMgr); |
| wac.setSessionHandler(sessionHandler);</code></pre></div></div></div><script type="text/javascript"> |
| SyntaxHighlighter.all() |
| </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using-persistent-sessions.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="session-management.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="session-clustering-mongodb.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Using Persistent Sessions </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top"> Session Clustering with MongoDB</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout"> |
| See an error or something missing? |
| <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at |
| <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2019-11-05)</i></span></div></p></body></html> |
