Backport web server configuration doc changes

Closes gh-13401

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -506,15 +506,17 @@ configure the embedded server. This section answers those questions.
 
 [[howto-use-another-web-server]]
 === Use Another Web Server
-Many Spring Boot starters include default embedded containers. `spring-boot-starter-web`
-includes Tomcat by including `spring-boot-starter-tomcat`, but you can use
-`spring-boot-starter-jetty` or  `spring-boot-starter-undertow` instead.
-`spring-boot-starter-webflux` includes  Reactor Netty by including
-`spring-boot-starter-reactor-netty`, but you can use `spring-boot-starter-tomcat`,
+Many Spring Boot starters include default embedded containers.
+
+* For servlet stack applications, the `spring-boot-starter-web` includes Tomcat by including
+`spring-boot-starter-tomcat`, but you can use `spring-boot-starter-jetty` or
+`spring-boot-starter-undertow` instead.
+* For reactive stack applications, the `spring-boot-starter-webflux` includes  Reactor Netty
+by including `spring-boot-starter-reactor-netty`, but you can use `spring-boot-starter-tomcat`,
 `spring-boot-starter-jetty`, or `spring-boot-starter-undertow` instead.
 
-If you need to use a different HTTP server, you need to exclude the default dependencies
-and include the one you need. Spring Boot provides separate starters for
+When switching to a different HTTP server, you need to exclude the default dependencies
+in addition to including the one you need. Spring Boot provides separate starters for
 HTTP servers to help make this process as easy as possible.
 
 The following Maven example shows how to exclude Tomcat and include Jetty for Spring MVC:
@@ -576,87 +578,6 @@ your `application.properties`, as shown in the following example:
 
 
 
-[[howto-configure-jetty]]
-=== Configure Jetty
-Generally, you can follow the advice from
-"`<<howto-discover-build-in-options-for-external-properties>>`" about
-`@ConfigurationProperties` (`ServerProperties` is the main one here). However, you should
-also look at
-{dc-spring-boot}/web/server/WebServerFactoryCustomizer.html[`WebServerFactoryCustomizer`].
-The Jetty APIs are quite rich, so, once you have access to the
-`JettyServletWebServerFactory`, you can modify it in a number of ways. Alternatively, if
-you need more control and customization, you can add your own
-`JettyServletWebServerFactory`.
-
-
-
-[[howto-add-a-servlet-filter-or-listener]]
-=== Add a Servlet, Filter, or Listener to an Application
-There are two ways to add `Servlet`, `Filter`, `ServletContextListener`, and the other
-listeners supported by the Servlet spec to your application:
-
-* <<howto-add-a-servlet-filter-or-listener-as-spring-bean>>
-* <<howto-add-a-servlet-filter-or-listener-using-scanning>>
-
-
-
-[[howto-add-a-servlet-filter-or-listener-as-spring-bean]]
-==== Add a Servlet, Filter, or Listener by Using a Spring Bean
-To add a `Servlet`, `Filter`, or Servlet `*Listener` by using a Spring bean, you must
-provide a `@Bean` definition for it. Doing so can be very useful when you want to inject
-configuration or dependencies. However, you must be very careful that they do not cause
-eager initialization of too many other beans, because they have to be installed in the
-container very early in the application lifecycle. (For example, it is not a good idea to
-have them depend on your `DataSource` or JPA configuration.) You can work around such
-restrictions by initializing the beans lazily when first used instead of on
-initialization.
-
-In the case of `Filters` and `Servlets`, you can also add mappings and init parameters by
-adding a `FilterRegistrationBean` or a `ServletRegistrationBean` instead of or in
-addition to the underlying component.
-
-[NOTE]
-====
-If no `dispatcherType` is specified on a filter registration, `REQUEST` is used. This
-aligns with the Servlet Specification's default dispatcher type.
-====
-
-Like any other Spring bean, you can define the order of Servlet filter beans; please
-make sure to check the
-"`<<spring-boot-features.adoc#boot-features-embedded-container-servlets-filters-listeners-beans>>`"
-section.
-
-
-
-[[howto-disable-registration-of-a-servlet-or-filter]]
-===== Disable Registration of a Servlet or Filter
-As <<howto-add-a-servlet-filter-or-listener-as-spring-bean,described earlier>>, any
-`Servlet` or `Filter` beans are registered with the servlet container automatically. To
-disable registration of a particular `Filter` or `Servlet` bean, create a registration
-bean for it and mark it as disabled, as shown in the following example:
-
-[source,java,indent=0,subs="verbatim,quotes,attributes"]
-----
-	@Bean
-	public FilterRegistrationBean registration(MyFilter filter) {
-		FilterRegistrationBean registration = new FilterRegistrationBean(filter);
-		registration.setEnabled(false);
-		return registration;
-	}
-----
-
-
-
-[[howto-add-a-servlet-filter-or-listener-using-scanning]]
-==== Add Servlets, Filters, and Listeners by Using Classpath Scanning
-`@WebServlet`, `@WebFilter`, and `@WebListener` annotated classes can be automatically
-registered with an embedded servlet container by annotating a `@Configuration` class
-with `@ServletComponentScan` and specifying the package(s) containing the components
-that you want to register. By default, `@ServletComponentScan` scans from the package
-of the annotated class.
-
-
-
 [[howto-change-the-http-port]]
 === Change the HTTP Port
 In a standalone application, the main HTTP port defaults to `8080` but can be set with
@@ -720,6 +641,32 @@ processed early (before the value is actually available).
 
 
 
+[[how-to-enable-http-response-compression]]
+=== Enable HTTP Response Compression
+HTTP response compression is supported by Jetty, Tomcat, and Undertow. It can be enabled
+in `application.properties`, as follows:
+
+[source,properties,indent=0,subs="verbatim,quotes,attributes"]
+----
+	server.compression.enabled=true
+----
+
+By default, responses must be at least 2048 bytes in length for compression to be
+performed. You can configure this behavior by setting the
+`server.compression.min-response-size` property.
+
+By default, responses are compressed only if their content type is one of the
+following:
+
+* `text/html`
+* `text/xml`
+* `text/plain`
+* `text/css`
+
+You can configure this behavior by setting the `server.compression.mime-types` property.
+
+
+
 [[howto-configure-ssl]]
 === Configure SSL
 SSL can be configured declaratively by setting the various `+server.ssl.*+` properties,
@@ -804,6 +751,143 @@ the version of your choice.
 
 
 
+[[howto-configure-webserver]]
+=== Configure the Web Server
+
+Generally, you should first consider using one of the many available configuration keys
+and customize your web server by adding new entries in your `application.properties` (or
+`application.yml`, or environment, etc. see
+"`<<howto-discover-build-in-options-for-external-properties>>`"). The `server.{asterisk}`
+namespace is quite useful here, and it includes namespaces like `server.tomcat.{asterisk}`,
+`server.jetty.{asterisk}` and others, for server-specific features.
+See the list of <<common-application-properties>>.
+
+The previous sections covered already many common use cases, such as compression, SSL
+or HTTP/2. However, if a configuration key doesn't exist for your use case, you should
+then look at
+{dc-spring-boot}/web/server/WebServerFactoryCustomizer.html[`WebServerFactoryCustomizer`].
+You can declare such a component and get access to the server factory relevant to your
+choice: you should select the variant for the chosen Server (Tomcat, Jetty, Reactor Netty,
+Undertow) and the chosen web stack (Servlet or Reactive).
+
+The example below is for Tomcat with the `spring-boot-starter-web` (Servlet stack):
+
+[source,java,indent=0,subs="verbatim,quotes,attributes"]
+----
+	@Component
+	public class MyTomcatWebServerCustomizer
+			implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
+
+		@Override
+		public void customize(TomcatServletWebServerFactory factory) {
+			// customize the factory here
+		}
+	}
+----
+
+In addition Spring Boot provides:
+
+[[howto-configure-webserver-customizers]]
+[cols="1,2,2", options="header"]
+|===
+| Server | Servlet stack | Reactive stack
+
+| Tomcat
+| `TomcatServletWebServerFactory`
+| `TomcatReactiveWebServerFactory`
+
+| Jetty
+| `JettyServletWebServerFactory`
+| `JettyReactiveWebServerFactory`
+
+| Undertow
+| `UndertowServletWebServerFactory`
+| `UndertowReactiveWebServerFactory`
+
+| Reactor
+| N/A
+| `NettyReactiveWebServerFactory`
+
+|===
+
+Once you've got access to a `WebServerFactory`, you can often add customizers to it to
+configure specific parts, like connectors, server resources, or the server itself - all
+using server-specific APIs.
+
+As a last resort, you can also declare your own `WebServerFactory` component, which will
+override the one provided by Spring Boot. In this case, you can't rely on configuration
+properties in the `server` namespace anymore.
+
+
+
+[[howto-add-a-servlet-filter-or-listener]]
+=== Add a Servlet, Filter, or Listener to a Application
+In a servlet stack application, i.e. with the `spring-boot-starter-web`, there are two
+ways to add `Servlet`, `Filter`, `ServletContextListener`, and the other listeners
+supported by the Servlet API to your application:
+
+* <<howto-add-a-servlet-filter-or-listener-as-spring-bean>>
+* <<howto-add-a-servlet-filter-or-listener-using-scanning>>
+
+
+
+[[howto-add-a-servlet-filter-or-listener-as-spring-bean]]
+==== Add a Servlet, Filter, or Listener by Using a Spring Bean
+To add a `Servlet`, `Filter`, or Servlet `*Listener` by using a Spring bean, you must
+provide a `@Bean` definition for it. Doing so can be very useful when you want to inject
+configuration or dependencies. However, you must be very careful that they do not cause
+eager initialization of too many other beans, because they have to be installed in the
+container very early in the application lifecycle. (For example, it is not a good idea to
+have them depend on your `DataSource` or JPA configuration.) You can work around such
+restrictions by initializing the beans lazily when first used instead of on
+initialization.
+
+In the case of `Filters` and `Servlets`, you can also add mappings and init parameters by
+adding a `FilterRegistrationBean` or a `ServletRegistrationBean` instead of or in
+addition to the underlying component.
+
+[NOTE]
+====
+If no `dispatcherType` is specified on a filter registration, `REQUEST` is used. This
+aligns with the Servlet Specification's default dispatcher type.
+====
+
+Like any other Spring bean, you can define the order of Servlet filter beans; please
+make sure to check the
+"`<<spring-boot-features.adoc#boot-features-embedded-container-servlets-filters-listeners-beans>>`"
+section.
+
+
+
+[[howto-disable-registration-of-a-servlet-or-filter]]
+===== Disable Registration of a Servlet or Filter
+As <<howto-add-a-servlet-filter-or-listener-as-spring-bean,described earlier>>, any
+`Servlet` or `Filter` beans are registered with the servlet container automatically. To
+disable registration of a particular `Filter` or `Servlet` bean, create a registration
+bean for it and mark it as disabled, as shown in the following example:
+
+[source,java,indent=0,subs="verbatim,quotes,attributes"]
+----
+	@Bean
+	public FilterRegistrationBean registration(MyFilter filter) {
+		FilterRegistrationBean registration = new FilterRegistrationBean(filter);
+		registration.setEnabled(false);
+		return registration;
+	}
+----
+
+
+
+[[howto-add-a-servlet-filter-or-listener-using-scanning]]
+==== Add Servlets, Filters, and Listeners by Using Classpath Scanning
+`@WebServlet`, `@WebFilter`, and `@WebListener` annotated classes can be automatically
+registered with an embedded servlet container by annotating a `@Configuration` class
+with `@ServletComponentScan` and specifying the package(s) containing the components
+that you want to register. By default, `@ServletComponentScan` scans from the package
+of the annotated class.
+
+
+
 [[howto-configure-accesslogs]]
 === Configure Access Logging
 Access logs can be configured for Tomcat, Undertow, and Jetty through their respective
@@ -904,19 +988,6 @@ adding a new valve instance in a `TomcatServletWebServerFactory` bean.
 
 
 
-[[howto-configure-tomcat]]
-=== Configure Tomcat
-Generally, you can follow the advice from
-"`<<howto-discover-build-in-options-for-external-properties>>`" about
-`@ConfigurationProperties` (`ServerProperties` is the main one here). However, you should
-also look at `WebServerFactoryCustomizer` and various Tomcat-specific
-`+*Customizers+` that you can add. The Tomcat APIs are quite rich. Consequently, once you
-have access to the `TomcatServletWebServerFactory`, you can modify it in a number of ways.
-Alternatively, if you need more control and customization, you can add your own
-`TomcatServletWebServerFactory`.
-
-
-
 [[howto-enable-multiple-connectors-in-tomcat]]
 === Enable Multiple Connectors with Tomcat
 You can add an `org.apache.catalina.connector.Connector` to the
@@ -982,19 +1053,6 @@ include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.jav
 
 
 
-[[howto-configure-undertow]]
-=== Configure Undertow
-Generally you can follow the advice from
-"`<<howto-discover-build-in-options-for-external-properties>>`" about
-`@ConfigurationProperties` (`ServerProperties` and `ServerProperties.Undertow` are the
-main ones here). However, you should also look at `WebServerFactoryCustomizer`.
-Once you have access to the `UndertowServletWebServerFactory`, you can use an
-`UndertowBuilderCustomizer` to modify Undertow's configuration to meet your needs.
-Alternatively, if you need more control and customization, you can add your own
-`UndertowServletWebServerFactory`.
-
-
-
 [[howto-enable-multiple-listeners-in-undertow]]
 === Enable Multiple Listeners with Undertow
 Add an `UndertowBuilderCustomizer` to the `UndertowServletWebServerFactory` and
@@ -1040,32 +1098,6 @@ this role is performed by a servlet container initializer, and the
 
 
 
-[[how-to-enable-http-response-compression]]
-=== Enable HTTP Response Compression
-HTTP response compression is supported by Jetty, Tomcat, and Undertow. It can be enabled
-in `application.properties`, as follows:
-
-[source,properties,indent=0,subs="verbatim,quotes,attributes"]
-----
-	server.compression.enabled=true
-----
-
-By default, responses must be at least 2048 bytes in length for compression to be
-performed. You can configure this behavior by setting the
-`server.compression.min-response-size` property.
-
-By default, responses are compressed only if their content type is one of the
-following:
-
-* `text/html`
-* `text/xml`
-* `text/plain`
-* `text/css`
-
-You can configure this behavior by setting the `server.compression.mime-types` property.
-
-
-
 [[howto-spring-mvc]]
 == Spring MVC