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

Documentation updates for #1793.

This commit is contained in:
WalkerWatch 2017-09-06 17:11:39 -04:00
parent df0e6d7f43
commit 1a89dff8db
13 changed files with 63 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -16,9 +16,9 @@
[[configuring-sessions-file-system]]
=== Persisted Sessions: File System
=== Persistent Sessions: File System
Note: Persisting sessions to the local file system should NOT be used in a clustered environment.
Note: Persisting sessions to the local file system should *not* be used in a clustered environment.
==== Enabling File System Sessions

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

@ -15,7 +15,8 @@
// ========================================================================
[[configuring-sessions-gcloud]]
=== Persisted Sessions: Google Cloud DataStore
=== Persistent Sessions: Google Cloud DataStore
==== Preparation

2
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-hazelcast.adoc
View File

@ -16,7 +16,7 @@
[[configuring-sessions-hazelcast]]
=== Persisted Sessions: Hazelcast
=== Persistent Sessions: Hazelcast
==== Enabling Hazelcast Sessions

25
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-housekeeper.adoc
View File

@ -17,37 +17,38 @@
[[session-configuration-housekeeper]]
=== The SessionIdManager and the Housekeeper
==== The Defaults
By default, jetty will instantiate a single instance of the DefaultSessionIdManager and HouseKeeper at startup with default settings.
==== Default Settings
By default, Jetty will instantiate a single instance of the `DefaultSessionIdManager` and `HouseKeeper` at startup with default settings.
The default settings are:
DefaultSessionIdManager: worker name::
This uniquely identifies the jetty server instance within a cluster.
It is set from the value of the JETTY_WORKER_INSTANCE environment variable, or "node0" if the environment value is not set.
If you have more than one jetty instance, it is crucial that you explicitly configure the worker name on each jetty instance (see below for how to configure).
It is set from the value of the `JETTY_WORKER_INSTANCE` environment variable, or `node0` if the environment value is not set.
If you have more than one Jetty instance, it is *crucial* that you explicitly configure the worker name on each Jetty instance (see link:#session-idmanager-housekeeper-config[below] for how to configure).
HouseKeeper: scavenge interval::
This is the period in seconds between runs of the session scavenger, and by default is set to the equivalent of 10mins.
As a rule of thumb, you should ensure that the scavenge interval is shorter than the maxInactiveInterval of your sessions to ensure that they are promptly scavenged. See below for instructions on how to configure this.
This is the period in seconds between runs of the session scavenger, and by default is set to the equivalent of 10 minutes.
As a rule of thumb, you should ensure that the scavenge interval is shorter than the `maxInactiveInterval` of your sessions to ensure that they are promptly scavenged.
See below for instructions on how to configure this.
==== Configuring
[[session-idmanager-housekeeper-config]]
==== Configuration
To change the default values, use the link:#startup-modules[module system] to link:#startup-modules[enable] the `sessions` module.
This will enable the `$jetty.home/etc/sessions/id-manager.xml` file and generate a `$jetty.base/start.d/sessions.ini` file.
The `$jetty.home/etc/sessions/id-manager.xml` file instantiates a singleton DefaultSessionIdManager and HouseKeeper and configures them using the properties from the `$jetty.base/start.d/sessions.ini` file.
The `id-manager.xml` file instantiates a single `DefaultSessionIdManager` and `HouseKeeper` and configures them using the properties from the `sessions.ini` file.
Edit the file to change the properties to easily customize the DefaultSessionIdManager and HouseKeeper:
Edit the ini file to change the properties to easily customize the `DefaultSessionIdManager` and `HouseKeeper`:
jetty.sessionIdManager.workerName::
By default it is `node1`.
This uniquely identifies the jetty server instance within a cluster.
If you have more than one jetty instance, it is crucial that you configure the worker name differently on each jetty instance.
This uniquely identifies the Jetty server instance within a cluster.
If you have more than one Jetty instance, it is crucial that you configure the worker name differently on each jetty instance.
jetty.sessionScavengeInterval.seconds::
This is the period in seconds between runs of the session scavenger.
By default it will run every 600 secs (ie 10 mins).
As a rule of thumb, you should ensure that the scavenge interval is shorter than the maxInactiveInterval of your sessions to ensure that they are promptly scavenged.

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

@ -16,7 +16,7 @@
[[configuring-sessions-infinispan]]
=== Persisted Sessions: Inifinspan
=== Persistent Sessions: Inifinspan
==== Enabling Infinispan Sessions

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

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

7
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-memcachedsessiondatastore.adoc
View File

@ -15,7 +15,8 @@
// ========================================================================
[[session-configuration-memcachedsessiondatastore]]
=== Persisted Sessions: The L2 Session Data Cache
=== 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.
@ -24,7 +25,7 @@ The `CachingSessionDataStore` is a special type of `SessionDataStore` that local
The `MemcachedSessionDataMap` uses `memcached` to perform caching.
To enable it with the jetty distribution, use the `session-store-cache` link:#startup-modules[module], along with your chosen `session-store-xxxx` module of course, and optionally the `session-cache-hash` or `session-cache-null` modules.
To enable it with the Jetty distribution, enable the `session-store-cache` link:#startup-modules[module], along with your chosen `session-store-xxxx` module, and optionally the `session-cache-hash` or `session-cache-null` modules.
After enabling, the `$jetty.base/start.d/session-store-cache.ini` file will be generated:
@ -56,8 +57,6 @@ jetty.session.memcached.expirySec::
Default value `0`.
This is the length of time in seconds that an item can remain in the memcached cache, where 0 indicates indefinitely.
jetty.session.memcached.heartbeats::
Default value `true`.
Whether or not the memcached system should generate heartbeats.

11
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-memory.adoc
View File

@ -16,17 +16,16 @@
[[configuring-sessions-memory]]
=== Non-persisted Sessions
=== Non-Persistent Sessions
Non-clustered, non-persisted, in-memory-only is the default style of session management.
Non-clustered, non-persistent, in-memory-only is the default style of session management.
In previous versions of Jetty this was referred to as "hash" sessions, as they were stored in a `HashMap` in memory.
This is delivered by a combination of the `DefaultSessionCache` (to keep sessions in memory) and a `NullSessionDataStore` (to avoid session persistence).
If you do nothing, then jetty will instantiate one of each of these objects for each context at startup time using hard-coded defaults.
If you do nothing, Jetty will instantiate one of each of these objects for each context at startup time using hard-coded defaults.
To explicitly set up non-persisted sessions using modules, use both the `session-cache-hash` and the `session-store-null` modules.
Enabling the modules allows you to configure behaviour - see link:#session-configuration-sessioncache[The L1 Session Cache] for detailed information on configuration options for the `DefaultSessionCache`.
As it is so trivial, the `NullSessionDataStore` has no customizable options.
Enabling the modules allows you to configure behavior - see link:#session-configuration-sessioncache[the L1 Session Cache] for detailed information on configuration options for the `DefaultSessionCache`.
The `NullSessionDataStore` has no customizable options.

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

@ -16,7 +16,7 @@
[[configuring-sessions-mongo]]
=== Persisted Sessions: MongoDB
=== Persistent Sessions: MongoDB
==== Enabling MongoDB Sessions

12
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-sessioncache.adoc
View File

@ -19,10 +19,10 @@
==== The DefaultSessionCache
In the absence of any explicit configuration, jetty will instantiate an instance of the `DefaultSessionCache` per context.
If you wish to change any of the defaulted values, you need to enable the `sesssion-cache-hash` link:#startup-modules[module].
In the absence of any explicit configuration, Jetty will instantiate an instance of the `DefaultSessionCache` per context.
If you wish to change any of the default values, you need to enable the `session-cache-hash` link:#startup-modules[module].
Opening `start.d/session-cache-hash.ini` will show a list of all the configurable options:
Once the `session-cache-hash` module has been enabled, you can view a list of all the configurable values by opening `start.d/session-cache-hash.ini`:
[source, screen, subs="{sub-order}"]
----
@ -39,12 +39,16 @@ 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.
If you are not using a `SessionDataStore` that persists sessions, then be aware that evicted sessions will be lost.
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
____
[NOTE]
If you are not using a `SessionDataStore` that persists sessions, be aware that evicted sessions will be lost.
____
jetty.session.saveOnInactiveEvict::
Boolean, default `false`.
Controls whether a session will be saved to the `SessionDataStore` just prior to its eviction.

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

@ -49,11 +49,11 @@ image::images/SessionsHierarchy.png[]
==== Configuring Sessions in the Jetty Distribution
Configuring session management involves selecting a link:#startup-modules[module] for the desired type of link:#session-configuration-sessioncache[session caching] behaviour, and a module for the type of session persistance.
Configuring session management involves selecting a link:#startup-modules[module] for the desired type of link:#session-configuration-sessioncache[session caching] behavior, and a module for the type of session persistence.
Jetty provides two different session caches: the `DefaultSessionCache` which holds sessions in memory, and the `NullSessionCache` which does not.
There is more information on both of these types of session caching and the circumstances which would lead you to select one or the other in the link:#sessions-details[Session Components] section, and more information on the configuration options of each in link:#session-configuration-sessioncache[The L1 Session Cache] section.
There is more information on both of these types of session caching and the circumstances which would lead you to select one or the other in the link:#sessions-details[Session Components] section, and more information on the configuration options of each in link:#session-configuration-sessioncache[the L1 Session Cache] section.
For session persistence, jetty provides a number of different implementations from which to choose including link:#configuring-sessions-memory[non-persistence], link:#configuring-sessions-file-system[local file storage], clustered technologies such as link:#configuring-sessions-jdbc[JDBC], link:#configuring-sessions-mongo[MongoDB], link:#configuring-sessions-infinispan[Inifinispan], link:#configuring-sessions-gcloud[Google Cloud Datastore], and link:#configuring-sessions-hazelcast[Hazelcast].
For session persistence, Jetty provides a number of different implementations from which to choose including link:#configuring-sessions-memory[non-persistence], link:#configuring-sessions-file-system[local file storage], clustered technologies such as link:#configuring-sessions-jdbc[JDBC], link:#configuring-sessions-mongo[MongoDB], link:#configuring-sessions-infinispan[Inifinispan], link:#configuring-sessions-gcloud[Google Cloud Datastore], and link:#configuring-sessions-hazelcast[Hazelcast].
Depending on your persistence technology, to enhance performance, you might want to use an L2 cache for session data, in which case jetty provides the link:#session-configuration-memcachedsessiondatastore[memcached L2 session data cache].
Depending on your persistence technology, to enhance performance, you may want to use an L2 cache for session data, in which case Jetty provides the link:#session-configuration-memcachedsessiondatastore[memcached L2 session data cache].

24
jetty-documentation/src/main/asciidoc/administration/sessions/sessions-details.adoc
View File

@ -19,13 +19,13 @@
==== SessionIdManager
There is a maximum of 1 `SessionIdManager` per jetty Server instance.
There is a maximum of one (1) `SessionIdManager` per Jetty Server instance.
Its purpose is to generate fresh, unique session ids and to coordinate the re-use of session ids amongst co-operating contexts.
Unlike in previous versions of Jetty, the `SessionIdManager` is agnostic with respect to the type of clustering technology chosen.
Jetty provides a default implementation - the `DefaultSessionIdManager` - which should meet the needs of most users.
If you do not explicitly enable one of the session modules, or otherwise configure a `SessionIdManager`, the `DefaultSessionIdManager` will be used.
If you do not explicitly enable one of the session modules or otherwise configure a `SessionIdManager`, the `DefaultSessionIdManager` will be used.
If the `DefaultSessionIdManager` does not meet your needs, you can extend the `org.eclipse.jetty.server.session.AbstractSessionIdManager` or do a fresh implementation of the `org.eclipse.jetty.server.session.SessionIdManager` interface.
@ -33,7 +33,7 @@ See link:#session-configuration-housekeeper[Configuring the SessionIdManager and
==== HouseKeeper
There is a maximum of 1 `HouseKeeper` per `SessionIdManager`.
There is a maximum of one (1) `HouseKeeper` per `SessionIdManager`.
Its purpose is to periodically poll the `SessionHandlers` to clean out expired sessions.
By default the `HouseKeeper` will poll the `SessionHandlers` every 10 mins to find and delete expired sessions, although this interval is configurable.
@ -43,14 +43,15 @@ See link:#session-configuration-housekeeper[Configuring the SessionIdManager and
==== SessionCache
There is 1 `SessionCache` per context.
There is one (1) `SessionCache` *per context.*
Its purpose is to provide an L1 cache of Session objects.
Having a working set of Session objects in memory allows multiple simultaneous requests for the same session to share the same Session object.
Jetty provides 2 `SessionCache` implementations: the `DefaultSessionCache` and the `NullSessionCache`.
Jetty provides two (2) `SessionCache` implementations: the `DefaultSessionCache` and the `NullSessionCache`.
The `DefaultSessionCache` retains Session objects in memory in a cache and has a number of link:#session-configuration-sessioncache[configuration options] to control cache behavior.
It is the default that is used if no other `SessionCache` has been configured.
It is suitable for non-clustered and clustered deployments with a sticky load balancer, as well as clustered deployments with a non-sticky load balancer, with some caveats.
The `NullSessionCache` does not actually cache any objects: each request uses a fresh Session object.
It is suitable for clustered deployments without a sticky load balancer and non-clustered deployments when purely minimal support for sessions is needed.
@ -60,18 +61,19 @@ They can also be configured to do an immediate, eager write of a freshly created
This can be useful if you are likely to experience multiple, near simultaneous requests referencing the same session, e.g. with HTTP/2 and you don't have a sticky load balancer.
Alternatively, if the eager write is not done, application paths which create and then invalidate a session within a single request never incur the cost of writing to persistent storage.
Additionally, if the `EVICT_ON_INACTIVITY` eviction policy is in use, you can link:#session-configuration-sessioncache[configure] the `DefaultSessionCache` to force a write of the Session to the SessionDataStore just before the Session is evicted.
Additionally, if the `EVICT_ON_INACTIVITY` eviction policy is in use, you can link:#session-configuration-sessioncache[configure] the `DefaultSessionCache` to force a write of the Session to the `SessionDataStore` just before the Session is evicted.
See link:#session-configuration-sessioncache[The L1 Session Cache] for more information.
See link:#session-configuration-sessioncache[the L1 Session Cache] for more information.
==== SessionDataStore
There is 1 `SessionDataStore` per context. Its purpose is to handle all persistence related operations on sessions.
There is one (1) `SessionDataStore` per context.
Its purpose is to handle all persistence related operations on sessions.
The common characteristics for all `SessionDataStores` are whether or not they support passivation, and the length of the grace period.
Supporting passivation means that session data is serialized.
Some persistence mechanisms serialize, such as JDBC, GCloud Datastore etc, whereas others may store an object in shared memory eg Infinispan when configured with a local cache.
Some persistence mechanisms serialize, such as JDBC, GCloud Datastore etc, whereas others may store an object in shared memory, e.g. Infinispan, when configured with a local cache.
Whether or not a clustering technology entails passivation controls whether or not the session passivation/activation listeners will be called.
@ -90,10 +92,10 @@ The distribution provides a number of alternative `SessionDataStore` implementat
==== CachingSessionDataStore
The `CachingSessionDataStore` is a special type of `SessionDataStore` that inserts an L2 cache of SessionData - the `SessionDataMap` - in front of a delegate `SessionDataStore`.
The `CachingSessionDataStore` is a special type of `SessionDataStore` that inserts an L2 cache of Session data - the `SessionDataMap` - in front of a delegate `SessionDataStore`.
The `SessionDataMap` is preferentially consulted before the actual SessionDataStore on reads.
This can improve the performance of slow stores.
Jetty provides one implementation of the this L2 cache based on `Memcached`, the `MemcachedSessionDataMap`.
See link:#session-configuration-memcachedsessiondatastore[The L2 SessionData Cache].
See link:#session-configuration-memcachedsessiondatastore[the L2 SessionData Cache]for additional information.

12
jetty-documentation/src/main/asciidoc/administration/sessions/sessions-usecases.adoc
View File

@ -20,11 +20,11 @@
===== 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.
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.
If you have a large number of Sessions or very large Session objects, then you might want to manage your memory allocation by controlling the amount of time Session objects spend in the cache.
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.
@ -36,7 +36,7 @@ With this policy, Session objects will remain in the cache until they either exp
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
===== 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.
@ -46,15 +46,15 @@ This means that every time a request references a session it must be brought in
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.
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.
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.
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
For various reasons it might not be possible for the SessionDataStore to re-read a stored session.
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 from preventing the scavenger from continually generating errors on the same expired, but un-restorable, session.