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

Update session documentation 

Signed-off-by: Jan Bartel <janb@webtide.com>
This commit is contained in:
Jan Bartel 2020-09-10 17:06:47 +02:00
parent a437558a48
commit 9c6a449a25
8 changed files with 70 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -27,7 +27,7 @@ The `id-manager.xml` file instantiates a `DefaultSessionIdManager` and `HouseKee
The former is used to generate and manage session ids whilst the latter is responsible for periodic xref:ops-session-base-scavenge[scavenging] of expired sessions.
==== Configuration
The `start.d/sessions.ini` file contains thse configuration properties:
The `start.d/sessions.ini` file contains these configuration properties:
jetty.sessionIdManager.workerName::
This uniquely identifies the jetty server instance and is applied to the `SessionIdManager`.
@ -44,12 +44,12 @@ IMPORTANT: If you have more than one Jetty instance, it is *crucial* that you co
jetty.sessionScavengeInterval.seconds::
This is the period in _seconds_ between runs of the `HouseKeeper`, responsible for orchestrating the removal of expired sessions.
By default it will run every 600 secs (ie 10 mins).
As a rule of thumb, you should ensure that the xref:op-session-base-scavenge[scavenge] interval is shorter than the `<session-timeout>` of your sessions to ensure that they are promptly scavenged.
On the other hand, if you have a backend store configured for your sessions, xref:op-session-base-scavenge[scavenging] too frequently can increase the load on it.
As a rule of thumb, you should ensure that the xref:ops-session-base-scavenge[scavenge] interval is shorter than the `<session-timeout>` of your sessions to ensure that they are promptly scavenged.
On the other hand, if you have a backend store configured for your sessions, xref:ops-session-base-scavenge[scavenging] too frequently can increase the load on it.
TIP: Don't forget that the `<session-timeout>` is specified in web.xml in _minutes_ and the value of the `jetty.sessionScavengeInterval.seconds` is in _seconds_.
[[op-session-base-scavenge]]
[[ops-session-base-scavenge]]
==== Session Scavenging
The `HouseKeeper` is responsible for the periodic initiation of session scavenge cycles.
@ -63,8 +63,8 @@ The `HouseKeeper` sequentially asks the `SessionHandler` in each context to find
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.
These sessions can be safely loaded and fully expired, meaning that `HttpSessionListener.destroy()` can be called for them.
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.
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.

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

@ -24,6 +24,7 @@ Hazelcast can be used to cluster session information in one of two modes: either
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
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.
@ -79,9 +80,11 @@ Thorough consideration of the `maxIdleTime` of the session when setting the `sav
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
During testing, it can be helpful to run an in-process instance of Hazelcast.
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.
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).

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

@ -16,10 +16,11 @@
// ========================================================================
//
[[configuring-sessions-infinispan]]
[[ops-sessions-infinispan]]
=== Persistent Sessions: Inifinspan
[[ops-session-infinispan-remote]]
==== Enabling Infinispan Sessions
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.
@ -117,8 +118,8 @@ Note that this is an *additional* module, to be used in conjuction with the `ses
There are no configuration properties associated with this module.
==== Configuring Embedded Inifinspan Clustering
[[ops-session-infinispan-embedded]]
==== Configuring Embedded Infinispan Clustering
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.
@ -157,7 +158,7 @@ It also downloaded the needed Infinispan-specific jar files and created a direct
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 Inifinspan Embedded Properties
==== 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:

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

@ -16,7 +16,7 @@
// ========================================================================
//
[[configuring-sessions-jdbc]]
[[ops-sessions-jdbc]]
=== Persistent Sessions: JDBC

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

@ -16,7 +16,7 @@
// ========================================================================
//
[[session-configuration-memcachedsessiondatastore]]
[[ops-session-memcachedsessiondatastore]]
=== Persistent Sessions: The L2 Session Data Cache

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

@ -28,12 +28,13 @@ 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.
SessionIdManager::
is responsible for allocating session ids.
Any Jetty server can have at most 1 SessionIdManager.
HouseKeeper::
is responsible for periodically orchestrating the removal of expired sessions.
This process is referred to as "scavenging".
This process is referred to as xref:ops-session-base-scavenge["scavenging"].
SessionHandler::
is responsible for managing the lifecycle of sessions.
A context can have at most 1 `SessionHandler`.
@ -53,27 +54,27 @@ More details on these concepts can be found in the link:${PROGGUIDE}/server/sess
====
`SessionDataStores` interface with other, usually third party, systems responsible for storing and/or distributing session information.
Sessions can be distributed without being persisted.
They can also be persisted without being persisted.
Because persisting session information to a shared store is one very common way of distributing or "clustering" sessions, in the documentation we will often refer to just "persisting".
They can also be persisted without being distributed.
Because persisting session information to a shared store is a very common way of distributing (also known as "clustering") sessions, in the documentation we will often refer to just "persisting".
====
==== Jetty Session Modules
==== Session Modules
There are a number of modules that offer pluggable alternatives for http session management.
You can design how you want to cache and store http sessions by selecting alternative combinations of session modules.
For example, jetty ships with two alternative implementations of the `SessionCache`: one that caches sessions in memory (`session-cache-hash`) and a trivial implementation that does not actually cache (`session-cache-null`).
For example, Jetty ships with two alternative implementations of the `SessionCache`:
There are at least 6 alternative implementations of the `SessionDataStore` that you can use to persist your http sessions.
The list currently includes support for:
* one that caches sessions in memory: xref:ops-session-hash[`session-cache-hash`]
* one that does not actually cache: xref:ops-session-null[`session-cache-null`]
* file system storage (`session-store-file`)
* relational database storage (`session-store-jdbc`)
* NoSQL database storage (`session-store-mongo`)
* Google Cloud datastore storage (`session-store-gcloud`)
* Hazelcast storage (`session-store-hazelcast-remote` or `session-store-hazelcast-embedded`)
* Infinispan storage (`session-store-infinispan-remote` or `session-store-infinispan-embedded`)
There are at least 6 alternative implementations of the `SessionDataStore` that you can use to persist/distribute your http sessions:
You might like to consult the xref:ops-session-usecases[use cases] to help you decide which combinations best suit your needs.
* file system storage: xref:ops-session-filesystem[`session-store-file`]
* relational database storage: xref:ops-session-jdbc[`session-store-jdbc`]
* NoSQL database storage: xref:ops-session-mongo[`session-store-mongo`]
* Google Cloud datastore storage: xref:ops-session-gcloud[`session-store-gcloud`]
* 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.

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

@ -20,40 +20,52 @@
=== SessionCache Alternatives
In this section we will look at the alternatives for the `SessionCache`, ie the L1 cache of in-use session objects.
Jetty ships with two alternatives: an in-memory cache, and a null cache.
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 [use-cases] go into more detail on these scenarios.
The xref:ops-session-usecases[use-cases] go into more detail on these scenarios.
[[ops-session-hash]]
==== Sessions Cached in Memory
If you wish to change any of the default configuration values you should enable the `session-cache-hash` link:#startup-modules[module].
The name `hash` harks back to historical jetty session implementations, whereby sessions were kept in memory using a HashMap.
After you have enabled the `session-cache-hash` module, the `$jetty.base/start.d/session-cache-hash.ini` will be generated.
Edit this file to change the properties that control the behaviour of the cache.
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.
===== Configuration
jetty.session.evictionPolicy::
Integer.
Controls whether session objects that are held in memory are subject to eviction from the memory cache.
Evicting sessions can reduce the memory footprint of the cache.
Eviction is usually used in conjunction with a `SessionDataStore` that persists sessions.
Values are:
* -1 : sessions are never evicted from the cache
* 0 : sessions are evicted from the cache as soon as the last active request for it finishes
* >= 1 : any positive number is the time in seconds after which a session that is in the cache but has not experienced any activity will be evicted
The `$jetty.base/start.d/session-cache-hash.ini` contains the following configurable properties:
NOTE: If you are not using one of the session persistence modules, ie one of the `session-store-xxxx.mod`s, then sessions will be lost when the context is stopped.
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.
Eviction is usually used in conjunction with a `SessionDataStore` that persists sessions.
The set of eviction strategies and their values are:
-1 (NO EVICTION):::
sessions are never evicted from the cache.
The only way they leave are via expiration or invalidation.
0 (EVICT AFTER USE):::
sessions are evicted from the cache as soon as the last active request for it finishes.
The session will be passed to the `SessionDataStore` to be written out before eviction.
>= 1 (EVICT ON INACTIVITY):::
any positive number is the time in seconds after which a session that is in the cache but has not experienced any activity will be evicted.
Use the `jetty.session.saveOnInactiveEvict` property to force a session write before eviction.
NOTE: If you are not using one of the session store modules, ie one of the ``session-store-xxxx``s, then sessions will be lost when the context is stopped, or the session is evicted.
jetty.session.saveOnInactiveEvict::
Boolean, default `false`.
Controls whether a session will be persisted to the `SessionDataStore` just prior to its eviction.
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.
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.
jetty.session.removeUnloadableSessions::
Boolean, default `false`.
@ -61,7 +73,7 @@ Controls whether the session cache should ask a `SessionDataStore` to delete a s
jetty.session.flushOnResponseCommit::
Boolean, default `false`.
If true, if a session is "dirty" - ie its attributes have changed - it will be written to the backing store as the response is about to commit.
If true, if a session is "dirty" - ie its attributes have changed - it will be written to the `SessionDataStore` as the response is about to commit.
This ensures that all subsequent requests whether to the same or different node will see the updated session data.
If false, a dirty session will only be written to the backing store when the last simultaneous request for it leaves the session.
@ -70,16 +82,18 @@ Boolean, default `false`.
If true, when a context is shutdown, all sessions in the cache are invalidated and deleted both from the cache and from the `SessionDataStore`.
[[ops-session-null]]
==== Sessions Not Cached
You may need to use the `session-cache-null.mod` 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.mod` modules), then sessions will _neither_ be retained in memory _nor_ persisted.
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.
===== Configuration
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.
jetty.session.removeUnloadableSessions::
Boolean, default `false`.

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

@ -20,12 +20,13 @@
== 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.
Choosing the correct session manager implementation is an important consideration for every application as each can fit and perform optimally in different situations.
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.
include::session-overview.adoc[]
include::session-base.adoc[]
include::session-sessioncache.adoc[]
include::session-file-system.adoc[]
include::session-filesystem.adoc[]
include::session-jdbc.adoc[]
include::session-mongodb.adoc[]
include::session-infinispan.adoc[]