Improvements to the Jetty documentation.

Moved the session documentation from old_docs/. Fixed xrefs and links. Fixed heading levels to match the new structure. Signed-off-by: Simone Bordet <[email protected]>
jetty · Sep 23, 2020 · 5a00eba · 5a00eba
1 parent 6c2a44e
commit 5a00eba
Show file tree

Hide file tree

Showing 15 changed files with 272 additions and 257 deletions.
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc
@@ -30,6 +30,7 @@ include::start/chapter.adoc[]
 include::deploy/chapter.adoc[]
 include::protocols/chapter.adoc[]
 include::modules/chapter.adoc[]
+include::sessions/chapter.adoc[]
 
 // TODO: how jetty standalone work what start.jar does, command line options, modules, etc.
 // TODO: this is mostly in old_docs/startup.

diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc
@@ -21,13 +21,15 @@
 
 The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications.
 
-=== Eclipse Jetty Introduction
+=== Introduction
 
 If you are new to Eclipse Jetty, read xref:og-begin[here] to download, install, start and deploy web applications to Jetty.
 
 === Eclipse Jetty Features
 
-If you know Jetty already, jump to a feature:
+If you know Eclipse Jetty already, jump to a feature:
+
+* xref:og-sessions[HTTP Session Caching and Clustering]
 
 TODO
 

diff --git a/...ons-guide/old_docs/sessions/sessions.adoc → ...oc/operations-guide/sessions/chapter.adoc b/...ons-guide/old_docs/sessions/sessions.adoc → ...oc/operations-guide/sessions/chapter.adoc
@@ -16,21 +16,22 @@
 // ========================================================================
 //
 
-[[op-session]]
-== Session Management
+[[og-sessions]]
+=== HTTP Session Management
+http://
 
-Http 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.
+HTTP 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.
 Jetty offers a number of pluggable alternatives for managing and distributing/persisting sessions.
 Choosing the best alternative is an important consideration for every application as is the correct configuration to achieve optimum performance.
 
 include::session-overview.adoc[]
 include::session-base.adoc[]
-include::session-sessioncache.adoc[]
+include::session-cache.adoc[]
 include::session-filesystem.adoc[]
 include::session-jdbc.adoc[]
 include::session-mongodb.adoc[]
 include::session-infinispan.adoc[]
 include::session-hazelcast.adoc[]
 include::session-gcloud.adoc[]
-include::session-memcachedsessiondatastore.adoc[]
+include::session-memcached.adoc[]
 include::session-usecases.adoc[]
diff --git a/...guide/old_docs/sessions/session-base.adoc → ...erations-guide/sessions/session-base.adoc b/...guide/old_docs/sessions/session-base.adoc → ...erations-guide/sessions/session-base.adoc
@@ -16,18 +16,20 @@
 // ========================================================================
 //
 
-[[ops-session-base]]
-=== The Base Session Module
+[[og-session-base]]
+==== The Base Session Module
+
 The `sessions` module is the base module that all other session modules depend upon.
 As such it will be _transitively_ enabled if you enable any of the other session modules: you need to _explicitly_ enable it if you wish to _change_ any settings from their defaults.
 
-Enabling the `sessions` module puts the `$jetty.home/etc/sessions/id-manager.xml` file onto the execution path and generates a `$jetty.base/start.d/sessions.ini` file.
+Enabling the `sessions` module puts the `$JETTY_HOME/etc/sessions/id-manager.xml` file onto the execution path and generates a `$JETTY_BASE/start.d/sessions.ini` file.
 
 The `id-manager.xml` file instantiates a `DefaultSessionIdManager` and `HouseKeeper`.
-The former is used to generate and manage session ids whilst the latter is responsible for periodic xref:ops-session-base-scavenge[scavenging] of expired sessions.
+The former is used to generate and manage session ids whilst the latter is responsible for periodic xref:og-session-base-scavenge[scavenging] of expired sessions.
+
+===== Configuration
 
-==== Configuration
-The `$jetty.base/start.d/sessions.ini` file contains these configuration properties:
+The `$JETTY_BASE/start.d/sessions.ini` file contains these configuration properties:
 
 jetty.sessionIdManager.workerName::
 This uniquely identifies the jetty server instance and is applied to the `SessionIdManager`.
@@ -43,17 +45,17 @@ IMPORTANT: If you have more than one Jetty instance, it is *crucial* that you co
 
 jetty.sessionScavengeInterval.seconds::
 This is the period in _seconds_ between runs of the `HouseKeeper`, responsible for orchestrating the removal of expired sessions.
-By default it will run appproximately every 600 secs (ie 10 mins).
-As a rule of thumb, you should ensure that the xref:ops-session-base-scavenge[scavenge] interval is shorter than the `<session-timeout>` of your sessions to ensure that they are promptly scavenged.
-On the other hand, if you have a backend store configured for your sessions, xref:ops-session-base-scavenge[scavenging] too frequently can increase the load on it.
+By default it will run approximately every 600 secs (ie 10 mins).
+As a rule of thumb, you should ensure that the xref:og-session-base-scavenge[scavenge] interval is shorter than the `<session-timeout>` of your sessions to ensure that they are promptly scavenged.
+On the other hand, if you have a backend store configured for your sessions, xref:og-session-base-scavenge[scavenging] too frequently can increase the load on it.
 
-TIP: Don't forget that the `<session-timeout>` is specified in web.xml in _minutes_ and the value of the `jetty.sessionScavengeInterval.seconds` is in _seconds_.
+CAUTION: Don't forget that the `<session-timeout>` is specified in `web.xml` in _minutes_ and the value of the `jetty.sessionScavengeInterval.seconds` is in _seconds_.
 
-[[ops-session-base-scavenge]]
-==== Session Scavenging
+[[og-session-base-scavenge]]
+===== Session Scavenging
 
 The `HouseKeeper` is responsible for the periodic initiation of session scavenge cycles.
-The `jetty.sessionScavengeInterval.seconds` property in `$jetty.base/start.d/sessions.ini` controls the periodicity of the cycle.
+The `jetty.sessionScavengeInterval.seconds` property in `$JETTY_BASE/start.d/sessions.ini` controls the periodicity of the cycle.
 
 [NOTE]
 ====
@@ -68,7 +70,7 @@ Scavenging occurs for all contexts on a server at every cycle.
 The `HouseKeeper` sequentially asks the `SessionHandler` in each context to find and remove expired sessions.
 The `SessionHandler` works with the `SessionDataStore` to evaluate candidates for expiry held in the `SessionCache`, and also to sweep the persistence mechanism to find expired sessions.
 
-The sweep takes two forms: once per cycle the `SessionDataStore` searches for sessions for it's own context that have expired; infrequently, the `SessionDataStore` will widen the search to expired sessions in all contexts.
+The sweep takes two forms: once per cycle the `SessionDataStore` searches for sessions for its own context that have expired; infrequently, the `SessionDataStore` will widen the search to expired sessions in all contexts.
 The former finds sessions that are no longer in this context's `SessionCache`, and using some heuristics, are unlikely to be in the `SessionCache` of the same context on another node either.
 These sessions will be loaded and fully expired, meaning that `HttpSessionListener.destroy()` will be called for them.
 The latter finds sessions that have not been disposed of by scavenge cycles on any other context/node.

diff --git a/...d_docs/sessions/session-sessioncache.adoc → ...rations-guide/sessions/session-cache.adoc b/...d_docs/sessions/session-sessioncache.adoc → ...rations-guide/sessions/session-cache.adoc
@@ -16,24 +16,24 @@
 // ========================================================================
 //
 
-[[ops-session-sessioncache]]
-=== Modules for Session Caching
+[[og-session-cache]]
+==== Modules for HTTP Session Caching
 
-In this section we will look at the alternatives for the `SessionCache`, ie the L1 cache of in-use session objects.
+In this section we will look at the alternatives for the `SessionCache`, i.e. the L1 cache of in-use session objects.
 Jetty ships with 2 alternatives: an in-memory cache, and a null cache.
 The latter does not actually do any caching of sessions, and can be useful if you either want to minimize your support for sessions, or you are in a clustered deployment without a sticky loadbalancer.
 
-The xref:ops-session-usecases[scenarios] go into more detail on this.
+The xref:og-session-usecases[scenarios] go into more detail on this.
 
-[[ops-session-hash]]
-==== Caching in Memory
+[[og-session-cache-hash]]
+===== Caching in Memory
 
 If you wish to change any of the default configuration values you should enable the `session-cache-hash` xref:startup-modules[module].
 The name `"hash"` harks back to historical Jetty session implementations, whereby sessions were kept in memory using a HashMap.
 
-===== Configuration
+====== Configuration
 
-The `$jetty.base/start.d/session-cache-hash.ini` contains the following configurable properties:
+The `$JETTY_BASE/start.d/session-cache-hash.ini` contains the following configurable properties:
 
 jetty.session.evictionPolicy::
 Integer, default -1.
@@ -81,16 +81,15 @@ jetty.session.invalidateOnShutdown::
 Boolean, default `false`.
 If true, when a context is shutdown, all sessions in the cache are invalidated and deleted both from the cache and from the `SessionDataStore`.
 
-
-[[ops-session-null]]
-==== No Caching
+[[og-session-cache-null]]
+===== No Caching
 
 You may need to use the `session-cache-null` module if your clustering setup does not have a sticky load balancer, or if you want absolutely minimal support for sessions.
 If you enable this module, but you don't enable a module that provides session persistence (ie one of the `session-store-xxx` modules), then sessions will _neither_ be retained in memory _nor_ persisted.
 
-===== Configuration
+====== Configuration
 
-The `$jetty.base/start.d/session-cache-null.ini` contains the following configurable properties:
+The `$JETTY_BASE/start.d/session-cache-null.ini` contains the following configurable properties:
 
 jetty.session.saveOnCreate::
 Boolean, default `false`.

diff --git a/...old_docs/sessions/session-filesystem.adoc → ...ns-guide/sessions/session-filesystem.adoc b/...old_docs/sessions/session-filesystem.adoc → ...ns-guide/sessions/session-filesystem.adoc
@@ -16,20 +16,19 @@
 // ========================================================================
 //
 
-[[ops-session-filesystem]]
+[[og-session-filesystem]]
+==== Modules for Persistent HTTP Sessions: File System
 
-=== Modules for Persistent Sessions: File System
-
-The `session-store-file` module supports persistent storage of session data in a filesystem.
+The `session-store-file` Jetty module supports persistent storage of session data in a filesystem.
 
 IMPORTANT: Persisting sessions to the local file system should *never* be used in a clustered environment.
 
-Enabling this module creates the `$jetty.base/sessions` directory.
+Enabling this module creates the `$JETTY_BASE/sessions` directory.
 By default session data will be saved to this directory, one file representing each session.
 
 File names follow this pattern:
 
-+[expiry]_[contextpath]_[virtualhost]_[id]+
+`+[expiry]_[contextpath]_[virtualhost]_[id]+`
 
 expiry::
 This is the expiry time in milliseconds since the epoch.
@@ -38,35 +37,36 @@ contextpath::
 This is the context path with any special characters, including `/`, replaced by the `_` underscore character.
 For example, a context path of `/catalog` would become `_catalog`.
 A context path of simply `/` becomes just `__`.
+
 virtualhost::
-This is the first virtual host associated with the context and has the form of 4 digits separated by `.` characters.
-If there are no virtual hosts associated with a context, then `0.0.0.0` is used:
+This is the first virtual host associated with the context and has the form of 4 digits separated by `.` characters: `+[digit].[digit].[digit].[digit]+`.
+If there are no virtual hosts associated with a context, then `0.0.0.0` is used.
 
-  [digit].[digit].[digit].[digit]
-
 id::
 This is the unique id of the session.
 
 Putting all of the above together as an example, a session with an id of `node0ek3vx7x2y1e7pmi3z00uqj1k0` for the context with path `/test` with no virtual hosts and an expiry of `1599558193150` would have a file name of:
 
 `1599558193150__test_0.0.0.0_node0ek3vx7x2y1e7pmi3z00uqj1k0`
 
+===== Configuration
 
-==== Configuration
-
-The `$jetty.base/start.d/sessions.ini` file contains the following properties which may be modified to customise filesystem session storage:
+The `$JETTY_BASE/start.d/sessions.ini` file contains the following properties which may be modified to customise filesystem session storage:
 
 jetty.session.storeDir::
-The default is `${jetty.base}/sessions`.
+The default is `$JETTY_BASE/sessions`.
 This is a path that defines the location for storage of session files.
+
 jetty.session.file.deleteUnrestorableFiles::
 Boolean, default `false`.
 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.
+
 jetty.session.gracePeriod.seconds::
 Integer, default 3600.
-Used during session xref:ops-session-base-scavenge[scavenging].
-Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:ops-session-base-scavenge[scavenged].
+Used during session xref:og-session-base-scavenge[scavenging].
+Multiples of this period are used to define how long ago a stored session must have expired before it should be xref:og-session-base-scavenge[scavenged].
+
 jetty.session.savePeriod.seconds::
 Integer, in seconds, default is `0`.
 Whenever a session is accessed by a request, its `lastAccessTime` and `expiry` are updated.
@@ -78,4 +78,4 @@ The value of this property is used to skip writes for these kinds of sessions: t
 ====
 You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its `expiry` time thus making it appear to other nodes that it has expired.
 Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - it would be undesirable to set a `savePeriod` that is larger than the `maxIdleTime`.
-====
+====