Skip to content

Commit 59746de

Browse files
bclozelbclozel
committed
Backport web server configuration doc changes
Closes gh-13401
1 parent 5c96943 commit 59746de

File tree

1 file changed

+172
-140
lines changed
  • spring-boot-project/spring-boot-docs/src/main/asciidoc

1 file changed

+172
-140
lines changed

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

Lines changed: 172 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -506,15 +506,17 @@ configure the embedded server. This section answers those questions.
506506

507507
[[howto-use-another-web-server]]
508508
=== Use Another Web Server
509-
Many Spring Boot starters include default embedded containers. `spring-boot-starter-web`
510-
includes Tomcat by including `spring-boot-starter-tomcat`, but you can use
511-
`spring-boot-starter-jetty` or `spring-boot-starter-undertow` instead.
512-
`spring-boot-starter-webflux` includes Reactor Netty by including
513-
`spring-boot-starter-reactor-netty`, but you can use `spring-boot-starter-tomcat`,
509+
Many Spring Boot starters include default embedded containers.
510+
511+
* For servlet stack applications, the `spring-boot-starter-web` includes Tomcat by including
512+
`spring-boot-starter-tomcat`, but you can use `spring-boot-starter-jetty` or
513+
`spring-boot-starter-undertow` instead.
514+
* For reactive stack applications, the `spring-boot-starter-webflux` includes Reactor Netty
515+
by including `spring-boot-starter-reactor-netty`, but you can use `spring-boot-starter-tomcat`,
514516
`spring-boot-starter-jetty`, or `spring-boot-starter-undertow` instead.
515517

516-
If you need to use a different HTTP server, you need to exclude the default dependencies
517-
and include the one you need. Spring Boot provides separate starters for
518+
When switching to a different HTTP server, you need to exclude the default dependencies
519+
in addition to including the one you need. Spring Boot provides separate starters for
518520
HTTP servers to help make this process as easy as possible.
519521

520522
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:
576578

577579

578580

579-
[[howto-configure-jetty]]
580-
=== Configure Jetty
581-
Generally, you can follow the advice from
582-
"`<<howto-discover-build-in-options-for-external-properties>>`" about
583-
`@ConfigurationProperties` (`ServerProperties` is the main one here). However, you should
584-
also look at
585-
{dc-spring-boot}/web/server/WebServerFactoryCustomizer.html[`WebServerFactoryCustomizer`].
586-
The Jetty APIs are quite rich, so, once you have access to the
587-
`JettyServletWebServerFactory`, you can modify it in a number of ways. Alternatively, if
588-
you need more control and customization, you can add your own
589-
`JettyServletWebServerFactory`.
590-
591-
592-
593-
[[howto-add-a-servlet-filter-or-listener]]
594-
=== Add a Servlet, Filter, or Listener to an Application
595-
There are two ways to add `Servlet`, `Filter`, `ServletContextListener`, and the other
596-
listeners supported by the Servlet spec to your application:
597-
598-
* <<howto-add-a-servlet-filter-or-listener-as-spring-bean>>
599-
* <<howto-add-a-servlet-filter-or-listener-using-scanning>>
600-
601-
602-
603-
[[howto-add-a-servlet-filter-or-listener-as-spring-bean]]
604-
==== Add a Servlet, Filter, or Listener by Using a Spring Bean
605-
To add a `Servlet`, `Filter`, or Servlet `*Listener` by using a Spring bean, you must
606-
provide a `@Bean` definition for it. Doing so can be very useful when you want to inject
607-
configuration or dependencies. However, you must be very careful that they do not cause
608-
eager initialization of too many other beans, because they have to be installed in the
609-
container very early in the application lifecycle. (For example, it is not a good idea to
610-
have them depend on your `DataSource` or JPA configuration.) You can work around such
611-
restrictions by initializing the beans lazily when first used instead of on
612-
initialization.
613-
614-
In the case of `Filters` and `Servlets`, you can also add mappings and init parameters by
615-
adding a `FilterRegistrationBean` or a `ServletRegistrationBean` instead of or in
616-
addition to the underlying component.
617-
618-
[NOTE]
619-
====
620-
If no `dispatcherType` is specified on a filter registration, `REQUEST` is used. This
621-
aligns with the Servlet Specification's default dispatcher type.
622-
====
623-
624-
Like any other Spring bean, you can define the order of Servlet filter beans; please
625-
make sure to check the
626-
"`<<spring-boot-features.adoc#boot-features-embedded-container-servlets-filters-listeners-beans>>`"
627-
section.
628-
629-
630-
631-
[[howto-disable-registration-of-a-servlet-or-filter]]
632-
===== Disable Registration of a Servlet or Filter
633-
As <<howto-add-a-servlet-filter-or-listener-as-spring-bean,described earlier>>, any
634-
`Servlet` or `Filter` beans are registered with the servlet container automatically. To
635-
disable registration of a particular `Filter` or `Servlet` bean, create a registration
636-
bean for it and mark it as disabled, as shown in the following example:
637-
638-
[source,java,indent=0,subs="verbatim,quotes,attributes"]
639-
----
640-
@Bean
641-
public FilterRegistrationBean registration(MyFilter filter) {
642-
FilterRegistrationBean registration = new FilterRegistrationBean(filter);
643-
registration.setEnabled(false);
644-
return registration;
645-
}
646-
----
647-
648-
649-
650-
[[howto-add-a-servlet-filter-or-listener-using-scanning]]
651-
==== Add Servlets, Filters, and Listeners by Using Classpath Scanning
652-
`@WebServlet`, `@WebFilter`, and `@WebListener` annotated classes can be automatically
653-
registered with an embedded servlet container by annotating a `@Configuration` class
654-
with `@ServletComponentScan` and specifying the package(s) containing the components
655-
that you want to register. By default, `@ServletComponentScan` scans from the package
656-
of the annotated class.
657-
658-
659-
660581
[[howto-change-the-http-port]]
661582
=== Change the HTTP Port
662583
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).
720641

721642

722643

644+
[[how-to-enable-http-response-compression]]
645+
=== Enable HTTP Response Compression
646+
HTTP response compression is supported by Jetty, Tomcat, and Undertow. It can be enabled
647+
in `application.properties`, as follows:
648+
649+
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
650+
----
651+
server.compression.enabled=true
652+
----
653+
654+
By default, responses must be at least 2048 bytes in length for compression to be
655+
performed. You can configure this behavior by setting the
656+
`server.compression.min-response-size` property.
657+
658+
By default, responses are compressed only if their content type is one of the
659+
following:
660+
661+
* `text/html`
662+
* `text/xml`
663+
* `text/plain`
664+
* `text/css`
665+
666+
You can configure this behavior by setting the `server.compression.mime-types` property.
667+
668+
669+
723670
[[howto-configure-ssl]]
724671
=== Configure SSL
725672
SSL can be configured declaratively by setting the various `+server.ssl.*+` properties,
@@ -804,6 +751,143 @@ the version of your choice.
804751

805752

806753

754+
[[howto-configure-webserver]]
755+
=== Configure the Web Server
756+
757+
Generally, you should first consider using one of the many available configuration keys
758+
and customize your web server by adding new entries in your `application.properties` (or
759+
`application.yml`, or environment, etc. see
760+
"`<<howto-discover-build-in-options-for-external-properties>>`"). The `server.{asterisk}`
761+
namespace is quite useful here, and it includes namespaces like `server.tomcat.{asterisk}`,
762+
`server.jetty.{asterisk}` and others, for server-specific features.
763+
See the list of <<common-application-properties>>.
764+
765+
The previous sections covered already many common use cases, such as compression, SSL
766+
or HTTP/2. However, if a configuration key doesn't exist for your use case, you should
767+
then look at
768+
{dc-spring-boot}/web/server/WebServerFactoryCustomizer.html[`WebServerFactoryCustomizer`].
769+
You can declare such a component and get access to the server factory relevant to your
770+
choice: you should select the variant for the chosen Server (Tomcat, Jetty, Reactor Netty,
771+
Undertow) and the chosen web stack (Servlet or Reactive).
772+
773+
The example below is for Tomcat with the `spring-boot-starter-web` (Servlet stack):
774+
775+
[source,java,indent=0,subs="verbatim,quotes,attributes"]
776+
----
777+
@Component
778+
public class MyTomcatWebServerCustomizer
779+
implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
780+
781+
@Override
782+
public void customize(TomcatServletWebServerFactory factory) {
783+
// customize the factory here
784+
}
785+
}
786+
----
787+
788+
In addition Spring Boot provides:
789+
790+
[[howto-configure-webserver-customizers]]
791+
[cols="1,2,2", options="header"]
792+
|===
793+
| Server | Servlet stack | Reactive stack
794+
795+
| Tomcat
796+
| `TomcatServletWebServerFactory`
797+
| `TomcatReactiveWebServerFactory`
798+
799+
| Jetty
800+
| `JettyServletWebServerFactory`
801+
| `JettyReactiveWebServerFactory`
802+
803+
| Undertow
804+
| `UndertowServletWebServerFactory`
805+
| `UndertowReactiveWebServerFactory`
806+
807+
| Reactor
808+
| N/A
809+
| `NettyReactiveWebServerFactory`
810+
811+
|===
812+
813+
Once you've got access to a `WebServerFactory`, you can often add customizers to it to
814+
configure specific parts, like connectors, server resources, or the server itself - all
815+
using server-specific APIs.
816+
817+
As a last resort, you can also declare your own `WebServerFactory` component, which will
818+
override the one provided by Spring Boot. In this case, you can't rely on configuration
819+
properties in the `server` namespace anymore.
820+
821+
822+
823+
[[howto-add-a-servlet-filter-or-listener]]
824+
=== Add a Servlet, Filter, or Listener to a Application
825+
In a servlet stack application, i.e. with the `spring-boot-starter-web`, there are two
826+
ways to add `Servlet`, `Filter`, `ServletContextListener`, and the other listeners
827+
supported by the Servlet API to your application:
828+
829+
* <<howto-add-a-servlet-filter-or-listener-as-spring-bean>>
830+
* <<howto-add-a-servlet-filter-or-listener-using-scanning>>
831+
832+
833+
834+
[[howto-add-a-servlet-filter-or-listener-as-spring-bean]]
835+
==== Add a Servlet, Filter, or Listener by Using a Spring Bean
836+
To add a `Servlet`, `Filter`, or Servlet `*Listener` by using a Spring bean, you must
837+
provide a `@Bean` definition for it. Doing so can be very useful when you want to inject
838+
configuration or dependencies. However, you must be very careful that they do not cause
839+
eager initialization of too many other beans, because they have to be installed in the
840+
container very early in the application lifecycle. (For example, it is not a good idea to
841+
have them depend on your `DataSource` or JPA configuration.) You can work around such
842+
restrictions by initializing the beans lazily when first used instead of on
843+
initialization.
844+
845+
In the case of `Filters` and `Servlets`, you can also add mappings and init parameters by
846+
adding a `FilterRegistrationBean` or a `ServletRegistrationBean` instead of or in
847+
addition to the underlying component.
848+
849+
[NOTE]
850+
====
851+
If no `dispatcherType` is specified on a filter registration, `REQUEST` is used. This
852+
aligns with the Servlet Specification's default dispatcher type.
853+
====
854+
855+
Like any other Spring bean, you can define the order of Servlet filter beans; please
856+
make sure to check the
857+
"`<<spring-boot-features.adoc#boot-features-embedded-container-servlets-filters-listeners-beans>>`"
858+
section.
859+
860+
861+
862+
[[howto-disable-registration-of-a-servlet-or-filter]]
863+
===== Disable Registration of a Servlet or Filter
864+
As <<howto-add-a-servlet-filter-or-listener-as-spring-bean,described earlier>>, any
865+
`Servlet` or `Filter` beans are registered with the servlet container automatically. To
866+
disable registration of a particular `Filter` or `Servlet` bean, create a registration
867+
bean for it and mark it as disabled, as shown in the following example:
868+
869+
[source,java,indent=0,subs="verbatim,quotes,attributes"]
870+
----
871+
@Bean
872+
public FilterRegistrationBean registration(MyFilter filter) {
873+
FilterRegistrationBean registration = new FilterRegistrationBean(filter);
874+
registration.setEnabled(false);
875+
return registration;
876+
}
877+
----
878+
879+
880+
881+
[[howto-add-a-servlet-filter-or-listener-using-scanning]]
882+
==== Add Servlets, Filters, and Listeners by Using Classpath Scanning
883+
`@WebServlet`, `@WebFilter`, and `@WebListener` annotated classes can be automatically
884+
registered with an embedded servlet container by annotating a `@Configuration` class
885+
with `@ServletComponentScan` and specifying the package(s) containing the components
886+
that you want to register. By default, `@ServletComponentScan` scans from the package
887+
of the annotated class.
888+
889+
890+
807891
[[howto-configure-accesslogs]]
808892
=== Configure Access Logging
809893
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.
904988

905989

906990

907-
[[howto-configure-tomcat]]
908-
=== Configure Tomcat
909-
Generally, you can follow the advice from
910-
"`<<howto-discover-build-in-options-for-external-properties>>`" about
911-
`@ConfigurationProperties` (`ServerProperties` is the main one here). However, you should
912-
also look at `WebServerFactoryCustomizer` and various Tomcat-specific
913-
`+*Customizers+` that you can add. The Tomcat APIs are quite rich. Consequently, once you
914-
have access to the `TomcatServletWebServerFactory`, you can modify it in a number of ways.
915-
Alternatively, if you need more control and customization, you can add your own
916-
`TomcatServletWebServerFactory`.
917-
918-
919-
920991
[[howto-enable-multiple-connectors-in-tomcat]]
921992
=== Enable Multiple Connectors with Tomcat
922993
You can add an `org.apache.catalina.connector.Connector` to the
@@ -982,19 +1053,6 @@ include::{code-examples}/context/embedded/TomcatLegacyCookieProcessorExample.jav
9821053

9831054

9841055

985-
[[howto-configure-undertow]]
986-
=== Configure Undertow
987-
Generally you can follow the advice from
988-
"`<<howto-discover-build-in-options-for-external-properties>>`" about
989-
`@ConfigurationProperties` (`ServerProperties` and `ServerProperties.Undertow` are the
990-
main ones here). However, you should also look at `WebServerFactoryCustomizer`.
991-
Once you have access to the `UndertowServletWebServerFactory`, you can use an
992-
`UndertowBuilderCustomizer` to modify Undertow's configuration to meet your needs.
993-
Alternatively, if you need more control and customization, you can add your own
994-
`UndertowServletWebServerFactory`.
995-
996-
997-
9981056
[[howto-enable-multiple-listeners-in-undertow]]
9991057
=== Enable Multiple Listeners with Undertow
10001058
Add an `UndertowBuilderCustomizer` to the `UndertowServletWebServerFactory` and
@@ -1040,32 +1098,6 @@ this role is performed by a servlet container initializer, and the
10401098

10411099

10421100

1043-
[[how-to-enable-http-response-compression]]
1044-
=== Enable HTTP Response Compression
1045-
HTTP response compression is supported by Jetty, Tomcat, and Undertow. It can be enabled
1046-
in `application.properties`, as follows:
1047-
1048-
[source,properties,indent=0,subs="verbatim,quotes,attributes"]
1049-
----
1050-
server.compression.enabled=true
1051-
----
1052-
1053-
By default, responses must be at least 2048 bytes in length for compression to be
1054-
performed. You can configure this behavior by setting the
1055-
`server.compression.min-response-size` property.
1056-
1057-
By default, responses are compressed only if their content type is one of the
1058-
following:
1059-
1060-
* `text/html`
1061-
* `text/xml`
1062-
* `text/plain`
1063-
* `text/css`
1064-
1065-
You can configure this behavior by setting the `server.compression.mime-types` property.
1066-
1067-
1068-
10691101
[[howto-spring-mvc]]
10701102
== Spring MVC
10711103

0 commit comments

Comments
 (0)