Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update to session documentation. 

Signed-off-by: Jan Bartel <janb@webtide.com>
This commit is contained in:
Jan Bartel 2020-09-11 16:59:19 +02:00
parent d8a7a13140
commit 6db6a65c31
13 changed files with 360 additions and 376 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-base.adoc
View File

@ -17,7 +17,7 @@
//
[[ops-session-base]]
=== The Base Sessions Module
=== The Base Session Module
The `sessions` module is the base module that all other session modules depend upon.
As such it will be _transitively_ enabled if you enable any of the other session modules: you need to _explicitly_ enable it if you wish to _change_ any settings from their defaults.
@ -56,17 +56,17 @@ The `HouseKeeper` is responsible for the periodic initiation of session scavenge
The `jetty.sessionScavengeInterval.seconds` property in `start.d/sessions.ini` controls the periodicity of the cycle.
A session whose expiry time has been exceeded is considered eligible for scavenging.
The session can either exist in a `SessionCache` or be passivated out into the session persistence/clustering mechanism.
The session might be present in a `SessionCache` and/or present in the session persistence/clustering mechanism.
Scavenging occurs for all contexts on a server at every cycle.
The `HouseKeeper` sequentially asks the `SessionHandler` in each context to find and remove expired sessions.
The `SessionHandler` works with the `SessionDataStore` to evaluate candidates for expiry held in the `SessionCache`, and also to sweep the persistence mechanism to find expired sessions.
The sweep takes two forms: once per cycle the `SessionDataStore` searches for sessions for it's own context that have expired; infrequently, the `SessionDataStore` will widen the search to expired sessions in any context.
The former finds sessions that are no longer in this node's `SessionCache`, and using some heuristics, are unlikely to be in the `SessionCache` of another node either.
The sweep takes two forms: once per cycle the `SessionDataStore` searches for sessions for it's own context that have expired; infrequently, the `SessionDataStore` will widen the search to expired sessions in all contexts.
The former finds sessions that are no longer in this context's `SessionCache`, and using some heuristics, are unlikely to be in the `SessionCache` of the same context on another node either.
These sessions will be loaded and fully expired, meaning that `HttpSessionListener.destroy()` will be called for them.
The latter finds sessions that have not been disposed of by scavenge cycles on any other context/node.
As these will be sessions that expired a long time ago, and may not be appropriate to load by the context of the `SessionDataStore`, these are summarily deleted without `HttpSessionListener.destroy()` being called.
As these will be sessions that expired a long time ago, and may not be appropriate to load by the context doing the scavenging, these are summarily deleted without `HttpSessionListener.destroy()` being called.
A combination of these sweeps should ensure that the persistence mechanism does not fill over time with expired sessions.

67
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-filesystem.adoc
View File

@ -18,53 +18,32 @@
[[ops-session-filesystem]]
=== Persistent Sessions: File System
=== Modules for Persistent Sessions: File System
The `session-store-file` module supports persistent storage of session data in a filesystem.
IMPORTANT: Persisting sessions to the local file system should *never* be used in a clustered environment.
==== Enabling File System Session Storage
When using the Jetty distribution, you will first need to enable the `session-store-file` xref: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 --create-startd
INFO : Base directory was modified
$ java -jar ../start.jar --add-to-start=session-store-file
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : session-store-file initialized in ${jetty.base}/start.d/session-store-file.ini
MKDIR : ${jetty.base}/sessions
INFO : Base directory was modified
----
Doing this enables this and any dependent modules or files needed for it to run on the server.
The example above is using a fresh `${jetty.base}` with nothing else enabled.
Enabling this module also creates the `${jetty.base}/sessions` directory.
Enabling this module creates the `${jetty.base}/sessions` directory.
By default session data will be saved to this directory, one file representing each session.
File names follow this pattern:
+[expiry]_[context]_[id]+
+[expiry]_[contextpath]_[virtualhost]_[id]+
expiry::
This is the expiry time in milliseconds since the epoch.
context::
This is a string representation of the context to which the session is scoped.
It is comprised of the (sanitised) context path and the virtual host:
+[contextpath]_[virtualhost]+
contextpath:::
This is the context path with any special characters, including `/`, replaced by the `_` underscore character.
For example, a context path of `/catalog` would become `_catalog`.
A context path of simply `/` becomes just `__`.
virtualhost:::
This is the first virtual host associated with the context and has the form of 4 digits separated by `.` characters.
If there are no virtual hosts associated with a context, then `0.0.0.0` is used:
contextpath::
This is the context path with any special characters, including `/`, replaced by the `_` underscore character.
For example, a context path of `/catalog` would become `_catalog`.
A context path of simply `/` becomes just `__`.
virtualhost::
This is the first virtual host associated with the context and has the form of 4 digits separated by `.` characters.
If there are no virtual hosts associated with a context, then `0.0.0.0` is used:
[digit].[digit].[digit].[digit]
id::
This is the unique id of the session.
@ -73,7 +52,7 @@ Putting all of the above together as an example, a session with an id of `node0e
`1599558193150__test_0.0.0.0_node0ek3vx7x2y1e7pmi3z00uqj1k0`
==== Configuring
==== Configuration
The `$jetty.base/start.d/sessions.ini` file contains the following properties which may be modified to customise filesystem session storage:
@ -86,9 +65,17 @@ If set to `true`, unreadable files will be deleted.
This is useful to prevent repeated logging of the same error when the scavenger periodically (re-)attempts to load the corrupted information for a session in order to expire it.
jetty.session.gracePeriod.seconds::
Integer, default 3600.
Used during session scavenging.
Multiples of this period are used to define how long ago a stored session must have expired before it should be scavenged.
Used during session xref:ops-session-base-scavenge[scavenging].
Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:ops-session-base-scavenge[scavenged].
jetty.session.savePeriod.seconds::
Integer, default is `0`.
By default whenever the last concurrent request leaves a session, that session is always persisted, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that jetty will skip persisting the session if only the access time changed, unless the time since the last save exceeds the value of this property.
Integer, in seconds, default is `0`.
Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
Even if your sessions are read-mostly, the `lastAccessTime` and `expiry` will always change.
For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed).
The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property.
[WARNING]
====
You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its `expiry` time thus making it appear to other nodes that it has expired.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
====

23
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-gcloud.adoc
View File

@ -18,7 +18,7 @@
[[ops-session-gcloud]]
=== Persistent Sessions: Google Cloud DataStore
=== Modules for Persistent Sessions: Google Cloud DataStore
Jetty can store http session information into GCloud by enabling the `session-store-gcloud` module.
@ -76,7 +76,7 @@ You can then choose one and enable it.
IMPORTANT: If you want to use updated versions of the jar files automatically downloaded during the module enablement, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
==== Configuring GCloud Session Properties
==== Configuration
The `start.d/session-store-gcloud.ini` file contains all of the configurable properties for the `session-store-gcloud` module:
@ -91,18 +91,19 @@ Number of milliseconds between successive attempts to connect to the GCloud Data
jetty.session.gracePeriod.seconds::
Integer, in seconds.
Default 3600.
Used during session scavenging.
Multiples of this period are used to define how long ago a stored session must have expired before it should be scavenged.
Used during session xref:session-base-scavenge[scavenging].
Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:session-base-scavenge[scavenged].
jetty.session.savePeriod.seconds::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
Integer, in seconds, default is `0`.
Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
Even if your sessions are read-mostly, the `lastAccessTime` and `expiry` will always change.
For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed).
The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property.
[NOTE]
[WARNING]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its `expiry` time thus making it appear to other nodes that it has expired.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
====
jetty.session.gcloud.namespace::

81
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-hazelcast.adoc
View File

@ -18,29 +18,24 @@
[[ops-session-hazelcast]]
=== Persistent Sessions: Hazelcast
=== Modules for Persistent Sessions: Hazelcast
Hazelcast can be used to cluster session information in one of two modes: either remote or embedded.
Remote mode means that Hazelcast will create a client to talk to other instances, possibly on other nodes.
Embedded mode means that Hazelcast will start a local instance and communicate with that.
[[ops-session-hazelcast-remote]]
==== Enabling Remote Hazelcast Clustering
==== Remote Hazelcast Clustering
Enable the `session-store-hazelcast-remote` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
Enabling the `session-store-hazelcast-remote` module allows jetty to communicate with a remote Hazelcast instance to cluster session data.
Doing this enables the Hazelcast Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh `${jetty.base}` with nothing else enabled.
Because Hazelcast 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).
Because Hazelcast is not a technology provided by the Eclipse Foundation, you will be 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-hazelcast-remote` module as well as the `sessions` and `server` modules, which are required for Hazelcast session management to operate.
It also downloaded the needed Hazelcast-specific jar files and created a directory named `${jetty.base}/lib/hazelcast/` to house them.
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `${jetty.base}/start.d` directory.
Hazelcast-specific jar files will be downloaded and saved to a directory named `${jetty.base}/lib/hazelcast/`.
NOTE: If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
===== Configuring
===== Configuration
The `start.d/session-store-hazelcast-remote.ini` contains a list of all the configurable options for the Hazelcast module:
@ -55,46 +50,43 @@ Optional.
This is the path to an external Hazelcast xml configuration file.
jetty.session.hazelcast.useQueries::
Boolean, default `false`.
If `true`, Jetty will use Hazelcast queries to find sessions to scavenge.
If `false` sessions that are not currently in a xref:op-session-sessioncache[session cache] cannot be scavenged, and will need to be removed by some external process.
If `true`, Jetty will use Hazelcast queries to find sessions to xref:session-base-scavenge[scavenge].
If `false` sessions that are not currently in a xref:op-session-sessioncache[session cache] cannot be xref:session-base-scavenge[scavenged], and will need to be removed by some external process.
jetty.session.hazelcast.addresses::
Optional.
These are the addresses of remote Hazelcast instances with which to communicate.
jetty.session.gracePeriod.seconds::
Integer, in seconds.
Default 3600.
Used during session scavenging.
Multiples of this period are used to define how long ago a stored session must have expired before it should be scavenged.
Used during session xref:session-base-scavenge[scavenging].
Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:session-base-scavenge[scavenged].
jetty.session.savePeriod.seconds::
Integer, default `0`.
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
Integer, in seconds, default is `0`.
Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
Even if your sessions are read-mostly, the `lastAccessTime` and `expiry` will always change.
For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed).
The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property.
[NOTE]
[WARNING]
====
Configuring `savePeriod` is useful if writes are slow/costly.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its `expiry` time thus making it appear to other nodes that it has expired.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
====
IMPORTANT: Be aware that if your session attributes contain classes from inside your webapp (or Jetty classes) then you will need to put these classes onto the classpath of all of your Hazelcast instances.
[[ops-session-hazelcast-embedded]]
==== Enabling Embedded Hazelcast Clustering
==== Embedded Hazelcast Clustering
This will run an in-process instance of Hazelcast.
This can be useful for example during testing.
To enable this you enable the `session-store-hazelcast-embedded` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
To enable this you enable the `session-store-hazelcast-embedded` module.
Because Hazelcast is not a technology provided by the Eclipse Foundation, you will be 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-hazelcast-embedded` module as well as the `sessions` and `server` modules, which are required for Hazelcast session management to operate.
It also downloaded the needed Hazelcast-specific jar files and created a directory named `${jetty.base}/lib/hazelcast/` to house them.
Hazelcast-specific jar files will be downloaded to a directory named `${jetty.base}/lib/hazelcast/`.
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `${jetty.base}/start.d` directory.
===== Configuring
===== Configuration
The `start.d/start.d/session-store-hazelcast-embedded.ini` contains a list of all the configurable options for the Hazelcast module:
@ -109,24 +101,25 @@ Optional.
This is the path to an external Hazelcast xml configuration file.
jetty.session.hazelcast.useQueries::
Boolean, default `false'.
If `true`, Jetty will use Hazelcast queries to find expired sessions to scavenge.
If `false` sessions that are not currently in a xref:op-session-sessioncache[session cache] cannot be scavenged, and will need to be removed by some external process.
If `true`, Jetty will use Hazelcast queries to find expired sessions to xref:session-base-scavenge[scavenge].
If `false` sessions that are not currently in a xref:op-session-sessioncache[session cache] cannot be xref:session-base-scavenge[scavenged], and will need to be removed by some external process.
jetty.session.gracePeriod.seconds::
Integer, in seconds.
Default 3600.
Used during session scavenging.
Multiples of this period are used to define how long ago a stored session must have expired before it should be scavenged.
Used during session xref:session-base-scavenge[scavenging].
Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:session-base-scavenge[scavenged].
jetty.session.savePeriod.seconds::
Integer, default `0`.
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
Integer, in seconds, default is `0`.
Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
Even if your sessions are read-mostly, the `lastAccessTime` and `expiry` will always change.
For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed).
The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property.
[NOTE]
[WARNING]
====
You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its `expiry` time thus making it appear to other nodes that it has expired.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
If your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances. In the case of embedded hazelcast, as it is started before your webapp, it will NOT have access to your webapp's classes - you will need to extract these classes and put them onto the jetty server's classpath.
====
IMPORTANT: If your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances. In the case of embedded hazelcast, as it is started before your webapp, it will NOT have access to your webapp's classes - you will need to extract these classes and put them onto the jetty server's classpath.

210
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-infinispan.adoc
View File

@ -18,184 +18,114 @@
[[ops-sessions-infinispan]]
=== Persistent Sessions: Inifinspan
=== Modules for Persistent Sessions: Infinispan
In order to persist/cluster sessions using Infinispan, Jetty needs to know how to contact Infinispan.
There are two options: a remote Infinispan instance, or an in-process Infinispan instance.
The former is referred to as "remote" Infinispan and the latter as "embedded" Infinispan.
If you wish Jetty to be able to xref:ops-session-base-scavenge[scavenge] expired sessions, you will also need to enable the appropriate `infinispan-[remote|embedded]-query` module.
[[ops-session-infinispan-remote]]
==== Enabling Infinispan Sessions
==== Remote Infinispan Session Module
When using the Jetty distribution, you will first need to enable the `session-store-infinispan-remote` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
The `session-store-infinispan-remote` module configures Jetty to talk to an external Infinispan instance to store session data.
Because Infinispan is not a technology provided by the Eclipse Foundation, you will be prompted to assent to the licenses of the external vendor (Apache in this case).
[source,screen,subs="{sub-order}"]
----
[my-base]$ java -jar /path/to/jetty-home/start.jar --create-startd
INFO : Base directory was modified
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=session-store-infinispan-remote
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-remote
+ 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 transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : session-store-infinispan-remote initialized in ${jetty.base}/start.d/session-store-infinispan-remote.ini
MKDIR : ${jetty.base}/lib/infinispan
DOWNLD: https://repo1.maven.org/maven2/org/infinispan/infinispan-remote-it/9.4.8.Final/infinispan-remote-it-9.4.8.Final.jar to ${jetty.base}/lib/infinispan/infinispan-remote-it-9.4.8.Final.jar
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/session-store-infinispan-remote/resources/hotrod-client.properties to ${jetty.base}/resources/hotrod-client.properties
INFO : Base directory was modified
----
Doing this enables the remote Infinispan Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh `${jetty.base}` with nothing else 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-remote` 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 them.
Infinispan-specific jar files are download to the directory named `${jetty.base}/lib/infinispan/`.
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `${jetty.base}/start.d` directory.
NOTE: If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
==== Configuring Inifinspan Remote Properties
==== Configuration
Opening the `start.d/session-store-infinispan-remote.ini` will show a list of all the configurable options for the JDBC module:
[source, screen, subs="{sub-order}"]
----
# ---------------------------------------
# Module: session-store-infinispan-remote
# Enables session data store in a remote Infinispan cache
# ---------------------------------------
--module=session-store-infinispan-remote
#jetty.session.infinispan.remoteCacheName=sessions
#jetty.session.infinispan.idleTimeout.seconds=0
#jetty.session.gracePeriod.seconds=3600
#jetty.session.savePeriod.seconds=0
----
The `start.d/session-store-infinispan-remote.ini` contains the following configurable properties:
jetty.session.infinispan.remoteCacheName::
Name of the cache in Infinispan where sessions will be stored.
Default `"sessions"`.
This is the name of the cache in Infinispan where sessions will be stored.
jetty.session.infinispan.idleTimeout.seconds::
Amount of time, in seconds, that a session entry in infinispan can be idle (ie not read or written) before infinispan will delete its entry.
Usually, you do *not* want to set a value for this, as you want jetty to handle all session expiration (and call any SessionListeners).
However, if there is the possibility that sessions can be left in infinispan but no longer referenced by any jetty node (so called "zombie" or "orphan" sessions), then you might want to use this feature.
You should make sure that the number of seconds you specify is sufficiently large to avoid the situation where a session is still being referenced by jetty, but is rarely accessed and thus deleted by infinispan.
Alternatively, you can enable the `infinispan-remote-query` module, which will allow jetty to search the infinispan session cache to proactively find and properly (ie calling any SessionListeners) scavenge defunct sessions.
Integer, in seconds, default `0`.
This is the amount of time, in seconds, that a session entry in Infinispan can be idle (ie neither read nor written) before Infinispan will delete its entry.
Usually, you do *not* want to set a value for this, as you want Jetty to manage all session expiration (and call any HttpSessionListeners).
You *should* enable the xref:ops-session-infinispan-remote-query[infinispan-remote-query] to allow jetty to xref:ops-session-base-scavenge[scavenge] for expired sessions.
If you do not, then there is the possibility that sessions can be left in Infinispan but no longer referenced by any Jetty node (so called "zombie" or "orphan" sessions), in which case you can use this feature to ensure their removal.
IMPORTANT: You should make sure that the number of seconds you specify is larger than the configured `maxIdleTime` for sessions.
jetty.session.gracePeriod.seconds::
Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.
jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
Integer, default 3600.
Used during session xref:ops-session-base-scavenge[scavenging].
Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:ops-session-base-scavenge[scavenged].
[NOTE]
jetty.session.savePeriod.seconds::
Integer, in seconds, default is `0`.
Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
Even if your sessions are read-mostly, the `lastAccessTime` and `expiry` will always change.
For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed).
The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property.
[WARNING]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its `expiry` time thus making it appear to other nodes that it has expired.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
====
==== Configuring the Remote Infinispan Query Module
[[ops-session-infinispan-remote-query]]
==== Remote Infinispan Query Module
Enabling this module allows jetty to search infinispan for expired sessions that are no longer being referenced by any jetty node.
Note that this is an *additional* module, to be used in conjuction with the `session-store-infinispan-remote` module.
[source, screen, subs="{sub-order}"]
----
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=infinispan-remote-query
----
The `infinispan-remote-query` module allows Jetty to xref:ops-session-base-scavenge[scavenge] expired sessions.
Note that this is an *additional* module, to be used in conjunction with the `session-store-infinispan-remote` module.
There are no configuration properties associated with this module.
[[ops-session-infinispan-embedded]]
==== Configuring Embedded Infinispan Clustering
==== Embedded Infinispan Session Module
During testing, it can be helpful to run an in-process instance of Infinispan.
To enable this you will first need to enable the `session-store-infinispan-embedded` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
Enabling the `session-store-infinispan-embedded` module runs an in-process instance of Infinispan.
IMPORTANT: If you are running Jetty with JDK 9 or greater, enable `session-store-infinispan-embedded-910.mod` instead.
Because Infinispan is not a technology provided by the Eclipse Foundation, you will be prompted to assent to the licenses of the external vendor (Apache in this case).
Infinispan-specific jar files will be downloaded and saved to a directory named `${jetty.base}/lib/infinispan/`.
[source,screen,subs="{sub-order}"]
----
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=session-store-infinispan-embedded
NOTE: If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
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
==== Configuration
Module: session-store-infinispan-embedded
+ 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
The `start.d/session-store-infinispan-embedded.ini` contains the following configurable properties:
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-embedded initialised in ${jetty.base}/start.d/session-store-infinispan-embedded.ini
DOWNLOAD: https://repo1.maven.org/maven2/org/infinispan/infinispan-embedded-it/9.4.8.Final/infinispan-embedded-it-9.4.8.Final.jar to ${jetty.base}/lib/infinispan/infinispan-embedded-it-9.4.8.Final.jar
INFO : Base directory was modified
----
jetty.session.infinispan.idleTimeout.seconds::
Integer, in seconds, default `0`.
This is the amount of time, in seconds, that a session entry in Infinispan can be idle (ie neither read nor written) before Infinispan will delete its entry.
Usually, you do *not* want to set a value for this, as you want Jetty to manage all session expiration (and call any HttpSessionListeners).
You *should* enable the xref:ops-session-infinispan-embedded-query[infinispan-embedded-query] to allow Jetty to xref:session-base-scavenge[scavenge] for expired sessions.
If you do not, then there is the possibility that expired sessions can be left in Infinispan.
Doing this enables the embedded Infinispan Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh `${jetty.base}` with nothing else 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-embedded` 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 them.
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `${jetty.base}/start.d` directory.
==== Configuring Infinispan Embedded Properties
Opening the `start.d/session-store-infinispan-remote.ini` will show a list of all the configurable options for the JDBC module:
[source, screen, subs="{sub-order}"]
----
# ---------------------------------------
# Module: session-store-infinispan-embedded
# Enables session data store in a local Infinispan cache
# ---------------------------------------
--module=session-store-infinispan-embedded
#jetty.session.gracePeriod.seconds=3600
#jetty.session.savePeriod.seconds=0
----
IMPORTANT: You should make sure that the number of seconds you specify is larger than the configured `maxIdleTime` for sessions.
jetty.session.gracePeriod.seconds::
Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.
jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
Integer, default 3600.
Used during session xref:ops-session-base-scavenge[scavenging].
Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:ops-session-base-scavenge[scavenged].
[NOTE]
jetty.session.savePeriod.seconds::
Integer, in seconds, default is `0`.
Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
Even if your sessions are read-mostly, the `lastAccessTime` and `expiry` will always change.
For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed).
The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property.
[WARNING]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
====
==== Configuring Inifinspan Embedded Query
Similarly to the `session-store-infinispan-remote` module, the `session-store-infinispan-embedded` module has an adjunct module `infinispan-embedded-query`, which when enabled, will allow jetty to detect and properly scavenge defunct sessions stranded in infinispan.
==== Embedded Infinispan Query Module
The `infinispan-embedded-query` module allows Jetty to xref:ops-session-base-scavenge[scavenge] expired sessions.
[source, screen, subs="{sub-order}"]
----
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=infinispan-embedded-query
----
There are no configuration properties associated with this module.
@ -203,7 +133,7 @@ There are no configuration properties associated with this module.
==== Converting Session Format for Jetty-9.4.13
From Jetty-9.4.13 onwards, we have changed the format of the serialized session when using a remote cache (ie using hotrod).
Prior to release 9.4.13 we used the default Infinispan serialization, however this was not able to store sufficient information to allow jetty to properly deserialize session attributes in all circumstances.
Prior to release 9.4.13 we used the default Infinispan serialization, however this was not able to store sufficient information to allow Jetty to properly deserialize session attributes in all circumstances.
See issue https://github.com/eclipse/jetty.project/issues/2919 for more background.
We have provided a conversion program which will convert any sessions stored in Infinispan to the new format.

144
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-jdbc.adoc
View File

@ -18,67 +18,123 @@
[[ops-sessions-jdbc]]
=== Persistent Sessions: JDBC
=== Modules for Persistent Sessions: JDBC
==== Enabling JDBC Sessions
Enabling the `session-store-jdbc` module configures Jetty to persist session data in a relational database.
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}"]
----
[my-base]$ java -jar /path/to/jetty-home/start.jar --create-startd
INFO : Base directory was modified
==== Configuration
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=session-store-jdbc
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : sessions/jdbc/datasource dynamic dependency of session-store-jdbc
INFO : session-store-jdbc initialized 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 using a fresh `${jetty.base}` with nothing else enabled.
==== Configuring
The persistence of sessions via jdbc can be customized by editing the `${jetty.base}/start.d/session-store-jdbc.ini` file.
The following properties are available:
After enabling the module, the `${jetty.base}/start.d/session-store-jdbc.ini` file contains the following customizable properties:
jetty.session.gracePeriod.seconds::
Integer.
Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.
Integer, default 3600.
Used during session xref:ops-session-base-scavenge[scavenging].
Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:ops-session-base-scavenge[scavenged].
jetty.session.savePeriod.seconds::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
Integer, in seconds, default is `0`.
Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
Even if your sessions are read-mostly, the `lastAccessTime` and `expiry` will always change.
For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed).
The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property.
[NOTE]
[WARNING]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its `expiry` time thus making it appear to other nodes that it has expired.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
====
db-connection-type::
Default `datasource`.
Set to either `datasource` or `driver` depending on the type of connection being used.
jetty.session.jdbc.datasourceName::
Name of the remote datasource.
jetty.session.jdbc.driverClass::
Name of the JDBC driver that controls access to the remote database, such as `com.mysql.jdbc.Driver`
jetty.session.jdbc.driverUrl::
Url of the database which includes the driver type, host name and port, service name and any specific attributes unique to the database, such as a username.
As an example, here is a mysql connection with the username appended: `jdbc:mysql://127.0.0.1:3306/sessions?user=sessionsadmin`.
Depending which you select, there are additional properties available:
The `jetty.session.jdbc.schema.*` values represent the names of the table and columns in the JDBC database used to store sessions and can be changed to suit your environment.
`datasource`:::
jetty.session.jdbc.datasourceName::::
Name of the remote datasource.
`driver`:::
jetty.session.jdbc.driverClass::::
Name of the JDBC driver that controls access to the remote database, such as `com.mysql.jdbc.Driver`
jetty.session.jdbc.driverUrl::::
URL of the database which includes the driver type, host name and port, service name and any specific attributes unique to the database, such as a username.
As an example, here is a mysql connection with the username appended: `jdbc:mysql://127.0.0.1:3306/sessions?user=sessionsadmin`.
There are also two special, optional properties: `jetty.session.jdbc.schema.schemaName` and `jetty.session.jdbc.schema.catalogName`.
jetty.session.jdbc.blobType::
Optional.
Default `blob` or `bytea` for Postgres.
This is the keyword used by the particular database to identify the blob data type.
If netiher default is suitable you can set this value explicitly.
jetty.session.jdbc.longType::
Optional.
Default `bigint` or `number(20)` for Oracle.
This is the keyword used by the particular database to identify the long integer data type.
Set this explicitly if neither of the default values is appropriate.
jetty.session.jdbc.stringType::
Optional.
Default `varchar`.
This is the keyword used by the particular database to identify character type.
If the default is not suitable, you can set this value explicitly.
jetty.session.jdbc.schema.schemaName::
jetty.session.jdbc.schema.catalogName::
Optional.
The exact meaning of these two properties is dependent on your database vendor, but can broadly be described as further scoping for the session table name.
See https://en.wikipedia.org/wiki/Database_schema and https://en.wikipedia.org/wiki/Database_catalog.
These extra scoping names can come into play at startup time when jetty determines if the session table already exists, or otherwise creates it on-the-fly.
If you have employed either of these concepts when you pre-created the session table, or you want to ensure that jetty uses them when it auto-creates the session table, then you have two options: either set them explicitly, or let jetty infer them from a database connection (obtained using either a Datasource or Driver according to the `db-connection-type` you have configured).
These extra scoping names can come into play at startup time when Jetty determines if the session table already exists, or otherwise creates it on-the-fly.
If you have employed either of these concepts when you pre-created the session table, or you want to ensure that Jetty uses them when it auto-creates the session table, then you have two options: either set them explicitly, or let Jetty infer them from a database connection (obtained using either a Datasource or Driver according to the `db-connection-type` you have configured).
To set them explicitly, uncomment and supply appropriate values for the `jetty.session.jdbc.schema.schemaName` and/or `jetty.session.jdbc.schema.catalogName` properties.
To allow jetty to infer them from a database connection, use the special string `INFERRED` instead.
Alternatively, to allow Jetty to infer them from a database connection, use the special string `INFERRED` instead.
If you leave them blank or commented out, then the sessions table will not be scoped by schema or catalog name.
jetty.session.jdbc.schema.table::
Default `JettySessions`.
This is the name of the table in which session data is stored.
jetty.session.jdbc.schema.accessTimeColumn::
Default `accessTime`.
This is the name of the column that stores the time - in ms since the epoch - at which a session was last accessed
jetty.session.jdbc.schema.contextPathColumn::
Default `contextPath`.
This is the name of the column that stores the `contextPath` of a session.
jetty.session.jdbc.schema.cookieTimeColumn::
Default `cookieTime`.
This is the name of the column that stores the time - in ms since the epoch - that the cookie was last set for a session.
jetty.session.jdbc.schema.createTimeColumn::
Default `createTime`.
This is the name of the column that stores the time - in ms since the epoch - at which a session was created.
jetty.session.jdbc.schema.expiryTimeColumn::
Default `expiryTime`.
This is name of the column that stores - in ms since the epoch - the time at which a session will expire.
jetty.session.jdbc.schema.lastAccessTimeColumn::
Default `lastAccessTime`.
This is the name of the column that stores the time - in ms since the epoch - that a session was previously accessed.
jetty.session.jdbc.schema.lastSavedTimeColumn::
Default `lastSavedTime`.
This is the name of the column that stores the time - in ms since the epoch - at which a session was last written.
jetty.session.jdbc.schema.idColumn::
Default `sessionId`.
This is the name of the column that stores the id of a session.
jetty.session.jdbc.schema.lastNodeColumn::
Default `lastNode`.
This is the name of the column that stores the `workerName` of the last node to write a session.
jetty.session.jdbc.schema.virtualHostColumn::
Default `virtualHost`.
This is the name of the column that stores the first virtual host of the context of a session.
jetty.session.jdbc.schema.maxIntervalColumn::
Default `maxInterval`.
This is the name of the column that stores the interval - in ms - during which a session can be idle before being considered expired.
jetty.session.jdbc.schema.mapColumn::
Default `map`.
This is the name of the column that stores the serialized attributes of a session.

2
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-memcachedsessiondatastore.adoc
View File

@ -18,7 +18,7 @@
[[ops-session-memcachedsessiondatastore]]
=== Persistent Sessions: The L2 Session Data Cache
=== Modules for Persistent Sessions: The L2 Session Data Cache
If your chosen persistence technology is slow, it can be helpful to locally cache the session data.
The `CachingSessionDataStore` is a special type of `SessionDataStore` that locally caches session data, which makes reads faster. It writes-through to your chosen type of `SessionDataStore` when session data changes.

36
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-mongodb.adoc
View File

@ -18,28 +18,24 @@
[[ops-session-mongo]]
=== Persistent Sessions: MongoDB
=== Modules for Persistent Sessions: MongoDB
==== Enabling MongoDB Sessions
Enable the `session-store-mongo` xref:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
Doing this enables the MongoDB Session module and any dependent modules or files needed for it to run on the server.
Enabling the `session-store-mongo` module configures Jetty to store session data in MongoDB.
Because MongoDB is not a technology provided by the Eclipse Foundation, you will be prompted to assent to the licenses of the external vendor (Apache in this case) during the install.
Jars needed by MongoDB are downloaded and stored into a directory named `${jetty.base}/lib/nosql/`.
IMPORTANT: If you want to use updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
==== Configuring MongoDB Session Properties
==== Configuration
The `start.d/session-store-mongo.ini` file contains all the configurable options for the MongoDB module:
The `start.d/session-store-mongo.ini` file contains these configurable properties:
jetty.session.mongo.dbName::
The default is "HttpSessions".
Default is "HttpSessions".
This is the name of the database in MongoDB used to store the session collection.
jetty.session.mongo.collectionName::
The default is "jettySessions".
Default is "jettySessions".
This is the name of the collection in MongoDB used to store all of the sessions.
The connection type-::
You can connect to MongoDB either using a host/port combination, or a URI.
@ -63,16 +59,18 @@ If both are utilized in your `session-store-mongo.ini`, only the _last_ `connect
jetty.session.gracePeriod.seconds::
Integer, in seconds.
Default 3600.
Used during session scavenging.
Multiples of this period are used to define how long ago a stored session must have expired before it should be scavenged.
Used during session xref:ops-session-base-scavenge[scavenging].
Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:ops-session-base-scavenge[scavenged].
jetty.session.savePeriod.seconds::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
Integer, in seconds, default is `0`.
Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
Even if your sessions are read-mostly, the `lastAccessTime` and `expiry` will always change.
For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed).
The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property.
[NOTE]
[WARNING]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its `expiry` time thus making it appear to other nodes that it has expired.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
====

6
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-overview.adoc
View File

@ -27,8 +27,8 @@ Before diving into the specifics of how to plug-in and configure various alterna
Session::
is a means of retaining information across requests for a particular user.
The Servlet Specification defines the semantics of sessions.
Some of the most important characteristics of sessions is that they have a unique id, and that their contents cannot be shared between different contexts (although the id can be).
If a session is invalidated in a context, then all other sessions that share the same id in other contexts will also be invalidated.
Some of the most important characteristics of sessions is that they have a unique id and that their contents cannot be shared between different contexts (although the id can be): if a session is invalidated in one context, then all other sessions that share the same id in other contexts will also be invalidated.
Sessions can expire or they can be explicitly invalidated.
SessionIdManager::
is responsible for allocating session ids.
Any Jetty server can have at most 1 SessionIdManager.
@ -77,4 +77,4 @@ There are at least 6 alternative implementations of the `SessionDataStore` that
* Hazelcast: xref:ops-session-hazelcast-remote[`session-store-hazelcast-remote`] or xref:ops-session-hazelcast-embedded[`session-store-hazelcast-embedded`]
* Infinispan: xref:ops-session-infinispan[`session-store-infinispan-remote`] or xref:ops-session-infinispan-embedded[`session-store-infinispan-embedded`]
TIP: It is worth noting that if you do not configure _any_ session modules, jetty will still provide http sessions that are cached in memory but are never persisted.
TIP: It is worth noting that if you do not configure _any_ session modules, Jetty will still provide http sessions that are cached in memory but are never persisted.

22
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-sessioncache.adoc
View File

@ -17,19 +17,19 @@
//
[[ops-session-sessioncache]]
=== SessionCache Alternatives
=== Modules for Session Caching
In this section we will look at the alternatives for the `SessionCache`, ie the L1 cache of in-use session objects.
Jetty ships with 2 alternatives: an in-memory cache, and a null cache.
The latter does not actually do any caching of sessions, and can be useful if you either want to minimize your support for sessions, or you are in a clustered deployment without a sticky loadbalancer.
The xref:ops-session-usecases[use-cases] go into more detail on these scenarios.
The xref:ops-session-usecases[scenarios] go into more detail on this.
[[ops-session-hash]]
==== Sessions Cached in Memory
==== Caching in Memory
If you wish to change any of the default configuration values you should enable the `session-cache-hash` xref:startup-modules[module].
The name `hash` harks back to historical Jetty session implementations, whereby sessions were kept in memory using a HashMap.
The name `"hash"` harks back to historical Jetty session implementations, whereby sessions were kept in memory using a HashMap.
===== Configuration
@ -39,10 +39,9 @@ jetty.session.evictionPolicy::
Integer, default -1.
This controls whether session objects that are held in memory are subject to eviction from the cache.
Eviction means that the session is removed from the cache.
This can reduce the memory footprint of the cache.
This can be useful if you have a lot of sessions.
This can reduce the memory footprint of the cache and can be useful if you have a lot of sessions.
Eviction is usually used in conjunction with a `SessionDataStore` that persists sessions.
The set of eviction strategies and their values are:
The eviction strategies and their corresponding values are:
-1 (NO EVICTION):::
sessions are never evicted from the cache.
The only way they leave are via expiration or invalidation.
@ -58,14 +57,15 @@ NOTE: If you are not using one of the session store modules, ie one of the ``ses
jetty.session.saveOnInactiveEvict::
Boolean, default `false`.
This controls whether a session will be persisted to the `SessionDataStore` if it is being evicted due to the EVICT ON INACTIVITY policy.
Usually sessions will be written to the 'SessionDataStore` whenever the last simultaneous request exits the session.
Usually sessions will be written to the `SessionDataStore` whenever the last simultaneous request exits the session.
However, as `SessionDataStores` can be configured to skip some writes (see the documentation for the `session-store-xxx` module that you are using), this option is provided to ensure that the session will be written out.
NOTE: Be careful with this option, as in clustered scenarios it would be possible to "re-animate" a session that has actually been deleted by another node.
jetty.session.saveOnCreate::
Boolean, default `false`.
Controls whether a session that is newly created will be immediately saved to the `SessionDataStore` or lazily saved as the last request for the session exits.
This can be useful if the request dispatches to another context.
This can be useful if the request dispatches to another context and needs to re-use the same session id.
jetty.session.removeUnloadableSessions::
Boolean, default `false`.
@ -83,7 +83,7 @@ If true, when a context is shutdown, all sessions in the cache are invalidated a
[[ops-session-null]]
==== Sessions Not Cached
==== No Caching
You may need to use the `session-cache-null` module if your clustering setup does not have a sticky load balancer, or if you want absolutely minimal support for sessions.
If you enable this module, but you don't enable a module that provides session persistence (ie one of the `session-store-xxx` modules), then sessions will _neither_ be retained in memory _nor_ persisted.
@ -93,7 +93,7 @@ If you enable this module, but you don't enable a module that provides session p
jetty.session.saveOnCreate::
Boolean, default `false`.
Controls whether a session that is newly created will be immediately saved to the `SessionDataStore` or lazily saved as the last request for the session exits.
This can be useful if the request dispatches to another context.
This can be useful if the request dispatches to another context and needs to re-use the same session id.
jetty.session.removeUnloadableSessions::
Boolean, default `false`.

81
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-usecases.adoc
View File

@ -17,79 +17,46 @@
//
[[ops-session-usecases]]
=== Session Use Cases
=== Session Scenarios
==== Clustering with a Sticky Load Balancer
Preferably, your cluster will utilize a sticky load balancer.
This will route requests for the same Session to the same Jetty instance.
In this case, the `DefaultSessionCache` can be used to keep in-use Session objects in memory.
You can fine-tune the cache by controlling how long Session objects remain in memory with the eviction policy settings.
This will route requests for the same session to the same Jetty instance.
In this case, the xref:ops-session-hash[`DefaultSessionCache`] can be used to keep in-use session objects xref:ops-session-hash[in memory].
You can fine-tune the cache by controlling how long session objects remain in memory with the xref:ops-session-hash[eviction policy settings].
If you have a large number of Sessions or very large Session objects, then you may want to manage your memory allocation by controlling the amount of time Session objects spend in the cache.
The `EVICT_ON_SESSION_EXIT` eviction policy will remove a Session object from the cache as soon as the last simultaneous request referencing it exits.
Alternatively, the `EVICT_ON_INACTIVITY` policy will remove a Session object from the cache after a configurable amount of time has passed without a request referencing it.
If you have a large number of sessions or very large session objects, then you may want to manage your memory allocation by controlling the amount of time session objects spend in the cache.
The `EVICT_ON_SESSION_EXIT` eviction policy will remove a session object from the cache as soon as the last simultaneous request referencing it exits.
Alternatively, the `EVICT_ON_INACTIVITY` policy will remove a session object from the cache after a configurable amount of time has passed without a request referencing it.
If your Sessions are very long lived and infrequently referenced, you might use the `EVICT_ON_INACTIVITY_POLICY` to control the size of the cache.
If your sessions are very long lived and infrequently referenced, you might use the `EVICT_ON_INACTIVITY_POLICY` to control the size of the cache.
If your Sessions are small, or relatively few or stable in number or they are read-mostly, then you might select the `NEVER_EVICT` policy.
With this policy, Session objects will remain in the cache until they either expire or are explicitly invalidated.
If your sessions are small, or relatively few or stable in number or they are read-mostly, then you might select the `NEVER_EVICT` policy.
With this policy, session objects will remain in the cache until they either expire or are explicitly invalidated.
If you have a high likelihood of simultaneous requests for the same session object, then the `EVICT_ON_SESSION_EXIT` policy will ensure the Session object stays in the cache as long as it is needed.
If you have a high likelihood of simultaneous requests for the same session object, then the `EVICT_ON_SESSION_EXIT` policy will ensure the session object stays in the cache as long as it is needed.
==== Clustering Without a Sticky Load Balancer
Without a sticky load balancer requests for the same session may arrive on any node in the cluster.
This means it is likely that the copy of the Session object in any `SessionCache` is likely to be out-of-date, as the Session was probably last accessed on a different node.
In this case, your choices are to use either the `NullSessionCache` or to de-tune the `DefaultSessionCache`.
If you use the NullSessionCache all Session object caching is avoided.
This means that every time a request references a session it must be brought in from persistent storage.
It also means that there can be no sharing of Session objects for multiple requests for the same session: each will have their own Session object.
This means it is likely that the copy of the session object in any `SessionCache` is likely to be out-of-date, as the session was probably last accessed on a different node.
In this case, your choices are to use either the xref:ops-session-null[`NullSessionCache`] or to de-tune the xref:ops-session-hash[`DefaultSessionCache`].
If you use the NullSessionCache all session object caching is avoided.
This means that every time a request references a session it must be read in from persistent storage.
It also means that there can be no sharing of session objects for multiple requests for the same session: each will have their own independent session object.
Furthermore, the outcome of session writes are indeterminate because the Servlet Specification does not mandate ACID transactions for sessions.
If you use the `DefaultSessionCache`, there is a risk that the caches on some nodes will contain out-of-date Session information as simultaneous requests for the same session are scattered over the cluster.
To mitigate this somewhat you can use the `EVICT_ON_SESSION_EXIT` eviction policy: this will ensure that the Session is removed from the cache as soon as the last simultaneous request for it exits.
Again, due to the lack of Session transactionality, the ordering outcome of write operations cannot be guaranteed.
As the Session is cached while at least one request is accessing it, it is possible for multiple simultaneous requests to share the same Session object.
If you use the `DefaultSessionCache`, there is a risk that the caches on some nodes will contain out-of-date session information as simultaneous requests for the same session are scattered over the cluster.
To mitigate this somewhat you can use the `EVICT_ON_SESSION_EXIT` eviction policy: this will ensure that the session is removed from the cache as soon as the last simultaneous request for it exits.
Again, due to the lack of session transactionality, the ordering outcome of write operations cannot be guaranteed.
As the session is cached while at least one request is accessing it, it is possible for multiple simultaneous requests to share the same session object.
==== Handling Corrupted or Unloadable Session Data
==== Handling Corrupted or Unreadable Session Data
For various reasons it might not be possible for the `SessionDataStore` to re-read a stored session.
One scenario is that the session stores a serialized object in it's attributes, and after a redeployment there in an incompatible class change.
Using the setter `SessionCache.setRemoveUnloadableSessions(true)` will allow the `SessionDataStore` to delete the unreadable session from persistent storage.
This can be useful for preventing the xref:ops-session-base-scavenge[scavenger] from continually generating errors on the same expired, but un-restorable session.
==== Configuring Sessions via Jetty XML
With the provided session modules, there is no need to configure a context xml or `jetty-web.xml` file for sessions.
That said, if a user wishes to configure sessions this way, it is possible using xref:jetty-xml-syntax[Jetty IoC XML format.]
Below is an example of how you could configure a the xref:ops-session-filesystem[`FileSessionDataStore`], but the same concept would apply to any of the *SessionDataStores discussed in this chapter:
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Call id="sh" name="getSessionHandler">
<Set name="sessionCache">
<New class="org.eclipse.jetty.server.session.DefaultSessionCache">
<Arg><Ref id="sh"/></Arg>
<Set name="sessionDataStore">
<New class="org.eclipse.jetty.server.session.FileSessionDataStore">
<Set name="storeDir">/tmp/sessions</Set>
</New>
</Set>
</New>
</Set>
</Call>
</Configure>
----
The example above functions in either a `jetty-web.xml` file or a xref:using-basic-descriptor-files[context xml descriptor file.]
[NOTE]
====
If you explicitly configure the `SessionCache` and `SessionDataStore` for a `SessionHandler` in a context xml file or `jetty-web.xml` file, any session modules you already have enabled are ignored.
So, for example, if you had enabled the `session-store-gcloud module` for your sever, you could force a particular webapp to use the `FileSessionDataStore` by explicitly configuring it in either a context xml file or a `jetty-web.xml` file as shown above.
====
One scenario is that the session stores a serialized object in it's attributes, and after a re-deployment there in an incompatible class change.
Setting the `${jetty.base}/start.d/session-cache-hash.ini` or `${jetty.base}/start.d/session-cache-null.ini` property `jetty.session.removeUnloadableSessions` to `true` will allow the unreadable session to be removed from persistent storage.
This can be useful for preventing the xref:ops-session-base-scavenge[scavenger] from continually generating errors on the same expired, but un-readable session.

52
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/session-xml.adoc Normal file
View File

@ -0,0 +1,52 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
TODO : decide whether to keep this info
==== Configuring Sessions via Jetty XML
With the provided session modules, there is no need to configure a context xml or `jetty-web.xml` file for sessions.
That said, if a user wishes to configure sessions this way, it is possible using xref:jetty-xml-syntax[Jetty IoC XML format.]
Below is an example of how you could configure a the xref:ops-session-filesystem[`FileSessionDataStore`], but the same concept would apply to any of the *SessionDataStores discussed in this chapter:
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Call id="sh" name="getSessionHandler">
<Set name="sessionCache">
<New class="org.eclipse.jetty.server.session.DefaultSessionCache">
<Arg><Ref id="sh"/></Arg>
<Set name="sessionDataStore">
<New class="org.eclipse.jetty.server.session.FileSessionDataStore">
<Set name="storeDir">/tmp/sessions</Set>
</New>
</Set>
</New>
</Set>
</Call>
</Configure>
----
The example above functions in either a `jetty-web.xml` file or a xref:using-basic-descriptor-files[context xml descriptor file.]
[NOTE]
====
If you explicitly configure the `SessionCache` and `SessionDataStore` for a `SessionHandler` in a context xml file or `jetty-web.xml` file, any session modules you already have enabled are ignored.
So, for example, if you had enabled the `session-store-gcloud module` for your sever, you could force a particular webapp to use the `FileSessionDataStore` by explicitly configuring it in either a context xml file or a `jetty-web.xml` file as shown above.
====

2
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/sessions/sessions.adoc
View File

@ -19,7 +19,7 @@
[[op-session]]
== Session Management
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.
Http 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.
Jetty offers a number of pluggable alternatives for managing and distributing/persisting sessions.
Choosing the best alternative is an important consideration for every application as is the correct configuration to achieve optimum performance.