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