From 3cc0f7b70dd14316ea4865765e5036739cecebbe Mon Sep 17 00:00:00 2001 From: Brian Clozel Date: Fri, 28 Apr 2017 16:48:47 +0200 Subject: [PATCH] Document embedded web server refactoring Closes gh-8532 --- spring-boot-docs/src/main/asciidoc/howto.adoc | 42 +++++++++---------- .../main/asciidoc/spring-boot-features.adoc | 14 +++---- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-docs/src/main/asciidoc/howto.adoc index a413c524acd..e1aa79f73ab 100644 --- a/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -571,9 +571,9 @@ To scan for a free port (using OS natives to prevent clashes) use `server.port=0 [[howto-discover-the-http-port-at-runtime]] === Discover the HTTP port at runtime You can access the port the server is running on from log output or from the -`EmbeddedWebApplicationContext` via its `EmbeddedWebServer`. The best way to get +`ServletWebServerApplicationContext` via its `EmbeddedWebServer`. The best way to get that and be sure that it has initialized is to add a `@Bean` of type -`ApplicationListener` and pull the container +`ApplicationListener` and pull the container out of the event when it is published. Tests that use `@SpringBootTest(webEnvironment=WebEnvironment.RANDOM_PORT)` can @@ -587,7 +587,7 @@ example: public class MyWebIntegrationTests { @Autowired - EmbeddedWebApplicationContext server; + ServletWebServerApplicationContext server; @LocalServerPort int port; @@ -727,7 +727,7 @@ this in production). You can take complete control of the configuration of Tomcat's `RemoteIpValve` by switching the automatic one off (i.e. set `server.use-forward-headers=false`) and adding -a new valve instance in a `TomcatEmbeddedServletContainerFactory` bean. +a new valve instance in a `TomcatServletWebServerFactory` bean. @@ -736,24 +736,24 @@ a new valve instance in a `TomcatEmbeddedServletContainerFactory` bean. Generally you can follow the advice from _<>_ about `@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at -`EmbeddedServletContainerCustomizer` and various Tomcat-specific `+*Customizers+` that you +`ServletWebServerFactoryCustomizer` and various Tomcat-specific `+*Customizers+` that you can add in one of those. The Tomcat APIs are quite rich so once you have access to the -`TomcatEmbeddedServletContainerFactory` you can modify it in a number of ways. Or the -nuclear option is to add your own `TomcatEmbeddedServletContainerFactory`. +`TomcatServletWebServerFactory` you can modify it in a number of ways. Or the +nuclear option is to add your own `TomcatServletWebServerFactory`. [[howto-enable-multiple-connectors-in-tomcat]] === Enable Multiple Connectors with Tomcat Add a `org.apache.catalina.connector.Connector` to the -`TomcatEmbeddedServletContainerFactory` which can allow multiple connectors, e.g. HTTP and +`TomcatServletWebServerFactory` which can allow multiple connectors, e.g. HTTP and HTTPS connector: [source,java,indent=0,subs="verbatim,quotes,attributes"] ---- @Bean - public EmbeddedServletContainerFactory servletContainer() { - TomcatEmbeddedServletContainerFactory tomcat = new TomcatEmbeddedServletContainerFactory(); + public ServletWebServerFactory servletContainer() { + TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory(); tomcat.addAdditionalTomcatConnectors(createSslConnector()); return tomcat; } @@ -798,7 +798,7 @@ If at all possible, you should consider updating your code to only store values compliant with later Cookie specifications. If, however, you're unable to change the way that cookies are written, you can instead configure Tomcat to use a `LegacyCookieProcessor`. To switch to the `LegacyCookieProcessor` use an -`EmbeddedServletContainerCustomizer` bean that adds a `TomcatContextCustomizer`: +`ServletWebServerFactoryCustomizer` bean that adds a `TomcatContextCustomizer`: [source,java,indent=0] ---- @@ -856,9 +856,9 @@ Example in Gradle: Generally you can follow the advice from _<>_ about `@ConfigurationProperties` (`ServerProperties` is the main one here), but also look at -`EmbeddedServletContainerCustomizer`. The Jetty APIs are quite rich so once you have -access to the `JettyEmbeddedServletContainerFactory` you can modify it in a number -of ways. Or the nuclear option is to add your own `JettyEmbeddedServletContainerFactory`. +`ServletWebServerFactoryCustomizer`. The Jetty APIs are quite rich so once you have +access to the `JettyServletWebServerFactory` you can modify it in a number +of ways. Or the nuclear option is to add your own `JettyServletWebServerFactory`. @@ -911,23 +911,23 @@ Generally you can follow the advice from _<>_ about `@ConfigurationProperties` (`ServerProperties` and `ServerProperties.Undertow` are the main ones here), but also look at -`EmbeddedServletContainerCustomizer`. Once you have access to the -`UndertowEmbeddedServletContainerFactory` you can use an `UndertowBuilderCustomizer` to +`ServletWebServerFactoryCustomizer`. Once you have access to the +`UndertowServletWebServerFactory` you can use an `UndertowBuilderCustomizer` to modify Undertow's configuration to meet your needs. Or the nuclear option is to add your -own `UndertowEmbeddedServletContainerFactory`. +own `UndertowServletWebServerFactory`. [[howto-enable-multiple-listeners-in-undertow]] === Enable Multiple Listeners with Undertow -Add an `UndertowBuilderCustomizer` to the `UndertowEmbeddedServletContainerFactory` and +Add an `UndertowBuilderCustomizer` to the `UndertowServletWebServerFactory` and add a listener to the `Builder`: [source,java,indent=0,subs="verbatim,quotes,attributes"] ---- @Bean - public UndertowEmbeddedServletContainerFactory embeddedServletContainerFactory() { - UndertowEmbeddedServletContainerFactory factory = new UndertowEmbeddedServletContainerFactory(); + public UndertowServletWebServerFactory servletWebServerFactory() { + UndertowServletWebServerFactory factory = new UndertowServletWebServerFactory(); factory.addBuilderCustomizers(new UndertowBuilderCustomizer() { @Override @@ -2234,7 +2234,7 @@ by adding some entries to `application.properties`, e.g. ---- (The presence of either of those properties will switch on the valve. Or you can add the -`RemoteIpValve` yourself by adding a `TomcatEmbeddedServletContainerFactory` bean.) +`RemoteIpValve` yourself by adding a `TomcatServletWebServerFactory` bean.) Spring Security can also be configured to require a secure channel for all (or some requests). To switch that on in a Spring Boot application you just need to set diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 571c07f2026..24bc692a386 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -38,8 +38,8 @@ When your application starts you should see something similar to the following: :: Spring Boot :: v{spring-boot-version} 2013-07-31 00:08:16.117 INFO 56603 --- [ main] o.s.b.s.app.SampleApplication : Starting SampleApplication v0.1.0 on mycomputer with PID 56603 (/apps/myapp.jar started by pwebb) -2013-07-31 00:08:16.166 INFO 56603 --- [ main] ationConfigEmbeddedWebApplicationContext : Refreshing org.springframework.boot.context.embedded.AnnotationConfigEmbeddedWebApplicationContext@6e5a8246: startup date [Wed Jul 31 00:08:16 PDT 2013]; root of context hierarchy -2014-03-04 13:09:54.912 INFO 41370 --- [ main] .t.TomcatEmbeddedServletContainerFactory : Server initialized with port: 8080 +2013-07-31 00:08:16.166 INFO 56603 --- [ main] ationConfigServletWebServerApplicationContext : Refreshing org.springframework.boot.web.servlet.context.AnnotationConfigServletWebServerApplicationContext@6e5a8246: startup date [Wed Jul 31 00:08:16 PDT 2013]; root of context hierarchy +2014-03-04 13:09:54.912 INFO 41370 --- [ main] .t.TomcatServletWebServerFactory : Server initialized with port: 8080 2014-03-04 13:09:56.501 INFO 41370 --- [ main] o.s.b.s.app.SampleApplication : Started SampleApplication in 2.992 seconds (JVM running for 3.658) ---- @@ -248,7 +248,7 @@ exist. Internally, Spring Boot uses events to handle a variety of tasks. === Web environment A `SpringApplication` will attempt to create the right type of `ApplicationContext` on your behalf. By default, an `AnnotationConfigApplicationContext` or -`AnnotationConfigEmbeddedWebApplicationContext` will be used, depending on whether you +`AnnotationConfigServletWebServerApplicationContext` will be used, depending on whether you are developing a web application or not. The algorithm used to determine a '`web environment`' is fairly simplistic (based on the @@ -2310,7 +2310,7 @@ inside a war will break Spring Boot applications. If you need to perform servlet context initialization in a Spring Boot application, you should register a bean that implements the -`org.springframework.boot.context.embedded.ServletContextInitializer` interface. The +`org.springframework.boot.web.servlet.ServletContextInitializer` interface. The single `onStartup` method provides access to the `ServletContext`, and can easily be used as an adapter to an existing `WebApplicationInitializer` if necessary. @@ -2385,7 +2385,7 @@ methods. Dedicated variants exists for Tomcat, Jetty and Undertow. @Component public class CustomizationBean implements WebServerFactoryCustomizer { - + @Override public void customize(ConfigurableServletWebServerFactory server) { server.setPort(9000); @@ -5253,10 +5253,10 @@ how your tests will run: APIs are not on your classpath this mode will transparently fallback to creating a regular non-web `ApplicationContext`. Can be used in conjunction with `@AutoConfigureMockMvc` for `MockMvc`-based testing of your application. -* `RANDOM_PORT` -- Loads an `EmbeddedWebApplicationContext` and provides a real +* `RANDOM_PORT` -- Loads an `ServletWebServerApplicationContext` and provides a real servlet environment. Embedded servlet containers are started and listening on a random port. -* `DEFINED_PORT` -- Loads an `EmbeddedWebApplicationContext` and provides a real +* `DEFINED_PORT` -- Loads an `ServletWebServerApplicationContext` and provides a real servlet environment. Embedded servlet containers are started and listening on a defined port (i.e from your `application.properties` or on the default port `8080`). * `NONE` -- Loads an `ApplicationContext` using `SpringApplication` but does not provide