documentation/9.3.0.v20150612/session-management.html - gerrit/www.eclipse.org/jetty - Git at Google

 <html><head>
       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    <title>Chapter&nbsp;10.&nbsp;Session Management</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.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 : The Definitive Reference"><link rel="up" href="administration.html" title="Part&nbsp;III.&nbsp;Jetty Administration Guide"><link rel="prev" href="startup-windows-service.html" title="Startup via Windows Service"><link rel="next" href="using-persistent-sessions.html" title="Using Persistent Sessions"><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"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/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.0.v20150612</span></td><td style="width: 50%"><script type="text/javascript">  (function() {
             var cx = '016459005284625897022:obd4lsai2ds';
             var gcse = document.createElement('script');
             gcse.type = 'text/javascript';
             gcse.async = true;
             gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
             '//www.google.com/cse/cse.js?cx=' + cx;
             var s = document.getElementsByTagName('script')[0];
             s.parentNode.insertBefore(gcse, s);
             })();
           </script><gcse:search></gcse:search></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">Chapter&nbsp;10.&nbsp;Session Management</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="startup-windows-service.html"><i class="icon-chevron-left"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;III.&nbsp;Jetty Administration Guide<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="using-persistent-sessions.html">Next <i class="icon-chevron-right"></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 from 1 day to full product delivery
       </p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="session-management"></a>Chapter&nbsp;10.&nbsp;Session Management</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="session-management.html#setting-session-characteristics">Setting Session Characteristics</a></span></dt><dt><span class="section"><a href="using-persistent-sessions.html">Using Persistent Sessions</a></span></dt><dt><span class="section"><a href="session-clustering-jdbc.html">Session Clustering with a Database</a></span></dt><dt><span class="section"><a href="session-clustering-mongodb.html">Session Clustering with MongoDB</a></span></dt><dt><span class="section"><a href="session-clustering-infinispan.html">Session Clustering with Infinispan</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="setting-session-characteristics"></a>Setting Session Characteristics</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="session-management.html#using-init-parameters">Using
     Init Parameters</a></span></dt><dt><span class="section"><a href="session-management.html#d0e9229">Using Servlet 3.0 Session Configuration</a></span></dt></dl></div><p>To modify the session characteristics of a web application, you can
   use the following parameters, applying them as in one of the example
   configurations:</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="using-init-parameters"></a>Using
     Init Parameters</h3></div></div></div><p>Use these parameters to set session characteristics.</p><div class="table"><a name="d0e9139"></a><p class="title"><b>Table&nbsp;10.1.&nbsp;Init Parameters</b></p><div class="table-contents"><table summary="Init Parameters" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="left">Context Parameter</th><th align="left">Default Value</th><th align="left">Description</th></tr></thead><tbody><tr><td>org.eclipse.jetty.servlet.SessionCookie</td><td>JSESSIONID</td><td>Session cookie name defaults to JSESSIONID, but can be set
             for a particular webapp with this context param.</td></tr><tr><td>org.eclipse.jetty.servlet.SessionIdPathParameterName</td><td>jsessionid</td><td>Session URL parameter name. Defaults to jsessionid, but can
             be set for a particular webapp with this context param. Set to
             "none" to disable URL rewriting.</td></tr><tr><td>org.eclipse.jetty.servlet.SessionDomain</td><td>-</td><td>Session Domain. If this property is set as a ServletContext
             param, then it is used as the domain for session cookies.If it is
             not set, then no domain is specified for the session
             cookie.</td></tr><tr><td>org.eclipse.jetty.servlet.SessionPath</td><td>-</td><td>Session Path. If this property is set as a ServletContext
             param, then it is used as the path for the session cookie. If it
             is not set, then the context path is used as the path for the
             cookie.</td></tr><tr><td>org.eclipse.jetty.servlet.MaxAge</td><td>-1</td><td>Session Max Age. If this property is set as a
             ServletContext param, then it is used as the max age for the
             session cookie. If it is not set, then a max age of -1 is
             used.</td></tr><tr><td>org.eclipse.jetty.servlet.CheckingRemoteSessionIdEncoding</td><td>false</td><td>If true, Jetty will add JSESSIONID parameter even when
             encoding external urls with calls to encodeURL(). False by
             default.</td></tr></tbody></table></div></div><br class="table-break"><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="applying-init-parameters"></a>Applying Init Parameters</h4></div></div></div><p>The following sections provide examples of how to apply the init
       parameters.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="context-parameter-example"></a>Context Parameter Example</h5></div></div></div><p>You can set these parameters as context parameters in a web
         application's <code class="filename"> WEB-INF/web.xml</code> file:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
           <![CDATA[

 <?xml version="1.0" encoding="UTF-8"?>
 <web-app
   xmlns="http://java.sun.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
   version="2.5">
   ...
   <context-param>
     <param-name>org.eclipse.jetty.servlet.SessionCookie</param-name>
     <param-value>XSESSIONID</param-value>
   </context-param>
   <context-param>
     <param-name>org.eclipse.jetty.servlet.SessionIdPathParameterName</param-name>
     <param-value>xsessionid</param-value>
   </context-param>
   ...
 </web-app>

         ]]>
         </script></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="web-application-examples"></a>Web Application Examples</h5></div></div></div><p>You can configure init parameters on a web application, either
         in code, or in a Jetty context xml file equivalent:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
           <![CDATA[

 <Configure class="org.eclipse.jetty.webapp.WebAppContext">
   <Set name="contextPath">/test</Set>
   <Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/test</Set>

   ...

   <Call name="setInitParameter">
         <Arg>org.eclipse.jetty.servlet.SessionCookie</Arg>
         <Arg>XSESSIONID</Arg>
   </Call>
   <Call name="setInitParameter">
         <Arg>org.eclipse.jetty.servlet.SessionIdPathParameterName</Arg>
         <Arg>xsessionid</Arg>
   </Call>
 </Configure>

         ]]>
         </script></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="init-parameter-examples"></a>SessionManager Examples</h5></div></div></div><p>You can configure init parameters directly on a
         <code class="code">SessionManager</code> instance, either in code or the equivalent
         in xml:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
           <![CDATA[

 <Configure class="org.eclipse.jetty.webapp.WebAppContext">
   <Set name="contextPath">/test</Set>
   <Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/test</Set>

    ...

   <Get name="sessionHandler">
      <Set name="sessionManager">
          <New class="org.eclipse.jetty.server.session.HashSessionManager">
             <Set name="sessionCookie">XSESSIONID</Set>
             <Set name="sessionIdPathParameterName">xsessionid</Set>
          </New>
      </Set>
   </Get>
 </Configure>

         ]]>
         </script></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e9229"></a>Using Servlet 3.0 Session Configuration</h3></div></div></div><p>With the advent of <a class="link" href="http://jcp.org/en/jsr/detail?id=315" target="_top"> Servlet Specification
     3.0</a> there are new APIs for configuring session handling
     characteristics. What was achievable before only via jetty-specific <a class="link" href="session-management.html#session-init-params">init-parameters</a> can now be achieved
     in a container-agostic manner either in code, or via web.xml.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="session-cookie-configuration"></a>SessionCookieConfiguration</h4></div></div></div><p>The <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionCookieConfig.html" target="_top">javax.servlet.SessionCookieConfig</a>
       class can be used to set up session handling characteristics. For full
       details, consult the <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionCookieConfig.html" target="_top">javadoc</a>.</p><p>Here's an example of how you use it: this is a
       ServletContextListener that retrieves the SessionCookieConfig and sets
       up some new values for it when the context is being initialized:</p><p><script type="syntaxhighlighter" class="brush: java;toolbar: false">
           <![CDATA[import javax.servlet.SessionCookieConfig;
 import javax.servlet.ServletContextEvent;
 import javax.servlet.ServletContextListener;

 public class TestListener implements ServletContextListener
 {

     public void contextInitialized(ServletContextEvent sce)
     {
         String comment = "This is my special cookie configuration";
         String domain = "foo.com";
         String path = "/my/special/path";
         boolean isSecure = true;
         boolean httpOnly = false;
         int maxAge = 30000;
         String cookieName = "FOO_SESSION";


         SessionCookieConfig scf = sce.getServletContext().getSessionCookieConfig();

         scf.setComment(comment);
         scf.setDomain(domain);
         scf.setHttpOnly(httpOnly);
         scf.setMaxAge(maxAge);
         scf.setPath(path);
         scf.setSecure(isSecure);
         scf.setName(cookieName);
     }

     public void contextDestroyed(ServletContextEvent sce)
     {

     }
 }]]>
         </script>You can also use web.xml to configure the session handling
       characteristics instead: here's an example, doing exactly the same as we
       did above in code:</p><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
           <![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <web-app
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    metadata-complete="true"
    version="3.0">

    <session-config>
       <cookie-config>
          <comment>This is my special cookie configuration</comment>
          <domain>foo.com</domain>
          <http-only>false</http-only>
          <max-age>30000</max-age>
          <path>/my/special/path</path>
          <secure>true</secure>
          <name>FOO_SESSION</name>
       </cookie-config>
    </session-config>
 </web-app>]]>
         </script></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="session-tracking-modes"></a>SessionTrackingModes</h4></div></div></div><p>In addition to the configuration of <a class="link" href="session-management.html#session-cookie-configuration" title="SessionCookieConfiguration">session cookies</a>, since
       Servlet 3.0 you can also use the <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html" target="_top">javax.servlet.SessionTrackingMode</a>
       to configure session tracking.</p><p>To determine what are the <span class="emphasis"><em>default</em></span> session
       tracking characteristics used by the container, call:</p><script type="syntaxhighlighter" class="brush: java;toolbar: false">
           <![CDATA[javax.servlet.SessionContext.getDefaultSessionTrackingModes();]]>
         </script><p>This returns a java.util.Set of javax.servlet.SessionTrackingMode.
       The <span class="emphasis"><em>default</em></span> session tracking modes for Jetty
       are:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html#COOKIE" target="_top">SessionTrackingMode.COOKIE</a></p></li><li class="listitem"><p><a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html#URL" target="_top">SessionTrackingMode.URL</a></p></li></ul></div><p>To see which session tracking modes are actually in effect for
       this Context, the following call returns a java.util.Set of
       javax.servlet.SessionTrackingMode:</p><script type="syntaxhighlighter" class="brush: plain;toolbar: false">
           <![CDATA[javax.servlet.SessionContext.getEffectiveSessionTrackingModes();]]>
         </script><p>To change the session tracking modes, call:</p><script type="syntaxhighlighter" class="brush: java;toolbar: false">
           <![CDATA[javax.servlet.SessionContext.setSessionTrackingModes(Set<SessionTrackingMode>);]]>
         </script><p>You may also set the tracking mode in web.xml, eg:</p><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
           <![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <web-app
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    metadata-complete="true"
    version="3.0">

    <session-config>
       <tracking-mode>URL</tracking-mode>
       <tracking-mode>COOKIE</tracking-mode>
    </session-config>
 </web-app>]]>
         </script><p></p></div></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="startup-windows-service.html"><i class="icon-chevron-left"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="administration.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="using-persistent-sessions.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Startup via Windows Service&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Using Persistent Sessions</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/jetty-project/jetty-documentation">Contribute to this documentation at
                 <span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2015-06-15T13:18:21-05:00)</i></span></div></p><script 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" type="text/javascript">
   var _gaq = _gaq || [];
   _gaq.push(['_setAccount', 'UA-1149868-7']);
   _gaq.push(['_trackPageview']);

   (function() {
     var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
     ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
     var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
   })();
     </script></body></html>
	<html><head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>Chapter 10. Session Management</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.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 : The Definitive Reference"><link rel="up" href="administration.html" title="Part III. Jetty Administration Guide"><link rel="prev" href="startup-windows-service.html" title="Startup via Windows Service"><link rel="next" href="using-persistent-sessions.html" title="Using Persistent Sessions"><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"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/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.0.v20150612</span></td><td style="width: 50%"><script type="text/javascript"> (function() {
	var cx = '016459005284625897022:obd4lsai2ds';
	var gcse = document.createElement('script');
	gcse.type = 'text/javascript';
	gcse.async = true;
	gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
	'//www.google.com/cse/cse.js?cx=' + cx;
	var s = document.getElementsByTagName('script')[0];
	s.parentNode.insertBefore(gcse, s);
	})();
	</script><gcse:search></gcse:search></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">Chapter 10. Session Management</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="startup-windows-service.html"><i class="icon-chevron-left"></i> Previous</a> </td><th width="60%" align="center">Part III. Jetty Administration Guide<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="using-persistent-sessions.html">Next <i class="icon-chevron-right"></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 from 1 day to full product delivery
	</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="session-management"></a>Chapter 10. Session Management</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="session-management.html#setting-session-characteristics">Setting Session Characteristics</a></span></dt><dt><span class="section"><a href="using-persistent-sessions.html">Using Persistent Sessions</a></span></dt><dt><span class="section"><a href="session-clustering-jdbc.html">Session Clustering with a Database</a></span></dt><dt><span class="section"><a href="session-clustering-mongodb.html">Session Clustering with MongoDB</a></span></dt><dt><span class="section"><a href="session-clustering-infinispan.html">Session Clustering with Infinispan</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="setting-session-characteristics"></a>Setting Session Characteristics</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="session-management.html#using-init-parameters">Using
	Init Parameters</a></span></dt><dt><span class="section"><a href="session-management.html#d0e9229">Using Servlet 3.0 Session Configuration</a></span></dt></dl></div><p>To modify the session characteristics of a web application, you can
	use the following parameters, applying them as in one of the example
	configurations:</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="using-init-parameters"></a>Using
	Init Parameters</h3></div></div></div><p>Use these parameters to set session characteristics.</p><div class="table"><a name="d0e9139"></a><p class="title"><b>Table 10.1. Init Parameters</b></p><div class="table-contents"><table summary="Init Parameters" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="left">Context Parameter</th><th align="left">Default Value</th><th align="left">Description</th></tr></thead><tbody><tr><td>org.eclipse.jetty.servlet.SessionCookie</td><td>JSESSIONID</td><td>Session cookie name defaults to JSESSIONID, but can be set
	for a particular webapp with this context param.</td></tr><tr><td>org.eclipse.jetty.servlet.SessionIdPathParameterName</td><td>jsessionid</td><td>Session URL parameter name. Defaults to jsessionid, but can
	be set for a particular webapp with this context param. Set to
	"none" to disable URL rewriting.</td></tr><tr><td>org.eclipse.jetty.servlet.SessionDomain</td><td>-</td><td>Session Domain. If this property is set as a ServletContext
	param, then it is used as the domain for session cookies.If it is
	not set, then no domain is specified for the session
	cookie.</td></tr><tr><td>org.eclipse.jetty.servlet.SessionPath</td><td>-</td><td>Session Path. If this property is set as a ServletContext
	param, then it is used as the path for the session cookie. If it
	is not set, then the context path is used as the path for the
	cookie.</td></tr><tr><td>org.eclipse.jetty.servlet.MaxAge</td><td>-1</td><td>Session Max Age. If this property is set as a
	ServletContext param, then it is used as the max age for the
	session cookie. If it is not set, then a max age of -1 is
	used.</td></tr><tr><td>org.eclipse.jetty.servlet.CheckingRemoteSessionIdEncoding</td><td>false</td><td>If true, Jetty will add JSESSIONID parameter even when
	encoding external urls with calls to encodeURL(). False by
	default.</td></tr></tbody></table></div></div><br class="table-break"><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="applying-init-parameters"></a>Applying Init Parameters</h4></div></div></div><p>The following sections provide examples of how to apply the init
	parameters.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="context-parameter-example"></a>Context Parameter Example</h5></div></div></div><p>You can set these parameters as context parameters in a web
	application's <code class="filename"> WEB-INF/web.xml</code> file:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
	<![CDATA[

	<?xml version="1.0" encoding="UTF-8"?>
	<web-app
	xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	version="2.5">
	...
	<context-param>
	<param-name>org.eclipse.jetty.servlet.SessionCookie</param-name>
	<param-value>XSESSIONID</param-value>
	</context-param>
	<context-param>
	<param-name>org.eclipse.jetty.servlet.SessionIdPathParameterName</param-name>
	<param-value>xsessionid</param-value>
	</context-param>
	...
	</web-app>

	]]>
	</script></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="web-application-examples"></a>Web Application Examples</h5></div></div></div><p>You can configure init parameters on a web application, either
	in code, or in a Jetty context xml file equivalent:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
	<![CDATA[

	<Configure class="org.eclipse.jetty.webapp.WebAppContext">
	<Set name="contextPath">/test</Set>
	<Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/test</Set>

	...

	<Call name="setInitParameter">
	<Arg>org.eclipse.jetty.servlet.SessionCookie</Arg>
	<Arg>XSESSIONID</Arg>
	</Call>
	<Call name="setInitParameter">
	<Arg>org.eclipse.jetty.servlet.SessionIdPathParameterName</Arg>
	<Arg>xsessionid</Arg>
	</Call>
	</Configure>

	]]>
	</script></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="init-parameter-examples"></a>SessionManager Examples</h5></div></div></div><p>You can configure init parameters directly on a
	<code class="code">SessionManager</code> instance, either in code or the equivalent
	in xml:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
	<![CDATA[

	<Configure class="org.eclipse.jetty.webapp.WebAppContext">
	<Set name="contextPath">/test</Set>
	<Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/test</Set>

	...

	<Get name="sessionHandler">
	<Set name="sessionManager">
	<New class="org.eclipse.jetty.server.session.HashSessionManager">
	<Set name="sessionCookie">XSESSIONID</Set>
	<Set name="sessionIdPathParameterName">xsessionid</Set>
	</New>
	</Set>
	</Get>
	</Configure>

	]]>
	</script></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e9229"></a>Using Servlet 3.0 Session Configuration</h3></div></div></div><p>With the advent of <a class="link" href="http://jcp.org/en/jsr/detail?id=315" target="_top"> Servlet Specification
	3.0</a> there are new APIs for configuring session handling
	characteristics. What was achievable before only via jetty-specific <a class="link" href="session-management.html#session-init-params">init-parameters</a> can now be achieved
	in a container-agostic manner either in code, or via web.xml.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="session-cookie-configuration"></a>SessionCookieConfiguration</h4></div></div></div><p>The <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionCookieConfig.html" target="_top">javax.servlet.SessionCookieConfig</a>
	class can be used to set up session handling characteristics. For full
	details, consult the <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionCookieConfig.html" target="_top">javadoc</a>.</p><p>Here's an example of how you use it: this is a
	ServletContextListener that retrieves the SessionCookieConfig and sets
	up some new values for it when the context is being initialized:</p><p><script type="syntaxhighlighter" class="brush: java;toolbar: false">
	<![CDATA[import javax.servlet.SessionCookieConfig;
	import javax.servlet.ServletContextEvent;
	import javax.servlet.ServletContextListener;

	public class TestListener implements ServletContextListener
	{

	public void contextInitialized(ServletContextEvent sce)
	{
	String comment = "This is my special cookie configuration";
	String domain = "foo.com";
	String path = "/my/special/path";
	boolean isSecure = true;
	boolean httpOnly = false;
	int maxAge = 30000;
	String cookieName = "FOO_SESSION";


	SessionCookieConfig scf = sce.getServletContext().getSessionCookieConfig();

	scf.setComment(comment);
	scf.setDomain(domain);
	scf.setHttpOnly(httpOnly);
	scf.setMaxAge(maxAge);
	scf.setPath(path);
	scf.setSecure(isSecure);
	scf.setName(cookieName);
	}

	public void contextDestroyed(ServletContextEvent sce)
	{

	}
	}]]>
	</script>You can also use web.xml to configure the session handling
	characteristics instead: here's an example, doing exactly the same as we
	did above in code:</p><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
	<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<web-app
	xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
	metadata-complete="true"
	version="3.0">

	<session-config>
	<cookie-config>
	<comment>This is my special cookie configuration</comment>
	<domain>foo.com</domain>
	<http-only>false</http-only>
	<max-age>30000</max-age>
	<path>/my/special/path</path>
	<secure>true</secure>
	<name>FOO_SESSION</name>
	</cookie-config>
	</session-config>
	</web-app>]]>
	</script></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="session-tracking-modes"></a>SessionTrackingModes</h4></div></div></div><p>In addition to the configuration of <a class="link" href="session-management.html#session-cookie-configuration" title="SessionCookieConfiguration">session cookies</a>, since
	Servlet 3.0 you can also use the <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html" target="_top">javax.servlet.SessionTrackingMode</a>
	to configure session tracking.</p><p>To determine what are the <span class="emphasis"><em>default</em></span> session
	tracking characteristics used by the container, call:</p><script type="syntaxhighlighter" class="brush: java;toolbar: false">
	<![CDATA[javax.servlet.SessionContext.getDefaultSessionTrackingModes();]]>
	</script><p>This returns a java.util.Set of javax.servlet.SessionTrackingMode.
	The <span class="emphasis"><em>default</em></span> session tracking modes for Jetty
	are:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html#COOKIE" target="_top">SessionTrackingMode.COOKIE</a></p></li><li class="listitem"><p><a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html#URL" target="_top">SessionTrackingMode.URL</a></p></li></ul></div><p>To see which session tracking modes are actually in effect for
	this Context, the following call returns a java.util.Set of
	javax.servlet.SessionTrackingMode:</p><script type="syntaxhighlighter" class="brush: plain;toolbar: false">
	<![CDATA[javax.servlet.SessionContext.getEffectiveSessionTrackingModes();]]>
	</script><p>To change the session tracking modes, call:</p><script type="syntaxhighlighter" class="brush: java;toolbar: false">
	<![CDATA[javax.servlet.SessionContext.setSessionTrackingModes(Set<SessionTrackingMode>);]]>
	</script><p>You may also set the tracking mode in web.xml, eg:</p><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
	<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<web-app
	xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
	metadata-complete="true"
	version="3.0">

	<session-config>
	<tracking-mode>URL</tracking-mode>
	<tracking-mode>COOKIE</tracking-mode>
	</session-config>
	</web-app>]]>
	</script><p></p></div></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="startup-windows-service.html"><i class="icon-chevron-left"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="administration.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="using-persistent-sessions.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Startup via Windows Service </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top"> Using Persistent Sessions</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/jetty-project/jetty-documentation">Contribute to this documentation at
	<span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2015-06-15T13:18:21-05:00)</i></span></div></p><script 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" type="text/javascript">
	var _gaq = _gaq \|\| [];
	_gaq.push(['_setAccount', 'UA-1149868-7']);
	_gaq.push(['_trackPageview']);

	(function() {
	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();
	</script></body></html>