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

Chapter 10 clean up and link fixes. 

Signed-off-by: WalkerWatch <ctwalker@gmail.com>
This commit is contained in:
WalkerWatch 2016-06-06 21:20:11 -04:00
parent 58f8d44ae2
commit 1d3816fdc5
6 changed files with 252 additions and 494 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
jetty-documentation/src/main/asciidoc/administration/sessions/session-clustering-gcloud-datastore.adoc
View File

@ -17,144 +17,97 @@
[[session-clustering-gcloud-datastore]] [[session-clustering-gcloud-datastore]]
=== Session Clustering with Google Cloud Datastore === Session Clustering with Google Cloud Datastore
Jetty can support session clustering by persisting sessions to Jetty can support session clustering by persisting sessions to https://cloud.google.com/datastore/docs/concepts/overview[Google Cloud Datastore].
https://cloud.google.com/datastore/docs/concepts/overview[Google Cloud Each Jetty instance locally caches sessions for which it has received requests, writing any changes to the session through to the Datastore as the request exits the server.
Datastore]. Each Jetty instance locally caches sessions for which it has Sessions must obey the Serialization contract, and servlets must call the `Session.setAttribute()` method to ensure that changes are persisted.
received requests, writing any changes to the session through to the
Datastore as the request exits the server. Sessions must obey the
Serialization contract, and servlets must call the
Session.setAttribute() method to ensure that changes are persisted.
The persistent session mechanism works in conjunction with a load The persistent session mechanism works in conjunction with a load balancer that supports stickiness.
balancer that supports stickiness. Stickiness can be based on various Stickiness can be based on various data items, such as source IP address or characteristics of the session ID or a load-balancer specific mechanism.
data items, such as source IP address or characteristics of the session For those load balancers that examine the session ID, the Jetty persistent session mechanism appends a node ID to the session ID, which can be used for routing.
ID or a load-balancer specific mechanism. For those load balancers that
examine the session ID, the Jetty persistent session mechanism appends a
node ID to the session ID, which can be used for routing.
==== Configuration ==== Configuration
There are two components to session management in Jetty: a session ID There are two components to session management in Jetty: a session ID manager and a session manager.
manager and a session manager.
* The session ID manager ensures that session IDs are unique across all * The session ID manager ensures that session IDs are unique across all webapps hosted on a Jetty instance, and thus there can only be one session ID manager per Jetty instance.
webapps hosted on a Jetty instance, and thus there can only be one * The session manager handles the session lifecycle (create/update/invalidate/expire) on behalf of a web application, so there is one session manager per web application instance.
session ID manager per Jetty instance.
* The session manager handles the session lifecycle
(create/update/invalidate/expire) on behalf of a web application, so
there is one session manager per web application instance.
These managers also cooperate and collaborate with the These managers also cooperate and collaborate with the `org.eclipse.jetty.server.session.SessionHandler` to enable cross-context dispatch.
`org.eclipse.jetty.server.session.SessionHandler` to enable
cross-context dispatch.
==== The gcloud-sessions Module ==== The gcloud-sessions Module
When using the jetty distribution, to enable Cloud Datastore session When using the jetty distribution, to enable Cloud Datastore session persistence, you will first need to enable the `gcloud-sessions` link:#startup-modules[module] for your link:#creating-jetty-base[base] using the `--add-to-start` or `--add-to-startd` argument to the link:#startup-overview[start.jar].
persistence, you will first need to enable the `gcloud-sessions`
link:#startup-modules[module] for your link:#creating-jetty-base[base]
using the --add-to-start or --add-to-startd argument to the
link:#startup-overview[start.jar].
As part of the module installation, the necessary jars will be As part of the module installation, the necessary jars will be dynamically downloaded and installed to your `${jetty.base}/lib/gcloud` directory.
dynamically downloaded and installed to your `${jetty.base}/lib/gcloud` If you need to up or downgrade the version of the jars, then you can delete the jars that were automatically installed and replace them.
directory. If you need to up or downgrade the version of the jars, then Once you've done that, you will need to prevent jetty's startup checks from detecting the missing jars.
you can delete the jars that were automatically installed and replace To do that, you can use `--skip-file-validation=glcoud-sessions` argument to start.jar on the command line, or place that line inside `${jetty.base}/start.ini` to ensure it is used for every start.
them. Once you've done that, you will need to prevent jetty's startup
checks from detecting the missing jars. To do that, you can use
`--skip-file-validation=glcoud-sessions` argument to start.jar on the
command line, or place that line inside `${jetty.base}/start.ini` to
ensure it is used for every start.
===== Configuring the GCloudSessionIdManager ===== Configuring the GCloudSessionIdManager
The gcloud-sessions module will have installed file called The gcloud-sessions module will have installed file called `${jetty.home}/etc/jetty-gcloud-sessions.xml`.
`${jetty.home}/etc/jetty-gcloud-sessions.xml`. This file configures an This file configures an instance of the `GCloudSessionIdManager` that will be shared across all webapps deployed on that server. It looks like this:
instance of the GCloudSessionIdManager that will be shared across all
webapps deployed on that server. It looks like this:
[source,xml] [source,xml]
---- ----
include::{SRCDIR}/jetty-gcloud/jetty-gcloud-session-manager/src/main/config/etc/jetty-gcloud-session-store.xml[] include::{SRCDIR}/jetty-gcloud/jetty-gcloud-session-manager/src/main/config/etc/jetty-gcloud-sessions.xml[]
---- ----
You configure it by setting values for properties. The properties will You configure it by setting values for properties.
either be inserted as commented out in your `start.ini`, or your The properties will either be inserted as commented out in your `start.ini`, or your `start.d/gcloud-sessions.ini` file, depending on how you enabled the module.
`start.d/gcloud-sessions.ini` file, depending on how you enabled the
module.
The only property you always need to set is the name of the node in the The only property you always need to set is the name of the node in the cluster:
cluster:
jetty.gcloudSession.workerName:: jetty.gcloudSession.workerName::
The name that uniquely identifies this node in the cluster. This value The name that uniquely identifies this node in the cluster.
will also be used by the sticky load balancer to identify the node. This value will also be used by the sticky load balancer to identify the node.
Don't forget to change the value of this property on *each* node on Don't forget to change the value of this property on *each* node on which you enable gcloud datastore session clustering.
which you enable gcloud datastore session clustering.
Which other properties you need to set depends on the execution Which other properties you need to set depends on the execution environment:
environment:
====== Running Within Google Infrastructure ====== Running Within Google Infrastructure
When you upload your webapp to run in Compute Engine, you do not need to When you upload your webapp to run in Compute Engine, you do not need to set any other properties for Jetty.
set any other properties for jetty. If you follow the instructions in If you follow the instructions in the https://cloud.google.com/datastore/docs/activate[Cloud Datastore documentation], all authorizations...etc. will be provided by the runtime environment.
the https://cloud.google.com/datastore/docs/activate[Cloud Datastore
documentation], all authorizations etc will be provided by the runtime
environment.
====== Running Externally to Google Infrastructure ====== Running Externally to Google Infrastructure
When your app is executing outside of Google, you can either contact a When your app is executing outside of Google, you can either contact a remote Cloud Datastore instance, or a https://cloud.google.com/datastore/docs/tools/devserver[local test dev server] provided by the sdk.
remote Cloud Datastore instance, or a The choice determines which properties you need to set:
https://cloud.google.com/datastore/docs/tools/devserver[local test dev
server] provided by the sdk. The choice determines which properties you
need to set:
Contacting an sdk dev server for testing::: Contacting an sdk dev server for testing:::
In this case, you need to set up either some _System_ properties or In this case, you need to set up either some _System_ properties or _environment variables_ - *NOT* Jetty properties!
_environment variables_ - NOT jetty properties!
+
DATASTORE_DATASET;; DATASTORE_DATASET;;
This must be the name of your (test) project. This must be the name of your (test) project.
DATASTORE_HOST;; DATASTORE_HOST;;
This is the url of the dev server as described at This is the url of the dev server as described https://cloud.google.com/datastore/docs/tools/devserver#setting_environment_variables[in Google's documentation].
https://cloud.google.com/datastore/docs/tools/devserver#setting_environment_variables. An example may be "http://localhost:9999".
An example may be "http://localhost:9999"
Contacting a remote Cloud Datastore::: Contacting a remote Cloud Datastore:::
In this case, you need to provide all of the authentication and In this case, you need to provide all of the authentication and authorization information explicitly via jetty properties in the ini file:
authorization information explicitly via jetty properties in the ini
file:
+
jetty.gcloudSession.projectId;; jetty.gcloudSession.projectId;;
This is the name of your project. This is the name of your project.
jetty.gcloudSession.p12File;; jetty.gcloudSession.p12File;;
This is the location of the p12 key file that is associated with This is the location of the p12 key file that is associated with your project.
your project.
jetty.gcloudSession.serviceAccount;; jetty.gcloudSession.serviceAccount;;
This is the email address that defines your service account for the This is the email address that defines your service account for the Cloud Datastore.
Cloud Datastore.
jetty.gcloudSession.password;; jetty.gcloudSession.password;;
This is the password associated with the p12 key file. This is the password associated with the p12 key file.
===== Configuring the GCloudSessionManager ===== Configuring the GCloudSessionManager
As mentioned elsewhere, there should be one GCloudSessionManager per As mentioned elsewhere, there should be one `GCloudSessionManager` per context (e.g. webapp).
context (ie webapp). It will need to reference the single It will need to reference the single `GCloudSessionIdManager` from which it derives the Cloud Datastore configuration information.
GCloudSessionIdManager from which it derives the Cloud Datastore
configuration information.
The way you configure a GCloudSessionManager depends on whether you're The way you configure a `GCloudSessionManager` depends on whether you're configuring from a context xml file, a `jetty-web.xml` file or code.
configuring from a context xml file or a `jetty-web.xml` file or code. The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.server.Server` instance.
The basic difference is how you get a reference to the Jetty
`org.eclipse.jetty.server.Server` instance.
From a context xml file, you reference the Server instance as a Ref: From a context xml file, you reference the Server instance as a Ref:
[source,xml] [source,xml]
---- ----
<!-- Get a reference to the GCloudSessionIdManager --> <!-- Get a reference to the GCloudSessionIdManager -->
<Ref id="Server"> <Ref id="Server">
<Call id="idMgr" name="getSessionIdManager"/> <Call id="idMgr" name="getSessionIdManager"/>
@ -175,12 +128,10 @@ From a context xml file, you reference the Server instance as a Ref:
</Set> </Set>
---- ----
From a `WEB-INF/jetty-web.xml` file, you can reference the Server From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
instance directly:
[source,xml] [source,xml]
---- ----
<!-- Reference the server directly --> <!-- Reference the server directly -->
<Get name="server"> <Get name="server">
<Get id="idMgr" name="sessionIdManager"/> <Get id="idMgr" name="sessionIdManager"/>
@ -201,19 +152,17 @@ instance directly:
</Set> </Set>
---- ----
The GCloudSessionManager supports the following configuration setters: The `GCloudSessionManager` supports the following configuration setters:
scavengeIntervalSec:: scavengeIntervalSec::
Time in seconds between runs of a scavenger task that looks for Time in seconds between runs of a scavenger task that looks for expired old sessions to delete.
expired old sessions to delete. The default is 10 minutes. If set to The default is 10 minutes.
0, no scavenging is done. If set to 0, no scavenging is done.
staleIntervalSec:: staleIntervalSec::
The length of time a session can be in memory without being checked The length of time a session can be in memory without being checked against the cluster.
against the cluster. A value of 0 indicates that the session is never A value of 0 indicates that the session is never checked against the cluster - the current node is considered to be the master for the session.
checked against the cluster - the current node is considered to be the
master for the session.
maxQueryResults:: maxQueryResults::
The maximum number of results to return for a query to find expired The maximum number of results to return for a query to find expired sessions.
sessions. For efficiency it is important to limit the size of the For efficiency it is important to limit the size of the result.
result. The default is 100. If 0 or negative numbers are set, the The default is 100.
default is used instead. If 0 or negative numbers are set, the default is used instead.

142
jetty-documentation/src/main/asciidoc/administration/sessions/session-clustering-infinispan.adoc
View File

@ -17,58 +17,33 @@
[[session-clustering-infinispan]] [[session-clustering-infinispan]]
=== Session Clustering with Infinispan === Session Clustering with Infinispan
Jetty can support session clustering by persisting sessions to Jetty can support session clustering by persisting sessions to http://www.infinispan.org[Infinispan].
http://www.infinispan.org[Infinispan]. Each Jetty instance locally Each Jetty instance locally caches sessions for which it has received requests, writing any changes to the session through to Infinispan as the request exits the server.
caches sessions for which it has received requests, writing any changes Sessions must obey the Serialization contract, and servlets must call the `Session.setAttribute()` method to ensure that changes are persisted.
to the session through to Infinispan as the request exits the server.
Sessions must obey the Serialization contract, and servlets must call
the Session.setAttribute() method to ensure that changes are persisted.
The persistent session mechanism works in conjunction with a load The persistent session mechanism works in conjunction with a load balancer that supports stickiness.
balancer that supports stickiness. Stickiness can be based on various Stickiness can be based on various data items, such as source IP address or characteristics of the session ID or a load-balancer specific mechanism.
data items, such as source IP address or characteristics of the session For those load balancers that examine the session ID, the Jetty persistent session mechanism appends a node ID to the session ID, which can be used for routing.
ID or a load-balancer specific mechanism. For those load balancers that
examine the session ID, the Jetty persistent session mechanism appends a
node ID to the session ID, which can be used for routing.
==== Configuration ==== Configuration
There are two components to session management in Jetty: a session ID There are two components to session management in Jetty: a session ID manager and a session manager.
manager and a session manager.
* The session ID manager ensures that session IDs are unique across all * The session ID manager ensures that session IDs are unique across all webapps hosted on a Jetty instance, and thus there can only be one session ID manager per Jetty instance.
webapps hosted on a Jetty instance, and thus there can only be one * The session manager handles the session lifecycle (create/update/invalidate/expire) on behalf of a web application, so there is one session manager per web application instance.
session ID manager per Jetty instance.
* The session manager handles the session lifecycle
(create/update/invalidate/expire) on behalf of a web application, so
there is one session manager per web application instance.
These managers also cooperate and collaborate with the These managers also cooperate and collaborate with the `org.eclipse.jetty.server.session.SessionHandler` to enable cross-context dispatch.
`org.eclipse.jetty.server.session.SessionHandler` to enable
cross-context dispatch.
==== The infinispan Module ==== The Infinispan Module
When using the jetty distribution, to enable Infinispan session When using the jetty distribution, to enable Infinispan session persistence, you will first need to enable the Infinispan link:#startup-modules[module] for your link:#creating-jetty-base[base] using the `--add-to-start` or `--add-to-startd` argument to the link:#startup-overview[start.jar].
persistence, you will first need to enable the `infinispan`
link:#startup-modules[module] for your link:#creating-jetty-base[base]
using the --add-to-start or --add-to-startd argument to the
link:#startup-overview[start.jar].
As part of the module installation, the necessary infinispan jars will As part of the module installation, the necessary Infinispan jars will be dynamically downloaded and installed to your `${jetty.base}/lib/infinispan` directory.
be dynamically downloaded and installed to your If you need to up or downgrade the version of the Infinispan jars, then you can delete the jars that were automatically installed and replace them.
`${jetty.base}/lib/infinispan` directory. If you need to up or downgrade Once you've done that, you will need to prevent Jetty's startup checks from detecting the missing jars.
the version of the infinispan jars, then you can delete the jars that To do that, you can use `--skip-file-validation=infinispan` argument to start.jar on the command line, or place that line inside `${jetty.base}/start.ini` to ensure it is used for every start.
were automatically installed and replace them. Once you've done that,
you will need to prevent jetty's startup checks from detecting the
missing jars. To do that, you can use
`--skip-file-validation=infinispan` argument to start.jar on the command
line, or place that line inside `${jetty.base}/start.ini` to ensure it
is used for every start.
You will also find the following properties, either in your base's You will also find the following properties, either in your base's `start.d/infinispan.ini` file or appended to your `start.ini`, depending on how you enabled the module:
`start.d/infinispan.ini` file or appended to your `start.ini`, depending
on how you enabled the module:
.... ....
## Unique identifier for this node in the cluster ## Unique identifier for this node in the cluster
@ -76,61 +51,41 @@ jetty.infinispanSession.workerName=node1
.... ....
jetty.infinispanSession.workerName:: jetty.infinispanSession.workerName::
The name that uniquely identifies this node in the cluster. This value The name that uniquely identifies this node in the cluster.
will also be used by the sticky load balancer to identify the node. This value will also be used by the sticky load balancer to identify the node.
Don't forget to change the value of this property on *each* node on Don't forget to change the value of this property on *each* node on which you enable Infinispan session clustering.
which you enable infinispan session clustering.
These properties are applied to the InfinispanSessionIdManager described These properties are applied to the `InfinispanSessionIdManager` described below.
below.
===== Configuring the InfinispanSessionIdManager ===== Configuring the InfinispanSessionIdManager
The infinispan module will have installed file called The Infinispan module will have installed file called `$\{jetty.home}/etc/jetty-infinispan.xml`.
$\{jetty.home}/etc/jetty-infinispan.xml. This file configures an This file configures an instance of the `InfinispanSessionIdManager` that will be shared across all webapps deployed on that server.
instance of the InfinispanSessionIdManager that will be shared across It looks like this:
all webapps deployed on that server. It looks like this:
[source,xml] [source,xml]
---- ----
include::{SRCDIR}/jetty-infinispan/src/main/config/etc/jetty-default-infinispan-store.xml[] include::{SRCDIR}/jetty-infinispan/src/main/config/etc/jetty-infinispan.xml[]
---- ----
As you can see, you configure the Infinispan As you can see, you configure the Infinispan http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_the_cache_apis[Cache] instance that the `InfinispanSessionIdManager` should use in this file.
http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_the_cache_apis[Cache] By default, the Infinispan http://infinispan.org/docs/7.1.x/getting_started/getting_started.html#_running_infinispan_on_a_single_node[Default cache] instance is used (e.g. on the local node).
instance that the InfinispanSessionIdManager should use in this file. By You can instead use a custom Cache setup - the `jetty-infinispan.xml` file shows you how to configure a remote Cache (using the http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_using_hot_rod_server[hotrod java client]).
default, the infinispan
http://infinispan.org/docs/7.1.x/getting_started/getting_started.html#_running_infinispan_on_a_single_node[Default
cache] instance is used (ie on the local node). You can instead use a
custom Cache setup - the jetty-infinispan.xml file shows you how to
configure a remote Cache (using the
http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_using_hot_rod_server[hotrod
java client]).
The InfinispanSessionIdManager can be configured by calling setters: The `InfinispanSessionIdManager` can be configured by calling setters:
idleExpiryMultiple:: idleExpiryMultiple::
Sessions that are not immortal, ie they have an expiry time, have Sessions that are not immortal, e.g. they have an expiry time, have their ids stored into Infinispan with an http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_expiration[idle expiry timeout] equivalent to double the session's timeout.
their ids stored into Infinispan with an This should be sufficient to ensure that a session id that is in-use by a session is never accidentally removed.
http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_expiration[idle However, should you wish to, you can configure this to any integral value to effectively increase the http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_expiration[idle expiry] timeout.
expiry timeout] equivalent to double the session's timeout. This
should be sufficient to ensure that a session id that is in-use by a
session is never accidentally removed. However, should you wish to,
you can configure this to any integral value to effectively increase
the
http://infinispan.org/docs/7.1.x/user_guide/user_guide.html#_expiration[idle
expiry] timeout.
===== Configuring the InfinispanSessionManager ===== Configuring the InfinispanSessionManager
As mentioned elsewhere, there should be one InfinispanSessionManager per As mentioned elsewhere, there should be one `InfinispanSessionManager` per context (e.g. webapp).
context (ie webapp). It will need to reference the single It will need to reference the single `InfinispanSessionIdManager` configured previously for the Server.
InfinispanSessionIdManager configured previously for the Server.
The way you configure a InfinispanSessionManager depends on whether The way you configure a `InfinispanSessionManager` depends on whether you're configuring from a context xml file, a `jetty-web.xml` file or code.
you're configuring from a context xml file or a `jetty-web.xml` file or The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.server.Server` instance.
code. The basic difference is how you get a reference to the Jetty
`org.eclipse.jetty.server.Server` instance.
From a context xml file, you reference the Server instance as a Ref: From a context xml file, you reference the Server instance as a Ref:
@ -171,8 +126,7 @@ From a context xml file, you reference the Server instance as a Ref:
</Set> </Set>
---- ----
From a `WEB-INF/jetty-web.xml` file, you can reference the Server From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
instance directly:
[source,xml] [source,xml]
---- ----
@ -213,25 +167,19 @@ instance directly:
The InfinispanSessionManager can be provided by calling setters: The InfinispanSessionManager can be provided by calling setters:
scavengeInterval:: scavengeInterval::
Time in seconds between runs of a scavenger task that looks for Time in seconds between runs of a scavenger task that looks for expired old sessions to delete.
expired old sessions to delete. The default is 10 minutes. The default is 10 minutes.
staleIntervalSec:: staleIntervalSec::
The length of time a session can be in memory without being checked The length of time a session can be in memory without being checked against the cluster.
against the cluster. A value of 0 indicates that the session is never A value of 0 indicates that the session is never checked against the cluster - the current node is considered to be the master for the session.
checked against the cluster - the current node is considered to be the
master for the session.
===== Using HotRod ===== Using HotRod
If you're using the hotrod client - where serialization will be required If you're using the hotrod client - where serialization will be required - you will need to ensure that the hotrod marshalling software works with Jetty classloading.
- you will need to ensure that the hotrod marshalling software works To do this, firstly ensure that you have included the lines containing the `prependServerClass` to your context xml file as shown above.
with jetty classloading. To do this, firstly ensure that you have
included the lines containing the `prependServerClass` to your context
xml file as shown above.
Then, create the file Then, create the file `${jetty.base}/resources/hotrod-client.properties`.
`${jetty.base}/resources/hotrod-client.properties`. Add the following Add the following line to this file:
line to this file:
.... ....
infinispan.client.hotrod.marshaller=org.eclipse.jetty.session.infinispan.WebAppMarshaller infinispan.client.hotrod.marshaller=org.eclipse.jetty.session.infinispan.WebAppMarshaller

143
jetty-documentation/src/main/asciidoc/administration/sessions/session-clustering-jdbc.adoc
View File

@ -17,57 +17,35 @@
[[session-clustering-jdbc]] [[session-clustering-jdbc]]
=== Session Clustering with a Database === Session Clustering with a Database
Jetty can support session clustering by persisting sessions to a shared Jetty can support session clustering by persisting sessions to a shared database.
database. Each Jetty instance locally caches sessions for which it has Each Jetty instance locally caches sessions for which it has received requests, writing any changes to the session through to the database as the request exits the server.
received requests, writing any changes to the session through to the Sessions must obey the Serialization contract, and servlets must call the `Session.setAttribute()` method to ensure that changes are persisted.
database as the request exits the server. Sessions must obey the
Serialization contract, and servlets must call the
Session.setAttribute() method to ensure that changes are persisted.
The persistent session mechanism works in conjunction with a load The persistent session mechanism works in conjunction with a load balancer that supports stickiness.
balancer that supports stickiness. Stickiness can be based on various Stickiness can be based on various data items, such as source IP address or characteristics of the session ID or a load-balancer specific mechanism.
data items, such as source IP address or characteristics of the session For those load balancers that examine the session ID, the Jetty persistent session mechanism appends a node ID to the session ID, which can be used for routing.
ID or a load-balancer specific mechanism. For those load balancers that
examine the session ID, the Jetty persistent session mechanism appends a
node ID to the session ID, which can be used for routing.
In this type of solution, the database can become both a bottleneck and In this type of solution, the database can become both a bottleneck and a single point of failure.
a single point of failure. Jetty takes steps to reduce the load on the Jetty takes steps to reduce the load on the database (discussed below), but in a heavily loaded environment you might need to investigate other optimization strategies such as local caching and database replication.
database (discussed below), but in a heavily loaded environment you You should also consult your database vendor's documentation for information on how to ensure high availability and failover of your database.
might need to investigate other optimization strategies such as local
caching and database replication. You should also consult your database
vendor's documentation for information on how to ensure high
availability and failover of your database.
==== Configuration ==== Configuration
There are two components to session management in Jetty: a session ID There are two components to session management in Jetty: a session ID manager and a session manager.
manager and a session manager.
* The session ID manager ensures that session IDs are unique across all * The session ID manager ensures that session IDs are unique across all webapps hosted on a Jetty instance, and thus there can only be one session ID manager per Jetty instance.
webapps hosted on a Jetty instance, and thus there can only be one * The session manager handles the session lifecycle (create/update/invalidate/expire) on behalf of a web application, so there is one session manager per web application instance.
session ID manager per Jetty instance.
* The session manager handles the session lifecycle
(create/update/invalidate/expire) on behalf of a web application, so
there is one session manager per web application instance.
These managers also cooperate and collaborate with the These managers also cooperate and collaborate with the `org.eclipse.jetty.server.session.SessionHandler` to enable cross-context dispatch.
`org.eclipse.jetty.server.session.SessionHandler` to enable
cross-context dispatch.
==== The jdbc-session Module ==== The jdbc-session Module
When using the jetty distribution, to enable jdbc session persistence, When using the jetty distribution, to enable jdbc session persistence, you will first need to enable the jdbc-session link:#startup-modules[module] for your link:#creating-jetty-base[base] using the `--add-to-start` or `--add-to-startd` argument to the link:#startup-overview[start.jar].
you will first need to enable the jdbc-session
link:#startup-modules[module] for your link:#creating-jetty-base[base]
using the --add-to-start or --add-to-startd argument to the
link:#startup-overview[start.jar].
You will also find the following properties, either in your base's You will also find the following properties, either in your base's start.d/jdbc-session.ini file or appended to your start.ini, depending on how you enabled the module:
start.d/jdbc-session.ini file or appended to your start.ini, depending
on how you enabled the module:
.... [source,java]
----
## Unique identifier for this node in the cluster ## Unique identifier for this node in the cluster
jetty.jdbcSession.workerName=node1 jetty.jdbcSession.workerName=node1
@ -75,53 +53,42 @@ jetty.jdbcSession.workerName=node1
#jetty.jdbcSession.datasource=sessions #jetty.jdbcSession.datasource=sessions
jetty.jdbcSession.driverClass=org.apache.derby.jdbc.EmbeddedDriver jetty.jdbcSession.driverClass=org.apache.derby.jdbc.EmbeddedDriver
jetty.jdbcSession.connectionURL=jdbc:derby:sessions;create=true jetty.jdbcSession.connectionURL=jdbc:derby:sessions;create=true
.... ----
jetty.jdbcSession.workerName:: jetty.jdbcSession.workerName::
The name that uniquely identifies this node in the cluster. This value The name that uniquely identifies this node in the cluster.
will also be used by the sticky load balancer to identify the node. This value will also be used by the sticky load balancer to identify the node.
Don't forget to change the value of this property on *each* node on Don't forget to change the value of this property on *each* node on which you enable jdbc session clustering.
which you enable jdbc session clustering.
jetty.jdbcSession.scavenge:: jetty.jdbcSession.scavenge::
The time in seconds between sweeps of a task which scavenges old The time in seconds between sweeps of a task which scavenges old expired sessions.
expired sessions. The default is 10 mins. We don't recommend you The default is 10 minutess.
increase the frequency bcause doing so increases the load on the Increasing the frequency is not recommended as doing so increases the load on the database with very little gain.
database with very little gain.
jetty.jdbcSession.datasource:: jetty.jdbcSession.datasource::
The name of a javax.sql.DataSource that gives access to the database The name of a `javax.sql.DataSource` that gives access to the database that holds the session information.
that holds the session information. You should configure *either* this You should configure *either* this or the jdbc driver information described next.
or the jdbc driver information described next.
jetty.jdbcSession.datasource and jetty.jdbcSession.connectionURL:: jetty.jdbcSession.datasource and jetty.jdbcSession.connectionURL::
This is the name of the jdbc driver class, and a jdbc connection url This is the name of the jdbc driver class, and a jdbc connection url suitable for that driver.
suitable for that driver. You should configure *either* this or the You should configure *either* this or the jdbc datasource name described above.
jdbc datasource name described above.
These properties are applied to the JDBCSessionIdManager described These properties are applied to the `JDBCSessionIdManager` described below.
below.
===== Configuring the JDBCSessionIdManager ===== Configuring the JDBCSessionIdManager
The jdbc-session module will have installed file called The jdbc-session module will have installed file called `$\{jetty.home}/etc/jetty-jdbc-sessions.xml`.
$\{jetty.home}/etc/jetty-jdbc-sessions.xml. This file configures an This file configures an instance of the `JDBCSessionIdManager` that will be shared across all webapps deployed on that server.
instance of the JDBCSessionIdManager that will be shared across all It looks like this:
webapps deployed on that server. It looks like this:
[source,xml] [source,xml]
---- ----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-jdbc-session-store.xml[] include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-jdbc-sessions.xml[]
---- ----
As well as uncommenting and setting up appropriate values for the As well as uncommenting and setting up appropriate values for the properties discussed above, you will also need to edit this file and uncomment *either* the data source or the driver info elements.
properties we discussed above, you will also need to edit this file and
uncomment *either* the datasource or the driver info elements.
As Jetty configuration files are direct mappings of XML to Java, it is As Jetty configuration files are direct mappings of XML to Java, it is straight forward to do this in code:
straightforward to see how to do this in code, but here's an example
anyway:
[source,java] [source,java]
---- ----
Server server = new Server(); Server server = new Server();
... ...
JDBCSessionIdManager idMgr = new JDBCSessionIdManager(server); JDBCSessionIdManager idMgr = new JDBCSessionIdManager(server);
@ -134,19 +101,18 @@ server.setSessionIdManager(idMgr);
====== Configuring the Database Schema ====== Configuring the Database Schema
You may find it necessary to change the names of the tables and columns You may find it necessary to change the names of the tables and columns that the JDBC Session management uses to store the session information.
that the JDBC Session management uses to store the session information.
The defaults used are: The defaults used are:
.Default Values for Session Id Table .Default Values for Session Id Table
[cols=",",] [options="header"]
|=========================== |===========================
|table name |JettySessionIds |table name |JettySessionIds
|columns |id |columns |id
|=========================== |===========================
.Default Values for Session Table .Default Values for Session Table
[cols=",",] [options="header"]
|======================================================================= |=======================================================================
|table name |JettySessions |table name |JettySessions
@ -155,16 +121,11 @@ accessTime, lastAccessTime, createTime, cookieTime, lastSavedTime,
expiryTime, maxInterval, map expiryTime, maxInterval, map
|======================================================================= |=======================================================================
To change these values, use the To change these values, use the link:{JDURL}/org/eclipse/jetty/server/session/SessionIdTableSchema.html[org.eclipse.jetty.server.session.SessionIdTableSchema] and link:{JDURL}/org/eclipse/jetty/server/session/SessionTableSchema.html[org.eclipse.jetty.server.session.SessionTableSchema] classes.
link:{JDURL}/org/eclipse/jetty/server/session/SessionIdTableSchema.html[org.eclipse.jetty.server.session.SessionIdTableSchema] These classes have getter/setter methods for the table name and all columns.
and
link:{JDURL}/org/eclipse/jetty/server/session/SessionTableSchema.html[org.eclipse.jetty.server.session.SessionTableSchema]
classes. These classes have getter/setter methods for the table name and
all columns.
Here's an example of changing the name of JettySessionsId table and its Here's an example of changing the name of `JettySessionsId` table and its single column.
single column. This example will use java code, but as explained above, This example will use java code, but as explained above, you may also do this via a Jetty xml configuration file:
you may also do this via a jetty xml configuration file:
[source,java] [source,java]
---- ----
@ -176,10 +137,8 @@ idTableSchema.setIdColumn("theid");
idManager.setSessionIdTableSchema(idTableSchema); idManager.setSessionIdTableSchema(idTableSchema);
---- ----
In a similar fashion, you can change the names of the table and columns In a similar fashion, you can change the names of the table and columns for the `JettySessions` table.
for the JettySessions table. *Note* that both the SessionIdTableSchema *Note* that both the `SessionIdTableSchema` and the `SessionTableSchema` instances are set on the `JDBCSessionIdManager` class.
and the SessionTableSchema instances are set on the JDBCSessionIdManager
class.
[source,java] [source,java]
---- ----
@ -203,14 +162,11 @@ idManager.setSessionTableSchema(sessionTableSchema);
===== Configuring the JDBCSessionManager ===== Configuring the JDBCSessionManager
As mentioned elsewhere, there should be one JDBCSessionManager per As mentioned elsewhere, there should be one `JDBCSessionManager` per context (e.g. webapp).
context (ie webapp). It will need to reference the single It will need to reference the single `JDBCSessionIdManager` configured previously for the Server.
JDBCSessionIdManager configured previously for the Server.
The way you configure a JDBCSessionManager depends on whether you're The way you configure a `JDBCSessionManager` depends on whether you're configuring from a context xml file, a `jetty-web.xml` file or code.
configuring from a context xml file or a `jetty-web.xml` file or code. The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.server.Server` instance.
The basic difference is how you get a reference to the Jetty
`org.eclipse.jetty.server.Server` instance.
From a context xml file, you reference the Server instance as a Ref: From a context xml file, you reference the Server instance as a Ref:
@ -232,8 +188,7 @@ From a context xml file, you reference the Server instance as a Ref:
</Set> </Set>
---- ----
From a `WEB-INF/jetty-web.xml` file, you can reference the Server From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
instance directly:
[source,xml] [source,xml]
---- ----

186
jetty-documentation/src/main/asciidoc/administration/sessions/session-clustering-mongodb.adoc
View File

@ -17,108 +17,72 @@
[[session-clustering-mongodb]] [[session-clustering-mongodb]]
=== Session Clustering with MongoDB === Session Clustering with MongoDB
Jetty can support session clustering by persisting sessions into Jetty can support session clustering by persisting sessions into http://www.mogodb.org[MongoDB].
http://www.mogodb.org[MongoDB]. Each Jetty instance locally caches Each Jetty instance locally caches sessions for which it has received requests, writing any changes to the session through to the cluster as the request exits the server.
sessions for which it has received requests, writing any changes to the Sessions must obey the Serialization contract, and servlets must call the `Session.setAttribute()` method to ensure that changes are persisted.
session through to the cluster as the request exits the server. Sessions
must obey the Serialization contract, and servlets must call the
Session.setAttribute() method to ensure that changes are persisted.
The session persistence mechanism works in conjunction with a load The session persistence mechanism works in conjunction with a load balancer that supports stickiness.
balancer that supports stickiness. Stickiness can be based on various Stickiness can be based on various data items, such as source IP address or characteristics of the session ID or a load-balancer specific mechanism.
data items, such as source IP address or characteristics of the session For those load balancers that examine the session ID, the Jetty persistent session mechanism appends a node ID to the session ID, which can be used for routing.
ID or a load-balancer specific mechanism. For those load balancers that
examine the session ID, the Jetty persistent session mechanism appends a
node ID to the session ID, which can be used for routing.
In this type of solution, the traffic on the network needs to be In this type of solution, the traffic on the network needs to be carefully watched and tends to be the bottleneck.
carefully watched and tends to be the bottleneck. You are probably You are probably investigating this solution in order to scale to large amount of users and sessions, so careful attention should be paid to your usage scenario.
investigating this solution in order to scale to large amount of users Applications with a heavy write profile to their sessions will consume more network bandwidth than profiles that are predominately read oriented.
and sessions, so careful attention should be paid to your usage We recommend using this session manager with largely read based session scenarios.
scenario. Applications with a heavy write profile to their sessions will
consume more network bandwidth than profiles that are predominately read
oriented. We recommend using this session manager with largely read
based session scenarios.
==== Configuration ==== Configuration
There are two components to session management in Jetty: a session ID There are two components to session management in Jetty: a session ID manager and a session manager.
manager and a session manager.
* The session ID manager ensures that session IDs are unique across all * The session ID manager ensures that session IDs are unique across all webapps hosted on a Jetty instance, and thus there can only be one session ID manager per Jetty instance.
webapps hosted on a Jetty instance, and thus there should only be one * The session manager handles the session lifecycle (create/update/invalidate/expire) on behalf of a web application, so there is one session manager per web application instance.
session ID manager per Jetty instance.
* The session manager handles the session lifecycle
(create/update/invalidate/expire) on behalf of a web application, so
there is one session manager per web application instance.
These managers also cooperate and collaborate with the These managers also cooperate and collaborate with the `org.eclipse.jetty.server.session.SessionHandler` to enable cross-context dispatch.
`org.eclipse.jetty.server.session.SessionHandler` to enable
cross-context dispatch.
==== The nosql Module ==== The nosql Module
When using the jetty distribution, to enable the mongodb session When using the jetty distribution, to enable the MongoDB session persistence mechanism, you will first need to enable the nosql link:#startup-modules[module] for your link:#creating-jetty-base[base] using the `--add-to-start` or `--add-to-startd` argument to the link:#startup-overview[start.jar].
persistence mechanism, you will first need to enable the nosql This module will automatically download the `mongodb-java-driver` and install it to your base's `lib/nosql` directory.
link:#startup-modules[module] for your link:#creating-jetty-base[base]
using the --add-to-start or --add-to-startd argument to the
link:#startup-overview[start.jar]. This module will automatically
download the mongodb-java-driver and install it to your base's lib/nosql
directory.
As part of the module installation, the necessary mongo java driver jars As part of the module installation, the necessary mongo java driver jars will be dynamically downloaded and installed to your `${jetty.base}/lib/nosql` directory.
will be dynamically downloaded and installed to your If you need to up or downgrade the version of these jars, then you can delete the jars that were automatically installed and replace them.
`${jetty.base}/lib/nosql` directory. If you need to up or downgrade the Once you've done that, you will need to prevent Jetty's startup checks from detecting the missing jars.
version of these jars, then you can delete the jars that were To do that, you can use `--skip-file-validation=nosql` argument to start.jar on the command line, or place that line inside `${jetty.base}/start.ini` to ensure it is used for every start.
automatically installed and replace them. Once you've done that, you
will need to prevent jetty's startup checks from detecting the missing
jars. To do that, you can use `--skip-file-validation=nosql` argument to
start.jar on the command line, or place that line inside
`${jetty.base}/start.ini` to ensure it is used for every start.
You will also find the following properties, either in your base's You will also find the following properties, either in your base's `start.d/nosql.ini` file or appended to your `start.ini`, depending on how you enabled the module:
start.d/nosql.ini file or appended to your start.ini, depending on how
you enabled the module:
.... [source,xml]
----
## Unique identifier for this node in the cluster ## Unique identifier for this node in the cluster
jetty.nosqlSession.workerName=node1 jetty.nosqlSession.workerName=node1
## Interval in seconds between scavenging expired sessions ## Interval in seconds between scavenging expired sessions
jetty.nosqlSession.scavenge=1800 jetty.nosqlSession.scavenge=1800
.... ----
The `jetty.nosqlSession.workerName` is the unique name for this jetty The `jetty.nosqlSession.workerName` is the unique name for this Jetty Server instance.
Server instance. It will be used by the sticky load balancer to uniquely It will be used by the sticky load balancer to uniquely identify the node.
identify the node. You should change this value on *each* node to which You should change this value on *each* node to which you install MongoDB session management.
you install mongodb session management.
The `jetty.nosqlSession.scavenge` property defines the time in seconds The `jetty.nosqlSession.scavenge` property defines the time in seconds between runs of the scavenger: the scavenger is a task which runs periodically to clean out sessions that have expired but become stranded in the database for whatever reason.
between runs of the scavengeer: the scavenger is a task which runs
periodically to clean out sessions that have expired but become stranded
in the database for whatever reason.
These properties are substituted into the configuration of the These properties are substituted into the configuration of the `MongoDBSessionIdManager` and `MongoSessionManager`.
MongoDBSessionIdManager and MongoSessionManager.
===== Configuring the MongoSessionIdManager ===== Configuring the MongoSessionIdManager
The nosql module will have installed file called The nosql module will have installed file called `$\{jetty.home}/etc/jetty-nosql.xml`.
$\{jetty.home}/etc/jetty-nosql.xml. This file configures an instance of This file configures an instance of the `MongoSessionIdManager` that will be shared across all webapps deployed on that server.
the MongoSessionIdManager that will be shared across all webapps It looks like this:
deployed on that server. It looks like this:
[source,xml] [source,xml]
---- ----
include::{SRCDIR}/jetty-nosql/src/main/config/etc/jetty-mongo-session-store.xml[] include::{SRCDIR}/jetty-nosql/src/main/config/etc/jetty-nosql.xml[]
---- ----
The MongoSessionIdManager needs access to a mongodb cluster, and the The `MongoSessionIdManager` needs access to a MongoDB cluster, and the `jetty-nosql.xml` file assumes the defaults of localhost and default MongoDB port.
jetty-nosql.xml file assumes the defaults of localhost and default If you need to configure something else, you will need to edit this file.
mongodb port. If you need to configure something else, you will need to Here's an example of a more complex setup to use a remote MongoDB instance:
edit this file. Here's an example of a more complex setup to use a
remote mongodb instance:
[source,xml] [source,xml]
---- ----
@ -162,9 +126,7 @@ remote mongodb instance:
---- ----
As Jetty configuration files are direct mappings of XML to Java, it is As Jetty configuration files are direct mappings of XML to Java, it is straight forward to do this in code:
straightforward to see how to do this in code, but here's an example
anyway:
[source,java] [source,java]
---- ----
@ -178,71 +140,52 @@ anyway:
---- ----
The MongoSessionIdManager has slightly different options than some of The MongoSessionIdManager has slightly different options than some of our more traditional session options.
our more traditional session options. The MongoDBSessionIdManager has The `MongoDBSessionIdManager` has the same scavenge timers which govern the setting of a valid session to invalid after a certain period of inactivity.
the same scavenge timers which govern the setting of a valid session to New to this session id manager is the extra purge setting which governs removal from the MongoDB cluster.
invalid after a certain period of inactivity. New to this session id This can be configured through the 'purge' option. Purge is by default set to true and by default runs daily for each node on the cluster.
manager is the extra purge setting which governs removal from the Also able to be configured is the age in which an invalid session will be retained which is set to 1 day by default.
mongodb cluster. This can be configured through the 'purge' option. This means that invalid sessions will be removed after lingering in the MongoDB instance for a day.
Purge is by default set to true and by default runs daily for each node There is also an option for purging valid sessions that have not been used recently.
on the cluster. Also able to be configured is the age in which an The default time for this is 1 week. You can disable these behaviors by setting purge to false.
invalid session will be retained which is set to 1 day by default. This
means that invalid sessions will be removed after lingering in the
mongodb instance for a day. There is also an option for purging valid
sessions that have not been used recently. The default time for this is
1 week. You can disable these behaviors by setting purge to false.
scavengeDelay:: scavengeDelay::
How long to delay before periodically looking for sessions to How long to delay before periodically looking for sessions to scavenge?
scavenge?
scavengePeriod:: scavengePeriod::
How much time after a scavenge has completed should you wait before How much time after a scavenge has completed should you wait before doing it again?
doing it again?
scavengeBlockSize:: scavengeBlockSize::
Number of session ids to which to limit each scavenge query. If you Number of session ids to which to limit each scavenge query.
have a very large number of sessions in memory then setting this to a If you have a very large number of sessions in memory then setting this to a non 0 value may help speed up scavenging by breaking the scavenge into multiple, queries.
non 0 value may help speed up scavenging by breaking the scavenge into The default is 0, which means that all session ids are considered in a single query.
multiple, queries. The default is 0, which means that all session ids
are considered in a single query.
purge (Boolean):: purge (Boolean)::
Do you want to purge (delete) sessions that are invalid from the Do you want to purge (delete) sessions that are invalid from the session store completely?
session store completely?
purgeDelay:: purgeDelay::
How often do you want to perform this purge operation? How often do you want to perform this purge operation?
purgeInvalidAge:: purgeInvalidAge::
How old should an invalid session be before it is eligible to be How old should an invalid session be before it is eligible to be purged?
purged?
purgeValidAge:: purgeValidAge::
How old should a valid session be before it is eligible to be marked How old should a valid session be before it is eligible to be marked invalid and purged?
invalid and purged? Should this occur at all? Should this occur at all?
purgeLimit:: purgeLimit::
Integer value that represents how many items to return from a purge Integer value that represents how many items to return from a purge query.
query. The default is 0, which is unlimited. If you have a lot of old The default is 0, which is unlimited.
expired orphaned sessions then setting this value may speed up the If you have a lot of old expired orphaned sessions then setting this value may speed up the purge process.
purge process.
preserveOnStop:: preserveOnStop::
Whether or not to retain all sessions when the session manager stops. Whether or not to retain all sessions when the session manager stops.
Default is `true`. Default is `true`.
===== Configuring a MongoSessionManager ===== Configuring a MongoSessionManager
As mentioned elsewhere, there should be one MongoSessionManager per As mentioned elsewhere, there should be one `MongoSessionManager` per context (e.g. webapp).
context (ie webapp). It will need to reference the single It will need to reference the single `MongoSessionIdManager` configured previously for the Server.
MongoSessionIdManager configured previously for the Server.
The way you configure a The way you configure a link:{JDURL}/org/eclipse/jetty/nosql/MongoSessionManager.html[org.eclipse.jetty.nosql.mongodb.MongoSessionManager] depends on whether you're configuring from a link:#deployable-descriptor-file[context xml] file or a link:#jetty-web-xml-config[jetty-web.xml] file or code.
link:{JDURL}/org/eclipse/jetty/nosql/MongoSessionManager.html[org.eclipse.jetty.nosql.mongodb.MongoSessionManager] The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.server.Server` instance.
depends on whether you're configuring from a
link:#deployable-descriptor-file[context xml] file or a
link:#jetty-web-xml-config[jetty-web.xml] file or code. The basic
difference is how you get a reference to the Jetty
`org.eclipse.jetty.server.Server` instance.
From a context xml file, you reference the Server instance as a Ref: From a context xml file, you reference the Server instance as a Ref:
[source,xml] [source,xml]
---- ----
<Ref name="Server" id="Server"> <Ref name="Server" id="Server">
<Call id="mongoIdMgr" name="getSessionIdManager"/> <Call id="mongoIdMgr" name="getSessionIdManager"/>
</Ref> </Ref>
@ -258,15 +201,12 @@ From a context xml file, you reference the Server instance as a Ref:
</Arg> </Arg>
</New> </New>
</Set> </Set>
---- ----
From a `WEB-INF/jetty-web.xml` file, you can reference the Server From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
instance directly:
[source,xml] [source,xml]
---- ----
<Get name="server"> <Get name="server">
<Get id="mongoIdMgr" name="sessionIdManager"/> <Get id="mongoIdMgr" name="sessionIdManager"/>
</Get> </Get>
@ -287,7 +227,6 @@ If you're embedding this in code:
[source,java] [source,java]
---- ----
//assuming you have already set up the MongoSessionIdManager as shown earlier //assuming you have already set up the MongoSessionIdManager as shown earlier
//and have a reference to the Server instance: //and have a reference to the Server instance:
@ -296,5 +235,4 @@ If you're embedding this in code:
MongoSessionManager mongoMgr = new MongoSessionManager(); MongoSessionManager mongoMgr = new MongoSessionManager();
mongoMgr.setSessionIdManager(server.getSessionIdManager()); mongoMgr.setSessionIdManager(server.getSessionIdManager());
wac.setSessionHandler(new SessionHandler(mongoMgr)); wac.setSessionHandler(new SessionHandler(mongoMgr));
---- ----

58
jetty-documentation/src/main/asciidoc/administration/sessions/setting-session-characteristics.adoc
View File

@ -17,9 +17,7 @@
[[setting-session-characteristics]] [[setting-session-characteristics]]
=== Setting Session Characteristics === Setting Session Characteristics
To modify the session characteristics of a web application, you can use To modify the session characteristics of a web application, you can use the following parameters, applying them as in one of the example configurations:
the following parameters, applying them as in one of the example
configurations:
[[using-init-parameters]] [[using-init-parameters]]
==== Using Init Parameters ==== Using Init Parameters
@ -61,14 +59,12 @@ urls with calls to encodeURL(). False by default.
[[applying-init-parameters]] [[applying-init-parameters]]
===== Applying Init Parameters ===== Applying Init Parameters
The following sections provide examples of how to apply the init The following sections provide examples of how to apply the init parameters.
parameters.
[[context-parameter-example]] [[context-parameter-example]]
====== Context Parameter Example ====== Context Parameter Example
You can set these parameters as context parameters in a web You can set these parameters as context parameters in a web application's `WEB-INF/web.xml` file:
application's ` WEB-INF/web.xml` file:
[source,xml] [source,xml]
---- ----
@ -97,8 +93,7 @@ application's ` WEB-INF/web.xml` file:
[[web-application-examples]] [[web-application-examples]]
====== Web Application Examples ====== Web Application Examples
You can configure init parameters on a web application, either in code, You can configure init parameters on a web application, either in code, or in a Jetty context xml file equivalent:
or in a Jetty context xml file equivalent:
[source,xml] [source,xml]
---- ----
@ -125,8 +120,7 @@ or in a Jetty context xml file equivalent:
[[init-parameter-examples]] [[init-parameter-examples]]
====== SessionManager Examples ====== SessionManager Examples
You can configure init parameters directly on a `SessionManager` You can configure init parameters directly on a `SessionManager` instance, either in code or the equivalent in xml:
instance, either in code or the equivalent in xml:
[source,xml] [source,xml]
---- ----
@ -152,24 +146,16 @@ instance, either in code or the equivalent in xml:
==== Using Servlet 3.0 Session Configuration ==== Using Servlet 3.0 Session Configuration
With the advent of http://jcp.org/en/jsr/detail?id=315[Servlet With the advent of http://jcp.org/en/jsr/detail?id=315[Servlet Specification 3.0] there are new APIs for configuring session handling characteristics.
Specification 3.0] there are new APIs for configuring session handling What was achievable before only via Jetty-specific link:#session-init-params[init-parameters] can now be achieved in a container-agnostic manner either in code, or via `web.xml`.
characteristics. What was achievable before only via jetty-specific
link:#session-init-params[init-parameters] can now be achieved in a
container-agostic manner either in code, or via web.xml.
[[session-cookie-configuration]] [[session-cookie-configuration]]
===== SessionCookieConfiguration ===== SessionCookieConfiguration
The The http://docs.oracle.com/javaee/6/api/javax/servlet/SessionCookieConfig.html[javax.servlet.SessionCookieConfig] class can be used to set up session handling characteristics.
http://docs.oracle.com/javaee/6/api/javax/servlet/SessionCookieConfig.html[javax.servlet.SessionCookieConfig] For full details, consult the http://docs.oracle.com/javaee/6/api/javax/servlet/SessionCookieConfig.html[javadoc].
class can be used to set up session handling characteristics. For full
details, consult the
http://docs.oracle.com/javaee/6/api/javax/servlet/SessionCookieConfig.html[javadoc].
Here's an example of how you use it: this is a ServletContextListener Below is an example of this implementation: a `ServletContextListener` retrieves the `SessionCookieConfig` and sets up some new values when the context is being initialized:
that retrieves the SessionCookieConfig and sets up some new values for
it when the context is being initialized:
[source,java] [source,java]
---- ----
@ -209,9 +195,7 @@ public class TestListener implements ServletContextListener
} }
---- ----
You can also use web.xml to configure the session handling You can also use `web.xml` to configure the session handling characteristics instead: here's an example doing exactly the same as above instead of using code:
characteristics instead: here's an example, doing exactly the same as we
did above in code:
[source,xml] [source,xml]
---- ----
@ -240,14 +224,9 @@ did above in code:
[[session-tracking-modes]] [[session-tracking-modes]]
===== SessionTrackingModes ===== SessionTrackingModes
In addition to the configuration of In addition to the configuration of link:#session-cookie-configuration[session cookies], since Servlet 3.0 you can also use the http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html[javax.servlet.SessionTrackingMode] to configure session tracking.
link:#session-cookie-configuration[session cookies], since Servlet 3.0
you can also use the
http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html[javax.servlet.SessionTrackingMode]
to configure session tracking.
To determine what are the _default_ session tracking characteristics To determine what are the _default_ session tracking characteristics used by the container, call:
used by the container, call:
[source,java] [source,java]
---- ----
@ -260,13 +239,12 @@ _default_ session tracking modes for Jetty are:
* http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html#COOKIE[SessionTrackingMode.COOKIE] * http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html#COOKIE[SessionTrackingMode.COOKIE]
* http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html#URL[SessionTrackingMode.URL] * http://docs.oracle.com/javaee/6/api/javax/servlet/SessionTrackingMode.html#URL[SessionTrackingMode.URL]
To see which session tracking modes are actually in effect for this To see which session tracking modes are actually in effect for this Context, the following call returns a `java.util.Set` of `javax.servlet.SessionTrackingMode`:
Context, the following call returns a java.util.Set of
javax.servlet.SessionTrackingMode:
.... [source,java]
----
javax.servlet.SessionContext.getEffectiveSessionTrackingModes(); javax.servlet.SessionContext.getEffectiveSessionTrackingModes();
.... ----
To change the session tracking modes, call: To change the session tracking modes, call:
@ -275,7 +253,7 @@ To change the session tracking modes, call:
javax.servlet.SessionContext.setSessionTrackingModes(Set<SessionTrackingMode>); javax.servlet.SessionContext.setSessionTrackingModes(Set<SessionTrackingMode>);
---- ----
You may also set the tracking mode in web.xml, eg: You may also set the tracking mode in `web.xml`, e.g.:
[source,xml] [source,xml]
---- ----

52
jetty-documentation/src/main/asciidoc/administration/sessions/using-persistent-sessions.adoc
View File

@ -17,21 +17,17 @@
[[using-persistent-sessions]] [[using-persistent-sessions]]
=== Using Persistent Sessions === Using Persistent Sessions
It is sometimes useful to preserve existing Sessions across restarts of It is sometimes useful to preserve existing Sessions across restarts of Jetty.
Jetty. The The link:{JDURL}/org/eclipse/jetty/server/session/HashSessionManager.html[`HashSessionManager`] supports this feature.
link:{JDURL}/org/eclipse/jetty/server/session/HashSessionManager.html[`HashSessionManager`] If you enable persistence, the `HashSessionManager` saves all existing, valid Sessions to disk before shutdown completes.
supports this feature. If you enable persistence, the On restart, Jetty restores the saved Sessions.
`HashSessionManager` saves all existing, valid Sessions to disk before
shutdown completes. On restart, Jetty restores the saved Sessions.
[[enabling-persistence]] [[enabling-persistence]]
==== Enabling Persistence ==== Enabling Persistence
A SessionManager does just what its name suggests–it manages the A `SessionManager` does just what its name suggests – it manages the lifecycle and state of sessions on behalf of a webapp.
lifecycle and state of sessions on behalf of a webapp. Each webapp must Each webapp must have its own unique `SessionManager` instance.
have its own unique SessionManager instance. Enabling persistence is as Enabling persistence is as simple as configuring the `HashSessionManager` as the `SessionManager` for a webapp and telling it where on disk to store the sessions:
simple as configuring the `HashSessionManager` as the SessionManager for
a webapp and telling it where on disk to store the sessions:
[source,xml] [source,xml]
---- ----
@ -57,30 +53,25 @@ a webapp and telling it where on disk to store the sessions:
---- ----
____ The above uses an example of a xref:intro-jetty-configuration-contexts[context configuration file].
[TIP]
If you want to persist the sessions from multiple webapps:
1. Configure a separate HashSessionManager for each.
2. Assign to each a different value for 'storeDirectory'.
____
The above example uses a configuration file suitable for the [TIP]
link:{JDURL}/org/eclipse/jetty/deploy/providers/ContextProvider.html[ContextProvider], ====
thus you might want to check out xref:using-context-provider[]. If you want to persist the sessions from multiple webapps:
1. Configure a separate `HashSessionManager` for each.
2. Assign to each a different value for `storeDirectory`.
====
[[delaying-session-load]] [[delaying-session-load]]
==== Delaying Session Load ==== Delaying Session Load
You might need to ensure that the sessions are loaded AFTER the servlet You might need to ensure that the sessions are loaded AFTER the servlet environment starts up (by default, Jetty eagerly loads sessions as part of the container startup, but before it initializes the servlet environment).
environment starts up (by default, Jetty eagerly loads sessions as part For example, the Wicket web framework requires the servlet environment to be available when sessions are activated.
of the container startup, but before it initializes the servlet
environment). For example, the Wicket web framework requires the servlet
environment to be available when sessions are activated.
Using `SessionManager.setLazyLoad(true)`, Jetty loads sessions lazily Using `SessionManager.setLazyLoad(true)`, Jetty loads sessions lazily either when it receives the first request for a session, or the session scavenger runs for the first time, whichever happens first.
either when it receives the first request for a session, or the session Here's how the configuration looks in XML:
scavenger runs for the first time, whichever happens first. Here's how
the configuration looks in XML:
[source,xml] [source,xml]
---- ----
@ -98,8 +89,7 @@ the configuration looks in XML:
[[enabling-persistence-for-jetty-maven-plugin]] [[enabling-persistence-for-jetty-maven-plugin]]
==== Enabling Persistence for the Jetty Maven Plugin ==== Enabling Persistence for the Jetty Maven Plugin
To enable session persistence for the Jetty Maven plugin, set up the To enable session persistence for the Jetty Maven plugin, set up the `HashSessionManager` in the configuration section like so:
HashSessionManager in the configuration section like so:
[source,xml] [source,xml]
---- ----