Merged branch 'jetty-10.0.x-more_docs' into 'jetty-10.0.x'.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>

documentation/jetty-documentation/src/main/asciidoc/config.adoc

@@ -17,7 +17,7 @@
 :revdate: {localdate}
 
 :toc: left
-:toclevels: 4
+:toclevels: 5
 
 :idseparator: -
 :sectlinks:

documentation/jetty-documentation/src/main/asciidoc/operations-guide/index-docinfo.html

@@ -0,0 +1,2 @@
+<link rel="stylesheet" href="../toc.css">
+<script src="../toc.js"></script>

documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc

@@ -15,6 +15,7 @@
 :toc-title: Operations Guide
 :breadcrumb: Home:../index.html | Operations Guide:./index.html
 :idprefix: og-
+:docinfo: private-head
 
 include::../config.adoc[]
 include::.asciidoctorconfig[]

documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc

@@ -136,7 +136,11 @@ Jetty supports ALPN and encrypted HTTP/2 with this configuration:
 include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=tlsALPNHTTP]
 ----
 
-Note how the ``ConnectionFactory``s passed to `ServerConnector` are in order: TLS, ALPN, HTTP/1.1, HTTP/2.
+Note how the ``ConnectionFactory``s passed to `ServerConnector` are in order: TLS, ALPN, HTTP/2, HTTP/1.1.
 
 Jetty starts parsing TLS bytes so that it can obtain the ALPN extension.
 With the ALPN extension information, Jetty can negotiate a protocol and pick, among the ``ConnectionFactory``s supported by the `ServerConnector`, the `ConnectionFactory` correspondent to the negotiated protocol.
+
+The fact that the HTTP/2 protocol comes before the HTTP/1.1 protocol indicates that HTTP/2 is the preferred protocol for the server.
+
+Note also that the default protocol set in the ALPN ``ConnectionFactory``, which is used in case ALPN is not supported by the client, is HTTP/1.1 -- if the client does not support ALPN is probably an old client so HTTP/1.1 is the safest choice.

documentation/jetty-documentation/src/main/asciidoc/toc.css

@@ -0,0 +1,26 @@
+/*
+ * ========================================================================
+ * Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ * ========================================================================
+ */
+
+.hidden {
+    display: none;
+}
+.toc-current {
+    font-weight: bold;
+}
+.toc-item {
+    padding-right: 0.4em;
+}
+.toc-toggle {
+    padding-right: 0.4em;
+    cursor: pointer;
+}

documentation/jetty-documentation/src/main/asciidoc/toc.js

@@ -0,0 +1,121 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+document.addEventListener('DOMContentLoaded', () => dynamicTOC());
+
+function dynamicTOC() {
+    // Bind a click listener to all section titles.
+    const content = document.getElementById('content');
+    const sectionTitles = content.querySelectorAll('a.link');
+    for (const sectionTitle of sectionTitles) {
+        sectionTitle.addEventListener('click', event => collapseThenExpand(event.target.hash));
+    }
+
+    // Bind a click listener to all TOC titles.
+    const toc = document.getElementById('toc');
+    const tocTitles = toc.querySelectorAll('a');
+    for (const tocTitle of tocTitles) {
+        tocTitle.addEventListener('click', event => collapseThenExpand(event.target.hash));
+    }
+
+    // Add the icons to TOC nodes.
+    const nodes = toc.querySelectorAll('li');
+    for (const node of nodes) {
+        const span = document.createElement('span');
+        const css = span.classList;
+        if (node.querySelector(':scope > ul')) {
+            css.add('toc-toggle');
+            // Font-Awesome classes.
+            css.add('fa');
+            css.add('fa-caret-right');
+            span.addEventListener('click', event => toggle(event.target));
+        } else {
+            css.add('toc-item');
+            // The "icon" is the • HTML entity.
+            span.appendChild(document.createTextNode('•'));
+        }
+        node.prepend(span);
+    }
+
+    collapseThenExpand(document.location.hash);
+}
+
+function collapseThenExpand(hash) {
+    const toc = document.getElementById('toc');
+    if (hash) {
+        const current = toc.querySelector('a.toc-current');
+        if (current) {
+            current.classList.remove('toc-current');
+        }
+        const anchor = toc.querySelector('a[href="' + hash + '"');
+        if (anchor) {
+            anchor.classList.add('toc-current');
+            collapse(toc);
+            expand(anchor.parentNode);
+        }
+    } else {
+        collapse(toc);
+    }
+}
+
+function collapse(node) {
+    const sections = node.querySelectorAll('ul');
+    for (const section of sections) {
+        const css = section.classList;
+        // Always show first levels TOC titles.
+        const alwaysShow = css.contains('sectlevel1') || css.contains('sectlevel2');
+        if (!alwaysShow) {
+            css.add('hidden');
+        }
+    }
+    // Show the collapsed icon.
+    const spans = node.querySelectorAll('span.toc-toggle');
+    for (const span of spans) {
+        const css = span.classList;
+        css.remove('fa-caret-down');
+        css.add('fa-caret-right');
+    }
+}
+
+function expand(node) {
+    const root = document.getElementById('toc').querySelector('ul');
+    // Show the current node and its ancestors.
+    let parent = node;
+    while (parent !== root) {
+        // Show the node.
+        parent.classList.remove('hidden');
+        // Show the expanded icon.
+        const span = parent.querySelector(':scope > span.toc-toggle');
+        if (span) {
+            const css = span.classList;
+            css.remove('fa-caret-right');
+            css.add('fa-caret-down');
+        }
+        parent = parent.parentNode;
+    }
+    // Show the children.
+    const children = node.querySelector(':scope > ul');
+    if (children) {
+        children.classList.remove('hidden');
+    }
+}
+
+function toggle(span) {
+    const css = span.classList;
+    const expanded = css.contains('fa-caret-down');
+    if (expanded) {
+        collapse(span.parentNode);
+    } else {
+        expand(span.parentNode);
+    }
+}

documentation/jetty-documentation/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java

@@ -331,7 +331,7 @@ public class HTTPServerDocs
         SslConnectionFactory tls = new SslConnectionFactory(sslContextFactory, alpn.getProtocol());
 
         // The ServerConnector instance.
-        ServerConnector connector = new ServerConnector(server, tls, alpn, http11, h2);
+        ServerConnector connector = new ServerConnector(server, tls, alpn, h2, http11);
         connector.setPort(8443);
 
         server.addConnector(connector);