From 139cde47e2e35561517334d02c0e023ea713c03c Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 19 Apr 2023 10:26:17 -0500 Subject: [PATCH] Fix cross references --- .../modules/ROOT/pages/appendix.adoc | 18 ++--- .../pages/core/aop-api/concise-proxy.adoc | 2 +- .../modules/ROOT/pages/core/aop-api/pfb.adoc | 8 +- .../ROOT/pages/core/aop-api/pointcuts.adoc | 2 +- .../modules/ROOT/pages/core/aop.adoc | 6 +- .../pages/core/aop/aspectj-programmatic.adoc | 2 +- .../ROOT/pages/core/aop/ataspectj.adoc | 2 +- .../ROOT/pages/core/aop/ataspectj/advice.adoc | 28 +++---- .../core/aop/ataspectj/aspectj-support.adoc | 4 +- .../pages/core/aop/ataspectj/example.adoc | 4 +- .../pages/core/aop/ataspectj/pointcuts.adoc | 20 ++--- .../pages/core/aop/introduction-defn.adoc | 4 +- .../pages/core/aop/introduction-proxies.adoc | 4 +- .../core/aop/introduction-spring-defn.adoc | 4 +- .../modules/ROOT/pages/core/aop/schema.adoc | 30 ++++---- .../ROOT/pages/core/aop/using-aspectj.adoc | 24 +++--- .../modules/ROOT/pages/core/aot.adoc | 8 +- .../ROOT/pages/core/appendix/xml-custom.adoc | 16 ++-- .../ROOT/pages/core/appendix/xsd-schemas.adoc | 46 +++++------ .../pages/core/beans/annotation-config.adoc | 12 +-- .../autowired-qualifiers.adoc | 4 +- .../beans/annotation-config/autowired.adoc | 4 +- ...tconstruct-and-predestroy-annotations.adoc | 6 +- .../annotation-config/value-annotations.adoc | 2 +- .../modules/ROOT/pages/core/beans/basics.adoc | 18 ++--- .../ROOT/pages/core/beans/beanfactory.adoc | 2 +- .../pages/core/beans/classpath-scanning.adoc | 14 ++-- .../core/beans/context-introduction.adoc | 14 ++-- .../core/beans/context-load-time-weaver.adoc | 4 +- .../ROOT/pages/core/beans/definition.adoc | 44 +++++------ .../beans/dependencies/factory-autowire.adoc | 12 +-- .../dependencies/factory-collaborators.adoc | 14 ++-- .../beans/dependencies/factory-dependson.adoc | 2 +- .../beans/dependencies/factory-lazy-init.adoc | 2 +- .../factory-method-injection.adoc | 14 ++-- .../factory-properties-detailed.adoc | 20 ++--- .../ROOT/pages/core/beans/environment.adoc | 12 +-- .../pages/core/beans/factory-extension.adoc | 10 +-- .../ROOT/pages/core/beans/factory-nature.adoc | 64 ++++++++-------- .../ROOT/pages/core/beans/factory-scopes.adoc | 32 ++++---- .../ROOT/pages/core/beans/introduction.adoc | 2 +- .../modules/ROOT/pages/core/beans/java.adoc | 18 ++--- .../core/beans/java/bean-annotation.adoc | 28 +++---- .../java/composing-configuration-classes.adoc | 4 +- .../beans/java/configuration-annotation.adoc | 4 +- .../beans/java/instantiating-container.adoc | 2 +- .../ROOT/pages/core/databuffer-codec.adoc | 14 ++-- .../modules/ROOT/pages/core/expressions.adoc | 2 +- .../pages/core/expressions/evaluation.adoc | 6 +- .../pages/core/expressions/language-ref.adoc | 30 ++++---- .../expressions/language-ref/operators.adoc | 8 +- .../language-ref/properties-arrays.adoc | 4 +- .../modules/ROOT/pages/core/null-safety.adoc | 2 +- .../modules/ROOT/pages/core/resources.adoc | 46 +++++------ .../modules/ROOT/pages/core/validation.adoc | 4 +- .../pages/core/validation/beans-beans.adoc | 8 +- .../pages/core/validation/beanvalidation.adoc | 8 +- .../pages/core/validation/conversion.adoc | 2 +- .../ROOT/pages/core/validation/convert.adoc | 4 +- ...uring-formatting-globaldatetimeformat.adoc | 4 +- .../ROOT/pages/core/validation/format.adoc | 4 +- .../ROOT/pages/data-access/appendix.adoc | 10 +-- .../ROOT/pages/data-access/jdbc/advanced.adoc | 2 +- .../pages/data-access/jdbc/connections.adoc | 16 ++-- .../ROOT/pages/data-access/jdbc/core.adoc | 22 +++--- .../jdbc/embedded-database-support.adoc | 10 +-- .../ROOT/pages/data-access/jdbc/object.adoc | 4 +- .../ROOT/pages/data-access/jdbc/packages.adoc | 10 +-- .../ROOT/pages/data-access/jdbc/simple.adoc | 6 +- .../ROOT/pages/data-access/orm/general.adoc | 8 +- .../ROOT/pages/data-access/orm/hibernate.adoc | 8 +- .../pages/data-access/orm/introduction.adoc | 2 +- .../ROOT/pages/data-access/orm/jpa.adoc | 22 +++--- .../modules/ROOT/pages/data-access/oxm.adoc | 14 ++-- .../modules/ROOT/pages/data-access/r2dbc.adoc | 28 +++---- .../ROOT/pages/data-access/transaction.adoc | 22 +++--- .../data-access/transaction/declarative.adoc | 2 +- .../transaction/declarative/annotations.adoc | 24 +++--- .../applying-more-than-just-tx-advice.adoc | 4 +- .../transaction/declarative/aspectj.adoc | 10 +-- .../declarative/first-example.adoc | 4 +- .../transaction/declarative/rolling-back.adoc | 4 +- .../declarative/tx-decl-explained.adoc | 4 +- .../declarative/txadvice-settings.adoc | 2 +- .../data-access/transaction/programmatic.adoc | 4 +- .../solutions-to-common-problems.adoc | 2 +- .../data-access/transaction/strategies.adoc | 8 +- framework-docs/modules/ROOT/pages/index.adoc | 16 ++-- .../ROOT/pages/integration/appendix.adoc | 12 +-- .../modules/ROOT/pages/integration/cache.adoc | 4 +- .../pages/integration/cache/annotations.adoc | 28 +++---- .../integration/cache/declarative-xml.adoc | 4 +- .../ROOT/pages/integration/cache/jsr-107.adoc | 4 +- .../cache/store-configuration.adoc | 2 +- .../pages/integration/cache/strategies.adoc | 4 +- .../modules/ROOT/pages/integration/email.adoc | 2 +- .../ROOT/pages/integration/jms/annotated.adoc | 6 +- .../ROOT/pages/integration/jms/namespace.adoc | 6 +- .../ROOT/pages/integration/jms/receiving.adoc | 4 +- .../ROOT/pages/integration/jms/using.adoc | 12 +-- .../modules/ROOT/pages/integration/jmx.adoc | 2 +- .../ROOT/pages/integration/jmx/exporting.adoc | 12 +-- .../ROOT/pages/integration/jmx/interface.adoc | 8 +- .../ROOT/pages/integration/jmx/naming.adoc | 4 +- .../ROOT/pages/integration/observability.adoc | 10 +-- .../ROOT/pages/integration/rest-clients.adoc | 20 ++--- .../ROOT/pages/integration/scheduling.adoc | 14 ++-- .../modules/ROOT/pages/languages/dynamic.adoc | 40 +++++----- .../modules/ROOT/pages/languages/groovy.adoc | 4 +- .../languages/kotlin/getting-started.adoc | 4 +- .../pages/languages/kotlin/null-safety.adoc | 2 +- .../languages/kotlin/spring-projects-in.adoc | 2 +- .../modules/ROOT/pages/rsocket.adoc | 32 ++++---- .../ROOT/pages/testing/annotations.adoc | 10 +-- .../integration-junit-jupiter.adoc | 68 ++++++++--------- .../annotations/integration-junit4.adoc | 14 ++-- .../testing/annotations/integration-meta.adoc | 4 +- .../annotations/integration-spring.adoc | 36 ++++----- .../annotation-activeprofiles.adoc | 6 +- .../annotation-bootstrapwith.adoc | 2 +- .../annotation-contextconfiguration.adoc | 6 +- .../annotation-contexthierarchy.adoc | 2 +- .../annotation-dynamicpropertysource.adoc | 2 +- .../annotation-recordapplicationevents.adoc | 2 +- .../annotation-rollback.adoc | 2 +- .../integration-spring/annotation-sql.adoc | 2 +- .../annotation-testexecutionlisteners.adoc | 6 +- .../annotation-testpropertysource.adoc | 2 +- .../annotations/integration-standard.adoc | 2 +- .../ROOT/pages/testing/integration.adoc | 36 ++++----- .../ROOT/pages/testing/introduction.adoc | 4 +- .../modules/ROOT/pages/testing/resources.adoc | 4 +- .../testing/spring-mvc-test-framework.adoc | 2 +- .../async-requests.adoc | 4 +- .../server-htmlunit.adoc | 2 +- .../server-htmlunit/geb.adoc | 6 +- .../server-htmlunit/mah.adoc | 8 +- .../server-htmlunit/webdriver.adoc | 8 +- .../server-htmlunit/why.adoc | 6 +- .../server-performing-requests.adoc | 2 +- .../server-setup-options.adoc | 4 +- .../server-static-imports.adoc | 2 +- .../spring-mvc-test-framework/server.adoc | 4 +- .../ROOT/pages/testing/support-jdbc.adoc | 8 +- .../pages/testing/testcontext-framework.adoc | 8 +- .../testing/testcontext-framework/aot.adoc | 8 +- .../application-events.adoc | 6 +- .../testcontext-framework/ctx-management.adoc | 26 +++---- .../ctx-management/caching.adoc | 8 +- .../dynamic-property-sources.adoc | 4 +- .../ctx-management/env-profiles.adoc | 2 +- .../ctx-management/groovy.adoc | 4 +- .../ctx-management/hierarchies.adoc | 2 +- .../ctx-management/inheritance.adoc | 2 +- .../ctx-management/javaconfig.adoc | 2 +- .../ctx-management/property-sources.adoc | 4 +- .../ctx-management/web-mocks.adoc | 2 +- .../testcontext-framework/executing-sql.adoc | 18 ++--- .../testcontext-framework/fixture-di.adoc | 8 +- .../key-abstractions.adoc | 2 +- .../parallel-test-execution.adoc | 2 +- .../support-classes.adoc | 34 ++++----- .../testcontext-framework/tel-config.adoc | 14 ++-- .../test-execution-events.adoc | 6 +- .../testing/testcontext-framework/tx.adoc | 20 ++--- .../web-scoped-beans.adoc | 6 +- .../modules/ROOT/pages/testing/unit.adoc | 26 +++---- .../ROOT/pages/testing/webtestclient.adoc | 24 +++--- .../modules/ROOT/pages/web-reactive.adoc | 16 ++-- framework-docs/modules/ROOT/pages/web.adoc | 6 +- .../modules/ROOT/pages/web/integration.adoc | 4 +- .../modules/ROOT/pages/web/webflux-cors.adoc | 12 +-- .../ROOT/pages/web/webflux-functional.adoc | 38 +++++----- .../modules/ROOT/pages/web/webflux-view.adoc | 42 +++++----- .../ROOT/pages/web/webflux-webclient.adoc | 4 +- .../web/webflux-webclient/client-builder.adoc | 6 +- .../web/webflux-webclient/client-context.adoc | 2 +- .../ROOT/pages/web/webflux-websocket.adoc | 20 ++--- .../web/webflux/ann-rest-exceptions.adoc | 16 ++-- .../ROOT/pages/web/webflux/caching.adoc | 14 ++-- .../ROOT/pages/web/webflux/config.adoc | 44 +++++------ .../ROOT/pages/web/webflux/controller.adoc | 2 +- .../web/webflux/controller/ann-advice.adoc | 6 +- .../webflux/controller/ann-exceptions.adoc | 16 ++-- .../webflux/controller/ann-initbinder.adoc | 6 +- .../web/webflux/controller/ann-methods.adoc | 2 +- .../controller/ann-methods/arguments.adoc | 32 ++++---- .../controller/ann-methods/cookievalue.adoc | 4 +- .../controller/ann-methods/httpentity.adoc | 4 +- .../controller/ann-methods/jackson.adoc | 2 +- .../ann-methods/matrix-variables.adoc | 2 +- .../ann-methods/modelattrib-method-args.adoc | 14 ++-- .../ann-methods/multipart-forms.adoc | 8 +- .../controller/ann-methods/requestattrib.adoc | 2 +- .../controller/ann-methods/requestbody.adoc | 6 +- .../controller/ann-methods/requestheader.adoc | 4 +- .../controller/ann-methods/requestparam.adoc | 6 +- .../controller/ann-methods/responsebody.adoc | 12 +-- .../ann-methods/responseentity.adoc | 6 +- .../controller/ann-methods/return-types.adoc | 18 ++--- .../ann-methods/sessionattribute.adoc | 4 +- .../ann-methods/sessionattributes.adoc | 2 +- .../ann-methods/typeconversion.adoc | 6 +- .../controller/ann-modelattrib-methods.adoc | 6 +- .../controller/ann-requestmapping.adoc | 24 +++--- .../pages/web/webflux/controller/ann.adoc | 6 +- .../pages/web/webflux/dispatcher-handler.adoc | 52 ++++++------- .../modules/ROOT/pages/web/webflux/http2.adoc | 2 +- .../ROOT/pages/web/webflux/new-framework.adoc | 24 +++--- .../pages/web/webflux/reactive-spring.adoc | 76 +++++++++---------- .../ROOT/pages/web/webflux/security.adoc | 2 +- .../ROOT/pages/web/webflux/uri-building.adoc | 2 +- .../modules/ROOT/pages/web/webmvc-client.adoc | 8 +- .../modules/ROOT/pages/web/webmvc-cors.adoc | 14 ++-- .../ROOT/pages/web/webmvc-functional.adoc | 28 +++---- .../modules/ROOT/pages/web/webmvc-test.adoc | 12 +-- .../modules/ROOT/pages/web/webmvc-view.adoc | 4 +- .../pages/web/webmvc-view/mvc-freemarker.adoc | 8 +- .../pages/web/webmvc-view/mvc-jackson.adoc | 6 +- .../ROOT/pages/web/webmvc-view/mvc-jsp.adoc | 4 +- .../pages/web/webmvc-view/mvc-script.adoc | 6 +- .../pages/web/webmvc-view/mvc-thymeleaf.adoc | 2 +- .../web/webmvc-view/mvc-xml-marshalling.adoc | 2 +- .../ROOT/pages/web/webmvc-view/mvc-xslt.adoc | 2 +- .../modules/ROOT/pages/web/webmvc.adoc | 2 +- .../ROOT/pages/web/webmvc/filters.adoc | 26 +++---- .../ROOT/pages/web/webmvc/mvc-ann-async.adoc | 50 ++++++------ .../web/webmvc/mvc-ann-rest-exceptions.adoc | 16 ++-- .../ROOT/pages/web/webmvc/mvc-caching.adoc | 16 ++-- .../ROOT/pages/web/webmvc/mvc-config.adoc | 8 +- .../web/webmvc/mvc-config/advanced-java.adoc | 2 +- .../mvc-config/content-negotiation.adoc | 4 +- .../web/webmvc/mvc-config/conversion.adoc | 4 +- .../web/webmvc/mvc-config/customize.adoc | 2 +- .../pages/web/webmvc/mvc-config/enable.adoc | 4 +- .../webmvc/mvc-config/message-converters.adoc | 2 +- .../web/webmvc/mvc-config/path-matching.adoc | 2 +- .../webmvc/mvc-config/static-resources.adoc | 4 +- .../web/webmvc/mvc-config/validation.adoc | 6 +- .../web/webmvc/mvc-config/view-resolvers.adoc | 2 +- .../ROOT/pages/web/webmvc/mvc-controller.adoc | 2 +- .../web/webmvc/mvc-controller/ann-advice.adoc | 6 +- .../mvc-controller/ann-exceptionhandler.adoc | 26 +++---- .../webmvc/mvc-controller/ann-initbinder.adoc | 6 +- .../webmvc/mvc-controller/ann-methods.adoc | 2 +- .../mvc-controller/ann-methods/arguments.adoc | 34 ++++----- .../ann-methods/cookievalue.adoc | 4 +- .../ann-methods/httpentity.adoc | 4 +- .../mvc-controller/ann-methods/jackson.adoc | 2 +- .../ann-methods/matrix-variables.adoc | 4 +- .../ann-methods/modelattrib-method-args.adoc | 16 ++-- .../ann-methods/multipart-forms.adoc | 8 +- .../ann-methods/redirecting-passing-data.adoc | 2 +- .../ann-methods/requestattrib.adoc | 2 +- .../ann-methods/requestbody.adoc | 6 +- .../ann-methods/requestheader.adoc | 4 +- .../ann-methods/requestparam.adoc | 4 +- .../ann-methods/responsebody.adoc | 10 +-- .../ann-methods/responseentity.adoc | 6 +- .../ann-methods/return-types.adoc | 28 +++---- .../ann-methods/sessionattribute.adoc | 4 +- .../ann-methods/sessionattributes.adoc | 2 +- .../ann-methods/typeconversion.adoc | 6 +- .../ann-modelattrib-methods.adoc | 6 +- .../mvc-controller/ann-requestmapping.adoc | 36 ++++----- .../pages/web/webmvc/mvc-controller/ann.adoc | 6 +- .../ROOT/pages/web/webmvc/mvc-http2.adoc | 4 +- .../ROOT/pages/web/webmvc/mvc-security.adoc | 2 +- .../ROOT/pages/web/webmvc/mvc-servlet.adoc | 8 +- .../pages/web/webmvc/mvc-servlet/config.adoc | 6 +- .../webmvc/mvc-servlet/context-hierarchy.adoc | 2 +- .../webmvc/mvc-servlet/exceptionhandlers.adoc | 8 +- .../handlermapping-interceptor.adoc | 4 +- .../mvc-servlet/handlermapping-path.adoc | 4 +- .../webmvc/mvc-servlet/localeresolver.adoc | 12 +-- .../pages/web/webmvc/mvc-servlet/logging.adoc | 4 +- .../web/webmvc/mvc-servlet/multipart.adoc | 2 +- .../web/webmvc/mvc-servlet/sequence.adoc | 10 +-- .../mvc-servlet/special-bean-types.adoc | 28 +++---- .../web/webmvc/mvc-servlet/themeresolver.adoc | 2 +- .../web/webmvc/mvc-servlet/viewresolver.adoc | 18 ++--- .../pages/web/webmvc/mvc-uri-building.adoc | 6 +- .../modules/ROOT/pages/web/websocket.adoc | 2 +- .../ROOT/pages/web/websocket/fallback.adoc | 4 +- .../ROOT/pages/web/websocket/server.adoc | 16 ++-- .../pages/web/websocket/stomp/benefits.adoc | 2 +- .../pages/web/websocket/stomp/client.adoc | 4 +- .../stomp/configuration-performance.adoc | 2 +- .../pages/web/websocket/stomp/enable.adoc | 6 +- .../websocket/stomp/handle-annotations.adoc | 22 +++--- .../stomp/handle-broker-relay-configure.adoc | 2 +- .../websocket/stomp/handle-broker-relay.adoc | 2 +- .../websocket/stomp/handle-simple-broker.adoc | 2 +- .../web/websocket/stomp/interceptors.adoc | 2 +- .../web/websocket/stomp/server-config.adoc | 2 +- .../web/websocket/stomp/user-destination.adoc | 2 +- 296 files changed, 1505 insertions(+), 1505 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/appendix.adoc b/framework-docs/modules/ROOT/pages/appendix.adoc index 3a75550f6e..c25f35e2de 100644 --- a/framework-docs/modules/ROOT/pages/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/appendix.adoc @@ -30,7 +30,7 @@ for details. | `spring.expression.compiler.mode` | The mode to use when compiling expressions for the -<>. +xref:core/expressions/evaluation.adoc#expressions-compiler-configuration[Spring Expression Language]. | `spring.getenv.ignore` | Instructs Spring to ignore operating system environment variables if a Spring @@ -41,12 +41,12 @@ for details. | `spring.index.ignore` | Instructs Spring to ignore the components index located in -`META-INF/spring.components`. See <>. +`META-INF/spring.components`. See xref:core/beans/classpath-scanning.adoc#beans-scanning-index[Generating an Index of Candidate Components] +. | `spring.jdbc.getParameterType.ignore` | Instructs Spring to ignore `java.sql.ParameterMetaData.getParameterType` completely. -See the note in <>. +See the note in xref:data-access/jdbc/advanced.adoc#jdbc-batch-list[Batch Operations with a List of Objects]. | `spring.jndi.ignore` | Instructs Spring to ignore a default JNDI environment, as an optimization for scenarios @@ -62,17 +62,17 @@ for details. | `spring.test.constructor.autowire.mode` | The default _test constructor autowire mode_ to use if `@TestConstructor` is not present -on a test class. See <>. +on a test class. See xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[Changing the default test constructor autowire mode] +. | `spring.test.context.cache.maxSize` | The maximum size of the context cache in the _Spring TestContext Framework_. See -<>. +xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching]. | `spring.test.enclosing.configuration` | The default _enclosing configuration inheritance mode_ to use if `@NestedTestConfiguration` is not present on a test class. See -<>. +xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[Changing the default enclosing configuration inheritance mode] +. |=== diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc index 7fa0edea71..a0218c7630 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc @@ -58,7 +58,7 @@ we override the transaction propagation settings: Note that in the parent bean example, we explicitly marked the parent bean definition as being abstract by setting the `abstract` attribute to `true`, as described -<>, so that it may not actually ever be +xref:core/beans/child-bean-definitions.adoc[previously], so that it may not actually ever be instantiated. Application contexts (but not simple bean factories), by default, pre-instantiate all singletons. Therefore, it is important (at least for singleton beans) that, if you have a (parent) bean definition that you intend to use only as a template, diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc index 4de522e0c9..4ede450416 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc @@ -40,7 +40,7 @@ In common with most `FactoryBean` implementations provided with Spring, the `ProxyFactoryBean` class is itself a JavaBean. Its properties are used to: * Specify the target you want to proxy. -* Specify whether to use CGLIB (described later and see also <>). +* Specify whether to use CGLIB (described later and see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]). Some key properties are inherited from `org.springframework.aop.framework.ProxyConfig` (the superclass for all AOP proxy factories in Spring). These key properties include @@ -48,7 +48,7 @@ the following: * `proxyTargetClass`: `true` if the target class is to be proxied, rather than the target class's interfaces. If this property value is set to `true`, then CGLIB proxies - are created (but see also <>). + are created (but see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]). * `optimize`: Controls whether or not aggressive optimizations are applied to proxies created through CGLIB. You should not blithely use this setting unless you fully understand how the relevant AOP proxy handles optimization. This is currently used @@ -66,7 +66,7 @@ the following: Other properties specific to `ProxyFactoryBean` include the following: * `proxyInterfaces`: An array of `String` interface names. If this is not supplied, a CGLIB - proxy for the target class is used (but see also <>). + proxy for the target class is used (but see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]). * `interceptorNames`: A `String` array of `Advisor`, interceptor, or other advice names to apply. Ordering is significant, on a first come-first served basis. That is to say that the first interceptor in the list is the first to be able to intercept the @@ -78,7 +78,7 @@ factories. You cannot mention bean references here, since doing so results in th + You can append an interceptor name with an asterisk (`*`). Doing so results in the application of all advisor beans with names that start with the part before the asterisk -to be applied. You can find an example of using this feature in <>. +to be applied. You can find an example of using this feature in xref:core/aop-api/pfb.adoc#aop-global-advisors[Using "`Global`" Advisors]. * singleton: Whether or not the factory should return a single object, no matter how often the `getObject()` method is called. Several `FactoryBean` implementations offer diff --git a/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc b/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc index 334097228e..a99cfd000d 100644 --- a/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc @@ -92,7 +92,7 @@ Since 2.0, the most important type of pointcut used by Spring is `org.springframework.aop.aspectj.AspectJExpressionPointcut`. This is a pointcut that uses an AspectJ-supplied library to parse an AspectJ pointcut expression string. -See the <> for a discussion of supported AspectJ pointcut primitives. +See the xref:core/aop.adoc[previous chapter] for a discussion of supported AspectJ pointcut primitives. diff --git a/framework-docs/modules/ROOT/pages/core/aop.adoc b/framework-docs/modules/ROOT/pages/core/aop.adoc index 1421a1bacd..3d86b381f3 100644 --- a/framework-docs/modules/ROOT/pages/core/aop.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop.adoc @@ -15,18 +15,18 @@ to), AOP complements Spring IoC to provide a very capable middleware solution. .Spring AOP with AspectJ pointcuts **** Spring provides simple and powerful ways of writing custom aspects by using either a -<> or the <>. +xref:core/aop/schema.adoc[schema-based approach] or the xref:core/aop/ataspectj.adoc[@AspectJ annotation style]. Both of these styles offer fully typed advice and use of the AspectJ pointcut language while still using Spring AOP for weaving. This chapter discusses the schema- and @AspectJ-based AOP support. -The lower-level AOP support is discussed in <>. +The lower-level AOP support is discussed in xref:core/aop-api.adoc[the following chapter]. **** AOP is used in the Spring Framework to: * Provide declarative enterprise services. The most important such service is - <>. + xref:data-access/transaction/declarative.adoc[declarative transaction management]. * Let users implement custom aspects, complementing their use of OOP with AOP. NOTE: If you are interested only in generic declarative services or other pre-packaged diff --git a/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc b/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc index 8e76aadb60..66fbd2209b 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc @@ -4,7 +4,7 @@ In addition to declaring aspects in your configuration by using either `` or ``, it is also possible to programmatically create proxies that advise target objects. For the full details of Spring's AOP API, see the -<>. Here, we want to focus on the ability to automatically +xref:core/aop-api.adoc[next chapter]. Here, we want to focus on the ability to automatically create proxies by using @AspectJ aspects. You can use the `org.springframework.aop.aspectj.annotation.AspectJProxyFactory` class diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc index bcda901515..7adfe44de7 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc @@ -9,7 +9,7 @@ for pointcut parsing and matching. The AOP runtime is still pure Spring AOP, tho there is no dependency on the AspectJ compiler or weaver. NOTE: Using the AspectJ compiler and weaver enables use of the full AspectJ language and -is discussed in <>. +is discussed in xref:core/aop/using-aspectj.adoc[Using AspectJ with Spring Applications]. diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc index 0b1f36c11a..856e660412 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc @@ -3,7 +3,7 @@ Advice is associated with a pointcut expression and runs before, after, or around method executions matched by the pointcut. The pointcut expression may be either an _inline -pointcut_ or a reference to a <>. +pointcut_ or a reference to a xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[_named pointcut_]. [[aop-advice-before]] @@ -44,7 +44,7 @@ The following example uses an inline pointcut expression. } ---- -If we use a <>, we can rewrite the preceding example +If we use a xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[named pointcut], we can rewrite the preceding example as follows: [source,java,indent=0,subs="verbatim",role="primary"] @@ -352,7 +352,7 @@ execution-only semantics. You only need to be aware of this difference if you co `@AspectJ` aspects written for Spring and use `proceed` with arguments with the AspectJ compiler and weaver. There is a way to write such aspects that is 100% compatible across both Spring AOP and AspectJ, and this is discussed in the -<>. +xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-proceeding-with-the-call[following section on advice parameters]. ==== The value returned by the around advice is the return value seen by the caller of the @@ -536,7 +536,7 @@ The following shows the advice that matches the execution of `@Auditable` method // ... } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin @@ -547,7 +547,7 @@ The following shows the advice that matches the execution of `@Auditable` method // ... } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [[aop-ataspectj-advice-params-generics]] === Advice Parameters and Generics @@ -633,7 +633,7 @@ of determining parameter names, an exception will be thrown. `AspectJAnnotationParameterNameDiscoverer` :: Uses parameter names that have been explicitly specified by the user via the `argNames` attribute in the corresponding advice or - pointcut annotation. See <> for details. + pointcut annotation. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params-names-explicit[Explicit Argument Names] for details. `KotlinReflectionParameterNameDiscoverer` :: Uses Kotlin reflection APIs to determine parameter names. This discoverer is only used if such APIs are present on the classpath. `StandardReflectionParameterNameDiscoverer` :: Uses the standard `java.lang.reflect.Parameter` @@ -679,7 +679,7 @@ The following example shows how to use the `argNames` attribute: // ... use code and bean } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. [source,kotlin,indent=0,subs="verbatim",role="secondary"] @@ -693,7 +693,7 @@ The following example shows how to use the `argNames` attribute: // ... use code and bean } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. If the first parameter is of type `JoinPoint`, `ProceedingJoinPoint`, or @@ -712,7 +712,7 @@ point object, the `argNames` attribute does not need to include it: // ... use code, bean, and jp } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. [source,kotlin,indent=0,subs="verbatim",role="secondary"] @@ -726,7 +726,7 @@ point object, the `argNames` attribute does not need to include it: // ... use code, bean, and jp } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. <2> Declares `bean` and `auditable` as the argument names. The special treatment given to the first parameter of type `JoinPoint`, @@ -743,7 +743,7 @@ the `argNames` attribute: // ... use jp } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin @@ -753,7 +753,7 @@ the `argNames` attribute: // ... use jp } ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. [[aop-ataspectj-advice-proceeding-with-the-call]] @@ -776,7 +776,7 @@ The following example shows how to do so: return pjp.proceed(new Object[] {newPattern}); } ---- -<1> References the `inDataAccessLayer` named pointcut defined in <>. +<1> References the `inDataAccessLayer` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin @@ -790,7 +790,7 @@ The following example shows how to do so: return pjp.proceed(arrayOf(newPattern)) } ---- -<1> References the `inDataAccessLayer` named pointcut defined in <>. +<1> References the `inDataAccessLayer` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. In many cases, you do this binding anyway (as in the preceding example). diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc index e0725013ea..c75a21e7e4 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc @@ -47,8 +47,8 @@ element, as the following example shows: ---- This assumes that you use schema support as described in -<>. -See <> for how to +xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration]. +See xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-aop[the AOP schema] for how to import the tags in the `aop` namespace. diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc index 46507ec9ff..d16aba8949 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc @@ -56,7 +56,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl } } ---- -<1> References the `businessService` named pointcut defined in <>. +<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin @@ -97,7 +97,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl } } ---- -<1> References the `businessService` named pointcut defined in <>. +<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. Note that the aspect implements the `Ordered` interface so that we can set the precedence of the aspect higher than the transaction advice (we want a fresh transaction each time we diff --git a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc index 4ddddf4fb8..722405ef76 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc @@ -99,7 +99,7 @@ If a pointcut is strictly meant to be public-only, even in a CGLIB proxy scenari potential non-public interactions through proxies, it needs to be defined accordingly. If your interception needs include method calls or even constructors within the target -class, consider the use of Spring-driven <> instead +class, consider the use of Spring-driven xref:core/aop/using-aspectj.adoc#aop-aj-ltw[native AspectJ weaving] instead of Spring's proxy-based AOP framework. This constitutes a different mode of AOP usage with different characteristics, so be sure to make yourself familiar with weaving before making a decision. @@ -350,8 +350,8 @@ could write the following which references the ---- -The `` and `` elements are discussed in <>. The -transaction elements are discussed in <>. +The `` and `` elements are discussed in xref:core/aop/schema.adoc[Schema-based AOP Support]. The +transaction elements are discussed in xref:data-access/transaction.adoc[Transaction Management]. [[aop-pointcuts-examples]] @@ -444,7 +444,7 @@ sub-packages: this(com.xyz.service.AccountService) ---- + -NOTE: `this` is more commonly used in a binding form. See the section on <> +NOTE: `this` is more commonly used in a binding form. See the section on xref:core/aop/ataspectj/advice.adoc[Declaring Advice] for how to make the proxy object available in the advice body. * Any join point (method execution only in Spring AOP) where the target object @@ -455,7 +455,7 @@ implements the `AccountService` interface: target(com.xyz.service.AccountService) ---- + -NOTE: `target` is more commonly used in a binding form. See the <> section +NOTE: `target` is more commonly used in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the target object available in the advice body. * Any join point (method execution only in Spring AOP) that takes a single parameter @@ -466,7 +466,7 @@ and where the argument passed at runtime is `Serializable`: args(java.io.Serializable) ---- + -NOTE: `args` is more commonly used in a binding form. See the <> section +NOTE: `args` is more commonly used in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the method arguments available in the advice body. + Note that the pointcut given in this example is different from `execution(* @@ -482,7 +482,7 @@ parameter of type `Serializable`. @target(org.springframework.transaction.annotation.Transactional) ---- + -NOTE: You can also use `@target` in a binding form. See the <> section for +NOTE: You can also use `@target` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the annotation object available in the advice body. * Any join point (method execution only in Spring AOP) where the declared type of the @@ -493,7 +493,7 @@ target object has an `@Transactional` annotation: @within(org.springframework.transaction.annotation.Transactional) ---- + -NOTE: You can also use `@within` in a binding form. See the <> section for +NOTE: You can also use `@within` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the annotation object available in the advice body. * Any join point (method execution only in Spring AOP) where the executing method has an @@ -504,7 +504,7 @@ how to make the annotation object available in the advice body. @annotation(org.springframework.transaction.annotation.Transactional) ---- + -NOTE: You can also use `@annotation` in a binding form. See the <> section +NOTE: You can also use `@annotation` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for how to make the annotation object available in the advice body. * Any join point (method execution only in Spring AOP) which takes a single parameter, @@ -515,7 +515,7 @@ and where the runtime type of the argument passed has the `@Classified` annotati @args(com.xyz.security.Classified) ---- + -NOTE: You can also use `@args` in a binding form. See the <> section +NOTE: You can also use `@args` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section how to make the annotation object(s) available in the advice body. * Any join point (method execution only in Spring AOP) on a Spring bean named diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc index 55ec9db45e..82b705f17c 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc @@ -8,8 +8,8 @@ However, it would be even more confusing if Spring used its own terminology. * Aspect: A modularization of a concern that cuts across multiple classes. Transaction management is a good example of a crosscutting concern in enterprise Java applications. In Spring AOP, aspects are implemented by using regular classes - (the <>) or regular classes annotated with the - `@Aspect` annotation (the <>). + (the xref:core/aop/schema.adoc[schema-based approach]) or regular classes annotated with the + `@Aspect` annotation (the xref:core/aop/ataspectj.adoc[@AspectJ style]). * Join point: A point during the execution of a program, such as the execution of a method or the handling of an exception. In Spring AOP, a join point always represents a method execution. diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc index 872673dbf4..de27700eaa 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc @@ -8,12 +8,12 @@ Spring AOP can also use CGLIB proxies. This is necessary to proxy classes rather interfaces. By default, CGLIB is used if a business object does not implement an interface. As it is good practice to program to interfaces rather than classes, business classes normally implement one or more business interfaces. It is possible to -<>, in those (hopefully rare) cases where you +xref:core/aop/proxying.adoc[force the use of CGLIB], in those (hopefully rare) cases where you need to advise a method that is not declared on an interface or where you need to pass a proxied object to a method as a concrete type. It is important to grasp the fact that Spring AOP is proxy-based. See -<> for a thorough examination of exactly what this +xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[Understanding AOP Proxies] for a thorough examination of exactly what this implementation detail actually means. diff --git a/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc b/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc index 48110b52cd..84ef5d6e58 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc @@ -30,7 +30,7 @@ frameworks such as AspectJ are valuable and that they are complementary, rather competition. Spring seamlessly integrates Spring AOP and IoC with AspectJ, to enable all uses of AOP within a consistent Spring-based application architecture. This integration does not affect the Spring AOP API or the AOP Alliance -API. Spring AOP remains backward-compatible. See <> +API. Spring AOP remains backward-compatible. See xref:core/aop-api.adoc[the following chapter] for a discussion of the Spring AOP APIs. [NOTE] @@ -52,7 +52,7 @@ configuration-style approach. The fact that this chapter chooses to introduce th @AspectJ-style approach first should not be taken as an indication that the Spring team favors the @AspectJ annotation-style approach over the Spring XML configuration-style. -See <> for a more complete discussion of the advantages and disadvantages of +See xref:core/aop/choosing.adoc[Choosing which AOP Declaration Style to Use] for a more complete discussion of the advantages and disadvantages of each style. ==== diff --git a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc index a0fe4a2474..875bcc2d80 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/schema.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/schema.adoc @@ -5,12 +5,12 @@ If you prefer an XML-based format, Spring also offers support for defining aspec using the `aop` namespace tags. The exact same pointcut expressions and advice kinds as when using the @AspectJ style are supported. Hence, in this section we focus on that syntax and refer the reader to the discussion in the previous section -(<>) for an understanding of writing pointcut expressions and the binding +(xref:core/aop/ataspectj.adoc[@AspectJ support]) for an understanding of writing pointcut expressions and the binding of advice parameters. To use the aop namespace tags described in this section, you need to import the -`spring-aop` schema, as described in <>. See <> +`spring-aop` schema, as described in xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration] +. See xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-aop[the AOP schema] for how to import the tags in the `aop` namespace. Within your Spring configurations, all aspect and advisor elements must be placed within @@ -19,7 +19,7 @@ application context configuration). An `` element can contain pointc advisor, and aspect elements (note that these must be declared in that order). WARNING: The `` style of configuration makes heavy use of Spring's -<> mechanism. This can cause issues (such as advice +xref:core/aop-api/autoproxy.adoc[auto-proxying] mechanism. This can cause issues (such as advice not being woven) if you already use explicit auto-proxying through the use of `BeanNameAutoProxyCreator` or something similar. The recommended usage pattern is to use either only the `` style or only the `AutoProxyCreator` style and @@ -75,7 +75,7 @@ be defined as follows: ---- Note that the pointcut expression itself uses the same AspectJ pointcut expression -language as described in <>. If you use the schema based declaration +language as described in xref:core/aop/ataspectj.adoc[@AspectJ support]. If you use the schema based declaration style, you can also refer to _named pointcuts_ defined in `@Aspect` types within the pointcut expression. Thus, another way of defining the above pointcut would be as follows: @@ -88,7 +88,7 @@ pointcut expression. Thus, another way of defining the above pointcut would be a ---- -<1> References the `businessService` named pointcut defined in <>. +<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions]. Declaring a pointcut _inside_ an aspect is very similar to declaring a top-level pointcut, as the following example shows: @@ -203,10 +203,10 @@ Before advice runs before a matched method execution. It is declared inside an ---- In the example above, `dataAccessOperation` is the `id` of a _named pointcut_ defined at -the top (``) level (see <>). +the top (``) level (see xref:core/aop/schema.adoc#aop-schema-pointcuts[Declaring a Pointcut]). NOTE: As we noted in the discussion of the @AspectJ style, using _named pointcuts_ can -significantly improve the readability of your code. See <> for +significantly improve the readability of your code. See xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions] for details. To define the pointcut inline instead, replace the `pointcut-ref` attribute with a @@ -379,7 +379,7 @@ Invoking `proceed()` without arguments will result in the caller's original argu being supplied to the underlying method when it is invoked. For advanced use cases, there is an overloaded variant of the `proceed()` method which accepts an array of arguments (`Object[]`). The values in the array will be used as the arguments to the underlying -method when it is invoked. See <> for notes on calling +method when it is invoked. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-around-advice[Around Advice] for notes on calling `proceed` with an `Object[]`. The following example shows how to declare around advice in XML: @@ -426,11 +426,11 @@ The implementation of the `doBasicProfiling` advice can be exactly the same as i The schema-based declaration style supports fully typed advice in the same way as described for the @AspectJ support -- by matching pointcut parameters by name against -advice method parameters. See <> for details. If you wish +advice method parameters. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params[Advice Parameters] for details. If you wish to explicitly specify argument names for the advice methods (not relying on the detection strategies previously described), you can do so by using the `arg-names` attribute of the advice element, which is treated in the same manner as the `argNames` -attribute in an advice annotation (as described in <>). +attribute in an advice annotation (as described in xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params-names[Determining Argument Names]). The following example shows how to specify an argument name in XML: [source,xml,indent=0,subs="verbatim"] @@ -440,7 +440,7 @@ The following example shows how to specify an argument name in XML: method="audit" arg-names="auditable" /> ---- -<1> References the `publicMethod` named pointcut defined in <>. +<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions]. The `arg-names` attribute accepts a comma-delimited list of parameter names. @@ -608,7 +608,7 @@ ms % Task name === Advice Ordering When multiple pieces of advice need to run at the same join point (executing method) -the ordering rules are as described in <>. The precedence +the ordering rules are as described in xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice Ordering]. The precedence between aspects is determined via the `order` attribute in the `` element or by either adding the `@Order` annotation to the bean that backs the aspect or by having the bean implement the `Ordered` interface. @@ -718,7 +718,7 @@ The concept of "advisors" comes from the AOP support defined in Spring and does not have a direct equivalent in AspectJ. An advisor is like a small self-contained aspect that has a single piece of advice. The advice itself is represented by a bean and must implement one of the advice interfaces described in -<>. Advisors can take advantage of AspectJ pointcut expressions. +xref:core/aop-api/advice.adoc#aop-api-advice-types[Advice Types in Spring]. Advisors can take advantage of AspectJ pointcut expressions. Spring supports the advisor concept with the `` element. You most commonly see it used in conjunction with transactional advice, which also has its own @@ -756,7 +756,7 @@ use the `order` attribute to define the `Ordered` value of the advisor. == An AOP Schema Example This section shows how the concurrent locking failure retry example from -<> looks when rewritten with the schema support. +xref:core/aop/ataspectj/example.adoc[An AOP Example] looks when rewritten with the schema support. The execution of business services can sometimes fail due to concurrency issues (for example, a deadlock loser). If the operation is retried, it is likely to succeed diff --git a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc index d0c65500d0..ea8cf920a2 100644 --- a/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc +++ b/framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc @@ -8,10 +8,10 @@ alone. Spring ships with a small AspectJ aspect library, which is available stand-alone in your distribution as `spring-aspects.jar`. You need to add this to your classpath in order -to use the aspects in it. <> and <> discuss the -content of this library and how you can use it. <> discusses how to +to use the aspects in it. xref:core/aop/using-aspectj.adoc#aop-atconfigurable[Using AspectJ to Dependency Inject Domain Objects with Spring] and xref:core/aop/using-aspectj.adoc#aop-ajlib-other[Other Spring aspects for AspectJ] discuss the +content of this library and how you can use it. xref:core/aop/using-aspectj.adoc#aop-aj-configure[Configuring AspectJ Aspects by Using Spring IoC] discusses how to dependency inject AspectJ aspects that are woven using the AspectJ compiler. Finally, -<> provides an introduction to load-time weaving for Spring applications +xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework] provides an introduction to load-time weaving for Spring applications that use AspectJ. @@ -108,7 +108,7 @@ annotation. You can specify either `@Configurable(autowire=Autowire.BY_TYPE)` or `@Configurable(autowire=Autowire.BY_NAME)` for autowiring by type or by name, respectively. As an alternative, it is preferable to specify explicit, annotation-driven dependency injection for your `@Configurable` beans through `@Autowired` or `@Inject` -at the field or method level (see <> for further details). +at the field or method level (see xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration] for further details). Finally, you can enable Spring dependency checking for the object references in the newly created and configured object by using the `dependencyCheck` attribute (for example, @@ -158,7 +158,7 @@ Programming Guide]. For this to work, the annotated types must be woven with the AspectJ weaver. You can either use a build-time Ant or Maven task to do this (see, for example, the https://www.eclipse.org/aspectj/doc/released/devguide/antTasks.html[AspectJ Development -Environment Guide]) or load-time weaving (see <>). The +Environment Guide]) or load-time weaving (see xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework]). The `AnnotationBeanConfigurerAspect` itself needs to be configured by Spring (in order to obtain a reference to the bean factory that is to be used to configure new objects). If you use Java-based configuration, you can add `@EnableSpringConfigured` to any @@ -182,7 +182,7 @@ use Java-based configuration, you can add `@EnableSpringConfigured` to any ---- If you prefer XML based configuration, the Spring -<> +xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-context[`context` namespace] defines a convenient `context:spring-configured` element, which you can use as follows: [source,xml,indent=0,subs="verbatim"] @@ -387,7 +387,7 @@ per-`ClassLoader` basis, which is more fine-grained and which can make more sense in a 'single-JVM-multiple-application' environment (such as is found in a typical application server environment). -Further, <>, this support enables +Further, xref:core/aop/using-aspectj.adoc#aop-aj-ltw-environments[in certain environments], this support enables load-time weaving without making any modifications to the application server's launch script that is needed to add `-javaagent:path/to/aspectjweaver.jar` or (as we describe later in this section) `-javaagent:path/to/spring-instrument.jar`. Developers configure @@ -410,9 +410,9 @@ quickly get some performance metrics. We can then apply a finer-grained profilin tool to that specific area immediately afterwards. NOTE: The example presented here uses XML configuration. You can also configure and -use @AspectJ with <>. Specifically, you can use the +use @AspectJ with xref:core/beans/java.adoc[Java configuration]. Specifically, you can use the `@EnableLoadTimeWeaving` annotation as an alternative to `` -(see <> for details). +(see xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[below] for details). The following example shows the profiling aspect, which is not fancy. It is a time-based profiler that uses the @AspectJ-style of aspect declaration: @@ -692,8 +692,8 @@ for AspectJ LTW: * `spring-aop.jar` * `aspectjweaver.jar` -If you use the <>, you also need: +If you use the xref:core/aop/using-aspectj.adoc#aop-aj-ltw-environments-generic[Spring-provided agent to enable instrumentation] +, you also need: * `spring-instrument.jar` @@ -900,7 +900,7 @@ containers. Tomcat, JBoss/WildFly, IBM WebSphere Application Server and Oracle WebLogic Server all provide a general app `ClassLoader` that is capable of local instrumentation. Spring's native LTW may leverage those ClassLoader implementations to provide AspectJ weaving. -You can simply enable load-time weaving, as <>. +You can simply enable load-time weaving, as xref:core/aop/using-aspectj.adoc[described earlier]. Specifically, you do not need to modify the JVM launch script to add `-javaagent:path/to/spring-instrument.jar`. diff --git a/framework-docs/modules/ROOT/pages/core/aot.adoc b/framework-docs/modules/ROOT/pages/core/aot.adoc index d4f0fca362..9a1553db5b 100644 --- a/framework-docs/modules/ROOT/pages/core/aot.adoc +++ b/framework-docs/modules/ROOT/pages/core/aot.adoc @@ -3,7 +3,7 @@ This chapter covers Spring's Ahead of Time (AOT) optimizations. -For AOT support specific to integration tests, see <>. +For AOT support specific to integration tests, see xref:testing/testcontext-framework/aot.adoc[Ahead of Time Support for Tests]. [[core.aot.introduction]] == Introduction to Ahead of Time Optimizations @@ -57,12 +57,12 @@ Let's look at a basic example: include::code:AotProcessingSample[tag=myapplication] Starting this application with the regular runtime involves a number of steps including classpath scanning, configuration class parsing, bean instantiation, and lifecycle callback handling. -Refresh for AOT processing only applies a subset of what happens with a <>. +Refresh for AOT processing only applies a subset of what happens with a xref:core/beans/introduction.adoc[regular `refresh`]. AOT processing can be triggered as follows: include::code:AotProcessingSample[tag=aotcontext] -In this mode, <> are invoked as usual. +In this mode, xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[`BeanFactoryPostProcessor` implementations] are invoked as usual. This includes configuration class parsing, import selectors, classpath scanning, etc. Such steps make sure that the `BeanRegistry` contains the relevant bean definitions for the application. If bean definitions are guarded by conditions (such as `@Profile`), these are discarded at this stage. @@ -108,7 +108,7 @@ It does so using a dedicated `BeanRegistrationAotProcessor`. This interface is used as follows: * Implemented by a `BeanPostProcessor` bean, to replace its runtime behavior. -For instance <> implements this interface to generate code that injects members annotated with `@Autowired`. +For instance xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp-examples-aabpp[`AutowiredAnnotationBeanPostProcessor`] implements this interface to generate code that injects members annotated with `@Autowired`. * Implemented by a type registered in `META-INF/spring/aot.factories` with a key equal to the fully qualified name of the interface. Typically used when the bean definition needs to be tuned for specific features of the core framework. diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc index 8ae321e2b4..aa7f4fda19 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc @@ -10,16 +10,16 @@ integrate such parsers into the Spring IoC container. To facilitate authoring configuration files that use a schema-aware XML editor, Spring's extensible XML configuration mechanism is based on XML Schema. If you are not familiar with Spring's current XML configuration extensions that come with the standard -Spring distribution, you should first read the previous section on <>. +Spring distribution, you should first read the previous section on xref:core/appendix/xsd-schemas.adoc[XML Schemas]. To create new XML configuration extensions: -. <> an XML schema to describe your custom element(s). -. <> a custom `NamespaceHandler` implementation. -. <> one or more `BeanDefinitionParser` implementations +. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-schema[Author] an XML schema to describe your custom element(s). +. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-namespacehandler[Code] a custom `NamespaceHandler` implementation. +. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-parser[Code] one or more `BeanDefinitionParser` implementations (this is where the real work is done). -. <> your new artifacts with Spring. +. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-registration[Register] your new artifacts with Spring. For a unified example, we create an XML extension (a custom XML element) that lets us configure objects of the type @@ -129,7 +129,7 @@ The `NamespaceHandler` interface features three methods: * `BeanDefinitionHolder decorate(Node, BeanDefinitionHolder, ParserContext)`: Called when Spring encounters an attribute or nested element of a different namespace. The decoration of one or more bean definitions is used (for example) with the - <>. + xref:core/beans/factory-scopes.adoc[scopes that Spring supports]. We start by highlighting a simple example, without using decoration, after which we show decoration in a somewhat more advanced example. @@ -541,7 +541,7 @@ setter property for the `components` property. The following listing shows such This works nicely, but it exposes a lot of Spring plumbing to the end user. What we are going to do is write a custom extension that hides away all of this Spring plumbing. -If we stick to <>, we start off +If we stick to xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-introduction[the steps described previously], we start off by creating the XSD schema to define the structure of our custom tag, as the following listing shows: @@ -568,7 +568,7 @@ listing shows: ---- -Again following <>, +Again following xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-introduction[the process described earlier], we then create a custom `NamespaceHandler`: [source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"] diff --git a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc index c5ab44c73a..a948355129 100644 --- a/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc +++ b/framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc @@ -312,7 +312,7 @@ Consider the following example: The preceding configuration uses a Spring `FactoryBean` implementation (the `PropertiesFactoryBean`) to instantiate a `java.util.Properties` instance with values -loaded from the supplied <> location). +loaded from the supplied xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[`Resource`] location). The following example uses a `util:properties` element to make a more concise representation: @@ -494,8 +494,8 @@ If no `set-class` attribute is supplied, the container chooses a `Set` implement The `aop` tags deal with configuring all things AOP in Spring, including Spring's own proxy-based AOP framework and Spring's integration with the AspectJ AOP framework. -These tags are comprehensively covered in the chapter entitled <>. +These tags are comprehensively covered in the chapter entitled xref:core/aop.adoc[Aspect Oriented Programming with Spring] +. In the interest of completeness, to use the tags in the `aop` schema, you need to have the following preamble at the top of your Spring XML configuration file (the text in the @@ -548,9 +548,9 @@ available to you: === Using `` This element activates the replacement of `${...}` placeholders, which are resolved against a -specified properties file (as a <>). This element -is a convenience mechanism that sets up a <> for you. If you need more control over the specific +specified properties file (as a xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Spring resource location]). This element +is a convenience mechanism that sets up a xref:core/beans/factory-extension.adoc#beans-factory-placeholderconfigurer[`PropertySourcesPlaceholderConfigurer`] + for you. If you need more control over the specific `PropertySourcesPlaceholderConfigurer` setup, you can explicitly define it as a bean yourself. @@ -559,50 +559,50 @@ is a convenience mechanism that sets up a <> model -* <>, `@Value`, and `@Lookup` +* Spring's xref:core/beans/basics.adoc#beans-factory-metadata[`@Configuration`] model +* xref:core/beans/annotation-config.adoc[`@Autowired`/`@Inject`], `@Value`, and `@Lookup` * JSR-250's `@Resource`, `@PostConstruct`, and `@PreDestroy` (if available) * JAX-WS's `@WebServiceRef` and EJB 3's `@EJB` (if available) * JPA's `@PersistenceContext` and `@PersistenceUnit` (if available) -* Spring's <> +* Spring's xref:core/beans/context-introduction.adoc#context-functionality-events-annotation[`@EventListener`] Alternatively, you can choose to explicitly activate the individual `BeanPostProcessors` for those annotations. NOTE: This element does not activate processing of Spring's -<> annotation; +xref:data-access/transaction/declarative/annotations.adoc[`@Transactional`] annotation; you can use the <`>> element for that purpose. Similarly, Spring's -<> need to be explicitly -<> as well. +xref:integration/cache/annotations.adoc[caching annotations] need to be explicitly +xref:integration/cache/annotations.adoc#cache-annotation-enable[enabled] as well. [[core.appendix.xsd-schemas-context-component-scan]] === Using `` -This element is detailed in the section on <>. +This element is detailed in the section on xref:core/beans/annotation-config.adoc[annotation-based container configuration] +. [[core.appendix.xsd-schemas-context-ltw]] === Using `` -This element is detailed in the section on <>. +This element is detailed in the section on xref:core/aop/using-aspectj.adoc#aop-aj-ltw[load-time weaving with AspectJ in the Spring Framework] +. [[core.appendix.xsd-schemas-context-sc]] === Using `` -This element is detailed in the section on <>. +This element is detailed in the section on xref:core/aop/using-aspectj.adoc#aop-atconfigurable[using AspectJ to dependency inject domain objects with Spring] +. [[core.appendix.xsd-schemas-context-mbe]] === Using `` -This element is detailed in the section on <>. +This element is detailed in the section on xref:integration/jmx/naming.adoc#jmx-context-mbeanexport[configuring annotation-based MBean export] +. @@ -612,13 +612,13 @@ configuring annotation-based MBean export>>. Last but not least, we have the elements in the `beans` schema. These elements have been in Spring since the very dawn of the framework. Examples of the various elements in the `beans` schema are not shown here because they are quite comprehensively covered -in <> -(and, indeed, in that entire <>). +in xref:core/beans/dependencies/factory-properties-detailed.adoc[dependencies and configuration in detail] +(and, indeed, in that entire xref:web/webmvc-view/mvc-xslt.adoc#mvc-view-xslt-beandefs[chapter]). Note that you can add zero or more key-value pairs to `` XML definitions. What, if anything, is done with this extra metadata is totally up to your own custom logic (and so is typically only of use if you write your own custom elements as described -in the appendix entitled <>). +in the appendix entitled xref:core/appendix/xml-custom.adoc[XML Schema Authoring]). The following example shows the `` element in the context of a surrounding `` (note that, without any logic to interpret it, the metadata is effectively useless diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc index 5c6d43e19d..c369aaa715 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc @@ -14,7 +14,7 @@ while others argue that annotated classes are no longer POJOs and, furthermore, configuration becomes decentralized and harder to control. No matter the choice, Spring can accommodate both styles and even mix them together. -It is worth pointing out that through its <> option, Spring lets +It is worth pointing out that through its xref:core/beans/java.adoc[JavaConfig] option, Spring lets annotations be used in a non-invasive way, without touching the target components' source code and that, in terms of tooling, all configuration styles are supported by https://spring.io/tools[Spring Tools] for Eclipse, Visual Studio Code, and Theia. @@ -24,15 +24,15 @@ An alternative to XML setup is provided by annotation-based configuration, which on bytecode metadata for wiring up components instead of XML declarations. Instead of using XML to describe a bean wiring, the developer moves the configuration into the component class itself by using annotations on the relevant class, method, or field -declaration. As mentioned in <>, using a +declaration. As mentioned in xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp-examples-aabpp[Example: The `AutowiredAnnotationBeanPostProcessor`], using a `BeanPostProcessor` in conjunction with annotations is a common means of extending the -Spring IoC container. For example, the <> -annotation provides the same capabilities as described in <> but +Spring IoC container. For example, the xref:core/beans/annotation-config/autowired.adoc[`@Autowired`] +annotation provides the same capabilities as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators] but with more fine-grained control and wider applicability. In addition, Spring provides support for JSR-250 annotations, such as `@PostConstruct` and `@PreDestroy`, as well as support for JSR-330 (Dependency Injection for Java) annotations contained in the `jakarta.inject` package such as `@Inject` and `@Named`. Details about those annotations -can be found in the <>. +can be found in the xref:core/beans/standard-annotations.adoc[relevant section]. [NOTE] ==== @@ -74,7 +74,7 @@ The `` element implicitly registers the following po application context in which it is defined. This means that, if you put `` in a `WebApplicationContext` for a `DispatcherServlet`, it only checks for `@Autowired` beans in your controllers, and not your services. See -<> for more information. +xref:web/webmvc/mvc-servlet.adoc[The DispatcherServlet] for more information. ==== diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc index 5d2c314078..a63b5e8bba 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc @@ -296,8 +296,8 @@ demonstrates both approaches: ---- -- -In <>, you can see an annotation-based alternative to -providing the qualifier metadata in XML. Specifically, see <>. +In xref:core/beans/classpath-scanning.adoc[Classpath Scanning and Managed Components], you can see an annotation-based alternative to +providing the qualifier metadata in XML. Specifically, see xref:core/beans/classpath-scanning.adoc#beans-scanning-qualifiers[Providing Qualifier Metadata with Annotations]. In some cases, using an annotation without a value may suffice. This can be useful when the annotation serves a more generic purpose and can be applied across diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc index d63163b195..2e5f36016b 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc @@ -4,7 +4,7 @@ [NOTE] ==== JSR 330's `@Inject` annotation can be used in place of Spring's `@Autowired` annotation in the -examples included in this section. See <> for more details. +examples included in this section. See xref:core/beans/standard-annotations.adoc[here] for more details. ==== You can apply the `@Autowired` annotation to constructors, as the following example shows: @@ -38,7 +38,7 @@ necessary if the target bean defines only one constructor to begin with. However several constructors are available and there is no primary/default constructor, at least one of the constructors must be annotated with `@Autowired` in order to instruct the container which one to use. See the discussion on -<> for details. +xref:core/beans/annotation-config/autowired.adoc#beans-autowired-annotation-constructor-resolution[constructor resolution] for details. ==== You can also apply the `@Autowired` annotation to _traditional_ setter methods, diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc index 9194100202..391158c84a 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc @@ -5,8 +5,8 @@ The `CommonAnnotationBeanPostProcessor` not only recognizes the `@Resource` anno but also the JSR-250 lifecycle annotations: `jakarta.annotation.PostConstruct` and `jakarta.annotation.PreDestroy`. Introduced in Spring 2.5, the support for these annotations offers an alternative to the lifecycle callback mechanism described in -<> and -<>. Provided that the +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[initialization callbacks] and +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[destruction callbacks]. Provided that the `CommonAnnotationBeanPostProcessor` is registered within the Spring `ApplicationContext`, a method carrying one of these annotations is invoked at the same point in the lifecycle as the corresponding Spring lifecycle interface method or explicitly declared callback @@ -47,7 +47,7 @@ cleared upon destruction: ---- For details about the effects of combining various lifecycle mechanisms, see -<>. +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-combined-effects[Combining Lifecycle Mechanisms]. [NOTE] ==== diff --git a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc index 7a5dd0a83a..006d8da85e 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc @@ -149,7 +149,7 @@ provide conversion support for your own custom type, you can provide your own } ---- -When `@Value` contains a <> the value will be dynamically +When `@Value` contains a xref:core/expressions.adoc[`SpEL` expression] the value will be dynamically computed at runtime as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/framework-docs/modules/ROOT/pages/core/beans/basics.adoc b/framework-docs/modules/ROOT/pages/core/beans/basics.adoc index d0c4643448..c38218c32c 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/basics.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/basics.adoc @@ -22,7 +22,7 @@ additional metadata formats. In most application scenarios, explicit user code is not required to instantiate one or more instances of a Spring IoC container. For example, in a web application scenario, a simple eight (or so) lines of boilerplate web descriptor XML in the `web.xml` file -of the application typically suffices (see <>). If you use the +of the application typically suffices (see xref:core/beans/context-introduction.adoc#context-create[Convenient ApplicationContext Instantiation for Web Applications]). If you use the https://spring.io/tools[Spring Tools for Eclipse] (an Eclipse-powered development environment), you can easily create this boilerplate configuration with a few mouse clicks or keystrokes. @@ -52,13 +52,13 @@ Spring IoC container. NOTE: XML-based metadata is not the only allowed form of configuration metadata. The Spring IoC container itself is totally decoupled from the format in which this configuration metadata is actually written. These days, many developers choose -<> for their Spring applications. +xref:core/beans/java.adoc[Java-based configuration] for their Spring applications. For information about using other forms of metadata with the Spring container, see: -* <>: define beans using +* xref:core/beans/annotation-config.adoc[Annotation-based configuration]: define beans using annotation-based configuration metadata. -* <>: define beans external to your application +* xref:core/beans/java.adoc[Java-based configuration]: define beans external to your application classes by using Java rather than XML files. To use these features, see the {api-spring-framework}/context/annotation/Configuration.html[`@Configuration`], {api-spring-framework}/context/annotation/Bean.html[`@Bean`], @@ -107,7 +107,7 @@ class name. The value of the `id` attribute can be used to refer to collaborating objects. The XML for referring to collaborating objects is not shown in this example. See -<> for more information. +xref:core/beans/dependencies.adoc[Dependencies] for more information. @@ -133,9 +133,9 @@ as the local file system, the Java `CLASSPATH`, and so on. [NOTE] ==== After you learn about Spring's IoC container, you may want to know more about Spring's -`Resource` abstraction (as described in <>), which provides a convenient +`Resource` abstraction (as described in xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources]), which provides a convenient mechanism for reading an InputStream from locations defined in a URI syntax. In particular, -`Resource` paths are used to construct applications contexts, as described in <>. +`Resource` paths are used to construct applications contexts, as described in xref:core/resources.adoc#resources-app-ctx[Application Contexts and Resource Paths]. ==== The following example shows the service layer objects `(services.xml)` configuration file: @@ -191,7 +191,7 @@ on the JPA Object-Relational Mapping standard). The `property name` element refe name of the JavaBean property, and the `ref` element refers to the name of another bean definition. This linkage between `id` and `ref` elements expresses the dependency between collaborating objects. For details of configuring an object's dependencies, see -<>. +xref:core/beans/dependencies.adoc[Dependencies]. [[beans-factory-xml-import]] @@ -202,7 +202,7 @@ XML configuration file represents a logical layer or module in your architecture You can use the application context constructor to load bean definitions from all these XML fragments. This constructor takes multiple `Resource` locations, as was shown in the -<>. Alternatively, use one or more +xref:core/beans/basics.adoc#beans-factory-instantiation[previous section]. Alternatively, use one or more occurrences of the `` element to load bean definitions from another file or files. The following example shows how to do so: diff --git a/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc b/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc index b8ca8fc3f2..e88c5d196c 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc @@ -43,7 +43,7 @@ by convention (that is, by bean name or by bean type -- in particular, post-proc while a plain `DefaultListableBeanFactory` is agnostic about any special beans. For many extended container features, such as annotation processing and AOP proxying, -the <> is essential. +the xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[`BeanPostProcessor` extension point] is essential. If you use only a plain `DefaultListableBeanFactory`, such post-processors do not get detected and activated by default. This situation could be confusing, because nothing is actually wrong with your bean configuration. Rather, in such a scenario, diff --git a/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc b/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc index 64b3bcf146..e595b82d60 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc @@ -3,7 +3,7 @@ Most examples in this chapter use XML to specify the configuration metadata that produces each `BeanDefinition` within the Spring container. The previous section -(<>) demonstrates how to provide a lot of the configuration +(xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration]) demonstrates how to provide a lot of the configuration metadata through source-level annotations. Even in those examples, however, the "base" bean definitions are explicitly defined in the XML file, while the annotations drive only the dependency injection. This section describes an option for implicitly detecting the @@ -29,7 +29,7 @@ use these features. The `@Repository` annotation is a marker for any class that fulfills the role or stereotype of a repository (also known as Data Access Object or DAO). Among the uses of this marker is the automatic translation of exceptions, as described in -<>. +xref:data-access/orm/general.adoc#orm-exception-translation[Exception Translation]. Spring provides further stereotype annotations: `@Component`, `@Service`, and `@Controller`. `@Component` is a generic stereotype for any Spring-managed component. @@ -52,7 +52,7 @@ supported as a marker for automatic exception translation in your persistence la Many of the annotations provided by Spring can be used as meta-annotations in your own code. A meta-annotation is an annotation that can be applied to another annotation. -For example, the `@Service` annotation mentioned <> +For example, the `@Service` annotation mentioned xref:core/beans/classpath-scanning.adoc#beans-stereotype-annotations[earlier] is meta-annotated with `@Component`, as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -723,7 +723,7 @@ definitions, there is no notion of bean definition inheritance, and inheritance hierarchies at the class level are irrelevant for metadata purposes. For details on web-specific scopes such as "`request`" or "`session`" in a Spring context, -see <>. As with the pre-built annotations for those scopes, +see xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other[Request, Session, Application, and WebSocket Scopes]. As with the pre-built annotations for those scopes, you may also compose your own scoping annotations by using Spring's meta-annotation approach: for example, a custom annotation meta-annotated with `@Scope("prototype")`, possibly also declaring a custom scoped-proxy mode. @@ -762,7 +762,7 @@ an annotation and a bean definition shows: ---- When using certain non-singleton scopes, it may be necessary to generate proxies for the -scoped objects. The reasoning is described in <>. +scoped objects. The reasoning is described in xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[Scoped Beans as Dependencies]. For this purpose, a scoped-proxy attribute is available on the component-scan element. The three possible values are: `no`, `interfaces`, and `targetClass`. For example, the following configuration results in standard JDK dynamic proxies: @@ -798,7 +798,7 @@ the following configuration results in standard JDK dynamic proxies: [[beans-scanning-qualifiers]] == Providing Qualifier Metadata with Annotations -The `@Qualifier` annotation is discussed in <>. +The `@Qualifier` annotation is discussed in xref:core/beans/annotation-config/autowired-qualifiers.adoc[Fine-tuning Annotation-based Autowiring with Qualifiers]. The examples in that section demonstrate the use of the `@Qualifier` annotation and custom qualifier annotations to provide fine-grained control when you resolve autowire candidates. Because those examples were based on XML bean definitions, the qualifier @@ -930,7 +930,7 @@ on the classpath. If an index is partially available for some libraries (or use but could not be built for the whole application, you can fall back to a regular classpath arrangement (as though no index were present at all) by setting `spring.index.ignore` to `true`, either as a JVM system property or via the -<> mechanism. +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism. diff --git a/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc b/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc index d568e9b3ac..4caec82ef4 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc @@ -1,7 +1,7 @@ [[context-introduction]] = Additional Capabilities of the `ApplicationContext` -As discussed in the <>, the `org.springframework.beans.factory` +As discussed in the xref:web/webmvc-view/mvc-xslt.adoc#mvc-view-xslt-beandefs[chapter introduction], the `org.springframework.beans.factory` package provides basic functionality for managing and manipulating beans, including in a programmatic way. The `org.springframework.context` package adds the {api-spring-framework}/context/ApplicationContext.html[`ApplicationContext`] @@ -266,7 +266,7 @@ class and the `ApplicationListener` interface. If a bean that implements the Essentially, this is the standard Observer design pattern. TIP: As of Spring 4.2, the event infrastructure has been significantly improved and offers -an <> as well as the +an xref:core/beans/context-introduction.adoc#context-functionality-events-annotation[annotation-based model] as well as the ability to publish any arbitrary event (that is, an object that does not necessarily extend from `ApplicationEvent`). When such an object is published, we wrap it in an event for you. @@ -555,7 +555,7 @@ following example shows how to do so: ---- It is also possible to add additional runtime filtering by using the `condition` attribute -of the annotation that defines a <>, which should match +of the annotation that defines a xref:core/expressions.adoc[`SpEL` expression], which should match to actually invoke the method for a particular event. The following example shows how our notifier can be rewritten to be invoked only if the @@ -631,7 +631,7 @@ method signature to return the event that should be published, as the following ---- NOTE: This feature is not supported for -<>. +xref:core/beans/context-introduction.adoc#context-functionality-events-async[asynchronous listeners]. The `handleBlockedListEvent()` method publishes a new `ListUpdateEvent` for every `BlockedListEvent` that it handles. If you need to publish several events, you can return @@ -642,7 +642,7 @@ a `Collection` or an array of events instead. === Asynchronous Listeners If you want a particular listener to process events asynchronously, you can reuse the -<>. +xref:integration/scheduling.adoc#scheduling-annotation-support-async[regular `@Async` support]. The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -771,7 +771,7 @@ an event. == Convenient Access to Low-level Resources For optimal usage and understanding of application contexts, you should familiarize -yourself with Spring's `Resource` abstraction, as described in <>. +yourself with Spring's `Resource` abstraction, as described in xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources]. An application context is a `ResourceLoader`, which can be used to load `Resource` objects. A `Resource` is essentially a more feature rich version of the JDK `java.net.URL` class. @@ -847,7 +847,7 @@ Here is an example of instrumentation in the `AnnotationConfigApplicationContext The application context is already instrumented with multiple steps. Once recorded, these startup steps can be collected, displayed and analyzed with specific tools. For a complete list of existing startup steps, you can check out the -<>. +xref:core/appendix/application-startup-steps.adoc[dedicated appendix section]. The default `ApplicationStartup` implementation is a no-op variant, for minimal overhead. This means no metrics will be collected during application startup by default. diff --git a/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc b/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc index 249ef15f38..c7280792b3 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc @@ -35,11 +35,11 @@ Alternatively, for XML configuration, you can use the `context:load-time-weaver` Once configured for the `ApplicationContext`, any bean within that `ApplicationContext` may implement `LoadTimeWeaverAware`, thereby receiving a reference to the load-time weaver instance. This is particularly useful in combination with -<> where load-time weaving may be +xref:data-access/orm/jpa.adoc[Spring's JPA support] where load-time weaving may be necessary for JPA class transformation. Consult the {api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`] -javadoc for more detail. For more on AspectJ load-time weaving, see <>. +javadoc for more detail. For more on AspectJ load-time weaving, see xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework]. diff --git a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc index 7caf554ce2..48efa61aca 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/definition.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/definition.adoc @@ -27,31 +27,31 @@ The following table describes these properties: | Property| Explained in... | Class -| <> +| xref:core/beans/definition.adoc#beans-factory-class[Instantiating Beans] | Name -| <> +| xref:core/beans/definition.adoc#beans-beanname[Naming Beans] | Scope -| <> +| xref:core/beans/factory-scopes.adoc[Bean Scopes] | Constructor arguments -| <> +| xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection] | Properties -| <> +| xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection] | Autowiring mode -| <> +| xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators] | Lazy initialization mode -| <> +| xref:core/beans/dependencies/factory-lazy-init.adoc[Lazy-initialized Beans] | Initialization method -| <> +| xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[Initialization Callbacks] | Destruction method -| <> +| xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[Destruction Callbacks] |=== In addition to bean definitions that contain information on how to create a specific @@ -95,8 +95,8 @@ You are not required to supply a `name` or an `id` for a bean. If you do not sup `name` or `id` explicitly, the container generates a unique name for that bean. However, if you want to refer to that bean by name, through the use of the `ref` element or a Service Locator style lookup, you must provide a name. -Motivations for not supplying a name are related to using <> and <>. +Motivations for not supplying a name are related to using xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-inner-beans[inner beans] + and xref:core/beans/dependencies/factory-autowire.adoc[autowiring collaborators]. .Bean Naming Conventions **** @@ -163,7 +163,7 @@ creating a namespace), yet they refer to the same bean. .Java-configuration **** If you use Java Configuration, the `@Bean` annotation can be used to provide aliases. -See <> for details. +See xref:core/beans/java/bean-annotation.adoc[Using the `@Bean` Annotation] for details. **** @@ -179,7 +179,7 @@ If you use XML-based configuration metadata, you specify the type (or class) of that is to be instantiated in the `class` attribute of the `` element. This `class` attribute (which, internally, is a `Class` property on a `BeanDefinition` instance) is usually mandatory. (For exceptions, see -<> and <>.) +xref:core/beans/definition.adoc#beans-factory-class-instance-factory-method[Instantiation by Using an Instance Factory Method] and xref:core/beans/child-bean-definitions.adoc[Bean Definition Inheritance].) You can use the `Class` property in one of two ways: * Typically, to specify the bean class to be constructed in the case where the container @@ -232,7 +232,7 @@ With XML-based configuration metadata you can specify your bean class as follows For details about the mechanism for supplying arguments to the constructor (if required) and setting object instance properties after the object is constructed, see -<>. +xref:core/beans/dependencies/factory-collaborators.adoc[Injecting Dependencies]. [[beans-factory-class-static-factory-method]] @@ -286,14 +286,14 @@ The following example shows a class that would work with the preceding bean defi For details about the mechanism for supplying (optional) arguments to the factory method and setting object instance properties after the object is returned from the factory, -see <>. +see xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail]. [[beans-factory-class-instance-factory-method]] === Instantiation by Using an Instance Factory Method -Similar to instantiation through a <>, instantiation with an instance factory method invokes a non-static +Similar to instantiation through a xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[static factory method] +, instantiation with an instance factory method invokes a non-static method of an existing bean from the container to create a new bean. To use this mechanism, leave the `class` attribute empty and, in the `factory-bean` attribute, specify the name of a bean in the current (or parent or ancestor) container that contains @@ -398,15 +398,15 @@ The following example shows the corresponding class: ---- This approach shows that the factory bean itself can be managed and configured through -dependency injection (DI). See <>. +dependency injection (DI). See xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail] +. NOTE: In Spring documentation, "factory bean" refers to a bean that is configured in the Spring container and that creates objects through an -<> or -<> factory method. By contrast, +xref:core/beans/definition.adoc#beans-factory-class-instance-factory-method[instance] or +xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[static] factory method. By contrast, `FactoryBean` (notice the capitalization) refers to a Spring-specific -<> implementation class. +xref:core/beans/factory-extension.adoc#beans-factory-extension-factorybean[`FactoryBean`] implementation class. [[beans-factory-type-determination]] diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc index 3ca999ae95..829fe815a8 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc @@ -8,7 +8,7 @@ advantages: * Autowiring can significantly reduce the need to specify properties or constructor arguments. (Other mechanisms such as a bean template - <> are also valuable + xref:core/beans/child-bean-definitions.adoc[discussed elsewhere in this chapter] are also valuable in this regard.) * Autowiring can update a configuration as your objects evolve. For example, if you need to add a dependency to a class, that dependency can be satisfied automatically without @@ -16,7 +16,7 @@ advantages: during development, without negating the option of switching to explicit wiring when the code base becomes more stable. -When using XML-based configuration metadata (see <>), you +When using XML-based configuration metadata (see xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection]), you can specify the autowire mode for a bean definition with the `autowire` attribute of the `` element. The autowiring functionality has four modes. You specify autowiring per bean and can thus choose which ones to autowire. The following table describes the @@ -89,11 +89,11 @@ In the latter scenario, you have several options: * Abandon autowiring in favor of explicit wiring. * Avoid autowiring for a bean definition by setting its `autowire-candidate` attributes - to `false`, as described in the <>. + to `false`, as described in the xref:core/beans/dependencies/factory-autowire.adoc#beans-factory-autowire-candidate[next section]. * Designate a single bean definition as the primary candidate by setting the `primary` attribute of its `` element to `true`. * Implement the more fine-grained control available with annotation-based configuration, - as described in <>. + as described in xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration]. @@ -103,8 +103,8 @@ In the latter scenario, you have several options: On a per-bean basis, you can exclude a bean from autowiring. In Spring's XML format, set the `autowire-candidate` attribute of the `` element to `false`. The container makes that specific bean definition unavailable to the autowiring infrastructure -(including annotation style configurations such as <>). +(including annotation style configurations such as xref:core/beans/annotation-config/autowired.adoc[`@Autowired`] +). NOTE: The `autowire-candidate` attribute is designed to only affect type-based autowiring. It does not affect explicit references by name, which get resolved even if the diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc index 7d686d4e13..becfead14b 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc @@ -16,8 +16,8 @@ not know the location or class of the dependencies. As a result, your classes be to test, particularly when the dependencies are on interfaces or abstract base classes, which allow for stub or mock implementations to be used in unit tests. -DI exists in two major variants: <> and <>. +DI exists in two major variants: xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[Constructor-based dependency injection] + and xref:core/beans/dependencies/factory-collaborators.adoc#beans-setter-injection[Setter-based dependency injection]. [[beans-constructor-injection]] @@ -279,7 +279,7 @@ load an entire Spring IoC container instance. **** Since you can mix constructor-based and setter-based DI, it is a good rule of thumb to use constructors for mandatory dependencies and setter methods or configuration methods -for optional dependencies. Note that use of the <> +for optional dependencies. Note that use of the xref:core/beans/annotation-config/autowired.adoc[@Autowired] annotation on a setter method can be used to make the property be a required dependency; however, constructor injection with programmatic validation of arguments is preferable. @@ -294,7 +294,7 @@ Setter injection should primarily only be used for optional dependencies that ca assigned reasonable default values within the class. Otherwise, not-null checks must be performed everywhere the code uses the dependency. One benefit of setter injection is that setter methods make objects of that class amenable to reconfiguration or re-injection -later. Management through <> is therefore a compelling +later. Management through xref:integration/jmx.adoc[JMX MBeans] is therefore a compelling use case for setter injection. Use the DI style that makes the most sense for a particular class. Sometimes, when dealing @@ -326,7 +326,7 @@ The container performs bean dependency resolution as follows: The Spring container validates the configuration of each bean as the container is created. However, the bean properties themselves are not set until the bean is actually created. Beans that are singleton-scoped and set to be pre-instantiated (the default) are created -when the container is created. Scopes are defined in <>. Otherwise, +when the container is created. Scopes are defined in xref:core/beans/factory-scopes.adoc[Bean Scopes]. Otherwise, the bean is created only when it is requested. Creation of a bean potentially causes a graph of beans to be created, as the bean's dependencies and its dependencies' dependencies (and so on) are created and assigned. Note that resolution mismatches among @@ -373,8 +373,8 @@ to being injected into the dependent bean. This means that, if bean A has a depe bean B, the Spring IoC container completely configures bean B prior to invoking the setter method on bean A. In other words, the bean is instantiated (if it is not a pre-instantiated singleton), its dependencies are set, and the relevant lifecycle -methods (such as a <> -or the <>) +methods (such as a xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[configured init method] +or the xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[InitializingBean callback method]) are invoked. diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc index 988075e19d..17e5e98246 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc @@ -31,7 +31,7 @@ delimiters): ---- NOTE: The `depends-on` attribute can specify both an initialization-time dependency and, -in the case of <> beans only, a corresponding +in the case of xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton] beans only, a corresponding destruction-time dependency. Dependent beans that define a `depends-on` relationship with a given bean are destroyed first, prior to the given bean itself being destroyed. Thus, `depends-on` can also control shutdown order. diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc index cbb8eeb361..59fd3a319b 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc @@ -2,7 +2,7 @@ = Lazy-initialized Beans By default, `ApplicationContext` implementations eagerly create and configure all -<> beans as part of the initialization +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton] beans as part of the initialization process. Generally, this pre-instantiation is desirable, because errors in the configuration or surrounding environment are discovered immediately, as opposed to hours or even days later. When this behavior is not desirable, you can prevent diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc index 5f97b946fd..18742fe6e1 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc @@ -2,7 +2,7 @@ = Method Injection In most application scenarios, most beans in the container are -<>. When a singleton bean needs to +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singletons]. When a singleton bean needs to collaborate with another singleton bean or a non-singleton bean needs to collaborate with another non-singleton bean, you typically handle the dependency by defining one bean as a property of the other. A problem arises when the bean lifecycles are @@ -11,9 +11,9 @@ perhaps on each method invocation on A. The container creates the singleton bean once, and thus only gets one opportunity to set the properties. The container cannot provide bean A with a new instance of bean B every time one is needed. -A solution is to forego some inversion of control. You can <> by implementing the `ApplicationContextAware` interface, -and by <> ask for (a +A solution is to forego some inversion of control. You can xref:core/beans/factory-nature.adoc#beans-factory-aware[make bean A aware of the container] + by implementing the `ApplicationContextAware` interface, +and by xref:core/beans/basics.adoc#beans-factory-client[making a `getBean("B")` call to the container] ask for (a typically new) bean B instance every time bean A needs it. The following example shows this approach: @@ -104,7 +104,7 @@ https://spring.io/blog/2004/08/06/method-injection/[this blog entry]. Lookup method injection is the ability of the container to override methods on container-managed beans and return the lookup result for another named bean in the container. The lookup typically involves a prototype bean, as in the scenario described -in <>. The Spring Framework +in xref:core/beans/dependencies/factory-method-injection.adoc[the preceding section]. The Spring Framework implements this method injection by using bytecode generation from the CGLIB library to dynamically generate a subclass that overrides the method. @@ -198,7 +198,7 @@ the original class. Consider the following example: The bean identified as `commandManager` calls its own `createCommand()` method whenever it needs a new instance of the `myCommand` bean. You must be careful to deploy the `myCommand` bean as a prototype if that is actually what is needed. If it is -a <>, the same instance of the `myCommand` +a xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton], the same instance of the `myCommand` bean is returned each time. Alternatively, within the annotation-based component model, you can declare a lookup @@ -277,7 +277,7 @@ apply to explicitly registered or explicitly imported bean classes. [TIP] ==== Another way of accessing differently scoped target beans is an `ObjectFactory`/ -`Provider` injection point. See <>. +`Provider` injection point. See xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[Scoped Beans as Dependencies]. You may also find the `ServiceLocatorFactoryBean` (in the `org.springframework.beans.factory.config` package) to be useful. diff --git a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc index 0453dc43ca..25b41d07a7 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc @@ -1,7 +1,7 @@ [[beans-factory-properties-detailed]] = Dependencies and Configuration in Detail -As mentioned in the <>, you can define bean +As mentioned in the xref:core/beans/dependencies/factory-collaborators.adoc[previous section], you can define bean properties and constructor arguments as references to other managed beans (collaborators) or as values defined inline. Spring's XML-based configuration metadata supports sub-element types within its `` and `` elements for this @@ -13,7 +13,7 @@ purpose. The `value` attribute of the `` element specifies a property or constructor argument as a human-readable string representation. Spring's -<> is used to convert these +xref:core/validation/convert.adoc#core-convert-ConversionService-API[conversion service] is used to convert these values from a `String` to the actual type of the property or argument. The following example shows various values being set: @@ -28,7 +28,7 @@ The following example shows various values being set: ---- -The following example uses the <> for even more succinct +The following example uses the xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-p-namespace[p-namespace] for even more succinct XML configuration: [source,xml,indent=0,subs="verbatim,quotes"] @@ -112,7 +112,7 @@ container validate at deployment time that the referenced, named bean actually exists. In the second variation, no validation is performed on the value that is passed to the `targetName` property of the `client` bean. Typos are only discovered (with most likely fatal results) when the `client` bean is actually instantiated. If the `client` -bean is a <> bean, this typo and the resulting exception +bean is a xref:core/beans/factory-scopes.adoc[prototype] bean, this typo and the resulting exception may only be discovered long after the container is deployed. NOTE: The `local` attribute on the `idref` element is no longer supported in the 4.0 beans @@ -120,7 +120,7 @@ XSD, since it does not provide value over a regular `bean` reference any more. C your existing `idref local` references to `idref bean` when upgrading to the 4.0 schema. A common place (at least in versions earlier than Spring 2.0) where the `` element -brings value is in the configuration of <> in a +brings value is in the configuration of xref:core/aop-api/pfb.adoc#aop-pfb-1[AOP interceptors] in a `ProxyFactoryBean` bean definition. Using `` elements when you specify the interceptor names prevents you from misspelling an interceptor ID. @@ -277,7 +277,7 @@ collection elements overriding values specified in the parent collection. This section on merging discusses the parent-child bean mechanism. Readers unfamiliar with parent and child bean definitions may wish to read the -<> before continuing. +xref:core/beans/child-bean-definitions.adoc[relevant section] before continuing. The following example demonstrates collection merging: @@ -451,7 +451,7 @@ The preceding configuration is equivalent to the following Java code: The p-namespace lets you use the `bean` element's attributes (instead of nested `` elements) to describe your property values collaborating beans, or both. -Spring supports extensible configuration formats <>, +Spring supports extensible configuration formats xref:core/appendix/xsd-schemas.adoc[with namespaces], which are based on an XML Schema definition. The `beans` configuration format discussed in this chapter is defined in an XML Schema document. However, the p-namespace is not defined in an XSD file and exists only in the core of Spring. @@ -526,12 +526,12 @@ three approaches at the same time. [[beans-c-namespace]] == XML Shortcut with the c-namespace -Similar to the <>, the c-namespace, introduced in Spring +Similar to the xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-p-namespace[XML Shortcut with the p-namespace], the c-namespace, introduced in Spring 3.1, allows inlined attributes for configuring the constructor arguments rather then nested `constructor-arg` elements. The following example uses the `c:` namespace to do the same thing as the from -<>: +xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[Constructor-based Dependency Injection]: [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -580,7 +580,7 @@ A corresponding index notation is also available for `` element not commonly used since the plain order of declaration is usually sufficient there. In practice, the constructor resolution -<> is quite efficient in matching +xref:core/beans/dependencies/factory-collaborators.adoc#beans-factory-ctor-arguments-resolution[mechanism] is quite efficient in matching arguments, so unless you really need to, we recommend using the name notation throughout your configuration. diff --git a/framework-docs/modules/ROOT/pages/core/beans/environment.adoc b/framework-docs/modules/ROOT/pages/core/beans/environment.adoc index 9c51906bda..137e0c32b4 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/environment.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/environment.adoc @@ -3,8 +3,8 @@ The {api-spring-framework}/core/env/Environment.html[`Environment`] interface is an abstraction integrated in the container that models two key -aspects of the application environment: <> -and <>. +aspects of the application environment: xref:core/beans/environment.adoc#beans-definition-profiles[profiles] +and xref:core/beans/environment.adoc#beans-property-source-abstraction[properties]. A profile is a named, logical group of bean definitions to be registered with the container only if the given profile is active. Beans may be assigned to a profile @@ -200,7 +200,7 @@ NOTE: You cannot mix the `&` and `|` operators without using parentheses. For ex `production & us-east | eu-central` is not a valid expression. It must be expressed as `production & (us-east | eu-central)`. -You can use `@Profile` as a <> for the purpose +You can use `@Profile` as a xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotation] for the purpose of creating a custom composed annotation. The following example defines a custom `@Production` annotation that you can use as a drop-in replacement for `@Profile("production")`: @@ -437,10 +437,10 @@ it programmatically against the `Environment` API which is available through an In addition, you can also declaratively activate profiles through the `spring.profiles.active` property, which may be specified through system environment variables, JVM system properties, servlet context parameters in `web.xml`, or even as an -entry in JNDI (see <>). In integration tests, active +entry in JNDI (see xref:core/beans/environment.adoc#beans-property-source-abstraction[`PropertySource` Abstraction]). In integration tests, active profiles can be declared by using the `@ActiveProfiles` annotation in the `spring-test` -module (see <>). +module (see xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[context configuration with environment profiles] +). Note that profiles are not an "`either-or`" proposition. You can activate multiple profiles at once. Programmatically, you can provide multiple profile names to the diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc index 51a30ee610..df156b2372 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc @@ -24,8 +24,8 @@ interface. If you write your own `BeanPostProcessor`, you should consider implem the `Ordered` interface, too. For further details, see the javadoc of the {api-spring-framework}/beans/factory/config/BeanPostProcessor.html[`BeanPostProcessor`] and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces. See also the note -on <>. +on xref:core/beans/factory-extension.adoc#beans-factory-programmatically-registering-beanpostprocessors[programmatic registration of `BeanPostProcessor` instances] +. [NOTE] ==== @@ -41,7 +41,7 @@ another container, even if both containers are part of the same hierarchy. To change the actual bean definition (that is, the blueprint that defines the bean), you instead need to use a `BeanFactoryPostProcessor`, as described in -<>. +xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[Customizing Configuration Metadata with a `BeanFactoryPostProcessor`]. ==== The `org.springframework.beans.factory.config.BeanPostProcessor` interface consists of @@ -192,7 +192,7 @@ Notice how the `InstantiationTracingBeanPostProcessor` is merely defined. It doe even have a name, and, because it is a bean, it can be dependency-injected as you would any other bean. (The preceding configuration also defines a bean that is backed by a Groovy script. The Spring dynamic language support is detailed in the chapter entitled -<>.) +xref:languages/dynamic.adoc[Dynamic Language Support].) The following Java application runs the preceding code and configuration: @@ -268,7 +268,7 @@ and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces for more deta ==== If you want to change the actual bean instances (that is, the objects that are created from the configuration metadata), then you instead need to use a `BeanPostProcessor` -(described earlier in <>). While it is technically possible +(described earlier in xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[Customizing Beans by Using a `BeanPostProcessor`]). While it is technically possible to work with bean instances within a `BeanFactoryPostProcessor` (for example, by using `BeanFactory.getBean()`), doing so causes premature bean instantiation, violating the standard container lifecycle. This may cause negative side effects, such as bypassing diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc index 13cf361ed2..b13f08e795 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc @@ -4,9 +4,9 @@ The Spring Framework provides a number of interfaces you can use to customize the nature of a bean. This section groups them as follows: -* <> -* <> -* <> +* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[Lifecycle Callbacks] +* xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`] +* xref:core/beans/factory-nature.adoc#aware-list[Other `Aware` Interfaces] @@ -23,7 +23,7 @@ perform certain actions upon initialization and destruction of your beans. The JSR-250 `@PostConstruct` and `@PreDestroy` annotations are generally considered best practice for receiving lifecycle callbacks in a modern Spring application. Using these annotations means that your beans are not coupled to Spring-specific interfaces. -For details, see <>. +For details, see xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[Using `@PostConstruct` and `@PreDestroy`]. If you do not want to use the JSR-250 annotations but you still want to remove coupling, consider `init-method` and `destroy-method` bean definition metadata. @@ -33,7 +33,7 @@ Internally, the Spring Framework uses `BeanPostProcessor` implementations to pro callback interfaces it can find and call the appropriate methods. If you need custom features or other lifecycle behavior Spring does not by default offer, you can implement a `BeanPostProcessor` yourself. For more information, see -<>. +xref:core/beans/factory-extension.adoc[Container Extension Points]. In addition to the initialization and destruction callbacks, Spring-managed objects may also implement the `Lifecycle` interface so that those objects can participate in the @@ -56,11 +56,11 @@ bean. The `InitializingBean` interface specifies a single method: We recommend that you do not use the `InitializingBean` interface, because it unnecessarily couples the code to Spring. Alternatively, we suggest using -the <> annotation or +the xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PostConstruct`] annotation or specifying a POJO initialization method. In the case of XML-based configuration metadata, you can use the `init-method` attribute to specify the name of the method that has a void no-argument signature. With Java configuration, you can use the `initMethod` attribute of -`@Bean`. See <>. Consider the following example: +`@Bean`. See xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receiving Lifecycle Callbacks]. Consider the following example: [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -135,11 +135,11 @@ bean get a callback when the container that contains it is destroyed. The We recommend that you do not use the `DisposableBean` callback interface, because it unnecessarily couples the code to Spring. Alternatively, we suggest using -the <> annotation or +the xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PreDestroy`] annotation or specifying a generic method that is supported by bean definitions. With XML-based configuration metadata, you can use the `destroy-method` attribute on the ``. With Java configuration, you can use the `destroyMethod` attribute of `@Bean`. See -<>. Consider the following definition: +xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receiving Lifecycle Callbacks]. Consider the following definition: [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -204,7 +204,7 @@ TIP: You can assign the `destroy-method` attribute of a `` element a speci `java.lang.AutoCloseable` or `java.io.Closeable` would therefore match.) You can also set this special `(inferred)` value on the `default-destroy-method` attribute of a `` element to apply this behavior to an entire set of beans (see -<>). Note that this is the +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-default-init-destroy-methods[Default Initialization and Destroy Methods]). Note that this is the default behavior with Java configuration. [[beans-factory-lifecycle-default-init-destroy-methods]] @@ -221,8 +221,8 @@ callback method names on every bean. This means that you, as an application developer, can write your application classes and use an initialization callback called `init()`, without having to configure an `init-method="init"` attribute with each bean definition. The Spring IoC container calls that method when the bean is created (and in -accordance with the standard lifecycle callback contract <>). This feature also enforces a consistent naming convention for +accordance with the standard lifecycle callback contract xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[described previously] +). This feature also enforces a consistent naming convention for initialization and destroy method callbacks. Suppose that your initialization callback methods are named `init()` and your destroy @@ -308,18 +308,18 @@ interacts directly with the raw target bean. As of Spring 2.5, you have three options for controlling bean lifecycle behavior: -* The <> and -<> callback interfaces +* The xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[`InitializingBean`] and +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[`DisposableBean`] callback interfaces * Custom `init()` and `destroy()` methods -* The <>. You can combine these mechanisms to control a given bean. +* The xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PostConstruct` and `@PreDestroy` annotations] +. You can combine these mechanisms to control a given bean. NOTE: If multiple lifecycle mechanisms are configured for a bean and each mechanism is configured with a different method name, then each configured method is run in the order listed after this note. However, if the same method name is configured -- for example, `init()` for an initialization method -- for more than one of these lifecycle mechanisms, that method is run once, as explained in the -<>. +xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-default-init-destroy-methods[preceding section]. Multiple lifecycle mechanisms configured for the same bean, with different initialization methods, are called as follows: @@ -542,18 +542,18 @@ it couples the code to Spring and does not follow the Inversion of Control style where collaborators are provided to beans as properties. Other methods of the `ApplicationContext` provide access to file resources, publishing application events, and accessing a `MessageSource`. These additional features are described in -<>. +xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`]. Autowiring is another alternative to obtain a reference to the `ApplicationContext`. The _traditional_ `constructor` and `byType` autowiring modes -(as described in <>) can provide a dependency of type +(as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators]) can provide a dependency of type `ApplicationContext` for a constructor argument or a setter method parameter, respectively. For more flexibility, including the ability to autowire fields and multiple parameter methods, use the annotation-based autowiring features. If you do, the `ApplicationContext` is autowired into a field, constructor argument, or method parameter that expects the `ApplicationContext` type if the field, constructor, or method in question carries the `@Autowired` annotation. For more information, see -<>. +xref:core/beans/annotation-config/autowired.adoc[Using `@Autowired`]. When an `ApplicationContext` creates a class that implements the `org.springframework.beans.factory.BeanNameAware` interface, the class is provided with @@ -577,7 +577,7 @@ init-method. [[aware-list]] == Other `Aware` Interfaces -Besides `ApplicationContextAware` and `BeanNameAware` (discussed <>), +Besides `ApplicationContextAware` and `BeanNameAware` (discussed xref:core/beans/factory-nature.adoc#beans-factory-aware[earlier]), Spring offers a wide range of `Aware` callback interfaces that let beans indicate to the container that they require a certain infrastructure dependency. As a general rule, the name indicates the dependency type. The following table summarizes the most important `Aware` interfaces: @@ -589,50 +589,50 @@ dependency type. The following table summarizes the most important `Aware` inter | `ApplicationContextAware` | Declaring `ApplicationContext`. -| <> +| xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`] | `ApplicationEventPublisherAware` | Event publisher of the enclosing `ApplicationContext`. -| <> +| xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`] | `BeanClassLoaderAware` | Class loader used to load the bean classes. -| <> +| xref:core/beans/definition.adoc#beans-factory-class[Instantiating Beans] | `BeanFactoryAware` | Declaring `BeanFactory`. -| <> +| xref:core/beans/beanfactory.adoc[The `BeanFactory` API] | `BeanNameAware` | Name of the declaring bean. -| <> +| xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`] | `LoadTimeWeaverAware` | Defined weaver for processing class definition at load time. -| <> +| xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework] | `MessageSourceAware` | Configured strategy for resolving messages (with support for parameterization and internationalization). -| <> +| xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`] | `NotificationPublisherAware` | Spring JMX notification publisher. -| <> +| xref:integration/jmx/notifications.adoc[Notifications] | `ResourceLoaderAware` | Configured loader for low-level access to resources. -| <> +| xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources] | `ServletConfigAware` | Current `ServletConfig` the container runs in. Valid only in a web-aware Spring `ApplicationContext`. -| <> +| xref:web/webmvc.adoc#mvc[Spring MVC] | `ServletContextAware` | Current `ServletContext` the container runs in. Valid only in a web-aware Spring `ApplicationContext`. -| <> +| xref:web/webmvc.adoc#mvc[Spring MVC] |=== Note again that using these interfaces ties your code to the Spring API and does not diff --git a/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc b/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc index 7925a2504c..06eb5eba3f 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc @@ -14,7 +14,7 @@ through configuration instead of having to bake in the scope of an object at the class level. Beans can be defined to be deployed in one of a number of scopes. The Spring Framework supports six scopes, four of which are available only if you use a web-aware `ApplicationContext`. You can also create -<> +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-custom[a custom scope.] The following table describes the supported scopes: @@ -24,27 +24,27 @@ The following table describes the supported scopes: |=== | Scope| Description -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton] | (Default) Scopes a single bean definition to a single object instance for each Spring IoC container. -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-prototype[prototype] | Scopes a single bean definition to any number of object instances. -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-request[request] | Scopes a single bean definition to the lifecycle of a single HTTP request. That is, each HTTP request has its own instance of a bean created off the back of a single bean definition. Only valid in the context of a web-aware Spring `ApplicationContext`. -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-session[session] | Scopes a single bean definition to the lifecycle of an HTTP `Session`. Only valid in the context of a web-aware Spring `ApplicationContext`. -| <> +| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-application[application] | Scopes a single bean definition to the lifecycle of a `ServletContext`. Only valid in the context of a web-aware Spring `ApplicationContext`. -| <> +| xref:web/websocket/stomp/scope.adoc[websocket] | Scopes a single bean definition to the lifecycle of a `WebSocket`. Only valid in the context of a web-aware Spring `ApplicationContext`. |=== @@ -53,7 +53,7 @@ NOTE: A thread scope is available but is not registered by default. For more inf see the documentation for {api-spring-framework}/context/support/SimpleThreadScope.html[`SimpleThreadScope`]. For instructions on how to register this or any other custom scope, see -<>. +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-custom-using[Using a Custom Scope]. @@ -125,13 +125,13 @@ objects regardless of scope, in the case of prototypes, configured destruction lifecycle callbacks are not called. The client code must clean up prototype-scoped objects and release expensive resources that the prototype beans hold. To get the Spring container to release resources held by prototype-scoped beans, try using a -custom <>, which holds a reference to +custom xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[bean post-processor], which holds a reference to beans that need to be cleaned up. In some respects, the Spring container's role in regard to a prototype-scoped bean is a replacement for the Java `new` operator. All lifecycle management past that point must be handled by the client. (For details on the lifecycle of a bean in the Spring -container, see <>.) +container, see xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[Lifecycle Callbacks].) @@ -149,7 +149,7 @@ prototype-scoped bean repeatedly at runtime. You cannot dependency-inject a prototype-scoped bean into your singleton bean, because that injection occurs only once, when the Spring container instantiates the singleton bean and resolves and injects its dependencies. If you need a new instance of a prototype bean at -runtime more than once, see <>. +runtime more than once, see xref:core/beans/dependencies/factory-method-injection.adoc[Method Injection]. @@ -362,7 +362,7 @@ following example shows how to do so: WebSocket scope is associated with the lifecycle of a WebSocket session and applies to STOMP over WebSocket applications, see -<> for more details. +xref:web/websocket/stomp/scope.adoc[WebSocket scope] for more details. @@ -399,7 +399,7 @@ several additional access variants, including `getIfAvailable` and `getIfUnique` The JSR-330 variant of this is called `Provider` and is used with a `Provider` declaration and a corresponding `get()` call for every retrieval attempt. -See <> for more details on JSR-330 overall. +See xref:core/beans/standard-annotations.adoc[here] for more details on JSR-330 overall. ==== The configuration in the following example is only one line, but it is important to @@ -433,8 +433,8 @@ understand the "`why`" as well as the "`how`" behind it: To create such a proxy, you insert a child `` element into a scoped -bean definition (see <> and -<>). +bean definition (see xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection-proxies[Choosing the Type of Proxy to Create] and +xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration]). Why do definitions of beans scoped at the `request`, `session` and custom-scope levels require the `` element? Consider the following singleton bean definition and contrast it with @@ -521,7 +521,7 @@ interfaces. The following example shows a proxy based on an interface: ---- For more detailed information about choosing class-based or interface-based proxying, -see <>. +see xref:core/aop/proxying.adoc[Proxying Mechanisms]. diff --git a/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc b/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc index 8ceef04028..84fce22f42 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/introduction.adoc @@ -30,7 +30,7 @@ and the `ApplicationContext` adds more enterprise-specific functionality. The `ApplicationContext` is a complete superset of the `BeanFactory` and is used exclusively in this chapter in descriptions of Spring's IoC container. For more information on using the `BeanFactory` instead of the `ApplicationContext,` see the section covering the -<>. +xref:core/beans/beanfactory.adoc[`BeanFactory` API]. In Spring, the objects that form the backbone of your application and that are managed by the Spring IoC container are called beans. A bean is an object that is diff --git a/framework-docs/modules/ROOT/pages/core/beans/java.adoc b/framework-docs/modules/ROOT/pages/core/beans/java.adoc index 7cd289d7c4..146880ab05 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java.adoc @@ -4,15 +4,15 @@ This section covers how to use annotations in your Java code to configure the Spring container. It includes the following topics: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:core/beans/java/basic-concepts.adoc[Basic Concepts: `@Bean` and `@Configuration`] +* xref:core/beans/java/instantiating-container.adoc[Instantiating the Spring Container by Using `AnnotationConfigApplicationContext`] +* xref:core/beans/java/bean-annotation.adoc[Using the `@Bean` Annotation] +* xref:core/beans/java/configuration-annotation.adoc[Using the `@Configuration` annotation] +* xref:core/beans/java/composing-configuration-classes.adoc[Composing Java-based Configurations] +* xref:core/beans/environment.adoc#beans-definition-profiles[Bean Definition Profiles] +* xref:core/beans/environment.adoc#beans-property-source-abstraction[`PropertySource` Abstraction] +* xref:core/beans/environment.adoc#beans-using-propertysource[Using `@PropertySource`] +* xref:core/beans/environment.adoc#beans-placeholder-resolution-in-statements[Placeholder Resolution in Statements] diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc index 7872e94cfa..e39ad32d47 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc @@ -4,9 +4,9 @@ `@Bean` is a method-level annotation and a direct analog of the XML `` element. The annotation supports some of the attributes offered by ``, such as: -* <> -* <> -* <> +* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[init-method] +* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[destroy-method] +* xref:core/beans/dependencies/factory-autowire.adoc[autowiring] * `name`. You can use the `@Bean` annotation in a `@Configuration`-annotated or in a @@ -160,7 +160,7 @@ parameter, as the following example shows: The resolution mechanism is pretty much identical to constructor-based dependency -injection. See <> for more details. +injection. See xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[the relevant section] for more details. [[beans-java-lifecycle-callbacks]] @@ -168,17 +168,17 @@ injection. See <> for more de Any classes defined with the `@Bean` annotation support the regular lifecycle callbacks and can use the `@PostConstruct` and `@PreDestroy` annotations from JSR-250. See -<> for further +xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[JSR-250 annotations] for further details. -The regular Spring <> callbacks are fully supported as +The regular Spring xref:core/beans/factory-nature.adoc[lifecycle] callbacks are fully supported as well. If a bean implements `InitializingBean`, `DisposableBean`, or `Lifecycle`, their respective methods are called by the container. -The standard set of `*Aware` interfaces (such as <>, -<>, -<>, -<>, and so on) are also fully supported. +The standard set of `*Aware` interfaces (such as xref:core/beans/beanfactory.adoc[BeanFactoryAware], +xref:core/beans/factory-nature.adoc#beans-factory-aware[BeanNameAware], +xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSourceAware], +xref:core/beans/factory-nature.adoc#beans-factory-aware[ApplicationContextAware], and so on) are also fully supported. The `@Bean` annotation supports specifying arbitrary initialization and destruction callback methods, much like Spring XML's `init-method` and `destroy-method` attributes @@ -331,7 +331,7 @@ Spring includes the `@Scope` annotation so that you can specify the scope of a b You can specify that your beans defined with the `@Bean` annotation should have a specific scope. You can use any of the standard scopes specified in the -<> section. +xref:core/beans/factory-scopes.adoc[Bean Scopes] section. The default scope is `singleton`, but you can override this with the `@Scope` annotation, as the following example shows: @@ -367,7 +367,7 @@ as the following example shows: === `@Scope` and `scoped-proxy` Spring offers a convenient way of working with scoped dependencies through -<>. The easiest way to create +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[scoped proxies]. The easiest way to create such a proxy when using the XML configuration is the `` element. Configuring your beans in Java with a `@Scope` annotation offers equivalent support with the `proxyMode` attribute. The default is `ScopedProxyMode.DEFAULT`, which @@ -376,7 +376,7 @@ has been configured at the component-scan instruction level. You can specify `ScopedProxyMode.TARGET_CLASS`, `ScopedProxyMode.INTERFACES` or `ScopedProxyMode.NO`. If you port the scoped proxy example from the XML reference documentation (see -<>) to our `@Bean` using Java, +xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[scoped proxies]) to our `@Bean` using Java, it resembles the following: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -448,7 +448,7 @@ as the following example shows: [[beans-java-bean-aliasing]] == Bean Aliasing -As discussed in <>, it is sometimes desirable to give a single bean +As discussed in xref:core/beans/definition.adoc#beans-beanname[Naming Beans], it is sometimes desirable to give a single bean multiple names, otherwise known as bean aliasing. The `name` attribute of the `@Bean` annotation accepts a String array for this purpose. The following example shows how to set a number of aliases for a bean: diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc index 9b02fa8f33..13b342fcab 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc @@ -101,7 +101,7 @@ issue, because no compiler is involved, and you can declare When using `@Configuration` classes, the Java compiler places constraints on the configuration model, in that references to other beans must be valid Java syntax. -Fortunately, solving this problem is simple. As <>, +Fortunately, solving this problem is simple. As xref:core/beans/java/bean-annotation.adoc#beans-java-dependencies[we already discussed], a `@Bean` method can have an arbitrary number of parameters that describe the bean dependencies. Consider the following more real-world scenario with several `@Configuration` classes, each depending on beans declared in the others: @@ -474,7 +474,7 @@ created before the current bean, beyond what the latter's direct dependencies im It is often useful to conditionally enable or disable a complete `@Configuration` class or even individual `@Bean` methods, based on some arbitrary system state. One common example of this is to use the `@Profile` annotation to activate beans only when a specific -profile has been enabled in the Spring `Environment` (see <> +profile has been enabled in the Spring `Environment` (see xref:core/beans/environment.adoc#beans-definition-profiles[Bean Definition Profiles] for details). The `@Profile` annotation is actually implemented by using a much more flexible annotation diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc index 74907e874b..ccf861e921 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc @@ -4,7 +4,7 @@ `@Configuration` is a class-level annotation indicating that an object is a source of bean definitions. `@Configuration` classes declare beans through `@Bean`-annotated methods. Calls to `@Bean` methods on `@Configuration` classes can also be used to define -inter-bean dependencies. See <> for a general introduction. +inter-bean dependencies. See xref:core/beans/java/basic-concepts.adoc[Basic Concepts: `@Bean` and `@Configuration`] for a general introduction. [[beans-java-injecting-dependencies]] @@ -56,7 +56,7 @@ by using plain `@Component` classes. [[beans-java-method-injection]] == Lookup Method Injection -As noted earlier, <> is an +As noted earlier, xref:core/beans/dependencies/factory-method-injection.adoc[lookup method injection] is an advanced feature that you should use rarely. It is useful in cases where a singleton-scoped bean has a dependency on a prototype-scoped bean. Using Java for this type of configuration provides a natural means for implementing this pattern. The diff --git a/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc b/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc index 9b3c6605aa..1a082498c4 100644 --- a/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc +++ b/framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc @@ -177,7 +177,7 @@ following example shows: } ---- -NOTE: Remember that `@Configuration` classes are <> +NOTE: Remember that `@Configuration` classes are xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotated] with `@Component`, so they are candidates for component-scanning. In the preceding example, assuming that `AppConfig` is declared within the `com.acme` package (or any package underneath), it is picked up during the call to `scan()`. Upon `refresh()`, all its `@Bean` diff --git a/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc b/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc index 1f9f6e995a..6991a5f30f 100644 --- a/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc +++ b/framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc @@ -8,10 +8,10 @@ XNIO, Jetty uses pooled byte buffers with a callback to be released, and so on. The `spring-core` module provides a set of abstractions to work with various byte buffer APIs as follows: -* <> abstracts the creation of a data buffer. -* <> represents a byte buffer, which may be -<>. -* <> offers utility methods for data buffers. +* xref:core/databuffer-codec.adoc#databuffers-factory[`DataBufferFactory`] abstracts the creation of a data buffer. +* xref:core/databuffer-codec.adoc#databuffers-buffer[`DataBuffer`] represents a byte buffer, which may be +xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[pooled]. +* xref:core/databuffer-codec.adoc#databuffers-utils[`DataBufferUtils`] offers utility methods for data buffers. * <> decode or encode data buffer streams into higher level objects. @@ -45,7 +45,7 @@ Below is a partial list of benefits: * Read and write with independent positions, i.e. not requiring a call to `flip()` to alternate between read and write. * Capacity expanded on demand as with `java.lang.StringBuilder`. -* Pooled buffers and reference counting via <>. +* Pooled buffers and reference counting via xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[`PooledDataBuffer`]. * View a buffer as `java.nio.ByteBuffer`, `InputStream`, or `OutputStream`. * Determine the index, or the last index, for a given byte. @@ -104,7 +104,7 @@ The `org.springframework.core.codec` package provides the following strategy int The `spring-core` module provides `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and `String` encoder and decoder implementations. The `spring-web` module adds Jackson JSON, Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders. See -<> in the WebFlux section. +xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] in the WebFlux section. @@ -113,7 +113,7 @@ Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders. See == Using `DataBuffer` When working with data buffers, special care must be taken to ensure buffers are released -since they may be <>. We'll use codecs to illustrate +since they may be xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[pooled]. We'll use codecs to illustrate how that works but the concepts apply more generally. Let's see what codecs must do internally to manage data buffers. diff --git a/framework-docs/modules/ROOT/pages/core/expressions.adoc b/framework-docs/modules/ROOT/pages/core/expressions.adoc index 69cc559abf..a87addc06f 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions.adoc @@ -23,7 +23,7 @@ infrastructure classes, such as the parser. Most Spring users need not deal with this infrastructure and can, instead, author only expression strings for evaluation. An example of this typical use is the integration of SpEL into creating XML or annotation-based bean definitions, as shown in -<>. +xref:core/expressions/beandef.adoc[Expression support for defining bean definitions]. This chapter covers the features of the expression language, its API, and its language syntax. In several places, `Inventor` and `Society` classes are used as the target diff --git a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc index d427d16586..096714936b 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc @@ -3,7 +3,7 @@ This section introduces the simple use of SpEL interfaces and its expression language. The complete language reference can be found in -<>. +xref:core/expressions/language-ref.adoc[Language Reference]. The following code introduces the SpEL API to evaluate the literal string expression, `Hello World`. @@ -376,7 +376,7 @@ interpreter and only 3ms using the compiled version of the expression. The compiler is not turned on by default, but you can turn it on in either of two different ways. You can turn it on by using the parser configuration process -(<>) or by using a Spring property +(xref:core/expressions/evaluation.adoc#expressions-parser-configuration[discussed earlier]) or by using a Spring property when SpEL usage is embedded inside another component. This section discusses both of these options. @@ -443,7 +443,7 @@ The second way to configure the compiler is for use when SpEL is embedded inside other component and it may not be possible to configure it through a configuration object. In these cases, it is possible to set the `spring.expression.compiler.mode` property via a JVM system property (or via the -<> mechanism) to one of the +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism) to one of the `SpelCompilerMode` enum values (`off`, `immediate`, or `mixed`). diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc index 2f17606729..c6c7e138d0 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc @@ -4,21 +4,21 @@ This section describes how the Spring Expression Language works. It covers the following topics: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:core/expressions/language-ref/literal.adoc[Literal Expressions] +* xref:core/expressions/language-ref/properties-arrays.adoc[Properties, Arrays, Lists, Maps, and Indexers] +* xref:core/expressions/language-ref/inline-lists.adoc[Inline Lists] +* xref:core/expressions/language-ref/inline-maps.adoc[Inline Maps] +* xref:core/expressions/language-ref/array-construction.adoc[Array Construction] +* xref:core/expressions/language-ref/methods.adoc[Methods] +* xref:core/expressions/language-ref/operators.adoc[Operators] +* xref:core/expressions/language-ref/types.adoc[Types] +* xref:core/expressions/language-ref/constructors.adoc[Constructors] +* xref:core/expressions/language-ref/variables.adoc[Variables] +* xref:core/expressions/language-ref/functions.adoc[Functions] +* xref:core/expressions/language-ref/bean-references.adoc[Bean References] +* xref:core/expressions/language-ref/operator-ternary.adoc[Ternary Operator (If-Then-Else)] +* xref:core/expressions/language-ref/operator-elvis.adoc[The Elvis Operator] +* xref:core/expressions/language-ref/operator-safe-navigation.adoc[Safe Navigation Operator] diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc index 2f0e56c1a2..240073f7da 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc @@ -3,10 +3,10 @@ The Spring Expression Language supports the following kinds of operators: -* <> -* <> -* <> -* <> +* xref:core/expressions/language-ref/operators.adoc#expressions-operators-relational[Relational Operators] +* xref:core/expressions/language-ref/operators.adoc#expressions-operators-logical[Logical Operators] +* xref:core/expressions/language-ref/operators.adoc#expressions-operators-mathematical[Mathematical Operators] +* xref:core/expressions/language-ref/operators.adoc#expressions-assignment[The Assignment Operator] [[expressions-operators-relational]] diff --git a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc index 5935065e40..bc717138ae 100644 --- a/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc +++ b/framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc @@ -3,8 +3,8 @@ Navigating with property references is easy. To do so, use a period to indicate a nested property value. The instances of the `Inventor` class, `pupin` and `tesla`, were -populated with data listed in the <> section. To navigate "down" the object graph and get Tesla's year of birth and +populated with data listed in the xref:core/expressions/example-classes.adoc[Classes used in the examples] + section. To navigate "down" the object graph and get Tesla's year of birth and Pupin's city of birth, we use the following expressions: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/framework-docs/modules/ROOT/pages/core/null-safety.adoc b/framework-docs/modules/ROOT/pages/core/null-safety.adoc index 2e649691ab..f64cef9b34 100644 --- a/framework-docs/modules/ROOT/pages/core/null-safety.adoc +++ b/framework-docs/modules/ROOT/pages/core/null-safety.adoc @@ -39,7 +39,7 @@ warnings related to null-safety in order to avoid `NullPointerException` at runt They are also used to make Spring API null-safe in Kotlin projects, since Kotlin natively supports https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details -are available in the <>. +are available in the xref:languages/kotlin/null-safety.adoc[Kotlin support documentation]. diff --git a/framework-docs/modules/ROOT/pages/core/resources.adoc b/framework-docs/modules/ROOT/pages/core/resources.adoc index 4aaa4575c8..d645fcca28 100644 --- a/framework-docs/modules/ROOT/pages/core/resources.adoc +++ b/framework-docs/modules/ROOT/pages/core/resources.adoc @@ -4,14 +4,14 @@ This chapter covers how Spring handles resources and how you can work with resources in Spring. It includes the following topics: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:core/resources.adoc#resources-introduction[Introduction] +* xref:core/resources.adoc#resources-resource[The `Resource` Interface] +* xref:core/resources.adoc#resources-implementations[Built-in `Resource` Implementations] +* xref:core/resources.adoc#resources-resourceloader[The `ResourceLoader` Interface] +* xref:core/resources.adoc#resources-resourcepatternresolver[The `ResourcePatternResolver` Interface] +* xref:core/resources.adoc#resources-resourceloaderaware[The `ResourceLoaderAware` Interface] +* xref:core/resources.adoc#resources-as-dependencies[Resources as Dependencies] +* xref:core/resources.adoc#resources-app-ctx[Application Contexts and Resource Paths] @@ -133,13 +133,13 @@ work. Spring includes several built-in `Resource` implementations: -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:core/resources.adoc#resources-implementations-urlresource[`UrlResource`] +* xref:core/resources.adoc#resources-implementations-classpathresource[`ClassPathResource`] +* xref:core/resources.adoc#resources-implementations-filesystemresource[`FileSystemResource`] +* xref:core/resources.adoc#resources-implementations-pathresource[`PathResource`] +* xref:core/resources.adoc#resources-implementations-servletcontextresource[`ServletContextResource`] +* xref:core/resources.adoc#resources-implementations-inputstreamresource[`InputStreamResource`] +* xref:core/resources.adoc#resources-implementations-bytearrayresource[`ByteArrayResource`] For a complete list of `Resource` implementations available in Spring, consult the "All Known Implementing Classes" section of the @@ -349,7 +349,7 @@ objects: | file: | `\file:///data/config.xml` -| Loaded as a `URL` from the filesystem. See also <>. +| Loaded as a `URL` from the filesystem. See also xref:core/resources.adoc#resources-filesystemresource-caveats[`FileSystemResource` Caveats]. | https: | `\https://myserver/logo.png` @@ -385,11 +385,11 @@ for all matching resources from the class path. Note that the resource location expected to be a path without placeholders in this case -- for example, `classpath*:/config/beans.xml`. JAR files or different directories in the class path can contain multiple files with the same path and the same name. See -<> and its subsections for further details +xref:core/resources.adoc#resources-app-ctx-wildcards-in-resource-paths[Wildcards in Application Context Constructor Resource Paths] and its subsections for further details on wildcard support with the `classpath*:` resource prefix. A passed-in `ResourceLoader` (for example, one supplied via -<> semantics) can be checked whether +xref:core/resources.adoc#resources-resourceloaderaware[`ResourceLoaderAware`] semantics) can be checked whether it implements this extended interface too. `PathMatchingResourcePatternResolver` is a standalone implementation that is usable @@ -444,18 +444,18 @@ interface (which can be considered a utility interface) and not to the whole Spr In application components, you may also rely upon autowiring of the `ResourceLoader` as an alternative to implementing the `ResourceLoaderAware` interface. The _traditional_ -`constructor` and `byType` autowiring modes (as described in <>) +`constructor` and `byType` autowiring modes (as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators]) are capable of providing a `ResourceLoader` for either a constructor argument or a setter method parameter, respectively. For more flexibility (including the ability to autowire fields and multiple parameter methods), consider using the annotation-based autowiring features. In that case, the `ResourceLoader` is autowired into a field, constructor argument, or method parameter that expects the `ResourceLoader` type as long as the field, constructor, or method in question carries the `@Autowired` annotation. -For more information, see <>. +For more information, see xref:core/beans/annotation-config/autowired.adoc[Using `@Autowired`]. NOTE: To load one or more `Resource` objects for a resource path that contains wildcards or makes use of the special `classpath*:` resource prefix, consider having an instance of -<> autowired into your +xref:core/resources.adoc#resources-resourcepatternresolver[`ResourcePatternResolver`] autowired into your application components instead of `ResourceLoader`. @@ -531,8 +531,8 @@ latter being used to access a file in the filesystem): If the `MyBean` class is refactored for use with annotation-driven configuration, the path to `myTemplate.txt` can be stored under a key named `template.path` -- for example, in a properties file made available to the Spring `Environment` (see -<>). The template path can then be referenced via the `@Value` -annotation using a property placeholder (see <>). Spring will +xref:core/beans/environment.adoc[Environment Abstraction]). The template path can then be referenced via the `@Value` +annotation using a property placeholder (see xref:core/beans/annotation-config/value-annotations.adoc[Using `@Value`]). Spring will retrieve the value of the template path as a string, and a special `PropertyEditor` will convert the string to a `Resource` object to be injected into the `MyBean` constructor. The following example demonstrates how to achieve this. diff --git a/framework-docs/modules/ROOT/pages/core/validation.adoc b/framework-docs/modules/ROOT/pages/core/validation.adoc index 84bad43d2d..cc55989412 100644 --- a/framework-docs/modules/ROOT/pages/core/validation.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation.adoc @@ -30,9 +30,9 @@ implementations. They are also discussed in this chapter. Spring supports Java Bean Validation through setup infrastructure and an adaptor to Spring's own `Validator` contract. Applications can enable Bean Validation once globally, -as described in <>, and use it exclusively for all validation +as described in xref:core/validation/beanvalidation.adoc[Java Bean Validation], and use it exclusively for all validation needs. In the web layer, applications can further register controller-local Spring -`Validator` instances per `DataBinder`, as described in <>, which can +`Validator` instances per `DataBinder`, as described in xref:core/validation/beanvalidation.adoc#validation-binder[Configuring a `DataBinder`], which can be useful for plugging in custom validation logic. diff --git a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc b/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc index 439125a3cb..c22f3c6ff6 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc @@ -57,7 +57,7 @@ details. The below table shows some examples of these conventions: (This next section is not vitally important to you if you do not plan to work with the `BeanWrapper` directly. If you use only the `DataBinder` and the `BeanFactory` and their default implementations, you should skip ahead to the -<>.) +xref:core/validation/beans-beans.adoc#beans-beans-conversion[section on `PropertyEditors`].) The following two example classes use the `BeanWrapper` to get and set properties: @@ -378,7 +378,7 @@ where it can be automatically detected and applied. Note that all bean factories and application contexts automatically use a number of built-in property editors, through their use of a `BeanWrapper` to handle property conversions. The standard property editors that the `BeanWrapper` -registers are listed in the <>. +registers are listed in the xref:core/validation/beans-beans.adoc#beans-beans-conversion[previous section]. Additionally, ``ApplicationContext``s also override or add additional editors to handle resource lookups in a manner appropriate to the specific application context type. @@ -495,7 +495,7 @@ You can write a corresponding registrar and reuse it in each case. `PropertyEditorRegistry`, an interface that is implemented by the Spring `BeanWrapper` (and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient when used in conjunction with `CustomEditorConfigurer` (described -<>), which exposes a property +xref:core/validation/beans-beans.adoc#beans-beans-conversion-customeditor-registration[here]), which exposes a property called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added to a `CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and Spring MVC controllers. Furthermore, it avoids the need for synchronization on custom @@ -562,7 +562,7 @@ of our `CustomPropertyEditorRegistrar` into it: ---- Finally (and in a bit of a departure from the focus of this chapter) for those of you -using <>, using a `PropertyEditorRegistrar` in +using xref:web/webmvc.adoc#mvc[Spring's MVC web framework], using a `PropertyEditorRegistrar` in conjunction with data-binding web controllers can be very convenient. The following example uses a `PropertyEditorRegistrar` in the implementation of an `@InitBinder` method: diff --git a/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc b/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc index 9a7978e5bd..46b410824f 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc @@ -265,10 +265,10 @@ for setup details with the Hibernate Validator and Bean Validation 1.1 providers [TIP] ==== -Method validation relies on <> around the +Method validation relies on xref:core/aop/introduction-proxies.adoc[AOP Proxies] around the target classes, either JDK dynamic proxies for methods on interfaces or CGLIB proxies. There are certain limitations with the use of proxies, some of which are described in -<>. In addition remember +xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[Understanding AOP Proxies]. In addition remember to always use methods and accessors on proxied classes; direct field access will not work. ==== @@ -333,11 +333,11 @@ You can also configure a `DataBinder` with multiple `Validator` instances throug `dataBinder.addValidators` and `dataBinder.replaceValidators`. This is useful when combining globally configured bean validation with a Spring `Validator` configured locally on a DataBinder instance. See -<>. +xref:web/webmvc/mvc-config/validation.adoc[Spring MVC Validation Configuration]. [[validation-mvc]] == Spring MVC 3 Validation -See <> in the Spring MVC chapter. +See xref:web/webmvc/mvc-config/validation.adoc[Validation] in the Spring MVC chapter. diff --git a/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc b/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc index 07bc88f064..49deddde0c 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/conversion.adoc @@ -2,7 +2,7 @@ = Resolving Codes to Error Messages We covered databinding and validation. This section covers outputting messages that correspond -to validation errors. In the example shown in the <>, +to validation errors. In the example shown in the xref:core/validation/validator.adoc[preceding section], we rejected the `name` and `age` fields. If we want to output the error messages by using a `MessageSource`, we can do so using the error code we provide when rejecting the field ('name' and 'age' in this case). When you call (either directly, or indirectly, by using, diff --git a/framework-docs/modules/ROOT/pages/core/validation/convert.adoc b/framework-docs/modules/ROOT/pages/core/validation/convert.adoc index fd5fc3af68..3d33722dce 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/convert.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/convert.adoc @@ -246,10 +246,10 @@ any of the `Converter`, `ConverterFactory`, or `GenericConverter` interfaces. ---- It is also common to use a `ConversionService` within a Spring MVC application. See -<> in the Spring MVC chapter. +xref:web/webmvc/mvc-config/conversion.adoc[Conversion and Formatting] in the Spring MVC chapter. In certain situations, you may wish to apply formatting during conversion. See -<> for details on using `FormattingConversionServiceFactoryBean`. +xref:core/validation/format.adoc#format-FormatterRegistry-SPI[The `FormatterRegistry` SPI] for details on using `FormattingConversionServiceFactoryBean`. diff --git a/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc b/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc index 90eb0f374f..053d98d73c 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc @@ -108,8 +108,8 @@ If you prefer XML-based configuration, you can use a Note there are extra considerations when configuring date and time formats in web applications. Please see -<> or -<>. +xref:web/webmvc/mvc-config/conversion.adoc[WebMVC Conversion and Formatting] or +xref:web/webflux/config.adoc#webflux-config-conversion[WebFlux Conversion and Formatting]. diff --git a/framework-docs/modules/ROOT/pages/core/validation/format.adoc b/framework-docs/modules/ROOT/pages/core/validation/format.adoc index b636cb0943..c344b2c731 100644 --- a/framework-docs/modules/ROOT/pages/core/validation/format.adoc +++ b/framework-docs/modules/ROOT/pages/core/validation/format.adoc @@ -1,7 +1,7 @@ [[format]] = Spring Field Formatting -As discussed in the previous section, <> is a +As discussed in the previous section, xref:core/validation/convert.adoc[`core.convert`] is a general-purpose type conversion system. It provides a unified `ConversionService` API as well as a strongly typed `Converter` SPI for implementing conversion logic from one type to another. A Spring container uses this system to bind bean property values. In @@ -356,7 +356,7 @@ converter and formatter registration. [[format-configuring-formatting-mvc]] == Configuring Formatting in Spring MVC -See <> in the Spring MVC chapter. +See xref:web/webmvc/mvc-config/conversion.adoc[Conversion and Formatting] in the Spring MVC chapter. diff --git a/framework-docs/modules/ROOT/pages/data-access/appendix.adoc b/framework-docs/modules/ROOT/pages/data-access/appendix.adoc index 449c86095d..3bd4f80fde 100644 --- a/framework-docs/modules/ROOT/pages/data-access/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/appendix.adoc @@ -9,8 +9,8 @@ This part of the appendix lists XML schemas for data access, including the following: -* <> -* <> +* xref:data-access/appendix.adoc#xsd-schemas-tx[The `tx` Schema] +* xref:data-access/appendix.adoc#xsd-schemas-jdbc[The `jdbc` Schema] @@ -19,7 +19,7 @@ This part of the appendix lists XML schemas for data access, including the follo The `tx` tags deal with configuring all of those beans in Spring's comprehensive support for transactions. These tags are covered in the chapter entitled -<>. +xref:data-access/transaction.adoc[Transaction Management]. TIP: We strongly encourage you to look at the `'spring-tx.xsd'` file that ships with the Spring distribution. This file contains the XML Schema for Spring's transaction @@ -68,8 +68,8 @@ to you. The `jdbc` elements let you quickly configure an embedded database or initialize an existing data source. These elements are documented in -<> and -<>, respectively. +xref:data-access/jdbc/embedded-database-support.adoc[Embedded Database Support] and +xref:data-access/jdbc/initializing-datasource.adoc[Initializing a DataSource], respectively. To use the elements in the `jdbc` schema, you need to have the following preamble at the top of your Spring XML configuration file. The text in the following snippet references diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc index 9c40642d57..203952f64a 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc @@ -198,7 +198,7 @@ While this usually works well, there is a potential for issues (for example, wit case, which can be expensive with your JDBC driver. You should use a recent driver version and consider setting the `spring.jdbc.getParameterType.ignore` property to `true` (as a JVM system property or via the -<> mechanism) if you encounter +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism) if you encounter a performance issue (as reported on Oracle 12c, JBoss, and PostgreSQL). Alternatively, you might consider specifying the corresponding JDBC types explicitly, diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc index 80fe71b593..fb787e7fa6 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc @@ -3,14 +3,14 @@ This section covers: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:data-access/jdbc/connections.adoc#jdbc-datasource[Using `DataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-DataSourceUtils[Using `DataSourceUtils`] +* xref:data-access/jdbc/connections.adoc#jdbc-SmartDataSource[Implementing `SmartDataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-AbstractDataSource[Extending `AbstractDataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-SingleConnectionDataSource[Using `SingleConnectionDataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-DriverManagerDataSource[Using `DriverManagerDataSource`] +* xref:data-access/jdbc/connections.adoc#jdbc-TransactionAwareDataSourceProxy[Using `TransactionAwareDataSourceProxy`] +* xref:data-access/jdbc/connections.adoc#jdbc-DataSourceTransactionManager[Using `DataSourceTransactionManager`] [[jdbc-datasource]] diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc index a2488bfa21..73c5bda829 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc @@ -4,13 +4,13 @@ This section covers how to use the JDBC core classes to control basic JDBC processing, including error handling. It includes the following topics: -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate[Using `JdbcTemplate`] +* xref:data-access/jdbc/core.adoc#jdbc-NamedParameterJdbcTemplate[Using `NamedParameterJdbcTemplate`] +* xref:data-access/jdbc/core.adoc#jdbc-SQLExceptionTranslator[Using `SQLExceptionTranslator`] +* xref:data-access/jdbc/core.adoc#jdbc-statements-executing[Running Statements] +* xref:data-access/jdbc/core.adoc#jdbc-statements-querying[Running Queries] +* xref:data-access/jdbc/core.adoc#jdbc-updates[Updating the Database] +* xref:data-access/jdbc/core.adoc#jdbc-auto-generated-keys[Retrieving Auto-generated Keys] [[jdbc-JdbcTemplate]] @@ -26,7 +26,7 @@ SQL and extract results. The `JdbcTemplate` class: * Updates statements and stored procedure calls * Performs iteration over `ResultSet` instances and extraction of returned parameter values. * Catches JDBC exceptions and translates them to the generic, more informative, exception -hierarchy defined in the `org.springframework.dao` package. (See <>.) +hierarchy defined in the `org.springframework.dao` package. (See xref:data-access/dao.adoc#dao-exceptions[Consistent Exception Hierarchy].) When you use the `JdbcTemplate` for your code, you need only to implement callback interfaces, giving them a clearly defined contract. Given a `Connection` provided by the @@ -270,7 +270,7 @@ The following example invokes a stored procedure: ---- -More sophisticated stored procedure support is <>. +More sophisticated stored procedure support is xref:data-access/jdbc/object.adoc#jdbc-StoredProcedure[covered later]. [[jdbc-JdbcTemplate-idioms]] === `JdbcTemplate` Best Practices @@ -282,7 +282,7 @@ The `JdbcTemplate` is stateful, in that it maintains a reference to a `DataSourc this state is not conversational state. A common practice when using the `JdbcTemplate` class (and the associated -<> class) is to +xref:data-access/jdbc/core.adoc#jdbc-NamedParameterJdbcTemplate[`NamedParameterJdbcTemplate`] class) is to configure a `DataSource` in your Spring configuration file and then dependency-inject that shared `DataSource` bean into your DAO classes. The `JdbcTemplate` is created in the setter for the `DataSource`. This leads to DAOs that resemble the following: @@ -607,7 +607,7 @@ functionality that is present only in the `JdbcTemplate` class, you can use the `getJdbcOperations()` method to access the wrapped `JdbcTemplate` through the `JdbcOperations` interface. -See also <> for guidelines on using the +See also xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate-idioms[`JdbcTemplate` Best Practices] for guidelines on using the `NamedParameterJdbcTemplate` class in the context of an application. diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc index 53b4a855ae..740d49db44 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc @@ -129,9 +129,9 @@ configuration, as the following example shows: This section covers how to select one of the three embedded databases that Spring supports. It includes the following topics: -* <> -* <> -* <> +* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-HSQL[Using HSQL] +* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-H2[Using H2] +* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-Derby[Using Derby] [[jdbc-embedded-database-using-HSQL]] === Using HSQL @@ -163,9 +163,9 @@ Embedded databases provide a lightweight way to test data access code. The next data access integration test template that uses an embedded database. Using such a template can be useful for one-offs when the embedded database does not need to be reused across test classes. However, if you wish to create an embedded database that is shared within a test suite, -consider using the <> and +consider using the xref:testing/testcontext-framework.adoc[Spring TestContext Framework] and configuring the embedded database as a bean in the Spring `ApplicationContext` as described -in <> and <>. The following listing +in xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-xml[Creating an Embedded Database by Using Spring XML] and xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-java[Creating an Embedded Database Programmatically]. The following listing shows the test template: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc index f3489b5082..4e0610bfd1 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc @@ -10,7 +10,7 @@ procedures and run update, delete, and insert statements. [NOTE] ==== Many Spring developers believe that the various RDBMS operation classes described below -(with the exception of the <> class) can often +(with the exception of the xref:data-access/jdbc/object.adoc#jdbc-StoredProcedure[`StoredProcedure`] class) can often be replaced with straight `JdbcTemplate` calls. Often, it is simpler to write a DAO method that calls a method on a `JdbcTemplate` directly (as opposed to encapsulating a query as a full-blown class). @@ -236,7 +236,7 @@ The SQL type is specified using the `java.sql.Types` constants. The first line (with the `SqlParameter`) declares an IN parameter. You can use IN parameters both for stored procedure calls and for queries using the `SqlQuery` and its -subclasses (covered in <>). +subclasses (covered in xref:data-access/jdbc/object.adoc#jdbc-SqlQuery[Understanding `SqlQuery`]). The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in the stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc index 5d4a56cbb5..e6719fec87 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc @@ -8,19 +8,19 @@ various callback interfaces, plus a variety of related classes. A subpackage nam `org.springframework.jdbc.core.simple` contains the `SimpleJdbcInsert` and `SimpleJdbcCall` classes. Another subpackage named `org.springframework.jdbc.core.namedparam` contains the `NamedParameterJdbcTemplate` -class and the related support classes. See <>, <>, and -<>. +class and the related support classes. See xref:data-access/jdbc/core.adoc[Using the JDBC Core Classes to Control Basic JDBC Processing and Error Handling], xref:data-access/jdbc/advanced.adoc[JDBC Batch Operations], and +xref:data-access/jdbc/simple.adoc[Simplifying JDBC Operations with the `SimpleJdbc` Classes]. * `datasource`: The `org.springframework.jdbc.datasource` package contains a utility class for easy `DataSource` access and various simple `DataSource` implementations that you can use for testing and running unmodified JDBC code outside of a Jakarta EE container. A subpackage named `org.springfamework.jdbc.datasource.embedded` provides support for creating embedded databases by using Java database engines, such as HSQL, H2, and Derby. See -<> and <>. +xref:data-access/jdbc/connections.adoc[Controlling Database Connections] and xref:data-access/jdbc/embedded-database-support.adoc[Embedded Database Support]. * `object`: The `org.springframework.jdbc.object` package contains classes that represent RDBMS queries, updates, and stored procedures as thread-safe, reusable objects. See -<>. This approach is modeled by JDO, although objects returned by queries +xref:data-access/jdbc/object.adoc[Modeling JDBC Operations as Java Objects]. This approach is modeled by JDO, although objects returned by queries are naturally disconnected from the database. This higher-level of JDBC abstraction depends on the lower-level abstraction in the `org.springframework.jdbc.core` package. @@ -30,7 +30,7 @@ translated to exceptions defined in the `org.springframework.dao` package. This that code using the Spring JDBC abstraction layer does not need to implement JDBC or RDBMS-specific error handling. All translated exceptions are unchecked, which gives you the option of catching the exceptions from which you can recover while letting other -exceptions be propagated to the caller. See <>. +exceptions be propagated to the caller. See xref:data-access/jdbc/core.adoc#jdbc-SQLExceptionTranslator[Using `SQLExceptionTranslator`]. diff --git a/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc b/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc index ef434dce1c..8b711afb55 100644 --- a/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc @@ -437,7 +437,7 @@ returned `out` parameters. Earlier in this chapter, we described how parameters are deduced from metadata, but you can declare them explicitly if you wish. You can do so by creating and configuring `SimpleJdbcCall` with the `declareParameters` method, which takes a variable number of `SqlParameter` objects -as input. See the <> for details on how to define an `SqlParameter`. +as input. See the xref:data-access/jdbc/simple.adoc#jdbc-params[next section] for details on how to define an `SqlParameter`. NOTE: Explicit declarations are necessary if the database you use is not a Spring-supported database. Currently, Spring supports metadata lookup of stored procedure calls for the @@ -510,7 +510,7 @@ details explicitly rather than relying on metadata. == How to Define `SqlParameters` To define a parameter for the `SimpleJdbc` classes and also for the RDBMS operations -classes (covered in <>) you can use `SqlParameter` or one of its subclasses. +classes (covered in xref:data-access/jdbc/object.adoc[Modeling JDBC Operations as Java Objects]) you can use `SqlParameter` or one of its subclasses. To do so, you typically specify the parameter name and SQL type in the constructor. The SQL type is specified by using the `java.sql.Types` constants. Earlier in this chapter, we saw declarations similar to the following: @@ -530,7 +530,7 @@ similar to the following: The first line with the `SqlParameter` declares an IN parameter. You can use IN parameters for both stored procedure calls and for queries by using the `SqlQuery` and its -subclasses (covered in <>). +subclasses (covered in xref:data-access/jdbc/object.adoc#jdbc-SqlQuery[Understanding `SqlQuery`]). The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in a stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc index 846760f93d..bb47bbd68f 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/general.adoc @@ -2,7 +2,7 @@ = General ORM Integration Considerations This section highlights considerations that apply to all ORM technologies. -The <> section provides more details and also show these features and +The xref:data-access/orm/hibernate.adoc[Hibernate] section provides more details and also show these features and configurations in a concrete context. The major goal of Spring's ORM integration is clear application layering (with any data @@ -31,18 +31,18 @@ interceptors for the ORM technologies. The infrastructure provides proper resource handling and appropriate conversion of specific API exceptions to an unchecked infrastructure exception hierarchy. Spring introduces a DAO exception hierarchy, applicable to any data access strategy. For direct -JDBC, the `JdbcTemplate` class mentioned in a <> +JDBC, the `JdbcTemplate` class mentioned in a xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate[previous section] provides connection handling and proper conversion of `SQLException` to the `DataAccessException` hierarchy, including translation of database-specific SQL error codes to meaningful exception classes. For ORM technologies, see the -<> for how to get the same exception +xref:data-access/orm/general.adoc#orm-exception-translation[next section] for how to get the same exception translation benefits. When it comes to transaction management, the `JdbcTemplate` class hooks in to the Spring transaction support and supports both JTA and JDBC transactions, through respective Spring transaction managers. For the supported ORM technologies, Spring offers Hibernate and JPA support through the Hibernate and JPA transaction managers as well as JTA support. -For details on transaction support, see the <> chapter. +For details on transaction support, see the xref:data-access/transaction.adoc[Transaction Management] chapter. [[orm-exception-translation]] diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc index fb32064e91..c449194c0a 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc @@ -21,7 +21,7 @@ To avoid tying application objects to hard-coded resource lookups, you can defin resources (such as a JDBC `DataSource` or a Hibernate `SessionFactory`) as beans in the Spring container. Application objects that need to access resources receive references to such predefined instances through bean references, as illustrated in the DAO -definition in the <>. +definition in the xref:data-access/orm/hibernate.adoc#orm-hibernate-straight[next section]. The following excerpt from an XML application context definition shows how to set up a JDBC `DataSource` and a Hibernate `SessionFactory` on top of it: @@ -83,7 +83,7 @@ property. On the programmatic `LocalSessionFactoryBuilder`, there is an overload As of Spring Framework 5.1, such a native Hibernate setup can also expose a JPA `EntityManagerFactory` for standard JPA interaction next to native Hibernate access. -See <> for details. +See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate Setup for JPA] for details. ==== @@ -185,7 +185,7 @@ container by using either Java annotations or XML. This declarative transaction lets you keep business services free of repetitive transaction demarcation code and focus on adding business logic, which is the real value of your application. -NOTE: Before you continue, we are strongly encourage you to read <> +NOTE: Before you continue, we are strongly encourage you to read xref:data-access/transaction/declarative.adoc[Declarative Transaction Management] if you have not already done so. You can annotate the service layer with `@Transactional` annotations and instruct the @@ -447,7 +447,7 @@ to which it synchronizes (along with Spring). You have two options for doing thi * Pass your Spring `JtaTransactionManager` bean to your Hibernate setup. The easiest way is a bean reference into the `jtaTransactionManager` property for your - `LocalSessionFactoryBean` bean (see <>). + `LocalSessionFactoryBean` bean (see xref:data-access/transaction/strategies.adoc#transaction-strategies-hibernate[Hibernate Transaction Setup]). Spring then makes the corresponding JTA strategies available to Hibernate. * You may also configure Hibernate's JTA-related properties explicitly, in particular "hibernate.transaction.coordinator_class", "hibernate.connection.handling_mode" diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc index 58b4b8aade..bfb3e3c532 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc @@ -48,7 +48,7 @@ The benefits of using the Spring Framework to create your ORM DAOs include: aspect-oriented programming (AOP) style method interceptor either through the `@Transactional` annotation or by explicitly configuring the transaction AOP advice in an XML configuration file. In both cases, transaction semantics and exception handling - (rollback and so on) are handled for you. As discussed in <>, + (rollback and so on) are handled for you. As discussed in xref:data-access/orm/general.adoc#orm-resource-mngmnt[Resource and Transaction Management], you can also swap various transaction managers, without affecting your ORM-related code. For example, you can swap between local transactions and JTA, with the same full services (such as declarative transactions) available in both scenarios. Additionally, diff --git a/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc b/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc index 76fc822098..3f02651697 100644 --- a/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc @@ -14,9 +14,9 @@ the underlying implementation in order to provide additional features. The Spring JPA support offers three ways of setting up the JPA `EntityManagerFactory` that is used by the application to obtain an entity manager. -* <> -* <> -* <> +* xref:data-access/orm/jpa.adoc#orm-jpa-setup-lemfb[Using `LocalEntityManagerFactoryBean`] +* xref:data-access/orm/jpa.adoc#orm-jpa-setup-jndi[Obtaining an EntityManagerFactory from JNDI] +* xref:data-access/orm/jpa.adoc#orm-jpa-setup-lcemfb[Using `LocalContainerEntityManagerFactoryBean`] [[orm-jpa-setup-lemfb]] === Using `LocalEntityManagerFactoryBean` @@ -92,7 +92,7 @@ NOTE: If you want to specifically configure a Hibernate setup, an immediate alte is to set up a native Hibernate `LocalSessionFactoryBean` instead of a plain JPA `LocalContainerEntityManagerFactoryBean`, letting it interact with JPA access code as well as native Hibernate access code. -See <> for details. +See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate setup for JPA interaction] for details. The `LocalContainerEntityManagerFactoryBean` gives full control over `EntityManagerFactory` configuration and is appropriate for environments where @@ -172,11 +172,11 @@ Spring provides a number of `LoadTimeWeaver` implementations for various environ letting `ClassTransformer` instances be applied only for each class loader and not for each VM. -See the <> in the AOP chapter for +See the xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration] in the AOP chapter for more insight regarding the `LoadTimeWeaver` implementations and their setup, either generic or customized to various platforms (such as Tomcat, JBoss and WebSphere). -As described in <>, you can configure +As described in xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration], you can configure a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation or the `context:load-time-weaver` XML element. Such a global weaver is automatically picked up by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example @@ -452,7 +452,7 @@ a non-invasiveness perspective and can feel more natural to JPA developers. [[orm-jpa-tx]] == Spring-driven JPA transactions -NOTE: We strongly encourage you to read <>, if you have not +NOTE: We strongly encourage you to read xref:data-access/transaction/declarative.adoc[Declarative Transaction Management], if you have not already done so, to get more detailed coverage of Spring's declarative transaction support. The recommended strategy for JPA is local transactions through JPA's native transaction @@ -464,12 +464,12 @@ Spring JPA also lets a configured `JpaTransactionManager` expose a JPA transacti to JDBC access code that accesses the same `DataSource`, provided that the registered `JpaDialect` supports retrieval of the underlying JDBC `Connection`. Spring provides dialects for the EclipseLink and Hibernate JPA implementations. -See the <> for details on the `JpaDialect` mechanism. +See the xref:data-access/orm/jpa.adoc#orm-jpa-dialect[next section] for details on the `JpaDialect` mechanism. NOTE: As an immediate alternative, Spring's native `HibernateTransactionManager` is capable of interacting with JPA access code, adapting to several Hibernate specifics and providing JDBC interaction. This makes particular sense in combination with `LocalSessionFactoryBean` -setup. See <> for details. +setup. See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate Setup for JPA Interaction] for details. [[orm-jpa-dialect]] @@ -529,7 +529,7 @@ Hibernate 5.0 but not any more in Hibernate 5.1+. For a JTA setup, make sure to your persistence unit transaction type as "JTA". Alternatively, set Hibernate 5.2's `hibernate.connection.handling_mode` property to `DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT` to restore Hibernate's own default. -See <> for related notes. +See xref:data-access/orm/hibernate.adoc#orm-hibernate-invalid-jdbc-access-error[Spurious Application Server Warnings with Hibernate] for related notes. * Alternatively, consider obtaining the `EntityManagerFactory` from your application server itself (that is, through a JNDI lookup instead of a locally declared @@ -565,7 +565,7 @@ seamlessly integrating with `@Bean` style configuration (no `FactoryBean` involv ==== `LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background bootstrapping, just as the JPA `LocalContainerEntityManagerFactoryBean` does. -See <> for an introduction. +See xref:data-access/orm/jpa.adoc#orm-jpa-setup-background[Background Bootstrapping] for an introduction. On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor` property. On the programmatic `LocalSessionFactoryBuilder`, an overloaded diff --git a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc index 1ead502a7f..81aec53f13 100644 --- a/framework-docs/modules/ROOT/pages/data-access/oxm.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/oxm.adoc @@ -18,9 +18,9 @@ stream, or a SAX handler. Some of the benefits of using Spring for your O/X mapping needs are: -* <> -* <> -* <> +* xref:data-access/oxm.adoc#oxm-ease-of-configuration[Ease of configuration] +* xref:data-access/oxm.adoc#oxm-consistent-interfaces[Consistent Interfaces] +* xref:data-access/oxm.adoc#oxm-consistent-exception-hierarchy[Consistent Exception Hierarchy] [[oxm-ease-of-configuration]] @@ -57,7 +57,7 @@ These runtime exceptions wrap the original exception so that no information is l [[oxm-marshaller-unmarshaller]] == `Marshaller` and `Unmarshaller` -As stated in the <>, a marshaller serializes an object +As stated in the xref:data-access/oxm.adoc#oxm-introduction[introduction], a marshaller serializes an object to XML, and an unmarshaller deserializes XML stream to an object. This section describes the two Spring interfaces used for this purpose. @@ -332,8 +332,8 @@ preamble of the XML configuration file. The following example shows how to do so The schema makes the following elements available: -* <> -* <> +* xref:data-access/oxm.adoc#oxm-jaxb2-xsd[`jaxb2-marshaller`] +* xref:data-access/oxm.adoc#oxm-jibx-xsd[`jibx-marshaller`] Each tag is explained in its respective marshaller's section. As an example, though, the configuration of a JAXB2 marshaller might resemble the following: @@ -353,7 +353,7 @@ The JAXB binding compiler translates a W3C XML Schema into one or more Java clas generate a schema from annotated Java classes. Spring supports the JAXB 2.0 API as XML marshalling strategies, following the -`Marshaller` and `Unmarshaller` interfaces described in <>. +`Marshaller` and `Unmarshaller` interfaces described in xref:data-access/oxm.adoc#oxm-marshaller-unmarshaller[`Marshaller` and `Unmarshaller`]. The corresponding integration classes reside in the `org.springframework.oxm.jaxb` package. diff --git a/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc b/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc index 178387529f..1345dd5fb0 100644 --- a/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc @@ -11,11 +11,11 @@ specification effort to standardize access to SQL databases using reactive patte The Spring Framework's R2DBC abstraction framework consists of two different packages: * `core`: The `org.springframework.r2dbc.core` package contains the `DatabaseClient` -class plus a variety of related classes. See <>. +class plus a variety of related classes. See xref:data-access/r2dbc.adoc#r2dbc-core[Using the R2DBC Core Classes to Control Basic R2DBC Processing and Error Handling]. * `connection`: The `org.springframework.r2dbc.connection` package contains a utility class for easy `ConnectionFactory` access and various simple `ConnectionFactory` implementations -that you can use for testing and running unmodified R2DBC. See <>. +that you can use for testing and running unmodified R2DBC. See xref:data-access/r2dbc.adoc#r2dbc-connections[Controlling Database Connections]. [[r2dbc-core]] @@ -24,12 +24,12 @@ that you can use for testing and running unmodified R2DBC. See <> -* <> -* <> -* <> -* <> -* <> +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient[Using `DatabaseClient`] +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-statement[Executing Statements] +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-query[Querying (`SELECT`)] +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-update[Updating (`INSERT`, `UPDATE`, and `DELETE`) with `DatabaseClient`] +* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-filter[Statement Filters] +* xref:data-access/r2dbc.adoc#r2dbc-auto-generated-keys[Retrieving Auto-generated Keys] [[r2dbc-DatabaseClient]] === Using `DatabaseClient` @@ -44,7 +44,7 @@ SQL and extract results. The `DatabaseClient` class: * Update statements and stored procedure calls * Performs iteration over `Result` instances * Catches R2DBC exceptions and translates them to the generic, more informative, exception -hierarchy defined in the `org.springframework.dao` package. (See <>.) +hierarchy defined in the `org.springframework.dao` package. (See xref:data-access/dao.adoc#dao-exceptions[Consistent Exception Hierarchy].) The client has a functional, fluent API using reactive types for declarative composition. @@ -543,11 +543,11 @@ requests the generated key for the desired column. This section covers: -* <> -* <> -* <> -* <> -* <> +* xref:data-access/r2dbc.adoc#r2dbc-ConnectionFactory[Using `ConnectionFactory`] +* xref:data-access/r2dbc.adoc#r2dbc-ConnectionFactoryUtils[Using `ConnectionFactoryUtils`] +* xref:data-access/r2dbc.adoc#r2dbc-SingleConnectionFactory[Using `SingleConnectionFactory`] +* xref:data-access/r2dbc.adoc#r2dbc-TransactionAwareConnectionFactoryProxy[Using `TransactionAwareConnectionFactoryProxy`] +* xref:data-access/r2dbc.adoc#r2dbc-R2dbcTransactionManager[Using `R2dbcTransactionManager`] [[r2dbc-ConnectionFactory]] diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction.adoc index 758ef2eddb..10254968d8 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction.adoc @@ -7,34 +7,34 @@ management that delivers the following benefits: * A consistent programming model across different transaction APIs, such as Java Transaction API (JTA), JDBC, Hibernate, and the Java Persistence API (JPA). -* Support for <>. -* A simpler API for <> transaction management +* Support for xref:data-access/transaction/declarative.adoc[declarative transaction management]. +* A simpler API for xref:data-access/transaction/programmatic.adoc[programmatic] transaction management than complex transaction APIs, such as JTA. * Excellent integration with Spring's data access abstractions. The following sections describe the Spring Framework's transaction features and technologies: -* <> describes why you would use the Spring Framework's transaction abstraction +* xref:data-access/transaction/motivation.adoc[Advantages of the Spring Framework's transaction support model] + describes why you would use the Spring Framework's transaction abstraction instead of EJB Container-Managed Transactions (CMT) or choosing to drive local transactions through a proprietary API, such as Hibernate. -* <> +* xref:data-access/transaction/strategies.adoc[Understanding the Spring Framework transaction abstraction] outlines the core classes and describes how to configure and obtain `DataSource` instances from a variety of sources. -* <> describes +* xref:data-access/transaction/tx-resource-synchronization.adoc[Synchronizing resources with transactions] describes how the application code ensures that resources are created, reused, and cleaned up properly. -* <> describes support for +* xref:data-access/transaction/declarative.adoc[Declarative transaction management] describes support for declarative transaction management. -* <> covers support for +* xref:data-access/transaction/programmatic.adoc[Programmatic transaction management] covers support for programmatic (that is, explicitly coded) transaction management. -* <> describes how you could use application +* xref:data-access/transaction/event.adoc[Transaction bound event] describes how you could use application events within a transaction. The chapter also includes discussions of best practices, -<>, -and <>. +xref:data-access/transaction/application-server-integration.adoc[application server integration], +and xref:data-access/transaction/solutions-to-common-problems.adoc[solutions to common problems]. diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc index 949f8285df..a87442d891 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc @@ -22,7 +22,7 @@ necessary. The differences between the two types of transaction management are: * You can apply the Spring Framework declarative transaction management to any class, not merely special classes such as EJBs. * The Spring Framework offers declarative - <>, a feature with no EJB + xref:data-access/transaction/declarative/rolling-back.adoc[rollback rules], a feature with no EJB equivalent. Both programmatic and declarative support for rollback rules is provided. * The Spring Framework lets you customize transactional behavior by using AOP. For example, you can insert custom behavior in the case of transaction rollback. You diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc index 536df97c36..83c9609e70 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc @@ -70,7 +70,7 @@ Consider the following class definition: Used at the class level as above, the annotation indicates a default for all methods of the declaring class (as well as its subclasses). Alternatively, each method can be -annotated individually. See <> for +annotated individually. See xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-annotations-method-visibility[null] for further details on which methods Spring considers transactional. Note that a class-level annotation does not apply to ancestor classes up the class hierarchy; in such a scenario, inherited methods need to be locally redeclared in order to participate in a @@ -182,7 +182,7 @@ programming arrangements as the following listing shows: ---- Note that there are special considerations for the returned `Publisher` with regards to -Reactive Streams cancellation signals. See the <> section under +Reactive Streams cancellation signals. See the xref:data-access/transaction/programmatic.adoc#tx-prog-operator-cancel[Cancel Signals] section under "Using the TransactionalOperator" for more details. @@ -221,7 +221,7 @@ Note, however, that transactional methods in interface-based proxies must always ---- The _Spring TestContext Framework_ supports non-private `@Transactional` test methods by -default. See <> in the testing +default. See xref:testing/testcontext-framework/tx.adoc[Transaction Management] in the testing chapter for examples. ==== @@ -276,7 +276,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method. affected classes with Spring's AspectJ transaction aspect, modifying the target class byte code to apply to any kind of method call. AspectJ weaving requires `spring-aspects.jar` in the classpath as well as having load-time weaving (or compile-time - weaving) enabled. (See <> + weaving) enabled. (See xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration] for details on how to set up load-time weaving.) | `proxy-target-class` @@ -286,7 +286,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method. for classes annotated with the `@Transactional` annotation. If the `proxy-target-class` attribute is set to `true`, class-based proxies are created. If `proxy-target-class` is `false` or if the attribute is omitted, then standard JDK - interface-based proxies are created. (See <> + interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms] for a detailed examination of the different proxy types.) | `order` @@ -294,7 +294,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method. | `Ordered.LOWEST_PRECEDENCE` | Defines the order of the transaction advice that is applied to beans annotated with `@Transactional`. (For more information about the rules related to ordering of AOP - advice, see <>.) + advice, see xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice Ordering].) No specified ordering means that the AOP subsystem determines the order of the advice. |=== @@ -307,14 +307,14 @@ NOTE: The `proxy-target-class` attribute controls what type of transactional pro created for classes annotated with the `@Transactional` annotation. If `proxy-target-class` is set to `true`, class-based proxies are created. If `proxy-target-class` is `false` or if the attribute is omitted, standard JDK -interface-based proxies are created. (See <> +interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms] for a discussion of the different proxy types.) NOTE: `@EnableTransactionManagement` and `` look for `@Transactional` only on beans in the same application context in which they are defined. This means that, if you put annotation-driven configuration in a `WebApplicationContext` for a `DispatcherServlet`, it checks for `@Transactional` beans only in your controllers -and not in your services. See <> for more information. +and not in your services. See xref:web/webmvc/mvc-servlet.adoc[MVC] for more information. The most derived location takes precedence when evaluating the transactional settings for a method. In the case of the following example, the `DefaultFooService` class is @@ -382,7 +382,7 @@ properties of the `@Transactional` annotation: |=== | Property| Type| Description -| <> +| xref:data-access/transaction/declarative/annotations.adoc#tx-multiple-tx-mgrs-with-attransactional[value] | `String` | Optional qualifier that specifies the transaction manager to be used. @@ -394,7 +394,7 @@ properties of the `@Transactional` annotation: | Array of `String` labels to add an expressive description to the transaction. | Labels may be evaluated by transaction managers to associate implementation-specific behavior with the actual transaction. -| <> +| xref:data-access/transaction/declarative/tx-propagation.adoc[propagation] | `enum`: `Propagation` | Optional propagation setting. @@ -431,7 +431,7 @@ properties of the `@Transactional` annotation: | Optional array of exception name patterns that must not cause rollback. |=== -TIP: See <> for further details +TIP: See xref:data-access/transaction/declarative/rolling-back.adoc#transaction-declarative-rollback-rules[Rollback rules] for further details on rollback rule semantics, patterns, and warnings regarding possible unintentional matches for pattern-based rollback rules. @@ -523,7 +523,7 @@ is still used if no specifically qualified `TransactionManager` bean is found. == Custom Composed Annotations If you find you repeatedly use the same attributes with `@Transactional` on many different -methods, <> lets you +methods, xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[Spring's meta-annotation support] lets you define custom composed annotations for your specific use cases. For example, consider the following annotation definitions: diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc index a9fd8d8b2f..38d49bc4b0 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc @@ -13,7 +13,7 @@ When you invoke the `updateFoo(Foo)` method, you want to see the following actio * The profiling aspect reports the exact duration of the whole transactional method invocation. NOTE: This chapter is not concerned with explaining AOP in any great detail (except as it -applies to transactions). See <> for detailed coverage of the AOP +applies to transactions). See xref:core/aop.adoc[AOP] for detailed coverage of the AOP configuration and AOP in general. The following code shows the simple profiling aspect discussed earlier: @@ -95,7 +95,7 @@ The following code shows the simple profiling aspect discussed earlier: The ordering of advice is controlled through the `Ordered` interface. For full details on advice ordering, see -<>. +xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice ordering]. The following configuration creates a `fooService` bean that has profiling and transactional aspects applied to it in the desired order: diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc index cddd2e2924..477d4b0e9e 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc @@ -10,12 +10,12 @@ and then link (weave) your application with the manager. You can use the Spring Framework's IoC container to take care of dependency-injecting the aspect. The simplest way to configure the transaction management aspect is to use the `` element and specify the `mode` -attribute to `aspectj` as described in <>. Because +attribute to `aspectj` as described in xref:data-access/transaction/declarative/annotations.adoc[Using `@Transactional`]. Because we focus here on applications that run outside of a Spring container, we show you how to do it programmatically. -NOTE: Prior to continuing, you may want to read <> and -<> respectively. +NOTE: Prior to continuing, you may want to read xref:data-access/transaction/declarative/annotations.adoc[Using `@Transactional`] and +xref:core/aop.adoc[AOP] respectively. The following example shows how to create a transaction manager and configure the `AnnotationTransactionAspect` to use it: @@ -53,8 +53,8 @@ regardless of visibility. To weave your applications with the `AnnotationTransactionAspect`, you must either build your application with AspectJ (see the https://www.eclipse.org/aspectj/doc/released/devguide/index.html[AspectJ Development -Guide]) or use load-time weaving. See <> for a discussion of load-time weaving with AspectJ. +Guide]) or use load-time weaving. See xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time weaving with AspectJ in the Spring Framework] + for a discussion of load-time weaving with AspectJ. diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc index 167e109daf..5bbe41208f 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc @@ -187,7 +187,7 @@ advisor. The result indicates that, at the execution of a `fooServiceOperation`, the advice defined by `txAdvice` is run. The expression defined within the `` element is an AspectJ pointcut -expression. See <> for more details on pointcut +expression. See xref:core/aop.adoc[the AOP section] for more details on pointcut expressions in Spring. A common requirement is to make an entire service layer transactional. The best way to @@ -203,7 +203,7 @@ service layer. The following example shows how to do so: ---- NOTE: In the preceding example, it is assumed that all your service interfaces are defined -in the `x.y.service` package. See <> for more details. +in the `x.y.service` package. See xref:core/aop.adoc[the AOP section] for more details. Now that we have analyzed the configuration, you may be asking yourself, "What does all this configuration actually do?" diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc index 4391a8ef4a..1145aabb86 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc @@ -6,7 +6,7 @@ classes, typically service layer classes, declaratively in your application. Thi describes how you can control the rollback of transactions in a simple, declarative fashion in XML configuration. For details on controlling rollback semantics declaratively with the `@Transactional` annotation, see -<>. +xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-attransactional-settings[`@Transactional` Settings]. The recommended way to indicate to the Spring Framework's transaction infrastructure that a transaction's work is to be rolled back is to throw an `Exception` from code that @@ -51,7 +51,7 @@ thrown, and the rules are based on exception types or exception patterns. Rollback rules may be configured in XML via the `rollback-for` and `no-rollback-for` attributes, which allow rules to be defined as patterns. When using -<>, rollback rules may +xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-attransactional-settings[`@Transactional`], rollback rules may be configured via the `rollbackFor`/`noRollbackFor` and `rollbackForClassName`/`noRollbackForClassName` attributes, which allow rules to be defined based on exception types or patterns, respectively. diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc index e3372fc1ed..f59bb26b00 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc @@ -9,13 +9,13 @@ infrastructure in the context of transaction-related issues. The most important concepts to grasp with regard to the Spring Framework's declarative transaction support are that this support is enabled -<> and that the transactional +xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[via AOP proxies] and that the transactional advice is driven by metadata (currently XML- or annotation-based). The combination of AOP with transactional metadata yields an AOP proxy that uses a `TransactionInterceptor` in conjunction with an appropriate `TransactionManager` implementation to drive transactions around method invocations. -NOTE: Spring AOP is covered in <>. +NOTE: Spring AOP is covered in xref:core/aop.adoc[the AOP section]. Spring Framework's `TransactionInterceptor` provides transaction management for imperative and reactive programming models. The interceptor detects the desired flavor of diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc index cac80d805b..566f44d1f6 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc @@ -4,7 +4,7 @@ This section summarizes the various transactional settings that you can specify by using the `` tag. The default `` settings are: -* The <> is `REQUIRED.` +* The xref:data-access/transaction/declarative/tx-propagation.adoc[propagation setting] is `REQUIRED.` * The isolation level is `DEFAULT.` * The transaction is read-write. * The transaction timeout defaults to the default timeout of the underlying transaction diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc index 60a51310fa..4b211aff98 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc @@ -139,7 +139,7 @@ Code within the callback can roll the transaction back by calling the You can specify transaction settings (such as the propagation mode, the isolation level, the timeout, and so forth) on the `TransactionTemplate` either programmatically or in configuration. By default, `TransactionTemplate` instances have the -<>. The +xref:data-access/transaction/declarative/txadvice-settings.adoc[default transactional settings]. The following example shows the programmatic customization of the transactional settings for a specific `TransactionTemplate:` @@ -302,7 +302,7 @@ the full output must be consumed to allow the transaction to complete. You can specify transaction settings (such as the propagation mode, the isolation level, the timeout, and so forth) for the `TransactionalOperator`. By default, `TransactionalOperator` instances have -<>. The +xref:data-access/transaction/declarative/txadvice-settings.adoc[default transactional settings]. The following example shows customization of the transactional settings for a specific `TransactionalOperator:` diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc index 562a516244..2c5ecd6e66 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc @@ -12,7 +12,7 @@ transactional technologies and requirements. Used properly, the Spring Framework provides a straightforward and portable abstraction. If you use global transactions, you must use the `org.springframework.transaction.jta.JtaTransactionManager` class (or an -<> of +xref:data-access/transaction/application-server-integration.adoc[application server-specific subclass] of it) for all your transactional operations. Otherwise, the transaction infrastructure tries to perform local transactions on such resources as container `DataSource` instances. Such local transactions do not make sense, and a good application server diff --git a/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc b/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc index 7b3c8f9368..52a2ddb264 100644 --- a/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc +++ b/framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc @@ -22,7 +22,7 @@ transaction management. The following listing shows the definition of the ---- This is primarily a service provider interface (SPI), although you can use it -<> from your application code. Because +xref:data-access/transaction/programmatic.adoc#transaction-programmatic-ptm[programmatically] from your application code. Because `PlatformTransactionManager` is an interface, it can be easily mocked or stubbed as necessary. It is not tied to a lookup strategy, such as JNDI. `PlatformTransactionManager` implementations are defined like any other object (or bean) @@ -63,7 +63,7 @@ listing shows the transaction strategy defined by ---- The reactive transaction manager is primarily a service provider interface (SPI), -although you can use it <> from your +although you can use it xref:data-access/transaction/programmatic.adoc#transaction-programmatic-rtm[programmatically] from your application code. Because `ReactiveTransactionManager` is an interface, it can be easily mocked or stubbed as necessary. @@ -75,7 +75,7 @@ The `TransactionDefinition` interface specifies: example, code can continue running in the existing transaction (the common case), or the existing transaction can be suspended and a new transaction created. Spring offers all of the transaction propagation options familiar from EJB CMT. To read - about the semantics of transaction propagation in Spring, see <>. + about the semantics of transaction propagation in Spring, see xref:data-access/transaction/declarative/tx-propagation.adoc[Transaction Propagation]. * Isolation: The degree to which this transaction is isolated from the work of other transactions. For example, can this transaction see uncommitted writes from other transactions? @@ -179,7 +179,7 @@ infrastructure. NOTE: The preceding definition of the `dataSource` bean uses the `` tag from the `jee` namespace. For more information see -<>. +xref:integration/appendix.adoc#integration.appendix.xsd-schemas-jee[The JEE Schema]. NOTE: If you use JTA, your transaction manager definition should look the same, regardless of what data access technology you use, be it JDBC, Hibernate JPA, or any other supported diff --git a/framework-docs/modules/ROOT/pages/index.adoc b/framework-docs/modules/ROOT/pages/index.adoc index c62a2b2899..b6897ab176 100644 --- a/framework-docs/modules/ROOT/pages/index.adoc +++ b/framework-docs/modules/ROOT/pages/index.adoc @@ -3,22 +3,22 @@ = Spring Framework Documentation [horizontal] -<> :: History, Design Philosophy, Feedback, +xref:web/websocket/stomp/overview.adoc[Overview] :: History, Design Philosophy, Feedback, Getting Started. -<> :: IoC Container, Events, Resources, i18n, +xref:core.adoc[Core] :: IoC Container, Events, Resources, i18n, Validation, Data Binding, Type Conversion, SpEL, AOP, AOT. <> :: Mock Objects, TestContext Framework, Spring MVC Test, WebTestClient. -<> :: Transactions, DAO Support, +xref:data-access.adoc[Data Access] :: Transactions, DAO Support, JDBC, R2DBC, O/R Mapping, XML Marshalling. -<> :: Spring MVC, WebSocket, SockJS, +xref:web.adoc[Web Servlet] :: Spring MVC, WebSocket, SockJS, STOMP Messaging. -<> :: Spring WebFlux, WebClient, +xref:testing/unit.adoc#mock-objects-web-reactive[Web Reactive] :: Spring WebFlux, WebClient, WebSocket, RSocket. -<> :: REST Clients, JMS, JCA, JMX, +xref:integration.adoc[Integration] :: REST Clients, JMS, JCA, JMX, Email, Tasks, Scheduling, Caching, Observability. -<> :: Kotlin, Groovy, Dynamic Languages. -<> :: Spring properties. +xref:languages.adoc[Languages] :: Kotlin, Groovy, Dynamic Languages. +xref:testing/appendix.adoc[Appendix] :: Spring properties. https://github.com/spring-projects/spring-framework/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information. diff --git a/framework-docs/modules/ROOT/pages/integration/appendix.adoc b/framework-docs/modules/ROOT/pages/integration/appendix.adoc index e714522b61..b07294bdba 100644 --- a/framework-docs/modules/ROOT/pages/integration/appendix.adoc +++ b/framework-docs/modules/ROOT/pages/integration/appendix.adoc @@ -272,9 +272,9 @@ with `jee`: === The `jms` Schema The `jms` elements deal with configuring JMS-related beans, such as Spring's -<>. These elements are detailed in the -section of the <> entitled <>. See that chapter for full details on this support +xref:integration/jms/using.adoc#jms-mdp[Message Listener Containers]. These elements are detailed in the +section of the xref:integration/jms.adoc[JMS chapter] entitled xref:integration/jms/namespace.adoc[JMS Namespace Support] +. See that chapter for full details on this support and the `jms` elements themselves. In the interest of completeness, to use the elements in the `jms` schema, you need to have @@ -305,7 +305,7 @@ are available to you: === Using `` This element is detailed in -<>. +xref:integration/jmx/naming.adoc#jmx-context-mbeanexport[Configuring Annotation-based MBean Export]. @@ -314,8 +314,8 @@ This element is detailed in You can use the `cache` elements to enable support for Spring's `@CacheEvict`, `@CachePut`, and `@Caching` annotations. It it also supports declarative XML-based caching. See -<> and -<> for details. +xref:integration/cache/annotations.adoc#cache-annotation-enable[Enabling Caching Annotations] and +xref:integration/cache/declarative-xml.adoc[Declarative XML-based Caching] for details. To use the elements in the `cache` schema, you need to have the following preamble at the top of your Spring XML configuration file. The text in the following snippet references diff --git a/framework-docs/modules/ROOT/pages/integration/cache.adoc b/framework-docs/modules/ROOT/pages/integration/cache.adoc index 9042bfdc8b..689a031b22 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache.adoc @@ -2,12 +2,12 @@ = Cache Abstraction Since version 3.1, the Spring Framework provides support for transparently adding caching to -an existing Spring application. Similar to the <> +an existing Spring application. Similar to the xref:data-access/transaction.adoc[transaction] support, the caching abstraction allows consistent use of various caching solutions with minimal impact on the code. In Spring Framework 4.1, the cache abstraction was significantly extended with support -for <> and more customization options. +for xref:integration/cache/jsr-107.adoc[JSR-107 annotations] and more customization options. diff --git a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc index a602e14f03..f4114765cb 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc @@ -94,16 +94,16 @@ they are no use for the cache. Furthermore, what if only one of the two is impor while the other is not? For such cases, the `@Cacheable` annotation lets you specify how the key is generated -through its `key` attribute. You can use <> to pick the +through its `key` attribute. You can use xref:core/expressions.adoc[SpEL] to pick the arguments of interest (or their nested properties), perform operations, or even invoke arbitrary methods without having to write any code or implement any interface. This is the recommended approach over the -<>, since methods tend to be +xref:integration/cache/annotations.adoc#cache-annotations-cacheable-default-key[default generator], since methods tend to be quite different in signatures as the code base grows. While the default strategy might work for some methods, it rarely works for all methods. The following examples use various SpEL declarations (if you are not familiar with SpEL, -do yourself a favor and read <>): +do yourself a favor and read xref:core/expressions.adoc[Spring Expression Language]): [source,java,indent=0,subs="verbatim,quotes"] ---- @@ -162,7 +162,7 @@ For applications that work with several cache managers, you can set the You can also replace the `CacheResolver` entirely in a fashion similar to that of -replacing <>. The resolution is +replacing xref:integration/cache/annotations.adoc#cache-annotations-cacheable-key[key generation]. The resolution is requested for every cache operation, letting the implementation actually resolve the caches to use based on runtime arguments. The following example shows how to specify a `CacheResolver`: @@ -256,12 +256,12 @@ as follows: ---- Note that `#result` still refers to `Book` and not `Optional`. Since it might be -`null`, we use SpEL's <>. +`null`, we use SpEL's xref:core/expressions/language-ref/operator-safe-navigation.adoc[safe navigation operator]. [[cache-spel-context]] === Available Caching SpEL Evaluation Context -Each `SpEL` expression evaluates against a dedicated <>. +Each `SpEL` expression evaluates against a dedicated xref:core/expressions/language-ref.adoc[`context`]. In addition to the built-in parameters, the framework provides dedicated caching-related metadata, such as the argument names. The following table describes the items made available to the context so that you can use them for key and conditional computations: @@ -472,7 +472,7 @@ Alternatively, for XML configuration you can use the `cache:annotation-driven` e Both the `cache:annotation-driven` element and the `@EnableCaching` annotation let you specify various options that influence the way the caching behavior is added to the application through AOP. The configuration is intentionally similar with that of -<>. +xref:data-access/transaction/declarative/annotations.adoc#tx-annotation-driven-settings[`@Transactional`]. NOTE: The default advice mode for processing caching annotations is `proxy`, which allows for interception of calls through the proxy only. Local calls within the same class @@ -524,7 +524,7 @@ required to implement `CachingConfigurer`, see the affected classes with Spring's AspectJ caching aspect, modifying the target class byte code to apply to any kind of method call. AspectJ weaving requires `spring-aspects.jar` in the classpath as well as load-time weaving (or compile-time weaving) enabled. (See - <> for details on how to set up + xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration] for details on how to set up load-time weaving.) | `proxy-target-class` @@ -534,7 +534,7 @@ required to implement `CachingConfigurer`, see the classes annotated with the `@Cacheable` or `@CacheEvict` annotations. If the `proxy-target-class` attribute is set to `true`, class-based proxies are created. If `proxy-target-class` is `false` or if the attribute is omitted, standard JDK - interface-based proxies are created. (See <> + interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms] for a detailed examination of the different proxy types.) | `order` @@ -542,7 +542,7 @@ required to implement `CachingConfigurer`, see the | Ordered.LOWEST_PRECEDENCE | Defines the order of the cache advice that is applied to beans annotated with `@Cacheable` or `@CacheEvict`. (For more information about the rules related to - ordering AOP advice, see <>.) + ordering AOP advice, see xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice Ordering].) No specified ordering means that the AOP subsystem determines the order of the advice. |=== @@ -550,7 +550,7 @@ NOTE: `` looks for `@Cacheable/@CachePut/@CacheEvict/@ only on beans in the same application context in which it is defined. This means that, if you put `` in a `WebApplicationContext` for a `DispatcherServlet`, it checks for beans only in your controllers, not your services. -See <> for more information. +See xref:web/webmvc/mvc-servlet.adoc[the MVC section] for more information. .Method visibility and cache annotations **** @@ -595,9 +595,9 @@ triggers cache population or eviction. This is quite handy as a template mechani as it eliminates the need to duplicate cache annotation declarations, which is especially useful if the key or condition are specified or if the foreign imports (`org.springframework`) are not allowed in your code base. Similarly to the rest -of the <> annotations, you can +of the xref:core/beans/classpath-scanning.adoc#beans-stereotype-annotations[stereotype] annotations, you can use `@Cacheable`, `@CachePut`, `@CacheEvict`, and `@CacheConfig` as -<> (that is, annotations that +xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotations] (that is, annotations that can annotate other annotations). In the following example, we replace a common `@Cacheable` declaration with our own custom annotation: @@ -630,7 +630,7 @@ preceding code: Even though `@SlowService` is not a Spring annotation, the container automatically picks up its declaration at runtime and understands its meaning. Note that, as mentioned -<>, annotation-driven behavior needs to be enabled. +xref:integration/cache/annotations.adoc#cache-annotation-enable[earlier], annotation-driven behavior needs to be enabled. diff --git a/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc b/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc index b62a6a5e5d..7b28afd746 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc @@ -5,7 +5,7 @@ If annotations are not an option (perhaps due to having no access to the sources or no external code), you can use XML for declarative caching. So, instead of annotating the methods for caching, you can specify the target method and the caching directives externally (similar to the declarative transaction management -<>). The example +xref:data-access/transaction/declarative/first-example.adoc[advice]). The example from the previous section can be translated into the following example: [source,xml,indent=0] @@ -37,7 +37,7 @@ data. Both definitions work against the `books` cache. The `aop:config` definition applies the cache advice to the appropriate points in the program by using the AspectJ pointcut expression (more information is available in -<>). In the preceding example, +xref:core/aop.adoc[Aspect Oriented Programming with Spring]). In the preceding example, all methods from the `BookService` are considered and the cache advice is applied to them. The declarative XML caching supports all of the annotation-based model, so moving between diff --git a/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc b/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc index 20f2735545..1bf0649409 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc @@ -74,8 +74,8 @@ bean lifecycle callbacks, such as dependency injection. Keys are generated by a `javax.cache.annotation.CacheKeyGenerator` that serves the same purpose as Spring's `KeyGenerator`. By default, all method arguments are taken into account, unless at least one parameter is annotated with `@CacheKey`. This is -similar to Spring's <>. For instance, the following are identical operations, one using +similar to Spring's xref:integration/cache/annotations.adoc#cache-annotations-cacheable-key[custom key generation declaration] +. For instance, the following are identical operations, one using Spring's abstraction and the other using JCache: [source,java,indent=0,subs="verbatim,quotes"] diff --git a/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc b/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc index 1bda81c330..c8009ce251 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc @@ -40,7 +40,7 @@ or eviction contracts. == Ehcache-based Cache Ehcache 3.x is fully JSR-107 compliant and no dedicated support is required for it. See -<> for details. +xref:integration/cache/store-configuration.adoc#cache-store-configuration-jsr107[JSR-107 Cache] for details. [[cache-store-configuration-caffeine]] diff --git a/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc b/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc index 826a4e9c8a..4235f06174 100644 --- a/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc +++ b/framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc @@ -45,10 +45,10 @@ that is, the abstraction frees you from having to write the caching logic but do provide the actual data store. This abstraction is materialized by the `org.springframework.cache.Cache` and `org.springframework.cache.CacheManager` interfaces. -Spring provides <> of that abstraction: +Spring provides xref:integration/cache/store-configuration.adoc[a few implementations] of that abstraction: JDK `java.util.concurrent.ConcurrentMap` based caches, Gemfire cache, https://github.com/ben-manes/caffeine/wiki[Caffeine], and JSR-107 compliant caches (such -as Ehcache 3.x). See <> for more information on plugging in other cache +as Ehcache 3.x). See xref:integration/cache/plug.adoc[Plugging-in Different Back-end Caches] for more information on plugging in other cache stores and providers. IMPORTANT: The caching abstraction has no special handling for multi-threaded and diff --git a/framework-docs/modules/ROOT/pages/integration/email.adoc b/framework-docs/modules/ROOT/pages/integration/email.adoc index fd82a39feb..610fda7c87 100644 --- a/framework-docs/modules/ROOT/pages/integration/email.adoc +++ b/framework-docs/modules/ROOT/pages/integration/email.adoc @@ -181,7 +181,7 @@ callback interface. In the following example, the `mailSender` property is of ty ---- NOTE: The mail code is a crosscutting concern and could well be a candidate for -refactoring into a <>, which could then +refactoring into a xref:core/aop.adoc[custom Spring AOP aspect], which could then be run at appropriate joinpoints on the `OrderManager` target. The Spring Framework's mail support ships with the standard JavaMail implementation. diff --git a/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc b/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc index e42387063a..edda9de3d3 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc @@ -18,7 +18,7 @@ bean as a JMS listener endpoint. The following example shows how to use it: The idea of the preceding example is that, whenever a message is available on the `jakarta.jms.Destination` `myDestination`, the `processOrder` method is invoked accordingly (in this case, with the content of the JMS message, similar to -what the <> +what the xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[`MessageListenerAdapter`] provides). The annotated endpoint infrastructure creates a message listener container @@ -67,7 +67,7 @@ container factory. See the javadoc of classes that implement {api-spring-framework}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`] for details and examples. -If you prefer <>, you can use the `` +If you prefer xref:integration/jms/namespace.adoc[XML configuration], you can use the `` element, as the following example shows: [source,xml,indent=0,subs="verbatim,quotes"] @@ -197,7 +197,7 @@ annotate the payload with `@Valid` and configure the necessary validator, as the [[jms-annotated-response]] == Response Management -The existing support in <> +The existing support in xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[`MessageListenerAdapter`] already lets your method have a non-`void` return type. When that is the case, the result of the invocation is encapsulated in a `jakarta.jms.Message`, sent either in the destination specified in the `JMSReplyTo` header of the original message or in the default destination configured on diff --git a/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc b/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc index b6e2f580e0..be6cb7b45c 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc @@ -24,8 +24,8 @@ namespace elements, you need to reference the JMS schema, as the following examp The namespace consists of three top-level elements: ``, `` -and ``. `` enables the use of <>. `` and `` +and ``. `` enables the use of xref:integration/jms/annotated.adoc[annotation-driven listener endpoints] +. `` and `` define shared listener container configuration and can contain `` child elements. The following example shows a basic configuration for two listeners: @@ -42,7 +42,7 @@ The following example shows a basic configuration for two listeners: The preceding example is equivalent to creating two distinct listener container bean definitions and two distinct `MessageListenerAdapter` bean definitions, as shown -in <>. In addition to the attributes shown +in xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[Using `MessageListenerAdapter`]. In addition to the attributes shown in the preceding example, the `listener` element can contain several optional ones. The following table describes all of the available attributes: diff --git a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc index 72658c5464..ff47edf512 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc @@ -21,11 +21,11 @@ the receiver should wait before giving up waiting for a message. NOTE: Spring also supports annotated-listener endpoints through the use of the `@JmsListener` annotation and provides an open infrastructure to register endpoints programmatically. This is, by far, the most convenient way to setup an asynchronous receiver. -See <> for more details. +See xref:integration/jms/annotated.adoc#jms-annotated-support[Enable Listener Endpoint Annotations] for more details. In a fashion similar to a Message-Driven Bean (MDB) in the EJB world, the Message-Driven POJO (MDP) acts as a receiver for JMS messages. The one restriction (but see -<>) on an MDP is that it must implement +xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[Using `MessageListenerAdapter`]) on an MDP is that it must implement the `jakarta.jms.MessageListener` interface. Note that, if your POJO receives messages on multiple threads, it is important to ensure that your implementation is thread-safe. diff --git a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc index 53883f7fa3..db342992e0 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc @@ -167,9 +167,9 @@ operations that do not refer to a specific destination. One of the most common uses of JMS messages in the EJB world is to drive message-driven beans (MDBs). Spring offers a solution to create message-driven POJOs (MDPs) in a way -that does not tie a user to an EJB container. (See <> for detailed +that does not tie a user to an EJB container. (See xref:integration/jms/receiving.adoc#jms-receiving-async[Asynchronous reception: Message-Driven POJOs] for detailed coverage of Spring's MDP support.) Since Spring Framework 4.1, endpoint methods can be -annotated with `@JmsListener` -- see <> for more details. +annotated with `@JmsListener` -- see xref:integration/jms/annotated.adoc[Annotation-driven Listener Endpoints] for more details. A message listener container is used to receive messages from a JMS message queue and drive the `MessageListener` that is injected into it. The listener container is @@ -184,8 +184,8 @@ boilerplate JMS infrastructure concerns to the framework. There are two standard JMS message listener containers packaged with Spring, each with its specialized feature set. -* <> -* <> +* xref:integration/jms/using.adoc#jms-mdp-simple[`SimpleMessageListenerContainer`] +* xref:integration/jms/using.adoc#jms-mdp-default[`DefaultMessageListenerContainer`] [[jms-mdp-simple]] === Using `SimpleMessageListenerContainer` @@ -236,7 +236,7 @@ a simple `BackOff` implementation retries every five seconds. You can specify a custom `BackOff` implementation for more fine-grained recovery options. See {api-spring-framework}/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example. -NOTE: Like its sibling (<>), +NOTE: Like its sibling (xref:integration/jms/using.adoc#jms-mdp-simple[`SimpleMessageListenerContainer`]), `DefaultMessageListenerContainer` supports native JMS transactions and allows for customizing the acknowledgment mode. If feasible for your scenario, This is strongly recommended over externally managed transactions -- that is, if you can live with @@ -263,7 +263,7 @@ reliability needs (for example, for reliable queue handling and durable topic su Spring provides a `JmsTransactionManager` that manages transactions for a single JMS `ConnectionFactory`. This lets JMS applications leverage the managed-transaction features of Spring, as described in -<>. +xref:data-access/transaction.adoc[Transaction Management section of the Data Access chapter]. The `JmsTransactionManager` performs local resource transactions, binding a JMS Connection/Session pair from the specified `ConnectionFactory` to the thread. `JmsTemplate` automatically detects such transactional resources and operates diff --git a/framework-docs/modules/ROOT/pages/integration/jmx.adoc b/framework-docs/modules/ROOT/pages/integration/jmx.adoc index 10a8c063d8..40e2bcd009 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx.adoc @@ -7,7 +7,7 @@ easily and transparently integrate your Spring application into a JMX infrastruc .JMX? **** This chapter is not an introduction to JMX. It does not try to explain why you might want -to use JMX. If you are new to JMX, see <> at the end of this chapter. +to use JMX. If you are new to JMX, see xref:integration/jmx/resources.adoc[Further Resources] at the end of this chapter. **** Specifically, Spring's JMX support provides four core features: diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc index fb452d849f..fdc637ad2e 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx/exporting.adoc @@ -67,15 +67,15 @@ The pertinent bean definition from the preceding configuration snippet is the `e bean. The `beans` property tells the `MBeanExporter` exactly which of your beans must be exported to the JMX `MBeanServer`. In the default configuration, the key of each entry in the `beans` `Map` is used as the `ObjectName` for the bean referenced by the -corresponding entry value. You can change this behavior, as described in <>. +corresponding entry value. You can change this behavior, as described in xref:integration/jmx/naming.adoc[Controlling `ObjectName` Instances for Your Beans]. With this configuration, the `testBean` bean is exposed as an MBean under the `ObjectName` `bean:name=testBean1`. By default, all `public` properties of the bean are exposed as attributes and all `public` methods (except those inherited from the `Object` class) are exposed as operations. -NOTE: `MBeanExporter` is a `Lifecycle` bean (see <>). By default, MBeans are exported as late as possible during +NOTE: `MBeanExporter` is a `Lifecycle` bean (see xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-processor[Startup and Shutdown Callbacks] +). By default, MBeans are exported as late as possible during the application lifecycle. You can configure the `phase` at which the export happens or disable automatic registration by setting the `autoStartup` flag. @@ -83,7 +83,7 @@ the export happens or disable automatic registration by setting the `autoStartup [[jmx-exporting-mbeanserver]] == Creating an MBeanServer -The configuration shown in the <> assumes that the +The configuration shown in the xref:integration/jmx/exporting.adoc[preceding section] assumes that the application is running in an environment that has one (and only one) `MBeanServer` already running. In this case, Spring tries to locate the running `MBeanServer` and register your beans with that server (if any). This behavior is useful when your @@ -159,7 +159,7 @@ be used, as the following example shows: For platforms or cases where the existing `MBeanServer` has a dynamic (or unknown) `agentId` that is retrieved through lookup methods, you should use -<>, +xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[factory-method], as the following example shows: [source,xml,indent=0,subs="verbatim,quotes"] @@ -208,7 +208,7 @@ property to `true`, as the following example shows: In the preceding example, the bean called `spring:mbean=true` is already a valid JMX MBean and is automatically registered by Spring. By default, a bean that is autodetected for JMX registration has its bean name used as the `ObjectName`. You can override this behavior, -as detailed in <>. +as detailed in xref:integration/jmx/naming.adoc[Controlling `ObjectName` Instances for Your Beans]. [[jmx-exporting-registration-behavior]] diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc index 98598aefef..f9458765aa 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx/interface.adoc @@ -1,7 +1,7 @@ [[jmx-interface]] = Controlling the Management Interface of Your Beans -In the example in the <>, +In the example in the xref:integration/jmx/exporting.adoc#jmx-exporting-registration-behavior[preceding section], you had little control over the management interface of your bean. All of the `public` properties and methods of each exported bean were exposed as JMX attributes and operations, respectively. To exercise finer-grained control over exactly which @@ -47,7 +47,7 @@ NOTE: A `ManagedResource`-annotated bean must be public, as must the methods exp an operation or an attribute. The following example shows the annotated version of the `JmxTestBean` class that we -used in <>: +used in xref:integration/jmx/exporting.adoc#jmx-exporting-mbeanserver[Creating an MBeanServer]: [source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] ---- @@ -113,7 +113,7 @@ In the preceding example, you can see that the `JmxTestBean` class is marked wit `ManagedResource` annotation and that this `ManagedResource` annotation is configured with a set of properties. These properties can be used to configure various aspects of the MBean that is generated by the `MBeanExporter` and are explained in greater -detail later in <>. +detail later in xref:integration/jmx/interface.adoc#jmx-interface-metadata-types[Source-level Metadata Types]. Both the `age` and `name` properties are annotated with the `ManagedAttribute` annotation, but, in the case of the `age` property, only the getter is marked. @@ -293,7 +293,7 @@ However, the `JmxTestBean` is still registered, since it is marked with the `Man attribute and the `MetadataMBeanInfoAssembler` detects this and votes to include it. The only problem with this approach is that the name of the `JmxTestBean` now has business meaning. You can address this issue by changing the default behavior for `ObjectName` -creation as defined in <>. +creation as defined in xref:integration/jmx/naming.adoc[Controlling `ObjectName` Instances for Your Beans]. [[jmx-interface-java]] diff --git a/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc b/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc index 0a0d423d35..39b9582819 100644 --- a/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jmx/naming.adoc @@ -116,7 +116,7 @@ example, the generated `ObjectName` for the following bean would be [[jmx-context-mbeanexport]] == Configuring Annotation-based MBean Export -If you prefer to use <> to define +If you prefer to use xref:integration/jmx/interface.adoc#jmx-interface-metadata[the annotation-based approach] to define your management interfaces, a convenience subclass of `MBeanExporter` is available: `AnnotationMBeanExporter`. When defining an instance of this subclass, you no longer need the `namingStrategy`, `assembler`, and `attributeSource` configuration, @@ -146,7 +146,7 @@ If necessary, you can provide a reference to a particular MBean `server`, and th `defaultDomain` attribute (a property of `AnnotationMBeanExporter`) accepts an alternate value for the generated MBean `ObjectName` domains. This is used in place of the fully qualified package name as described in the previous section on -<>, as the following example shows: +xref:integration/jmx/naming.adoc#jmx-naming-metadata[MetadataNamingStrategy], as the following example shows: [source,java,indent=0,subs="verbatim,quotes"] ---- diff --git a/framework-docs/modules/ROOT/pages/integration/observability.adoc b/framework-docs/modules/ROOT/pages/integration/observability.adoc index 735d6aeb3b..b7453decaa 100644 --- a/framework-docs/modules/ROOT/pages/integration/observability.adoc +++ b/framework-docs/modules/ROOT/pages/integration/observability.adoc @@ -14,17 +14,17 @@ You can learn more about {docs-spring-boot}/html/actuator.html#actuator.metrics[ == List of produced Observations Spring Framework instruments various features for observability. -As outlined <>, observations can generate timer Metrics and/or Traces depending on the configuration. +As outlined xref:integration/observability.adoc[at the beginning of this section], observations can generate timer Metrics and/or Traces depending on the configuration. .Observations produced by Spring Framework [%autowidth] |=== |Observation name |Description -|<> +|xref:integration/observability.adoc#integration.observability.http-client[`"http.client.requests"`] |Time spent for HTTP client exchanges -|<> +|xref:integration/observability.adoc#integration.observability.http-server[`"http.server.requests"`] |Processing time for HTTP server exchanges at the Framework level |=== @@ -92,7 +92,7 @@ Applications need to configure the `org.springframework.web.filter.ServerHttpObs It is using the `org.springframework.http.server.observation.DefaultServerRequestObservationConvention` by default, backed by the `ServerRequestObservationContext`. This will only record an observation as an error if the `Exception` has not been handled by the web Framework and has bubbled up to the Servlet filter. -Typically, all exceptions handled by Spring MVC's `@ExceptionHandler` and <> will not be recorded with the observation. +Typically, all exceptions handled by Spring MVC's `@ExceptionHandler` and xref:web/webmvc/mvc-ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: include::code:UserController[] @@ -125,7 +125,7 @@ Applications need to configure the `org.springframework.web.filter.reactive.Serv It is using the `org.springframework.http.server.reactive.observation.DefaultServerRequestObservationConvention` by default, backed by the `ServerRequestObservationContext`. This will only record an observation as an error if the `Exception` has not been handled by the web Framework and has bubbled up to the `WebFilter`. -Typically, all exceptions handled by Spring WebFlux's `@ExceptionHandler` and <> will not be recorded with the observation. +Typically, all exceptions handled by Spring WebFlux's `@ExceptionHandler` and xref:web/webflux/ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: include::code:UserController[] diff --git a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc index 8a47198d4b..b34aa4c85d 100644 --- a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc +++ b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc @@ -3,9 +3,9 @@ The Spring Framework provides the following choices for making calls to REST endpoints: -* <> - non-blocking, reactive client w fluent API. -* <> - synchronous client with template method API. -* <> - annotated interface with generated, dynamic proxy implementation. +* xref:integration/rest-clients.adoc#rest-webclient[`WebClient`] - non-blocking, reactive client w fluent API. +* xref:integration/rest-clients.adoc#rest-resttemplate[`RestTemplate`] - synchronous client with template method API. +* xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] - annotated interface with generated, dynamic proxy implementation. [[rest-webclient]] @@ -24,7 +24,7 @@ synchronous, asynchronous, and streaming scenarios. * Synchronous and asynchronous interactions. * Streaming up to or streaming down from a server. -See <> for more details. +See xref:web/webflux-webclient.adoc[WebClient] for more details. @@ -38,7 +38,7 @@ overloaded methods: NOTE: `RestTemplate` is in maintenance mode, with only requests for minor changes and bugs to be accepted. Please, consider using the -<> instead. +xref:web/webflux-webclient.adoc[WebClient] instead. [[rest-overview-of-resttemplate-methods-tbl]] .RestTemplate methods @@ -118,7 +118,7 @@ accessing the status of a response that represents an error (such as 401). If th issue, switch to another HTTP client library. NOTE: `RestTemplate` can be instrumented for observability, in order to produce metrics and traces. -See the <> section. +See the xref:integration/observability.adoc#integration.observability.http-client.resttemplate[RestTemplate Observability support] section. [[rest-resttemplate-uri]] ==== URIs @@ -157,7 +157,7 @@ You can use the `uriTemplateHandler` property of `RestTemplate` to customize how are encoded. Alternatively, you can prepare a `java.net.URI` and pass it into one of the `RestTemplate` methods that accepts a `URI`. -For more details on working with and encoding URIs, see <>. +For more details on working with and encoding URIs, see xref:web/webmvc/mvc-uri-building.adoc[URI Links]. [[rest-template-headers]] ==== Headers @@ -212,13 +212,13 @@ then helps to populate the `Accept` header. If necessary, you can use the `excha methods to provide the `Accept` header explicitly. By default, `RestTemplate` registers all built-in -<>, depending on classpath checks that help +xref:integration/rest-clients.adoc#rest-message-conversion[message converters], depending on classpath checks that help to determine what optional conversion libraries are present. You can also set the message converters to use explicitly. [[rest-message-conversion]] ==== Message Conversion -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs[See equivalent in the Reactive stack]# The `spring-web` module contains the `HttpMessageConverter` contract for reading and writing the body of HTTP requests and responses through `InputStream` and `OutputStream`. @@ -228,7 +228,7 @@ on the server side (for example, in Spring MVC REST controllers). Concrete implementations for the main media (MIME) types are provided in the framework and are, by default, registered with the `RestTemplate` on the client side and with `RequestMappingHandlerAdapter` on the server side (see -<>). +xref:web/webmvc/mvc-config/message-converters.adoc[Configuring Message Converters]). The implementations of `HttpMessageConverter` are described in the following sections. For all converters, a default media type is used, but you can override it by setting the diff --git a/framework-docs/modules/ROOT/pages/integration/scheduling.adoc b/framework-docs/modules/ROOT/pages/integration/scheduling.adoc index 6f60f4aef0..eae7ff2e70 100644 --- a/framework-docs/modules/ROOT/pages/integration/scheduling.adoc +++ b/framework-docs/modules/ROOT/pages/integration/scheduling.adoc @@ -209,7 +209,7 @@ default). The following listing shows the available methods for `Trigger` implem Spring provides two implementations of the `Trigger` interface. The most interesting one is the `CronTrigger`. It enables the scheduling of tasks based on -<>. +xref:integration/scheduling.adoc#scheduling-cron-expression[cron expressions]. For example, the following task is scheduled to run 15 minutes past each hour but only during the 9-to-5 "business hours" on weekdays: @@ -361,7 +361,7 @@ amount of time to wait before the first execution of the method, as the followin ---- If simple periodic scheduling is not expressive enough, you can provide a -<>. +xref:integration/scheduling.adoc#scheduling-cron-expression[cron expression]. The following example runs only on weekdays: [source,java,indent=0] @@ -485,7 +485,7 @@ in combination with a custom pointcut. === Executor Qualification with `@Async` By default, when specifying `@Async` on a method, the executor that is used is the -one <>, +one xref:integration/scheduling.adoc#scheduling-enable-annotation-support[configured when enabling async support], i.e. the "`annotation-driven`" element if you are using XML or your `AsyncConfigurer` implementation, if any. However, you can use the `value` attribute of the `@Async` annotation when you need to indicate that an executor other than the default should be @@ -565,7 +565,7 @@ The following creates a `ThreadPoolTaskExecutor` instance: ---- -As with the scheduler shown in the <>, +As with the scheduler shown in the xref:integration/scheduling.adoc#scheduling-task-namespace-scheduler[previous section], the value provided for the `id` attribute is used as the prefix for thread names within the pool. As far as the pool size is concerned, the `executor` element supports more configuration options than the `scheduler` element. For one thing, the thread pool for @@ -676,7 +676,7 @@ milliseconds to wait after each task execution has completed. Another option is any previous execution takes. Additionally, for both `fixed-delay` and `fixed-rate` tasks, you can specify an 'initial-delay' parameter, indicating the number of milliseconds to wait before the first execution of the method. For more control, you can instead provide a `cron` attribute -to provide a <>. +to provide a xref:integration/scheduling.adoc#scheduling-cron-expression[cron expression]. The following example shows these other options: [source,xml,indent=0] @@ -697,8 +697,8 @@ The following example shows these other options: == Cron Expressions All Spring cron expressions have to conform to the same format, whether you are using them in -<>, -<>, +xref:integration/scheduling.adoc#scheduling-annotation-support-scheduled[`@Scheduled` annotations], +xref:integration/scheduling.adoc#scheduling-task-namespace-scheduled-tasks[`task:scheduled-tasks` elements], or someplace else. A well-formed cron expression, such as `* * * * * *`, consists of six space-separated time and date fields, each with its own range of valid values: diff --git a/framework-docs/modules/ROOT/pages/languages/dynamic.adoc b/framework-docs/modules/ROOT/pages/languages/dynamic.adoc index 60d20034ad..fed4d8574e 100644 --- a/framework-docs/modules/ROOT/pages/languages/dynamic.adoc +++ b/framework-docs/modules/ROOT/pages/languages/dynamic.adoc @@ -13,7 +13,7 @@ for integration with any JSR-223 capable language provider (as of Spring 4.2), e.g. JRuby. You can find fully working examples of where this dynamic language support can be -immediately useful in <>. +immediately useful in xref:languages/dynamic.adoc#dynamic-language-scenarios[Scenarios]. @@ -88,8 +88,8 @@ container. Using the dynamic-language-backed beans with a plain `BeanFactory` implementation is supported, but you have to manage the plumbing of the Spring internals to do so. -For more information on schema-based configuration, see <>. +For more information on schema-based configuration, see xref:languages/dynamic.adoc#xsd-schemas-lang[XML Schema-based Configuration] +. ==== Finally, the following example shows the bean definitions that effect the injection of the @@ -138,7 +138,7 @@ supported dynamic languages. Note that this chapter does not attempt to explain the syntax and idioms of the supported dynamic languages. For example, if you want to use Groovy to write certain of the classes in your application, we assume that you already know Groovy. If you need further details -about the dynamic languages themselves, see <> at the end of +about the dynamic languages themselves, see xref:languages/dynamic.adoc#dynamic-language-resources[Further Resources] at the end of this chapter. @@ -168,7 +168,7 @@ of your dynamic language source files. [[dynamic-language-beans-concepts-xml-language-element]] ==== The element -The final step in the list in the <> +The final step in the list in the xref:languages/dynamic.adoc#dynamic-language-beans-concepts[preceding section] involves defining dynamic-language-backed bean definitions, one for each bean that you want to configure (this is no different from normal JavaBean configuration). However, instead of specifying the fully qualified class name of the class that is to be @@ -212,7 +212,7 @@ NOTE: This feature is off by default. Now we can take a look at an example to see how easy it is to start using refreshable beans. To turn on the refreshable beans feature, you have to specify exactly one additional attribute on the `` element of your bean definition. So, -if we stick with <> from earlier in +if we stick with xref:languages/dynamic.adoc#dynamic-language-a-first-example[the example] from earlier in this chapter, the following example shows what we would change in the Spring XML configuration to effect refreshable beans: @@ -310,7 +310,7 @@ results in a fatal exception being propagated to the calling code. The refreshable bean behavior described earlier does not apply to dynamic language source files defined with the `` element notation (see -<>). Additionally, it applies only to beans where +xref:languages/dynamic.adoc#dynamic-language-beans-inline[Inline Dynamic Language Source Files]). Additionally, it applies only to beans where changes to the underlying source file can actually be detected (for example, by code that checks the last modified date of a dynamic language source file that exists on the file system). @@ -347,7 +347,7 @@ If we put to one side the issues surrounding whether it is good practice to defi dynamic language source inside a Spring configuration file, the `` element can be useful in some scenarios. For instance, we might want to quickly add a Spring `Validator` implementation to a Spring MVC `Controller`. This is but a moment's -work using inline source. (See <> for such an +work using inline source. (See xref:languages/dynamic.adoc#dynamic-language-scenarios-validators[Scripted Validators] for such an example.) @@ -416,7 +416,7 @@ features that people like so much in languages like Python, Ruby and Smalltalk, them available to Java developers using a Java-like syntax.`" If you have read this chapter straight from the top, you have already -<> of a Groovy-dynamic-language-backed +xref:languages/dynamic.adoc#dynamic-language-a-first-example[seen an example] of a Groovy-dynamic-language-backed bean. Now consider another example (again using an example from the Spring test suite): [source,java,indent=0,subs="verbatim,quotes",chomp="-packages"] @@ -475,7 +475,7 @@ Finally, the following small application exercises the preceding configuration: The resulting output from running the above program is (unsurprisingly) `10`. (For more interesting examples, see the dynamic language showcase project for a more -complex example or see the examples <> later in this chapter). +complex example or see the examples xref:languages/dynamic.adoc#dynamic-language-scenarios[Scenarios] later in this chapter). You must not define more than one class per Groovy source file. While this is perfectly legal in Groovy, it is (arguably) a bad practice. In the interests of a consistent @@ -633,7 +633,7 @@ The following example shows the Spring XML that defines an "`instance`" of the a ---- -See <> for some scenarios where you might want to use +See xref:languages/dynamic.adoc#dynamic-language-scenarios[Scenarios] for some scenarios where you might want to use BeanShell-based beans. @@ -670,7 +670,7 @@ automatically reflected in the beans that are backed by dynamic language source NOTE: To effect this automatic "`pickup`" of any changes to dynamic-language-backed beans, you have to enable the "`refreshable beans`" functionality. See -<> for a full treatment of this feature. +xref:languages/dynamic.adoc#dynamic-language-refreshable-beans[Refreshable Beans] for a full treatment of this feature. The following example shows an `org.springframework.web.servlet.mvc.Controller` implemented by using the Groovy dynamic language: @@ -725,11 +725,11 @@ running application and would not require the restart of an application. NOTE: To effect the automatic "`pickup`" of any changes to dynamic-language-backed beans, you have to enable the 'refreshable beans' feature. See -<> for a full and detailed treatment of this feature. +xref:languages/dynamic.adoc#dynamic-language-refreshable-beans[Refreshable Beans] for a full and detailed treatment of this feature. The following example shows a Spring `org.springframework.validation.Validator` -implemented by using the Groovy dynamic language (see <> for a discussion of the +implemented by using the Groovy dynamic language (see xref:core/validation/validator.adoc[Validation using Spring’s Validator interface] + for a discussion of the `Validator` interface): [source,groovy,indent=0,subs="verbatim,quotes"] @@ -770,7 +770,7 @@ You can use the Spring AOP framework to advise scripted beans. The Spring AOP framework actually is unaware that a bean that is being advised might be a scripted bean, so all of the AOP use cases and functionality that you use (or aim to use) work with scripted beans. When you advise scripted beans, you cannot use class-based -proxies. You must use <>. +proxies. You must use xref:core/aop/proxying.adoc[interface-based proxies]. You are not limited to advising scripted beans. You can also write aspects themselves in a supported dynamic language and use such beans to advise other Spring beans. @@ -784,11 +784,11 @@ This really would be an advanced use of the dynamic language support though. In case it is not immediately obvious, scripted beans can be scoped in the same way as any other bean. The `scope` attribute on the various `` elements lets you control the scope of the underlying scripted bean, as it does with a regular -bean. (The default scope is <>, +bean. (The default scope is xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton], as it is with "`regular`" beans.) The following example uses the `scope` attribute to define a Groovy bean scoped as -a <>: +a xref:core/beans/factory-scopes.adoc#beans-factory-scopes-prototype[prototype]: [source,xml,indent=0,subs="verbatim,quotes"] ---- @@ -810,7 +810,7 @@ a <>: ---- -See <> in <> +See xref:core/beans/factory-scopes.adoc[Bean Scopes] in xref:web/webmvc-view/mvc-xslt.adoc#mvc-view-xslt-beandefs[The IoC Container] for a full discussion of the scoping support in the Spring Framework. @@ -822,7 +822,7 @@ The `lang` elements in Spring XML configuration deal with exposing objects that written in a dynamic language (such as Groovy or BeanShell) as beans in the Spring container. These elements (and the dynamic language support) are comprehensively covered in -<>. See that section +xref:languages/dynamic.adoc[Dynamic Language Support]. See that section for full details on this support and the `lang` elements. To use the elements in the `lang` schema, you need to have the following preamble at the diff --git a/framework-docs/modules/ROOT/pages/languages/groovy.adoc b/framework-docs/modules/ROOT/pages/languages/groovy.adoc index 1fd0d3c924..d0833c2e80 100644 --- a/framework-docs/modules/ROOT/pages/languages/groovy.adoc +++ b/framework-docs/modules/ROOT/pages/languages/groovy.adoc @@ -7,7 +7,7 @@ existing Java application. The Spring Framework provides a dedicated `ApplicationContext` that supports a Groovy-based Bean Definition DSL. For more details, see -<>. +xref:core/beans/basics.adoc#groovy-bean-definition-dsl[The Groovy Bean Definition DSL]. Further support for Groovy, including beans written in Groovy, refreshable script beans, -and more is available in <>. +and more is available in xref:languages/dynamic.adoc[Dynamic Language Support]. diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc index 78b32230f4..c53a37351d 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/getting-started.adoc @@ -17,8 +17,8 @@ Boot 2 project on https://start.spring.io/#!language=kotlin&type=gradle-project[ [[choosing-the-web-flavor]] == Choosing the Web Flavor -Spring Framework now comes with two different web stacks: <> and -<>. +Spring Framework now comes with two different web stacks: xref:web/webmvc.adoc#mvc[Spring MVC] and +xref:testing/unit.adoc#mock-objects-web-reactive[Spring WebFlux]. Spring WebFlux is recommended if you want to create applications that will deal with latency, long-lived connections, streaming scenarios or if you want to use the web functional diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc index 3c8cc756c7..dc1a3f0257 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/null-safety.adoc @@ -9,7 +9,7 @@ declarations and expressing "`value or no value`" semantics without paying the c https://www.baeldung.com/kotlin-null-safety[comprehensive guide to Kotlin null-safety].) Although Java does not let you express null-safety in its type-system, the Spring Framework -provides <> +provides xref:languages/kotlin/null-safety.adoc[null-safety of the whole Spring Framework API] via tooling-friendly annotations declared in the `org.springframework.lang` package. By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], diff --git a/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc b/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc index 4bcb633c47..721eda14c8 100644 --- a/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc +++ b/framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc @@ -250,7 +250,7 @@ https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-featu [[constructor-injection]] === Constructor injection -As described in the <>, +As described in the xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-di[dedicated section], JUnit 5 allows constructor injection of beans which is pretty useful with Kotlin in order to use `val` instead of `lateinit var`. You can use {api-spring-framework}/test/context/TestConstructor.html[`@TestConstructor(autowireMode = AutowireMode.ALL)`] diff --git a/framework-docs/modules/ROOT/pages/rsocket.adoc b/framework-docs/modules/ROOT/pages/rsocket.adoc index f3580d824d..0672161ec6 100644 --- a/framework-docs/modules/ROOT/pages/rsocket.adoc +++ b/framework-docs/modules/ROOT/pages/rsocket.adoc @@ -137,9 +137,9 @@ demonstrate its API and protocol features. The `spring-messaging` module contains the following: -* <> -- fluent API to make requests through an `io.rsocket.RSocket` +* xref:rsocket.adoc#rsocket-requester[RSocketRequester] -- fluent API to make requests through an `io.rsocket.RSocket` with data and metadata encoding/decoding. -* <> -- `@MessageMapping` annotated handler methods for +* xref:rsocket.adoc#rsocket-annot-responders[Annotated Responders] -- `@MessageMapping` annotated handler methods for responding. The `spring-web` module contains `Encoder` and `Decoder` implementations such as Jackson @@ -219,7 +219,7 @@ metadata, the default mime type is metadata value and mime type pairs per request. Typically both don't need to be changed. Data and metadata in the `SETUP` frame is optional. On the server side, -<> methods can be used to handle the start of a +xref:rsocket.adoc#rsocket-annot-connectmapping[@ConnectMapping] methods can be used to handle the start of a connection and the content of the `SETUP` frame. Metadata may be used for connection level security. @@ -344,7 +344,7 @@ annotation such as `@RSocketClientResponder` vs the default `@Controller`. This is necessary in scenarios with client and server, or multiple clients in the same application. -See also <>, for more on the programming model. +See also xref:rsocket.adoc#rsocket-annot-responders[Annotated Responders], for more on the programming model. [[rsocket-requester-client-advanced]] @@ -382,7 +382,7 @@ at that level as follows: To make requests from a server to connected clients is a matter of obtaining the requester for the connected client from the server. -In <>, `@ConnectMapping` and `@MessageMapping` methods support an +In xref:rsocket.adoc#rsocket-annot-responders[Annotated Responders], `@ConnectMapping` and `@MessageMapping` methods support an `RSocketRequester` argument. Use it to access the requester for the connection. Keep in mind that `@ConnectMapping` methods are essentially handlers of the `SETUP` frame which must be handled before requests can begin. Therefore, requests at the very start must be @@ -425,8 +425,8 @@ decoupled from handling. For example: [[rsocket-requester-requests]] === Requests -Once you have a <> or -<> requester, you can make requests as follows: +Once you have a xref:rsocket.adoc#rsocket-requester-client[client] or +xref:rsocket.adoc#rsocket-requester-server[server] requester, you can make requests as follows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -604,7 +604,7 @@ Then start an RSocket server through the Java RSocket API and plug the `RSocketMessageHandler` supports {gh-rsocket-extensions}/CompositeMetadata.md[composite] and {gh-rsocket-extensions}/Routing.md[routing] metadata by default. You can set its -<> if you need to switch to a +xref:rsocket.adoc#rsocket-metadata-extractor[MetadataExtractor] if you need to switch to a different mime type or register additional metadata mime types. You'll need to set the `Encoder` and `Decoder` instances required for metadata and data @@ -669,15 +669,15 @@ you need to share configuration between a client and a server in the same proces Annotated responders on the client side need to be configured in the `RSocketRequester.Builder`. For details, see -<>. +xref:rsocket.adoc#rsocket-requester-client-responder[Client Responders]. [[rsocket-annot-messagemapping]] === @MessageMapping -Once <> or -<> responder configuration is in place, +Once xref:rsocket.adoc#rsocket-annot-responders-server[server] or +xref:rsocket.adoc#rsocket-annot-responders-client[client] responder configuration is in place, `@MessageMapping` methods can be used as follows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -729,10 +729,10 @@ use the following method arguments: pass:q[`@MessageMapping("find.radar.{id}")`]. | `@Header` -| Metadata value registered for extraction as described in <>. +| Metadata value registered for extraction as described in xref:rsocket.adoc#rsocket-metadata-extractor[MetadataExtractor]. | `@Headers Map` -| All metadata values registered for extraction as described in <>. +| All metadata values registered for extraction as described in xref:rsocket.adoc#rsocket-metadata-extractor[MetadataExtractor]. |=== @@ -800,7 +800,7 @@ any subsequent metadata push notifications through the `METADATA_PUSH` frame, i. `metadataPush(Payload)` in `io.rsocket.RSocket`. `@ConnectMapping` methods support the same arguments as -<> but based on metadata and data from the `SETUP` and +xref:rsocket.adoc#rsocket-annot-messagemapping[@MessageMapping] but based on metadata and data from the `SETUP` and `METADATA_PUSH` frames. `@ConnectMapping` can have a pattern to narrow handling to specific connections that have a route in the metadata, or if no patterns are declared then all connections match. @@ -809,7 +809,7 @@ then all connections match. `Mono` as the return value. If handling returns an error for a new connection then the connection is rejected. Handling must not be held up to make requests to the `RSocketRequester` for the connection. See -<> for details. +xref:rsocket.adoc#rsocket-requester-server[Server Requester] for details. @@ -911,7 +911,7 @@ simply use a callback to customize registrations as follows: The Spring Framework lets you define an RSocket service as a Java interface with annotated methods for RSocket exchanges. You can then generate a proxy that implements this interface and performs the exchanges. This helps to simplify RSocket remote access by wrapping the -use of the underlying <>. +use of the underlying xref:rsocket.adoc#rsocket-requester[RSocketRequester]. One, declare an interface with `@RSocketExchange` methods: diff --git a/framework-docs/modules/ROOT/pages/testing/annotations.adoc b/framework-docs/modules/ROOT/pages/testing/annotations.adoc index a13a911735..6e0ce2f52c 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations.adoc @@ -4,11 +4,11 @@ This section covers annotations that you can use when you test Spring applications. It includes the following topics: -* <> -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-standard.adoc[Standard Annotation Support] +* xref:testing/annotations/integration-spring.adoc[Spring Testing Annotations] +* xref:testing/annotations/integration-junit4.adoc[Spring JUnit 4 Testing Annotations] +* xref:testing/annotations/integration-junit-jupiter.adoc[Spring JUnit Jupiter Testing Annotations] +* xref:testing/annotations/integration-meta.adoc[Meta-Annotation Support for Testing] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc index bc53256f22..aaa87fca2a 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc @@ -2,15 +2,15 @@ = Spring JUnit Jupiter Testing Annotations The following annotations are supported when used in conjunction with the -<> and JUnit Jupiter +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-extension[`SpringExtension`] and JUnit Jupiter (that is, the programming model in JUnit 5): -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-springjunitconfig[`@SpringJUnitConfig`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-springjunitwebconfig[`@SpringJUnitWebConfig`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[`@NestedTestConfiguration`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-enabledif[`@EnabledIf`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-disabledif[`@DisabledIf`] [[integration-testing-annotations-junit-jupiter-springjunitconfig]] == `@SpringJUnitConfig` @@ -70,7 +70,7 @@ location of a configuration file: <1> Specify the location of a configuration file. -See <> as well as the javadoc for +See xref:testing/testcontext-framework/ctx-management.adoc[Context Management] as well as the javadoc for {api-spring-framework}/test/context/junit/jupiter/SpringJUnitConfig.html[`@SpringJUnitConfig`] and `@ContextConfiguration` for further details. @@ -135,7 +135,7 @@ location of a configuration file: <1> Specify the location of a configuration file. -See <> as well as the javadoc for +See xref:testing/testcontext-framework/ctx-management.adoc[Context Management] as well as the javadoc for {api-spring-framework}/test/context/junit/jupiter/web/SpringJUnitWebConfig.html[`@SpringJUnitWebConfig`], {api-spring-framework}/test/context/ContextConfiguration.html[`@ContextConfiguration`], and {api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`] @@ -159,7 +159,7 @@ constructor takes precedence over both `@TestConstructor` and the default mode. The default _test constructor autowire mode_ can be changed by setting the `spring.test.constructor.autowire.mode` JVM system property to `all`. Alternatively, the default mode may be set via the -<> mechanism. +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism. As of Spring Framework 5.3, the default mode may also be configured as a https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params[JUnit Platform configuration parameter]. @@ -192,36 +192,36 @@ change the default mode. The default _enclosing configuration inheritance mode_ is `INHERIT`, but it can be changed by setting the `spring.test.enclosing.configuration` JVM system property to `OVERRIDE`. Alternatively, the default mode may be set via the -<> mechanism. +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism. ===== -The <> honors `@NestedTestConfiguration` semantics for the +The xref:testing/testcontext-framework.adoc[Spring TestContext Framework] honors `@NestedTestConfiguration` semantics for the following annotations. -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-spring/annotation-bootstrapwith.adoc[`@BootstrapWith`] +* xref:testing/annotations/integration-spring/annotation-contextconfiguration.adoc[`@ContextConfiguration`] +* xref:testing/annotations/integration-spring/annotation-webappconfiguration.adoc[`@WebAppConfiguration`] +* xref:testing/annotations/integration-spring/annotation-contexthierarchy.adoc[`@ContextHierarchy`] +* xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[`@ActiveProfiles`] +* xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[`@TestPropertySource`] +* xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[`@DynamicPropertySource`] +* xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`] +* xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[`@TestExecutionListeners`] +* xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[`@RecordApplicationEvents`] +* xref:testing/testcontext-framework/tx.adoc[`@Transactional`] +* xref:testing/annotations/integration-spring/annotation-commit.adoc[`@Commit`] +* xref:testing/annotations/integration-spring/annotation-rollback.adoc[`@Rollback`] +* xref:testing/annotations/integration-spring/annotation-sql.adoc[`@Sql`] +* xref:testing/annotations/integration-spring/annotation-sqlconfig.adoc[`@SqlConfig`] +* xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[`@SqlMergeMode`] +* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`] NOTE: The use of `@NestedTestConfiguration` typically only makes sense in conjunction with `@Nested` test classes in JUnit Jupiter; however, there may be other testing frameworks with support for Spring and nested test classes that make use of this annotation. -See <> for an example and further +See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for an example and further details. [[integration-testing-annotations-junit-jupiter-enabledif]] @@ -235,9 +235,9 @@ within that class are automatically enabled by default as well. Expressions can be any of the following: -* <> (SpEL) expression. For example: +* xref:core/expressions.adoc[Spring Expression Language] (SpEL) expression. For example: `@EnabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")` -* Placeholder for a property available in the Spring <>. +* Placeholder for a property available in the Spring xref:core/beans/environment.adoc[`Environment`]. For example: `@EnabledIf("${smoke.tests.enabled}")` * Text literal. For example: `@EnabledIf("true")` @@ -295,9 +295,9 @@ test methods within that class are automatically disabled as well. Expressions can be any of the following: -* <> (SpEL) expression. For example: +* xref:core/expressions.adoc[Spring Expression Language] (SpEL) expression. For example: `@DisabledIf("#{systemProperties['os.name'].toLowerCase().contains('mac')}")` -* Placeholder for a property available in the Spring <>. +* Placeholder for a property available in the Spring xref:core/beans/environment.adoc[`Environment`]. For example: `@DisabledIf("${smoke.tests.disabled}")` * Text literal. For example: `@DisabledIf("true")` diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc index 077c53dbf0..924a17f81c 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-junit4.adoc @@ -2,13 +2,13 @@ = Spring JUnit 4 Testing Annotations The following annotations are supported only when used in conjunction with the -<>, <>, or <>: +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-runner[SpringRunner], xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules[Spring's JUnit 4 rules] +, or xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-junit4[Spring's JUnit 4 support classes]: -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-junit4.adoc#integration-testing-annotations-junit4-ifprofilevalue[`@IfProfileValue`] +* xref:testing/annotations/integration-junit4.adoc#integration-testing-annotations-junit4-profilevaluesourceconfiguration[`@ProfileValueSourceConfiguration`] +* xref:testing/annotations/integration-junit4.adoc#integration-testing-annotations-junit4-timed[`@Timed`] +* xref:testing/annotations/integration-junit4.adoc#integration-testing-annotations-junit4-repeat[`@Repeat`] [[integration-testing-annotations-junit4-ifprofilevalue]] == `@IfProfileValue` @@ -154,7 +154,7 @@ times that the test method is to be run is specified in the annotation. The scope of execution to be repeated includes execution of the test method itself as well as any setting up or tearing down of the test fixture. When used with the -<>, the scope additionally includes +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules[`SpringMethodRule`], the scope additionally includes preparation of the test instance by `TestExecutionListener` implementations. The following example shows how to use the `@Repeat` annotation: diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc index 8cb176ac1b..66ee7b1123 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-meta.adoc @@ -2,11 +2,11 @@ = Meta-Annotation Support for Testing You can use most test-related annotations as -<> to create custom composed +xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotations] to create custom composed annotations and reduce configuration duplication across a test suite. You can use each of the following as a meta-annotation in conjunction with the -<>. +xref:testing/testcontext-framework.adoc[TestContext framework]. * `@BootstrapWith` * `@ContextConfiguration` diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc index 8bfde481a8..3db79d44bc 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring.adoc @@ -8,22 +8,22 @@ values, attribute aliases, and other details. Spring's testing annotations include the following: -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/annotations/integration-spring/annotation-bootstrapwith.adoc[`@BootstrapWith`] +* xref:testing/annotations/integration-spring/annotation-contextconfiguration.adoc[`@ContextConfiguration`] +* xref:testing/annotations/integration-spring/annotation-webappconfiguration.adoc[`@WebAppConfiguration`] +* xref:testing/annotations/integration-spring/annotation-contexthierarchy.adoc[`@ContextHierarchy`] +* xref:testing/annotations/integration-spring/annotation-activeprofiles.adoc[`@ActiveProfiles`] +* xref:testing/annotations/integration-spring/annotation-testpropertysource.adoc[`@TestPropertySource`] +* xref:testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc[`@DynamicPropertySource`] +* xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`] +* xref:testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc[`@TestExecutionListeners`] +* xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[`@RecordApplicationEvents`] +* xref:testing/annotations/integration-spring/annotation-commit.adoc[`@Commit`] +* xref:testing/annotations/integration-spring/annotation-rollback.adoc[`@Rollback`] +* xref:testing/annotations/integration-spring/annotation-beforetransaction.adoc[`@BeforeTransaction`] +* xref:testing/annotations/integration-spring/annotation-aftertransaction.adoc[`@AfterTransaction`] +* xref:testing/annotations/integration-spring/annotation-sql.adoc[`@Sql`] +* xref:testing/annotations/integration-spring/annotation-sqlconfig.adoc[`@SqlConfig`] +* xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[`@SqlMergeMode`] +* xref:testing/annotations/integration-spring/annotation-sqlgroup.adoc[`@SqlGroup`] diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc index 42a1284f6d..7ff17ec542 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-activeprofiles.adoc @@ -59,11 +59,11 @@ be active: NOTE: `@ActiveProfiles` provides support for inheriting active bean definition profiles declared by superclasses and enclosing classes by default. You can also resolve active bean definition profiles programmatically by implementing a custom -<> +xref:testing/testcontext-framework/ctx-management/env-profiles.adoc#testcontext-ctx-management-env-profiles-ActiveProfilesResolver[`ActiveProfilesResolver`] and registering it by using the `resolver` attribute of `@ActiveProfiles`. -See <>, -<>, and the +See xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[Context Configuration with Environment Profiles], +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration], and the {api-spring-framework}/test/context/ActiveProfiles.html[`@ActiveProfiles`] javadoc for examples and further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc index 6646495d54..be83db1212 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-bootstrapwith.adoc @@ -4,5 +4,5 @@ `@BootstrapWith` is a class-level annotation that you can use to configure how the Spring TestContext Framework is bootstrapped. Specifically, you can use `@BootstrapWith` to specify a custom `TestContextBootstrapper`. See the section on -<> for further details. +xref:testing/testcontext-framework/bootstrapping.adoc[bootstrapping the TestContext framework] for further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc index e39524afd9..8d783ac240 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contextconfiguration.adoc @@ -10,7 +10,7 @@ Resource locations are typically XML configuration files or Groovy scripts locat classpath, while component classes are typically `@Configuration` classes. However, resource locations can also refer to files and scripts in the file system, and component classes can be `@Component` classes, `@Service` classes, and so on. See -<> for further details. +xref:testing/testcontext-framework/ctx-management/javaconfig.adoc#testcontext-ctx-management-javaconfig-component-classes[null] for further details. The following example shows a `@ContextConfiguration` annotation that refers to an XML file: @@ -116,7 +116,7 @@ NOTE: `@ContextConfiguration` provides support for inheriting resource locations configuration classes as well as context initializers that are declared by superclasses or enclosing classes. -See <>, -<>, and the `@ContextConfiguration` +See xref:testing/testcontext-framework/ctx-management.adoc[Context Management], +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration], and the `@ContextConfiguration` javadocs for further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc index e0f0c48b54..89bf319058 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-contexthierarchy.adoc @@ -57,7 +57,7 @@ within a test class hierarchy): If you need to merge or override the configuration for a given level of the context hierarchy within a test class hierarchy, you must explicitly name that level by supplying the same value to the `name` attribute in `@ContextConfiguration` at each corresponding -level in the class hierarchy. See <> and the +level in the class hierarchy. See xref:testing/testcontext-framework/ctx-management/hierarchies.adoc[Context Hierarchies] and the {api-spring-framework}/test/context/ContextHierarchy.html[`@ContextHierarchy`] javadoc for further examples. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc index 70bb526e0d..21bafb5324 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-dynamicpropertysource.adoc @@ -55,5 +55,5 @@ The following example demonstrates how to register a dynamic property: <2> Accept a `DynamicPropertyRegistry` as an argument. <3> Register a dynamic `server.port` property to be retrieved lazily from the server. -See <> for further details. +See xref:testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc[Context Configuration with Dynamic Property Sources] for further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc index dcb9a2df44..51a1c21000 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-recordapplicationevents.adoc @@ -7,7 +7,7 @@ _Spring TestContext Framework_ to record all application events that are publish The recorded events can be accessed via the `ApplicationEvents` API within tests. -See <> and the +See xref:testing/testcontext-framework/application-events.adoc[Application Events] and the {api-spring-framework}/test/context/event/RecordApplicationEvents.html[`@RecordApplicationEvents` javadoc] for an example and further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc index 2d4c7ace09..d5eb93ed28 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-rollback.adoc @@ -4,7 +4,7 @@ `@Rollback` indicates whether the transaction for a transactional test method should be rolled back after the test method has completed. If `true`, the transaction is rolled back. Otherwise, the transaction is committed (see also -<>). Rollback for integration tests in the Spring +xref:testing/annotations/integration-spring/annotation-commit.adoc[`@Commit`]). Rollback for integration tests in the Spring TestContext Framework defaults to `true` even if `@Rollback` is not explicitly declared. When declared as a class-level annotation, `@Rollback` defines the default rollback diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc index 32dd573437..975e043e86 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-sql.adoc @@ -27,6 +27,6 @@ it: ---- <1> Run two scripts for this test. -See <> for further details. +See xref:testing/testcontext-framework/executing-sql.adoc#testcontext-executing-sql-declaratively[Executing SQL scripts declaratively with @Sql] for further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc index 38548fc415..e79aa245ec 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testexecutionlisteners.adoc @@ -4,7 +4,7 @@ `@TestExecutionListeners` is used to register listeners for a particular test class, its subclasses, and its nested classes. If you wish to register a listener globally, you should register it via the automatic discovery mechanism described in -<>. +xref:testing/testcontext-framework/tel-config.adoc[`TestExecutionListener` Configuration]. The following example shows how to register two `TestExecutionListener` implementations: @@ -33,9 +33,9 @@ The following example shows how to register two `TestExecutionListener` implemen By default, `@TestExecutionListeners` provides support for inheriting listeners from superclasses or enclosing classes. See -<> and the +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] and the {api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners` javadoc] for an example and further details. If you discover that you need to switch back to using the default `TestExecutionListener` implementations, see the note -in <>. +in xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-registering-tels[Registering `TestExecutionListener` Implementations]. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc index c793c4b057..40ba2240a3 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-spring/annotation-testpropertysource.adoc @@ -55,5 +55,5 @@ The following example demonstrates how to declare inlined properties: ---- <1> Declare `timezone` and `port` properties. -See <> for examples and further details. +See xref:testing/testcontext-framework/ctx-management/property-sources.adoc[Context Configuration with Test Property Sources] for examples and further details. diff --git a/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc b/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc index c18d763e57..4406377286 100644 --- a/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc +++ b/framework-docs/modules/ROOT/pages/testing/annotations/integration-standard.adoc @@ -15,7 +15,7 @@ and can be used anywhere in the Spring Framework. * `@PersistenceContext` (jakarta.persistence) if JPA is present * `@PersistenceUnit` (jakarta.persistence) if JPA is present * `@Transactional` (org.springframework.transaction.annotation) - _with <>_ + _with xref:testing/testcontext-framework/tx.adoc#testcontext-tx-attribute-support[limited attribute support]_ .JSR-250 Lifecycle Annotations [NOTE] diff --git a/framework-docs/modules/ROOT/pages/testing/integration.adoc b/framework-docs/modules/ROOT/pages/testing/integration.adoc index 5c5bc4e90b..a7a4b39729 100644 --- a/framework-docs/modules/ROOT/pages/testing/integration.adoc +++ b/framework-docs/modules/ROOT/pages/testing/integration.adoc @@ -12,7 +12,7 @@ Doing so lets you test things such as: The Spring Framework provides first-class support for integration testing in the `spring-test` module. The name of the actual JAR file might include the release version and might also be in the long `org.springframework.test` form, depending on where you get -it from (see the <> +it from (see the xref:core/beans/dependencies.adoc[section on Dependency Management] for an explanation). This library includes the `org.springframework.test` package, which contains valuable classes for integration testing with a Spring container. This testing does not rely on an application server or other deployment environment. Such tests are @@ -20,19 +20,19 @@ slower to run than unit tests but much faster than the equivalent Selenium tests remote tests that rely on deployment to an application server. Unit and integration testing support is provided in the form of the annotation-driven -<>. The TestContext framework is +xref:testing/testcontext-framework.adoc[Spring TestContext Framework]. The TestContext framework is agnostic of the actual testing framework in use, which allows instrumentation of tests in various environments, including JUnit, TestNG, and others. The following section provides an overview of the high-level goals of Spring's integration support, and the rest of this chapter then focuses on dedicated topics: -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/support-jdbc.adoc[JDBC Testing Support] +* xref:testing/testcontext-framework.adoc[Spring TestContext Framework] +* xref:testing/webtestclient.adoc[WebTestClient] +* xref:testing/spring-mvc-test-framework.adoc[MockMvc] +* xref:testing/spring-mvc-test-client.adoc[Testing Client Applications] +* xref:testing/annotations.adoc[Annotations] @@ -41,10 +41,10 @@ integration support, and the rest of this chapter then focuses on dedicated topi Spring's integration testing support has the following primary goals: -* To manage <> between tests. -* To provide <>. -* To provide <> appropriate to integration testing. -* To supply <> that assist +* To manage xref:testing/integration.adoc#testing-ctx-management[Spring IoC container caching] between tests. +* To provide xref:testing/integration.adoc#testing-fixture-di[Dependency Injection of test fixture instances]. +* To provide xref:testing/integration.adoc#testing-tx[transaction management] appropriate to integration testing. +* To supply xref:testing/integration.adoc#testing-support-classes[Spring-specific base classes] that assist developers in writing integration tests. The next few sections describe each goal and provide links to implementation and @@ -78,7 +78,7 @@ reloading (for example, by modifying a bean definition or the state of an applic object) the TestContext framework can be configured to reload the configuration and rebuild the application context before executing the next test. -See <> and <> with the +See xref:testing/testcontext-framework/ctx-management.adoc[Context Management] and xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching] with the TestContext framework. @@ -105,7 +105,7 @@ integration tests that test the following areas: perform as anticipated? See dependency injection of test fixtures with the -<>. +xref:testing/testcontext-framework/fixture-di.adoc[TestContext framework]. [[testing-tx]] @@ -128,9 +128,9 @@ using a `PlatformTransactionManager` bean defined in the test's application cont If you want a transaction to commit (unusual, but occasionally useful when you want a particular test to populate or modify the database), you can tell the TestContext framework to cause the transaction to commit instead of roll back by using the -<> annotation. +xref:testing/annotations.adoc[`@Commit`] annotation. -See transaction management with the <>. +See transaction management with the xref:testing/testcontext-framework/tx.adoc[TestContext framework]. [[testing-support-classes]] @@ -147,9 +147,9 @@ which let you access: queries to confirm database state both before and after execution of database-related application code, and Spring ensures that such queries run in the scope of the same transaction as the application code. When used in conjunction with an ORM tool, be sure - to avoid <>. + to avoid xref:testing/testcontext-framework/tx.adoc#testcontext-tx-false-positives[false positives]. In addition, you may want to create your own custom, application-wide superclass with instance variables and methods specific to your project. -See support classes for the <>. +See support classes for the xref:testing/testcontext-framework/support-classes.adoc[TestContext framework]. diff --git a/framework-docs/modules/ROOT/pages/testing/introduction.adoc b/framework-docs/modules/ROOT/pages/testing/introduction.adoc index 1bc210f4b1..71bf53da36 100644 --- a/framework-docs/modules/ROOT/pages/testing/introduction.adoc +++ b/framework-docs/modules/ROOT/pages/testing/introduction.adoc @@ -2,7 +2,7 @@ = Introduction to Spring Testing Testing is an integral part of enterprise software development. This chapter focuses on -the value added by the IoC principle to <> and on the benefits -of the Spring Framework's support for <>. (A +the value added by the IoC principle to xref:testing/unit.adoc[unit testing] and on the benefits +of the Spring Framework's support for xref:testing/integration.adoc[integration testing]. (A thorough treatment of testing in the enterprise is beyond the scope of this reference manual.) diff --git a/framework-docs/modules/ROOT/pages/testing/resources.adoc b/framework-docs/modules/ROOT/pages/testing/resources.adoc index e274dd94f9..c7b3c247dc 100644 --- a/framework-docs/modules/ROOT/pages/testing/resources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/resources.adoc @@ -4,10 +4,10 @@ See the following resources for more information about testing: * https://www.junit.org/[JUnit]: "A programmer-friendly testing framework for Java and the JVM". Used by the Spring Framework in its test suite and supported in the - <>. + xref:testing/testcontext-framework.adoc[Spring TestContext Framework]. * https://testng.org/[TestNG]: A testing framework inspired by JUnit with added support for test groups, data-driven testing, distributed testing, and other features. Supported - in the <> + in the xref:testing/testcontext-framework.adoc[Spring TestContext Framework] * https://assertj.github.io/doc/[AssertJ]: "Fluent assertions for Java", including support for Java 8 lambdas, streams, and numerous other features. * https://en.wikipedia.org/wiki/Mock_Object[Mock Objects]: Article in Wikipedia. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc index 20e842203e..19ed892215 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework.adoc @@ -6,7 +6,7 @@ MVC applications. It performs full Spring MVC request handling but via mock requ response objects instead of a running server. MockMvc can be used on its own to perform requests and verify responses. It can also be -used through the <> where MockMvc is plugged in as the server to handle +used through the xref:testing/webtestclient.adoc[WebTestClient] where MockMvc is plugged in as the server to handle requests with. The advantage of `WebTestClient` is the option to work with higher level objects instead of raw data as well as the ability to switch to full, end-to-end HTTP tests against a live server and use the same test API. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc index b6b4f06ff1..f8e8cda909 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/async-requests.adoc @@ -2,11 +2,11 @@ = Async Requests This section shows how to use MockMvc on its own to test asynchronous request handling. -If using MockMvc through the <>, there is nothing special to do to make +If using MockMvc through the xref:testing/webtestclient.adoc[WebTestClient], there is nothing special to do to make asynchronous requests work as the `WebTestClient` automatically does what is described in this section. -Servlet asynchronous requests, <>, +Servlet asynchronous requests, xref:web/webmvc/mvc-ann-async.adoc[supported in Spring MVC], work by exiting the Servlet container thread and allowing the application to compute the response asynchronously, after which an async dispatch is made to complete processing on a Servlet container thread. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc index 579c3e5e97..fda2259ef3 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit.adoc @@ -1,7 +1,7 @@ [[spring-mvc-test-server-htmlunit]] = HtmlUnit Integration -Spring provides integration between <> and +Spring provides integration between xref:testing/spring-mvc-test-framework/server.adoc[MockMvc] and https://htmlunit.sourceforge.io/[HtmlUnit]. This simplifies performing end-to-end testing when using HTML-based views. This integration lets you: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc index 39d6033201..8be8dd5292 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/geb.adoc @@ -8,7 +8,7 @@ use https://www.gebish.org/[Geb] to make our tests even Groovy-er. == Why Geb and MockMvc? Geb is backed by WebDriver, so it offers many of the -<> that we get from +xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-why[same benefits] that we get from WebDriver. However, Geb makes things even easier by taking care of some of the boilerplate code for us. @@ -28,7 +28,7 @@ def setup() { ---- NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced -usage, see <>. +usage, see xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-advanced-builder[Advanced `MockMvcHtmlUnitDriverBuilder`]. This ensures that any URL referencing `localhost` as the server is directed to our `MockMvc` instance without the need for a real HTTP connection. Any other URL is @@ -62,7 +62,7 @@ forwarded to the current page object. This removes a lot of the boilerplate code needed when using WebDriver directly. As with direct WebDriver usage, this improves on the design of our -<> by using the Page Object +xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-usage[HtmlUnit test] by using the Page Object Pattern. As mentioned previously, we can use the Page Object Pattern with HtmlUnit and WebDriver, but it is even easier with Geb. Consider our new Groovy-based `CreateMessagePage` implementation: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc index c343237872..3809ffd3b5 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/mah.adoc @@ -41,7 +41,7 @@ We can easily create an HtmlUnit `WebClient` that integrates with MockMvc by usi ---- NOTE: This is a simple example of using `MockMvcWebClientBuilder`. For advanced usage, -see <>. +see xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-advanced-builder[Advanced `MockMvcWebClientBuilder`]. This ensures that any URL that references `localhost` as the server is directed to our `MockMvc` instance without the need for a real HTTP connection. Any other URL is @@ -68,7 +68,7 @@ message with the following: ---- NOTE: The default context path is `""`. Alternatively, we can specify the context path, -as described in <>. +as described in xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-advanced-builder[Advanced `MockMvcWebClientBuilder`]. Once we have a reference to the `HtmlPage`, we can then fill out the form and submit it to create a message, as the following example shows: @@ -123,7 +123,7 @@ assertions use the https://assertj.github.io/doc/[AssertJ] library: ---- The preceding code improves on our -<> in a number of ways. +xref:testing/spring-mvc-test-framework/server-htmlunit/why.adoc#spring-mvc-test-server-htmlunit-mock-mvc-test[MockMvc test] in a number of ways. First, we no longer have to explicitly verify our form and then create a request that looks like the form. Instead, we request the form, fill it out, and submit it, thereby significantly reducing the overhead. @@ -238,5 +238,5 @@ This is more verbose, but, by building the `WebClient` with a `MockMvc` instance the full power of MockMvc at our fingertips. TIP: For additional information on creating a `MockMvc` instance, see -<>. +xref:testing/spring-mvc-test-framework/server-setup-options.adoc[Setup Choices]. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc index 57a91b6595..fbc2d34485 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc @@ -180,7 +180,7 @@ We can easily create a Selenium WebDriver that integrates with MockMvc by using ---- NOTE: This is a simple example of using `MockMvcHtmlUnitDriverBuilder`. For more advanced -usage, see <>. +usage, see xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-advanced-builder[Advanced `MockMvcHtmlUnitDriverBuilder`]. The preceding example ensures that any URL that references `localhost` as the server is directed to our `MockMvc` instance without the need for a real HTTP connection. Any other @@ -226,9 +226,9 @@ We can then fill out the form and submit it to create a message, as follows: ---- -- -This improves on the design of our <> +This improves on the design of our xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc#spring-mvc-test-server-htmlunit-mah-usage[HtmlUnit test] by leveraging the Page Object Pattern. As we mentioned in -<>, we can use the Page Object Pattern +xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc#spring-mvc-test-server-htmlunit-webdriver-why[Why WebDriver and MockMvc?], we can use the Page Object Pattern with HtmlUnit, but it is much easier with WebDriver. Consider the following `CreateMessagePage` implementation: @@ -499,5 +499,5 @@ This is more verbose, but, by building the `WebDriver` with a `MockMvc` instance the full power of MockMvc at our fingertips. TIP: For additional information on creating a `MockMvc` instance, see -<>. +xref:testing/spring-mvc-test-framework/server-setup-options.adoc[Setup Choices]. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc index 55b478e20d..174f9108fa 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-htmlunit/why.adoc @@ -177,11 +177,11 @@ with HtmlUnit.`" You have a number of options when you want to integrate MockMvc with HtmlUnit: -* <>: Use this option if you +* xref:testing/spring-mvc-test-framework/server-htmlunit/mah.adoc[MockMvc and HtmlUnit]: Use this option if you want to use the raw HtmlUnit libraries. -* <>: Use this option to +* xref:testing/spring-mvc-test-framework/server-htmlunit/webdriver.adoc[MockMvc and WebDriver]: Use this option to ease development and reuse code between integration and end-to-end testing. -* <>: Use this option if you want to +* xref:testing/spring-mvc-test-framework/server-htmlunit/geb.adoc[MockMvc and Geb]: Use this option if you want to use Groovy for testing, ease development, and reuse code between integration and end-to-end testing. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc index adc596e549..4bb64992e3 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-performing-requests.adoc @@ -3,7 +3,7 @@ This section shows how to use MockMvc on its own to perform requests and verify responses. If using MockMvc through the `WebTestClient` please see the corresponding section on -<> instead. +xref:testing/webtestclient.adoc#webtestclient-tests[Writing Tests] instead. To perform requests that use any HTTP method, as the following example shows: diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc index 26e34e1641..d6a6cf9f48 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-setup-options.adoc @@ -42,7 +42,7 @@ To set up MockMvc for testing a specific controller, use the following: ---- Or you can also use this setup when testing through the -<> which delegates to the same builder +xref:testing/webtestclient.adoc#webtestclient-controller-config[WebTestClient] which delegates to the same builder as shown above. To set up MockMvc through Spring configuration, use the following: @@ -84,7 +84,7 @@ To set up MockMvc through Spring configuration, use the following: ---- Or you can also use this setup when testing through the -<> which delegates to the same builder +xref:testing/webtestclient.adoc#webtestclient-context-config[WebTestClient] which delegates to the same builder as shown above. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc index 834ee8d26b..a082636a62 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server-static-imports.adoc @@ -11,7 +11,7 @@ When using MockMvc directly to perform requests, you'll need static imports for: An easy way to remember that is search for `MockMvc*`. If using Eclipse be sure to also add the above as "`favorite static members`" in the Eclipse preferences. -When using MockMvc through the <> you do not need static imports. +When using MockMvc through the xref:testing/webtestclient.adoc[WebTestClient] you do not need static imports. The `WebTestClient` provides a fluent API without static imports. diff --git a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc index 929faaf13b..f319cabb9a 100644 --- a/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc +++ b/framework-docs/modules/ROOT/pages/testing/spring-mvc-test-framework/server.adoc @@ -10,14 +10,14 @@ do they involve any of the supporting `@InitBinder`, `@ModelAttribute`, or The Spring MVC Test framework, also known as `MockMvc`, aims to provide more complete testing for Spring MVC controllers without a running server. It does that by invoking the `DispatcherServlet` and passing -<> from the +xref:testing/unit.adoc#mock-objects-servlet["`mock`" implementations of the Servlet API] from the `spring-test` module which replicates the full Spring MVC request handling without a running server. MockMvc is a server side test framework that lets you verify most of the functionality of a Spring MVC application using lightweight and targeted tests. You can use it on its own to perform requests and to verify responses, or you can also use it through -the <> API with MockMvc plugged in as the server to handle requests +the xref:testing/webtestclient.adoc[WebTestClient] API with MockMvc plugged in as the server to handle requests with. diff --git a/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc b/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc index 8ae2a2be22..cc09b76658 100644 --- a/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc +++ b/framework-docs/modules/ROOT/pages/testing/support-jdbc.adoc @@ -19,8 +19,8 @@ methods. [TIP] ==== -<> -and <> +xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-junit4[`AbstractTransactionalJUnit4SpringContextTests`] +and xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-testng[`AbstractTransactionalTestNGSpringContextTests`] provide convenience methods that delegate to the aforementioned methods in `JdbcTestUtils`. ==== @@ -30,6 +30,6 @@ provide convenience methods that delegate to the aforementioned methods in The `spring-jdbc` module provides support for configuring and launching an embedded database, which you can use in integration tests that interact with a database. -For details, see <> and <>. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc index fe336ea7d5..0acb1ddcb7 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework.adoc @@ -17,9 +17,9 @@ required to extend a particular class hierarchy, such as the `abstract` support The following section provides an overview of the internals of the TestContext framework. If you are interested only in using the framework and are not interested in extending it with your own custom listeners or custom loaders, feel free to go directly to the -configuration (<>, -<>, <>), <>, and -<> sections. +configuration (xref:testing/testcontext-framework/ctx-management.adoc[context management], +xref:testing/testcontext-framework/fixture-di.adoc[dependency injection], xref:testing/testcontext-framework/tx.adoc[transaction management] +), xref:testing/testcontext-framework/support-classes.adoc[support classes], and +xref:testing/annotations.adoc[annotation support] sections. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc index d7a9e735c9..88487c5002 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/aot.adoc @@ -4,7 +4,7 @@ This chapter covers Spring's Ahead of Time (AOT) support for integration tests using the Spring TestContext Framework. -The testing support extends Spring's <> with the +The testing support extends Spring's xref:core/aot.adoc[core AOT support] with the following features. * Build-time detection of all integration tests in the current project that use the @@ -14,10 +14,10 @@ following features. testing annotations -- as long as the tests are run using a JUnit Platform `TestEngine` that is registered for the current project. * Build-time AOT processing: each unique test `ApplicationContext` in the current project - will be <>. + will be xref:core/aot.adoc#core.aot.refresh[refreshed for AOT processing]. * Runtime AOT support: when executing in AOT runtime mode, a Spring integration test will use an AOT-optimized `ApplicationContext` that participates transparently with the - <>. + xref:testing/testcontext-framework/ctx-management/caching.adoc[context cache]. [WARNING] ==== @@ -35,7 +35,7 @@ the following options. via {api-spring-framework}/context/annotation/ImportRuntimeHints.html[`@ImportRuntimeHints`]. * Annotate a test class with {api-spring-framework}/aot/hint/annotation/Reflective.html[`@Reflective`] or {api-spring-framework}/aot/hint/annotation/RegisterReflectionForBinding.html[`@RegisterReflectionForBinding`]. -* See <> for details on Spring's core runtime hints +* See xref:core/aot.adoc#core.aot.hints[Runtime Hints] for details on Spring's core runtime hints and annotation support. [TIP] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc index 516e5de64d..b9779c0152 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/application-events.adoc @@ -2,7 +2,7 @@ = Application Events Since Spring Framework 5.3.3, the TestContext framework provides support for recording -<> published in the +xref:core/beans/context-introduction.adoc#context-functionality-events[application events] published in the `ApplicationContext` so that assertions can be performed against those events within tests. All events published during the execution of a single test are made available via the `ApplicationEvents` API which allows you to process the events as a @@ -11,7 +11,7 @@ the `ApplicationEvents` API which allows you to process the events as a To use `ApplicationEvents` in your tests, do the following. * Ensure that your test class is annotated or meta-annotated with - <>. + xref:testing/annotations/integration-spring/annotation-recordapplicationevents.adoc[`@RecordApplicationEvents`]. * Ensure that the `ApplicationEventsTestExecutionListener` is registered. Note, however, that `ApplicationEventsTestExecutionListener` is registered by default and only needs to be manually registered if you have custom configuration via @@ -19,7 +19,7 @@ To use `ApplicationEvents` in your tests, do the following. * Annotate a field of type `ApplicationEvents` with `@Autowired` and use that instance of `ApplicationEvents` in your test and lifecycle methods (such as `@BeforeEach` and `@AfterEach` methods in JUnit Jupiter). -** When using the <>, you may declare a method +** When using the xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-extension[SpringExtension for JUnit Jupiter], you may declare a method parameter of type `ApplicationEvents` in a test or lifecycle method as an alternative to an `@Autowired` field in the test class. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc index 605aef0a4b..3807f827d0 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management.adoc @@ -80,7 +80,7 @@ the web application context into your test, as follows: Dependency injection by using `@Autowired` is provided by the `DependencyInjectionTestExecutionListener`, which is configured by default -(see <>). +(see xref:testing/testcontext-framework/fixture-di.adoc[Dependency Injection of Test Fixtures]). ===== Test classes that use the TestContext framework do not need to extend any particular @@ -98,16 +98,16 @@ component classes (typically `@Configuration` classes), or context initializers. Alternatively, you can implement and configure your own custom `SmartContextLoader` for advanced use cases. -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* xref:testing/testcontext-framework/ctx-management/xml.adoc[Context Configuration with XML resources] +* xref:testing/testcontext-framework/ctx-management/groovy.adoc[Context Configuration with Groovy Scripts] +* xref:testing/testcontext-framework/ctx-management/javaconfig.adoc[Context Configuration with Component Classes] +* xref:testing/testcontext-framework/ctx-management/mixed-config.adoc[Mixing XML, Groovy Scripts, and Component Classes] +* xref:testing/testcontext-framework/ctx-management/initializers.adoc[Context Configuration with Context Initializers] +* xref:testing/testcontext-framework/ctx-management/inheritance.adoc[Context Configuration Inheritance] +* xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[Context Configuration with Environment Profiles] +* xref:testing/testcontext-framework/ctx-management/property-sources.adoc[Context Configuration with Test Property Sources] +* xref:testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc[Context Configuration with Dynamic Property Sources] +* xref:testing/testcontext-framework/ctx-management/web.adoc[Loading a `WebApplicationContext`] +* xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching] +* xref:testing/testcontext-framework/ctx-management/hierarchies.adoc[Context Hierarchies] diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc index fd6f51764a..0a4f02f912 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/caching.adoc @@ -60,7 +60,7 @@ maximum size is reached, a least recently used (LRU) eviction policy is used to close stale contexts. You can configure the maximum size from the command line or a build script by setting a JVM system property named `spring.test.context.cache.maxSize`. As an alternative, you can set the same property via the -<> mechanism. +xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism. Since having a large number of application contexts loaded within a given test suite can cause the suite to take an unnecessarily long time to run, it is often beneficial to @@ -71,8 +71,8 @@ the underlying context cache, you can set the log level for the In the unlikely case that a test corrupts the application context and requires reloading (for example, by modifying a bean definition or the state of an application object), you can annotate your test class or test method with `@DirtiesContext` (see the discussion of -`@DirtiesContext` in <>). This instructs Spring to remove the context from the cache and rebuild +`@DirtiesContext` in xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[Spring Testing Annotations] +). This instructs Spring to remove the context from the cache and rebuild the application context before running the next test that requires the same application context. Note that support for the `@DirtiesContext` annotation is provided by the `DirtiesContextBeforeModesTestExecutionListener` and the @@ -96,7 +96,7 @@ class is being prepared -- for example, to perform dependency injection into `@A fields of the test instance. This means that any console logging triggered during the initialization of the `ApplicationContext` typically cannot be associated with an individual test method. However, if the context is closed immediately before the -execution of a test method according to <> +execution of a test method according to xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`] semantics, a new instance of the context will be loaded just prior to execution of the test method. In the latter scenario, an IDE or build tool may potentially associate console logging with the individual test method. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc index d1935942e2..30de9635eb 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc @@ -16,7 +16,7 @@ Spring integration tests. However, this feature may also be used with any form o external resource whose lifecycle is maintained outside the test's `ApplicationContext`. ==== -In contrast to the <> +In contrast to the xref:testing/testcontext-framework/ctx-management/property-sources.adoc[`@TestPropertySource`] annotation that is applied at the class level, `@DynamicPropertySource` must be applied to a `static` method that accepts a single `DynamicPropertyRegistry` argument which is used to add _name-value_ pairs to the `Environment`. Values are dynamic and provided via @@ -33,7 +33,7 @@ abstraction or injected directly into Spring-managed components – for example, ==== If you use `@DynamicPropertySource` in a base class and discover that tests in subclasses fail because the dynamic properties change between subclasses, you may need to annotate -your base class with <> to +your base class with xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[`@DirtiesContext`] to ensure that each subclass gets its own `ApplicationContext` with the correct dynamic properties. ==== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc index 2a96d0bd42..1f41ef8a09 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/env-profiles.adoc @@ -331,7 +331,7 @@ following example, the declaration of `@ActiveProfiles` (as well as other annota has been moved to an abstract superclass, `AbstractIntegrationTest`: NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <> for details. +classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for details. [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc index fcd850e9d7..e34e5b3bec 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/groovy.adoc @@ -2,11 +2,11 @@ = Context Configuration with Groovy Scripts To load an `ApplicationContext` for your tests by using Groovy scripts that use the -<>, you can annotate +xref:core/beans/basics.adoc#groovy-bean-definition-dsl[Groovy Bean Definition DSL], you can annotate your test class with `@ContextConfiguration` and configure the `locations` or `value` attribute with an array that contains the resource locations of Groovy scripts. Resource lookup semantics for Groovy scripts are the same as those described for -<>. +xref:testing/testcontext-framework/ctx-management/xml.adoc[XML configuration files]. .Enabling Groovy script support TIP: Support for using Groovy scripts to load an `ApplicationContext` in the Spring diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc index 6cfd1b3a4e..1411e7c1b1 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/hierarchies.adoc @@ -212,7 +212,7 @@ shows this configuration scenario: NOTE: If you use `@DirtiesContext` in a test whose context is configured as part of a context hierarchy, you can use the `hierarchyMode` flag to control how the context cache is cleared. For further details, see the discussion of `@DirtiesContext` in -<> and the +xref:testing/annotations/integration-spring/annotation-dirtiescontext.adoc[Spring Testing Annotations] and the {api-spring-framework}/test/annotation/DirtiesContext.html[`@DirtiesContext`] javadoc. -- diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc index 8229e9c89a..6c7b7650f2 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/inheritance.adoc @@ -18,7 +18,7 @@ initializers, respectively, for the test class shadow and effectively replace th configuration defined by superclasses. NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <> for details. +classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for details. In the next example, which uses XML resource locations, the `ApplicationContext` for `ExtendedTest` is loaded from `base-config.xml` and `extended-config.xml`, in that order. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc index fbc1b11114..bd7af6c148 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/javaconfig.adoc @@ -2,7 +2,7 @@ = Context Configuration with Component Classes To load an `ApplicationContext` for your tests by using component classes (see -<>), you can annotate your test +xref:core/beans/java.adoc[Java-based container configuration]), you can annotate your test class with `@ContextConfiguration` and configure the `classes` attribute with an array that contains references to component classes. The following example shows how to do so: diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc index 7d59858e24..263e21446d 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/property-sources.adoc @@ -137,7 +137,7 @@ declaratively by using `@PropertySource` or programmatically. Thus, test propert be used to selectively override properties loaded from system and application property sources. Furthermore, inlined properties have higher precedence than properties loaded from resource locations. Note, however, that properties registered via -<> have +xref:testing/testcontext-framework/ctx-management/dynamic-property-sources.adoc[`@DynamicPropertySource`] have higher precedence than those loaded via `@TestPropertySource`. In the next example, the `timezone` and `port` properties and any properties defined in @@ -191,7 +191,7 @@ set to `false`, the locations or inlined properties, respectively, for the test shadow and effectively replace the configuration defined by superclasses. NOTE: As of Spring Framework 5.3, test configuration may also be inherited from enclosing -classes. See <> for details. +classes. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-nested-test-configuration[`@Nested` test class configuration] for details. In the next example, the `ApplicationContext` for `BaseTest` is loaded by using only the `base.properties` file as a test property source. In contrast, the `ApplicationContext` diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc index bd5a31d226..9908886253 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/ctx-management/web-mocks.adoc @@ -3,7 +3,7 @@ To provide comprehensive web testing support, the TestContext framework has a `ServletTestExecutionListener` that is enabled by default. When testing against a -`WebApplicationContext`, this <> +`WebApplicationContext`, this xref:testing/testcontext-framework/key-abstractions.adoc[`TestExecutionListener`] sets up default thread-local state by using Spring Web's `RequestContextHolder` before each test method and creates a `MockHttpServletRequest`, a `MockHttpServletResponse`, and a `ServletWebRequest` based on the base resource path configured with diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc index c09002d9a6..bfb5100453 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/executing-sql.adoc @@ -5,9 +5,9 @@ When writing integration tests against a relational database, it is often benefi run SQL scripts to modify the database schema or insert test data into tables. The `spring-jdbc` module provides support for _initializing_ an embedded or existing database by executing SQL scripts when the Spring `ApplicationContext` is loaded. See -<> and -<> for details. +xref:data-access/jdbc/embedded-database-support.adoc[Embedded database support] and +xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-dao-testing[Testing data access logic with an embedded database] + for details. Although it is very useful to initialize a database for testing _once_ when the `ApplicationContext` is loaded, sometimes it is essential to be able to modify the @@ -77,8 +77,8 @@ specifies SQL scripts for a test schema and test data, sets the statement separa Note that `ResourceDatabasePopulator` internally delegates to `ScriptUtils` for parsing and running SQL scripts. Similarly, the `executeSqlScript(..)` methods in -<> -and <> +xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-junit4[`AbstractTransactionalJUnit4SpringContextTests`] +and xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-testng[`AbstractTransactionalTestNGSpringContextTests`] internally use a `ResourceDatabasePopulator` to run SQL scripts. See the Javadoc for the various `executeSqlScript(..)` methods for further details. @@ -95,7 +95,7 @@ run against a given database before or after an integration test method. Support NOTE: Method-level `@Sql` declarations override class-level declarations by default. As of Spring Framework 5.2, however, this behavior may be configured per test class or per test method via `@SqlMergeMode`. See -<> for further details. +xref:testing/testcontext-framework/executing-sql.adoc#testcontext-executing-sql-declaratively-script-merging[Merging and Overriding Configuration with `@SqlMergeMode`] for further details. [[testcontext-executing-sql-declaratively-script-resources]] === Path Resource Semantics @@ -382,7 +382,7 @@ that uses JUnit Jupiter and transactional tests with `@Sql`: Note that there is no need to clean up the database after the `usersTest()` method is run, since any changes made to the database (either within the test method or within the `/test-data.sql` script) are automatically rolled back by the -`TransactionalTestExecutionListener` (see <> for +`TransactionalTestExecutionListener` (see xref:testing/testcontext-framework/tx.adoc[transaction management] for details). [[testcontext-executing-sql-declaratively-script-merging]] @@ -394,7 +394,7 @@ database schema or some common test data once per test class and then provide ad use case specific test data per test method. To enable `@Sql` merging, annotate either your test class or test method with `@SqlMergeMode(MERGE)`. To disable merging for a specific test method (or specific test subclass), you can switch back to the default mode -via `@SqlMergeMode(OVERRIDE)`. Consult the <> for examples and further details. +via `@SqlMergeMode(OVERRIDE)`. Consult the xref:testing/annotations/integration-spring/annotation-sqlmergemode.adoc[`@SqlMergeMode` annotation documentation section] + for examples and further details. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc index e42242d68b..2951d0430d 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/fixture-di.adoc @@ -7,7 +7,7 @@ application context that you configured with `@ContextConfiguration` or related annotations. You may use setter injection, field injection, or both, depending on which annotations you choose and whether you place them on setter methods or fields. If you are using JUnit Jupiter you may also optionally use constructor injection -(see <>). For consistency with Spring's annotation-based +(see xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-di[Dependency Injection with `SpringExtension`]). For consistency with Spring's annotation-based injection support, you may also use Spring's `@Autowired` annotation or the `@Inject` annotation from JSR-330 for field and setter injection. @@ -20,8 +20,8 @@ actually quite natural in test code. The rationale for the difference is that yo never instantiate your test class directly. Consequently, there is no need to be able to invoke a `public` constructor or setter method on your test class. -Because `@Autowired` is used to perform <>, if you have multiple bean definitions of the same type, you cannot rely on this +Because `@Autowired` is used to perform xref:core/beans/dependencies/factory-autowire.adoc[autowiring by type] +, if you have multiple bean definitions of the same type, you cannot rely on this approach for those particular beans. In that case, you can use `@Autowired` in conjunction with `@Qualifier`. You can also choose to use `@Inject` in conjunction with `@Named`. Alternatively, if your test class has access to its `ApplicationContext`, you @@ -35,7 +35,7 @@ dependency injection altogether by explicitly configuring your class with from the list of listeners. Consider the scenario of testing a `HibernateTitleRepository` class, as outlined in the -<> section. The next two code listings demonstrate the +xref:testing/integration.adoc#integration-testing-goals[Goals] section. The next two code listings demonstrate the use of `@Autowired` on fields and setter methods. The application context configuration is presented after all sample code listings. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc index 7a36013910..04e5e9ce4a 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/key-abstractions.adoc @@ -40,7 +40,7 @@ responsible for managing a single `TestContext` and signaling events to each reg == `TestExecutionListener` `TestExecutionListener` defines the API for reacting to test-execution events published by -the `TestContextManager` with which the listener is registered. See <>. +the `TestContextManager` with which the listener is registered. See xref:testing/testcontext-framework/tel-config.adoc[`TestExecutionListener` Configuration]. [[context-loaders]] == Context Loaders diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc index dfa8b13add..1a3c642f62 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/parallel-test-execution.adoc @@ -34,7 +34,7 @@ This may be due to the use of `@DirtiesContext` or due to automatic eviction fro `ContextCache`. If `@DirtiesContext` is the culprit, you either need to find a way to avoid using `@DirtiesContext` or exclude such tests from parallel execution. If the maximum size of the `ContextCache` has been exceeded, you can increase the maximum size -of the cache. See the discussion on <> +of the cache. See the discussion on xref:testing/testcontext-framework/ctx-management/caching.adoc[context caching] for details. ==== diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc index 543ee423e1..ae9aa71b1b 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc @@ -15,7 +15,7 @@ loading application contexts, dependency injection of test instances, transactio method execution, and so on. If you want to use the Spring TestContext Framework with an alternative runner (such as JUnit 4's `Parameterized` runner) or third-party runners (such as the `MockitoJUnitRunner`), you can, optionally, use -<> instead. +xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules[Spring's support for JUnit rules] instead. The following code listing shows the minimal requirements for configuring a test class to run with the custom Spring `Runner`: @@ -140,8 +140,8 @@ extend `AbstractTransactionalJUnit4SpringContextTests`, you can access a `protec database. You can use such queries to confirm database state both before and after running database-related application code, and Spring ensures that such queries run in the scope of the same transaction as the application code. When used in conjunction with -an ORM tool, be sure to avoid <>. -As mentioned in <>, +an ORM tool, be sure to avoid xref:testing/testcontext-framework/tx.adoc#testcontext-tx-false-positives[false positives]. +As mentioned in xref:testing/support-jdbc.adoc[JDBC Testing Support], `AbstractTransactionalJUnit4SpringContextTests` also provides convenience methods that delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`. Furthermore, `AbstractTransactionalJUnit4SpringContextTests` provides an @@ -149,8 +149,8 @@ Furthermore, `AbstractTransactionalJUnit4SpringContextTests` provides an TIP: These classes are a convenience for extension. If you do not want your test classes to be tied to a Spring-specific class hierarchy, you can configure your own custom test -classes by using `@RunWith(SpringRunner.class)` or <>. +classes by using `@RunWith(SpringRunner.class)` or xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit4-rules[Spring's JUnit rules] +. [[testcontext-junit-jupiter-extension]] == SpringExtension for JUnit Jupiter @@ -167,14 +167,14 @@ following features above and beyond the feature set that Spring supports for JUn TestNG: * Dependency injection for test constructors, test methods, and test lifecycle callback - methods. See <> for further details. + methods. See xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-di[Dependency Injection with `SpringExtension`] for further details. * Powerful support for link:https://junit.org/junit5/docs/current/user-guide/#extensions-conditions[conditional test execution] based on SpEL expressions, environment variables, system properties, and so on. See the documentation for `@EnabledIf` and `@DisabledIf` in - <> for further details and examples. + xref:testing/annotations/integration-junit-jupiter.adoc[Spring JUnit Jupiter Testing Annotations] for further details and examples. * Custom composed annotations that combine annotations from Spring and JUnit Jupiter. See the `@TransactionalDevTestConfig` and `@TransactionalIntegrationTest` examples in - <> for further details. + xref:testing/annotations/integration-meta.adoc[Meta-Annotation Support for Testing] for further details. The following code listing shows how to configure a test class to use the `SpringExtension` in conjunction with `@ContextConfiguration`: @@ -282,7 +282,7 @@ Similarly, the following example uses `@SpringJUnitWebConfig` to create a ---- See the documentation for `@SpringJUnitConfig` and `@SpringJUnitWebConfig` in -<> for further details. +xref:testing/annotations/integration-junit-jupiter.adoc[Spring JUnit Jupiter Testing Annotations] for further details. [[testcontext-junit-jupiter-di]] === Dependency Injection with `SpringExtension` @@ -314,7 +314,7 @@ autowirable if one of the following conditions is met (in order of precedence). attribute set to `ALL`. * The default _test constructor autowire mode_ has been changed to `ALL`. -See <> for details on the use of +See xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`] for details on the use of `@TestConstructor` and how to change the global _test constructor autowire mode_. WARNING: If the constructor for a test class is considered to be _autowirable_, Spring @@ -375,7 +375,7 @@ In the following example, Spring injects the `OrderService` bean from the Note that this feature lets test dependencies be `final` and therefore immutable. If the `spring.test.constructor.autowire.mode` property is to `all` (see -<>), we can omit the declaration of +xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`]), we can omit the declaration of `@Autowired` on the constructor in the previous example, resulting in the following. [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -502,16 +502,16 @@ recursively. In order to allow development teams to change the default to `OVERRIDE` – for example, for compatibility with Spring Framework 5.0 through 5.2 – the default mode can be changed globally via a JVM system property or a `spring.properties` file in the root of the -classpath. See the <> note for details. +classpath. See the xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration["Changing the default enclosing configuration inheritance mode"] + note for details. Although the following "Hello World" example is very simplistic, it shows how to declare common configuration on a top-level class that is inherited by its `@Nested` test classes. In this particular example, only the `TestConfig` configuration class is inherited. Each nested test class provides its own set of active profiles, resulting in a distinct `ApplicationContext` for each nested test class (see -<> for details). Consult the list of -<> to see +xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching] for details). Consult the list of +xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[supported annotations] to see which annotations can be inherited in `@Nested` test classes. [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -594,8 +594,8 @@ extend `AbstractTransactionalTestNGSpringContextTests`, you can access a `protec database. You can use such queries to confirm database state both before and after running database-related application code, and Spring ensures that such queries run in the scope of the same transaction as the application code. When used in conjunction with -an ORM tool, be sure to avoid <>. -As mentioned in <>, +an ORM tool, be sure to avoid xref:testing/testcontext-framework/tx.adoc#testcontext-tx-false-positives[false positives]. +As mentioned in xref:testing/support-jdbc.adoc[JDBC Testing Support], `AbstractTransactionalTestNGSpringContextTests` also provides convenience methods that delegate to methods in `JdbcTestUtils` by using the aforementioned `jdbcTemplate`. Furthermore, `AbstractTransactionalTestNGSpringContextTests` provides an diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc index cb6856f261..6b255cb59b 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc @@ -9,7 +9,7 @@ by default, exactly in the following order: * `DirtiesContextBeforeModesTestExecutionListener`: Handles the `@DirtiesContext` annotation for "`before`" modes. * `ApplicationEventsTestExecutionListener`: Provides support for - <>. + xref:testing/testcontext-framework/application-events.adoc[`ApplicationEvents`]. * `DependencyInjectionTestExecutionListener`: Provides dependency injection for the test instance. * `DirtiesContextTestExecutionListener`: Handles the `@DirtiesContext` annotation for @@ -19,14 +19,14 @@ by default, exactly in the following order: * `SqlScriptsTestExecutionListener`: Runs SQL scripts configured by using the `@Sql` annotation. * `EventPublishingTestExecutionListener`: Publishes test execution events to the test's - `ApplicationContext` (see <>). + `ApplicationContext` (see xref:testing/testcontext-framework/test-execution-events.adoc[Test Execution Events]). [[testcontext-tel-config-registering-tels]] == Registering `TestExecutionListener` Implementations You can register `TestExecutionListener` implementations explicitly for a test class, its subclasses, and its nested classes by using the `@TestExecutionListeners` annotation. See -<> and the javadoc for +xref:testing/annotations.adoc[annotation support] and the javadoc for {api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners`] for details and examples. @@ -84,7 +84,7 @@ file. == Ordering `TestExecutionListener` Implementations When the TestContext framework discovers default `TestExecutionListener` implementations -through the <> +through the xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-automatic-discovery[aforementioned] `SpringFactoriesLoader` mechanism, the instantiated listeners are sorted by using Spring's `AnnotationAwareOrderComparator`, which honors Spring's `Ordered` interface and `@Order` annotation for ordering. `AbstractTestExecutionListener` and all default @@ -145,15 +145,15 @@ change from release to release -- for example, `SqlScriptsTestExecutionListener` introduced in Spring Framework 4.1, and `DirtiesContextBeforeModesTestExecutionListener` was introduced in Spring Framework 4.2. Furthermore, third-party frameworks like Spring Boot and Spring Security register their own default `TestExecutionListener` -implementations by using the aforementioned <>. +implementations by using the aforementioned xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-automatic-discovery[automatic discovery mechanism] +. To avoid having to be aware of and re-declare all default listeners, you can set the `mergeMode` attribute of `@TestExecutionListeners` to `MergeMode.MERGE_WITH_DEFAULTS`. `MERGE_WITH_DEFAULTS` indicates that locally declared listeners should be merged with the default listeners. The merging algorithm ensures that duplicates are removed from the list and that the resulting set of merged listeners is sorted according to the semantics -of `AnnotationAwareOrderComparator`, as described in <>. +of `AnnotationAwareOrderComparator`, as described in xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-ordering[Ordering `TestExecutionListener` Implementations]. If a listener implements `Ordered` or is annotated with `@Order`, it can influence the position in which it is merged with the defaults. Otherwise, locally declared listeners are appended to the list of default listeners when merged. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc index 73dda5f70c..b83c127367 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/test-execution-events.adoc @@ -52,7 +52,7 @@ In order to listen to test execution events, a Spring bean may choose to impleme `org.springframework.context.ApplicationListener` interface. Alternatively, listener methods can be annotated with `@EventListener` and configured to listen to one of the particular event types listed above (see -<>). +xref:core/beans/context-introduction.adoc#context-functionality-events-annotation[Annotation-based Event Listeners]). Due to the popularity of this approach, Spring provides the following dedicated `@EventListener` annotations to simplify registration of test execution event listeners. These annotations reside in the `org.springframework.test.context.event.annotation` @@ -81,8 +81,8 @@ asynchronous exception handling, consult the class-level javadoc for `@EventList == Asynchronous Listeners If you want a particular test execution event listener to process events asynchronously, -you can use Spring's <>. For further details, consult the class-level javadoc for +you can use Spring's xref:integration/scheduling.adoc#scheduling-annotation-support-async[regular `@Async` support] +. For further details, consult the class-level javadoc for `@EventListener`. diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc index 72e7470342..babf258e0f 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/tx.adoc @@ -21,7 +21,7 @@ application code that is invoked by tests). Spring-managed and application-manag transactions typically participate in test-managed transactions. However, you should use caution if Spring-managed or application-managed transactions are configured with any propagation type other than `REQUIRED` or `SUPPORTS` (see the discussion on -<> for details). +xref:data-access/transaction/declarative/tx-propagation.adoc[transaction propagation] for details). .Preemptive timeouts and test-managed transactions [WARNING] @@ -94,9 +94,9 @@ your test class and then use that with a `TransactionTemplate` for programmatic transaction management. ==== -Note that <> and -<> +Note that xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-junit4[`AbstractTransactionalJUnit4SpringContextTests`] + and +xref:testing/testcontext-framework/support-classes.adoc#testcontext-support-classes-testng[`AbstractTransactionalTestNGSpringContextTests`] are preconfigured for transactional support at the class level. The following example demonstrates a common scenario for writing an integration test for @@ -188,7 +188,7 @@ a Hibernate-based `UserRepository`: } ---- -As explained in <>, there is no need to +As explained in xref:testing/testcontext-framework/tx.adoc#testcontext-tx-rollback-and-commit-behavior[Transaction Rollback and Commit Behavior], there is no need to clean up the database after the `createUser()` method runs, since any changes made to the database are automatically rolled back by the `TransactionalTestExecutionListener`. @@ -198,7 +198,7 @@ database are automatically rolled back by the `TransactionalTestExecutionListene By default, test transactions will be automatically rolled back after completion of the test; however, transactional commit and rollback behavior can be configured declaratively via the `@Commit` and `@Rollback` annotations. See the corresponding entries in the -<> section for further details. +xref:testing/annotations.adoc[annotation support] section for further details. [[testcontext-tx-programmatic-tx-mgt]] == Programmatic Transaction Management @@ -312,9 +312,9 @@ algorithm used to look up a transaction manager in the test's `ApplicationContex The following JUnit Jupiter based example displays a fictitious integration testing scenario that highlights all transaction-related annotations. The example is not intended to demonstrate best practices but rather to demonstrate how these annotations can be -used. See the <> section for further -information and configuration examples. <> contains an additional example that uses `@Sql` for +used. See the xref:testing/annotations.adoc[annotation support] section for further +information and configuration examples. xref:testing/testcontext-framework/executing-sql.adoc#testcontext-executing-sql-declaratively-tx[Transaction management for `@Sql`] + contains an additional example that uses `@Sql` for declarative SQL script execution with default transaction rollback semantics. The following example shows the relevant annotations: @@ -521,7 +521,7 @@ The following example shows matching methods for JPA: .Testing ORM entity lifecycle callbacks [NOTE] ===== -Similar to the note about avoiding <> +Similar to the note about avoiding xref:testing/testcontext-framework/tx.adoc#testcontext-tx-false-positives[false positives] when testing ORM code, if your application makes use of entity lifecycle callbacks (also known as entity listeners), make sure to flush the underlying unit of work within test methods that run that code. Failing to _flush_ or _clear_ the underlying unit of work can diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc index fd70310f11..5c87d206a1 100644 --- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc +++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/web-scoped-beans.adoc @@ -1,8 +1,8 @@ [[testcontext-web-scoped-beans]] = Testing Request- and Session-scoped Beans -Spring has supported <> since the early years, and you can test your request-scoped and session-scoped +Spring has supported xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other[Request- and session-scoped beans] + since the early years, and you can test your request-scoped and session-scoped beans by following these steps: * Ensure that a `WebApplicationContext` is loaded for your test by annotating your test @@ -15,7 +15,7 @@ beans by following these steps: The next code snippet shows the XML configuration for a login use case. Note that the `userService` bean has a dependency on a request-scoped `loginAction` bean. Also, the -`LoginAction` is instantiated by using <> that +`LoginAction` is instantiated by using xref:core/expressions.adoc[SpEL expressions] that retrieve the username and password from the current HTTP request. In our test, we want to configure these request parameters through the mock managed by the TestContext framework. The following listing shows the configuration for this use case: diff --git a/framework-docs/modules/ROOT/pages/testing/unit.adoc b/framework-docs/modules/ROOT/pages/testing/unit.adoc index 6a3cbe0275..f137331a51 100644 --- a/framework-docs/modules/ROOT/pages/testing/unit.adoc +++ b/framework-docs/modules/ROOT/pages/testing/unit.adoc @@ -4,7 +4,7 @@ Dependency injection should make your code less dependent on the container than it would be with traditional J2EE / Java EE development. The POJOs that make up your application should be testable in JUnit or TestNG tests, with objects instantiated by using the `new` -operator, without Spring or any other container. You can use <> +operator, without Spring or any other container. You can use xref:testing/unit.adoc#mock-objects[mock objects] (in conjunction with other valuable testing techniques) to test your code in isolation. If you follow the architecture recommendations for Spring, the resulting clean layering and componentization of your codebase facilitate easier unit testing. For example, @@ -25,10 +25,10 @@ are described in this chapter. Spring includes a number of packages dedicated to mocking: -* <> -* <> -* <> -* <> +* xref:testing/unit.adoc#mock-objects-env[Environment] +* xref:testing/unit.adoc#mock-objects-jndi[JNDI] +* xref:testing/unit.adoc#mock-objects-servlet[Servlet API] +* xref:testing/unit.adoc#mock-objects-web-reactive[Spring Web Reactive] [[mock-objects-env]] @@ -36,8 +36,8 @@ Spring includes a number of packages dedicated to mocking: The `org.springframework.mock.env` package contains mock implementations of the `Environment` and `PropertySource` abstractions (see -<> -and <>). +xref:core/beans/environment.adoc#beans-definition-profiles[Bean Definition Profiles] +and xref:core/beans/environment.adoc#beans-property-source-abstraction[`PropertySource` Abstraction]). `MockEnvironment` and `MockPropertySource` are useful for developing out-of-container tests for code that depends on environment-specific properties. @@ -69,7 +69,7 @@ TIP: Since Spring Framework 6.0, the mock objects in `org.springframework.mock.w based on the Servlet 6.0 API. The Spring MVC Test framework builds on the mock Servlet API objects to provide an -integration testing framework for Spring MVC. See <>. +integration testing framework for Spring MVC. See xref:testing/spring-mvc-test-framework.adoc[MockMvc]. [[mock-objects-web-reactive]] @@ -90,7 +90,7 @@ write completion handle (that is, `Mono`), it by default uses a `Flux` wit `cache().then()`, which buffers the data and makes it available for assertions in tests. Applications can set a custom write function (for example, to test an infinite stream). -The <> builds on the mock request and response to provide support for +The xref:testing/webtestclient.adoc[WebTestClient] builds on the mock request and response to provide support for testing WebFlux applications without an HTTP server. The client can also be used for end-to-end tests with a running server. @@ -102,8 +102,8 @@ end-to-end tests with a running server. Spring includes a number of classes that can help with unit testing. They fall into two categories: -* <> -* <> +* xref:testing/unit.adoc#unit-testing-utilities[General Testing Utilities] +* xref:testing/unit.adoc#unit-testing-spring-mvc[Spring MVC Testing Utilities] [[unit-testing-utilities]] @@ -162,7 +162,7 @@ that deal with Spring MVC `ModelAndView` objects. .Unit testing Spring MVC Controllers TIP: To unit test your Spring MVC `Controller` classes as POJOs, use `ModelAndViewAssert` combined with `MockHttpServletRequest`, `MockHttpSession`, and so on from Spring's -<>. For thorough integration testing of your +xref:testing/unit.adoc#mock-objects-servlet[Servlet API mocks]. For thorough integration testing of your Spring MVC and REST `Controller` classes in conjunction with your `WebApplicationContext` configuration for Spring MVC, use the -<> instead. +xref:testing/spring-mvc-test-framework.adoc[Spring MVC Test Framework] instead. diff --git a/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc index 4335760e10..f5f1cab0a7 100644 --- a/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc +++ b/framework-docs/modules/ROOT/pages/testing/webtestclient.adoc @@ -2,12 +2,12 @@ = WebTestClient `WebTestClient` is an HTTP client designed for testing server applications. It wraps -Spring's <> and uses it to perform requests +Spring's xref:web/webflux-webclient.adoc[WebClient] and uses it to perform requests but exposes a testing facade for verifying responses. `WebTestClient` can be used to perform end-to-end HTTP tests. It can also be used to test Spring MVC and Spring WebFlux applications without a running server via mock server request and response objects. -TIP: Kotlin users: See <> +TIP: Kotlin users: See xref:languages/kotlin/spring-projects-in.adoc#kotlin-webtestclient-issue[this section] related to use of the `WebTestClient`. @@ -28,8 +28,8 @@ This setup allows you to test specific controller(s) via mock request and respon without a running server. For WebFlux applications, use the following which loads infrastructure equivalent to the -<>, registers the given -controller(s), and creates a <> +xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Java config], registers the given +controller(s), and creates a xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[WebHandler chain] to handle requests: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -46,9 +46,9 @@ to handle requests: For Spring MVC, use the following which delegates to the {api-spring-framework}/test/web/servlet/setup/StandaloneMockMvcBuilder.html[StandaloneMockMvcBuilder] -to load infrastructure equivalent to the <>, +to load infrastructure equivalent to the xref:web/webmvc/mvc-config.adoc[WebMvc Java config], registers the given controller(s), and creates an instance of -<> to handle requests: +xref:testing/spring-mvc-test-framework.adoc[MockMvc] to handle requests: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -73,7 +73,7 @@ and response objects, without a running server. For WebFlux, use the following where the Spring `ApplicationContext` is passed to {api-spring-framework}/web/server/adapter/WebHttpHandlerBuilder.html#applicationContext-org.springframework.context.ApplicationContext-[WebHttpHandlerBuilder] -to create the <> to handle +to create the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[WebHandler chain] to handle requests: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -114,7 +114,7 @@ requests: For Spring MVC, use the following where the Spring `ApplicationContext` is passed to {api-spring-framework}/test/web/servlet/setup/MockMvcBuilders.html#webAppContextSetup-org.springframework.web.context.WebApplicationContext-[MockMvcBuilders.webAppContextSetup] -to create a <> instance to handle +to create a xref:testing/spring-mvc-test-framework.adoc[MockMvc] instance to handle requests: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -194,7 +194,7 @@ create a server setup to handle requests: ---- For Spring MVC there are currently no options to test -<>. +xref:web/webmvc-functional.adoc[WebMvc functional endpoints]. @@ -248,9 +248,9 @@ follows: [[webtestclient-tests]] == Writing Tests -`WebTestClient` provides an API identical to <> +`WebTestClient` provides an API identical to xref:web/webflux-webclient.adoc[WebClient] up to the point of performing a request by using `exchange()`. See the -<> documentation for examples on how to +xref:web/webflux-webclient/client-body.adoc[WebClient] documentation for examples on how to prepare a request with any content including form data, multipart data, and more. After the call to `exchange()`, `WebTestClient` diverges from the `WebClient` and @@ -298,7 +298,7 @@ You can then choose to decode the response body through one of the following: * `expectBody(Class)`: Decode to single object. * `expectBodyList(Class)`: Decode and collect objects to `List`. -* `expectBody()`: Decode to `byte[]` for <> or an empty body. +* `expectBody()`: Decode to `byte[]` for xref:testing/webtestclient.adoc#webtestclient-json[JSON Content] or an empty body. And perform assertions on the resulting higher level Object(s): diff --git a/framework-docs/modules/ROOT/pages/web-reactive.adoc b/framework-docs/modules/ROOT/pages/web-reactive.adoc index 01d6cc8c55..4fc5fbe565 100644 --- a/framework-docs/modules/ROOT/pages/web-reactive.adoc +++ b/framework-docs/modules/ROOT/pages/web-reactive.adoc @@ -4,10 +4,10 @@ This part of the documentation covers support for reactive-stack web applications built on a https://www.reactive-streams.org/[Reactive Streams] API to run on non-blocking servers, such as Netty, Undertow, and Servlet containers. Individual chapters cover -the <> framework, -the reactive <>, support for <>, -and <>. For Servlet-stack web applications, -see <>. +the xref:web/webflux.adoc#webflux[Spring WebFlux] framework, +the reactive xref:web/webflux-webclient.adoc[`WebClient`], support for xref:web-reactive.adoc#webflux-test[testing], +and xref:web-reactive.adoc#webflux-reactive-libraries[reactive libraries]. For Servlet-stack web applications, +see xref:web.adoc[Web on Servlet Stack]. @@ -20,7 +20,7 @@ exchange methods. You can then generate a proxy that implements this interface a performs the exchanges. This helps to simplify HTTP remote access and provides additional flexibility for to choose an API style such as synchronous or reactive. -See <> for details. +See xref:integration/rest-clients.adoc#rest-http-interface[REST Endpoints] for details. @@ -28,14 +28,14 @@ See <> for details. [[webflux-test]] == Testing -[.small]#<># +[.small]#xref:web/webmvc-test.adoc[Same in Spring MVC]# The `spring-test` module provides mock implementations of `ServerHttpRequest`, `ServerHttpResponse`, and `ServerWebExchange`. -See <> for a +See xref:testing/unit.adoc#mock-objects-web-reactive[Spring Web Reactive] for a discussion of mock objects. -<> builds on these mock request and +xref:testing/webtestclient.adoc[`WebTestClient`] builds on these mock request and response objects to provide support for testing WebFlux applications without an HTTP server. You can use the `WebTestClient` for end-to-end integration tests, too. diff --git a/framework-docs/modules/ROOT/pages/web.adoc b/framework-docs/modules/ROOT/pages/web.adoc index 2772fc3508..2cfb7be73e 100644 --- a/framework-docs/modules/ROOT/pages/web.adoc +++ b/framework-docs/modules/ROOT/pages/web.adoc @@ -2,9 +2,9 @@ = Web on Servlet Stack This part of the documentation covers support for Servlet-stack web applications built on the -Servlet API and deployed to Servlet containers. Individual chapters include <>, -<>, <>, and <>. -For reactive-stack web applications, see <>. +Servlet API and deployed to Servlet containers. Individual chapters include xref:web/webmvc.adoc#mvc[Spring MVC], +xref:web/webmvc-view.adoc[View Technologies], xref:web/webmvc-cors.adoc[CORS Support], and xref:web/websocket.adoc[WebSocket Support]. +For reactive-stack web applications, see xref:testing/unit.adoc#mock-objects-web-reactive[Web on Reactive Stack]. diff --git a/framework-docs/modules/ROOT/pages/web/integration.adoc b/framework-docs/modules/ROOT/pages/web/integration.adoc index 5fdd1595dd..6d362d916a 100644 --- a/framework-docs/modules/ROOT/pages/web/integration.adoc +++ b/framework-docs/modules/ROOT/pages/web/integration.adoc @@ -9,7 +9,7 @@ particular architecture, technology, or methodology (although it certainly recom some over others). This freedom to pick and choose the architecture, technology, or methodology that is most relevant to a developer and their development team is arguably most evident in the web area, where Spring provides its own web frameworks -(<> and <>) while, at the same time, +(xref:web/webmvc.adoc#mvc[Spring MVC] and xref:web/webflux.adoc#webflux[Spring WebFlux]) while, at the same time, supporting integration with a number of popular third-party web frameworks. @@ -178,7 +178,7 @@ https://struts.apache.org/plugins/spring/[Spring Plugin] for built-in Spring int https://tapestry.apache.org/[Tapestry] is a "Component oriented framework for creating dynamic, robust, highly scalable web applications in Java." -While Spring has its own <>, there are a number of unique +While Spring has its own xref:web/webmvc.adoc#mvc[powerful web layer], there are a number of unique advantages to building an enterprise Java application by using a combination of Tapestry for the web user interface and the Spring container for the lower layers. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc index b8805e226a..8ee097700d 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-cors.adoc @@ -1,6 +1,6 @@ [[webflux-cors]] = CORS -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc[See equivalent in the Servlet stack]# Spring WebFlux lets you handle CORS (Cross-Origin Resource Sharing). This section describes how to do so. @@ -10,7 +10,7 @@ describes how to do so. [[webflux-cors-intro]] == Introduction -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-intro[See equivalent in the Servlet stack]# For security reasons, browsers prohibit AJAX calls to resources outside the current origin. For example, you could have your bank account in one tab and evil.com in another. Scripts @@ -27,7 +27,7 @@ powerful workarounds based on IFRAME or JSONP. [[webflux-cors-processing]] == Processing -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-processing[See equivalent in the Servlet stack]# The CORS specification distinguishes between preflight, simple, and actual requests. To learn how CORS works, you can read @@ -77,7 +77,7 @@ To learn more from the source or to make advanced customizations, see: [[webflux-cors-controller]] == `@CrossOrigin` -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-controller[See equivalent in the Servlet stack]# The {api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] annotation enables cross-origin requests on annotated controller methods, as the @@ -237,7 +237,7 @@ as the following example shows: [[webflux-cors-global]] == Global Configuration -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-global[See equivalent in the Servlet stack]# In addition to fine-grained, controller method-level configuration, you probably want to define some global CORS configuration, too. You can set URL-based `CorsConfiguration` @@ -308,7 +308,7 @@ as the following example shows: [[webflux-cors-webfilter]] == CORS `WebFilter` -[.small]#<># +[.small]#xref:web/webmvc-cors.adoc#mvc-cors-filter[See equivalent in the Servlet stack]# You can apply CORS support through the built-in {api-spring-framework}/web/cors/reactive/CorsWebFilter.html[`CorsWebFilter`], which is a diff --git a/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc index 882c68200d..daba67c290 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-functional.adoc @@ -1,18 +1,18 @@ [[webflux-fn]] = Functional Endpoints -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc[See equivalent in the Servlet stack]# Spring WebFlux includes WebFlux.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. It is an alternative to the annotation-based programming model but otherwise runs on -the same <> foundation. +the same xref:web/webflux/reactive-spring.adoc[Reactive Core] foundation. [[webflux-fn-overview]] == Overview -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-overview[See equivalent in the Servlet stack]# In WebFlux.fn, an HTTP request is handled with a `HandlerFunction`: a function that takes `ServerRequest` and returns a delayed `ServerResponse` (i.e. `Mono`). @@ -101,19 +101,19 @@ as the following example shows: <1> Create router using Coroutines router DSL; a Reactive alternative is also available via `router { }`. One way to run a `RouterFunction` is to turn it into an `HttpHandler` and install it -through one of the built-in <>: +through one of the built-in xref:web/webflux/reactive-spring.adoc#webflux-httphandler[server adapters]: * `RouterFunctions.toHttpHandler(RouterFunction)` * `RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)` -Most applications can run through the WebFlux Java configuration, see <>. +Most applications can run through the WebFlux Java configuration, see xref:web/webflux-functional.adoc#webflux-fn-running[Running a Server]. [[webflux-fn-handler-functions]] == HandlerFunction -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-handler-functions[See equivalent in the Servlet stack]# `ServerRequest` and `ServerResponse` are immutable interfaces that offer JDK 8-friendly access to the HTTP request and response. @@ -121,7 +121,7 @@ Both request and response provide https://www.reactive-streams.org[Reactive Stre against the body streams. The request body is represented with a Reactor `Flux` or `Mono`. The response body is represented with any Reactive Streams `Publisher`, including `Flux` and `Mono`. -For more on that, see <>. +For more on that, see xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries]. @@ -418,9 +418,9 @@ found. If it is not found, we return a 404 Not Found response. [[webflux-fn-handler-validation]] === Validation -A functional endpoint can use Spring's <> to +A functional endpoint can use Spring's xref:web/webmvc/mvc-config/validation.adoc[validation facilities] to apply validation to the request body. For example, given a custom Spring -<> implementation for a `Person`: +xref:web/webmvc/mvc-config/validation.adoc[Validator] implementation for a `Person`: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -480,13 +480,13 @@ apply validation to the request body. For example, given a custom Spring Handlers can also use the standard bean validation API (JSR-303) by creating and injecting a global `Validator` instance based on `LocalValidatorFactoryBean`. -See <>. +See xref:core/validation/beanvalidation.adoc[Spring Validation]. [[webflux-fn-router-functions]] == `RouterFunction` -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-router-functions[See equivalent in the Servlet stack]# Router functions are used to route the requests to the corresponding `HandlerFunction`. Typically, you do not write router functions yourself, but rather use a method on the @@ -688,7 +688,7 @@ We can further improve by using the `nest` method together with `accept`: [[webflux-fn-running]] == Running a Server -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-running[See equivalent in the Servlet stack]# How do you run a router function in an HTTP server? A simple option is to convert a router function to an `HttpHandler` by using one of the following: @@ -697,16 +697,16 @@ function to an `HttpHandler` by using one of the following: * `RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)` You can then use the returned `HttpHandler` with a number of server adapters by following -<> for server-specific instructions. +xref:web/webflux/reactive-spring.adoc#webflux-httphandler[HttpHandler] for server-specific instructions. A more typical option, also used by Spring Boot, is to run with a -<>-based setup through the -<>, which uses Spring configuration to declare the +xref:web/webflux/dispatcher-handler.adoc[`DispatcherHandler`]-based setup through the +xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config], which uses Spring configuration to declare the components required to process requests. The WebFlux Java configuration declares the following infrastructure components to support functional endpoints: * `RouterFunctionMapping`: Detects one or more `RouterFunction` beans in the Spring -configuration, <>, combines them through +configuration, xref:core/beans/annotation-config/autowired.adoc#beans-factory-ordered[orders them], combines them through `RouterFunction.andOther`, and routes requests to the resulting composed `RouterFunction`. * `HandlerFunctionAdapter`: Simple adapter that lets `DispatcherHandler` invoke a `HandlerFunction` that was mapped to a request. @@ -719,7 +719,7 @@ any are declared. It is also how functional endpoints are enabled by the Spring starter. The following example shows a WebFlux Java configuration (see -<> for how to run it): +xref:web/webflux/dispatcher-handler.adoc[DispatcherHandler] for how to run it): [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -794,7 +794,7 @@ The following example shows a WebFlux Java configuration (see [[webflux-fn-handler-filter-function]] == Filtering Handler Functions -[.small]#<># +[.small]#xref:web/webmvc-functional.adoc#webmvc-fn-handler-filter-function[See equivalent in the Servlet stack]# You can filter handler functions by using the `before`, `after`, or `filter` methods on the routing function builder. @@ -903,4 +903,4 @@ Besides using the `filter` method on the router function builder, it is possible filter to an existing router function via `RouterFunction.filter(HandlerFilterFunction)`. NOTE: CORS support for functional endpoints is provided through a dedicated -<>. +xref:web/webflux-cors.adoc#webflux-cors-webfilter[`CorsWebFilter`]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-view.adoc b/framework-docs/modules/ROOT/pages/web/webflux-view.adoc index 9348d3ca56..6122ef22bd 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-view.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-view.adoc @@ -1,18 +1,18 @@ [[webflux-view]] = View Technologies -[.small]#<># +[.small]#xref:web/webmvc-view.adoc[See equivalent in the Servlet stack]# The use of view technologies in Spring WebFlux is pluggable. Whether you decide to use Thymeleaf, FreeMarker, or some other view technology is primarily a matter of a configuration change. This chapter covers the view technologies integrated with Spring -WebFlux. We assume you are already familiar with <>. +WebFlux. We assume you are already familiar with xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution[View Resolution]. [[webflux-view-thymeleaf]] == Thymeleaf -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-thymeleaf.adoc[See equivalent in the Servlet stack]# Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very @@ -33,7 +33,7 @@ https://web.archive.org/web/20210623051330/http%3A//forum.thymeleaf.org/Thymelea [[webflux-view-freemarker]] == FreeMarker -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc[See equivalent in the Servlet stack]# https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any kind of text output from HTML to email and others. The Spring Framework has built-in @@ -43,7 +43,7 @@ integration for using Spring WebFlux with FreeMarker templates. [[webflux-view-freemarker-contextconfig]] === View Configuration -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-freemarker-contextconfig[See equivalent in the Servlet stack]# The following example shows how to configure FreeMarker as a view technology: @@ -98,7 +98,7 @@ returns the view name, `welcome`, the resolver looks for the [[webflux-views-freemarker]] === FreeMarker Configuration -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-freemarker[See equivalent in the Servlet stack]# You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker `Configuration` object (which is managed by Spring) by setting the appropriate bean @@ -151,7 +151,7 @@ the `Configuration` object. [[webflux-view-freemarker-forms]] === Form Handling -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-freemarker-forms[See equivalent in the Servlet stack]# Spring provides a tag library for use in JSPs that contains, among others, a `` element. This element primarily lets forms display values from @@ -162,7 +162,7 @@ with additional convenience macros for generating form input elements themselves [[webflux-view-bind-macros]] ==== The Bind Macros -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-bind-macros[See equivalent in the Servlet stack]# A standard set of macros are maintained within the `spring-webflux.jar` file for FreeMarker, so they are always available to a suitably configured application. @@ -174,8 +174,8 @@ you need to directly call from within your templates. If you wish to view the ma directly, the file is called `spring.ftl` and is in the `org.springframework.web.reactive.result.view.freemarker` package. -For additional details on binding support, see <> for Spring MVC. +For additional details on binding support, see xref:web/webmvc-view/mvc-freemarker.adoc#mvc-view-simple-binding[Simple Binding] + for Spring MVC. [[webflux-views-form-macros]] @@ -184,16 +184,16 @@ Binding>> for Spring MVC. For details on Spring's form macro support for FreeMarker templates, consult the following sections of the Spring MVC documentation. -* <> -* <> -* <> -* <> +* xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros[Input Macros] +* xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-input[Input Fields] +* xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-select[Selection Fields] +* xref:web/webmvc-view/mvc-freemarker.adoc#mvc-views-form-macros-html-escaping[HTML Escaping] [[webflux-view-script]] == Script Views -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-script.adoc[See equivalent in the Servlet stack]# The Spring Framework has a built-in integration for using Spring WebFlux with any templating library that can run on top of the @@ -219,7 +219,7 @@ TIP: The basic rule for integrating any other script engine is that it must impl [[webflux-view-script-dependencies]] === Requirements -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-script.adoc#mvc-view-script-dependencies[See equivalent in the Servlet stack]# You need to have the script engine on your classpath, the details of which vary by script engine: @@ -239,7 +239,7 @@ through https://www.webjars.org/[WebJars]. [[webflux-view-script-integrate]] === Script Templates -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-script.adoc#mvc-view-script-integrate[See equivalent in the Servlet stack]# You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, the script files to load, what function to call to render templates, and so on. @@ -389,17 +389,17 @@ for more configuration examples. [[webflux-view-httpmessagewriter]] == JSON and XML -[.small]#<># +[.small]#xref:web/webmvc-view/mvc-jackson.adoc[See equivalent in the Servlet stack]# -For <> purposes, it is useful to be able to alternate +For xref:web/webflux/dispatcher-handler.adoc#webflux-multiple-representations[Content Negotiation] purposes, it is useful to be able to alternate between rendering a model with an HTML template or as other formats (such as JSON or XML), depending on the content type requested by the client. To support doing so, Spring WebFlux provides the `HttpMessageWriterView`, which you can use to plug in any of the available -<> from `spring-web`, such as `Jackson2JsonEncoder`, `Jackson2SmileEncoder`, +xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] from `spring-web`, such as `Jackson2JsonEncoder`, `Jackson2SmileEncoder`, or `Jaxb2XmlEncoder`. Unlike other view technologies, `HttpMessageWriterView` does not require a `ViewResolver` -but is instead <> as a default view. You can +but is instead xref:web/webflux/config.adoc#webflux-config-view-resolvers[configured] as a default view. You can configure one or more such default views, wrapping different `HttpMessageWriter` instances or `Encoder` instances. The one that matches the requested content type is used at runtime. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc index 4f367cf44f..4b4a7c845b 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient.adoc @@ -2,10 +2,10 @@ = WebClient Spring WebFlux includes a client to perform HTTP requests with. `WebClient` has a -functional, fluent API based on Reactor, see <>, +functional, fluent API based on Reactor, see xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries], which enables declarative composition of asynchronous logic without the need to deal with threads or concurrency. It is fully non-blocking, it supports streaming, and relies on -the same <> that are also used to encode and +the same xref:web/webflux/reactive-spring.adoc#webflux-codecs[codecs] that are also used to encode and decode request and response content on the server side. `WebClient` needs an HTTP client library to perform requests with. There is built-in diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc index 75c4296697..608d2cc117 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-builder.adoc @@ -16,8 +16,8 @@ You can also use `WebClient.builder()` with further options: * `filter`: Client filter for every request. * `exchangeStrategies`: HTTP message reader/writer customizations. * `clientConnector`: HTTP client library settings. -* `observationRegistry`: the registry to use for enabling <>. -* `observationConvention`: <> for recorded observations. +* `observationRegistry`: the registry to use for enabling xref:integration/observability.adoc#integration.observability.http-client.webclient[Observability support]. +* `observationConvention`: xref:integration/observability.adoc#integration.observability.config[an optional, custom convention to extract metadata] for recorded observations. For example: @@ -69,7 +69,7 @@ modified copy as follows: [[webflux-client-builder-maxinmemorysize]] == MaxInMemorySize -Codecs have <> for buffering data in +Codecs have xref:web/webflux/reactive-spring.adoc#webflux-codecs-limits[limits] for buffering data in memory to avoid application memory issues. By default those are set to 256KB. If that's not enough you'll get the following error: diff --git a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc index 406f80c4de..0cb4e619b3 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-webclient/client-context.adoc @@ -1,7 +1,7 @@ [[webflux-client-context]] = Context -<> provide a convenient way to pass information to the filter +xref:web/webflux-webclient/client-attributes.adoc[Attributes] provide a convenient way to pass information to the filter chain but they only influence the current request. If you want to pass information that propagates to additional requests that are nested, e.g. via `flatMap`, or executed after, e.g. via `concatMap`, then you'll need to use the Reactor `Context`. diff --git a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc index 5e9b0e0108..e68b54067a 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux-websocket.adoc @@ -1,6 +1,6 @@ [[webflux-websocket]] = WebSockets -[.small]#<># +[.small]#xref:web/websocket.adoc[See equivalent in the Servlet stack]# This part of the reference documentation covers support for reactive-stack WebSocket messaging. @@ -11,7 +11,7 @@ messaging. [[webflux-websocket-server]] == WebSocket API -[.small]#<># +[.small]#xref:web/websocket/stomp/server-config.adoc[See equivalent in the Servlet stack]# The Spring Framework provides a WebSocket API that you can use to write client- and server-side applications that handle WebSocket messages. @@ -20,7 +20,7 @@ server-side applications that handle WebSocket messages. [[webflux-websocket-server-handler]] === Server -[.small]#<># +[.small]#xref:web/websocket/server.adoc#websocket-server-handler[See equivalent in the Servlet stack]# To create a WebSocket server, you can first create a `WebSocketHandler`. The following example shows how to do so: @@ -87,7 +87,7 @@ Then you can map it to a URL: } ---- -If using the <> there is nothing +If using the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] there is nothing further to do, or otherwise if not using the WebFlux config you'll need to declare a `WebSocketHandlerAdapter` as shown below: @@ -206,7 +206,7 @@ following example shows such an implementation: TIP: For nested, asynchronous operations, you may need to call `message.retain()` on underlying servers that use pooled data buffers (for example, Netty). Otherwise, the data buffer may be released before you have had a chance to read the data. For more background, see -<>. +xref:core/databuffer-codec.adoc[Data Buffers and Codecs]. The following implementation combines the inbound and outbound streams: @@ -325,7 +325,7 @@ as the following example shows: `DataBuffer` is the representation for a byte buffer in WebFlux. The Spring Core part of the reference has more on that in the section on -<>. The key point to understand is that on some +xref:core/databuffer-codec.adoc[Data Buffers and Codecs]. The key point to understand is that on some servers like Netty, byte buffers are pooled and reference counted, and must be released when consumed to avoid memory leaks. @@ -338,7 +338,7 @@ subsequently use `DataBufferUtils.release(dataBuffer)` when the buffers are cons [[webflux-websocket-server-handshake]] === Handshake -[.small]#<># +[.small]#xref:web/websocket/server.adoc#websocket-server-handshake[See equivalent in the Servlet stack]# `WebSocketHandlerAdapter` delegates to a `WebSocketService`. By default, that is an instance of `HandshakeWebSocketService`, which performs basic checks on the WebSocket request and @@ -353,12 +353,12 @@ into the attributes of the `WebSocketSession`. [[webflux-websocket-server-config]] === Server Configuration -[.small]#<># +[.small]#xref:web/websocket/server.adoc#websocket-server-runtime-configuration[See equivalent in the Servlet stack]# The `RequestUpgradeStrategy` for each server exposes configuration specific to the underlying WebSocket server engine. When using the WebFlux Java config you can customize such properties as shown in the corresponding section of the -<>, or otherwise if +xref:web/webflux/config.adoc#webflux-config-websocket-service[WebFlux Config], or otherwise if not using the WebFlux config, use the below: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -407,7 +407,7 @@ only Tomcat and Jetty expose such options. [[webflux-websocket-server-cors]] === CORS -[.small]#<># +[.small]#xref:web/websocket/server.adoc#websocket-server-allowed-origins[See equivalent in the Servlet stack]# The easiest way to configure CORS and restrict access to a WebSocket endpoint is to have your `WebSocketHandler` implement `CorsConfigurationSource` and return a diff --git a/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc index e46f27228f..b9e731e9b5 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/ann-rest-exceptions.adoc @@ -1,7 +1,7 @@ [[webflux-ann-rest-exceptions]] = Error Responses -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc[See equivalent in the Servlet stack]# A common requirement for REST services is to include details in the body of error responses. The Spring Framework supports the "Problem Details for HTTP APIs" @@ -18,14 +18,14 @@ exceptions implement this. - `ErrorResponseException` -- basic `ErrorResponse` implementation that others can use as a convenient base class. - `ResponseEntityExceptionHandler` -- convenient base class for an -<> that handles all Spring WebFlux exceptions, +xref:web/webflux/controller/ann-advice.adoc[@ControllerAdvice] that handles all Spring WebFlux exceptions, and any `ErrorResponseException`, and renders an error response with a body. [[webflux-ann-rest-exceptions-render]] == Render -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc#mvc-ann-rest-exceptions-render[See equivalent in the Servlet stack]# You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: @@ -39,7 +39,7 @@ and also falls back on it if no compatible media type is found. To enable RFC 7807 responses for Spring WebFlux exceptions and for any `ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an -<> in Spring configuration. The handler +xref:web/webflux/controller/ann-advice.adoc[@ControllerAdvice] in Spring configuration. The handler has an `@ExceptionHandler` method that handles any `ErrorResponse` exception, which includes all built-in web exceptions. You can add more exception handling methods, and use a protected method to map any exception to a `ProblemDetail`. @@ -48,7 +48,7 @@ use a protected method to map any exception to a `ProblemDetail`. [[webflux-ann-rest-exceptions-non-standard]] == Non-Standard Fields -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc#mvc-ann-rest-exceptions-non-standard[See equivalent in the Servlet stack]# You can extend an RFC 7807 response with non-standard fields in one of two ways. @@ -68,13 +68,13 @@ from an existing `ProblemDetail`. This could be done centrally, e.g. from an [[webflux-ann-rest-exceptions-i18n]] == Internationalization -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc#mvc-ann-rest-exceptions-i18n[See equivalent in the Servlet stack]# It is a common requirement to internationalize error response details, and good practice to customize the problem details for Spring WebFlux exceptions. This is supported as follows: - Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field -through a <>. +through a xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSource]. The actual message code value is parameterized with placeholders, e.g. `"HTTP method {0} not supported"` to be expanded from the arguments. - Each `ErrorResponse` also exposes a message code to resolve the "title" field. @@ -139,7 +139,7 @@ qualified exception class name. [[webflux-ann-rest-exceptions-client]] == Client Handling -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-rest-exceptions.adoc#mvc-ann-rest-exceptions-client[See equivalent in the Servlet stack]# A client application can catch `WebClientResponseException`, when using the `WebClient`, or `RestClientResponseException` when using the `RestTemplate`, and use their diff --git a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc index 0178ebf2b1..7586c31997 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/caching.adoc @@ -1,7 +1,7 @@ [[webflux-caching]] = HTTP Caching -[.small]#<># +[.small]#xref:web/webmvc/mvc-caching.adoc[See equivalent in the Servlet stack]# HTTP caching can significantly improve the performance of a web application. HTTP caching revolves around the `Cache-Control` response header and subsequent conditional request @@ -17,14 +17,14 @@ This section describes the HTTP caching related options available in Spring WebF [[webflux-caching-cachecontrol]] == `CacheControl` -[.small]#<># +[.small]#xref:web/webmvc/mvc-caching.adoc#mvc-caching-cachecontrol[See equivalent in the Servlet stack]# {api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for configuring settings related to the `Cache-Control` header and is accepted as an argument in a number of places: -* <> -* <> +* xref:web/webflux/caching.adoc#webflux-caching-etag-lastmodified[Controllers] +* xref:web/webflux/caching.adoc#webflux-caching-static-resources[Static Resources] While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all possible directives for the `Cache-Control` response header, the `CacheControl` type takes a @@ -65,7 +65,7 @@ use case-oriented approach that focuses on the common scenarios, as the followin [[webflux-caching-etag-lastmodified]] == Controllers -[.small]#<># +[.small]#xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[See equivalent in the Servlet stack]# Controllers can add explicit support for HTTP caching. We recommend doing so, since the `lastModified` or `ETag` value for a resource needs to be calculated before it can be compared @@ -166,10 +166,10 @@ to 412 (PRECONDITION_FAILED) to prevent concurrent modification. [[webflux-caching-static-resources]] == Static Resources -[.small]#<># +[.small]#xref:web/webmvc/mvc-caching.adoc#mvc-caching-static-resources[See equivalent in the Servlet stack]# You should serve static resources with a `Cache-Control` and conditional response headers -for optimal performance. See the section on configuring <>. +for optimal performance. See the section on configuring xref:web/webflux/config.adoc#webflux-config-static-resources[Static Resources]. include:../:webflux-view.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc index 62b53bb863..4ee8732068 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/config.adoc @@ -1,24 +1,24 @@ [[webflux-config]] = WebFlux Config -[.small]#<># +[.small]#xref:web/webmvc/mvc-config.adoc[See equivalent in the Servlet stack]# The WebFlux Java configuration declares the components that are required to process requests with annotated controllers or functional endpoints, and it offers an API to customize the configuration. That means you do not need to understand the underlying beans created by the Java configuration. However, if you want to understand them, you can see them in `WebFluxConfigurationSupport` or read more about what they are -in <>. +in xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[Special Bean Types]. For more advanced customizations, not available in the configuration API, you can gain full control over the configuration through the -<>. +xref:web/webflux/config.adoc#webflux-config-advanced-java[Advanced Configuration Mode]. [[webflux-config-enable]] == Enabling WebFlux Config -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/enable.adoc[See equivalent in the Servlet stack]# You can use the `@EnableWebFlux` annotation in your Java config, as the following example shows: @@ -40,14 +40,14 @@ You can use the `@EnableWebFlux` annotation in your Java config, as the followin ---- The preceding example registers a number of Spring WebFlux -<> and adapts to dependencies +xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[infrastructure beans] and adapts to dependencies available on the classpath -- for JSON, XML, and others. [[webflux-config-customize]] == WebFlux config API -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/customize.adoc[See equivalent in the Servlet stack]# In your Java configuration, you can implement the `WebFluxConfigurer` interface, as the following example shows: @@ -78,7 +78,7 @@ class WebConfig : WebFluxConfigurer { [[webflux-config-conversion]] == Conversion, formatting -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/conversion.adoc[See equivalent in the Servlet stack]# By default, formatters for various number and date types are installed, along with support for customization via `@NumberFormat` and `@DateTimeFormat` on fields. @@ -147,7 +147,7 @@ in the HTML spec. For such cases date and time formatting can be customized as f } ---- -NOTE: See <> +NOTE: See xref:core/validation/format.adoc#format-FormatterRegistrar-SPI[`FormatterRegistrar` SPI] and the `FormattingConversionServiceFactoryBean` for more information on when to use `FormatterRegistrar` implementations. @@ -155,11 +155,11 @@ use `FormatterRegistrar` implementations. [[webflux-config-validation]] == Validation -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/validation.adoc[See equivalent in the Servlet stack]# -By default, if <> is present +By default, if xref:core/validation/beanvalidation.adoc#validation-beanvalidation-overview[Bean Validation] is present on the classpath (for example, the Hibernate Validator), the `LocalValidatorFactoryBean` -is registered as a global <> for use with `@Valid` and +is registered as a global xref:core/validation/validator.adoc[validator] for use with `@Valid` and `@Validated` on `@Controller` method arguments. In your Java configuration, you can customize the global `Validator` instance, @@ -230,7 +230,7 @@ mark it with `@Primary` in order to avoid conflict with the one declared in the [[webflux-config-content-negotiation]] == Content Type Resolvers -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/content-negotiation.adoc[See equivalent in the Servlet stack]# You can configure how Spring WebFlux determines the requested media types for `@Controller` instances from the request. By default, only the `Accept` header is checked, @@ -268,7 +268,7 @@ The following example shows how to customize the requested content type resoluti [[webflux-config-message-codecs]] == HTTP message codecs -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/message-converters.adoc[See equivalent in the Servlet stack]# The following example shows how to customize how the request and response body are read and written: @@ -319,7 +319,7 @@ It also automatically registers the following well-known modules if they are det [[webflux-config-view-resolvers]] == View Resolvers -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/view-resolvers.adoc[See equivalent in the Servlet stack]# The following example shows how to configure view resolution: @@ -427,10 +427,10 @@ You can also plug in any `ViewResolver` implementation, as the following example } ---- -To support <> and rendering other formats +To support xref:web/webflux/dispatcher-handler.adoc#webflux-multiple-representations[Content Negotiation] and rendering other formats through view resolution (besides HTML), you can configure one or more default views based on the `HttpMessageWriterView` implementation, which accepts any of the available -<> from `spring-web`. The following example shows how to do so: +xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] from `spring-web`. The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -470,13 +470,13 @@ on the `HttpMessageWriterView` implementation, which accepts any of the availabl } ---- -See <> for more on the view technologies that are integrated with Spring WebFlux. +See xref:web/webflux-view.adoc[View Technologies] for more on the view technologies that are integrated with Spring WebFlux. [[webflux-config-static-resources]] == Static Resources -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/static-resources.adoc[See equivalent in the Servlet stack]# This option provides a convenient way to serve static resources from a list of {api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. @@ -519,7 +519,7 @@ the example: } ---- -See also <>. +See also xref:web/webflux/caching.adoc#webflux-caching-static-resources[HTTP caching support for static resources]. The resource handler also supports a chain of {api-spring-framework}/web/reactive/resource/ResourceResolver.html[`ResourceResolver`] implementations and @@ -600,7 +600,7 @@ for fine-grained control, e.g. last-modified behavior and optimized resource res [[webflux-config-path-matching]] == Path Matching -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/path-matching.adoc[See equivalent in the Servlet stack]# You can customize options related to path matching. For details on the individual options, see the {api-spring-framework}/web/reactive/config/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc. @@ -646,7 +646,7 @@ whether to decode the request path nor whether to remove semicolon content for path matching purposes. Spring WebFlux also does not support suffix pattern matching, unlike in Spring MVC, where we -are also <> moving away from +are also xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-suffix-pattern-match[recommend] moving away from reliance on it. ==== @@ -701,7 +701,7 @@ For example: [[webflux-config-advanced-java]] == Advanced Configuration Mode -[.small]#<># +[.small]#xref:web/webmvc/mvc-config/advanced-java.adoc[See equivalent in the Servlet stack]# `@EnableWebFlux` imports `DelegatingWebFluxConfiguration` that: diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc index 2f8e72ac0e..32d1a1fb60 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller.adoc @@ -1,7 +1,7 @@ [[webflux-controller]] = Annotated Controllers -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller.adoc[See equivalent in the Servlet stack]# Spring WebFlux provides an annotation-based programming model, where `@Controller` and `@RestController` components use annotations to express request mappings, request input, diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc index 0af8667d8a..0be31002a6 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-advice.adoc @@ -1,7 +1,7 @@ [[webflux-ann-controller-advice]] = Controller Advice -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-advice.adoc[See equivalent in the Servlet stack]# Typically, the `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply within the `@Controller` class (or class hierarchy) in which they are declared. If you @@ -9,8 +9,8 @@ want such methods to apply more globally (across controllers), you can declare t class annotated with `@ControllerAdvice` or `@RestControllerAdvice`. `@ControllerAdvice` is annotated with `@Component`, which means that such classes can be -registered as Spring beans through <>. `@RestControllerAdvice` is a composed annotation that is annotated +registered as Spring beans through xref:core/beans/java/instantiating-container.adoc#beans-java-instantiating-container-scan[component scanning] +. `@RestControllerAdvice` is a composed annotation that is annotated with both `@ControllerAdvice` and `@ResponseBody`, which essentially means `@ExceptionHandler` methods are rendered to the response body through message conversion (versus view resolution or template rendering). diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc index fd0d2779f8..ab7c3ea2e3 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-exceptions.adoc @@ -1,9 +1,9 @@ [[webflux-ann-controller-exceptions]] = Exceptions -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc[See equivalent in the Servlet stack]# -`@Controller` and <> classes can have +`@Controller` and xref:web/webflux/controller/ann-advice.adoc[@ControllerAdvice] classes can have `@ExceptionHandler` methods to handle exceptions from controller methods. The following example includes such a handler method: @@ -49,32 +49,32 @@ as shown in the preceding example. Alternatively, the annotation declaration can exception types to match. We generally recommend being as specific as possible in the argument signature and to declare your primary root exception mappings on a `@ControllerAdvice` prioritized with a corresponding order. -See <> for details. +See xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc[the MVC section] for details. NOTE: An `@ExceptionHandler` method in WebFlux supports the same method arguments and return values as a `@RequestMapping` method, with the exception of request body- and `@ModelAttribute`-related method arguments. Support for `@ExceptionHandler` methods in Spring WebFlux is provided by the -`HandlerAdapter` for `@RequestMapping` methods. See <> +`HandlerAdapter` for `@RequestMapping` methods. See xref:web/webflux/dispatcher-handler.adoc[`DispatcherHandler`] for more detail. [[webflux-ann-exceptionhandler-args]] == Method Arguments -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc#mvc-ann-exceptionhandler-args[See equivalent in the Servlet stack]# -`@ExceptionHandler` methods support the same <> +`@ExceptionHandler` methods support the same xref:web/webflux/controller/ann-methods/arguments.adoc[method arguments] as `@RequestMapping` methods, except the request body might have been consumed already. [[webflux-ann-exceptionhandler-return-values]] == Return Values -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc#mvc-ann-exceptionhandler-return-values[See equivalent in the Servlet stack]# -`@ExceptionHandler` methods support the same <> +`@ExceptionHandler` methods support the same xref:web/webflux/controller/ann-methods/return-types.adoc[return values] as `@RequestMapping` methods. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc index 6ffe7b6e54..d3f5cb6b94 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-initbinder.adoc @@ -1,7 +1,7 @@ [[webflux-ann-initbinder]] = `DataBinder` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-initbinder.adoc[See equivalent in the Servlet stack]# `@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods, to initialize instances of `WebDataBinder`. Those, in turn, are used to: @@ -13,7 +13,7 @@ headers, cookies, and others) to the target type of controller method arguments. `@InitBinder` methods can register controller-specific `java.beans.PropertyEditor` or Spring `Converter` and `Formatter` components. In addition, you can use the -<> to register `Converter` and +xref:web/webflux/config.adoc#webflux-config-conversion[WebFlux Java configuration] to register `Converter` and `Formatter` types in a globally shared `FormattingConversionService`. `@InitBinder` methods support many of the same arguments that `@RequestMapping` methods @@ -100,7 +100,7 @@ controller-specific `Formatter` instances, as the following example shows: [[webflux-ann-initbinder-model-design]] == Model Design -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-initbinder.adoc#mvc-ann-initbinder-model-design[See equivalent in the Servlet stack]# include:../../:web-data-binding-model-design.adoc[] diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc index 6389dada1e..7c073797e8 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods.adoc @@ -1,7 +1,7 @@ [[webflux-ann-methods]] = Handler Methods -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods.adoc[See equivalent in the Servlet stack]# `@RequestMapping` handler methods have a flexible signature and can choose from a range of supported controller method arguments and return values. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc index 9ac95fa05e..87cb4522b2 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/arguments.adoc @@ -1,11 +1,11 @@ [[webflux-ann-arguments]] = Method Arguments -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/arguments.adoc[See equivalent in the Servlet stack]# The following table shows the supported controller method arguments. -Reactive types (Reactor, RxJava, <>) are +Reactive types (Reactor, RxJava, xref:web-reactive.adoc#webflux-reactive-libraries[or other]) are supported on arguments that require blocking I/O (for example, reading the request body) to be resolved. This is marked in the Description column. Reactive types are not expected on arguments that do not require blocking. @@ -44,38 +44,38 @@ and others) and is equivalent to `required=false`. | The time zone associated with the current request, as determined by a `LocaleContextResolver`. | `@PathVariable` -| For access to URI template variables. See <>. +| For access to URI template variables. See xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-uri-templates[URI Patterns]. | `@MatrixVariable` -| For access to name-value pairs in URI path segments. See <>. +| For access to name-value pairs in URI path segments. See xref:web/webflux/controller/ann-methods/matrix-variables.adoc[Matrix Variables]. | `@RequestParam` | For access to query parameters. Parameter values are converted to the declared method argument - type. See <>. + type. See xref:web/webflux/controller/ann-methods/requestparam.adoc[`@RequestParam`]. Note that use of `@RequestParam` is optional -- for example, to set its attributes. See "`Any other argument`" later in this table. | `@RequestHeader` | For access to request headers. Header values are converted to the declared method argument - type. See <>. + type. See xref:web/webflux/controller/ann-methods/requestheader.adoc[`@RequestHeader`]. | `@CookieValue` | For access to cookies. Cookie values are converted to the declared method argument type. - See <>. + See xref:web/webflux/controller/ann-methods/cookievalue.adoc[`@CookieValue`]. | `@RequestBody` | For access to the HTTP request body. Body content is converted to the declared method argument type by using `HttpMessageReader` instances. Supports reactive types. - See <>. + See xref:web/webflux/controller/ann-methods/requestbody.adoc[`@RequestBody`]. | `HttpEntity` | For access to request headers and body. The body is converted with `HttpMessageReader` instances. - Supports reactive types. See <>. + Supports reactive types. See xref:web/webflux/controller/ann-methods/httpentity.adoc[`HttpEntity`]. | `@RequestPart` | For access to a part in a `multipart/form-data` request. Supports reactive types. - See <> and <>. + See xref:web/webflux/controller/ann-methods/multipart-forms.adoc[Multipart Content] and xref:web/webflux/reactive-spring.adoc#webflux-multipart[Multipart Data]. | `java.util.Map`, `org.springframework.ui.Model`, and `org.springframework.ui.ModelMap`. | For access to the model that is used in HTML controllers and is exposed to templates as @@ -83,8 +83,8 @@ and others) and is equivalent to `required=false`. | `@ModelAttribute` | For access to an existing attribute in the model (instantiated if not present) with - data binding and validation applied. See <> as well - as <> and <>. + data binding and validation applied. See xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[`@ModelAttribute`] as well + as xref:web/webflux/controller/ann-modelattrib-methods.adoc[`Model`] and xref:web/webflux/controller/ann-initbinder.adoc[`DataBinder`]. Note that use of `@ModelAttribute` is optional -- for example, to set its attributes. See "`Any other argument`" later in this table. @@ -97,19 +97,19 @@ and others) and is equivalent to `required=false`. | `SessionStatus` + class-level `@SessionAttributes` | For marking form processing complete, which triggers cleanup of session attributes declared through a class-level `@SessionAttributes` annotation. - See <> for more details. + See xref:web/webflux/controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`] for more details. | `UriComponentsBuilder` | For preparing a URL relative to the current request's host, port, scheme, and - context path. See <>. + context path. See xref:web/webflux/uri-building.adoc[URI Links]. | `@SessionAttribute` | For access to any session attribute -- in contrast to model attributes stored in the session as a result of a class-level `@SessionAttributes` declaration. See - <> for more details. + xref:web/webflux/controller/ann-methods/sessionattribute.adoc[`@SessionAttribute`] for more details. | `@RequestAttribute` -| For access to request attributes. See <> for more details. +| For access to request attributes. See xref:web/webflux/controller/ann-methods/requestattrib.adoc[`@RequestAttribute`] for more details. | Any other argument | If a method argument is not matched to any of the above, it is, by default, resolved as diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc index 92abcfe6bc..a90cf11ad7 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/cookievalue.adoc @@ -1,7 +1,7 @@ [[webflux-ann-cookievalue]] = `@CookieValue` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/cookievalue.adoc[See equivalent in the Servlet stack]# You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument in a controller. @@ -37,6 +37,6 @@ The following code sample demonstrates how to get the cookie value: Type conversion is applied automatically if the target method parameter type is not -`String`. See <>. +`String`. See xref:web/webflux/controller/ann-methods/typeconversion.adoc[Type Conversion]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc index d43d137f8e..1b326645c8 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/httpentity.adoc @@ -1,9 +1,9 @@ [[webflux-ann-httpentity]] = `HttpEntity` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/httpentity.adoc[See equivalent in the Servlet stack]# -`HttpEntity` is more or less identical to using <> but is based on a +`HttpEntity` is more or less identical to using xref:web/webflux/controller/ann-methods/requestbody.adoc[`@RequestBody`] but is based on a container object that exposes request headers and the body. The following example uses an `HttpEntity`: diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc index 36930e54d4..ee443c1d7b 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/jackson.adoc @@ -5,7 +5,7 @@ Spring offers support for the Jackson JSON library. [[webflux-ann-jsonview]] == JSON Views -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/jackson.adoc[See equivalent in the Servlet stack]# Spring WebFlux provides built-in support for https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc index 4392607137..f37d3830f5 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/matrix-variables.adoc @@ -1,7 +1,7 @@ [[webflux-ann-matrix-variables]] = Matrix Variables -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc[See equivalent in the Servlet stack]# https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in path segments. In Spring WebFlux, we refer to those as "`matrix variables`" based on an diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc index 140b5d68e3..f2d234a0b1 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/modelattrib-method-args.adoc @@ -1,7 +1,7 @@ [[webflux-ann-modelattrib-method-args]] = `@ModelAttribute` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[See equivalent in the Servlet stack]# You can use the `@ModelAttribute` annotation on a method argument to access an attribute from the model or have it instantiated if not present. The model attribute is also overlaid with @@ -27,8 +27,8 @@ converting individual query parameters and form fields. The following example bi The `Pet` instance in the preceding example is resolved as follows: -* From the model if already added through <>. -* From the HTTP session through <>. +* From the model if already added through xref:web/webflux/controller/ann-modelattrib-methods.adoc[`Model`]. +* From the HTTP session through xref:web/webflux/controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`]. * From the invocation of a default constructor. * From the invocation of a "`primary constructor`" with arguments that match query parameters or form fields. Argument names are determined through JavaBeans @@ -38,8 +38,8 @@ After the model attribute instance is obtained, data binding is applied. The `WebExchangeDataBinder` class matches names of query parameters and form fields to field names on the target `Object`. Matching fields are populated after type conversion is applied where necessary. For more on data binding (and validation), see -<>. For more on customizing data binding, see -<>. +xref:web/webmvc/mvc-config/validation.adoc[Validation]. For more on customizing data binding, see +xref:web/webflux/controller/ann-initbinder.adoc[`DataBinder`]. Data binding can result in errors. By default, a `WebExchangeBindException` is raised, but, to check for such errors in the controller method, you can add a `BindingResult` argument @@ -73,8 +73,8 @@ immediately next to the `@ModelAttribute`, as the following example shows: You can automatically apply validation after data binding by adding the `jakarta.validation.Valid` annotation or Spring's `@Validated` annotation (see also -<> and -<>). The following example uses the `@Valid` annotation: +xref:core/validation/beanvalidation.adoc[Bean Validation] and +xref:web/webmvc/mvc-config/validation.adoc[Spring validation]). The following example uses the `@Valid` annotation: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc index a89f22184d..489c6ec2d8 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/multipart-forms.adoc @@ -1,11 +1,11 @@ [[webflux-multipart-forms]] = Multipart Content -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[See equivalent in the Servlet stack]# -As explained in <>, `ServerWebExchange` provides access to multipart +As explained in xref:web/webflux/reactive-spring.adoc#webflux-multipart[Multipart Data], `ServerWebExchange` provides access to multipart content. The best way to handle a file upload form (for example, from a browser) in a controller -is through data binding to a <>, +is through data binding to a xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[command object], as the following example shows: -- @@ -274,6 +274,6 @@ file upload. <6> The body contents must be completely consumed, relayed, or released to avoid memory leaks. Received part events can also be relayed to another service by using the `WebClient`. -See <>. +See xref:web/webflux-webclient/client-body.adoc#webflux-client-body-multipart[Multipart Data]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc index bcd9cfcc16..b91d1d18bc 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestattrib.adoc @@ -1,7 +1,7 @@ [[webflux-ann-requestattrib]] = `@RequestAttribute` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/requestattrib.adoc[See equivalent in the Servlet stack]# Similarly to `@SessionAttribute`, you can use the `@RequestAttribute` annotation to access pre-existing request attributes created earlier (for example, by a `WebFilter`), diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc index 3349acccf5..40e79bf6ba 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestbody.adoc @@ -1,10 +1,10 @@ [[webflux-ann-requestbody]] = `@RequestBody` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[See equivalent in the Servlet stack]# You can use the `@RequestBody` annotation to have the request body read and deserialized into an -`Object` through an <>. +`Object` through an xref:web/webflux/reactive-spring.adoc#webflux-codecs[HttpMessageReader]. The following example uses a `@RequestBody` argument: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -45,7 +45,7 @@ and fully non-blocking reading and (client-to-server) streaming. } ---- -You can use the <> option of the <> to +You can use the xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs] option of the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] to configure or customize message readers. You can use `@RequestBody` in combination with `jakarta.validation.Valid` or Spring's diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc index 7c29618b73..cf08bc2453 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestheader.adoc @@ -1,7 +1,7 @@ [[webflux-ann-requestheader]] = `@RequestHeader` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/requestheader.adoc[See equivalent in the Servlet stack]# You can use the `@RequestHeader` annotation to bind a request header to a method argument in a controller. @@ -48,7 +48,7 @@ The following example gets the value of the `Accept-Encoding` and `Keep-Alive` h <2> Get the value of the `Keep-Alive` header. Type conversion is applied automatically if the target method parameter type is not -`String`. See <>. +`String`. See xref:web/webflux/controller/ann-methods/typeconversion.adoc[Type Conversion]. When a `@RequestHeader` annotation is used on a `Map`, `MultiValueMap`, or `HttpHeaders` argument, the map is populated diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc index 59b7a1d45c..64bad1fd03 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/requestparam.adoc @@ -1,7 +1,7 @@ [[webflux-ann-requestparam]] = `@RequestParam` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/requestparam.adoc[See equivalent in the Servlet stack]# You can use the `@RequestParam` annotation to bind query parameters to a method argument in a controller. The following code snippet shows the usage: @@ -54,7 +54,7 @@ TIP: The Servlet API "`request parameter`" concept conflates query parameters, f data, and multiparts into one. However, in WebFlux, each is accessed individually through `ServerWebExchange`. While `@RequestParam` binds to query parameters only, you can use data binding to apply query parameters, form data, and multiparts to a -<>. +xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[command object]. Method parameters that use the `@RequestParam` annotation are required by default, but you can specify that a method parameter is optional by setting the required flag of a `@RequestParam` @@ -62,7 +62,7 @@ to `false` or by declaring the argument with a `java.util.Optional` wrapper. Type conversion is applied automatically if the target method parameter type is not -`String`. See <>. +`String`. See xref:web/webflux/controller/ann-methods/typeconversion.adoc[Type Conversion]. When a `@RequestParam` annotation is declared on a `Map` or `MultiValueMap` argument, the map is populated with all query parameters. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc index 212343784d..ce69b696b0 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responsebody.adoc @@ -1,10 +1,10 @@ [[webflux-ann-responsebody]] = `@ResponseBody` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[See equivalent in the Servlet stack]# You can use the `@ResponseBody` annotation on a method to have the return serialized -to the response body through an <>. The following +to the response body through an xref:web/webflux/reactive-spring.adoc#webflux-codecs[HttpMessageWriter]. The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -32,13 +32,13 @@ than a meta-annotation marked with `@Controller` and `@ResponseBody`. `@ResponseBody` supports reactive types, which means you can return Reactor or RxJava types and have the asynchronous values they produce rendered to the response. -For additional details, see <> and -<>. +For additional details, see xref:web/webflux/reactive-spring.adoc#webflux-codecs-streaming[Streaming] and +xref:web/webflux/reactive-spring.adoc#webflux-codecs-jackson[JSON rendering]. You can combine `@ResponseBody` methods with JSON serialization views. -See <> for details. +See xref:web/webflux/controller/ann-methods/jackson.adoc[Jackson JSON] for details. -You can use the <> option of the <> to +You can use the xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs] option of the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] to configure or customize message writing. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc index 317a49d5fd..06c68e1112 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/responseentity.adoc @@ -1,9 +1,9 @@ [[webflux-ann-responseentity]] = `ResponseEntity` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/responseentity.adoc[See equivalent in the Servlet stack]# -`ResponseEntity` is like <> but with status and headers. For example: +`ResponseEntity` is like xref:web/webflux/controller/ann-methods/responsebody.adoc[`@ResponseBody`] but with status and headers. For example: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -26,7 +26,7 @@ } ---- -WebFlux supports using a single value <> to +WebFlux supports using a single value xref:web-reactive.adoc#webflux-reactive-libraries[reactive type] to produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive types for the body. This allows a variety of async responses with `ResponseEntity` as follows: diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc index 499ac55f50..7752ee4853 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/return-types.adoc @@ -1,10 +1,10 @@ [[webflux-ann-return-types]] = Return Values -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/return-types.adoc[See equivalent in the Servlet stack]# The following table shows the supported controller method return values. Note that reactive -types from libraries such as Reactor, RxJava, <> are +types from libraries such as Reactor, RxJava, xref:web-reactive.adoc#webflux-reactive-libraries[or other] are generally supported for all return values. [cols="1,2", options="header"] @@ -13,35 +13,35 @@ generally supported for all return values. | `@ResponseBody` | The return value is encoded through `HttpMessageWriter` instances and written to the response. - See <>. + See xref:web/webflux/controller/ann-methods/responsebody.adoc[`@ResponseBody`]. | `HttpEntity`, `ResponseEntity` | The return value specifies the full response, including HTTP headers, and the body is encoded through `HttpMessageWriter` instances and written to the response. - See <>. + See xref:web/webflux/controller/ann-methods/responseentity.adoc[`ResponseEntity`]. | `HttpHeaders` | For returning a response with headers and no body. | `ErrorResponse` | To render an RFC 7807 error response with details in the body, - see <> + see xref:web/webflux/ann-rest-exceptions.adoc[Error Responses] | `ProblemDetail` | To render an RFC 7807 error response with details in the body, - see <> + see xref:web/webflux/ann-rest-exceptions.adoc[Error Responses] | `String` | A view name to be resolved with `ViewResolver` instances and used together with the implicit model -- determined through command objects and `@ModelAttribute` methods. The handler method can also programmatically enrich the model by declaring a `Model` argument - (described <>). + (described xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution-handling[earlier]). | `View` | A `View` instance to use for rendering together with the implicit model -- determined through command objects and `@ModelAttribute` methods. The handler method can also programmatically enrich the model by declaring a `Model` argument - (described <>). + (described xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution-handling[earlier]). | `java.util.Map`, `org.springframework.ui.Model` | Attributes to be added to the implicit model, with the view name implicitly determined @@ -62,7 +62,7 @@ generally supported for all return values. value) is considered to have fully handled the response if it also has a `ServerHttpResponse`, a `ServerWebExchange` argument, or an `@ResponseStatus` annotation. The same is also true if the controller has made a positive ETag or `lastModified` timestamp check. - See <> for details. + See xref:web/webflux/caching.adoc#webflux-caching-etag-lastmodified[Controllers] for details. If none of the above is true, a `void` return type can also indicate "`no response body`" for REST controllers or default view name selection for HTML controllers. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc index e570ac4773..a205bd26c4 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattribute.adoc @@ -1,7 +1,7 @@ [[webflux-ann-sessionattribute]] = `@SessionAttribute` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc[See equivalent in the Servlet stack]# If you need access to pre-existing session attributes that are managed globally (that is, outside the controller -- for example, by a filter) and may or may not be present, @@ -32,6 +32,6 @@ For use cases that require adding or removing session attributes, consider injec For temporary storage of model attributes in the session as part of a controller workflow, consider using `SessionAttributes`, as described in -<>. +xref:web/webflux/controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`]. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc index 8cdb375830..72fd242c82 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/sessionattributes.adoc @@ -1,7 +1,7 @@ [[webflux-ann-sessionattributes]] = `@SessionAttributes` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[See equivalent in the Servlet stack]# `@SessionAttributes` is used to store model attributes in the `WebSession` between requests. It is a type-level annotation that declares session attributes used by a diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc index 7d83d27e28..c1b58f2bdd 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-methods/typeconversion.adoc @@ -1,7 +1,7 @@ [[webflux-ann-typeconversion]] = Type Conversion -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[See equivalent in the Servlet stack]# Some annotated controller method arguments that represent String-based request input (for example, `@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) @@ -9,8 +9,8 @@ can require type conversion if the argument is declared as something other than For such cases, type conversion is automatically applied based on the configured converters. By default, simple types (such as `int`, `long`, `Date`, and others) are supported. Type conversion -can be customized through a `WebDataBinder` (see <>) or by registering -`Formatters` with the `FormattingConversionService` (see <>). +can be customized through a `WebDataBinder` (see xref:web/webflux/controller/ann-initbinder.adoc[`DataBinder`]) or by registering +`Formatters` with the `FormattingConversionService` (see xref:core/validation/format.adoc[Spring Field Formatting]). A practical issue in type conversion is the treatment of an empty String source value. Such a value is treated as missing if it becomes `null` as a result of type conversion. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc index a04b99f8c1..654d0fc9a9 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-modelattrib-methods.adoc @@ -1,11 +1,11 @@ [[webflux-ann-modelattrib-methods]] = `Model` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[See equivalent in the Servlet stack]# You can use the `@ModelAttribute` annotation: -* On a <> in `@RequestMapping` methods +* On a xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[method argument] in `@RequestMapping` methods to create or access an Object from the model and to bind it to the request through a `WebDataBinder`. * As a method-level annotation in `@Controller` or `@ControllerAdvice` classes, helping @@ -16,7 +16,7 @@ This section discusses `@ModelAttribute` methods, or the second item from the pr A controller can have any number of `@ModelAttribute` methods. All such methods are invoked before `@RequestMapping` methods in the same controller. A `@ModelAttribute` method can also be shared across controllers through `@ControllerAdvice`. See the section on -<> for more details. +xref:web/webflux/controller/ann-advice.adoc[Controller Advice] for more details. `@ModelAttribute` methods have flexible method signatures. They support many of the same arguments as `@RequestMapping` methods (except for `@ModelAttribute` itself and anything diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc index 743d015c5e..053b795659 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann-requestmapping.adoc @@ -1,7 +1,7 @@ [[webflux-ann-requestmapping]] = Request Mapping -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc[See equivalent in the Servlet stack]# The `@RequestMapping` annotation is used to map requests to controllers methods. It has various attributes to match by URL, HTTP method, request parameters, headers, and media @@ -16,7 +16,7 @@ There are also HTTP method specific shortcut variants of `@RequestMapping`: * `@DeleteMapping` * `@PatchMapping` -The preceding annotations are <> that are provided +The preceding annotations are xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-composed[Custom Annotations] that are provided because, arguably, most controller methods should be mapped to a specific HTTP method versus using `@RequestMapping`, which, by default, matches to all HTTP methods. At the same time, a `@RequestMapping` is still needed at the class level to express shared mappings. @@ -65,7 +65,7 @@ The following example uses type and method level mappings: [[webflux-ann-requestmapping-uri-templates]] == URI Patterns -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-uri-templates[See equivalent in the Servlet stack]# You can map requests by using glob patterns and wildcards: @@ -164,7 +164,7 @@ You can declare URI variables at the class and method levels, as the following e URI variables are automatically converted to the appropriate type or a `TypeMismatchException` is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can register support for any other data type. -See <> and <>. +See xref:web/webflux/controller/ann-methods/typeconversion.adoc[Type Conversion] and xref:web/webflux/controller/ann-initbinder.adoc[`DataBinder`]. URI variables can be named explicitly (for example, `@PathVariable("customId")`), but you can leave that detail out if the names are the same and you compile your code with the `-parameters` @@ -214,7 +214,7 @@ explicit, and less vulnerable to URL path based exploits. [[webflux-ann-requestmapping-pattern-comparison]] == Pattern Comparison -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-pattern-comparison[See equivalent in the Servlet stack]# When multiple patterns match a URL, they must be compared to find the best match. This is done with `PathPattern.SPECIFICITY_COMPARATOR`, which looks for patterns that are more specific. @@ -229,7 +229,7 @@ sorted last instead. If two patterns are both catch-all, the longer is chosen. [[webflux-ann-requestmapping-consumes]] == Consumable Media Types -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-consumes[See equivalent in the Servlet stack]# You can narrow the request mapping based on the `Content-Type` of the request, as the following example shows: @@ -264,7 +264,7 @@ TIP: `MediaType` provides constants for commonly used media types -- for example [[webflux-ann-requestmapping-produces]] == Producible Media Types -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-produces[See equivalent in the Servlet stack]# You can narrow the request mapping based on the `Accept` request header and the list of content types that a controller method produces, as the following example shows: @@ -301,7 +301,7 @@ TIP: `MediaType` provides constants for commonly used media types -- e.g. [[webflux-ann-requestmapping-params-and-headers]] == Parameters and Headers -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-params-and-headers[See equivalent in the Servlet stack]# You can narrow request mappings based on query parameter conditions. You can test for the presence of a query parameter (`myParam`), for its absence (`!myParam`), or for a @@ -353,7 +353,7 @@ You can also use the same with request header conditions, as the following examp [[webflux-ann-requestmapping-head-options]] == HTTP HEAD, OPTIONS -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-head-options[See equivalent in the Servlet stack]# `@GetMapping` and `@RequestMapping(method=HttpMethod.GET)` support HTTP HEAD transparently for request mapping purposes. Controller methods need not change. @@ -374,9 +374,9 @@ is not necessary in the common case. [[webflux-ann-requestmapping-composed]] == Custom Annotations -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-composed[See equivalent in the Servlet stack]# -Spring WebFlux supports the use of <> +Spring WebFlux supports the use of xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[composed annotations] for request mapping. Those are annotations that are themselves meta-annotated with `@RequestMapping` and composed to redeclare a subset (or all) of the `@RequestMapping` attributes with a narrower, more specific purpose. @@ -395,7 +395,7 @@ you can check the custom attribute and return your own `RequestCondition`. [[webflux-ann-requestmapping-registration]] == Explicit Registrations -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-registration[See equivalent in the Servlet stack]# You can programmatically register Handler methods, which can be used for dynamic registrations or for advanced cases, such as different instances of the same handler diff --git a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc index 555a8a5876..c44f42c332 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/controller/ann.adoc @@ -1,7 +1,7 @@ [[webflux-ann-controller]] = `@Controller` -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann.adoc[See equivalent in the Servlet stack]# You can define controller beans by using a standard Spring bean definition. The `@Controller` stereotype allows for auto-detection and is aligned with Spring general support @@ -36,7 +36,7 @@ your Java configuration, as the following example shows: ---- <1> Scan the `org.example.web` package. -`@RestController` is a <> that is +`@RestController` is a xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[composed annotation] that is itself meta-annotated with `@Controller` and `@ResponseBody`, indicating a controller whose every method inherits the type-level `@ResponseBody` annotation and, therefore, writes directly to the response body versus view resolution and rendering with an HTML template. @@ -45,7 +45,7 @@ directly to the response body versus view resolution and rendering with an HTML [[webflux-ann-requestmapping-proxying]] == AOP Proxies -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann.adoc#mvc-ann-requestmapping-proxying[See equivalent in the Servlet stack]# In some cases, you may need to decorate a controller with an AOP proxy at runtime. One example is if you choose to have `@Transactional` annotations directly on the diff --git a/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc b/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc index 8afcc14d7e..46250c6f68 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/dispatcher-handler.adoc @@ -1,7 +1,7 @@ [[webflux-dispatcher-handler]] = `DispatcherHandler` -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet.adoc[See equivalent in the Servlet stack]# Spring WebFlux, similarly to Spring MVC, is designed around the front controller pattern, where a central `WebHandler`, the `DispatcherHandler`, provides a shared algorithm for @@ -13,13 +13,13 @@ It is also designed to be a Spring bean itself and implements `ApplicationContex for access to the context in which it runs. If `DispatcherHandler` is declared with a bean name of `webHandler`, it is, in turn, discovered by {api-spring-framework}/web/server/adapter/WebHttpHandlerBuilder.html[`WebHttpHandlerBuilder`], -which puts together a request-processing chain, as described in <>. +which puts together a request-processing chain, as described in xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API]. Spring configuration in a WebFlux application typically contains: * `DispatcherHandler` with the bean name `webHandler` * `WebFilter` and `WebExceptionHandler` beans -* <> +* xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[`DispatcherHandler` special beans] * Others The configuration is given to `WebHttpHandlerBuilder` to build the processing chain, @@ -38,13 +38,13 @@ as the following example shows: val handler = WebHttpHandlerBuilder.applicationContext(context).build() ---- -The resulting `HttpHandler` is ready for use with a <>. +The resulting `HttpHandler` is ready for use with a xref:web/webflux/reactive-spring.adoc#webflux-httphandler[server adapter]. [[webflux-special-bean-types]] == Special Bean Types -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/special-bean-types.adoc[See equivalent in the Servlet stack]# The `DispatcherHandler` delegates to special beans to process requests and render the appropriate responses. By "`special beans,`" we mean Spring-managed `Object` instances that @@ -53,7 +53,7 @@ you can customize their properties, extend them, or replace them. The following table lists the special beans detected by the `DispatcherHandler`. Note that there are also some other beans detected at a lower level (see -<> in the Web Handler API). +xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[Special bean types] in the Web Handler API). [[webflux-special-beans-table]] [cols="1,2", options="header"] @@ -78,7 +78,7 @@ there are also some other beans detected at a lower level (see | `HandlerResultHandler` | Process the result from the handler invocation and finalize the response. - See <>. + See xref:web/webflux/dispatcher-handler.adoc#webflux-resulthandling[Result Handling]. |=== @@ -86,12 +86,12 @@ there are also some other beans detected at a lower level (see [[webflux-framework-config]] == WebFlux Config -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/config.adoc[See equivalent in the Servlet stack]# Applications can declare the infrastructure beans (listed under -<> and -<>) that are required to process requests. -However, in most cases, the <> is the best starting point. It declares the +xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[Web Handler API] and +xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[`DispatcherHandler`]) that are required to process requests. +However, in most cases, the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config] is the best starting point. It declares the required beans and provides a higher-level configuration callback API to customize it. NOTE: Spring Boot relies on the WebFlux config to configure Spring WebFlux and also provides @@ -101,7 +101,7 @@ many extra convenient options. [[webflux-dispatcher-handler-sequence]] == Processing -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/sequence.adoc[See equivalent in the Servlet stack]# `DispatcherHandler` processes requests as follows: @@ -119,7 +119,7 @@ processing by writing to the response directly or by using a view to render. The return value from the invocation of a handler, through a `HandlerAdapter`, is wrapped as a `HandlerResult`, along with some additional context, and passed to the first `HandlerResultHandler` that claims support for it. The following table shows the available -`HandlerResultHandler` implementations, all of which are declared in the <>: +`HandlerResultHandler` implementations, all of which are declared in the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config]: [cols="1,2,1", options="header"] |=== @@ -143,7 +143,7 @@ as a `HandlerResult`, along with some additional context, and passed to the firs {api-spring-framework}/web/reactive/result/view/Rendering.html[Rendering], or any other `Object` is treated as a model attribute. - See also <>. + See also xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution[View Resolution]. | `Integer.MAX_VALUE` |=== @@ -152,7 +152,7 @@ as a `HandlerResult`, along with some additional context, and passed to the firs [[webflux-dispatcher-exceptions]] == Exceptions -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[See equivalent in the Servlet stack]# `HandlerAdapter` implementations can handle internally exceptions from invoking a request handler, such as a controller method. However, an exception may be deferred if the request @@ -166,25 +166,25 @@ A `HandlerAdapter` may also choose to implement `DispatchExceptionHandler`. In t `DispatcherHandler` will apply it to exceptions that arise before a handler is mapped, e.g. during handler mapping, or earlier, e.g. in a `WebFilter`. -See also <> in the "`Annotated Controller`" section or -<> in the WebHandler API section. +See also xref:web/webflux/controller/ann-exceptions.adoc[Exceptions] in the "`Annotated Controller`" section or +xref:web/webflux/reactive-spring.adoc#webflux-exception-handler[Exceptions] in the WebHandler API section. [[webflux-viewresolution]] == View Resolution -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/viewresolver.adoc[See equivalent in the Servlet stack]# View resolution enables rendering to a browser with an HTML template and a model without tying you to a specific view technology. In Spring WebFlux, view resolution is -supported through a dedicated <> that uses +supported through a dedicated xref:web/webflux/dispatcher-handler.adoc#webflux-resulthandling[HandlerResultHandler] that uses `ViewResolver` instances to map a String (representing a logical view name) to a `View` instance. The `View` is then used to render the response. [[webflux-viewresolution-handling]] === Handling -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/viewresolver.adoc#mvc-viewresolver-handling[See equivalent in the Servlet stack]# The `HandlerResult` passed into `ViewResolutionResultHandler` contains the return value from the handler and the model that contains attributes added during request @@ -212,15 +212,15 @@ value or no value (if empty), while multi-value reactive types (for example, `Fl collected and resolved to `List`. To configure view resolution is as simple as adding a `ViewResolutionResultHandler` bean -to your Spring configuration. <> provides a +to your Spring configuration. xref:web/webflux/config.adoc#webflux-config-view-resolvers[WebFlux Config] provides a dedicated configuration API for view resolution. -See <> for more on the view technologies integrated with Spring WebFlux. +See xref:web/webflux-view.adoc[View Technologies] for more on the view technologies integrated with Spring WebFlux. [[webflux-redirecting-redirect-prefix]] === Redirecting -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/viewresolver.adoc#mvc-redirecting-redirect-prefix[See equivalent in the Servlet stack]# The special `redirect:` prefix in a view name lets you perform a redirect. The `UrlBasedViewResolver` (and sub-classes) recognize this as an instruction that a @@ -235,7 +235,7 @@ operate in terms of logical view names. A view name such as [[webflux-multiple-representations]] === Content Negotiation -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/viewresolver.adoc#mvc-multiple-representations[See equivalent in the Servlet stack]# `ViewResolutionResultHandler` supports content negotiation. It compares the request media types with the media types supported by each selected `View`. The first `View` @@ -243,8 +243,8 @@ that supports the requested media type(s) is used. In order to support media types such as JSON and XML, Spring WebFlux provides `HttpMessageWriterView`, which is a special `View` that renders through an -<>. Typically, you would configure these as default -views through the <>. Default views are +xref:web/webflux/reactive-spring.adoc#webflux-codecs[HttpMessageWriter]. Typically, you would configure these as default +views through the xref:web/webflux/config.adoc#webflux-config-view-resolvers[WebFlux Configuration]. Default views are always selected and used if they match the requested media type. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc b/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc index ac8879e0d2..0ae23f0661 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/http2.adoc @@ -1,7 +1,7 @@ [[webflux-http2]] = HTTP/2 -[.small]#<># +[.small]#xref:web/webmvc/mvc-http2.adoc[See equivalent in the Servlet stack]# HTTP/2 is supported with Reactor Netty, Tomcat, Jetty, and Undertow. However, there are considerations related to server configuration. For more details, see the diff --git a/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc b/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc index 70e6be40db..93c9fdcabd 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/new-framework.adoc @@ -79,10 +79,10 @@ as input, adapts it to a Reactor type internally, uses that, and returns either `Flux` or a `Mono` as output. So, you can pass any `Publisher` as input and you can apply operations on the output, but you need to adapt the output for use with another reactive library. Whenever feasible (for example, annotated controllers), WebFlux adapts transparently to the use -of RxJava or another reactive library. See <> for more details. +of RxJava or another reactive library. See xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries] for more details. NOTE: In addition to Reactive APIs, WebFlux can also be used with -<> APIs in Kotlin which provides a more imperative style of programming. +xref:languages/kotlin/coroutines.adoc[Coroutines] APIs in Kotlin which provides a more imperative style of programming. The following Kotlin code samples will be provided with Coroutines APIs. @@ -91,13 +91,13 @@ The following Kotlin code samples will be provided with Coroutines APIs. == Programming Models The `spring-web` module contains the reactive foundation that underlies Spring WebFlux, -including HTTP abstractions, Reactive Streams <> for supported -servers, <>, and a core <> comparable to +including HTTP abstractions, Reactive Streams xref:web/webflux/reactive-spring.adoc#webflux-httphandler[adapters] for supported +servers, xref:web/webflux/reactive-spring.adoc#webflux-codecs[codecs], and a core xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API] comparable to the Servlet API but with non-blocking contracts. On that foundation, Spring WebFlux provides a choice of two programming models: -* <>: Consistent with Spring MVC and based on the same annotations +* xref:web/webflux/controller.adoc[Annotated Controllers]: Consistent with Spring MVC and based on the same annotations from the `spring-web` module. Both Spring MVC and WebFlux controllers support reactive (Reactor and RxJava) return types, and, as a result, it is not easy to tell them apart. One notable difference is that WebFlux also supports reactive `@RequestBody` arguments. @@ -151,7 +151,7 @@ RxJava to perform blocking calls on a separate thread but you would not be makin most of a non-blocking web stack. * If you have a Spring MVC application with calls to remote services, try the reactive `WebClient`. -You can return reactive types (Reactor, RxJava, <>) +You can return reactive types (Reactor, RxJava, xref:web-reactive.adoc#webflux-reactive-libraries[or other]) directly from Spring MVC controller methods. The greater the latency per call or the interdependency among calls, the more dramatic the benefits. Spring MVC controllers can call other reactive components too. @@ -170,12 +170,12 @@ unsure what benefits to look for, start by learning about how non-blocking I/O w Spring WebFlux is supported on Tomcat, Jetty, Servlet containers, as well as on non-Servlet runtimes such as Netty and Undertow. All servers are adapted to a low-level, -<> so that higher-level -<> can be supported across servers. +xref:web/webflux/reactive-spring.adoc#webflux-httphandler[common API] so that higher-level +xref:web/webflux/new-framework.adoc#webflux-programming-models[programming models] can be supported across servers. Spring WebFlux does not have built-in support to start or stop a server. However, it is -easy to <> an application from Spring configuration and -<> and <> with a few +easy to xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[assemble] an application from Spring configuration and +xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux infrastructure] and xref:web/webflux/reactive-spring.adoc#webflux-httphandler[run it] with a few lines of code. Spring Boot has a WebFlux starter that automates these steps. By default, the starter uses @@ -275,10 +275,10 @@ of their own. === Configuring The Spring Framework does not provide support for starting and stopping -<>. To configure the threading model for a server, +xref:web/webflux/new-framework.adoc#webflux-server-choice[servers]. To configure the threading model for a server, you need to use server-specific configuration APIs, or, if you use Spring Boot, check the Spring Boot configuration options for each server. You can -<> the `WebClient` directly. +xref:web/webflux-webclient/client-builder.adoc[configure] the `WebClient` directly. For all other libraries, see their respective documentation. diff --git a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc index cfef50ee74..052378f29a 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc @@ -5,10 +5,10 @@ The `spring-web` module contains the following foundational support for reactive applications: * For server request processing there are two levels of support. -** <>: Basic contract for HTTP request handling with +** xref:web/webflux/reactive-spring.adoc#webflux-httphandler[HttpHandler]: Basic contract for HTTP request handling with non-blocking I/O and Reactive Streams back pressure, along with adapters for Reactor Netty, Undertow, Tomcat, Jetty, and any Servlet container. -** <>: Slightly higher level, general-purpose web API for +** xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API]: Slightly higher level, general-purpose web API for request handling, on top of which concrete programming models such as annotated controllers and functional endpoints are built. * For the client side, there is a basic `ClientHttpConnector` contract to perform HTTP @@ -16,9 +16,9 @@ requests with non-blocking I/O and Reactive Streams back pressure, along with ad https://github.com/reactor/reactor-netty[Reactor Netty], reactive https://github.com/jetty-project/jetty-reactive-httpclient[Jetty HttpClient] and https://hc.apache.org/[Apache HttpComponents]. -The higher level <> used in applications +The higher level xref:web/webflux-webclient.adoc[WebClient] used in applications builds on this basic contract. -* For client and server, <> for serialization and +* For client and server, xref:web/webflux/reactive-spring.adoc#webflux-codecs[codecs] for serialization and deserialization of HTTP request and response content. @@ -198,14 +198,14 @@ that as a `Servlet`. [[webflux-web-handler-api]] == `WebHandler` API -The `org.springframework.web.server` package builds on the <> contract +The `org.springframework.web.server` package builds on the xref:web/webflux/reactive-spring.adoc#webflux-httphandler[`HttpHandler`] contract to provide a general-purpose web API for processing requests through a chain of multiple {api-spring-framework}/web/server/WebExceptionHandler.html[`WebExceptionHandler`], multiple {api-spring-framework}/web/server/WebFilter.html[`WebFilter`], and a single {api-spring-framework}/web/server/WebHandler.html[`WebHandler`] component. The chain can be put together with `WebHttpHandlerBuilder` by simply pointing to a Spring `ApplicationContext` where components are -<>, and/or by registering components +xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[auto-detected], and/or by registering components with the builder. While `HttpHandler` has a simple goal to abstract the use of different HTTP servers, the @@ -233,13 +233,13 @@ Spring ApplicationContext, or that can be registered directly with it: | `WebExceptionHandler` | 0..N | Provide handling for exceptions from the chain of `WebFilter` instances and the target - `WebHandler`. For more details, see <>. + `WebHandler`. For more details, see xref:web/webflux/reactive-spring.adoc#webflux-exception-handler[Exceptions]. | | `WebFilter` | 0..N | Apply interception style logic to before and after the rest of the filter chain and - the target `WebHandler`. For more details, see <>. + the target `WebHandler`. For more details, see xref:web/webflux/reactive-spring.adoc#webflux-filters[Filters]. | `webHandler` | `WebHandler` @@ -291,12 +291,12 @@ Spring ApplicationContext, or that can be registered directly with it: The `DefaultServerWebExchange` uses the configured `HttpMessageReader` to parse form data (`application/x-www-form-urlencoded`) into a `MultiValueMap`. By default, `FormHttpMessageReader` is configured for use by the `ServerCodecConfigurer` bean -(see the <>). +(see the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[Web Handler API]). [[webflux-multipart]] === Multipart Data -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/multipart.adoc[See equivalent in the Servlet stack]# `ServerWebExchange` exposes the following method for accessing multipart data: @@ -319,7 +319,7 @@ dependencies. Alternatively, the `SynchronossPartHttpMessageReader` can be used, which is based on the https://github.com/synchronoss/nio-multipart[Synchronoss NIO Multipart] library. Both are configured through the `ServerCodecConfigurer` bean -(see the <>). +(see the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[Web Handler API]). To parse multipart data in streaming fashion, you can use the `Flux` returned from the `PartEventHttpMessageReader` instead of using `@RequestPart`, as that implies `Map`-like access @@ -330,7 +330,7 @@ collecting to a `MultiValueMap`. [[webflux-forwarded-headers]] === Forwarded Headers -[.small]#<># +[.small]#xref:web/webmvc/filters.adoc#filters-forwarded-headers[See equivalent in the Servlet stack]# As a request goes through proxies (such as load balancers), the host, port, and scheme may change. That makes it a challenge, from a client perspective, to create links that point to the correct @@ -344,7 +344,7 @@ non-standard headers, too, including `X-Forwarded-Host`, `X-Forwarded-Port`, `ForwardedHeaderTransformer` is a component that modifies the host, port, and scheme of the request, based on forwarded headers, and then removes those headers. If you declare it as a bean with the name `forwardedHeaderTransformer`, it will be -<> and used. +xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api-special-beans[detected] and used. There are security considerations for forwarded headers, since an application cannot know if the headers were added by a proxy, as intended, or by a malicious client. This is why @@ -361,33 +361,33 @@ filters, and `ForwardedHeaderTransformer` is used instead. [[webflux-filters]] == Filters -[.small]#<># +[.small]#xref:web/webmvc/filters.adoc[See equivalent in the Servlet stack]# -In the <>, you can use a `WebFilter` to apply interception-style +In the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API], you can use a `WebFilter` to apply interception-style logic before and after the rest of the processing chain of filters and the target -`WebHandler`. When using the <>, registering a `WebFilter` is as simple +`WebHandler`. When using the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config], registering a `WebFilter` is as simple as declaring it as a Spring bean and (optionally) expressing precedence by using `@Order` on the bean declaration or by implementing `Ordered`. [[webflux-filters-cors]] === CORS -[.small]#<># +[.small]#xref:web/webmvc/filters.adoc#filters-cors[See equivalent in the Servlet stack]# Spring WebFlux provides fine-grained support for CORS configuration through annotations on controllers. However, when you use it with Spring Security, we advise relying on the built-in `CorsFilter`, which must be ordered ahead of Spring Security's chain of filters. -See the section on <> and the <> for more details. +See the section on xref:web/webflux-cors.adoc[CORS] and the xref:web/webflux-cors.adoc#webflux-cors-webfilter[CORS `WebFilter`] for more details. [[webflux-exception-handler]] == Exceptions -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc#mvc-ann-customer-servlet-container-error-page[See equivalent in the Servlet stack]# -In the <>, you can use a `WebExceptionHandler` to handle +In the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API], you can use a `WebExceptionHandler` to handle exceptions from the chain of `WebFilter` instances and the target `WebHandler`. When using the -<>, registering a `WebExceptionHandler` is as simple as declaring it as a +xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config], registering a `WebExceptionHandler` is as simple as declaring it as a Spring bean and (optionally) expressing precedence by using `@Order` on the bean declaration or by implementing `Ordered`. @@ -406,7 +406,7 @@ The following table describes the available `WebExceptionHandler` implementation | Extension of `ResponseStatusExceptionHandler` that can also determine the HTTP status code of a `@ResponseStatus` annotation on any exception. - This handler is declared in the <>. + This handler is declared in the xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[WebFlux Config]. |=== @@ -414,7 +414,7 @@ The following table describes the available `WebExceptionHandler` implementation [[webflux-codecs]] == Codecs -[.small]#<># +[.small]#xref:integration/rest-clients.adoc#rest-message-conversion[See equivalent in the Servlet stack]# The `spring-web` and `spring-core` modules provide support for serializing and deserializing byte content to and from higher level objects through non-blocking I/O with @@ -430,7 +430,7 @@ to encode and decode HTTP message content. application, while a `Decoder` can be wrapped with `DecoderHttpMessageReader`. * {api-spring-framework}/core/io/buffer/DataBuffer.html[`DataBuffer`] abstracts different byte buffer representations (e.g. Netty `ByteBuf`, `java.nio.ByteBuffer`, etc.) and is -what all codecs work on. See <> in the +what all codecs work on. See xref:core/databuffer-codec.adoc[Data Buffers and Codecs] in the "Spring Core" section for more on this topic. The `spring-core` module provides `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and @@ -441,7 +441,7 @@ server-sent events, and others. `ClientCodecConfigurer` and `ServerCodecConfigurer` are typically used to configure and customize the codecs to use in an application. See the section on configuring -<>. +xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs]. [[webflux-codecs-jackson]] === Jackson JSON @@ -493,7 +493,7 @@ encode a `Mono>`. On the server side where form content often needs to be accessed from multiple places, `ServerWebExchange` provides a dedicated `getFormData()` method that parses the content through `FormHttpMessageReader` and then caches the result for repeated access. -See <> in the <> section. +See xref:web/webflux/reactive-spring.adoc#webflux-form-data[Form Data] in the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API] section. Once `getFormData()` is used, the original raw content can no longer be read from the request body. For this reason, applications are expected to go through `ServerWebExchange` @@ -515,7 +515,7 @@ For more information about the `DefaultPartHttpMessageReader`, refer to the On the server side where multipart form content may need to be accessed from multiple places, `ServerWebExchange` provides a dedicated `getMultipartData()` method that parses the content through `MultipartHttpMessageReader` and then caches the result for repeated access. -See <> in the <> section. +See xref:web/webflux/reactive-spring.adoc#webflux-multipart[Multipart Data] in the xref:web/webflux/reactive-spring.adoc#webflux-web-handler-api[`WebHandler` API] section. Once `getMultipartData()` is used, the original raw content can no longer be read from the request body. For this reason applications have to consistently use `getMultipartData()` @@ -538,11 +538,11 @@ with one object in the stream. To configure buffer sizes, you can check if a given `Decoder` or `HttpMessageReader` exposes a `maxInMemorySize` property and if so the Javadoc will have details about default values. On the server side, `ServerCodecConfigurer` provides a single place from where to -set all codecs, see <>. On the client side, the limit for +set all codecs, see xref:web/webflux/config.adoc#webflux-config-message-codecs[HTTP message codecs]. On the client side, the limit for all codecs can be changed in -<>. +xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-maxinmemorysize[WebClient.Builder]. -For <> the `maxInMemorySize` property limits +For xref:web/webflux/reactive-spring.adoc#webflux-codecs-multipart[Multipart parsing] the `maxInMemorySize` property limits the size of non-file parts. For file parts, it determines the threshold at which the part is written to disk. For file parts written to disk, there is an additional `maxDiskUsagePerPart` property to limit the amount of disk space per part. There is also @@ -554,7 +554,7 @@ To configure all three in WebFlux, you'll need to supply a pre-configured instan [[webflux-codecs-streaming]] === Streaming -[.small]#<># +[.small]#xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[See equivalent in the Servlet stack]# When streaming to the HTTP response (for example, `text/event-stream`, `application/x-ndjson`), it is important to send data periodically, in order to @@ -568,21 +568,21 @@ a heartbeat. `DataBuffer` is the representation for a byte buffer in WebFlux. The Spring Core part of this reference has more on that in the section on -<>. The key point to understand is that on some +xref:core/databuffer-codec.adoc[Data Buffers and Codecs]. The key point to understand is that on some servers like Netty, byte buffers are pooled and reference counted, and must be released when consumed to avoid memory leaks. WebFlux applications generally do not need to be concerned with such issues, unless they consume or produce data buffers directly, as opposed to relying on codecs to convert to and from higher level objects, or unless they choose to create custom codecs. For such -cases please review the information in <>, -especially the section on <>. +cases please review the information in xref:core/databuffer-codec.adoc[Data Buffers and Codecs], +especially the section on xref:core/databuffer-codec.adoc#databuffers-using[Using DataBuffer]. [[webflux-logging]] == Logging -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/logging.adoc[See equivalent in the Servlet stack]# `DEBUG` level logging in Spring WebFlux is designed to be compact, minimal, and human-friendly. It focuses on high value bits of information that are useful over and @@ -614,7 +614,7 @@ while a fully formatted prefix based on that ID is available from [[webflux-logging-sensitive-data]] === Sensitive Data -[.small]#<># +[.small]#xref:web/webmvc/mvc-servlet/logging.adoc#mvc-logging-sensitive-data[See equivalent in the Servlet stack]# `DEBUG` and `TRACE` logging can log sensitive information. This is why form parameters and headers are masked by default and you must explicitly enable their logging in full. @@ -688,8 +688,8 @@ or specific behaviors that are not supported by the default codecs. Some configuration options expressed by developers are enforced on default codecs. Custom codecs might want to get a chance to align with those preferences, -like <> -or <>. +like xref:web/webflux/reactive-spring.adoc#webflux-codecs-limits[enforcing buffering limits] +or xref:web/webflux/reactive-spring.adoc#webflux-logging-sensitive-data[logging sensitive data]. The following example shows how to do so for client-side requests: diff --git a/framework-docs/modules/ROOT/pages/web/webflux/security.adoc b/framework-docs/modules/ROOT/pages/web/webflux/security.adoc index c198e3540c..9f0e759098 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/security.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/security.adoc @@ -1,7 +1,7 @@ [[webflux-web-security]] = Web Security -[.small]#<># +[.small]#xref:web/webmvc/mvc-security.adoc[See equivalent in the Servlet stack]# The https://spring.io/projects/spring-security[Spring Security] project provides support for protecting web applications from malicious exploits. See the Spring Security diff --git a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc index 92f579e974..4df3001510 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/uri-building.adoc @@ -1,7 +1,7 @@ [[webflux-uri-building]] = URI Links -[.small]#<># +[.small]#xref:web/webmvc/mvc-uri-building.adoc[See equivalent in the Servlet stack]# This section describes various options available in the Spring Framework to prepare URIs. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc index 0936a06ce0..6ea33120fd 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-client.adoc @@ -15,10 +15,10 @@ libraries. NOTE: As of 5.0 the `RestTemplate` is in maintenance mode, with only requests for minor changes and bugs to be accepted. Please, consider using the -<> which offers a more modern API and +xref:web/webflux-webclient.adoc[WebClient] which offers a more modern API and supports sync, async, and streaming scenarios. -See <> for details. +See xref:integration/rest-clients.adoc[REST Endpoints] for details. @@ -39,7 +39,7 @@ In contrast to `RestTemplate`, `WebClient` supports the following: * Synchronous and asynchronous interactions. * Streaming up to or streaming down from a server. -See <> for more details. +See xref:web/webflux-webclient.adoc[WebClient] for more details. @@ -52,4 +52,4 @@ exchange methods. You can then generate a proxy that implements this interface a performs the exchanges. This helps to simplify HTTP remote access and provides additional flexibility for to choose an API style such as synchronous or reactive. -See <> for details. +See xref:integration/rest-clients.adoc#rest-http-interface[REST Endpoints] for details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc index d5a3334a96..c41e79bfcb 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-cors.adoc @@ -1,6 +1,6 @@ [[mvc-cors]] = CORS -[.small]#<># +[.small]#xref:web/webflux-cors.adoc[See equivalent in the Reactive stack]# Spring MVC lets you handle CORS (Cross-Origin Resource Sharing). This section describes how to do so. @@ -10,7 +10,7 @@ describes how to do so. [[mvc-cors-intro]] == Introduction -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-intro[See equivalent in the Reactive stack]# For security reasons, browsers prohibit AJAX calls to resources outside the current origin. For example, you could have your bank account in one tab and evil.com in another. Scripts @@ -27,7 +27,7 @@ powerful workarounds based on IFRAME or JSONP. [[mvc-cors-processing]] == Processing -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-processing[See equivalent in the Reactive stack]# The CORS specification distinguishes between preflight, simple, and actual requests. To learn how CORS works, you can read @@ -77,7 +77,7 @@ To learn more from the source or make advanced customizations, check the code be [[mvc-cors-controller]] == `@CrossOrigin` -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-controller[See equivalent in the Reactive stack]# The {api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] annotation enables cross-origin requests on annotated controller methods, @@ -226,7 +226,7 @@ as the following example shows: [[mvc-cors-global]] == Global Configuration -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-global[See equivalent in the Reactive stack]# In addition to fine-grained, controller method level configuration, you probably want to define some global CORS configuration, too. You can set URL-based `CorsConfiguration` @@ -252,7 +252,7 @@ the `allowOriginPatterns` property may be used to match to a dynamic set of orig [[mvc-cors-global-java]] === Java Configuration -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-global[See equivalent in the Reactive stack]# To enable CORS in the MVC Java config, you can use the `CorsRegistry` callback, as the following example shows: @@ -329,7 +329,7 @@ as the following example shows: [[mvc-cors-filter]] == CORS Filter -[.small]#<># +[.small]#xref:web/webflux-cors.adoc#webflux-cors-webfilter[See equivalent in the Reactive stack]# You can apply CORS support through the built-in {api-spring-framework}/web/filter/CorsFilter.html[`CorsFilter`]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc index 2dc31aa9b7..988a1d795f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-functional.adoc @@ -5,14 +5,14 @@ Spring Web MVC includes WebMvc.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. It is an alternative to the annotation-based programming model but otherwise runs on -the same <>. +the same xref:web/webmvc/mvc-servlet.adoc[DispatcherServlet]. [[webmvc-fn-overview]] == Overview -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-overview[See equivalent in the Reactive stack]# In WebMvc.fn, an HTTP request is handled with a `HandlerFunction`: a function that takes `ServerRequest` and returns a `ServerResponse`. @@ -104,14 +104,14 @@ as the following example shows: If you register the `RouterFunction` as a bean, for instance by exposing it in a -`@Configuration` class, it will be auto-detected by the servlet, as explained in <>. +`@Configuration` class, it will be auto-detected by the servlet, as explained in xref:web/webmvc-functional.adoc#webmvc-fn-running[Running a Server]. [[webmvc-fn-handler-functions]] == HandlerFunction -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-handler-functions[See equivalent in the Reactive stack]# `ServerRequest` and `ServerResponse` are immutable interfaces that offer JDK 8-friendly access to the HTTP request and response, including headers, body, method, and status code. @@ -393,9 +393,9 @@ found. If it is not found, we return a 404 Not Found response. [[webmvc-fn-handler-validation]] === Validation -A functional endpoint can use Spring's <> to +A functional endpoint can use Spring's xref:web/webmvc/mvc-config/validation.adoc[validation facilities] to apply validation to the request body. For example, given a custom Spring -<> implementation for a `Person`: +xref:web/webmvc/mvc-config/validation.adoc[Validator] implementation for a `Person`: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -457,13 +457,13 @@ apply validation to the request body. For example, given a custom Spring Handlers can also use the standard bean validation API (JSR-303) by creating and injecting a global `Validator` instance based on `LocalValidatorFactoryBean`. -See <>. +See xref:core/validation/beanvalidation.adoc[Spring Validation]. [[webmvc-fn-router-functions]] == `RouterFunction` -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-router-functions[See equivalent in the Reactive stack]# Router functions are used to route the requests to the corresponding `HandlerFunction`. Typically, you do not write router functions yourself, but rather use a method on the @@ -673,15 +673,15 @@ We can further improve by using the `nest` method together with `accept`: [[webmvc-fn-running]] == Running a Server -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-running[See equivalent in the Reactive stack]# -You typically run router functions in a <>-based setup through the -<>, which uses Spring configuration to declare the +You typically run router functions in a xref:web/webmvc/mvc-servlet.adoc[`DispatcherHandler`]-based setup through the +xref:web/webmvc/mvc-config.adoc[MVC Config], which uses Spring configuration to declare the components required to process requests. The MVC Java configuration declares the following infrastructure components to support functional endpoints: * `RouterFunctionMapping`: Detects one or more `RouterFunction` beans in the Spring -configuration, <>, combines them through +configuration, xref:core/beans/annotation-config/autowired.adoc#beans-factory-ordered[orders them], combines them through `RouterFunction.andOther`, and routes requests to the resulting composed `RouterFunction`. * `HandlerFunctionAdapter`: Simple adapter that lets `DispatcherHandler` invoke a `HandlerFunction` that was mapped to a request. @@ -766,7 +766,7 @@ The following example shows a WebFlux Java configuration: [[webmvc-fn-handler-filter-function]] == Filtering Handler Functions -[.small]#<># +[.small]#xref:web/webflux-functional.adoc#webflux-fn-handler-filter-function[See equivalent in the Reactive stack]# You can filter handler functions by using the `before`, `after`, or `filter` methods on the routing function builder. @@ -879,4 +879,4 @@ Besides using the `filter` method on the router function builder, it is possible filter to an existing router function via `RouterFunction.filter(HandlerFilterFunction)`. NOTE: CORS support for functional endpoints is provided through a dedicated -<>. +xref:web/webmvc-cors.adoc#mvc-cors-filter[`CorsFilter`]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc index d59d546fa5..3a5d565e1e 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-test.adoc @@ -1,28 +1,28 @@ [[webmvc.test]] = Testing -[.small]#<># +[.small]#xref:web-reactive.adoc#webflux-test[See equivalent in the Reactive stack]# This section summarizes the options available in `spring-test` for Spring MVC applications. * Servlet API Mocks: Mock implementations of Servlet API contracts for unit testing controllers, -filters, and other web components. See <> +filters, and other web components. See xref:testing/unit.adoc#mock-objects-servlet[Servlet API] mock objects for more details. * TestContext Framework: Support for loading Spring configuration in JUnit and TestNG tests, including efficient caching of the loaded configuration across test methods and support for loading a `WebApplicationContext` with a `MockServletContext`. -See <> for more details. +See xref:testing/testcontext-framework.adoc[TestContext Framework] for more details. * Spring MVC Test: A framework, also known as `MockMvc`, for testing annotated controllers through the `DispatcherServlet` (that is, supporting annotations), complete with the Spring MVC infrastructure but without an HTTP server. -See <> for more details. +See xref:testing/spring-mvc-test-framework.adoc[Spring MVC Test] for more details. * Client-side REST: `spring-test` provides a `MockRestServiceServer` that you can use as a mock server for testing client-side code that internally uses the `RestTemplate`. -See <> for more details. +See xref:testing/spring-mvc-test-client.adoc[Client REST Tests] for more details. * `WebTestClient`: Built for testing WebFlux applications, but it can also be used for end-to-end integration testing, to any server, over an HTTP connection. It is a non-blocking, reactive client and is well suited for testing asynchronous and streaming -scenarios. See <> for more details. +scenarios. See xref:testing/webtestclient.adoc[`WebTestClient`] for more details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc index 0017d91c4e..d0547f6fa6 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view.adoc @@ -1,11 +1,11 @@ [[mvc-view]] = View Technologies -[.small]#<># +[.small]#xref:web/webflux-view.adoc[See equivalent in the Reactive stack]# The use of view technologies in Spring MVC is pluggable. Whether you decide to use Thymeleaf, Groovy Markup Templates, JSPs, or other technologies is primarily a matter of a configuration change. This chapter covers view technologies integrated with Spring MVC. -We assume you are already familiar with <>. +We assume you are already familiar with xref:web/webmvc/mvc-servlet/viewresolver.adoc[View Resolution]. WARNING: The views of a Spring MVC application live within the internal trust boundaries of that application. Views have access to all the beans of your application context. As diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc index 38ffb009f4..dbd7481706 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-freemarker.adoc @@ -1,7 +1,7 @@ [[mvc-view-freemarker]] = FreeMarker -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-freemarker[See equivalent in the Reactive stack]# https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any kind of text output from HTML to email and others. The Spring Framework has built-in @@ -11,7 +11,7 @@ integration for using Spring MVC with FreeMarker templates. [[mvc-view-freemarker-contextconfig]] == View Configuration -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-freemarker-contextconfig[See equivalent in the Reactive stack]# The following example shows how to configure FreeMarker as a view technology: @@ -92,7 +92,7 @@ returns a view name of `welcome`, the resolver looks for the [[mvc-views-freemarker]] == FreeMarker Configuration -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-views-freemarker[See equivalent in the Reactive stack]# You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker `Configuration` object (which is managed by Spring) by setting the appropriate bean @@ -131,7 +131,7 @@ with additional convenience macros for generating form input elements themselves [[mvc-view-bind-macros]] === The Bind Macros -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-bind-macros[See equivalent in the Reactive stack]# A standard set of macros are maintained within the `spring-webmvc.jar` file for FreeMarker, so they are always available to a suitably configured application. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc index 674fc94fae..fd8f534043 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jackson.adoc @@ -1,7 +1,7 @@ [[mvc-view-jackson]] = Jackson -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-httpmessagewriter[See equivalent in the Reactive stack]# Spring offers support for the Jackson JSON library. @@ -9,7 +9,7 @@ Spring offers support for the Jackson JSON library. [[mvc-view-json-mapping]] == Jackson-based JSON MVC Views -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-httpmessagewriter[See equivalent in the Reactive stack]# The `MappingJackson2JsonView` uses the Jackson library's `ObjectMapper` to render the response content as JSON. By default, the entire contents of the model map (with the exception of @@ -28,7 +28,7 @@ serializers and deserializers for specific types. [[mvc-view-xml-mapping]] == Jackson-based XML Views -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-httpmessagewriter[See equivalent in the Reactive stack]# `MappingJackson2XmlView` uses the https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML extension's] `XmlMapper` diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc index 8c5ec476c0..5284dc0126 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-jsp.adoc @@ -173,7 +173,7 @@ following example shows: === The `input` Tag This tag renders an HTML `input` element with the bound value and `type='text'` by default. -For an example of this tag, see <>. You can also use +For an example of this tag, see xref:web/webmvc-view/mvc-jsp.adoc#mvc-view-jsp-formtaglib-formtag[The Form Tag]. You can also use HTML5-specific types, such as `email`, `tel`, `date`, and others. @@ -362,7 +362,7 @@ but with different values, as the following example shows: This tag renders multiple HTML `input` elements with the `type` set to `radio`. -As with the <>, you might want to +As with the xref:web/webmvc-view/mvc-jsp.adoc#mvc-view-jsp-formtaglib-checkboxestag[`checkboxes` tag], you might want to pass in the available options as a runtime variable. For this usage, you can use the `radiobuttons` tag. You pass in an `Array`, a `List`, or a `Map` that contains the available options in the `items` property. If you use a `Map`, the map entry key is diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc index 9d5c0e0c72..8cb6e1b124 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-script.adoc @@ -1,7 +1,7 @@ [[mvc-view-script]] = Script Views -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-script[See equivalent in the Reactive stack]# The Spring Framework has a built-in integration for using Spring MVC with any templating library that can run on top of the @@ -27,7 +27,7 @@ TIP: The basic rule for integrating any other script engine is that it must impl [[mvc-view-script-dependencies]] == Requirements -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-script-dependencies[See equivalent in the Reactive stack]# You need to have the script engine on your classpath, the details of which vary by script engine: @@ -47,7 +47,7 @@ through https://www.webjars.org/[WebJars]. [[mvc-view-script-integrate]] == Script Templates -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-script[See equivalent in the Reactive stack]# You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, the script files to load, what function to call to render templates, and so on. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc index e6ea3d7894..53c69f2a37 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-thymeleaf.adoc @@ -1,7 +1,7 @@ [[mvc-view-thymeleaf]] = Thymeleaf -[.small]#<># +[.small]#xref:web/webflux-view.adoc#webflux-view-thymeleaf[See equivalent in the Reactive stack]# Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very helpful diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc index 374172dfdc..2b8ccd547d 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xml-marshalling.adoc @@ -6,7 +6,7 @@ package) to render the response content as XML. You can explicitly set the objec marshalled by using a `MarshallingView` instance's `modelKey` bean property. Alternatively, the view iterates over all model properties and marshals the first type that is supported by the `Marshaller`. For more information on the functionality in the -`org.springframework.oxm` package, see <>. +`org.springframework.oxm` package, see xref:data-access/oxm.adoc[Marshalling XML using O/X Mappers]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc index 8586a50bbb..b139bad0de 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc-view/mvc-xslt.adoc @@ -9,7 +9,7 @@ XSLT in a Spring Web MVC application. This example is a trivial Spring application that creates a list of words in the `Controller` and adds them to the model map. The map is returned, along with the view -name of our XSLT view. See <> for details of Spring Web MVC's +name of our XSLT view. See xref:web/webmvc/mvc-controller.adoc[Annotated Controllers] for details of Spring Web MVC's `Controller` interface. The XSLT controller turns the list of words into a simple XML document ready for transformation. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc.adoc b/framework-docs/modules/ROOT/pages/web/webmvc.adoc index 8c6fa01c2f..4578acc952 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc.adoc @@ -12,7 +12,7 @@ but it is more commonly known as "Spring MVC". Parallel to Spring Web MVC, Spring Framework 5.0 introduced a reactive-stack web framework whose name, "Spring WebFlux," is also based on its source module ({spring-framework-main-code}/spring-webflux[`spring-webflux`]). -This chapter covers Spring Web MVC. The <> +This chapter covers Spring Web MVC. The xref:testing/unit.adoc#mock-objects-web-reactive[next chapter] covers Spring WebFlux. For baseline information and compatibility with Servlet container and Jakarta EE version diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc index b00b961187..c6097bb03d 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/filters.adoc @@ -1,14 +1,14 @@ [[filters]] = Filters -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-filters[See equivalent in the Reactive stack]# The `spring-web` module provides some useful filters: -* <> -* <> -* <> -* <> +* xref:web/webmvc/filters.adoc#filters-http-put[Form Data] +* xref:web/webmvc/filters.adoc#filters-forwarded-headers[Forwarded Headers] +* xref:web/webmvc/filters.adoc#filters-shallow-etag[Shallow ETag] +* xref:web/webmvc/filters.adoc#filters-cors[CORS] @@ -28,7 +28,7 @@ available through the `ServletRequest.getParameter{asterisk}()` family of method [[filters-forwarded-headers]] == Forwarded Headers -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-forwarded-headers[See equivalent in the Reactive stack]# As a request goes through proxies (such as load balancers) the host, port, and scheme may change, and that makes it a challenge to create links that point to the correct @@ -51,10 +51,10 @@ a proxy at the boundary of trust should be configured to remove untrusted `Forwa headers that come from the outside. You can also configure the `ForwardedHeaderFilter` with `removeOnly=true`, in which case it removes but does not use the headers. -In order to support <> and error dispatches this +In order to support xref:web/webmvc/mvc-ann-async.adoc[asynchronous requests] and error dispatches this filter should be mapped with `DispatcherType.ASYNC` and also `DispatcherType.ERROR`. If using Spring Framework's `AbstractAnnotationConfigDispatcherServletInitializer` -(see <>) all filters are automatically registered for all dispatch +(see xref:web/webmvc/mvc-servlet/container-config.adoc[Servlet Config]) all filters are automatically registered for all dispatch types. However if registering the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sure to include `DispatcherType.ASYNC` and `DispatcherType.ERROR` in addition to `DispatcherType.REQUEST`. @@ -71,16 +71,16 @@ request header and, if the two are equal, returns a 304 (NOT_MODIFIED). This strategy saves network bandwidth but not CPU, as the full response must be computed for each request. Other strategies at the controller level, described earlier, can avoid -the computation. See <>. +the computation. See xref:web/webmvc/mvc-caching.adoc[HTTP Caching]. This filter has a `writeWeakETag` parameter that configures the filter to write weak ETags similar to the following: `W/"02a2d595e6ed9a0b24f027f2b63b134d6"` (as defined in https://tools.ietf.org/html/rfc7232#section-2.3[RFC 7232 Section 2.3]). -In order to support <> this filter must be mapped +In order to support xref:web/webmvc/mvc-ann-async.adoc[asynchronous requests] this filter must be mapped with `DispatcherType.ASYNC` so that the filter can delay and successfully generate an ETag to the end of the last async dispatch. If using Spring Framework's -`AbstractAnnotationConfigDispatcherServletInitializer` (see <>) +`AbstractAnnotationConfigDispatcherServletInitializer` (see xref:web/webmvc/mvc-servlet/container-config.adoc[Servlet Config]) all filters are automatically registered for all dispatch types. However if registering the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sure to include `DispatcherType.ASYNC`. @@ -89,13 +89,13 @@ the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sur [[filters-cors]] == CORS -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-filters-cors[See equivalent in the Reactive stack]# Spring MVC provides fine-grained support for CORS configuration through annotations on controllers. However, when used with Spring Security, we advise relying on the built-in `CorsFilter` that must be ordered ahead of Spring Security's chain of filters. -See the sections on <> and the <> for more details. +See the sections on xref:web/webmvc-cors.adoc[CORS] and the xref:web/webmvc-cors.adoc#mvc-cors-filter[CORS Filter] for more details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc index b6e4766979..4fd42b9f71 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-async.adoc @@ -2,22 +2,22 @@ = Asynchronous Requests Spring MVC has an extensive integration with Servlet asynchronous request -<>: +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-processing[processing]: -* <> and <> +* xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-deferredresult[`DeferredResult`] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-callable[`Callable`] return values in controller methods provide basic support for a single asynchronous return value. -* Controllers can <> multiple values, including -<> and <>. +* Controllers can xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[stream] multiple values, including +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-sse[SSE] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-output-stream[raw data]. * Controllers can use reactive clients and return -<> for response handling. +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive types] for response handling. -For an overview of how this differs from Spring WebFlux, see the <> section below. +For an overview of how this differs from Spring WebFlux, see the xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-vs-webflux[Async Spring MVC compared to WebFlux] section below. [[mvc-ann-async-deferredresult]] == `DeferredResult` -Once the asynchronous request processing feature is <> +Once the asynchronous request processing feature is xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration[enabled] in the Servlet container, controller methods can wrap any supported controller method return value with `DeferredResult`, as the following example shows: @@ -80,7 +80,7 @@ as the following example shows: ---- The return value can then be obtained by running the given task through the -<> `TaskExecutor`. +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration-spring-mvc[configured] `TaskExecutor`. @@ -180,7 +180,7 @@ handling is built into all framework contracts and is intrinsically supported th stages of request processing. From a programming model perspective, both Spring MVC and Spring WebFlux support -asynchronous and <> as return values in controller methods. +asynchronous and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types] as return values in controller methods. Spring MVC even supports streaming, including reactive back pressure. However, individual writes to the response remain blocking (and are performed on a separate thread), unlike WebFlux, which relies on non-blocking I/O and does not need an extra thread for each write. @@ -191,12 +191,12 @@ nor does it have any explicit support for asynchronous and reactive types as mod Spring WebFlux does support all that. Finally, from a configuration perspective the asynchronous request processing feature must be -<>. +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration[enabled at the Servlet container level]. [[mvc-ann-async-http-streaming]] == HTTP Streaming -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs-streaming[See equivalent in the Reactive stack]# You can use `DeferredResult` and `Callable` for a single asynchronous return value. What if you want to produce multiple asynchronous values and have those written to the @@ -208,7 +208,7 @@ response? This section describes how to do so. You can use the `ResponseBodyEmitter` return value to produce a stream of objects, where each object is serialized with an -<> and written to the +xref:integration/rest-clients.adoc#rest-message-conversion[`HttpMessageConverter`] and written to the response, as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -306,11 +306,11 @@ stream from a controller, return `SseEmitter`, as the following example shows: While SSE is the main option for streaming into browsers, note that Internet Explorer does not support Server-Sent Events. Consider using Spring's -<> with -<> transports (including SSE) that target +xref:web/websocket.adoc[WebSocket messaging] with +xref:web/websocket/fallback.adoc[SockJS fallback] transports (including SSE) that target a wide range of browsers. -See also <> for notes on exception handling. +See also xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-objects[previous section] for notes on exception handling. [[mvc-ann-async-output-stream]] @@ -349,10 +349,10 @@ customize the status and headers of the response. [[mvc-ann-async-reactive-types]] == Reactive Types -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs-streaming[See equivalent in the Reactive stack]# Spring MVC supports use of reactive client libraries in a controller (also read -<> in the WebFlux section). +xref:web-reactive.adoc#webflux-reactive-libraries[Reactive Libraries] in the WebFlux section). This includes the `WebClient` from `spring-webflux` and others, such as Spring Data reactive data repositories. In such scenarios, it is convenient to be able to return reactive types from the controller method. @@ -374,11 +374,11 @@ TIP: Spring MVC supports Reactor and RxJava through the For streaming to the response, reactive back pressure is supported, but writes to the response are still blocking and are run on a separate thread through the -<> `TaskExecutor`, to avoid +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration-spring-mvc[configured] `TaskExecutor`, to avoid blocking the upstream source (such as a `Flux` returned from `WebClient`). By default, `SimpleAsyncTaskExecutor` is used for the blocking writes, but that is not suitable under load. If you plan to stream with a reactive type, you should use the -<> to configure a task executor. +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-configuration-spring-mvc[MVC configuration] to configure a task executor. @@ -396,7 +396,7 @@ GraphQL Java https://www.graphql-java.com/documentation/concerns/#context-object and others. If Micrometer Context Propagation is present on the classpath, when a controller method -returns a <> such as `Flux` or `Mono`, all +returns a xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive type] such as `Flux` or `Mono`, all `ThreadLocal` values, for which there is a registered `io.micrometer.ThreadLocalAccessor`, are written to the Reactor `Context` as key-value pairs, using the key assigned by the `ThreadLocalAccessor`. @@ -424,17 +424,17 @@ Propagation library. [[mvc-ann-async-disconnects]] == Disconnects -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs-streaming[See equivalent in the Reactive stack]# The Servlet API does not provide any notification when a remote client goes away. -Therefore, while streaming to the response, whether through <> -or <>, it is important to send data periodically, +Therefore, while streaming to the response, whether through xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-sse[SseEmitter] +or xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive types], it is important to send data periodically, since the write fails if the client has disconnected. The send could take the form of an empty (comment-only) SSE event or any other data that the other side would have to interpret as a heartbeat and ignore. Alternatively, consider using web messaging solutions (such as -<> or WebSocket with <>) +xref:web/websocket/stomp.adoc[STOMP over WebSocket] or WebSocket with xref:web/websocket/fallback.adoc[SockJS]) that have a built-in heartbeat mechanism. @@ -474,7 +474,7 @@ You can configure the following: * Default timeout value for async requests, which if not set, depends on the underlying Servlet container. * `AsyncTaskExecutor` to use for blocking writes when streaming with -<> and for executing `Callable` instances returned from +xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types] and for executing `Callable` instances returned from controller methods. We highly recommended configuring this property if you stream with reactive types or have controller methods that return `Callable`, since by default, it is a `SimpleAsyncTaskExecutor`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc index 65bac5f96b..2769c1f1b5 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-ann-rest-exceptions.adoc @@ -1,7 +1,7 @@ [[mvc-ann-rest-exceptions]] = Error Responses -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc[See equivalent in the Reactive stack]# A common requirement for REST services is to include details in the body of error responses. The Spring Framework supports the "Problem Details for HTTP APIs" @@ -18,14 +18,14 @@ exceptions implement this. - `ErrorResponseException` -- basic `ErrorResponse` implementation that others can use as a convenient base class. - `ResponseEntityExceptionHandler` -- convenient base class for an -<> that handles all Spring MVC exceptions, +xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] that handles all Spring MVC exceptions, and any `ErrorResponseException`, and renders an error response with a body. [[mvc-ann-rest-exceptions-render]] == Render -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-render[See equivalent in the Reactive stack]# You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: @@ -39,7 +39,7 @@ and also falls back on it if no compatible media type is found. To enable RFC 7807 responses for Spring WebFlux exceptions and for any `ErrorResponseException`, extend `ResponseEntityExceptionHandler` and declare it as an -<> in Spring configuration. The handler +xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] in Spring configuration. The handler has an `@ExceptionHandler` method that handles any `ErrorResponse` exception, which includes all built-in web exceptions. You can add more exception handling methods, and use a protected method to map any exception to a `ProblemDetail`. @@ -48,7 +48,7 @@ use a protected method to map any exception to a `ProblemDetail`. [[mvc-ann-rest-exceptions-non-standard]] == Non-Standard Fields -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-non-standard[See equivalent in the Reactive stack]# You can extend an RFC 7807 response with non-standard fields in one of two ways. @@ -68,13 +68,13 @@ from an existing `ProblemDetail`. This could be done centrally, e.g. from an [[mvc-ann-rest-exceptions-i18n]] == Internationalization -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-i18n[See equivalent in the Reactive stack]# It is a common requirement to internationalize error response details, and good practice to customize the problem details for Spring MVC exceptions. This is supported as follows: - Each `ErrorResponse` exposes a message code and arguments to resolve the "detail" field -through a <>. +through a xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSource]. The actual message code value is parameterized with placeholders, e.g. `"HTTP method {0} not supported"` to be expanded from the arguments. - Each `ErrorResponse` also exposes a message code to resolve the "title" field. @@ -178,7 +178,7 @@ qualified exception class name. [[mvc-ann-rest-exceptions-client]] == Client Handling -[.small]#<># +[.small]#xref:web/webflux/ann-rest-exceptions.adoc#webflux-ann-rest-exceptions-client[See equivalent in the Reactive stack]# A client application can catch `WebClientResponseException`, when using the `WebClient`, or `RestClientResponseException` when using the `RestTemplate`, and use their diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc index 35f5ef7add..f84647c9a7 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-caching.adoc @@ -1,7 +1,7 @@ [[mvc-caching]] = HTTP Caching -[.small]#<># +[.small]#xref:web/webflux/caching.adoc[See equivalent in the Reactive stack]# HTTP caching can significantly improve the performance of a web application. HTTP caching revolves around the `Cache-Control` response header and, subsequently, conditional request @@ -17,7 +17,7 @@ This section describes the HTTP caching-related options that are available in Sp [[mvc-caching-cachecontrol]] == `CacheControl` -[.small]#<># +[.small]#xref:web/webflux/caching.adoc#webflux-caching-cachecontrol[See equivalent in the Reactive stack]# {api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for configuring settings related to the `Cache-Control` header and is accepted as an argument @@ -25,8 +25,8 @@ in a number of places: * {api-spring-framework}/web/servlet/mvc/WebContentInterceptor.html[`WebContentInterceptor`] * {api-spring-framework}/web/servlet/support/WebContentGenerator.html[`WebContentGenerator`] -* <> -* <> +* xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[Controllers] +* xref:web/webmvc/mvc-caching.adoc#mvc-caching-static-resources[Static Resources] While https://tools.ietf.org/html/rfc7234#section-5.2.2[RFC 7234] describes all possible directives for the `Cache-Control` response header, the `CacheControl` type takes a @@ -73,7 +73,7 @@ works as follows: [[mvc-caching-etag-lastmodified]] == Controllers -[.small]#<># +[.small]#xref:web/webflux/caching.adoc#webflux-caching-etag-lastmodified[See equivalent in the Reactive stack]# Controllers can add explicit support for HTTP caching. We recommended doing so, since the `lastModified` or `ETag` value for a resource needs to be calculated before it can be compared @@ -174,10 +174,10 @@ to 412 (PRECONDITION_FAILED), to prevent concurrent modification. [[mvc-caching-static-resources]] == Static Resources -[.small]#<># +[.small]#xref:web/webflux/caching.adoc#webflux-caching-static-resources[See equivalent in the Reactive stack]# You should serve static resources with a `Cache-Control` and conditional response headers -for optimal performance. See the section on configuring <>. +for optimal performance. See the section on configuring xref:web/webmvc/mvc-config/static-resources.adoc[Static Resources]. @@ -185,7 +185,7 @@ for optimal performance. See the section on configuring <>. +response content and, thus, save bandwidth but not CPU time. See xref:web/webmvc/filters.adoc#filters-shallow-etag[Shallow ETag]. include:../:webmvc-view.adoc[leveloffset=+1] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc index 2b43f62326..0b3446d506 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config.adoc @@ -1,17 +1,17 @@ [[mvc-config]] = MVC Config -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[See equivalent in the Reactive stack]# The MVC Java configuration and the MVC XML namespace provide default configuration suitable for most applications and a configuration API to customize it. For more advanced customizations, which are not available in the configuration API, -see <> and <>. +see xref:web/webmvc/mvc-config/advanced-java.adoc[Advanced Java Config] and xref:web/webmvc/mvc-config/advanced-xml.adoc[Advanced XML Config]. You do not need to understand the underlying beans created by the MVC Java configuration -and the MVC namespace. If you want to learn more, see <> -and <>. +and the MVC namespace. If you want to learn more, see xref:web/webmvc/mvc-servlet/special-bean-types.adoc[Special Bean Types] +and xref:web/webmvc/mvc-servlet/config.adoc[Web MVC Config]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc index e469a02b8f..edf120d601 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/advanced-java.adoc @@ -1,7 +1,7 @@ [[mvc-config-advanced-java]] = Advanced Java Config -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-advanced-java[See equivalent in the Reactive stack]# `@EnableWebMvc` imports `DelegatingWebMvcConfiguration`, which: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc index 95c1392657..2848ad42b1 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/content-negotiation.adoc @@ -1,7 +1,7 @@ [[mvc-config-content-negotiation]] = Content Types -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-content-negotiation[See equivalent in the Reactive stack]# You can configure how Spring MVC determines the requested media types from the request (for example, `Accept` header, URL path extension, query parameter, and others). @@ -10,7 +10,7 @@ By default, only the `Accept` header is checked. If you must use URL-based content type resolution, consider using the query parameter strategy over path extensions. See -<> and <> for +xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-suffix-pattern-match[Suffix Match] and xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-rfd[Suffix Match and RFD] for more details. In Java configuration, you can customize requested content type resolution, as the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc index 9ac7ec9ddb..2de0ddc856 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/conversion.adoc @@ -1,7 +1,7 @@ [[mvc-config-conversion]] = Type Conversion -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-conversion[See equivalent in the Reactive stack]# By default, formatters for various number and date types are installed, along with support for customization via `@NumberFormat` and `@DateTimeFormat` on fields. @@ -108,7 +108,7 @@ in the HTML spec. For such cases date and time formatting can be customized as f } ---- -NOTE: See <> +NOTE: See xref:core/validation/format.adoc#format-FormatterRegistrar-SPI[the `FormatterRegistrar` SPI] and the `FormattingConversionServiceFactoryBean` for more information on when to use FormatterRegistrar implementations. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc index 66261c7616..f9126edd1f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/customize.adoc @@ -1,7 +1,7 @@ [[mvc-config-customize]] = MVC Config API -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-customize[See equivalent in the Reactive stack]# In Java configuration, you can implement the `WebMvcConfigurer` interface, as the following example shows: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc index d1bdaacc48..e7300178a1 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/enable.adoc @@ -1,7 +1,7 @@ [[mvc-config-enable]] = Enable MVC Configuration -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-enable[See equivalent in the Reactive stack]# In Java configuration, you can use the `@EnableWebMvc` annotation to enable MVC configuration, as the following example shows: @@ -43,7 +43,7 @@ configuration, as the following example shows: ---- The preceding example registers a number of Spring MVC -<> and adapts to dependencies +xref:web/webmvc/mvc-servlet/special-bean-types.adoc[infrastructure beans] and adapts to dependencies available on the classpath (for example, payload converters for JSON, XML, and others). diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc index 2182ccdf98..c8c8611579 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/message-converters.adoc @@ -1,7 +1,7 @@ [[mvc-config-message-converters]] = Message Converters -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-message-codecs[See equivalent in the Reactive stack]# You can customize `HttpMessageConverter` in Java configuration by overriding {api-spring-framework}/web/servlet/config/annotation/WebMvcConfigurer.html#configureMessageConverters-java.util.List-[`configureMessageConverters()`] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc index cde874c9ec..a3318bc15b 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/path-matching.adoc @@ -1,7 +1,7 @@ [[mvc-config-path-matching]] = Path Matching -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-path-matching[See equivalent in the Reactive stack]# You can customize options related to path matching and treatment of the URL. For details on the individual options, see the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc index e1f162c873..7620f00ec7 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/static-resources.adoc @@ -1,7 +1,7 @@ [[mvc-config-static-resources]] = Static Resources -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-static-resources[See equivalent in the Reactive stack]# This option provides a convenient way to serve static resources from a list of {api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. @@ -55,7 +55,7 @@ The following example shows how to achieve the same configuration in XML: ---- See also -<>. +xref:web/webmvc/mvc-caching.adoc#mvc-caching-static-resources[HTTP caching support for static resources]. The resource handler also supports a chain of {api-spring-framework}/web/servlet/resource/ResourceResolver.html[`ResourceResolver`] implementations and diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc index d5791c3519..82a89a8e13 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/validation.adoc @@ -1,11 +1,11 @@ [[mvc-config-validation]] = Validation -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-validation[See equivalent in the Reactive stack]# -By default, if <> is present +By default, if xref:core/validation/beanvalidation.adoc#validation-beanvalidation-overview[Bean Validation] is present on the classpath (for example, Hibernate Validator), the `LocalValidatorFactoryBean` is -registered as a global <> for use with `@Valid` and +registered as a global xref:core/validation/validator.adoc[Validator] for use with `@Valid` and `Validated` on controller method arguments. In Java configuration, you can customize the global `Validator` instance, as the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc index 950afe5868..da2227b20e 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/view-resolvers.adoc @@ -1,7 +1,7 @@ [[mvc-config-view-resolvers]] = View Resolvers -[.small]#<># +[.small]#xref:web/webflux/config.adoc#webflux-config-view-resolvers[See equivalent in the Reactive stack]# The MVC configuration simplifies the registration of view resolvers. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc index f3363d0aa0..7af5f14a55 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller.adoc @@ -1,7 +1,7 @@ [[mvc-controller]] = Annotated Controllers -[.small]#<># +[.small]#xref:web/webflux/controller.adoc[See equivalent in the Reactive stack]# Spring MVC provides an annotation-based programming model where `@Controller` and `@RestController` components use annotations to express request mappings, request input, diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc index 67132df5ef..1f50964cf4 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-advice.adoc @@ -1,7 +1,7 @@ [[mvc-ann-controller-advice]] = Controller Advice -[.small]#<># +[.small]#xref:web/webflux/controller/ann-advice.adoc[See equivalent in the Reactive stack]# `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply only to the `@Controller` class, or class hierarchy, in which they are declared. If, instead, they @@ -10,8 +10,8 @@ to any controller. Moreover, as of 5.3, `@ExceptionHandler` methods in `@Control can be used to handle exceptions from any `@Controller` or any other handler. `@ControllerAdvice` is meta-annotated with `@Component` and therefore can be registered as -a Spring bean through <>. `@RestControllerAdvice` is meta-annotated with `@ControllerAdvice` +a Spring bean through xref:core/beans/java/instantiating-container.adoc#beans-java-instantiating-container-scan[component scanning] +. `@RestControllerAdvice` is meta-annotated with `@ControllerAdvice` and `@ResponseBody`, and that means `@ExceptionHandler` methods will have their return value rendered via response body message conversion, rather than via HTML views. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc index 4b3b141ed3..89f7aeff9a 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-exceptionhandler.adoc @@ -1,9 +1,9 @@ [[mvc-ann-exceptionhandler]] = Exceptions -[.small]#<># +[.small]#xref:web/webflux/controller/ann-exceptions.adoc[See equivalent in the Reactive stack]# -`@Controller` and <> classes can have +`@Controller` and xref:web/webmvc/mvc-controller/ann-advice.adoc[@ControllerAdvice] classes can have `@ExceptionHandler` methods to handle exceptions from controller methods, as the following example shows: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -122,12 +122,12 @@ exception is propagated through the remaining resolution chain, as though the given `@ExceptionHandler` method would not have matched in the first place. Support for `@ExceptionHandler` methods in Spring MVC is built on the `DispatcherServlet` -level, <> mechanism. +level, xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[HandlerExceptionResolver] mechanism. [[mvc-ann-exceptionhandler-args]] == Method Arguments -[.small]#<># +[.small]#xref:web/webflux/controller/ann-exceptions.adoc#webflux-ann-exceptionhandler-args[See equivalent in the Reactive stack]# `@ExceptionHandler` methods support the following arguments: @@ -177,22 +177,22 @@ level, <> mechanism. | `RedirectAttributes` | Specify attributes to use in case of a redirect -- (that is to be appended to the query string) and flash attributes to be stored temporarily until the request after the redirect. - See <> and <>. + See xref:web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc[Redirect Attributes] and xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[Flash Attributes]. | `@SessionAttribute` | For access to any session attribute, in contrast to model attributes stored in the session as a result of a class-level `@SessionAttributes` declaration. - See <> for more details. + See xref:web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc[`@SessionAttribute`] for more details. | `@RequestAttribute` -| For access to request attributes. See <> for more details. +| For access to request attributes. See xref:web/webmvc/mvc-controller/ann-methods/requestattrib.adoc[`@RequestAttribute`] for more details. |=== [[mvc-ann-exceptionhandler-return-values]] == Return Values -[.small]#<># +[.small]#xref:web/webflux/controller/ann-exceptions.adoc#webflux-ann-exceptionhandler-return-values[See equivalent in the Reactive stack]# `@ExceptionHandler` methods support the following return values: @@ -202,20 +202,20 @@ level, <> mechanism. | `@ResponseBody` | The return value is converted through `HttpMessageConverter` instances and written to the - response. See <>. + response. See xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[`@ResponseBody`]. | `HttpEntity`, `ResponseEntity` | The return value specifies that the full response (including the HTTP headers and the body) be converted through `HttpMessageConverter` instances and written to the response. - See <>. + See xref:web/webmvc/mvc-controller/ann-methods/responseentity.adoc[ResponseEntity]. | `ErrorResponse` | To render an RFC 7807 error response with details in the body, -see <> +see xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses] | `ProblemDetail` | To render an RFC 7807 error response with details in the body, -see <> +see xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses] | `String` | A view name to be resolved with `ViewResolver` implementations and used together with the @@ -246,7 +246,7 @@ see <> | A method with a `void` return type (or `null` return value) is considered to have fully handled the response if it also has a `ServletResponse` an `OutputStream` argument, or a `@ResponseStatus` annotation. The same is also true if the controller has made a positive - `ETag` or `lastModified` timestamp check (see <> for details). + `ETag` or `lastModified` timestamp check (see xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[Controllers] for details). If none of the above is true, a `void` return type can also indicate "`no response body`" for REST controllers or default view name selection for HTML controllers. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc index 6d025b3665..ded39846ce 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-initbinder.adoc @@ -1,7 +1,7 @@ [[mvc-ann-initbinder]] = `DataBinder` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-initbinder.adoc[See equivalent in the Reactive stack]# `@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods that initialize instances of `WebDataBinder`, and those, in turn, can: @@ -13,7 +13,7 @@ headers, cookies, and others) to the target type of controller method arguments. `@InitBinder` methods can register controller-specific `java.beans.PropertyEditor` or Spring `Converter` and `Formatter` components. In addition, you can use the -<> to register `Converter` and `Formatter` +xref:web/webmvc/mvc-config/conversion.adoc[MVC config] to register `Converter` and `Formatter` types in a globally shared `FormattingConversionService`. `@InitBinder` methods support many of the same arguments that `@RequestMapping` methods @@ -95,7 +95,7 @@ controller-specific `Formatter` implementations, as the following example shows: [[mvc-ann-initbinder-model-design]] == Model Design -[.small]#<># +[.small]#xref:web/webflux/controller/ann-initbinder.adoc#webflux-ann-initbinder-model-design[See equivalent in the Reactive stack]# include:../../:web-data-binding-model-design.adoc[] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc index ee2178aa14..d5717e459c 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods.adoc @@ -1,7 +1,7 @@ [[mvc-ann-methods]] = Handler Methods -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods.adoc[See equivalent in the Reactive stack]# `@RequestMapping` handler methods have a flexible signature and can choose from a range of supported controller method arguments and return values. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc index b0fb31911f..d1509896fe 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/arguments.adoc @@ -1,7 +1,7 @@ [[mvc-ann-arguments]] = Method Arguments -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/arguments.adoc[See equivalent in the Reactive stack]# The next table describes the supported controller method arguments. Reactive types are not supported for any arguments. @@ -59,38 +59,38 @@ and others) and is equivalent to `required=false`. | For access to the raw response body as exposed by the Servlet API. | `@PathVariable` -| For access to URI template variables. See <>. +| For access to URI template variables. See xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-uri-templates[URI patterns]. | `@MatrixVariable` -| For access to name-value pairs in URI path segments. See <>. +| For access to name-value pairs in URI path segments. See xref:web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc[Matrix Variables]. | `@RequestParam` | For access to the Servlet request parameters, including multipart files. Parameter values - are converted to the declared method argument type. See <> as well - as <>. + are converted to the declared method argument type. See xref:web/webmvc/mvc-controller/ann-methods/requestparam.adoc[`@RequestParam`] as well + as xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[Multipart]. Note that use of `@RequestParam` is optional for simple parameter values. See "`Any other argument`", at the end of this table. | `@RequestHeader` | For access to request headers. Header values are converted to the declared method argument - type. See <>. + type. See xref:web/webmvc/mvc-controller/ann-methods/requestheader.adoc[`@RequestHeader`]. | `@CookieValue` | For access to cookies. Cookies values are converted to the declared method argument - type. See <>. + type. See xref:web/webmvc/mvc-controller/ann-methods/cookievalue.adoc[`@CookieValue`]. | `@RequestBody` | For access to the HTTP request body. Body content is converted to the declared method - argument type by using `HttpMessageConverter` implementations. See <>. + argument type by using `HttpMessageConverter` implementations. See xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[`@RequestBody`]. | `HttpEntity` | For access to request headers and body. The body is converted with an `HttpMessageConverter`. - See <>. + See xref:web/webmvc/mvc-controller/ann-methods/httpentity.adoc[HttpEntity]. | `@RequestPart` | For access to a part in a `multipart/form-data` request, converting the part's body - with an `HttpMessageConverter`. See <>. + with an `HttpMessageConverter`. See xref:web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc[Multipart]. | `java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap` | For access to the model that is used in HTML controllers and exposed to templates as @@ -99,12 +99,12 @@ and others) and is equivalent to `required=false`. | `RedirectAttributes` | Specify attributes to use in case of a redirect (that is, to be appended to the query string) and flash attributes to be stored temporarily until the request after redirect. - See <> and <>. + See xref:web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc[Redirect Attributes] and xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[Flash Attributes]. | `@ModelAttribute` | For access to an existing attribute in the model (instantiated if not present) with - data binding and validation applied. See <> as well as - <> and <>. + data binding and validation applied. See xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[`@ModelAttribute`] as well as + xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[Model] and xref:web/webmvc/mvc-controller/ann-initbinder.adoc[`DataBinder`]. Note that use of `@ModelAttribute` is optional (for example, to set its attributes). See "`Any other argument`" at the end of this table. @@ -118,19 +118,19 @@ and others) and is equivalent to `required=false`. | `SessionStatus` + class-level `@SessionAttributes` | For marking form processing complete, which triggers cleanup of session attributes declared through a class-level `@SessionAttributes` annotation. See - <> for more details. + xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`] for more details. | `UriComponentsBuilder` | For preparing a URL relative to the current request's host, port, scheme, context path, and - the literal part of the servlet mapping. See <>. + the literal part of the servlet mapping. See xref:web/webmvc/mvc-uri-building.adoc[URI Links]. | `@SessionAttribute` | For access to any session attribute, in contrast to model attributes stored in the session as a result of a class-level `@SessionAttributes` declaration. See - <> for more details. + xref:web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc[`@SessionAttribute`] for more details. | `@RequestAttribute` -| For access to request attributes. See <> for more details. +| For access to request attributes. See xref:web/webmvc/mvc-controller/ann-methods/requestattrib.adoc[`@RequestAttribute`] for more details. | Any other argument | If a method argument is not matched to any of the earlier values in this table and it is diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc index c666037407..953953f51e 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/cookievalue.adoc @@ -1,7 +1,7 @@ [[mvc-ann-cookievalue]] = `@CookieValue` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/cookievalue.adoc[See equivalent in the Reactive stack]# You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument in a controller. @@ -36,6 +36,6 @@ The following example shows how to get the cookie value: <1> Get the value of the `JSESSIONID` cookie. If the target method parameter type is not `String`, type conversion is applied automatically. -See <>. +See xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[Type Conversion]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc index ae9ffe0d08..9ed54e0d6f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/httpentity.adoc @@ -1,9 +1,9 @@ [[mvc-ann-httpentity]] = HttpEntity -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/httpentity.adoc[See equivalent in the Reactive stack]# -`HttpEntity` is more or less identical to using <> but is based on a +`HttpEntity` is more or less identical to using xref:web/webmvc/mvc-controller/ann-methods/requestbody.adoc[`@RequestBody`] but is based on a container object that exposes request headers and body. The following listing shows an example: [source,java,indent=0,subs="verbatim,quotes",role="primary"] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc index 83d9bc3385..c8a44324c2 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/jackson.adoc @@ -5,7 +5,7 @@ Spring offers support for the Jackson JSON library. [[mvc-ann-jsonview]] == JSON Views -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/jackson.adoc#webflux-ann-jsonview[See equivalent in the Reactive stack]# Spring MVC provides built-in support for https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc index 0fb3135050..927cf90a71 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/matrix-variables.adoc @@ -1,7 +1,7 @@ [[mvc-ann-matrix-variables]] = Matrix Variables -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/matrix-variables.adoc[See equivalent in the Reactive stack]# https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in path segments. In Spring MVC, we refer to those as "`matrix variables`" based on an @@ -135,7 +135,7 @@ To get all matrix variables, you can use a `MultiValueMap`, as the following exa Note that you need to enable the use of matrix variables. In the MVC Java configuration, you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through -<>. In the MVC XML namespace, you can set +xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching]. In the MVC XML namespace, you can set ``. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc index bd26f9a1af..8140ea15dc 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc @@ -1,7 +1,7 @@ [[mvc-ann-modelattrib-method-args]] = `@ModelAttribute` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/modelattrib-method-args.adoc[See equivalent in the Reactive stack]# You can use the `@ModelAttribute` annotation on a method argument to access an attribute from the model or have it be instantiated if not present. The model attribute is also overlain with @@ -32,9 +32,9 @@ fun processSubmit(@ModelAttribute pet: Pet): String { // <1> The `Pet` instance above is sourced in one of the following ways: * Retrieved from the model where it may have been added by a - <>. + xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[@ModelAttribute method]. * Retrieved from the HTTP session if the model attribute was listed in - the class-level <> annotation. + the class-level xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`] annotation. * Obtained through a `Converter` where the model attribute name matches the name of a request value such as a path variable or a request parameter (see next example). * Instantiated using its default constructor. @@ -42,7 +42,7 @@ The `Pet` instance above is sourced in one of the following ways: request parameters. Argument names are determined through JavaBeans `@ConstructorProperties` or through runtime-retained parameter names in the bytecode. -One alternative to using a <> to +One alternative to using a xref:web/webmvc/mvc-controller/ann-modelattrib-methods.adoc[@ModelAttribute method] to supply it or relying on the framework to create the model attribute, is to have a `Converter` to provide the instance. This is applied when the model attribute name matches to the name of a request value such as a path variable or a request @@ -75,8 +75,8 @@ After the model attribute instance is obtained, data binding is applied. The `WebDataBinder` class matches Servlet request parameter names (query parameters and form fields) to field names on the target `Object`. Matching fields are populated after type conversion is applied, where necessary. For more on data binding (and validation), see -<>. For more on customizing data binding, see -<>. +xref:web/webmvc/mvc-config/validation.adoc[Validation]. For more on customizing data binding, see +xref:web/webmvc/mvc-controller/ann-initbinder.adoc[`DataBinder`]. Data binding can result in errors. By default, a `BindException` is raised. However, to check for such errors in the controller method, you can add a `BindingResult` argument immediately next @@ -156,8 +156,8 @@ alternatively, set `@ModelAttribute(binding=false)`, as the following example sh You can automatically apply validation after data binding by adding the `jakarta.validation.Valid` annotation or Spring's `@Validated` annotation -(<> and -<>). The following example shows how to do so: +(xref:core/validation/beanvalidation.adoc[Bean Validation] and +xref:web/webmvc/mvc-config/validation.adoc[Spring validation]). The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc index 59ca68e20e..5348bc4750 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/multipart-forms.adoc @@ -1,9 +1,9 @@ [[mvc-multipart-forms]] = Multipart -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/multipart-forms.adoc[See equivalent in the Reactive stack]# -After a `MultipartResolver` has been <>, the content of POST +After a `MultipartResolver` has been xref:web/webmvc/mvc-servlet/multipart.adoc[enabled], the content of POST requests with `multipart/form-data` is parsed and accessible as regular request parameters. The following example accesses one regular form field and one uploaded file: @@ -58,7 +58,7 @@ NOTE: With Servlet multipart parsing, you may also declare `jakarta.servlet.http instead of Spring's `MultipartFile`, as a method argument or collection value type. You can also use multipart content as part of data binding to a -<>. For example, the form field +xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[command object]. For example, the form field and file from the preceding example could be fields on a form object, as the following example shows: @@ -135,7 +135,7 @@ Content-Transfer-Encoding: 8bit You can access the "meta-data" part with `@RequestParam` as a `String` but you'll probably want it deserialized from JSON (similar to `@RequestBody`). Use the `@RequestPart` annotation to access a multipart after converting it with an -<>: +xref:integration/rest-clients.adoc#rest-message-conversion[HttpMessageConverter]: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc index 135e279087..d32331c410 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/redirecting-passing-data.adoc @@ -47,6 +47,6 @@ through `Model` or `RedirectAttributes`. The following example shows how to defi Another way of passing data to the redirect target is by using flash attributes. Unlike other redirect attributes, flash attributes are saved in the HTTP session (and, hence, do -not appear in the URL). See <> for more information. +not appear in the URL). See xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[Flash Attributes] for more information. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc index 35f921cc91..30858af1c9 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestattrib.adoc @@ -1,7 +1,7 @@ [[mvc-ann-requestattrib]] = `@RequestAttribute` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/requestattrib.adoc[See equivalent in the Reactive stack]# Similar to `@SessionAttribute`, you can use the `@RequestAttribute` annotations to access pre-existing request attributes created earlier (for example, by a Servlet `Filter` diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc index e19db56d7d..b5cc27f47e 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestbody.adoc @@ -1,10 +1,10 @@ [[mvc-ann-requestbody]] = `@RequestBody` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/requestbody.adoc[See equivalent in the Reactive stack]# You can use the `@RequestBody` annotation to have the request body read and deserialized into an -`Object` through an <>. +`Object` through an xref:integration/rest-clients.adoc#rest-message-conversion[`HttpMessageConverter`]. The following example uses a `@RequestBody` argument: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -25,7 +25,7 @@ The following example uses a `@RequestBody` argument: ---- -You can use the <> option of the <> to +You can use the xref:web/webmvc/mvc-config/message-converters.adoc[Message Converters] option of the xref:web/webmvc/mvc-config.adoc[MVC Config] to configure or customize message conversion. You can use `@RequestBody` in combination with `jakarta.validation.Valid` or Spring's diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc index b41391ca5b..d4ce20b0f8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestheader.adoc @@ -1,7 +1,7 @@ [[mvc-ann-requestheader]] = `@RequestHeader` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/requestheader.adoc[See equivalent in the Reactive stack]# You can use the `@RequestHeader` annotation to bind a request header to a method argument in a controller. @@ -48,7 +48,7 @@ The following example gets the value of the `Accept-Encoding` and `Keep-Alive` h <2> Get the value of the `Keep-Alive` header. If the target method parameter type is not -`String`, type conversion is automatically applied. See <>. +`String`, type conversion is automatically applied. See xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[Type Conversion]. When an `@RequestHeader` annotation is used on a `Map`, `MultiValueMap`, or `HttpHeaders` argument, the map is populated diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc index 3d124f4ee0..41b66fe9fa 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/requestparam.adoc @@ -1,7 +1,7 @@ [[mvc-ann-requestparam]] = `@RequestParam` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/requestparam.adoc[See equivalent in the Reactive stack]# You can use the `@RequestParam` annotation to bind Servlet request parameters (that is, query parameters or form data) to a method argument in a controller. @@ -59,7 +59,7 @@ a method parameter is optional by setting the `@RequestParam` annotation's `requ `false` or by declaring the argument with an `java.util.Optional` wrapper. Type conversion is automatically applied if the target method parameter type is not -`String`. See <>. +`String`. See xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[Type Conversion]. Declaring the argument type as an array or list allows for resolving multiple parameter values for the same parameter name. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc index 9e16a49a1b..7462334c47 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responsebody.adoc @@ -1,11 +1,11 @@ [[mvc-ann-responsebody]] = `@ResponseBody` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/responsebody.adoc[See equivalent in the Reactive stack]# You can use the `@ResponseBody` annotation on a method to have the return serialized to the response body through an -<>. +xref:integration/rest-clients.adoc#rest-message-conversion[HttpMessageConverter]. The following listing shows an example: [source,java,indent=0,subs="verbatim,quotes",role="primary"] @@ -32,12 +32,12 @@ all controller methods. This is the effect of `@RestController`, which is nothin than a meta-annotation marked with `@Controller` and `@ResponseBody`. You can use `@ResponseBody` with reactive types. -See <> and <> for more details. +See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types] for more details. -You can use the <> option of the <> to +You can use the xref:web/webmvc/mvc-config/message-converters.adoc[Message Converters] option of the xref:web/webmvc/mvc-config.adoc[MVC Config] to configure or customize message conversion. You can combine `@ResponseBody` methods with JSON serialization views. -See <> for details. +See xref:web/webmvc/mvc-controller/ann-methods/jackson.adoc[Jackson JSON] for details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc index 46a78dccd7..9fb12986a2 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/responseentity.adoc @@ -1,9 +1,9 @@ [[mvc-ann-responseentity]] = ResponseEntity -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/responseentity.adoc[See equivalent in the Reactive stack]# -`ResponseEntity` is like <> but with status and headers. For example: +`ResponseEntity` is like xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[`@ResponseBody`] but with status and headers. For example: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -26,7 +26,7 @@ } ---- -Spring MVC supports using a single value <> +Spring MVC supports using a single value xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[reactive type] to produce the `ResponseEntity` asynchronously, and/or single and multi-value reactive types for the body. This allows the following types of async responses: diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc index 4ac29378d5..266d6ee1aa 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/return-types.adoc @@ -1,7 +1,7 @@ [[mvc-ann-return-types]] = Return Values -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/return-types.adoc[See equivalent in the Reactive stack]# The next table describes the supported controller method return values. Reactive types are supported for all return values. @@ -12,35 +12,35 @@ supported for all return values. | `@ResponseBody` | The return value is converted through `HttpMessageConverter` implementations and written to the - response. See <>. + response. See xref:web/webmvc/mvc-controller/ann-methods/responsebody.adoc[`@ResponseBody`]. | `HttpEntity`, `ResponseEntity` | The return value that specifies the full response (including HTTP headers and body) is to be converted through `HttpMessageConverter` implementations and written to the response. - See <>. + See xref:web/webmvc/mvc-controller/ann-methods/responseentity.adoc[ResponseEntity]. | `HttpHeaders` | For returning a response with headers and no body. | `ErrorResponse` | To render an RFC 7807 error response with details in the body, - see <> + see xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses] | `ProblemDetail` | To render an RFC 7807 error response with details in the body, - see <> + see xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses] | `String` | A view name to be resolved with `ViewResolver` implementations and used together with the implicit model -- determined through command objects and `@ModelAttribute` methods. The handler method can also programmatically enrich the model by declaring a `Model` argument - (see <>). + (see xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-registration[Explicit Registrations]). | `View` | A `View` instance to use for rendering together with the implicit model -- determined through command objects and `@ModelAttribute` methods. The handler method can also programmatically enrich the model by declaring a `Model` argument - (see <>). + (see xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-registration[Explicit Registrations]). | `java.util.Map`, `org.springframework.ui.Model` | Attributes to be added to the implicit model, with the view name implicitly determined @@ -60,18 +60,18 @@ supported for all return values. | A method with a `void` return type (or `null` return value) is considered to have fully handled the response if it also has a `ServletResponse`, an `OutputStream` argument, or an `@ResponseStatus` annotation. The same is also true if the controller has made a positive - `ETag` or `lastModified` timestamp check (see <> for details). + `ETag` or `lastModified` timestamp check (see xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[Controllers] for details). If none of the above is true, a `void` return type can also indicate "`no response body`" for REST controllers or a default view name selection for HTML controllers. | `DeferredResult` | Produce any of the preceding return values asynchronously from any thread -- for example, as a - result of some event or callback. See <> and <>. + result of some event or callback. See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-deferredresult[`DeferredResult`]. | `Callable` | Produce any of the above return values asynchronously in a Spring MVC-managed thread. - See <> and <>. + See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-callable[`Callable`]. | `ListenableFuture`, `java.util.concurrent.CompletionStage`, @@ -82,18 +82,18 @@ supported for all return values. | `ResponseBodyEmitter`, `SseEmitter` | Emit a stream of objects asynchronously to be written to the response with `HttpMessageConverter` implementations. Also supported as the body of a `ResponseEntity`. - See <> and <>. + See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[HTTP Streaming]. | `StreamingResponseBody` | Write to the response `OutputStream` asynchronously. Also supported as the body of a - `ResponseEntity`. See <> and <>. + `ResponseEntity`. See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-http-streaming[HTTP Streaming]. | Reactor and other reactive types registered via `ReactiveAdapterRegistry` | A single value type, e.g. `Mono`, is comparable to returning `DeferredResult`. A multi-value type, e.g. `Flux`, may be treated as a stream depending on the requested media type, e.g. "text/event-stream", "application/json+stream", or otherwise is - collected to a List and rendered as a single value. See <> and - <>. + collected to a List and rendered as a single value. See xref:web/webmvc/mvc-ann-async.adoc[Asynchronous Requests] and + xref:web/webmvc/mvc-ann-async.adoc#mvc-ann-async-reactive-types[Reactive Types]. | Other return values | If a return value remains unresolved in any other way, it is treated as a model diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc index a205b2ec2f..3e5fcad06f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattribute.adoc @@ -1,7 +1,7 @@ [[mvc-ann-sessionattribute]] = `@SessionAttribute` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/sessionattribute.adoc[See equivalent in the Reactive stack]# If you need access to pre-existing session attributes that are managed globally (that is, outside the controller -- for example, by a filter) and may or may not be present, @@ -34,6 +34,6 @@ For use cases that require adding or removing session attributes, consider injec For temporary storage of model attributes in the session as part of a controller workflow, consider using `@SessionAttributes` as described in -<>. +xref:web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc[`@SessionAttributes`]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc index 1163d77211..3dcbf3a6d8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/sessionattributes.adoc @@ -1,7 +1,7 @@ [[mvc-ann-sessionattributes]] = `@SessionAttributes` -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/sessionattributes.adoc[See equivalent in the Reactive stack]# `@SessionAttributes` is used to store model attributes in the HTTP Servlet session between requests. It is a type-level annotation that declares the session attributes used by a diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc index d876bd7e7f..fbaf33f899 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-methods/typeconversion.adoc @@ -1,7 +1,7 @@ [[mvc-ann-typeconversion]] = Type Conversion -[.small]#<># +[.small]#xref:web/webflux/controller/ann-methods/typeconversion.adoc[See equivalent in the Reactive stack]# Some annotated controller method arguments that represent `String`-based request input (such as `@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) @@ -9,9 +9,9 @@ can require type conversion if the argument is declared as something other than For such cases, type conversion is automatically applied based on the configured converters. By default, simple types (`int`, `long`, `Date`, and others) are supported. You can customize -type conversion through a `WebDataBinder` (see <>) or by registering +type conversion through a `WebDataBinder` (see xref:web/webmvc/mvc-controller/ann-initbinder.adoc[`DataBinder`]) or by registering `Formatters` with the `FormattingConversionService`. -See <>. +See xref:core/validation/format.adoc[Spring Field Formatting]. A practical issue in type conversion is the treatment of an empty String source value. Such a value is treated as missing if it becomes `null` as a result of type conversion. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc index 08a54deef4..fec596077f 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-modelattrib-methods.adoc @@ -1,11 +1,11 @@ [[mvc-ann-modelattrib-methods]] = Model -[.small]#<># +[.small]#xref:web/webflux/controller/ann-modelattrib-methods.adoc[See equivalent in the Reactive stack]# You can use the `@ModelAttribute` annotation: -* On a <> in `@RequestMapping` methods +* On a xref:web/webmvc/mvc-controller/ann-methods/modelattrib-method-args.adoc[method argument] in `@RequestMapping` methods to create or access an `Object` from the model and to bind it to the request through a `WebDataBinder`. * As a method-level annotation in `@Controller` or `@ControllerAdvice` classes that help @@ -16,7 +16,7 @@ This section discusses `@ModelAttribute` methods -- the second item in the prece A controller can have any number of `@ModelAttribute` methods. All such methods are invoked before `@RequestMapping` methods in the same controller. A `@ModelAttribute` method can also be shared across controllers through `@ControllerAdvice`. See the section on -<> for more details. +xref:web/webmvc/mvc-controller/ann-advice.adoc[Controller Advice] for more details. `@ModelAttribute` methods have flexible method signatures. They support many of the same arguments as `@RequestMapping` methods, except for `@ModelAttribute` itself or anything diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc index 30969a6a15..36b81824db 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc @@ -1,7 +1,7 @@ [[mvc-ann-requestmapping]] = Request Mapping -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc[See equivalent in the Reactive stack]# You can use the `@RequestMapping` annotation to map requests to controllers methods. It has various attributes to match by URL, HTTP method, request parameters, headers, and media @@ -16,7 +16,7 @@ There are also HTTP method specific shortcut variants of `@RequestMapping`: * `@DeleteMapping` * `@PatchMapping` -The shortcuts are <> that are provided because, +The shortcuts are xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-composed[Custom Annotations] that are provided because, arguably, most controller methods should be mapped to a specific HTTP method versus using `@RequestMapping`, which, by default, matches to all HTTP methods. A `@RequestMapping` is still needed at the class level to express shared mappings. @@ -66,7 +66,7 @@ The following example has type and method level mappings: [[mvc-ann-requestmapping-uri-templates]] == URI patterns -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-uri-templates[See equivalent in the Reactive stack]# `@RequestMapping` methods can be mapped using URL patterns. There are two alternatives: @@ -80,7 +80,7 @@ challenge for dealing effectively with encoding and other issues with URLs. `PathPattern` is the recommended solution for web applications and it is the only choice in Spring WebFlux. It was enabled for use in Spring MVC from version 5.3 and is enabled by -default from version 6.0. See <> for +default from version 6.0. See xref:web/webmvc/mvc-config/path-matching.adoc[MVC config] for customizations of path matching options. `PathPattern` supports the same pattern syntax as `AntPathMatcher`. In addition, it also @@ -152,7 +152,7 @@ You can declare URI variables at the class and method levels, as the following e URI variables are automatically converted to the appropriate type, or `TypeMismatchException` is raised. Simple types (`int`, `long`, `Date`, and so on) are supported by default and you can register support for any other data type. -See <> and <>. +See xref:web/webmvc/mvc-controller/ann-methods/typeconversion.adoc[Type Conversion] and xref:web/webmvc/mvc-controller/ann-initbinder.adoc[`DataBinder`]. You can explicitly name URI variables (for example, `@PathVariable("customId")`), but you can leave that detail out if the names are the same and your code is compiled with the `-parameters` @@ -188,7 +188,7 @@ some external configuration. [[mvc-ann-requestmapping-pattern-comparison]] == Pattern Comparison -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-pattern-comparison[See equivalent in the Reactive stack]# When multiple patterns match a URL, the best match must be selected. This is done with one of the following depending on whether use of parsed `PathPattern` is enabled for use or not: @@ -229,14 +229,14 @@ and security (see next section for more details) also becomes more difficult. To completely disable the use of path extensions in versions prior to 5.3, set the following: -* `useSuffixPatternMatching(false)`, see <> -* `favorPathExtension(false)`, see <> +* `useSuffixPatternMatching(false)`, see xref:web/webmvc/mvc-config/path-matching.adoc[PathMatchConfigurer] +* `favorPathExtension(false)`, see xref:web/webmvc/mvc-config/content-negotiation.adoc[ContentNegotiationConfigurer] Having a way to request content types other than through the `"Accept"` header can still be useful, e.g. when typing a URL in a browser. A safe alternative to path extensions is to use the query parameter strategy. If you must use file extensions, consider restricting them to a list of explicitly registered extensions through the `mediaTypes` property of -<>. +xref:web/webmvc/mvc-config/content-negotiation.adoc[ContentNegotiationConfigurer]. [[mvc-ann-requestmapping-rfd]] @@ -261,7 +261,7 @@ potentially have side effects when URLs are typed directly into a browser. Many common path extensions are allowed as safe by default. Applications with custom `HttpMessageConverter` implementations can explicitly register file extensions for content negotiation to avoid having a `Content-Disposition` header added for those extensions. -See <>. +See xref:web/webmvc/mvc-config/content-negotiation.adoc[Content Types]. See https://pivotal.io/security/cve-2015-5211[CVE-2015-5211] for additional recommendations related to RFD. @@ -269,7 +269,7 @@ recommendations related to RFD. [[mvc-ann-requestmapping-consumes]] == Consumable Media Types -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-consumes[See equivalent in the Reactive stack]# You can narrow the request mapping based on the `Content-Type` of the request, as the following example shows: @@ -307,7 +307,7 @@ TIP: `MediaType` provides constants for commonly used media types, such as [[mvc-ann-requestmapping-produces]] == Producible Media Types -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-produces[See equivalent in the Reactive stack]# You can narrow the request mapping based on the `Accept` request header and the list of content types that a controller method produces, as the following example shows: @@ -347,7 +347,7 @@ TIP: `MediaType` provides constants for commonly used media types, such as [[mvc-ann-requestmapping-params-and-headers]] == Parameters, headers -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-params-and-headers[See equivalent in the Reactive stack]# You can narrow request mappings based on request parameter conditions. You can test for the presence of a request parameter (`myParam`), for the absence of one (`!myParam`), or for a @@ -396,13 +396,13 @@ You can also use the same with request header conditions, as the following examp <1> Testing whether `myHeader` equals `myValue`. TIP: You can match `Content-Type` and `Accept` with the headers condition, but it is better to use -<> and <> +xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-consumes[consumes] and xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-produces[produces] instead. [[mvc-ann-requestmapping-head-options]] == HTTP HEAD, OPTIONS -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-head-options[See equivalent in the Reactive stack]# `@GetMapping` (and `@RequestMapping(method=HttpMethod.GET)`) support HTTP HEAD transparently for request mapping. Controller methods do not need to change. @@ -428,9 +428,9 @@ is not necessary in the common case. [[mvc-ann-requestmapping-composed]] == Custom Annotations -[.small]#<># +[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-head-options[See equivalent in the Reactive stack]# -Spring MVC supports the use of <> +Spring MVC supports the use of xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[composed annotations] for request mapping. Those are annotations that are themselves meta-annotated with `@RequestMapping` and composed to redeclare a subset (or all) of the `@RequestMapping` attributes with a narrower, more specific purpose. @@ -449,7 +449,7 @@ you can check the custom attribute and return your own `RequestCondition`. [[mvc-ann-requestmapping-registration]] == Explicit Registrations -[.small]#<># +[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-registration[See equivalent in the Reactive stack]# You can programmatically register handler methods, which you can use for dynamic registrations or for advanced cases, such as different instances of the same handler diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc index 3af293ea7f..502a3587ad 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann.adoc @@ -1,7 +1,7 @@ [[mvc-ann-controller]] = Declaration -[.small]#<># +[.small]#xref:web/webflux/controller/ann.adoc[See equivalent in the Reactive stack]# You can define controller beans by using a standard Spring bean definition in the Servlet's `WebApplicationContext`. The `@Controller` stereotype allows for auto-detection, @@ -55,7 +55,7 @@ The following example shows the XML configuration equivalent of the preceding ex ---- -`@RestController` is a <> that is +`@RestController` is a xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[composed annotation] that is itself meta-annotated with `@Controller` and `@ResponseBody` to indicate a controller whose every method inherits the type-level `@ResponseBody` annotation and, therefore, writes directly to the response body versus view resolution and rendering with an HTML template. @@ -63,7 +63,7 @@ directly to the response body versus view resolution and rendering with an HTML [[mvc-ann-requestmapping-proxying]] == AOP Proxies -[.small]#<># +[.small]#xref:web/webflux/controller/ann.adoc#webflux-ann-requestmapping-proxying[See equivalent in the Reactive stack]# In some cases, you may need to decorate a controller with an AOP proxy at runtime. One example is if you choose to have `@Transactional` annotations directly on the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc index 2c6f1eb15a..429b619ac6 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-http2.adoc @@ -1,7 +1,7 @@ [[mvc-http2]] = HTTP/2 -[.small]#<># +[.small]#xref:web/webflux/http2.adoc[See equivalent in the Reactive stack]# Servlet 4 containers are required to support HTTP/2, and Spring Framework 5 is compatible with Servlet API 4. From a programming model perspective, there is nothing specific that @@ -11,4 +11,4 @@ https://github.com/spring-projects/spring-framework/wiki/HTTP-2-support[HTTP/2 w The Servlet API does expose one construct related to HTTP/2. You can use the `jakarta.servlet.http.PushBuilder` to proactively push resources to clients, and it -is supported as a <> to `@RequestMapping` methods. +is supported as a xref:web/webmvc/mvc-controller/ann-methods/arguments.adoc[method argument] to `@RequestMapping` methods. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc index d7a43f9988..d704b7e176 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-security.adoc @@ -1,7 +1,7 @@ [[mvc-web-security]] = Web Security -[.small]#<># +[.small]#xref:web/webflux/security.adoc[See equivalent in the Reactive stack]# The https://spring.io/projects/spring-security[Spring Security] project provides support for protecting web applications from malicious exploits. See the Spring Security diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc index 4cff137d26..388084fda2 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet.adoc @@ -1,7 +1,7 @@ [[mvc-servlet]] = DispatcherServlet -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc[See equivalent in the Reactive stack]# Spring MVC, as many other web frameworks, is designed around the front controller pattern where a central `Servlet`, the `DispatcherServlet`, provides a shared algorithm @@ -12,11 +12,11 @@ The `DispatcherServlet`, as any `Servlet`, needs to be declared and mapped accor to the Servlet specification by using Java configuration or in `web.xml`. In turn, the `DispatcherServlet` uses Spring configuration to discover the delegate components it needs for request mapping, view resolution, exception -handling, <>. +handling, xref:web/webmvc/mvc-servlet/special-bean-types.adoc[and more]. The following example of the Java configuration registers and initializes the `DispatcherServlet`, which is auto-detected by the Servlet container -(see <>): +(see xref:web/webmvc/mvc-servlet/container-config.adoc[Servlet Config]): [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -60,7 +60,7 @@ the `DispatcherServlet`, which is auto-detected by the Servlet container NOTE: In addition to using the ServletContext API directly, you can also extend `AbstractAnnotationConfigDispatcherServletInitializer` and override specific methods -(see the example under <>). +(see the example under xref:web/webmvc/mvc-servlet/context-hierarchy.adoc[Context Hierarchy]). NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an alternative to `AnnotationConfigWebApplicationContext`. See the diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc index 86f7aaf0d7..8a23033444 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/config.adoc @@ -1,15 +1,15 @@ [[mvc-servlet-config]] = Web MVC Config -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-framework-config[See equivalent in the Reactive stack]# -Applications can declare the infrastructure beans listed in <> +Applications can declare the infrastructure beans listed in xref:web/webmvc/mvc-servlet/special-bean-types.adoc[Special Bean Types] that are required to process requests. The `DispatcherServlet` checks the `WebApplicationContext` for each special bean. If there are no matching bean types, it falls back on the default types listed in {spring-framework-main-code}/spring-webmvc/src/main/resources/org/springframework/web/servlet/DispatcherServlet.properties[`DispatcherServlet.properties`]. -In most cases, the <> is the best starting point. It declares the required +In most cases, the xref:web/webmvc/mvc-config.adoc[MVC Config] is the best starting point. It declares the required beans in either Java or XML and provides a higher-level configuration callback API to customize it. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc index 149ab98daf..8884cfacc8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/context-hierarchy.adoc @@ -11,7 +11,7 @@ For many applications, having a single `WebApplicationContext` is simple and suf It is also possible to have a context hierarchy where one root `WebApplicationContext` is shared across multiple `DispatcherServlet` (or other `Servlet`) instances, each with its own child `WebApplicationContext` configuration. -See <> +See xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`] for more on the context hierarchy feature. The root `WebApplicationContext` typically contains infrastructure beans, such as data repositories and diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc index 2c527e9740..c839fb1115 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/exceptionhandlers.adoc @@ -1,7 +1,7 @@ [[mvc-exceptionhandlers]] = Exceptions -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-dispatcher-exceptions[See equivalent in the Reactive stack]# If an exception occurs during request mapping or is thrown from a request handler (such as a `@Controller`), the `DispatcherServlet` delegates to a chain of `HandlerExceptionResolver` @@ -21,7 +21,7 @@ The following table lists the available `HandlerExceptionResolver` implementatio | {api-spring-framework}/web/servlet/mvc/support/DefaultHandlerExceptionResolver.html[`DefaultHandlerExceptionResolver`] | Resolves exceptions raised by Spring MVC and maps them to HTTP status codes. - See also alternative `ResponseEntityExceptionHandler` and <>. + See also alternative `ResponseEntityExceptionHandler` and xref:web/webmvc/mvc-ann-rest-exceptions.adoc[Error Responses]. | `ResponseStatusExceptionResolver` | Resolves exceptions with the `@ResponseStatus` annotation and maps them to HTTP status @@ -29,7 +29,7 @@ The following table lists the available `HandlerExceptionResolver` implementatio | `ExceptionHandlerExceptionResolver` | Resolves exceptions by invoking an `@ExceptionHandler` method in a `@Controller` or a - `@ControllerAdvice` class. See <>. + `@ControllerAdvice` class. See xref:web/webmvc/mvc-controller/ann-exceptionhandler.adoc[@ExceptionHandler methods]. |=== @@ -47,7 +47,7 @@ The contract of `HandlerExceptionResolver` specifies that it can return: * `null` if the exception remains unresolved, for subsequent resolvers to try, and, if the exception remains at the end, it is allowed to bubble up to the Servlet container. -The <> automatically declares built-in resolvers for default Spring MVC +The xref:web/webmvc/mvc-config.adoc[MVC Config] automatically declares built-in resolvers for default Spring MVC exceptions, for `@ResponseStatus` annotated exceptions, and for support of `@ExceptionHandler` methods. You can customize that list or replace it. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc index dcf5bc86cd..95aa38fbd3 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-interceptor.adoc @@ -18,7 +18,7 @@ assumes the interceptor itself has taken care of requests (and, for example, ren appropriate view) and does not continue executing the other interceptors and the actual handler in the execution chain. -See <> in the section on MVC configuration for examples of how to +See xref:web/webmvc/mvc-config/interceptors.adoc[Interceptors] in the section on MVC configuration for examples of how to configure interceptors. You can also register them directly by using setters on individual `HandlerMapping` implementations. @@ -26,7 +26,7 @@ configure interceptors. You can also register them directly by using setters on which the response is written and committed within the `HandlerAdapter` and before `postHandle`. That means it is too late to make any changes to the response, such as adding an extra header. For such scenarios, you can implement `ResponseBodyAdvice` and either -declare it as an <> bean or configure it directly on +declare it as an xref:web/webmvc/mvc-controller/ann-advice.adoc[Controller Advice] bean or configure it directly on `RequestMappingHandlerAdapter`. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc index 49b35ffda7..3627ca857e 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/handlermapping-path.adoc @@ -22,7 +22,7 @@ default Servlet with `"/"` or otherwise without a prefix with `"/*"` and the Ser container is 4.0+ then Spring MVC is able to detect the Servlet mapping type and avoid use of the `servletPath` and `pathInfo` altogether. On a 3.1 Servlet container, assuming the same Servlet mapping types, the equivalent can be achieved by providing -a `UrlPathHelper` with `alwaysUseFullPath=true` via <> in +a `UrlPathHelper` with `alwaysUseFullPath=true` via xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching] in the MVC config. Fortunately the default Servlet mapping `"/"` is a good choice. However, there is still @@ -45,7 +45,7 @@ sanitizing path segment values individually without the risk of altering the str of the path. Parsed `PathPattern` also supports the use of `servletPath` prefix mapping as long as a Servlet path mapping is used and the prefix is kept simple, i.e. it has no encoded characters. For pattern syntax details and comparison, see -<>. +xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-pattern-comparison[Pattern Comparison]. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc index 168385e9dc..b489b45314 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc @@ -10,7 +10,7 @@ finds one, it tries to use it to set the locale. By using the `RequestContext.ge method, you can always retrieve the locale that was resolved by the locale resolver. In addition to automatic locale resolution, you can also attach an interceptor to the -handler mapping (see <> for more information on handler +handler mapping (see xref:web/webmvc/mvc-servlet/handlermapping-interceptor.adoc[Interception] for more information on handler mapping interceptors) to change the locale under specific circumstances (for example, based on a parameter in the request). @@ -19,11 +19,11 @@ Locale resolvers and interceptors are defined in the context in the normal way. The following selection of locale resolvers is included in Spring. -* <> -* <> -* <> -* <> -* <> +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-timezone[Time Zone] +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-localeresolver-acceptheader[Header Resolver] +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-localeresolver-cookie[Cookie Resolver] +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-localeresolver-session[Session Resolver] +* xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-localeresolver-interceptor[Locale Interceptor] [[mvc-timezone]] diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc index d09b90c4dc..d3ab01eb37 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/logging.adoc @@ -1,7 +1,7 @@ [[mvc-logging]] = Logging -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-logging[See equivalent in the Reactive stack]# DEBUG-level logging in Spring MVC is designed to be compact, minimal, and human-friendly. It focuses on high-value bits of information that are useful over and @@ -17,7 +17,7 @@ not meet the stated goals, please let us know. [[mvc-logging-sensitive-data]] == Sensitive Data -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-logging-sensitive-data[See equivalent in the Reactive stack]# DEBUG and TRACE logging may log sensitive information. This is why request parameters and headers are masked by default and their logging in full must be enabled explicitly diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc index d9eec04f11..a0dfe886c6 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/multipart.adoc @@ -1,7 +1,7 @@ [[mvc-multipart]] = Multipart Resolver -[.small]#<># +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-multipart[See equivalent in the Reactive stack]# `MultipartResolver` from the `org.springframework.web.multipart` package is a strategy for parsing multipart requests including file uploads. There is a container-based diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc index e1577db645..a640ef3fd8 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/sequence.adoc @@ -1,7 +1,7 @@ [[mvc-servlet-sequence]] = Processing -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-dispatcher-handler-sequence[See equivalent in the Reactive stack]# The `DispatcherServlet` processes requests as follows: @@ -15,7 +15,7 @@ The `DispatcherServlet` processes requests as follows: which theme to use. If you do not use themes, you can ignore it. * If you specify a multipart file resolver, the request is inspected for multiparts. If multiparts are found, the request is wrapped in a `MultipartHttpServletRequest` for - further processing by other elements in the process. See <> for further + further processing by other elements in the process. See xref:web/webmvc/mvc-servlet/multipart.adoc[Multipart Resolver] for further information about multipart handling. * An appropriate handler is searched for. If a handler is found, the execution chain associated with the handler (preprocessors, postprocessors, and controllers) is @@ -28,11 +28,11 @@ The `DispatcherServlet` processes requests as follows: The `HandlerExceptionResolver` beans declared in the `WebApplicationContext` are used to resolve exceptions thrown during request processing. Those exception resolvers allow -customizing the logic to address exceptions. See <> for more details. +customizing the logic to address exceptions. See xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[Exceptions] for more details. For HTTP caching support, handlers can use the `checkNotModified` methods of `WebRequest`, along with further options for annotated controllers as described in -<>. +xref:web/webmvc/mvc-caching.adoc#mvc-caching-etag-lastmodified[HTTP Caching for Controllers]. You can customize individual `DispatcherServlet` instances by adding Servlet initialization parameters (`init-param` elements) to the Servlet declaration in the @@ -65,7 +65,7 @@ initialization parameters (`init-param` elements) to the Servlet declaration in By default, this is set to `false`, in which case the `DispatcherServlet` sets the response status to 404 (NOT_FOUND) without raising an exception. - Note that, if <> is + Note that, if xref:web/webmvc/mvc-config/default-servlet-handler.adoc[default servlet handling] is also configured, unresolved requests are always forwarded to the default servlet and a 404 is never raised. |=== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc index c9a650490f..edb52264be 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/special-bean-types.adoc @@ -1,7 +1,7 @@ [[mvc-servlet-special-bean-types]] = Special Bean Types -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-special-bean-types[See equivalent in the Reactive stack]# The `DispatcherServlet` delegates to special beans to process requests and render the appropriate responses. By "`special beans`" we mean Spring-managed `Object` instances that @@ -17,7 +17,7 @@ The following table lists the special beans detected by the `DispatcherServlet`: | `HandlerMapping` | Map a request to a handler along with a list of - <> for pre- and post-processing. + xref:web/webmvc/mvc-servlet/handlermapping-interceptor.adoc[interceptors] for pre- and post-processing. The mapping is based on some criteria, the details of which vary by `HandlerMapping` implementation. @@ -31,30 +31,30 @@ The following table lists the special beans detected by the `DispatcherServlet`: requires resolving annotations. The main purpose of a `HandlerAdapter` is to shield the `DispatcherServlet` from such details. -| <> +| xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[`HandlerExceptionResolver`] | Strategy to resolve exceptions, possibly mapping them to handlers, to HTML error - views, or other targets. See <>. + views, or other targets. See xref:web/webmvc/mvc-servlet/exceptionhandlers.adoc[Exceptions]. -| <> +| xref:web/webmvc/mvc-servlet/viewresolver.adoc[`ViewResolver`] | Resolve logical `String`-based view names returned from a handler to an actual `View` - with which to render to the response. See <> and <>. + with which to render to the response. See xref:web/webmvc/mvc-servlet/viewresolver.adoc[View Resolution] and xref:web/webmvc-view.adoc[View Technologies]. -| <>, <> +| xref:web/webmvc/mvc-servlet/localeresolver.adoc[`LocaleResolver`], xref:web/webmvc/mvc-servlet/localeresolver.adoc#mvc-timezone[LocaleContextResolver] | Resolve the `Locale` a client is using and possibly their time zone, in order to be able - to offer internationalized views. See <>. + to offer internationalized views. See xref:web/webmvc/mvc-servlet/localeresolver.adoc[Locale]. -| <> +| xref:web/webmvc/mvc-servlet/themeresolver.adoc[`ThemeResolver`] | Resolve themes your web application can use -- for example, to offer personalized layouts. - See <>. + See xref:web/webmvc/mvc-servlet/themeresolver.adoc[Themes]. -| <> +| xref:web/webmvc/mvc-servlet/multipart.adoc[`MultipartResolver`] | Abstraction for parsing a multi-part request (for example, browser form file upload) with - the help of some multipart parsing library. See <>. + the help of some multipart parsing library. See xref:web/webmvc/mvc-servlet/multipart.adoc[Multipart Resolver]. -| <> +| xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[`FlashMapManager`] | Store and retrieve the "`input`" and the "`output`" `FlashMap` that can be used to pass attributes from one request to another, usually across a redirect. - See <>. + See xref:web/webmvc/mvc-controller/ann-methods/flash-attributes.adoc[Flash Attributes]. |=== diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc index 83f9f81a8e..fc4bc9a103 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/themeresolver.adoc @@ -62,7 +62,7 @@ background image with Dutch text on it. [[mvc-themeresolver-resolving]] == Resolving Themes -After you define themes, as described in the <>, +After you define themes, as described in the xref:web/webmvc/mvc-servlet/themeresolver.adoc#mvc-themeresolver-defining[preceding section], you decide which theme to use. The `DispatcherServlet` looks for a bean named `themeResolver` to find out which `ThemeResolver` implementation to use. A theme resolver works in much the same way as a `LocaleResolver`. It detects the theme to use for a particular request and can also diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc index f4bf8270ce..96d9ceb063 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/viewresolver.adoc @@ -1,7 +1,7 @@ [[mvc-viewresolver]] = View Resolution -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution[See equivalent in the Reactive stack]# Spring MVC defines the `ViewResolver` and `View` interfaces that let you render models in a browser without tying you to a specific view technology. `ViewResolver` @@ -41,7 +41,7 @@ The following table provides more details on the `ViewResolver` hierarchy: | `ContentNegotiatingViewResolver` | Implementation of the `ViewResolver` interface that resolves a view based on the - request file name or `Accept` header. See <>. + request file name or `Accept` header. See xref:web/webmvc/mvc-servlet/viewresolver.adoc#mvc-multiple-representations[Content Negotiation]. | `BeanNameViewResolver` | Implementation of the `ViewResolver` interface that interprets a view name as a @@ -53,7 +53,7 @@ The following table provides more details on the `ViewResolver` hierarchy: [[mvc-viewresolver-handling]] == Handling -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-viewresolution-handling[See equivalent in the Reactive stack]# You can chain view resolvers by declaring more than one resolver bean and, if necessary, by setting the `order` property to specify ordering. Remember, the higher the order property, @@ -66,15 +66,15 @@ the only way to figure out if a JSP exists is to perform a dispatch through to be last in the overall order of view resolvers. Configuring view resolution is as simple as adding `ViewResolver` beans to your Spring -configuration. The <> provides a dedicated configuration API for -<> and for adding logic-less -<> which are useful for HTML template +configuration. The xref:web/webmvc/mvc-config.adoc[MVC Config] provides a dedicated configuration API for +xref:web/webmvc/mvc-config/view-resolvers.adoc[View Resolvers] and for adding logic-less +xref:web/webmvc/mvc-config/view-controller.adoc[View Controllers] which are useful for HTML template rendering without controller logic. [[mvc-redirecting-redirect-prefix]] == Redirecting -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-redirecting-redirect-prefix[See equivalent in the Reactive stack]# The special `redirect:` prefix in a view name lets you perform a redirect. The `UrlBasedViewResolver` (and its subclasses) recognize this as an instruction that a @@ -104,7 +104,7 @@ Servlet/JSP engine. Note that you may also chain multiple view resolvers, instea [[mvc-multiple-representations]] == Content Negotiation -[.small]#<># +[.small]#xref:web/webflux/dispatcher-handler.adoc#webflux-multiple-representations[See equivalent in the Reactive stack]# {api-spring-framework}/web/servlet/view/ContentNegotiatingViewResolver.html[`ContentNegotiatingViewResolver`] does not resolve views itself but rather delegates @@ -123,7 +123,7 @@ representation of the current resource regardless of the logical view name. The header can include wildcards (for example `text/{asterisk}`), in which case a `View` whose `Content-Type` is `text/xml` is a compatible match. -See <> under <> for configuration details. +See xref:web/webmvc/mvc-config/view-resolvers.adoc[View Resolvers] under xref:web/webmvc/mvc-config.adoc[MVC Config] for configuration details. diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc index e2cadde805..235652b984 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-uri-building.adoc @@ -1,7 +1,7 @@ [[mvc-uri-building]] = URI Links -[.small]#<># +[.small]#xref:web/webflux/uri-building.adoc[See equivalent in the Reactive stack]# This section describes various options available in the Spring Framework to work with URI's. @@ -95,7 +95,7 @@ as the following example shows: NOTE: As of 5.1, `ServletUriComponentsBuilder` ignores information from the `Forwarded` and `X-Forwarded-*` headers, which specify the client-originated address. Consider using the -<> to extract and use or to discard +xref:web/webmvc/filters.adoc#filters-forwarded-headers[`ForwardedHeaderFilter`] to extract and use or to discard such headers. @@ -221,7 +221,7 @@ following listing uses `withMethodCall`: NOTE: As of 5.1, `MvcUriComponentsBuilder` ignores information from the `Forwarded` and `X-Forwarded-*` headers, which specify the client-originated address. Consider using the -<> to extract and use or to discard +xref:web/webmvc/filters.adoc#filters-forwarded-headers[ForwardedHeaderFilter] to extract and use or to discard such headers. diff --git a/framework-docs/modules/ROOT/pages/web/websocket.adoc b/framework-docs/modules/ROOT/pages/web/websocket.adoc index c429f5fe70..79665ef428 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket.adoc @@ -1,6 +1,6 @@ [[websocket]] = WebSockets -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc[See equivalent in the Reactive stack]# This part of the reference documentation covers support for Servlet stack, WebSocket messaging that includes raw WebSocket interactions, WebSocket emulation through SockJS, and diff --git a/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc b/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc index 477f291c68..f565c2250a 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/fallback.adoc @@ -127,7 +127,7 @@ The following example shows the XML configuration equivalent of the preceding ex ---- The preceding example is for use in Spring MVC applications and should be included in the -configuration of a <>. However, Spring's WebSocket +configuration of a xref:web/webmvc/mvc-servlet.adoc[`DispatcherServlet`]. However, Spring's WebSocket and SockJS support does not depend on Spring MVC. It is relatively simple to integrate into other HTTP serving environments with the help of {api-spring-framework}/web/socket/sockjs/support/SockJsHttpRequestHandler.html[`SockJsHttpRequestHandler`]. @@ -273,7 +273,7 @@ log category to TRACE. [[websocket-fallback-cors]] == SockJS and CORS -If you allow cross-origin requests (see <>), the SockJS protocol +If you allow cross-origin requests (see xref:web/websocket/server.adoc#websocket-server-allowed-origins[Allowed Origins]), the SockJS protocol uses CORS for cross-domain support in the XHR streaming and polling transports. Therefore, CORS headers are added automatically, unless the presence of CORS headers in the response is detected. So, if an application is already configured to provide CORS support (for example, diff --git a/framework-docs/modules/ROOT/pages/web/websocket/server.adoc b/framework-docs/modules/ROOT/pages/web/websocket/server.adoc index a67bbac5fa..653f944dfc 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/server.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/server.adoc @@ -1,7 +1,7 @@ [[websocket-server]] = WebSocket API -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server[See equivalent in the Reactive stack]# The Spring Framework provides a WebSocket API that you can use to write client- and server-side applications that handle WebSocket messages. @@ -10,7 +10,7 @@ server-side applications that handle WebSocket messages. [[websocket-server-handler]] == `WebSocketHandler` -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-handler[See equivalent in the Reactive stack]# Creating a WebSocket server is as simple as implementing `WebSocketHandler` or, more likely, extending either `TextWebSocketHandler` or `BinaryWebSocketHandler`. The following @@ -81,13 +81,13 @@ The following example shows the XML configuration equivalent of the preceding ex ---- The preceding example is for use in Spring MVC applications and should be included -in the configuration of a <>. However, Spring's +in the configuration of a xref:web/webmvc/mvc-servlet.adoc[`DispatcherServlet`]. However, Spring's WebSocket support does not depend on Spring MVC. It is relatively simple to integrate a `WebSocketHandler` into other HTTP-serving environments with the help of {api-spring-framework}/web/socket/server/support/WebSocketHttpRequestHandler.html[`WebSocketHttpRequestHandler`]. When using the `WebSocketHandler` API directly vs indirectly, e.g. through the -<> messaging, the application must synchronize the sending of messages +xref:web/websocket/stomp.adoc[STOMP] messaging, the application must synchronize the sending of messages since the underlying standard WebSocket session (JSR-356) does not allow concurrent sending. One option is to wrap the `WebSocketSession` with {api-spring-framework}/web/socket/handler/ConcurrentWebSocketSessionDecorator.html[`ConcurrentWebSocketSessionDecorator`]. @@ -96,7 +96,7 @@ sending. One option is to wrap the `WebSocketSession` with [[websocket-server-handshake]] == WebSocket Handshake -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-handshake[See equivalent in the Reactive stack]# The easiest way to customize the initial HTTP WebSocket handshake request is through a `HandshakeInterceptor`, which exposes methods for "`before`" and "`after`" the handshake. @@ -149,7 +149,7 @@ the steps of the WebSocket handshake, including validating the client origin, negotiating a sub-protocol, and other details. An application may also need to use this option if it needs to configure a custom `RequestUpgradeStrategy` in order to adapt to a WebSocket server engine and version that is not yet supported -(see <> for more on this subject). +(see xref:web/websocket/server.adoc#websocket-server-deployment[Deployment] for more on this subject). Both the Java configuration and XML namespace make it possible to configure a custom `HandshakeHandler`. @@ -230,7 +230,7 @@ Java initialization API. The following example shows how to do so: [[websocket-server-runtime-configuration]] == Server Configuration -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-config[See equivalent in the Reactive stack]# Each underlying WebSocket engine exposes configuration properties that control runtime characteristics, such as the size of message buffer sizes, idle timeout, @@ -353,7 +353,7 @@ The following example shows the XML configuration equivalent of the preceding ex [[websocket-server-allowed-origins]] == Allowed Origins -[.small]#<># +[.small]#xref:web/webflux-websocket.adoc#webflux-websocket-server-cors[See equivalent in the Reactive stack]# As of Spring Framework 4.1.5, the default behavior for WebSocket and SockJS is to accept only same-origin requests. It is also possible to allow all or a specified list of origins. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc index 49c95b8f0d..a4bcb1fdff 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/benefits.adoc @@ -7,7 +7,7 @@ made about HTTP versus raw TCP and how it lets Spring MVC and other web framewor provide rich functionality. The following is a list of benefits: * No need to invent a custom messaging protocol and message format. -* STOMP clients, including a <> +* STOMP clients, including a xref:web/websocket/stomp/client.adoc[Java client] in the Spring Framework, are available. * You can (optionally) use message brokers (such as RabbitMQ, ActiveMQ, and others) to manage subscriptions and broadcast messages. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc index 03b7a0c283..1eae090212 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/client.adoc @@ -16,7 +16,7 @@ To begin, you can create and configure `WebSocketStompClient`, as the following In the preceding example, you could replace `StandardWebSocketClient` with `SockJsClient`, since that is also an implementation of `WebSocketClient`. The `SockJsClient` can use WebSocket or HTTP-based transport as a fallback. For more details, see -<>. +xref:web/websocket/fallback.adoc#websocket-fallback-sockjs-client[`SockJsClient`]. Next, you can establish a connection and provide a handler for the STOMP session, as the following example shows: @@ -80,7 +80,7 @@ closes the connection). other messages are sent. This can present a challenge when using an external broker since messages with a non-broker destination represent activity but aren't actually forwarded to the broker. In that case you can configure a `TaskScheduler` -when initializing the <> which ensures a +when initializing the xref:web/websocket/stomp/handle-broker-relay.adoc[External Broker] which ensures a heartbeat is forwarded to the broker also when only messages with a non-broker destination are sent. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc index c15c6c4f40..aa0017e093 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/configuration-performance.adoc @@ -11,7 +11,7 @@ on how to reason about scaling. In a messaging application, messages are passed through channels for asynchronous executions that are backed by thread pools. Configuring such an application requires good knowledge of the channels and the flow of messages. Therefore, it is -recommended to review <>. +recommended to review xref:web/websocket/stomp/message-flow.adoc[Flow of Messages]. The obvious place to start is to configure the thread pools that back the `clientInboundChannel` and the `clientOutboundChannel`. By default, both diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc index 10a3dc470f..16dc4ce382 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/enable.adoc @@ -3,7 +3,7 @@ STOMP over WebSocket support is available in the `spring-messaging` and `spring-websocket` modules. Once you have those dependencies, you can expose a STOMP -endpoints, over WebSocket with <>, as the following example shows: +endpoints, over WebSocket with xref:web/websocket/fallback.adoc[SockJS Fallback], as the following example shows: [source,java,indent=0,subs="verbatim,quotes"] ---- @@ -95,8 +95,8 @@ Alternatively, if you connect through WebSocket (without SockJS), you can use th Note that `stompClient` in the preceding example does not need to specify `login` and `passcode` headers. Even if it did, they would be ignored (or, rather, -overridden) on the server side. See <> -and <> for more information on authentication. +overridden) on the server side. See xref:web/websocket/stomp/handle-broker-relay-configure.adoc[Connecting to a Broker] +and xref:web/websocket/stomp/authentication.adoc[Authentication] for more information on authentication. For more example code see: diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc index 6eaf09f96b..7479fd6dc9 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-annotations.adoc @@ -5,9 +5,9 @@ Applications can use annotated `@Controller` classes to handle messages from cli Such classes can declare `@MessageMapping`, `@SubscribeMapping`, and `@ExceptionHandler` methods, as described in the following topics: -* <> -* <> -* <> +* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[`@MessageMapping`] +* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-subscribe-mapping[`@SubscribeMapping`] +* xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-exception-handler[`@MessageExceptionHandler`] [[websocket-stomp-message-mapping]] @@ -22,7 +22,7 @@ By default, the mapping values are Ant-style path patterns (for example `/thing* including support for template variables (for example, pass:q[`/thing/{id}`]). The values can be referenced through `@DestinationVariable` method arguments. Applications can also switch to a dot-separated destination convention for mappings, as explained in -<>. +xref:web/websocket/stomp/destination-separator.adoc[Dots as Separators]. [[supported-method-arguments]] === Supported Method Arguments @@ -80,7 +80,7 @@ same as that of the inbound message but prefixed with `/topic`. You can use the `@SendTo` and `@SendToUser` annotations to customize the destination of the output message. `@SendTo` is used to customize the target destination or to specify multiple destinations. `@SendToUser` is used to direct the output message -to only the user associated with the input message. See <>. +to only the user associated with the input message. See xref:web/websocket/stomp/user-destination.adoc[User Destinations]. You can use both `@SendTo` and `@SendToUser` at the same time on the same method, and both are supported at the class level, in which case they act as a default for methods in the @@ -94,7 +94,7 @@ Note that `@SendTo` and `@SendToUser` are merely a convenience that amounts to u `SimpMessagingTemplate` to send messages. If necessary, for more advanced scenarios, `@MessageMapping` methods can fall back on using the `SimpMessagingTemplate` directly. This can be done instead of, or possibly in addition to, returning a value. -See <>. +See xref:web/websocket/stomp/handle-send.adoc[Sending Messages]. [[websocket-stomp-subscribe-mapping]] @@ -102,7 +102,7 @@ See <>. `@SubscribeMapping` is similar to `@MessageMapping` but narrows the mapping to subscription messages only. It supports the same -<> as `@MessageMapping`. However +xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[method arguments] as `@MessageMapping`. However for the return value, by default, a message is sent directly to the client (through `clientOutboundChannel`, in response to the subscription) and not to the broker (through `brokerChannel`, as a broadcast to matching subscriptions). Adding `@SendTo` or @@ -123,7 +123,7 @@ for some reason. Inbound messages are handled in parallel. There are no guarante a broker or a controller processes a given message first. If the goal is to be notified when a subscription is stored and ready for broadcasts, a client should ask for a receipt if the server supports it (simple broker does not). For example, with the Java -<>, you could do the following to add a receipt: +xref:web/websocket/stomp/client.adoc[STOMP client], you could do the following to add a receipt: [source,java,indent=0,subs="verbatim,quotes"] ---- @@ -143,7 +143,7 @@ receipt if the server supports it (simple broker does not). For example, with th }); ---- -A server side option is <> an +A server side option is xref:web/websocket/stomp/interceptors.adoc[to register] an `ExecutorChannelInterceptor` on the `brokerChannel` and implement the `afterMessageHandled` method that is invoked after messages, including subscriptions, have been handled. @@ -173,13 +173,13 @@ The following example declares an exception through a method argument: `@MessageExceptionHandler` methods support flexible method signatures and support the same method argument types and return values as -<> methods. +xref:web/websocket/stomp/handle-annotations.adoc#websocket-stomp-message-mapping[`@MessageMapping`] methods. Typically, `@MessageExceptionHandler` methods apply within the `@Controller` class (or class hierarchy) in which they are declared. If you want such methods to apply more globally (across controllers), you can declare them in a class marked with `@ControllerAdvice`. This is comparable to the -<> available in Spring MVC. +xref:web/webmvc/mvc-controller/ann-advice.adoc[similar support] available in Spring MVC. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc index 84d61cc03a..853732b600 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay-configure.adoc @@ -16,7 +16,7 @@ values of `guest` and `guest`. NOTE: The STOMP broker relay always sets the `login` and `passcode` headers on every `CONNECT` frame that it forwards to the broker on behalf of clients. Therefore, WebSocket clients -need not set those headers. They are ignored. As the <> +need not set those headers. They are ignored. As the xref:web/websocket/stomp/authentication.adoc[Authentication] section explains, WebSocket clients should instead rely on HTTP authentication to protect the WebSocket endpoint and establish the client identity. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc index 245c85b587..8db28f6dd5 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-broker-relay.adoc @@ -71,7 +71,7 @@ dependencies to your project for TCP connection management. Furthermore, application components (such as HTTP request handling methods, business services, and others) can also send messages to the broker relay, as described -in <>, to broadcast messages to subscribed WebSocket clients. +in xref:web/websocket/stomp/handle-send.adoc[Sending Messages], to broadcast messages to subscribed WebSocket clients. In effect, the broker relay enables robust and scalable message broadcasting. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc index d8803a9802..5be3fdb6ae 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/handle-simple-broker.adoc @@ -7,7 +7,7 @@ destinations. The broker supports path-like destinations, including subscription to Ant-style destination patterns. NOTE: Applications can also use dot-separated (rather than slash-separated) destinations. -See <>. +See xref:web/websocket/stomp/destination-separator.adoc[Dots as Separators]. If configured with a task scheduler, the simple broker supports https://stomp.github.io/stomp-specification-1.2.html#Heart-beating[STOMP heartbeats]. diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc index 8c6d0db145..7a21a1b8d4 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/interceptors.adoc @@ -1,7 +1,7 @@ [[websocket-stomp-interceptors]] = Interception -<> provide notifications for the lifecycle +xref:web/websocket/stomp/application-context-events.adoc[Events] provide notifications for the lifecycle of a STOMP connection but not for every client message. Applications can also register a `ChannelInterceptor` to intercept any message and in any part of the processing chain. The following example shows how to intercept inbound messages from clients: diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc index 119db2b62b..9253817717 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/server-config.adoc @@ -2,7 +2,7 @@ = WebSocket Server To configure the underlying WebSocket server, the information in -<> applies. For Jetty, however you need to set +xref:web/websocket/server.adoc#websocket-server-runtime-configuration[Server Configuration] applies. For Jetty, however you need to set the `HandshakeHandler` and `WebSocketPolicy` through the `StompEndpointRegistry`: [source,java,indent=0,subs="verbatim,quotes"] diff --git a/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc b/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc index 7dd0ceb118..84fef9ffb7 100644 --- a/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc +++ b/framework-docs/modules/ROOT/pages/web/websocket/stomp/user-destination.adoc @@ -11,7 +11,7 @@ at the same time, ensuring no collisions with other users who subscribe to the s destination so that each user can receive unique stock position updates. TIP: When working with user destinations, it is important to configure broker and -application destination prefixes as shown in <>, or otherwise the +application destination prefixes as shown in xref:web/websocket/stomp/enable.adoc[Enable STOMP], or otherwise the broker would handle "/user" prefixed messages that should only be handled by `UserDestinationMessageHandler`.