Skip to content

Commit 72e3c43

Browse files
committed
Refine @EnableWebFlux docs for functional endpoints
@EnableWebFlux bootstraps both annotated controllers and functional endpoints, so we need to be more explicit about which parts of the configuration apply to which. Issue: SPR-16360
1 parent 8f6d3fe commit 72e3c43

File tree

4 files changed

+71
-55
lines changed

4 files changed

+71
-55
lines changed

spring-webflux/src/main/java/org/springframework/web/reactive/config/EnableWebFlux.java

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,11 @@
2525
import org.springframework.context.annotation.Import;
2626

2727
/**
28-
* Adding this annotation to an {@code @Configuration} class imports the Spring Web
29-
* Reactive configuration from {@link WebFluxConfigurationSupport}, e.g.:
28+
* Adding this annotation to an {@code @Configuration} class imports the Spring
29+
* WebFlux configuration from {@link WebFluxConfigurationSupport} that enables
30+
* use of annotated controllers and functional endpoints.
31+
*
32+
* <p>For example:
3033
*
3134
* <pre class="code">
3235
* &#064;Configuration
@@ -36,8 +39,8 @@
3639
* }
3740
* </pre>
3841
*
39-
* <p>To customize the imported configuration implement
40-
* {@link WebFluxConfigurer} and override individual methods as shown below:
42+
* <p>To customize the imported configuration, implement
43+
* {@link WebFluxConfigurer} and one or more of its methods:
4144
*
4245
* <pre class="code">
4346
* &#064;Configuration
@@ -46,33 +49,32 @@
4649
* public class MyConfiguration implements WebFluxConfigurer {
4750
*
4851
* &#064;Override
49-
* public void addFormatters(FormatterRegistry formatterRegistry) {
50-
* formatterRegistry.addConverter(new MyConverter());
51-
* }
52-
*
53-
* &#064;Override
5452
* public void configureMessageWriters(List&lt;HttpMessageWriter&lt;?&gt&gt messageWriters) {
5553
* messageWriters.add(new MyHttpMessageWriter());
5654
* }
55+
*
56+
* // ...
5757
* }
5858
* </pre>
5959
*
60-
* <p><strong>Note:</strong> only one {@code @Configuration} class may have the
61-
* {@code @EnableWebFlux} annotation to import the Spring WebFlux configuration.
62-
* There can however be multiple {@code @Configuration} classes implementing
63-
* {@code WebFluxConfigurer} in order to customize the provided configuration.
60+
* <p>Only one {@code @Configuration} class should have the {@code @EnableWebFlux}
61+
* annotation in order to import the Spring WebFlux configuration. There can
62+
* however be multiple {@code @Configuration} classes that implement
63+
* {@code WebFluxConfigurer} that customize the provided configuration.
6464
*
65-
* <p>If {@link WebFluxConfigurer} does not expose some more advanced setting
66-
* that needs to be configured consider removing the {@code @EnableWebFlux}
67-
* annotation and extending directly from {@link WebFluxConfigurationSupport}
68-
* or {@link DelegatingWebFluxConfiguration} if you still want to allow
69-
* {@link WebFluxConfigurer} instances to customize the configuration.
65+
* <p>If {@code WebFluxConfigurer} does not expose some setting that needs to be
66+
* configured, consider switching to an advanced mode by removing the
67+
* {@code @EnableWebFlux} annotation and extending directly from
68+
* {@link WebFluxConfigurationSupport} or {@link DelegatingWebFluxConfiguration} --
69+
* the latter allows detecting and delegating to one or more
70+
* {@code WebFluxConfigurer} configuration classes.
7071
*
7172
* @author Brian Clozel
7273
* @author Rossen Stoyanchev
7374
* @since 5.0
7475
* @see WebFluxConfigurer
7576
* @see WebFluxConfigurationSupport
77+
* @see DelegatingWebFluxConfiguration
7678
*/
7779
@Retention(RetentionPolicy.RUNTIME)
7880
@Target(ElementType.TYPE)

spring-webflux/src/main/java/org/springframework/web/reactive/config/WebFluxConfigurer.java

Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828

2929
/**
3030
* Defines callback methods to customize the configuration for WebFlux
31-
* applications enabled via {@code @EnableWebFlux}.
31+
* applications enabled via {@link EnableWebFlux @EnableWebFlux}.
3232
*
3333
* <p>{@code @EnableWebFlux}-annotated configuration classes may implement
3434
* this interface to be called back and given a chance to customize the
@@ -38,27 +38,35 @@
3838
* @author Brian Clozel
3939
* @author Rossen Stoyanchev
4040
* @since 5.0
41+
* @see WebFluxConfigurationSupport
42+
* @see DelegatingWebFluxConfiguration
4143
*/
4244
public interface WebFluxConfigurer {
4345

4446
/**
45-
* Configure how the content type requested for the response is resolved.
47+
* Configure how the content type requested for the response is resolved
48+
* when handling reqests with annotated controllers.
4649
* @param builder for configuring the resolvers to use
4750
*/
4851
default void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {
4952
}
5053

5154
/**
52-
* Configure cross origin requests processing.
55+
* Configure "global" cross origin request processing.
56+
* <p>The configured readers and writers will apply to all requests including
57+
* annotated controllers and functional endpoints. Annotated controllers can
58+
* further declare more fine-grained configuration via
59+
* {@link org.springframework.web.bind.annotation.CrossOrigin @CrossOrigin}.
5360
* @see CorsRegistry
5461
*/
5562
default void addCorsMappings(CorsRegistry registry) {
5663
}
5764

5865
/**
5966
* Configure path matching options.
60-
*
61-
* {@code HandlerMapping}s with path matching options.
67+
* <p>The configured path matching options will be used for mapping to
68+
* annotated controllers and also
69+
* {@link #addResourceHandlers(ResourceHandlerRegistry) static resources}.
6270
* @param configurer the {@link PathMatchConfigurer} instance
6371
*/
6472
default void configurePathMatching(PathMatchConfigurer configurer) {
@@ -72,22 +80,24 @@ default void addResourceHandlers(ResourceHandlerRegistry registry) {
7280
}
7381

7482
/**
75-
* Configure resolvers for custom controller method arguments.
83+
* Configure resolvers for custom {@code @RequestMapping} method arguments.
7684
* @param configurer to configurer to use
7785
*/
7886
default void configureArgumentResolvers(ArgumentResolverConfigurer configurer) {
7987
}
8088

8189
/**
8290
* Configure custom HTTP message readers and writers or override built-in ones.
91+
* <p>The configured readers and writers will be used for both annotated
92+
* controllers and functional endpoints.
8393
* @param configurer the configurer to use
8494
*/
8595
default void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
8696
}
8797

8898
/**
8999
* Add custom {@link Converter}s and {@link Formatter}s for performing type
90-
* conversion and formatting of controller method arguments.
100+
* conversion and formatting of annotated controller method arguments.
91101
*/
92102
default void addFormatters(FormatterRegistry registry) {
93103
}
@@ -96,30 +106,30 @@ default void addFormatters(FormatterRegistry registry) {
96106
* Provide a custom {@link Validator}.
97107
* <p>By default a validator for standard bean validation is created if
98108
* bean validation api is present on the classpath.
109+
* <p>The configured validator is used for validating annotated controller
110+
* method arguments.
99111
*/
100112
@Nullable
101113
default Validator getValidator() {
102114
return null;
103115
}
104116

105117
/**
106-
* Provide a custom {@link MessageCodesResolver} to use for data binding instead
107-
* of the one created by default in {@link org.springframework.validation.DataBinder}.
118+
* Provide a custom {@link MessageCodesResolver} to use for data binding in
119+
* annotated controller method arguments instead of the one created by
120+
* default in {@link org.springframework.validation.DataBinder}.
108121
*/
109122
@Nullable
110123
default MessageCodesResolver getMessageCodesResolver() {
111124
return null;
112125
}
113126

114127
/**
115-
* Configure view resolution for processing the return values of controller
116-
* methods that rely on resolving a
117-
* {@link org.springframework.web.reactive.result.view.View} to render
118-
* the response with. By default all controller methods rely on view
119-
* resolution unless annotated with {@code @ResponseBody} or explicitly
120-
* return {@code ResponseEntity}. A view may be specified explicitly with
121-
* a String return value or implicitly, e.g. {@code void} return value.
122-
* @see ViewResolverRegistry
128+
* Configure view resolution for rendering responses with a view and a model,
129+
* where the view is typically an HTML template but could also be based on
130+
* an HTTP message writer (e.g. JSON, XML).
131+
* <p>The configured view resolvers will be used for both annotated
132+
* controllers and functional endpoints.
123133
*/
124134
default void configureViewResolvers(ViewResolverRegistry registry) {
125135
}

src/docs/asciidoc/web/webflux-functional.adoc

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -205,20 +205,21 @@ The returned `HttpHandler` can then be used with a number of servers adapters by
205205
A more advanced option is to run with a
206206
<<web-reactive.adoc#webflux-dispatcher-handler,DispatcherHandler>>-based setup through the
207207
<<web-reactive.adoc#webflux-config>> which uses Spring configuration to declare the
208-
components process requests. The WebFlux Java config declares the following components
209-
related to functional endpoints:
210-
211-
* `RouterFunctionMapping` -- this detects one or more `RouterFunction<?>` beans in the
212-
Spring configuration, combines them via `RouterFunction.andOther`, and routes requests to
213-
the resulting, composed `RouterFunction`.
214-
* `HandlerFunctionAdapter` -- simple adapter to invoke a `HandlerFunction` selected to
215-
handle a request.
216-
* `ServerResponseResultHandler` -- invokes the `writeTo` method of the `ServerResponse`
217-
returned by the `HandlerFunction`.
218-
219-
The above allows functional endpoints to fit within the `DispatcherHandler` request
220-
processing lifecycle, and potentially to run side by side with annotated controllers, if
221-
any are declared. This is also the mechanism used in the Spring Boot WebFlux starter.
208+
components quired to process requests. The WebFlux Java config declares the following
209+
infrastructure components to support functional endpoints:
210+
211+
* `RouterFunctionMapping` -- detects one or more `RouterFunction<?>` beans in the Spring
212+
configuration, combines them via `RouterFunction.andOther`, and routes requests to the
213+
resulting composed `RouterFunction`.
214+
* `HandlerFunctionAdapter` -- simple adapter that allows the `DispatcherHandler` to invoke
215+
a `HandlerFunction` that was mapped to a request.
216+
* `ServerResponseResultHandler` -- handles the result from the invocation of a
217+
`HandlerFunction` by invoking the `writeTo` method of the `ServerResponse`.
218+
219+
The above components allow functional endpoints to fit within the `DispatcherHandler` request
220+
processing lifecycle, and also potentially run side by side with annotated controllers, if
221+
any are declared. It is also how functional endpoints are enabled the Spring Boot WebFlux
222+
starter.
222223

223224
Below is example WebFlux Java config (see
224225
<<web-reactive.adoc#webflux-dispatcher-handler,DispatcherHandler>> for how to run):

src/docs/asciidoc/web/webflux.adoc

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1098,13 +1098,16 @@ include::webflux-functional.adoc[leveloffset=+1]
10981098
== WebFlux Java Config
10991099
[.small]#<<web.adoc#mvc-config,Same in Spring MVC>>#
11001100

1101-
The WebFlux Java config provides default configuration suitable for most applications along
1102-
with a configuration API to customize it. For more advanced customizations, not available in
1103-
the configuration API, see <<webflux-config-advanced-java>>.
1101+
The WebFlux Java config declares components required to process requests with annotated
1102+
controllers or functional endpoints, and it offers an API to customize the configuration.
1103+
That means you do not need to understand the underlying beans created by the Java config
1104+
but, if you want to, it's very easy to see them in `WebFluxConfigurationSupport` or read more
1105+
what they are in <<webflux-special-bean-types>>.
1106+
1107+
For more advanced customizations, not available in the configuration API, it is also
1108+
possible to gain full control over the configuration through the
1109+
<<webflux-config-advanced-java>>.
11041110

1105-
You do not need to understand the underlying beans created by the Java config, but it's
1106-
easy to seem them in `WebFluxConfigurationSupport`, and if you want to learn more, see
1107-
<<webflux-special-bean-types>>.
11081111

11091112

11101113

0 commit comments

Comments
 (0)