root
/
spring-boot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

Backport web server configuration doc changes

Browse Source 
Closes gh-13401
pull/13413/head
Brian Clozel 7 years ago
parent 5c96943e59
commit 59746de63b
1 changed files with 172 additions and 140 deletions
Show Stats Download Patch File Download Diff File

312
spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc
Unescape Escape View File

@ -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

Write Preview
Loading…
Cancel
Save