Document Reactor Netty server configuration
This commit regroups the documentation on how to configure a web server in Spring Boot. The same concepts apply, whether the server is Tomcat/Netty/Jetty/Undertow, or if it's deployed for a Servlet or Reactive web application. Closes gh-13315
This commit is contained in:
Brian Clozel
parent
fe3de2816c
commit
0004550f7b
|
|
@ -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
|
||||
"`<<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 +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
|
||||
"`<<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).
|
||||
|
||||
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<TomcatServletWebServerFactory> {
|
||||
|
||||
@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>>
|
||||
* <<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 +967,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 +1032,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 +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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue