Update session docs

Signed-off-by: Jan Bartel <janb@webtide.com>

jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessioncache.adoc

@@ -71,7 +71,8 @@ The `AbstractSessionCache` does not implement this behaviour, a subclass must im
 
 flushOnResponseCommit::
 This forces a "dirty" session to be written to the `SessionDataStore` just before a response is returned to the client, rather than waiting until the request is finished.
-This ensures that subsequent requests to either the same node or a different node see the changed session data.
+A "dirty" session is one whose attributes have changed, or it has been freshly created.
+Using this option ensures that all subsequent requests - either to the same or a different node - will see the latest changes to the session.
 
 Jetty provides two `SessionCache` implementations: the link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionCache.html[DefaultSessionCache] and the link:{JDURL}/org/eclipse/jetty/server/session/NullSessionCache.html[NullSessionCache].
 

jetty-documentation/src/main/asciidoc/programming-guide/server/sessions/session-sessionhandler.adoc

@@ -0,0 +1,68 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[pg-server-session-sessionhandler]]
+==== Session Components: The SessionHandler
+
+Each context can have a single `SessionHandler`.
+The purpose of the `SessionHandler` is to interact with the `Request` and `Response` to create, maintain and propagate sessions
+It also calls the context-level session listeners at appropriate points in the session lifecycle.
+
+The majority of configuration for the `SessionHandler` can be done via `web.xml` `<session-config>` declarations, or the `javax.servlet.SessionCookieConfig` api.
+There are also a few jetty-specific configuration options that we will cover here:
+
+checkingRemoteSessionIdEncoding::
+Boolean, default `false`.
+This controls whether or not the `javax.servlet.http.Response.encodeURL(String)` method will include the session id as a path parameter when the URL is destined for a remote node.
+
+
+setMaxInactiveInterval::
+Integer, seconds.
+This is equivalent to the `<session-config><session-timeout/></session-config>` that can be set in `web.xml`, although take note that that in `web.xml` this is specified in _minutes_ but this method uses _seconds_.
+
+setHttpOnly::
+Boolean, default `false`.
+This is equivalent to using `javax.servlet.SessionCookieConfig.setHttpOnly(boolean)` method, or the `<session-config><cookie-config><http-only/></cookie-config></session-config>` element.
+If `true`, the session cookie will not be exposed to client-side scripting code.
+
+refreshCookieAge::
+Integer, seconds, default is `-1`.
+This controls resetting the session cookie when `SessionCookieConfig.setMaxAge(int)` is non-zero.
+If the amount of time since the session cookie was last set exceeds this time, the session cookie is regenerated to keep the session cookie valid.
+
+sameSite::
+
+secureRequestOnly::
+Boolean, default true.
+
+
+sessionCookie::
+String, default is `JSESSIONID`.
+
+sessionIdPathParameterName::
+String, default is `jsessionid`.
+
+sessionTrackingModes::
+
+usingCookies::
+Boolean, default `true`.
+
+
+
+
+