Merge pull request #838 from WalkerWatch/docupdates/Sessions
Sessions redux rough drafts.
This commit is contained in:
Jesse McConnell
GitHub
commit
c1c5e76c4c
|
|
@ -17,9 +17,21 @@
|
|||
[[session-management]]
|
||||
== Session Management
|
||||
|
||||
include::setting-session-characteristics.adoc[]
|
||||
include::using-persistent-sessions.adoc[]
|
||||
include::session-clustering-jdbc.adoc[]
|
||||
include::session-clustering-mongodb.adoc[]
|
||||
include::session-clustering-infinispan.adoc[]
|
||||
include::session-clustering-gcloud-datastore.adoc[]
|
||||
Sessions are a concept within the Servlet api which allow requests to store and retrieve information across the time a user spends in an application.
|
||||
Choosing the correct session manager implementation is an important consideration for every application as each can fit and perform optimally in different situations.
|
||||
If you need a simple in-memory session manager that can persist to disk then session management using the local file system can be a good place to start.
|
||||
If you need a session manager that can work in a clustered scenario with multiple instances of Jetty, then the JDBC session manager can be an excellent option.
|
||||
Jetty also offers more niche session managers that leverage backends such as MongoDB, Inifinispan, or even Google's Cloud Data Store.
|
||||
|
||||
include::session-hierarchy.adoc[]
|
||||
include::session-configuration-file-system.adoc[]
|
||||
include::session-configuration-jdbc.adoc[]
|
||||
include::session-configuration-mongodb.adoc[]
|
||||
include::session-configuration-infinispan.adoc[]
|
||||
include::session-configuration-gcloud.adoc[]
|
||||
//include::setting-session-characteristics.adoc[]
|
||||
//include::using-persistent-sessions.adoc[]
|
||||
//include::session-clustering-jdbc.adoc[]
|
||||
//include::session-clustering-mongodb.adoc[]
|
||||
//include::session-clustering-infinispan.adoc[]
|
||||
//include::session-clustering-gcloud-datastore.adoc[]
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
|
|
@ -17,12 +17,12 @@
|
|||
[[session-clustering-infinispan]]
|
||||
=== Session Clustering with Infinispan
|
||||
|
||||
Jetty can support session clustering by persisting sessions to http://www.infinispan.org[Infinispan].
|
||||
Jetty can support session clustering by persisting sessions to http://www.infinispan.org[Infinispan].
|
||||
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.
|
||||
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 balancer that supports stickiness.
|
||||
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.
|
||||
The persistent session mechanism works in conjunction with a load balancer that supports stickiness.
|
||||
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.
|
||||
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
|
||||
|
|
@ -38,9 +38,9 @@ These managers also cooperate and collaborate with the `org.eclipse.jetty.server
|
|||
|
||||
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].
|
||||
|
||||
As part of the module installation, the necessary Infinispan jars will be dynamically downloaded and installed to your `${jetty.base}/lib/infinispan` directory.
|
||||
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.
|
||||
Once you've done that, you will need to prevent Jetty's startup checks from detecting the missing jars.
|
||||
As part of the module installation, the necessary Infinispan jars will be dynamically downloaded and installed to your `${jetty.base}/lib/infinispan` directory.
|
||||
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.
|
||||
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 `start.d/infinispan.ini` file or appended to your `start.ini`, depending on how you enabled the module:
|
||||
|
|
@ -51,7 +51,7 @@ jetty.infinispanSession.workerName=node1
|
|||
....
|
||||
|
||||
jetty.infinispanSession.workerName::
|
||||
The name that uniquely identifies this node in the cluster.
|
||||
The name that uniquely identifies this node in the cluster.
|
||||
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 which you enable Infinispan session clustering.
|
||||
|
||||
|
|
@ -59,8 +59,8 @@ These properties are applied to the `InfinispanSessionIdManager` described below
|
|||
|
||||
===== Configuring the InfinispanSessionIdManager
|
||||
|
||||
The Infinispan module will have installed file called `$\{jetty.home}/etc/jetty-infinispan.xml`.
|
||||
This file configures an instance of the `InfinispanSessionIdManager` that will be shared across all webapps deployed on that server.
|
||||
The Infinispan module will have installed file called `$\{jetty.home}/etc/jetty-infinispan.xml`.
|
||||
This file configures an instance of the `InfinispanSessionIdManager` that will be shared across all webapps deployed on that server.
|
||||
It looks like this:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
|
|
@ -68,23 +68,23 @@ It looks like this:
|
|||
include::{SRCDIR}/jetty-infinispan/src/main/config/etc/jetty-infinispan.xml[]
|
||||
----
|
||||
|
||||
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.
|
||||
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).
|
||||
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.
|
||||
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).
|
||||
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:
|
||||
|
||||
idleExpiryMultiple::
|
||||
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.
|
||||
This should be sufficient to ensure that a session id that is in-use by a session is never accidentally removed.
|
||||
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.
|
||||
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
|
||||
|
||||
As mentioned elsewhere, there should be one `InfinispanSessionManager` per context (e.g. webapp).
|
||||
As mentioned elsewhere, there should be one `InfinispanSessionManager` per context (e.g. webapp).
|
||||
It will need to reference the single `InfinispanSessionIdManager` configured previously for the Server.
|
||||
|
||||
The way you configure a `InfinispanSessionManager` depends on whether you're configuring from a context xml file, a `jetty-web.xml` file or code.
|
||||
The way you configure a `InfinispanSessionManager` depends on whether you're configuring from a context xml file, 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.
|
||||
|
||||
From a context xml file, you reference the Server instance as a Ref:
|
||||
|
|
@ -96,7 +96,7 @@ From a context xml file, you reference the Server instance as a Ref:
|
|||
<Arg>-org.eclipse.jetty.session.infinispan.</Arg>
|
||||
</Call>
|
||||
|
||||
|
||||
|
||||
<!-- Get a reference to the InfinispanSessionIdManager -->
|
||||
<Ref id="Server">
|
||||
<Call id="idMgr" name="getSessionIdManager"/>
|
||||
|
|
@ -167,18 +167,18 @@ From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance direc
|
|||
The InfinispanSessionManager can be provided by calling setters:
|
||||
|
||||
scavengeInterval::
|
||||
Time in seconds between runs of a scavenger task that looks for expired old sessions to delete.
|
||||
Time in seconds between runs of a scavenger task that looks for expired old sessions to delete.
|
||||
The default is 10 minutes.
|
||||
staleIntervalSec::
|
||||
The length of time a session can be in memory without being checked against the cluster.
|
||||
The length of time a session can be in memory without being checked against the cluster.
|
||||
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.
|
||||
|
||||
===== Using HotRod
|
||||
|
||||
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.
|
||||
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.
|
||||
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 `${jetty.base}/resources/hotrod-client.properties`.
|
||||
Then, create the file `${jetty.base}/resources/hotrod-client.properties`.
|
||||
Add the following line to this file:
|
||||
|
||||
....
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[configuring-sessions-file-system]]
|
||||
|
||||
=== Configuring Session Management using the File System
|
||||
|
||||
When using the Jetty distribution, you will first need to enable the `session-store-file` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
$ java -jar ../start.jar --add-to-start=session-store-file
|
||||
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO : sessions initialised (transitively) in ${jetty.base}/start.d/sessions.ini
|
||||
INFO : session-store-file initialised in ${jetty.base}/start.d/session-store-file.ini
|
||||
MKDIR: ${jetty.base}/sessions
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
//TODO - Callout default Session file location - note it is configurable
|
||||
Doing this enables the File System Session module and any dependent modules or files needed for it to run on the server.
|
||||
The example above is running an fresh `{$jetty.base}` with nothing enabled.
|
||||
When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-file` module as well as the `sessions` and `server` modules, which are required for the File System session management to operate.
|
||||
Additionally a `${jetty.base}/sessions` directory was created.
|
||||
By default Session files will be saved to this directory.
|
||||
|
||||
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
|
||||
|
||||
Opening the `start.d/session-store-file.ini` will show a list of all the configurable options for the file system session module:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
# ---------------------------------------
|
||||
# Module: session-store-file
|
||||
# Enables session persistent storage in files.
|
||||
# ---------------------------------------
|
||||
--module=session-store-file
|
||||
|
||||
jetty.session.storeDir=${jetty.base}/sessions
|
||||
#jetty.session.deleteUnrestorableFiles=false
|
||||
----
|
||||
|
||||
jetty.session.storeDir::
|
||||
This defines the location for storage of Session files.
|
||||
jetty.session.deleteUnrestorableFiles::
|
||||
Boolean.
|
||||
If set to true, unreadable files will be deleted: this is useful to prevent repeated logging of the same error when the scavenger periodically (re-) attempts to load the corrupted information for a session in order to expire it.
|
||||
|
|
@ -0,0 +1,140 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[configuring-sessions-gcloud]]
|
||||
|
||||
=== Configuring Google Cloud DataStore
|
||||
|
||||
When using the Jetty distribution, you will first need to enable the `session-store-gcloud` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
|
||||
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
$ java -jar ../start.jar --add-to-start=session-store-gcloud
|
||||
|
||||
ALERT: There are enabled module(s) with licenses.
|
||||
The following 1 module(s):
|
||||
+ contains software not provided by the Eclipse Foundation!
|
||||
+ contains software not covered by the Eclipse Public License!
|
||||
+ has not been audited for compliance with its license
|
||||
|
||||
Module: session-store-gcloud
|
||||
+ GCloudDatastore is an open source project hosted on Github and released under the Apache 2.0 license.
|
||||
+ https://github.com/GoogleCloudPlatform/gcloud-java
|
||||
+ http://www.apache.org/licenses/LICENSE-2.0.html
|
||||
|
||||
Proceed (y/N)? y
|
||||
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO : sessions initialised (transitively) in ${jetty.base}/start.d/sessions.ini
|
||||
INFO : session-store-gcloud initialised in ${jetty.base}/start.d/session-store-gcloud.ini
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/cloud/gcloud-java-datastore/0.2.3/gcloud-java-datastore-0.2.3.jar to ${jetty.base}/lib/gcloud/gcloud-java-datastore-0.2.3.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/cloud/gcloud-java-core/0.2.3/gcloud-java-core-0.2.3.jar to ${jetty.base}/lib/gcloud/gcloud-java-core-0.2.3.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/auth/google-auth-library-credentials/0.3.1/google-auth-library-credentials-0.3.1.jar to ${jetty.base}/lib/gcloud/google-auth-library-credentials-0.3.1.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/auth/google-auth-library-oauth2-http/0.3.1/google-auth-library-oauth2-http-0.3.1.jar to ${jetty.base}/lib/gcloud/google-auth-library-oauth2-http-0.3.1.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/http-client/google-http-client-jackson2/1.19.0/google-http-client-jackson2-1.19.0.jar to ${jetty.base}/lib/gcloud/google-http-client-jackson2-1.19.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/fasterxml/jackson/core/jackson-core/2.1.3/jackson-core-2.1.3.jar to ${jetty.base}/lib/gcloud/jackson-core-2.1.3.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/http-client/google-http-client/1.21.0/google-http-client-1.21.0.jar to ${jetty.base}/lib/gcloud/google-http-client-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/code/findbugs/jsr305/1.3.9/jsr305-1.3.9.jar to ${jetty.base}/lib/gcloud/jsr305-1.3.9.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/org/apache/httpcomponents/httpclient/4.0.1/httpclient-4.0.1.jar to ${jetty.base}/lib/gcloud/httpclient-4.0.1.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/org/apache/httpcomponents/httpcore/4.0.1/httpcore-4.0.1.jar to ${jetty.base}/lib/gcloud/httpcore-4.0.1.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/commons-codec/commons-codec/1.3/commons-codec-1.3.jar to ${jetty.base}/lib/gcloud/commons-codec-1.3.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/oauth-client/google-oauth-client/1.21.0/google-oauth-client-1.21.0.jar to ${jetty.base}/lib/gcloud/google-oauth-client-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/guava/guava/19.0/guava-19.0.jar to ${jetty.base}/lib/gcloud/guava-19.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/api-client/google-api-client-appengine/1.21.0/google-api-client-appengine-1.21.0.jar to ${jetty.base}/lib/gcloud/google-api-client-appengine-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/oauth-client/google-oauth-client-appengine/1.21.0/google-oauth-client-appengine-1.21.0.jar to ${jetty.base}/lib/gcloud/google-oauth-client-appengine-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/oauth-client/google-oauth-client-servlet/1.21.0/google-oauth-client-servlet-1.21.0.jar to ${jetty.base}/lib/gcloud/google-oauth-client-servlet-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/http-client/google-http-client-jdo/1.21.0/google-http-client-jdo-1.21.0.jar to ${jetty.base}/lib/gcloud/google-http-client-jdo-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/api-client/google-api-client-servlet/1.21.0/google-api-client-servlet-1.21.0.jar to ${jetty.base}/lib/gcloud/google-api-client-servlet-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/javax/jdo/jdo2-api/2.3-eb/jdo2-api-2.3-eb.jar to ${jetty.base}/lib/gcloud/jdo2-api-2.3-eb.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/javax/transaction/transaction-api/1.1/transaction-api-1.1.jar to ${jetty.base}/lib/gcloud/transaction-api-1.1.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/http-client/google-http-client-appengine/1.21.0/google-http-client-appengine-1.21.0.jar to ${jetty.base}/lib/gcloud/google-http-client-appengine-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/http-client/google-http-client-jackson/1.21.0/google-http-client-jackson-1.21.0.jar to ${jetty.base}/lib/gcloud/google-http-client-jackson-1.21.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/org/codehaus/jackson/jackson-core-asl/1.9.11/jackson-core-asl-1.9.11.jar to ${jetty.base}/lib/gcloud/jackson-core-asl-1.9.11.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/joda-time/joda-time/2.9.2/joda-time-2.9.2.jar to ${jetty.base}/lib/gcloud/joda-time-2.9.2.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/org/json/json/20151123/json-20151123.jar to ${jetty.base}/lib/gcloud/json-20151123.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/cloud/datastore/datastore-v1beta3-protos/1.0.0-beta/datastore-v1beta3-protos-1.0.0-beta.jar to ${jetty.base}/lib/gcloud/datastore-v1beta3-protos-1.0.0-beta.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/protobuf/protobuf-java/3.0.0-beta-1/protobuf-java-3.0.0-beta-1.jar to ${jetty.base}/lib/gcloud/protobuf-java-3.0.0-beta-1.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/cloud/datastore/datastore-v1beta3-proto-client/1.0.0-beta.2/datastore-v1beta3-proto-client-1.0.0-beta.2.jar to ${jetty.base}/lib/gcloud/datastore-v1beta3-proto-client-1.0.0-beta.2.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/http-client/google-http-client-protobuf/1.20.0/google-http-client-protobuf-1.20.0.jar to ${jetty.base}/lib/gcloud/google-http-client-protobuf-1.20.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/api-client/google-api-client/1.20.0/google-api-client-1.20.0.jar to ${jetty.base}/lib/gcloud/google-api-client-1.20.0.jar
|
||||
DOWNLOAD: http://central.maven.org/maven2/com/google/guava/guava-jdk5/13.0/guava-jdk5-13.0.jar to ${jetty.base}/lib/gcloud/guava-jdk5-13.0.jar
|
||||
INFO : Base directory was modified
|
||||
WARN : Module session-store-gcloud requires jcl-impl from one of [jcl, jcl-slf4j]
|
||||
|
||||
WARN : Module session-store-gcloud requires jcl-api from one of [jcl, jcl-slf4j]
|
||||
|
||||
WARN : Unsatisfied module dependencies: session-store-gcloud,session-store-gcloud
|
||||
|
||||
Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
|
||||
java -jar $JETTY_HOME/start.jar --help # for more information
|
||||
----
|
||||
|
||||
Doing this enables the GCloud Session module and any dependent session modules or files needed for it to run on the server.
|
||||
The example above is running an fresh `{$jetty.base}` with nothing enabled.
|
||||
Because the Google Cloud DataStore is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).
|
||||
You will notice, however, that the above output presented a warning: GCloud requires certain Java Commons Logging features to work correctly.
|
||||
As such, you will also need to enable either the `jcl` or `jcl-slf4j` module.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
$ java -jar ../start.jar --add-to-start=jcl
|
||||
|
||||
ALERT: There are enabled module(s) with licenses.
|
||||
The following 1 module(s):
|
||||
+ contains software not provided by the Eclipse Foundation!
|
||||
+ contains software not covered by the Eclipse Public License!
|
||||
+ has not been audited for compliance with its license
|
||||
|
||||
Module: jcl
|
||||
+ Log4j is released under the Apache 2.0 license.
|
||||
+ http://www.apache.org/licenses/LICENSE-2.0.html
|
||||
|
||||
Proceed (y/N)? y
|
||||
INFO : jcl initialised in ${jetty.base}/start.d/jcl.ini
|
||||
DOWNLOAD: http://central.maven.org/maven2/commons-logging/commons-logging/1.1.3/commons-logging-1.1.3.jar to ${jetty.base}/lib/jcl/commons-logging-1.1.3.jar
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
When the `--add-to-start` argument was added to the command line the first time, it enabled the the `session-store-gcloud` module as well as the `sessions` and `server` modules, which are required for GCloud session management to operate; the `jcl` module was added when we ran it the second time.
|
||||
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
|
||||
____
|
||||
|
||||
Opening the `start.d/session-store-gcloud.ini` will show a list of all the configurable options for the Google Cloud DataStore module:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
# ---------------------------------------
|
||||
# Module: session-store-gcloud
|
||||
# Enables GCloudDatastore session management.
|
||||
# ---------------------------------------
|
||||
--module=session-store-gcloud
|
||||
|
||||
|
||||
## GCloudDatastore Session config
|
||||
#jetty.gcloudSession.maxRetries=5
|
||||
#jetty.gcloudSession.backoffMs=1000
|
||||
----
|
||||
|
||||
jetty.gcloudSession.maxRetries::
|
||||
Maxmium number of tries to connect to GCloud DataStore to write sessions.
|
||||
jetty.gcloudSession.backoffMs::
|
||||
Amount of time, in milliseconds, between attempts to connect to the GCloud DataStore to write sessions.
|
||||
|
||||
//TODO - Add index.yaml properties?
|
||||
|
|
@ -0,0 +1,113 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[configuring-sessions-infinispan]]
|
||||
|
||||
=== Configuring Remote Inifinspan Clustering
|
||||
|
||||
When using the Jetty distribution, you will first need to enable the `session-store-infinispan-remote` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
$ java -jar ../start.jar --add-to-start=session-store-infinispan-remote
|
||||
|
||||
ALERT: There are enabled module(s) with licenses.
|
||||
The following 1 module(s):
|
||||
+ contains software not provided by the Eclipse Foundation!
|
||||
+ contains software not covered by the Eclipse Public License!
|
||||
+ has not been audited for compliance with its license
|
||||
|
||||
Module: session-store-infinispan-remote
|
||||
+ Infinispan is an open source project hosted on Github and released under the Apache 2.0 license.
|
||||
+ http://infinispan.org/
|
||||
+ http://www.apache.org/licenses/LICENSE-2.0.html
|
||||
|
||||
Proceed (y/N)? y
|
||||
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO : sessions initialised (transitively) in ${jetty.base}/start.d/sessions.ini
|
||||
INFO : session-store-infinispan-remote initialised in ${jetty.base}/start.d/session-store-infinispan-remote.ini
|
||||
DOWNLOAD: https://raw.githubusercontent.com/eclipse/jetty.project/master/jetty-infinispan/src/main/infinispan-resources/hotrod-client.properties?id=master to ${jetty.base}/resources/hotrod-client.properties
|
||||
DOWNLOAD: http://central.maven.org/maven2/org/infinispan/infinispan-remote/7.1.1.Final/infinispan-remote-7.1.1.Final.jar to ${jetty.base}/lib/infinispan/infinispan-remote-7.1.1.Final.jar
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
Doing this enables the remote Infinispan Session module and any dependent modules or files needed for it to run on the server.
|
||||
The example above is running an fresh `{$jetty.base}` with nothing enabled.
|
||||
Because Infinispan is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).
|
||||
When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-infinispan-remote` module as well as the `sessions` and `server` modules, which are required for Infinispan session management to operate.
|
||||
It also downloaded the needed Infinispan-specific jar files and created a directory named `${jetty.base}/lib/infinispan/` to house them.
|
||||
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
|
||||
____
|
||||
|
||||
Opening the `start.d/session-store-infinispan-remote.ini` will show a list of all the configurable options for the JDBC module:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
# ---------------------------------------
|
||||
# Module: session-store-infinispan-remote
|
||||
# Enables session data store in a remote Infinispan cache
|
||||
# ---------------------------------------
|
||||
--module=session-store-infinispan-remote
|
||||
|
||||
#jetty.session.remoteInfinispanCache.name=sessions
|
||||
#jetty.session.infinispanIdleTimeout.seconds=0
|
||||
#jetty.session.gracePeriod.seconds=3600
|
||||
----
|
||||
|
||||
jetty.session.remoteInfinispanCache.name::
|
||||
jetty.session.infinispanIdleTimeout.seconds::
|
||||
jetty.session.gracePeriod.seconds::
|
||||
Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.
|
||||
|
||||
|
||||
=== Configuring Embedded Inifinspan Clustering
|
||||
|
||||
During testing, it can be helpful to run an in-process instance of Infinispan.
|
||||
To enable this you will first need to enable the `session-store-infinispan-embedded` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
java -jar ../start.jar --add-to-start=session-store-infinispan-embedded
|
||||
|
||||
ALERT: There are enabled module(s) with licenses.
|
||||
The following 1 module(s):
|
||||
+ contains software not provided by the Eclipse Foundation!
|
||||
+ contains software not covered by the Eclipse Public License!
|
||||
+ has not been audited for compliance with its license
|
||||
|
||||
Module: session-store-infinispan-embedded
|
||||
+ Infinispan is an open source project hosted on Github and released under the Apache 2.0 license.
|
||||
+ http://infinispan.org/
|
||||
+ http://www.apache.org/licenses/LICENSE-2.0.html
|
||||
|
||||
Proceed (y/N)? y
|
||||
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO : sessions initialised (transitively) in ${jetty.base}/start.d/sessions.ini
|
||||
INFO : session-store-infinispan-embedded initialised in ${jetty.base}/start.d/session-store-infinispan-embedded.ini
|
||||
DOWNLOAD: http://central.maven.org/maven2/org/infinispan/infinispan-embedded/7.1.1.Final/infinispan-embedded-7.1.1.Final.jar to ${jetty.base}/lib/infinispan/infinispan-embedded-7.1.1.Final.jar
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
Doing this enables the embedded Infinispan Session module and any dependent modules or files needed for it to run on the server.
|
||||
The example above is running an fresh `{$jetty.base}` with nothing enabled.
|
||||
Because Infinispan is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).
|
||||
When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-infinispan-embedded` module as well as the `sessions` and `server` modules, which are required for Infinispan session management to operate.
|
||||
It also downloaded the needed Infinispan-specific jar files and created a directory named `${jetty.base}/lib/infinispan/` to house them.
|
||||
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[configuring-sessions-jdbc]]
|
||||
|
||||
=== Configuring JDBC Clustering
|
||||
|
||||
When using the Jetty distribution, you will first need to enable the `session-store-jdbc` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
$ java -jar ../start.jar --add-to-start=session-store-jdbc
|
||||
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO : sessions initialised (transitively) in ${jetty.base}/start.d/sessions.ini
|
||||
INFO : session-store-jdbc initialised in ${jetty.base}/start.d/session-store-jdbc.ini
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
Doing this enables the JDBC Session module and any dependent modules or files needed for it to run on the server.
|
||||
The example above is running an fresh `{$jetty.base}` with nothing enabled.
|
||||
When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-jdbc` module as well as the `sessions` and `server` modules, which are required for JDBC session management to operate.
|
||||
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
|
||||
|
||||
Opening the `start.d/session-store-jdbc.ini` will show a list of all the configurable options for the JDBC module:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
# ---------------------------------------
|
||||
# Module: session-store-jdbc
|
||||
# Enables JDBC peristent/distributed session storage.
|
||||
# ---------------------------------------
|
||||
--module=session-store-jdbc
|
||||
|
||||
##
|
||||
##JDBC Session properties
|
||||
##
|
||||
|
||||
#jetty.session.gracePeriod.seconds=3600
|
||||
|
||||
## Connection type:Datasource
|
||||
db-connection-type=datasource
|
||||
#jetty.session.datasourceName=/jdbc/sessions
|
||||
|
||||
## Connection type:driver
|
||||
#db-connection-type=driver
|
||||
#jetty.session.driverClass=
|
||||
#jetty.session.driverUrl=
|
||||
|
||||
## Session table schema
|
||||
#jetty.sessionTableSchema.accessTimeColumn=accessTime
|
||||
#jetty.sessionTableSchema.contextPathColumn=contextPath
|
||||
#jetty.sessionTableSchema.cookieTimeColumn=cookieTime
|
||||
#jetty.sessionTableSchema.createTimeColumn=createTime
|
||||
#jetty.sessionTableSchema.expiryTimeColumn=expiryTime
|
||||
#jetty.sessionTableSchema.lastAccessTimeColumn=lastAccessTime
|
||||
#jetty.sessionTableSchema.lastSavedTimeColumn=lastSavedTime
|
||||
#jetty.sessionTableSchema.idColumn=sessionId
|
||||
#jetty.sessionTableSchema.lastNodeColumn=lastNode
|
||||
#jetty.sessionTableSchema.virtualHostColumn=virtualHost
|
||||
#jetty.sessionTableSchema.maxIntervalColumn=maxInterval
|
||||
#jetty.sessionTableSchema.mapColumn=map
|
||||
#jetty.sessionTableSchema.table=JettySessions
|
||||
----
|
||||
|
||||
jetty.session.gracePeriod.seconds::
|
||||
Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.
|
||||
|
||||
db-connection-type::
|
||||
jetty.session.datasourceName::
|
||||
|
||||
db-connection-type::
|
||||
jetty.session.driverClass::
|
||||
jetty.session.driverUrl::
|
||||
|
||||
jetty.sessionTableSchema.accessTimeColumn::
|
||||
jetty.sessionTableSchema.contextPathColumn::
|
||||
jetty.sessionTableSchema.cookieTimeColumn::
|
||||
jetty.sessionTableSchema.createTimeColumn::
|
||||
jetty.sessionTableSchema.expiryTimeColumn::
|
||||
jetty.sessionTableSchema.lastAccessTimeColumn::
|
||||
jetty.sessionTableSchema.lastSavedTimeColumn::
|
||||
jetty.sessionTableSchema.idColumn::
|
||||
jetty.sessionTableSchema.lastNodeColumn::
|
||||
jetty.sessionTableSchema.virtualHostColumn::
|
||||
jetty.sessionTableSchema.maxIntervalColumn::
|
||||
jetty.sessionTableSchema.mapColumn::
|
||||
jetty.sessionTableSchema.table::
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[configuring-sessions-mongo]]
|
||||
|
||||
=== Configuring MongoDB Clustering
|
||||
|
||||
When using the Jetty distribution, you will first need to enable the `session-store-mongo` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
$ java -jar ../start.jar --add-to-start=session-store-mongo
|
||||
|
||||
ALERT: There are enabled module(s) with licenses.
|
||||
The following 1 module(s):
|
||||
+ contains software not provided by the Eclipse Foundation!
|
||||
+ contains software not covered by the Eclipse Public License!
|
||||
+ has not been audited for compliance with its license
|
||||
|
||||
Module: session-store-mongo
|
||||
+ The java driver for the MongoDB document-based database system is hosted on GitHub and released under the Apache 2.0 license.
|
||||
+ http://www.mongodb.org/
|
||||
+ http://www.apache.org/licenses/LICENSE-2.0.html
|
||||
|
||||
Proceed (y/N)? y
|
||||
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO : sessions initialised (transitively) in ${jetty.base}/start.d/sessions.ini
|
||||
INFO : session-store-mongo initialised in ${jetty.base}/start.d/session-store-mongo.ini
|
||||
DOWNLOAD: http://central.maven.org/maven2/org/mongodb/mongo-java-driver/2.6.1/mongo-java-driver-2.6.1.jar to ${jetty.base}/lib/nosql/mongo-java-driver-2.6.1.jar
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
Doing this enables the MongoDB Session module and any dependent modules or files needed for it to run on the server.
|
||||
The example above is running an fresh `{$jetty.base}` with nothing enabled.
|
||||
Because MongoDB is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).
|
||||
When the `--add-to-start` argument was added to the command line, it enabled the the `session-store-mongo` module as well as the `sessions` and `server` modules, which are required for MongoDB session management to operate..
|
||||
It also downloaded the needed Mongo-specific jar file and created a directory named `${jetty.base}/lib/nosql/` to house it.
|
||||
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `start.d` directory of the `{$jetty.base}`.
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
|
||||
____
|
||||
|
||||
Opening the `start.d/session-store-mongo.ini` will show a list of all the configurable options for the MongoDB module:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
# ---------------------------------------
|
||||
# Module: session-store-mongo
|
||||
# Enables NoSql session management with a MongoDB driver.
|
||||
# ---------------------------------------
|
||||
--module=session-store-mongo
|
||||
|
||||
#jetty.session.dbName=HttpSessions
|
||||
#jetty.session.collectionName=jettySessions
|
||||
#jetty.session.gracePeriod.seconds=3600
|
||||
----
|
||||
|
||||
jetty.session.dbName::
|
||||
Name of the database in Mongo used to store the Session collection.
|
||||
jetty.session.collectionName::
|
||||
Name of the collection in Mongo used to keep all of the Sessions.
|
||||
jetty.session.gracePeriod.seconds::
|
||||
Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
// ========================================================================
|
||||
// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
|
||||
// ========================================================================
|
||||
// All rights reserved. This program and the accompanying materials
|
||||
// are made available under the terms of the Eclipse Public License v1.0
|
||||
// and Apache License v2.0 which accompanies this distribution.
|
||||
//
|
||||
// The Eclipse Public License is available at
|
||||
// http://www.eclipse.org/legal/epl-v10.html
|
||||
//
|
||||
// The Apache License v2.0 is available at
|
||||
// http://www.opensource.org/licenses/apache2.0.php
|
||||
//
|
||||
// You may elect to redistribute this code under either of these licenses.
|
||||
// ========================================================================
|
||||
|
||||
[[jetty-sessions-architecture]]
|
||||
=== Session Architecture
|
||||
|
||||
==== Changes in Session Architecture
|
||||
The architecture of Session Management Jetty changed significantly in Jetty 9.4.
|
||||
These changes have resulted in Sessions not only being easier to configure but making them much more pluggable for various technologies.
|
||||
|
||||
In previous versions of Jetty, users were required to configure a separate `SessionIdManager` for each kind of session clustering technology being implemented (JDBC, MongoDB..etc.).
|
||||
In Jetty 9.4, there is now a single `SessionIdManager` implementation which works across all types of session clustering technologies.
|
||||
Likewise, prior to Jetty 9.4 there were several different instances of the `SessionManager` class.
|
||||
Instead of a single `SessionManager` though, it has been done away with entirely, with most of it's functionality moved to the `SesssionHandler` class.
|
||||
Additionally, Jetty 9.4 introduced the concepts of a `SessionCache` and an associated `SessionDataStore` (both explained below).
|
||||
|
||||
Finally, Session scavenging has been re-worked.
|
||||
Where previously each `SessionManager` instance would periodically scan the in-memory (or clustered) sessions for expired sessions, there is now a single generic scavenger thread which instructs the `SessionHandler` to clean up expired sessions.
|
||||
Session expiration has been changed to use a much more efficient timer-based mechanism that avoids constant iteration over all current sessions in memory by the scavenger.
|
||||
|
||||
==== Session Architecture Hierarchy
|
||||
|
||||
Each Jetty instance has a singular `SessionIdManager` to handle all session requests, regardless of clustering technology.
|
||||
For each context on the server there is one (1) `SessionCache` which contains all of the Session objects for the given context.
|
||||
The benefit of the `SessionCache` is to ensure that simultaneous requests accessing the same Session Id in the same context always operate on the same Session object.
|
||||
The SessionCache implementation supplied with the Jetty distribution does just that: keeps Session objects in memory so that they can be shared between simultaneous requests.
|
||||
However, it is possible to provide your own implementation that never shares Session objects should you require it.
|
||||
|
||||
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`.
|
||||
|
||||
Visually the Session Hierarchy can be represented like this:
|
||||
|
||||
image::images/SessionsHierarchy.png[]
|
||||
|
||||
==== Configuring Sessions in the Jetty Distribution
|
||||
|
||||
Jetty provides support for several different Session Management/Clustering technologies including JDBC, MongoDB, Inifinispan, Google Cloud Datastore and one for local file storage.
|
||||
Setting up these technologies is as easy as enabling it's link:#startup-modules[module] and editing it's associated ini file with any usernames, passwords or changes you need to make for your instance.
|
||||
The following sections will cover how exactly to enable the required modules as well as an overview of what options are available for customization.
|
||||
Loading…
Reference in New Issue