mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-09-03 04:26:12 +08:00
Clarify behaviour of WebServerFactory in reference guide
Closes gh-24705
This commit is contained in:
parent
b309980a59
commit
826d79be3e
@ -71,6 +71,7 @@ dependencies {
|
|||||||
implementation("com.zaxxer:HikariCP")
|
implementation("com.zaxxer:HikariCP")
|
||||||
implementation("io.micrometer:micrometer-core")
|
implementation("io.micrometer:micrometer-core")
|
||||||
implementation("io.projectreactor.netty:reactor-netty")
|
implementation("io.projectreactor.netty:reactor-netty")
|
||||||
|
implementation("io.undertow:undertow-core")
|
||||||
implementation("jakarta.servlet:jakarta.servlet-api")
|
implementation("jakarta.servlet:jakarta.servlet-api")
|
||||||
implementation("org.apache.commons:commons-dbcp2")
|
implementation("org.apache.commons:commons-dbcp2")
|
||||||
implementation("org.apache.kafka:kafka-streams")
|
implementation("org.apache.kafka:kafka-streams")
|
||||||
|
@ -720,6 +720,11 @@ The example below is for Tomcat with the `spring-boot-starter-web` (Servlet stac
|
|||||||
}
|
}
|
||||||
----
|
----
|
||||||
|
|
||||||
|
NOTE: Spring Boot uses that infrastructure internally to auto-configure the server.
|
||||||
|
Auto-configured `WebServerFactoryCustomizer` beans have an order of `0` and will be processed before any user-defined customizers, unless it has an explicit order that states otherwise.
|
||||||
|
|
||||||
|
Once you've got access to a `WebServerFactory` using the customizer, you can use it to configure specific parts, like connectors, server resources, or the server itself - all using server-specific APIs.
|
||||||
|
|
||||||
In addition Spring Boot provides:
|
In addition Spring Boot provides:
|
||||||
|
|
||||||
[[howto-configure-webserver-customizers]]
|
[[howto-configure-webserver-customizers]]
|
||||||
@ -744,10 +749,8 @@ In addition Spring Boot provides:
|
|||||||
| `NettyReactiveWebServerFactory`
|
| `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` bean, which will override the one provided by Spring Boot.
|
||||||
|
When you do so, auto-configured customizers are still applied on your custom factory, so use that option carefully.
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@ -892,7 +895,7 @@ If you use YAML, single backslashes are sufficient, and a value equivalent to th
|
|||||||
|
|
||||||
NOTE: You can trust all proxies by setting the `internal-proxies` to empty (but do not do so in production).
|
NOTE: You can trust all proxies by setting the `internal-proxies` to empty (but do not do so in production).
|
||||||
|
|
||||||
You can take complete control of the configuration of Tomcat's `RemoteIpValve` by switching the automatic one off (to do so, set `server.forward-headers-strategy=NONE`) and adding a new valve instance in a `TomcatServletWebServerFactory` bean.
|
You can take complete control of the configuration of Tomcat's `RemoteIpValve` by switching the automatic one off (to do so, set `server.forward-headers-strategy=NONE`) and adding a new valve instance using a `WebServerFactoryCustomizer` bean.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@ -902,35 +905,7 @@ You can add an `org.apache.catalina.connector.Connector` to the `TomcatServletWe
|
|||||||
|
|
||||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||||
----
|
----
|
||||||
@Bean
|
include::{code-examples}/context/embedded/TomcatMultipleConnectorsExample.java[tag=configuration]
|
||||||
public ServletWebServerFactory servletContainer() {
|
|
||||||
TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory();
|
|
||||||
tomcat.addAdditionalTomcatConnectors(createSslConnector());
|
|
||||||
return tomcat;
|
|
||||||
}
|
|
||||||
|
|
||||||
private Connector createSslConnector() {
|
|
||||||
Connector connector = new Connector("org.apache.coyote.http11.Http11NioProtocol");
|
|
||||||
Http11NioProtocol protocol = (Http11NioProtocol) connector.getProtocolHandler();
|
|
||||||
try {
|
|
||||||
File keystore = new ClassPathResource("keystore").getFile();
|
|
||||||
File truststore = new ClassPathResource("keystore").getFile();
|
|
||||||
connector.setScheme("https");
|
|
||||||
connector.setSecure(true);
|
|
||||||
connector.setPort(8443);
|
|
||||||
protocol.setSSLEnabled(true);
|
|
||||||
protocol.setKeystoreFile(keystore.getAbsolutePath());
|
|
||||||
protocol.setKeystorePass("changeit");
|
|
||||||
protocol.setTruststoreFile(truststore.getAbsolutePath());
|
|
||||||
protocol.setTruststorePass("changeit");
|
|
||||||
protocol.setKeyAlias("apitester");
|
|
||||||
return connector;
|
|
||||||
}
|
|
||||||
catch (IOException ex) {
|
|
||||||
throw new IllegalStateException("can't access keystore: [" + keystore
|
|
||||||
+ "] or truststore: [" + truststore + "]", ex);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
----
|
----
|
||||||
|
|
||||||
|
|
||||||
@ -974,19 +949,7 @@ Add an `UndertowBuilderCustomizer` to the `UndertowServletWebServerFactory` and
|
|||||||
|
|
||||||
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||||
----
|
----
|
||||||
@Bean
|
include::{code-examples}/context/embedded/UndertowMultipleListenersExample.java[tag=configuration]
|
||||||
public UndertowServletWebServerFactory servletWebServerFactory() {
|
|
||||||
UndertowServletWebServerFactory factory = new UndertowServletWebServerFactory();
|
|
||||||
factory.addBuilderCustomizers(new UndertowBuilderCustomizer() {
|
|
||||||
|
|
||||||
@Override
|
|
||||||
public void customize(Builder builder) {
|
|
||||||
builder.addHttpListener(8080, "0.0.0.0");
|
|
||||||
}
|
|
||||||
|
|
||||||
});
|
|
||||||
return factory;
|
|
||||||
}
|
|
||||||
----
|
----
|
||||||
|
|
||||||
|
|
||||||
@ -2367,7 +2330,7 @@ You can switch on the valve by adding some entries to `application.properties`,
|
|||||||
----
|
----
|
||||||
|
|
||||||
(The presence of either of those properties switches on the valve.
|
(The presence of either of those properties switches on the valve.
|
||||||
Alternatively, you can add the `RemoteIpValve` by adding a `TomcatServletWebServerFactory` bean.)
|
Alternatively, you can add the `RemoteIpValve` by customizing the `TomcatServletWebServerFactory` using a `WebServerFactoryCustomizer` bean.)
|
||||||
|
|
||||||
To configure Spring Security to require a secure channel for all (or some) requests, consider adding your own `WebSecurityConfigurerAdapter` that adds the following `HttpSecurity` configuration:
|
To configure Spring Security to require a secure channel for all (or some) requests, consider adding your own `WebSecurityConfigurerAdapter` that adds the following `HttpSecurity` configuration:
|
||||||
|
|
||||||
|
@ -3115,30 +3115,26 @@ The following example shows programmatically setting the port:
|
|||||||
}
|
}
|
||||||
----
|
----
|
||||||
|
|
||||||
NOTE: `TomcatServletWebServerFactory`, `JettyServletWebServerFactory` and `UndertowServletWebServerFactory` are dedicated variants of `ConfigurableServletWebServerFactory` that have additional customization setter methods for Tomcat, Jetty and Undertow respectively.
|
`TomcatServletWebServerFactory`, `JettyServletWebServerFactory` and `UndertowServletWebServerFactory` are dedicated variants of `ConfigurableServletWebServerFactory` that have additional customization setter methods for Tomcat, Jetty and Undertow respectively.
|
||||||
|
The following example shows how to customize `TomcatServletWebServerFactory` that provides access to Tomcat-specific configuration options:
|
||||||
|
|
||||||
|
[source,java,indent=0,subs="verbatim,quotes,attributes"]
|
||||||
|
----
|
||||||
|
include::{code-examples}/context/embedded/TomcatServerCustomizerExample.java[tag=configuration]
|
||||||
|
----
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
[[boot-features-customizing-configurableservletwebserverfactory-directly]]
|
[[boot-features-customizing-configurableservletwebserverfactory-directly]]
|
||||||
===== Customizing ConfigurableServletWebServerFactory Directly
|
===== Customizing ConfigurableServletWebServerFactory Directly
|
||||||
If the preceding customization techniques are too limited, you can register the `TomcatServletWebServerFactory`, `JettyServletWebServerFactory`, or `UndertowServletWebServerFactory` bean yourself.
|
For more advanced use cases that require you to extend from `ServletWebServerFactory`, you can expose a bean of such type yourself.
|
||||||
|
|
||||||
[source,java,indent=0]
|
|
||||||
----
|
|
||||||
@Bean
|
|
||||||
public ConfigurableServletWebServerFactory webServerFactory() {
|
|
||||||
TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory();
|
|
||||||
factory.setPort(9000);
|
|
||||||
factory.setSessionTimeout(10, TimeUnit.MINUTES);
|
|
||||||
factory.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/notfound.html"));
|
|
||||||
return factory;
|
|
||||||
}
|
|
||||||
----
|
|
||||||
|
|
||||||
Setters are provided for many configuration options.
|
Setters are provided for many configuration options.
|
||||||
Several protected method "`hooks`" are also provided should you need to do something more exotic.
|
Several protected method "`hooks`" are also provided should you need to do something more exotic.
|
||||||
See the {spring-boot-module-api}/web/servlet/server/ConfigurableServletWebServerFactory.html[source code documentation] for details.
|
See the {spring-boot-module-api}/web/servlet/server/ConfigurableServletWebServerFactory.html[source code documentation] for details.
|
||||||
|
|
||||||
|
NOTE: Auto-configured customizers are still applied on your custom factory, so use that option carefully.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
[[boot-features-jsp-limitations]]
|
[[boot-features-jsp-limitations]]
|
||||||
|
@ -0,0 +1,68 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2012-2021 the original author or authors.
|
||||||
|
*
|
||||||
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
* you may not use this file except in compliance with the License.
|
||||||
|
* You may obtain a copy of the License at
|
||||||
|
*
|
||||||
|
* https://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
*
|
||||||
|
* Unless required by applicable law or agreed to in writing, software
|
||||||
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
* See the License for the specific language governing permissions and
|
||||||
|
* limitations under the License.
|
||||||
|
*/
|
||||||
|
|
||||||
|
package org.springframework.boot.docs.context.embedded;
|
||||||
|
|
||||||
|
import java.io.IOException;
|
||||||
|
import java.net.URL;
|
||||||
|
|
||||||
|
import org.apache.catalina.connector.Connector;
|
||||||
|
import org.apache.coyote.http11.Http11NioProtocol;
|
||||||
|
|
||||||
|
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
|
||||||
|
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
|
||||||
|
import org.springframework.context.annotation.Bean;
|
||||||
|
import org.springframework.context.annotation.Configuration;
|
||||||
|
import org.springframework.util.ResourceUtils;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Example configuration for configuring Tomcat with an additional {@link Connector}.
|
||||||
|
*
|
||||||
|
* @author Stephane Nicoll
|
||||||
|
*/
|
||||||
|
@Configuration(proxyBeanMethods = false)
|
||||||
|
public class TomcatMultipleConnectorsExample {
|
||||||
|
|
||||||
|
// tag::configuration[]
|
||||||
|
@Bean
|
||||||
|
public WebServerFactoryCustomizer<TomcatServletWebServerFactory> sslConnectorCustomizer() {
|
||||||
|
return (tomcat) -> tomcat.addAdditionalTomcatConnectors(createSslConnector());
|
||||||
|
}
|
||||||
|
|
||||||
|
private Connector createSslConnector() {
|
||||||
|
Connector connector = new Connector("org.apache.coyote.http11.Http11NioProtocol");
|
||||||
|
Http11NioProtocol protocol = (Http11NioProtocol) connector.getProtocolHandler();
|
||||||
|
try {
|
||||||
|
URL keystore = ResourceUtils.getURL("keystore");
|
||||||
|
URL truststore = ResourceUtils.getURL("truststore");
|
||||||
|
connector.setScheme("https");
|
||||||
|
connector.setSecure(true);
|
||||||
|
connector.setPort(8443);
|
||||||
|
protocol.setSSLEnabled(true);
|
||||||
|
protocol.setKeystoreFile(keystore.toString());
|
||||||
|
protocol.setKeystorePass("changeit");
|
||||||
|
protocol.setTruststoreFile(truststore.toString());
|
||||||
|
protocol.setTruststorePass("changeit");
|
||||||
|
protocol.setKeyAlias("apitester");
|
||||||
|
return connector;
|
||||||
|
}
|
||||||
|
catch (IOException ex) {
|
||||||
|
throw new IllegalStateException("Fail to create ssl connector", ex);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
// end::configuration[]
|
||||||
|
|
||||||
|
}
|
@ -0,0 +1,41 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2012-2021 the original author or authors.
|
||||||
|
*
|
||||||
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
* you may not use this file except in compliance with the License.
|
||||||
|
* You may obtain a copy of the License at
|
||||||
|
*
|
||||||
|
* https://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
*
|
||||||
|
* Unless required by applicable law or agreed to in writing, software
|
||||||
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
* See the License for the specific language governing permissions and
|
||||||
|
* limitations under the License.
|
||||||
|
*/
|
||||||
|
|
||||||
|
package org.springframework.boot.docs.context.embedded;
|
||||||
|
|
||||||
|
import java.time.Duration;
|
||||||
|
|
||||||
|
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
|
||||||
|
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
|
||||||
|
import org.springframework.stereotype.Component;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Example of a {@link WebServerFactoryCustomizer} that uses a more narrowed server type.
|
||||||
|
*
|
||||||
|
* @author Stephane Nicoll
|
||||||
|
*/
|
||||||
|
// tag::configuration[]
|
||||||
|
@Component
|
||||||
|
public class TomcatServerCustomizerExample implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void customize(TomcatServletWebServerFactory server) {
|
||||||
|
server.addConnectorCustomizers(
|
||||||
|
(tomcatConnector) -> tomcatConnector.setAsyncTimeout(Duration.ofSeconds(20).toMillis()));
|
||||||
|
}
|
||||||
|
|
||||||
|
}
|
||||||
|
// end::configuration[]
|
@ -0,0 +1,51 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2012-2021 the original author or authors.
|
||||||
|
*
|
||||||
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
* you may not use this file except in compliance with the License.
|
||||||
|
* You may obtain a copy of the License at
|
||||||
|
*
|
||||||
|
* https://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
*
|
||||||
|
* Unless required by applicable law or agreed to in writing, software
|
||||||
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
* See the License for the specific language governing permissions and
|
||||||
|
* limitations under the License.
|
||||||
|
*/
|
||||||
|
|
||||||
|
package org.springframework.boot.docs.context.embedded;
|
||||||
|
|
||||||
|
import io.undertow.Undertow.Builder;
|
||||||
|
|
||||||
|
import org.springframework.boot.web.embedded.undertow.UndertowBuilderCustomizer;
|
||||||
|
import org.springframework.boot.web.embedded.undertow.UndertowServletWebServerFactory;
|
||||||
|
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
|
||||||
|
import org.springframework.context.annotation.Bean;
|
||||||
|
import org.springframework.context.annotation.Configuration;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Example configuration for configuring Undertow with an additional listener.
|
||||||
|
*
|
||||||
|
* @author Stephane Nicoll
|
||||||
|
*/
|
||||||
|
@Configuration(proxyBeanMethods = false)
|
||||||
|
public class UndertowMultipleListenersExample {
|
||||||
|
|
||||||
|
// tag::configuration[]
|
||||||
|
@Bean
|
||||||
|
public WebServerFactoryCustomizer<UndertowServletWebServerFactory> undertowListenerCustomizer() {
|
||||||
|
return (factory) -> {
|
||||||
|
factory.addBuilderCustomizers(new UndertowBuilderCustomizer() {
|
||||||
|
|
||||||
|
@Override
|
||||||
|
public void customize(Builder builder) {
|
||||||
|
builder.addHttpListener(8080, "0.0.0.0");
|
||||||
|
}
|
||||||
|
|
||||||
|
});
|
||||||
|
};
|
||||||
|
}
|
||||||
|
// end::configuration[]
|
||||||
|
|
||||||
|
}
|
Loading…
Reference in New Issue
Block a user