Sessions redux rough drafts.

Signed-off-by: WalkerWatch <ctwalker@gmail.com>

jetty-documentation/src/main/asciidoc/administration/sessions/chapter.adoc

@@ -17,9 +17,21 @@
 [[session-management]]
 == Session Management
 
-include::setting-session-characteristics.adoc[]
+Sessions are a concept within the Servlet api which allow requests to store and retrieve information across the time a user spends in an application.
-include::using-persistent-sessions.adoc[]
+Choosing the correct session manager implementation is an important consideration for every application as each can fit and perform optimally in different situations.
-include::session-clustering-jdbc.adoc[]
+If you need a simple in-memory session manager that can persist to disk then the File Session Manager can be a good place to start.
-include::session-clustering-mongodb.adoc[]
+If you need a session manager that can work in a clustered scenario with multiple instances of Jetty, then the JDBC session manager can be an excellent option.
-include::session-clustering-infinispan.adoc[]
+Jetty also offers more niche session managers that leverage backends such as MongoDB, Inifinispan, or even Google's Cloud Data Store.
-include::session-clustering-gcloud-datastore.adoc[]
+
+include::session-hierarchy.adoc[]
+include::session-configuration-file-system.adoc[]
+include::session-configuration-jdbc.adoc[]
+include::session-configuration-mongodb.adoc[]
+include::session-configuration-infinispan.adoc[]
+include::session-configuration-gcloud.adoc[]
+//include::setting-session-characteristics.adoc[]
+//include::using-persistent-sessions.adoc[]
+//include::session-clustering-jdbc.adoc[]
+//include::session-clustering-mongodb.adoc[]
+//include::session-clustering-infinispan.adoc[]
+//include::session-clustering-gcloud-datastore.adoc[]

jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-infinispan.adoc

@@ -17,12 +17,12 @@
 [[session-clustering-infinispan]]
 === Session Clustering with Infinispan
 
-Jetty can support session clustering by persisting sessions to http://www.infinispan.org[Infinispan]. 
+Jetty can support session clustering by persisting sessions to http://www.infinispan.org[Infinispan].
 Each Jetty instance locally caches sessions for which it has received requests, writing any changes to the session through to Infinispan as the request exits the server.
 Sessions must obey the Serialization contract, and servlets must call the `Session.setAttribute()` method to ensure that changes are persisted.
 
-The persistent session mechanism works in conjunction with a load balancer that supports stickiness. 
+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. 
+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.
 
 ==== Configuration
@@ -38,9 +38,9 @@ These managers also cooperate and collaborate with the `org.eclipse.jetty.server
 
 When using the jetty distribution, to enable Infinispan session persistence, you will first need to enable the Infinispan link:#startup-modules[module] for your link:#creating-jetty-base[base] using the `--add-to-start` or `--add-to-startd` argument to the link:#startup-overview[start.jar].
 
-As part of the module installation, the necessary Infinispan jars will be dynamically downloaded and installed to your `${jetty.base}/lib/infinispan` directory. 
+As part of the module installation, the necessary Infinispan jars will be dynamically downloaded and installed to your `${jetty.base}/lib/infinispan` directory.
-If you need to up or downgrade the version of the Infinispan jars, then you can delete the jars that were automatically installed and replace them. 
+If you need to up or downgrade the version of the Infinispan jars, then you can delete the jars that were automatically installed and replace them.
-Once you've done that, you will need to prevent Jetty's startup checks from detecting the missing jars. 
+Once you've done that, you will need to prevent Jetty's startup checks from detecting the missing jars.
 To do that, you can use `--skip-file-validation=infinispan` argument to start.jar on the command line, or place that line inside `${jetty.base}/start.ini` to ensure it is used for every start.
 
 You will also find the following properties, either in your base's `start.d/infinispan.ini` file or appended to your `start.ini`, depending on how you enabled the module:
@@ -51,7 +51,7 @@ jetty.infinispanSession.workerName=node1
 ....
 
 jetty.infinispanSession.workerName::
-  The name that uniquely identifies this node in the cluster. 
+  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 *each* node on which you enable Infinispan session clustering.
 
@@ -59,8 +59,8 @@ These properties are applied to the `InfinispanSessionIdManager` described below
 
 ===== Configuring the InfinispanSessionIdManager
 
-The Infinispan module will have installed file called `$\{jetty.home}/etc/jetty-infinispan.xml`. 
+The Infinispan module will have installed file called `$\{jetty.home}/etc/jetty-infinispan.xml`.
-This file configures an instance of the `InfinispanSessionIdManager` that will be shared across all webapps deployed on that server. 
+This file configures an instance of the `InfinispanSessionIdManager` that will be shared across all webapps deployed on that server.
 It looks like this:
 
 [source, xml, subs="{sub-order}"]
@@ -68,23 +68,23 @@ It looks like this:
 include::{SRCDIR}/jetty-infinispan/src/main/config/etc/jetty-infinispan.xml[]
 ----
 
-As you can see, you configure the Infinispan http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_the_cache_apis[Cache] instance that the `InfinispanSessionIdManager` should use in this file. 
+As you can see, you configure the Infinispan http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_the_cache_apis[Cache] instance that the `InfinispanSessionIdManager` should use in this file.
-By default, the Infinispan http://infinispan.org/docs/7.1.x/getting_started/getting_started.html#_running_infinispan_on_a_single_node[Default cache] instance is used (e.g. on the local node). 
+By default, the Infinispan http://infinispan.org/docs/7.1.x/getting_started/getting_started.html#_running_infinispan_on_a_single_node[Default cache] instance is used (e.g. on the local node).
 You can instead use a custom Cache setup - the `jetty-infinispan.xml` file shows you how to configure a remote Cache (using the http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_using_hot_rod_server[hotrod java client]).
 
 The `InfinispanSessionIdManager` can be configured by calling setters:
 
 idleExpiryMultiple::
-  Sessions that are not immortal, e.g. they have an expiry time, have   their ids stored into Infinispan with an http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_expiration[idle  expiry timeout] equivalent to double the session's timeout. 
+  Sessions that are not immortal, e.g. they have an expiry time, have   their ids stored into Infinispan with an http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_expiration[idle  expiry timeout] equivalent to double the session's timeout.
-  This should be sufficient to ensure that a session id that is in-use by a session is never accidentally removed. 
+  This should be sufficient to ensure that a session id that is in-use by a session is never accidentally removed.
   However, should you wish to, you can configure this to any integral value to effectively increase the http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_expiration[idle expiry] timeout.
 
 ===== Configuring the InfinispanSessionManager
 
-As mentioned elsewhere, there should be one `InfinispanSessionManager` per context (e.g. webapp). 
+As mentioned elsewhere, there should be one `InfinispanSessionManager` per context (e.g. webapp).
 It will need to reference the single `InfinispanSessionIdManager` configured previously for the Server.
 
-The way you configure a `InfinispanSessionManager` depends on whether you're configuring from a context xml file, a `jetty-web.xml` file or code. 
+The way you configure a `InfinispanSessionManager` depends on whether you're configuring from a context xml file, a `jetty-web.xml` file or code.
 The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.server.Server` instance.
 
 From a context xml file, you reference the Server instance as a Ref:
@@ -96,7 +96,7 @@ From a context xml file, you reference the Server instance as a Ref:
     <Arg>-org.eclipse.jetty.session.infinispan.</Arg>
   </Call>
 
-  
+
   <!-- Get a reference to the InfinispanSessionIdManager -->
   <Ref id="Server">
     <Call id="idMgr" name="getSessionIdManager"/>
@@ -167,18 +167,18 @@ From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance direc
 The InfinispanSessionManager can be provided by calling setters:
 
 scavengeInterval::
-  Time in seconds between runs of a scavenger task that looks for expired old sessions to delete. 
+  Time in seconds between runs of a scavenger task that looks for expired old sessions to delete.
   The default is 10 minutes.
 staleIntervalSec::
-  The length of time a session can be in memory without being checked against the cluster. 
+  The length of time a session can be in memory without being checked against the cluster.
   A value of 0 indicates that the session is never checked against the cluster - the current node is considered to be the master for the session.
 
 ===== Using HotRod
 
-If you're using the hotrod client - where serialization will be required - you will need to ensure that the hotrod marshalling software works with Jetty classloading. 
+If you're using the hotrod client - where serialization will be required - you will need to ensure that the hotrod marshalling software works with Jetty classloading.
 To do this, firstly ensure that you have included the lines containing the `prependServerClass` to your context xml file as shown above.
 
-Then, create the file `${jetty.base}/resources/hotrod-client.properties`. 
+Then, create the file `${jetty.base}/resources/hotrod-client.properties`.
 Add the following line to this file:
 
 ....

jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-file-system.adoc

@@ -0,0 +1,60 @@
+//  ========================================================================
+//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
+//  ========================================================================
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+
+[[configuring-sessions-file-system]]
+
+=== Configuring Session Management using the File System
+
+When using the Jetty distribution, you will first need to enable the `session-store-file` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
+
+[source, screen, subs="{sub-order}"]
+----
+$ java -jar ../start.jar --add-to-start=session-store-file
+INFO : server          initialised (transitively) in ${jetty.base}/start.d/server.ini
+INFO : sessions        initialised (transitively) in ${jetty.base}/start.d/sessions.ini
+INFO : session-store-file initialised in ${jetty.base}/start.d/session-store-file.ini
+MKDIR: ${jetty.base}/sessions
+INFO : Base directory was modified
+----
+
+//TODO - Callout default Session file location - note it is configurable
+Doing this enables the File System Session module and any dependent modules or files needed for it to run on the server.
+The example above is running an fresh `{$jetty.base}` with nothing enabled.
+When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-file` module as well as the `sessions` and `server` modules, which are required for the File System session management to operate.
+Additionally a `${jetty.base}/sessions` directory was created.
+By default Session files will be saved to this directory.
+
+In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
+
+Opening the `start.d/session-store-file.ini` will show a list of all the configurable options for the JDBC module:
+
+[source, screen, subs="{sub-order}"]
+----
+# ---------------------------------------
+# Module: session-store-file
+# Enables session persistent storage in files.
+# ---------------------------------------
+--module=session-store-file
+
+jetty.session.storeDir=${jetty.base}/sessions
+#jetty.session.deleteUnrestorableFiles=false
+----
+
+jetty.session.storeDir::
+This defines the location for storage of Session files.
+jetty.session.deleteUnrestorableFiles::
+Boolean.
+If set to true, the server will delete files during the scavenging process for Sessions that have expired or otherwise unable to be restored.

jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-gcloud.adoc

@@ -0,0 +1,76 @@
+//  ========================================================================
+//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
+//  ========================================================================
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+
+[[configuring-sessions-gcloud]]
+
+=== Configuring Google Cloud DataStore
+
+When using the Jetty distribution, you will first need to enable the `session-store-gcloud` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
+
+[source, screen, subs="{sub-order}"]
+----
+$ java -jar ../start.jar --add-to-start=session-store-jdbc
+INFO : server          initialised (transitively) in ${jetty.base}/start.d/server.ini
+INFO : sessions        initialised (transitively) in ${jetty.base}/start.d/sessions.ini
+INFO : session-store-jdbc initialised in ${jetty.base}/start.d/session-store-jdbc.ini
+INFO : Base directory was modified
+----
+
+Doing this enables the GCloud Session module and any dependent modules or files needed for it to run on the server.
+The example above is running an fresh `{$jetty.base}` with nothing enabled.
+When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-gcloud` module as well as the `sessions` and `server` modules, which are required for GCloud session management to operate.
+In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
+
+Opening the `start.d/session-store-jdbc.ini` will show a list of all the configurable options for the JDBC module:
+
+[source, screen, subs="{sub-order}"]
+----
+# ---------------------------------------
+# Module: session-store-jdbc
+# Enables JDBC peristent/distributed session storage.
+# ---------------------------------------
+--module=session-store-jdbc
+
+##
+##JDBC Session properties
+##
+
+#jetty.session.gracePeriod.seconds=3600
+
+## Connection type:Datasource
+db-connection-type=datasource
+#jetty.session.datasourceName=/jdbc/sessions
+
+## Connection type:driver
+#db-connection-type=driver
+#jetty.session.driverClass=
+#jetty.session.driverUrl=
+
+## Session table schema
+#jetty.sessionTableSchema.accessTimeColumn=accessTime
+#jetty.sessionTableSchema.contextPathColumn=contextPath
+#jetty.sessionTableSchema.cookieTimeColumn=cookieTime
+#jetty.sessionTableSchema.createTimeColumn=createTime
+#jetty.sessionTableSchema.expiryTimeColumn=expiryTime
+#jetty.sessionTableSchema.lastAccessTimeColumn=lastAccessTime
+#jetty.sessionTableSchema.lastSavedTimeColumn=lastSavedTime
+#jetty.sessionTableSchema.idColumn=sessionId
+#jetty.sessionTableSchema.lastNodeColumn=lastNode
+#jetty.sessionTableSchema.virtualHostColumn=virtualHost
+#jetty.sessionTableSchema.maxIntervalColumn=maxInterval
+#jetty.sessionTableSchema.mapColumn=map
+#jetty.sessionTableSchema.table=JettySessions
+----

jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-infinispan.adoc

@@ -0,0 +1,77 @@
+//  ========================================================================
+//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
+//  ========================================================================
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+
+[[configuring-sessions-infinispan]]
+
+=== Configuring Inifinspan Clustering
+
+When using the Jetty distribution, you will first need to enable the `session-store-infinispan` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
+
+[source, screen, subs="{sub-order}"]
+----
+$ java -jar ../start.jar --add-to-start=session-store-infinispan
+
+ALERT: There are enabled module(s) with licenses.
+The following 1 module(s):
+ + contains software not provided by the Eclipse Foundation!
+ + contains software not covered by the Eclipse Public License!
+ + has not been audited for compliance with its license
+
+ Module: session-store-infinispan
+  + Infinispan is an open source project hosted on Github and released under the Apache 2.0 license.
+  + http://infinispan.org/
+  + http://www.apache.org/licenses/LICENSE-2.0.html
+
+Proceed (y/N)? y
+INFO : server          initialised (transitively) in ${jetty.base}/start.d/server.ini
+INFO : sessions        initialised (transitively) in ${jetty.base}/start.d/sessions.ini
+INFO : session-store-infinispan initialised in ${jetty.base}/start.d/session-store-infinispan.ini
+DOWNLOAD: http://central.maven.org/maven2/org/infinispan/infinispan-core/7.1.1.Final/infinispan-core-7.1.1.Final.jar to ${jetty.base}/lib/infinispan/infinispan-core-7.1.1.Final.jar
+DOWNLOAD: http://central.maven.org/maven2/org/infinispan/infinispan-commons/7.1.1.Final/infinispan-commons-7.1.1.Final.jar to ${jetty.base}/lib/infinispan/infinispan-commons-7.1.1.Final.jar
+DOWNLOAD: http://central.maven.org/maven2/org/jgroups/jgroups/3.6.1.Final/jgroups-3.6.1.Final.jar to ${jetty.base}/lib/infinispan/jgroups-3.6.1.Final.jar
+DOWNLOAD: http://central.maven.org/maven2/org/jboss/marshalling/jboss-marshalling-osgi/1.4.4.Final/jboss-marshalling-osgi-1.4.4.Final.jar to ${jetty.base}/lib/infinispan/jboss-marshalling-osgi-1.4.4.Final.jar
+DOWNLOAD: http://central.maven.org/maven2/org/jboss/logging/jboss-logging/3.1.2.GA/jboss-logging-3.1.2.GA.jar to ${jetty.base}/lib/infinispan/jboss-logging-3.1.2.GA.jar
+INFO : Base directory was modified
+----
+
+Doing this enables the Infinispan Session module and any dependent modules or files needed for it to run on the server.
+The example above is running an fresh `{$jetty.base}` with nothing enabled.
+Because Infinispan is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).
+When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-infinispan` module as well as the `sessions` and `server` modules, which are required for Infinispan session management to operate.
+It also downloaded the needed Infinispan-specific jar files and created a directory named `${jetty.base}/lib/infinispan/` to house it.
+In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
+
+Opening the `start.d/session-store-jdbc.ini` will show a list of all the configurable options for the JDBC module:
+
+[source, screen, subs="{sub-order}"]
+----
+# ---------------------------------------
+# Module: session-store-infinispan
+# Enables session data store in an Infinispan cache
+# ---------------------------------------
+--module=session-store-infinispan
+
+cache-type=default
+
+#cache-type=remote
+#jetty.session.remoteInfinispanCache.name=sessions
+#jetty.session.infinispanIdleTimeout.seconds=0
+#jetty.session.gracePeriod.seconds=3600
+----
+
+jetty.session.remoteInfinispanCache.name::
+jetty.session.infinispanIdleTimeout.seconds::
+jetty.session.gracePeriod.seconds::

jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-jdbc.adoc

@@ -0,0 +1,114 @@
+//  ========================================================================
+//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
+//  ========================================================================
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+
+[[configuring-sessions-jdbc]]
+
+=== Configuring JDBC Clustering
+
+When using the Jetty distribution, you will first need to enable the `session-store-jdbc` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
+
+[source, screen, subs="{sub-order}"]
+----
+$ java -jar ../start.jar --add-to-start=session-store-jdbc
+INFO : server          initialised (transitively) in ${jetty.base}/start.d/server.ini
+INFO : sessions        initialised (transitively) in ${jetty.base}/start.d/sessions.ini
+INFO : session-store-jdbc initialised in ${jetty.base}/start.d/session-store-jdbc.ini
+INFO : Base directory was modified
+----
+
+Doing this enables the JDBC Session module and any dependent modules or files needed for it to run on the server.
+The example above is running an fresh `{$jetty.base}` with nothing enabled.
+When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-jdbc` module as well as the `sessions` and `server` modules, which are required for JDBC session management to operate.
+In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
+
+Opening the `start.d/session-store-jdbc.ini` will show a list of all the configurable options for the JDBC module:
+
+[source, screen, subs="{sub-order}"]
+----
+# ---------------------------------------
+# Module: session-store-jdbc
+# Enables JDBC peristent/distributed session storage.
+# ---------------------------------------
+--module=session-store-jdbc
+
+##
+##JDBC Session properties
+##
+
+#jetty.session.gracePeriod.seconds=3600
+
+## Connection type:Datasource
+db-connection-type=datasource
+#jetty.session.datasourceName=/jdbc/sessions
+
+## Connection type:driver
+#db-connection-type=driver
+#jetty.session.driverClass=
+#jetty.session.driverUrl=
+
+## Session table schema
+#jetty.sessionTableSchema.accessTimeColumn=accessTime
+#jetty.sessionTableSchema.contextPathColumn=contextPath
+#jetty.sessionTableSchema.cookieTimeColumn=cookieTime
+#jetty.sessionTableSchema.createTimeColumn=createTime
+#jetty.sessionTableSchema.expiryTimeColumn=expiryTime
+#jetty.sessionTableSchema.lastAccessTimeColumn=lastAccessTime
+#jetty.sessionTableSchema.lastSavedTimeColumn=lastSavedTime
+#jetty.sessionTableSchema.idColumn=sessionId
+#jetty.sessionTableSchema.lastNodeColumn=lastNode
+#jetty.sessionTableSchema.virtualHostColumn=virtualHost
+#jetty.sessionTableSchema.maxIntervalColumn=maxInterval
+#jetty.sessionTableSchema.mapColumn=map
+#jetty.sessionTableSchema.table=JettySessions
+----
+
+jetty.session.gracePeriod.seconds::
+
+db-connection-type::
+jetty.session.datasourceName::
+
+db-connection-type::
+jetty.session.driverClass::
+jetty.session.driverUrl::
+
+jetty.sessionTableSchema.accessTimeColumn::
+jetty.sessionTableSchema.contextPathColumn::
+jetty.sessionTableSchema.cookieTimeColumn::
+jetty.sessionTableSchema.createTimeColumn::
+jetty.sessionTableSchema.expiryTimeColumn::
+jetty.sessionTableSchema.lastAccessTimeColumn::
+jetty.sessionTableSchema.lastSavedTimeColumn::
+jetty.sessionTableSchema.idColumn::
+jetty.sessionTableSchema.lastNodeColumn::
+jetty.sessionTableSchema.virtualHostColumn::
+jetty.sessionTableSchema.maxIntervalColumn::
+jetty.sessionTableSchema.mapColumn::
+jetty.sessionTableSchema.table::
+
+jetty.jdbcSession.workerName::
+  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 *each* node on which you enable jdbc session clustering.
+jetty.jdbcSession.scavenge::
+  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.
+jetty.jdbcSession.datasource::
+  The name of a `javax.sql.DataSource` that gives access to the database that holds the session information.
+  You should configure *either* this or the jdbc driver information described next.
+jetty.jdbcSession.datasource and jetty.jdbcSession.connectionURL::
+  This is the name of the jdbc driver class, and a jdbc connection url suitable for that driver.
+  You should configure *either* this or the jdbc datasource name described above.

jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-mongodb.adoc

@@ -0,0 +1,70 @@
+//  ========================================================================
+//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
+//  ========================================================================
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+
+[[configuring-sessions-mongo]]
+
+=== Configuring MongoDB Clustering
+
+When using the Jetty distribution, you will first need to enable the `session-store-mongo` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
+
+[source, screen, subs="{sub-order}"]
+----
+$ java -jar ../start.jar --add-to-start=session-store-mongo
+
+ALERT: There are enabled module(s) with licenses.
+The following 1 module(s):
+ + contains software not provided by the Eclipse Foundation!
+ + contains software not covered by the Eclipse Public License!
+ + has not been audited for compliance with its license
+
+ Module: session-store-mongo
+  + The java driver for the MongoDB document-based database system is hosted on GitHub and released under the Apache 2.0 license.
+  + http://www.mongodb.org/
+  + http://www.apache.org/licenses/LICENSE-2.0.html
+
+Proceed (y/N)? y
+INFO : server          initialised (transitively) in ${jetty.base}/start.d/server.ini
+INFO : sessions        initialised (transitively) in ${jetty.base}/start.d/sessions.ini
+INFO : session-store-mongo initialised in ${jetty.base}/start.d/session-store-mongo.ini
+DOWNLOAD: http://central.maven.org/maven2/org/mongodb/mongo-java-driver/2.6.1/mongo-java-driver-2.6.1.jar to ${jetty.base}/lib/nosql/mongo-java-driver-2.6.1.jar
+INFO : Base directory was modified
+----
+
+Doing this enables the MongoDB Session module and any dependent modules or files needed for it to run on the server.
+The example above is running an fresh `{$jetty.base}` with nothing enabled.
+Because MongoDB is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).
+When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-mongo` module as well as the `sessions` and `server` modules, which are required for MongoDB session management to operate..
+It also downloaded the needed Mongo-specific jar file and created a directory named `${jetty.base}/lib/nosql/` to house it.
+In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
+
+Opening the `start.d/session-store-jdbc.ini` will show a list of all the configurable options for the JDBC module:
+
+[source, screen, subs="{sub-order}"]
+----
+# ---------------------------------------
+# Module: session-store-mongo
+# Enables NoSql session management with a MongoDB driver.
+# ---------------------------------------
+--module=session-store-mongo
+
+#jetty.session.dbName=HttpSessions
+#jetty.session.collectionName=jettySessions
+#jetty.session.gracePeriod.seconds=3600
+----
+
+jetty.session.dbName::
+jetty.session.collectionName::
+jetty.session.gracePeriod.seconds::

jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc

@@ -0,0 +1,51 @@
+//  ========================================================================
+//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
+//  ========================================================================
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+
+[[jetty-sessions-architecture]]
+=== Session Architecture
+
+==== Changes in Session Architecture
+The architecture of Session Management Jetty changed significantly in Jetty 9.4.
+These changes have resulted in Sessions not only being easier to configure but making them much more pluggable for various technologies.
+
+In previous versions of Jetty, users were required to have a separate `SessionIdManager` for each kind of session manager implemented (JDBC, MongoDB..etc.); now there is a singular `SessionIdManager` for the entire Jetty instance.
+Likewise, prior to Jetty 9.4 there were several different instances of the `SessionManager` class.
+Instead of a single `SessionManager` though, it has been done away with entirely, with most of it's functionality moved to the `SesssionHandler` class.
+Additionally, Jetty 9.4 introduced the concepts of a `SessionCache` and an associated `SessionDataStore` (both explained below).
+
+Finally, Session scavenging has been re-worked.
+Where previously each `SessionManager` instance would periodically scan the in-memory (or clustered) sessions for expired sessions, there is now a single generic scavenger thread which instructs the `SessionHandler` to clean up expired sessions.
+
+
+==== Session Architecture Hierarchy
+
+Each Jetty instance has a singular `SessionIdManager` to handle all session requests, regardless of clustering technology.
+For each context on the server there is one (1) `SessionCache` which acts as a cache of Session objects for the given context.
+The purpose of the `SessionCache` is to ensure that simultaneous requests always operate on the same Session object.
+By default Session information is kept in-memory, but this can be configured.
+
+Where the `SessionCache` handles Session information, Session data is stored in a `SessionDataStore` that is specific to the clustering technology being implemented.
+There is only one (1) `SessionDataStore` per `SessionCache`.
+
+Visually the Session Hierarchy can be represented like this:
+
+image::images/SessionsHierarchy.png[]
+
+==== Configuring Sessions in the Jetty Distribution
+
+Jetty provides support for several different Session Management/Clustering technologies including JDBC, MongoDB, Inifinispan, Google Cloud Datastore and one for local file storage.
+Setting up these technologies is as easy as enabling it's link:#startup-modules[module] and editing it's associated ini file with any usernames, passwords or changes you need to make for your instance.
+The following sections will cover how exactly to enable the required modules as well as an overview of what options are available for customization.