diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc index 2942966a663..b9cd1126724 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -576,87 +576,6 @@ your `application.properties`, as shown in the following example: -[[howto-configure-jetty]] -=== Configure Jetty -Generally, you can follow the advice from -"`<>`" 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]] -==== 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 -"`<>`" -section. - - - -[[howto-disable-registration-of-a-servlet-or-filter]] -===== Disable Registration of a Servlet or Filter -As <>, 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 +639,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 +749,124 @@ 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 +"`<>`"). 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 <>. + +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). + +In the following example, we're using Tomcat in a Servlet-based web application: + +[source,java,indent=0,subs="verbatim,quotes,attributes"] +---- + @Component + public class MyTomcatWebServerCustomizer + implements WebServerFactoryCustomizer { + + @Override + public void customize(TomcatServletWebServerFactory factory) { + // customize the factory here + } + } +---- + +Spring Boot currently provides: + +* `TomcatServletWebServerFactory` and `TomcatReactiveWebServerFactory` for Tomcat +* `JettyServletWebServerFactory` and `JettyReactiveWebServerFactory` for Jetty +* `UndertowServletWebServerFactory` and `UndertowReactiveWebServerFactory` for Undertow +* `NettyReactiveWebServerFactory` for Reactor Netty + +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 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]] +==== 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 +"`<>`" +section. + + + +[[howto-disable-registration-of-a-servlet-or-filter]] +===== Disable Registration of a Servlet or Filter +As <>, 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 +967,6 @@ adding a new valve instance in a `TomcatServletWebServerFactory` bean. -[[howto-configure-tomcat]] -=== Configure Tomcat -Generally, you can follow the advice from -"`<>`" 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 +1032,6 @@ include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.jav -[[howto-configure-undertow]] -=== Configure Undertow -Generally you can follow the advice from -"`<>`" 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 +1077,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