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

Updates for sessions upgrade, misc doc cleanup. 

Signed-off-by: WalkerWatch <ctwalker@gmail.com>
This commit is contained in:
WalkerWatch 2016-11-10 16:11:17 -05:00
parent fe1704c89a
commit 0ebe3d7bd9
6 changed files with 128 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
jetty-documentation/src/main/asciidoc/administration/logging/chapter.adoc
View File

@ -23,11 +23,5 @@ include::configuring-jetty-logging.adoc[]
include::default-logging-with-stderrlog.adoc[] include::default-logging-with-stderrlog.adoc[]
include::configuring-jetty-request-logs.adoc[] include::configuring-jetty-request-logs.adoc[]
include::configuring-logging-modules.adoc[] include::configuring-logging-modules.adoc[]
// TODO - Remove following
// include::example-apache-log4j.adoc[]
// include::example-java-util-logging.adoc[]
// include::example-java-util-logging-native.adoc[]
// include::example-logback.adoc[]
// include::example-slf4j-multiple-loggers.adoc[]
include::example-logback-centralized-logging.adoc[] include::example-logback-centralized-logging.adoc[]
include::dump-tool.adoc[] include::dump-tool.adoc[]

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

@ -47,8 +47,6 @@ The Google deployment tools will automatically configure the project and authent
Regardless of whether you're running inside or outside google infrastructure you will need to upload a file that defines some indexes that are needed by the GCloud datastore session data store. Regardless of whether you're running inside or outside google infrastructure you will need to upload a file that defines some indexes that are needed by the GCloud datastore session data store.
This file is named `index.yaml` and you can find it in your distribution in `${jetty.base}/etc/sessions/gcloud/index.yaml`. This file is named `index.yaml` and you can find it in your distribution in `${jetty.base}/etc/sessions/gcloud/index.yaml`.
//TODO - Add index.yaml properties? Test with new 9.4.x. It needs uploaded to Google as part of config
Follow the instructions link:https://cloud.google.com/datastore/docs/tools/#the_development_workflow_using_gcloud[here] to upload the pre-generated `index.yaml` file. Follow the instructions link:https://cloud.google.com/datastore/docs/tools/#the_development_workflow_using_gcloud[here] to upload the pre-generated `index.yaml` file.
===== Communicating with the GCloudDataStore Emulator ===== Communicating with the GCloudDataStore Emulator

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

@ -42,10 +42,6 @@ However, it is possible to provide your own implementation that never shares Ses
Where the `SessionCache` handles Session information, Session data is stored in a `SessionDataStore` that is specific to the clustering technology being implemented. Where the `SessionCache` handles Session information, Session data is stored in a `SessionDataStore` that is specific to the clustering technology being implemented.
There is only one (1) `SessionDataStore` per `SessionCache`. There is only one (1) `SessionDataStore` per `SessionCache`.
//TODO : Information on memcache-d, when to use different config options. "Configuration Scenarios?"
// Null cache, memcache, non-sticky load-balancer
// in-memory caching
Visually the session architecture can be represented like this: Visually the session architecture can be represented like this:
image::images/SessionsHierarchy.png[] image::images/SessionsHierarchy.png[]

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

@ -21,68 +21,72 @@
===== SessionIdManager ===== SessionIdManager
There is a maximum of 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. There is a maximum of 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. 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 most users' needs. 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. 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.
===== HouseKeeper ===== HouseKeeper
There is a maximum of 1 HouseKeeper per SessionIdManager. Its purpose is to periodically poll the SessionHandlers to clean out expired sessions. There is a maximum of 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. By default the `HouseKeeper` will poll the `SessionHandlers` every 10 mins to find and delete expired sessions, although this interval is configurable.
===== SessionCache ===== SessionCache
There is 1 SessionCache per context. Its purpose is to provide an L1 cache of Session objects. There is 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. 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 2 `SessionCache` implementations: the `DefaultSessionCache` and the `NullSessionCache`.
The DefaultSessionCache retains Session objects in memory in a cache and has a number of configuration options to control cache behaviour. The `DefaultSessionCache` retains Session objects in memory in a cache and has a number of configuration options to control cache behavior.
It is the default that is used if no other SessionCache has been configured. 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. 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. 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. It is suitable for clustered deployments without a sticky load balancer and non-clustered deployments when purely minimal support for sessions is needed.
SessionCaches always write out a Session to the SessionDataStore whenever the last request for the Session exits. `SessionCaches` always write out a Session to the `SessionDataStore` whenever the last request for the Session exits.
They can also be configured to do an immediate, eager write of a freshly created session. They can also be configured to do an immediate, eager write of a freshly created session.
This can be useful if you are likely to experience multiple, near simultaneous requests referencing the same session, eg with HTTP2 and you don't have a sticky load balancer. 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. 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 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 configure the `DefaultSessionCache` to force a write of the Session to the SessionDataStore just before the Session is evicted.
===== SessionDataStore ===== SessionDataStore
There is 1 SessionDataStore per context. Its purpose is to handle all persistance related operations on sessions. There is 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. 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. 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 eg 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. Whether or not a clustering technology entails passivation controls whether or not the session passivation/activation listeners will be called.
The grace period is an interval, configured in seconds, that attempts to deal with the non-transactional nature of sessions with regard to finding sessions that have expired. The grace period is an interval, configured in seconds, that attempts to deal with the non-transactional nature of sessions with regard to finding sessions that have expired.
Due to the lack of transactionality, in a clustered configuration, even with a sticky load balancer, it is always possible that a Session is live on a node but has not yet been updated in the persistent store. Due to the lack of transactionality, in a clustered configuration, even with a sticky load balancer, it is always possible that a Session is live on a node but has not yet been updated in the persistent store.
When SessionDataStores search their persistant store to find sessions that have expired, they typically perform a few sequential searches: When `SessionDataStores` search their persistent store to find sessions that have expired, they typically perform a few sequential searches:
. the first verifies the expiration of a list of candidate session ids suggested by the SessionCache
. the second finds sessions in the store that have expired which were last live on the current node * The first verifies the expiration of a list of candidate session ids suggested by the SessionCache
. the third finds sessions that expired a "while" ago, irrespective of on which node they were last used: the definition of "a while" is based on the grace period. * The second finds sessions in the store that have expired which were last live on the current node
* The third finds sessions that expired a "while" ago, irrespective of on which node they were last used: the definition of "a while" is based on the grace period.
===== CachingSessionDataStore ===== 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 SessionData - the `SessionDataMap` - in front of a delegate `SessionDataStore`.
The SessionDataMap is preferentially consulted before the actual SessionDataStore on reads. The `SessionDataMap` is preferentially consulted before the actual SessionDataStore on reads.
This can improve the performance of slow stores. This can improve the performance of slow stores.
At the time of writing, jetty provides one implementation of the this L2 cache based on Memcached, the MemcachedSessionDataMap. Jetty provides one implementation of the this L2 cache based on `Memcached`, the `MemcachedSessionDataMap`.
==== Use Cases ==== Use Cases
@ -90,34 +94,34 @@ At the time of writing, jetty provides one implementation of the this L2 cache b
===== Clustering with a Sticky Load Balancer ===== Clustering with a Sticky Load Balancer
Preferably, your cluster will utilize 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. 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. 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 might 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. 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. 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. 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. 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 ===== Clustering without a Sticky Load Balancer
Without a sticky load balancer requests for the same session may arrive on any node in the cluster. 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. 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-tuned the DefaultSessionCache. In this case, your `choices` are to use either the `NullSessionCache` or to de-tuned the `DefaultSessionCache`.
If you use the NullSessionCache all Session object caching is avoided. 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. 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. 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. 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. 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. 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.
@ -126,6 +130,5 @@ As the Session is cached while at least one request is accessing it, it is possi
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. 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. 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 erroring on the same expired, but unrestorable session. This can be useful from preventing the scavenger from continually generating errors on the same expired, but un-restorable, session.

7
jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc
View File

@ -270,10 +270,3 @@ To filter out internal modules when searching a specific module tag, simply add
For example, if you wanted to look at only the logging modules (excluding the internal implementation modules), you would use `--list-modules=logging,-internal`. For example, if you wanted to look at only the logging modules (excluding the internal implementation modules), you would use `--list-modules=logging,-internal`.
include::screen-list-logging-modules.adoc[] include::screen-list-logging-modules.adoc[]
// Since being introduced in Jetty 9.1 the modules provided in the Jetty distribution has expanded greatly.
// Below is a graphical representation of the standard modules and their dependencies.
//
// TODO - Update modules image for 9.4 / 10?
//
// image:images/modules-9.3-simplified.png[image,width=768]

175
jetty-documentation/src/main/asciidoc/reference/upgrading/upgrading-9.3-to-9.4.adoc
View File

@ -18,11 +18,9 @@
==== jetty.sh ==== jetty.sh
The file `jetty.sh`, typically used to start Jetty as a service in Linux/Unix The file `jetty.sh`, typically used to start Jetty as a service in Linux/Unix machines underwent only small changes, such as the addition of https://wiki.debian.org/LSBInitScripts[LSB tags].
machines underwent only small changes, such as the addition of
https://wiki.debian.org/LSBInitScripts[LSB tags].
You can safely replace Jetty 9.3's `jetty.sh` with 9.4's. You can safely replace the `jetty.sh` file packaged with Jetty 9.3 with the version found in Jetty 9.4.
==== Removed Classes ==== Removed Classes
@ -32,7 +30,7 @@ You can safely replace Jetty 9.3's `jetty.sh` with 9.4's.
[cols="1,1", options="header"] [cols="1,1", options="header"]
|=== |===
| 9.3 Module | 9.4 Module | Jetty 9.3 Module | Jetty 9.4 Module
| `logging` | `console-capture` | `logging` | `console-capture`
| `infinispan` | `session-store-infinispan-embedded` or `session-store-infinispan-remote` | `infinispan` | `session-store-infinispan-embedded` or `session-store-infinispan-remote`
| `jdbc-sessions` | `session-store-jdbc` | `jdbc-sessions` | `session-store-jdbc`
@ -44,28 +42,19 @@ You can safely replace Jetty 9.3's `jetty.sh` with 9.4's.
The module `logging` is no longer available in Jetty 9.4. The module `logging` is no longer available in Jetty 9.4.
The logging module structure present in Jetty 9.3 has been replaced with The logging module structure present in Jetty 9.3 has been replaced with a more fine-grained structure in Jetty 9.4, so that you have now more choices available that are also easier to configure.
a more fine-grained structure in Jetty 9.4, so that you have now more choices
available that are also easier to configure.
The migration path is different depending on whether you have completely The migration path is different depending on whether you have completely customized this module or not.
customized this module or not.
If you have a Jetty 9.3 installation, and you have both If you have a Jetty 9.3 installation, and you have both `$jetty.base/modules/logging.mod` and `$jetty.base/etc/jetty-logging.xml`, then this module is local to your `$jetty.base` setup and will be used by Jetty 9.4 as before.
`$jetty.base/modules/logging.mod` and `$jetty.base/etc/jetty-logging.xml`,
then this module is local to your `$jetty.base` setup and will be used
by Jetty 9.4 as before.
No changes are required for your implementation. No changes are required for your implementation.
If either `$jetty.base/modules/logging.mod` or `$jetty.base/etc/jetty-logging.xml` If either `$jetty.base/modules/logging.mod` or `$jetty.base/etc/jetty-logging.xml` are missing, then you were relying on those present in `$jetty.home`, which were present in Jetty 9.3, but are no longer available in Jetty 9.4.
are missing, then you were relying on those present in `$jetty.home`,
which were present in Jetty 9.3, but are no longer available in Jetty 9.4.
The Jetty 9.3 `logging` module has been renamed to `console-capture` in Jetty 9.4. The Jetty 9.3 `logging` module has been renamed to `console-capture` in Jetty 9.4.
You need to open your Jetty 9.3 `start.ini` and replace the references to the You need to open your Jetty 9.3 `start.ini` and replace the references to the `logging` modules with `console-capture`.
`logging` modules with `console-capture`.
For example, in an existing 9.3 `start.ini` file the module declaration for logging would look like this: For example, in an existing Jetty 9.3 `start.ini` file the module declaration for logging would look like this:
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]
---- ----
@ -85,14 +74,14 @@ The properties that may be present in your Jetty 9.3's `start.ini`, such as `jet
For information on logging modules in the Jetty 9.4 architecture please see the section on link:#configuring-logging-modules[configuring logging modules.] For information on logging modules in the Jetty 9.4 architecture please see the section on link:#configuring-logging-modules[configuring logging modules.]
===== Session Management ==== Session Management
Session management received a significant overhaul in Jetty 9.4. Session management received a significant overhaul in Jetty 9.4.
Session functionality has been refactored to promote code-reuse, easier configuration and easier customization. Session functionality has been refactored to promote code-reuse, easier configuration and easier customization.
Whereas previously users needed to edit xml configuration files, in Jetty 9.4 all session behavior is controlled by properties that are exposed by the various session modules. Whereas previously users needed to edit xml configuration files, in Jetty 9.4 all session behavior is controlled by properties that are exposed by the various session modules.
Users now configure session management by selecting a composition of session modules. Users now configure session management by selecting a composition of session modules.
====== Change Overview ===== Change Overview
SessionIdManager:: Previously there was a different class of SessionIdManager - with different configuration options - depending upon which type of clustering technology chosen. SessionIdManager:: Previously there was a different class of SessionIdManager - with different configuration options - depending upon which type of clustering technology chosen.
In Jetty 9.4, there is only one type, the link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionIdManager.html[org.eclipse.jetty.server.session.DefaultSessionIdManager]. In Jetty 9.4, there is only one type, the link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionIdManager.html[org.eclipse.jetty.server.session.DefaultSessionIdManager].
@ -101,155 +90,157 @@ SessionManager:: Previously, there was a different class of SessionManager depen
In Jetty 9.4 we have removed the SessionManager class and split its functionality into different, more easily extensible and composable classes: In Jetty 9.4 we have removed the SessionManager class and split its functionality into different, more easily extensible and composable classes:
General setters::: General setters:::
All of the common setup of sessions such as the maxInactiveInterval and session cookie-related configuration has been moved to the link:{JDURL}/org/eclipse/jetty/server/session/SessionHandler.html[org.eclipse.jetty.server.session.SessionHandler] All of the common setup of sessions such as the maxInactiveInterval and session cookie-related configuration has been moved to the link:{JDURL}/org/eclipse/jetty/server/session/SessionHandler.html[org.eclipse.jetty.server.session.SessionHandler]
[cols="1,1", options="header"] [cols="1,1", options="header"]
|=== |===
| 9.3 SessionManager | 9.4 SessionHandler | 9.3 SessionManager | 9.4 SessionHandler
| setMaxInactiveInterval(sec) | setMaxInactiveInterval(sec) | `setMaxInactiveInterval(sec)` | `setMaxInactiveInterval(sec)`
| setSessionCookie(String) | setSessionCookie(String) | `setSessionCookie(String)` | `setSessionCookie(String)`
| setRefreshCookieAge(sec) | setRefreshCookieAge(sec) | `setRefreshCookieAge(sec)` | `setRefreshCookieAge(sec)`
| setSecureRequestOnly(boolean) | setSecureRequestOnly(boolean | `setSecureRequestOnly(boolean)` | `setSecureRequestOnly(boolean)`
| setSessionIdPathParameterName(String) | setSessionIdPathParameterName(String) | `setSessionIdPathParameterName(String)` | `setSessionIdPathParameterName(String)`
| setSessionTrackingModes(Set<SessionTrackingMode>) | setSessionTrackingModes(Set<SessionTrackingMode>) | `setSessionTrackingModes(Set<SessionTrackingMode>)` | `setSessionTrackingModes(Set<SessionTrackingMode>)`
| setHttpOnly(boolean) | setHttpOnly(boolean) | `setHttpOnly(boolean)` | `setHttpOnly(boolean)`
| setUsingCookies(boolean) | setUsingCookies(boolean) | `setUsingCookies(boolean)` | `setUsingCookies(boolean)`
| setCheckingRemoteSessionIdEncoding(boolean) | setCheckingRemoteSessionIdEncoding(boolean) | `setCheckingRemoteSessionIdEncoding(boolean)` | `setCheckingRemoteSessionIdEncoding(boolean)`
|=== |===
Persistence::: Persistence:::
In Jetty 9.3 SessionManagers (and sometimes SessionIdManagers) implemented the persistence mechanism. In Jetty 9.3 `SessionManagers` (and sometimes `SessionIdManagers`) implemented the persistence mechanism.
In Jetty 9.4 we have moved this functionality into the link:{JDURL}/org/eclipse/jetty/server/session/SessionDataStore.html[org.eclipse.jetty.server.session.SessionDataStore]. In Jetty 9.4 we have moved this functionality into the link:{JDURL}/org/eclipse/jetty/server/session/SessionDataStore.html[`org.eclipse.jetty.server.session.SessionDataStore`].
Session cache::: Session cache:::
In Jetty 9.3 the SessionManager held a map of session objects in memory. In Jetty 9.3 the `SessionManager` held a map of session objects in memory.
In Jetty 9.4 this has been moved into the new link:{JDURL}/org/eclipse/jetty/server/session/SessionCache.html[org.eclipse.jetty.server.session.SessionCache] interface. In Jetty 9.4 this has been moved into the new link:{JDURL}/org/eclipse/jetty/server/session/SessionCache.html[`org.eclipse.jetty.server.session.SessionCache`] interface.
For more information, please refer to the documentation on link:#jetty-sessions-architecture[Jetty Session Architecture.] For more information, please refer to the documentation on link:#jetty-sessions-architecture[Jetty Session Architecture.]
====== Default ===== Default Sessions
As with earlier versions of Jetty, if you do not explicitly configure any session modules, the default session infrastructure will be enabled. As with earlier versions of Jetty, if you do not explicitly configure any session modules, the default session infrastructure will be enabled.
In previous versions of Jetty this was referred to as "hash" session management. In previous versions of Jetty this was referred to as "hash" session management.
The new default provides similar features to the old hash session management: The new default provides similar features to the old hash session management:
* a session scavenger thread that runs every 10mins and removes expired sessions
* a session id manager that generates unique session ids and handles session id sharing during context forwarding * A session scavenger thread that runs every 10mins and removes expired sessions
* an in-memory cache of session objects. * A session id manager that generates unique session ids and handles session id sharing during context forwarding
* An in-memory cache of session objects.
Requests for the same session in the same context share the same session object. Requests for the same session in the same context share the same session object.
Session objects remain in the cache until they expire or are explicitly invalidated. Session objects remain in the cache until they expire or are explicitly invalidated.
If you wish to configure the default setup further, enable the `session-cache-default` module. If you wish to configure the default setup further, enable the `session-cache-default` module.
Compatibility *Compatibility*
As Session objects do not persist beyond a server restart, there are no compatibility issues. As Session objects do not persist beyond a server restart, there are no compatibility issues.
====== Filesystem ===== Sessions using the Filesystem
In earlier versions of Jetty, persisting sessions to the local filesystem was an option of the "hash" session manager. In earlier versions of Jetty, persisting sessions to the local filesystem was an option of the "hash" session manager.
In Jetty 9.4 this has been refactored to its own configurable module `session-store-file`. In Jetty 9.4 this has been refactored to its own configurable module `session-store-file`.
Compatibility *Compatibility*
Sessions stored to files by earlier versions of jetty are not compatible with jetty-9.4 sessions. Sessions stored to files by earlier versions of jetty are not compatible with jetty-9.4 sessions.
Here is a comparison of file formats, note that the file contents are listed in order of file output: Here is a comparison of file formats, note that the file contents are listed in order of file output:
[cols="1,1", options="header"] [cols="1,1", options="header"]
|=== |===
| 9.3 | 9.4 | Jetty 9.3 | Jetty 9.4
| File name: sessionid | File name: expirytime_contextpath_vhost_sessionid | File name: `sessionid` | File name: `expirytime_contextpath_vhost_sessionid`
| sessionid (utf) | sessionid (utf) | `sessionid (utf)` | `sessionid (utf)`
| | contextpath (uft) | | `contextpath (utf)`
| | vhost (utf) | | `vhost (utf)`
| nodeid (utf) | lastnode (utlf) | `nodeid (utf)` | `lastnode (utf)`
| createtime (long) | createtime (long) | `createtime (long)` | `createtime (long)`
| accessed (long) | accessed (long) | `accessed (long)` | `accessed (long)`
| | lastaccessed (long) | | `lastaccessed (long)`
| | cookiesettime (long) | | `cookiesettime (long)`
| | expiry (long) | | `expiry (long)`
| requests (int) | | `requests (int)` |
| | maxInactive (long) | | `maxInactive (long)`
| attributes size (int) | attributes size (int) | `attributes size (int)` | `attributes size (int)`
| attributes serialized (obj) | attributes serialized (obj) | `attributes serialized (obj)` | `attributes serialized (obj)`
| maxInactive (long) | | `maxInactive (long)` |
|=== |===
====== JDBC ===== JDBC Sessions
As with earlier versions of Jetty, sessions may be persisted to a relational database. As with earlier versions of Jetty, sessions may be persisted to a relational database.
Enable the `session-store-jdbc` module. Enable the `session-store-jdbc` module.
Compatibility *Compatibility*
Sessions stored to the database by earlier versions of jetty are not compatible with jetty-9.4 sessions. Sessions stored to the database by earlier versions of jetty are not compatible with jetty-9.4 sessions.
The incompatibility is minor: in jetty-9.4 the `rowid` primary key column is no longer used, and the primary key is a composite of `(sessionid,contextpath,vhost)` columns. The incompatibility is minor: in jetty-9.4 the `rowid` primary key column is no longer used, and the primary key is a composite of `(sessionid,contextpath,vhost)` columns.
====== NoSQL ===== NoSQL Sessions
As with earlier versions of Jetty, sessions may be persisted to a document database. As with earlier versions of Jetty, sessions may be persisted to a document database.
Jetty supports the Mongo document database. Jetty supports the Mongo document database.
Enable the `session-store-mongo` module. Enable the `session-store-mongo` module.
Compatibility *Compatibility*
Sessions stored to mongo by earlier versions of jetty are not compatible with jetty-9.4 sessions. Sessions stored to mongo by earlier versions of jetty are not compatible with jetty-9.4 sessions.
The key for each subdocument that represents the session information for a context is different between jetty-9.3 and 9.4: The key for each subdocument that represents the session information for a context is different between jetty-9.3 and 9.4:
[cols="1,1", options="header"] [cols="1,1", options="header"]
|=== |===
| 9.3 | 9.4 | Jetty 9.3 | Jetty 9.4
|Each context key is: vhost+context+path, where empty vhosts="::" and root context = "*" and / is replaced by _ |Each context key is: vhost+context+path, where empty vhosts="::" and root context = "*" and / is replaced by _
|Each context key is: vhost:contextpath, where empty vhosts="0_0_0_0" and root context = "" and / replaced by _ |Each context key is: vhost:contextpath, where empty vhosts="0_0_0_0" and root context = "" and / replaced by _
| eg "::/contextA" | eg " 0_0_0_0:_contextA" | eg "::/contextA" | eg " 0_0_0_0:_contextA"
|=== |===
====== Infinispan ===== Infinispan Sessions
As with earlier versions of Jetty, sessions may be clustered via Infinispan to either an in-process or remote infinispan instance. As with earlier versions of Jetty, sessions may be clustered via Infinispan to either an in-process or remote infinispan instance.
Enable the `session-store-infinispan` module. Enable the `session-store-infinispan` module.
Compatibility *Compatibility*
Sessions stored in infinispan by jetty-9.3 are incompatible with jetty-9.4. Sessions stored in infinispan by jetty-9.3 are incompatible with jetty-9.4.
In jetty-9.3 the serialized object stored to represent the session data was `org.eclipse.jetty.session.infinispan.SerializableSessionData`. In Jetty 9.3 the serialized object stored to represent the session data was `org.eclipse.jetty.session.infinispan.SerializableSessionData`.
In jetty-9.4 the serialized object is `org.eclipse.jetty.serer.session.SessionData`. In Jetty 9.4 the serialized object is `org.eclipse.jetty.serer.session.SessionData`.
====== GCloud Datastore ===== GCloud Datastore
As with earlier versions of Jetty, sessions may be persisted to Google's GCloud Datastore. As with earlier versions of Jetty, sessions may be persisted to Google's GCloud Datastore.
Enable the `session-store-gcloud` module. Enable the `session-store-gcloud` module.
*Compatibility*
Compatibility Sessions stored into GCloud Datastore by Jetty 9.3 are *incompatible* with Jetty 9.4, although the incompatibility is trivial: the name of the session id entity property has changed:
Sessions stored into gcloud datastore by jetty-9.3 are incompatible with jetty-9.4, although the incompatibility is trivial: the name of the session id entity property has changed:
[cols="1,1", options="header"] [cols="1,1", options="header"]
|=== |===
|9.3 | 9.4 |Jetty 9.3 | Jetty 9.4
|Kind: GCloudSession | Kind: GCloudSession |Kind: `GCloudSession` | Kind: `GCloudSession`
|key: contextpath_vhost_sessionid | key: contextpath_vhost_sessionid |key: `contextpath_vhost_sessionid` | key: `contextpath_vhost_sessionid`
|*"clusterId": sessionId* | *"id" : sessionId* |*"clusterId"*: `sessionId` | *"id"*: `sessionId`
|"contextPath" : contextpath | "contextPath": contextpath |"contextPath" : `contextpath` | "contextPath": `contextpath`
|"vhost" :vhost | "vhost": vhost |"vhost" : `vhost` | "vhost": `vhost`
|"accessed":accesstime | "accessed": accesstime |"accessed": `accesstime` | "accessed": `accesstime`
|"lastAccessed": lastaccesstime | "lastAccessed": lastaccesstime |"lastAccessed": `lastaccesstime` | "lastAccessed": `lastaccesstime`
|"createTime": createtime | "createTime": createtime |"createTime": `createtime` | "createTime": `createtime`
|"cookieSetTime": cookiesettime | "cookieSetTime": cookiesettime |"cookieSetTime": `cookiesettime` | "cookieSetTime": `cookiesettime`
|"lastNode": lastnode | "lastNode": lastnode |"lastNode": `lastnode` | "lastNode": `lastnode`
|"expiry": expiry | "expiry": expiry |"expiry": `expiry` | "expiry": `expiry`
|"maxInactive": maxInactive | "maxInactive": maxInactive |"maxInactive": `maxInactive` | "maxInactive": `maxInactive`
|"attributes": blob | "attributes": blob |"attributes": `blob` | "attributes": `blob`
|=== |===
====== GCloud Datastore with Memcached ===== GCloud Datastore with Memcached
As with earlier versions of Jetty, sessions can be both persisted to Google's GCloud Datastore, and cached into Memcached for faster access. As with earlier versions of Jetty, sessions can be both persisted to Google's GCloud Datastore, and cached into Memcached for faster access.
Enable the `session-store-gcloud` and `session-store-cache` modules. Enable the `session-store-gcloud` and `session-store-cache` modules.
Compatibility *Compatibility*
Sessions stored into memcached by earlier versions of jetty are incompatible with jetty-9.4. Previous versions of jetty stored `org.eclipse.jetty.gcloud.memcached.session.SerializableSessionData` whereas jetty-9.4 stores `org.eclipse.jetty.server.session.SessionData`. Sessions stored into Memcached by earlier versions of jetty are incompatible with Jetty 9.4. Previous versions of jetty stored `org.eclipse.jetty.gcloud.memcached.session.SerializableSessionData` whereas Jetty 9.4 stores `org.eclipse.jetty.server.session.SessionData`.