Merge remote-tracking branch 'origin/jetty-10.0.x' into jetty-11.0.x

jetty-documentation/pom.xml

@@ -165,9 +165,9 @@
             <SRCDIR>${basedir}/..</SRCDIR>
             <GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/master</GITBROWSEURL>
             <GITDOCURL>https://github.com/eclipse/jetty.project/tree/jetty-10.0.x-doc-refactor/jetty-documentation/src/main/asciidoc</GITDOCURL>
-            <DISTGUIDE>../distribution-guide/index.html</DISTGUIDE>
-            <EMBEDGUIDE>../embedded-guide/index.html</EMBEDGUIDE>
-            <QUICKGUIDE>../quickstart-guide/index.html</QUICKGUIDE>
+            <OPGUIDE>../operation-guide/index.html</OPGUIDE>
+            <PROGGUIDE>../programming-guide/index.html</PROGGUIDE>
+            <GSTARTGUIDE>../gettingstarted-guide/index.html</GSTARTGUIDE>
             <CONTRIBGUIDE>../contribution-guide/index.html</CONTRIBGUIDE>
             <MVNCENTRAL>http://central.maven.org/maven2</MVNCENTRAL>
             <VERSION>${project.version}</VERSION>
@@ -176,7 +176,7 @@
         </configuration>
         <executions>
           <execution>
-            <id>quickstart-guide</id>
+            <id>gettingstarted-guide</id>
             <phase>generate-resources</phase>
             <goals>
               <goal>process-asciidoc</goal>
@@ -184,13 +184,13 @@
             <configuration>
               <backend>html5</backend>
               <templateDir>${web.resources.directory}/asciidoc/slim-template</templateDir>
-              <sourceDirectory>${basedir}/src/main/asciidoc/quickstart-guide</sourceDirectory>
+              <sourceDirectory>${basedir}/src/main/asciidoc/gettingstarted-guide</sourceDirectory>
               <sourceDocumentName>index.adoc</sourceDocumentName>
-              <outputDirectory>${project.build.directory}/html/quickstart-guide</outputDirectory>
+              <outputDirectory>${project.build.directory}/html/gettingstarted-guide</outputDirectory>
             </configuration>
           </execution>
           <execution>
-            <id>distribution-guide</id>
+            <id>operation-guide</id>
             <phase>generate-resources</phase>
             <goals>
               <goal>process-asciidoc</goal>
@@ -198,9 +198,9 @@
             <configuration>
               <backend>html5</backend>
               <templateDir>${web.resources.directory}/asciidoc/slim-template</templateDir>
-              <sourceDirectory>${basedir}/src/main/asciidoc/distribution-guide</sourceDirectory>
+              <sourceDirectory>${basedir}/src/main/asciidoc/operation-guide</sourceDirectory>
               <sourceDocumentName>index.adoc</sourceDocumentName>
-              <outputDirectory>${project.build.directory}/html/distribution-guide</outputDirectory>
+              <outputDirectory>${project.build.directory}/html/operation-guide</outputDirectory>
             </configuration>
           </execution>
           <execution>
@@ -219,7 +219,7 @@
             </configuration>
           </execution>
           <execution>
-            <id>embedded-guide</id>
+            <id>programming-guide</id>
             <phase>prepare-package</phase>
             <goals>
               <goal>process-asciidoc</goal>
@@ -227,9 +227,9 @@
             <configuration>
               <backend>html5</backend>
               <templateDir>${web.resources.directory}/asciidoc/slim-template</templateDir>
-              <sourceDirectory>${basedir}/src/main/asciidoc/embedded-guide</sourceDirectory>
+              <sourceDirectory>${basedir}/src/main/asciidoc/programming-guide</sourceDirectory>
               <sourceDocumentName>index.adoc</sourceDocumentName>
-              <outputDirectory>${project.build.directory}/html/embedded-guide</outputDirectory>
+              <outputDirectory>${project.build.directory}/html/programming-guide</outputDirectory>
               <sourceHighlighter>coderay</sourceHighlighter>
               <requires>
                 <require>asciidoctor-diagram</require>

jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/architecture/basic-architecture.adoc

@@ -1,178 +0,0 @@
-//
-// ========================================================================
-// 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
-// ========================================================================
-//
-
-[[basic-architecture]]
-=== Jetty Architecture
-
-==== View from 20,000 feet
-
-The Jetty link:{JDURL}/org/eclipse/jetty/server/Server.html[Server] is the plumbing between
-a collection of `Connector`s that accept connections and a collection of `Handler`s that
-service requests from the connections and produce responses, with threads from a thread pool doing the work.
-
-image:jetty-high-level-architecture.png[image,width=576]
-
-While the Jetty request/responses are derived from the Servlet API, the full features of the Servlet API
-are only available if you configure the appropriate handlers.
-For example, the session API on the request is inactive unless the request has been passed to a `SessionHandler`.
-The concept of a Servlet itself is implemented by a `ServletHandler`.
-If Servlets are not required, there is very little overhead in the use of the servlet request/response APIs.
-Thus you can build a Jetty server using only connectors and handlers, without using Servlets.
-
-The job of configuring Jetty is building a tree of connectors and handlers and providing their individual configurations.
-As Jetty components are simply Plain Old Java Objects (POJOs), you can accomplish this assembly
-and configuration of components by a variety of techniques:
-
-* In code, see the examples in the Jetty Source XRef.
-* Using Jetty XML, a dependency injection style in XML format.
-* With your dependency injection framework of choice, Spring or XBean.
-* Using Jetty WebApp and Context Deployers.
-
-==== Patterns
-
-The implementation of Jetty follows some fairly standard patterns.
-Most abstract concepts such as `Connector`s and `Handler`s are captured by interfaces.
-Generic handling for those interfaces is then provided in an abstract implementation
-such as `AbstractConnector` and `AbstractHandler`.
-
-image:basic-architecture-patterns.png[image,width=576]
-
-The JSR77 inspired life cycle of most Jetty components is represented by the `LifeCycle`
-interface and the `AbstractLifeCycle` implementation used as the base of many Jetty components.
-
-==== Connectors
-
-A `Connector` is the component that accepts TCP connections.
-For each accepted TCP connection, the `Connector` asks a `ConnectionFactory` to create
-a `Connection` object that handles the network traffic on that TCP connection, parsing
-and generating bytes for a specific protocol.
-
-A `ServerConnector` can therefore be configured with one or more `ConnectionFactory`.
-
-The simplest case is a single `ConnectionFactory` such as `HttpConnectionFactory`, that
-creates `HttpConnection` objects that parse and generate bytes for the HTTP/1.1 protocol.
-
-A more complex case can be a `ServerConnector` configured with three factories:
-`ProxyConnectionFactory`, `SslConnectionFactory` and `HttpConnectionFactory`.
-Such connector will be able to handle PROXY protocol bytes coming from a load balancer
-such as HAProxy (with the `ProxyConnectionFactory`), then handle TLS bytes (with
-`SslConnectionFactory`) and therefore decrypting/encrypting the bytes from/to a remote
-client, and finally handling HTTP/1.1 bytes (with `HttpConnectionFactory`).
-Each `ConnectionFactory` is asked to create a `Connection` object for each TCP connection;
-the `Connection` objects will be chained together to handle the bytes, each for its
-own protocol.
-Therefore the `ProxyConnection` will handle the PROXY protocol bytes, `SslConnection`
-will handle the encryption/decryption of the bytes, and `HttpConnection` will handle
-the HTTP/1.1 bytes producing a request and response object that will be processed by
-applications.
-
-Advanced usages of Jetty will allow users to write their own `ConnectionFactory` to
-handle custom protocols that are not implemented directly by the Jetty project,
-therefore using Jetty as a generic network server.
-
-==== Handlers
-
-A `Handler` is the component that deals with HTTP requests and responses.
-The core API of a handler is the handle method:
-
-image:basic-architecture-handlers.png[image,width=576]
-
-[source, java, subs="{sub-order}"]
-----
-public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException
-----
-
-Parameters:
-
-* `target` – the target of the request, either a URI or a name.
-* `baseRequest` – the original unwrapped request object.
-* `request` – the request object, either as the `baseRequest` object or a wrapper of `baseRequest`.
-You can use the HttpConnection.getCurrentConnection() method to access the Request object if required.
-* response – the response object, either unwrapped as `Response` or a wrapper of that response.
-You can use the HttpConnection.getCurrentConnection() method to access the `Response` object if required.
-
-An implementation of this method can handle the request, pass the request onto another handler (or servlet)
-or it might modify and/or wrap the request and then pass it on.
-This gives three styles of Handler:
-
-* Coordinating handlers – handlers that route requests to other handlers (`HandlerCollection`, `ContextHandlerCollection`)
-* Filtering handlers – handlers that augment a request and pass it on to other handlers (`HandlerWrapper`, `ContextHandler`, `SessionHandler`)
-* Generating handlers – handlers that produce content (`ResourceHandler` and `ServletHandler`)
-
-===== Nested Handlers and Handlers Called Sequentially
-
-You can combine handlers to handle different aspects of a request by nesting them,
-calling them in sequence, or by combining the two models.
-
-image:basic-architecture-nested-handlers.png[image,width=576]
-
-Handlers called in sequence perform actions that do not depend on the next invocation, nor on the handler order.
-They handle a request and generate the response without interacting with other handlers.
-The main class for this model is `HandlerCollection`.
-
-Nested handlers are called according to a before/invokeNext/after pattern.
-The main class for nested handlers is `HandlerWrapper`.
-Nested handlers are much more common than those called in sequence.
-
-See also xref:writing-custom-handlers[].
-
-===== Servlet Handler
-
-The `ServletHandler` is a `Handler` that generates content by passing the request to any
-configured Servlet Filters and then to a Servlet mapped by a URI pattern.
-
-image:basic-architecture-servlet-handler.png[image,width=576]
-
-A `ServletHandler` is normally deployed within the scope of a `ServletContext`, which is a
-`ContextHandler` that provides convenience methods for mapping URIs to servlets.
-
-Filters and Servlets can also use a `RequestDispatcher` to reroute a request to another context
-or another Servlet in the current context.
-
-[[what-is-a-context]]
-==== Contexts
-
-Contexts are handlers that group other handlers below a particular URI context path or a virtual host.
-Typically a context can have:
-
-* A context path that defines which requests are handled by the context (e.g. `/myapp`)
-* A resource base for static content (a document root)
-* A class loader to obtain classes specific to the context (typically from `/WEB-INF/classes` and `/WEB-INF/lib`)
-* Virtual host names
-
-Contexts implementations include:
-
-* `ContextHandler`
-* `ServletContextHandler`
-* `WebAppContext`
-
-A web application context combines handlers for security, session and servlets in a single unit
-that you can configure with a `web.xml` descriptor.
-
-==== Web Application
-
-A `WebAppContext` is a derivation of `ServletContextHandler` that supports the standardized layout
-of a web application and configuration of session, security, listeners, filter, servlets, and JSP
-via a `web.xml` descriptor normally found in the `/WEB-INF` directory of a web application.
-
-image:basic-architecture-web-application.png[image,width=576]
-
-Essentially `WebAppContext` is a convenience class that assists the construction and configuration
-of other handlers to achieve a standard web application configuration.
-Configuration is actually done by pluggable implementations of the Configuration class and the
-prime among these is `WebXmlConfiguration.`

jetty-documentation/src/main/asciidoc/embedded-guide/old_docs/handlers/writing-custom-handlers.adoc

@@ -1,195 +0,0 @@
-//
-// ========================================================================
-// 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
-// ========================================================================
-//
-
-[[writing-custom-handlers]]
-=== Writing Custom Handlers
-
-The Handler is the Jetty component that deals with received requests.
-
-Many users of Jetty never need to write a Jetty Handler, but instead use the link:{JDURL}/org/eclipse/jetty/servlet/package-summary.html[Servlet API.]
-You can reuse the existing Jetty handlers for context, security, sessions and servlets without the need for extension.
-However, some users might have special requirements or footprint concerns that prohibit the use of the full servlet API.
-For them implementing a Jetty handler is a straight forward way to provide dynamic web content with a minimum of fuss.
-
-See the section on xref:basic-architecture[] to understand more about Handlers vs. Servlets.
-
-[[handler-api]]
-==== The Handler API
-
-The link:{JDURL}/org/eclipse/jetty/server/Handler.html[Handler] interface provides Jetty's core of content generation or manipulation.
-Classes that implement this interface are used to coordinate requests, filter requests and generate content.
-
-The core API of the Handler interface is:
-
-[source, java, subs="{sub-order}"]
-----
-public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response)
-    throws IOException, ServletException
-----
-
-An implementation of this method can handle a request and pass the request onto another handler (or servlet), or it can modify and/or wrap the request before passing it on.
-This gives three styles of handler:
-
-* Coordinating Handlers - Handlers that route requests to other handlers (`HandlerCollection`, `ContextHandlerCollection`)
-* Filtering Handlers - Handlers that augment a request and pass it on to other handlers (`HandlerWrapper`, `ContextHandler`, `SessionHandler`)
-* Generating Handlers - Handlers that produce content (`ResourceHandler` and `ServletHandler`)
-
-[[target]]
-===== The Target
-
-The target of a handler is an identifier for the resource that should handle the passed request.
-This is normally the URI that is parsed from an HTTP Request.
-However, in two key circumstances the target may differ from the URI of the passed request:
-
-* If the request has been dispatched to a named resource, such as a named servlet, the target is the name of that resource.
-* If the request is being made by a call to link:http://docs.oracle.com/javaee/7/api/javax/servlet/RequestDispatcher.html[`RequestDispatcher`], the target is the URI of the included resource and is different to the URI of the actual request.
-
-[[request-and-response]]
-===== The Request and Response
-
-The request and response objects used in the signature of the handle method are
-link:http://docs.oracle.com/javaee/7/api/javax/servlet/ServletRequest.html[`ServletRequest`] and link:http://docs.oracle.com/javaee/7/api/javax/servlet/ServletResponse.html[`ServletResponse`].
-These are the standard APIs and are moderately restricted in what they can do to the request and response.
-More often than not, access to the Jetty implementations of these classes is required: link:{JDURL}/org/eclipse/jetty/server/Request.html[`Request`] and link:{JDURL}/org/eclipse/jetty/server/Response.html[`Response`].
-However, as the request and response may be wrapped by handlers, filters and servlets, it is not possible to pass the implementation directly.
-The following mantra retrieves the core implementation objects from under any wrappers:
-
-[source, java, subs="{sub-order}"]
-----
-Request base_request = request instanceof Request ? (Request)request : HttpConnection.getCurrentConnection().getHttpChannel().getRequest();
-Response base_response = response instanceof Response ? (Response)response : HttpConnection.getCurrentConnection().getHttpChannel().getResponse();
-----
-
-Notice that if the handler passes the request on to another handler, it should use the Request/Response objects passed in, and not the base objects.
-This is to preserve any wrapping done by up stream handlers.
-
-[[dispatch]]
-===== The Dispatch
-
-The dispatch argument indicates the state of the handling of the call and may be:
-
-* `REQUEST == 1` - An original request received from a connector.
-* `FORWARD == 2` - A request being forwarded by a RequestDispatcher.
-* `INCLUDE == 4` - A request being included by a RequestDispatcher.
-* `ERROR == 8` - A request being forwarded to a error handler by the container.
-
-These mostly have significance for servlet and related handlers.
-For example, the security handler only applies authentication and authorization to REQUEST dispatches.
-
-[[handling-requests]]
-==== Handling Requests
-
-A Handler may handle a request by:
-
-* xref:generating-response[]
-* xref:filtering-request-or-response[]
-* xref:passing-request-and-response[]
-
-[[generating-response]]
-===== Generating a Response
-
-The link:{JDURL}/org/eclipse/jetty/embedded/OneHandler.html[`OneHandler`] embedded example shows how a simple handler can generate a response.
-
-You can use the standard servlet response API, which will typically set some status, content headers and then write out the content:
-
-[source, java, subs="{sub-order}"]
-----
- response.setContentType("text/html");
- response.setStatus(HttpServletResponse.SC_OK);
- response.getWriter().println("<h1>Hello OneHandler</h1>");
-----
-
-It is also very important that a handler indicate that it has completed handling the request and that the request should not be passed to other handlers:
-
-[source, java, subs="{sub-order}"]
-----
- Request base_request = (request instanceof Request) ? (Request)request:HttpConnection.getCurrentConnection().getHttpChannel().getRequest();
- base_request.setHandled(true);
-----
-
-[[filtering-request-or-response]]
-===== Filtering the Request and/or Response
-
-Once the base request or response object is obtained, you can modify it.
-Typically you would make modifications to accomplish:
-
-* Breaking the URI into contextPath, servletPath and pathInfo components.
-* Associating a resource base with a request for static content.
-* Associating a session with a request.
-* Associating a security principal with a request.
-* Changing the URI and paths during a request dispatch forward to another resource.
-
-You can also update the context of the request:
-
-* Setting the current threads context classloader.
-* Setting thread locals to identify the current `ServletContext`.
-
-Typically Jetty passes a modified request to another handler and undoes modifications in a finally block afterwards:
-
-[source, java, subs="{sub-order}"]
-----
- try
- {
-    base_request.setSession(a_session);
-    next_handler.handle(target,request,response,dispatch);
- }
- finally
- {
-    base_request.setSession(old_session);
- }
-----
-
-The classes that implement the link:{JDURL}/org/eclipse/jetty/server/handler/HandlerWrapper.html[`HandlerWrapper`] class are typically handler filters of this style.
-
-[[passing-request-and-response]]
-===== Passing the Request and Response to Another Handler
-
-A handler might simply inspect the request and use the target, request URI or other information to select another handler to pass the request to.
-These handlers typically implement the link:{JDURL}/org/eclipse/jetty/server/HandlerContainer.html[`HandlerContainer`] interface.
-
-Examples include:
-
-* link:{JDURL}/org/eclipse/jetty/server/handler/HandlerCollection.html[Class `HandlerCollection`] -
-A collection of handlers, where each handler is called regardless of the state of the request.
-This is typically used to pass a request to a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandlerCollection.html[`ContextHandlerCollection`,] and then the link:{JDURL}/org/eclipse/jetty/server/handler/RequestLogHandler.html[`RequestLogHandler`.]
-* link:{JDURL}/org/eclipse/jetty/server/handler/HandlerList.html[`HandlerList`] - A list of handlers that are called in turn until the request state is set as handled.
-* link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandlerCollection.html[`ContextHandlerCollection`] - A collection of Handlers, of which one is selected by best match for the context path.
-
-[[injecting-handlers]]
-==== Injecting Handlers
-
-The `Handler` needs to be added to the server classpath as described in xref:startup-classpath[].
-Then it can be added to the server, either by overriding some existing XML configuration files such as `jetty.xml` as shown below, or by defining a custom module as described in xref:custom-modules[].
-
-[source, xml]
-----
-<?xml version="1.0"?>
-<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
-<Configure id="Server" class="org.eclipse.jetty.server.Server">
-    <Call name="setHandler">
-        <Arg>
-            <New id="myCustomJettyHandler" class="com.my.handler.CustomJettyHandler" />
-        </Arg>
-    </Call>
-</Configure>
-----
-
-[[more-about-handlers]]
-==== More About Handlers
-
-See the link:{JDURL}/[latest Jetty JavaDoc] for detailed information on each Jetty handler.

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

@@ -16,20 +16,20 @@
 // ========================================================================
 //
 
-:doctitle: Eclipse Jetty: Quickstart Guide
+:doctitle: Eclipse Jetty: Getting Started Guide
 :author: Jetty Developers
 :email: jetty-dev@eclipse.org
 :revnumber: 1.0
 :revdate: {TIMESTAMP}
 :toc: left
-:toc-title: Quickstart Guide
+:toc-title: Getting Started Guide
 :toc-style:
 
 :header-style: eclipse-thin
 :breadcrumb-style: eclipse-thin
 :footer-style: default
 
-:breadcrumb: Home:../index.html | Quickstart Guide:./index.html
+:breadcrumb: Home:../index.html | Getting Started Guide:./index.html
 
 // html specific directives
 ifdef::backend-html5[]
@@ -54,4 +54,4 @@ endif::[]
 
 include::introduction/chapter.adoc[]
 include::getting-started/chapter.adoc[]
-include::configuring/chapter.adoc[]
+

jetty-documentation/src/main/asciidoc/gettingstarted-guide/introduction/what-is-jetty.adoc

@@ -23,15 +23,15 @@ Eclipse Jetty is an open-source project providing an HTTP server, HTTP client, a
 
 The Jetty documentation is broken up in to four parts:
 
-* The link:{QUICKGUIDE}[Quick Start Guide] emphasizes beginning to use Jetty.
+* The link:{GSTARTEDGUIDE}[Getting Started Guide] emphasizes beginning to use Jetty.
 It provides information about what Jetty is and where you can download it, and where to find Jetty in repositories like Central Maven.
 It also provides a Quick Start guide on how to get Jetty up and running as well as an overview of how and what to configure in Jetty.
 
-* The link:{DISTGUIDE}[Distribution Guide] details configuring Jetty as a distributed package at a more granular level.
+* The link:{OPGUIDE}[Operation Guide] details configuring Jetty as a distributed package at a more granular level.
 From server startup to session management, logging, HTTP/2 support and Jetty optimization, these chapters will help administrators get the most out of their distributed Jetty server instances.
 This section also covers configuring many of the most common servlet container features such as JNDI and JMX.
 
-* Aimed at advanced users of Jetty, the link:{EMBEDGUIDE}[Embedded Guide] focuses on Jetty development.
+* Aimed at advanced users of Jetty, the link:{PROGGUIDE}[Programming Guide] focuses on Jetty development.
 A large portion of this section is focused on using Jetty as an embedded server in existing applications.
 It contains several examples and how-to guides for making the most out of the Jetty framework.
 This section also includes a guide on using the Jetty Maven plugin as well as information on debugging Jetty.

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

@@ -16,19 +16,19 @@
 // ========================================================================
 //
 
-:doctitle: Eclipse Jetty: Distribution Guide
+:doctitle: Eclipse Jetty: Operation Guide
 :author: Jetty Developers
 :email: jetty-dev@eclipse.org
 :revnumber: 1.0
 :revdate: {TIMESTAMP}
 :toc: left
-:toc-title: Distribution Guide
+:toc-title: Operation Guide
 :toc-style:
 
 :header-style: eclipse-thin
 :breadcrumb-style: eclipse-thin
 :footer-style: default
-:breadcrumb: Home:../index.html | Distribution Guide:./index.html
+:breadcrumb: Home:../index.html | Operation Guide:./index.html
 
 // docinfo lets you pull in shared content and/or influence via render type
 //:docinfodir: {DOCINFODIR}/documentation