root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 16 Packages Projects Releases Wiki Activity

Fix some typos and mistakes in ref docs 

Closes gh-27388
This commit is contained in:
Dmitriy Bogdanov 2021-09-10 17:38:42 +04:00 committed by Sam Brannen
parent 674dc2f203
commit c46cc666d6
17 changed files with 134 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/docs/asciidoc/core/core-aop.adoc
View File

@ -366,7 +366,7 @@ the https://www.eclipse.org/aspectj/doc/released/progguide/index.html[AspectJ
Programming Guide] (and, for extensions, the Programming Guide] (and, for extensions, the
https://www.eclipse.org/aspectj/doc/released/adk15notebook/index.html[AspectJ 5 https://www.eclipse.org/aspectj/doc/released/adk15notebook/index.html[AspectJ 5
Developer's Notebook]) or one of the books on AspectJ (such as _Eclipse AspectJ_, by Colyer Developer's Notebook]) or one of the books on AspectJ (such as _Eclipse AspectJ_, by Colyer
et. al., or _AspectJ in Action_, by Ramnivas Laddad). et al., or _AspectJ in Action_, by Ramnivas Laddad).
[[aop-pointcuts-designators]] [[aop-pointcuts-designators]]
@ -893,7 +893,7 @@ scoping). You can include the contextual designators to match based on
join point context or bind that context for use in the advice. Supplying only a join point context or bind that context for use in the advice. Supplying only a
kinded designator or only a contextual designator works but could affect weaving kinded designator or only a contextual designator works but could affect weaving
performance (time and memory used), due to extra processing and analysis. Scoping performance (time and memory used), due to extra processing and analysis. Scoping
designators are very fast to match, and using them usage means AspectJ can very quickly designators are very fast to match, and using them means AspectJ can very quickly
dismiss groups of join points that should not be further processed. A good dismiss groups of join points that should not be further processed. A good
pointcut should always include one if possible. pointcut should always include one if possible.

71
src/docs/asciidoc/core/core-beans.adoc
View File

@ -1024,7 +1024,7 @@ by type without help. Consider the following class:
class ExampleBean( class ExampleBean(
private val years: Int, // Number of years to calculate the Ultimate Answer private val years: Int, // Number of years to calculate the Ultimate Answer
private val ultimateAnswer: String// The Answer to Life, the Universe, and Everything private val ultimateAnswer: String // The Answer to Life, the Universe, and Everything
) )
---- ----
@ -1608,7 +1608,7 @@ listings shows how to use the `parent` attribute:
---- ----
<!-- in the parent context --> <!-- in the parent context -->
<bean id="accountService" class="com.something.SimpleAccountService"> <bean id="accountService" class="com.something.SimpleAccountService">
<!-- insert dependencies as required as here --> <!-- insert dependencies as required here -->
</bean> </bean>
---- ----
@ -1690,7 +1690,7 @@ respectively. The following example shows how to use them:
<property name="someMap"> <property name="someMap">
<map> <map>
<entry key="an entry" value="just some string"/> <entry key="an entry" value="just some string"/>
<entry key ="a ref" value-ref="myDataSource"/> <entry key="a ref" value-ref="myDataSource"/>
</map> </map>
</property> </property>
<!-- results in a setSomeSet(java.util.Set) call --> <!-- results in a setSomeSet(java.util.Set) call -->
@ -1834,7 +1834,7 @@ class SomeClass {
When the `accounts` property of the `something` bean is prepared for injection, the generics When the `accounts` property of the `something` bean is prepared for injection, the generics
information about the element type of the strongly-typed `Map<String, Float>` is information about the element type of the strongly-typed `Map<String, Float>` is
available by reflection. Thus, Spring's type conversion infrastructure recognizes the available by reflection. Thus, Spring's type conversion infrastructure recognizes the
various value elements as being of type `Float`, and the string values (`9.99, 2.75`, and various value elements as being of type `Float`, and the string values (`9.99`, `2.75`, and
`3.99`) are converted into an actual `Float` type. `3.99`) are converted into an actual `Float` type.
@ -2028,7 +2028,7 @@ not commonly used since the plain order of declaration is usually sufficient the
In practice, the constructor resolution In practice, the constructor resolution
<<beans-factory-ctor-arguments-resolution,mechanism>> is quite efficient in matching <<beans-factory-ctor-arguments-resolution,mechanism>> is quite efficient in matching
arguments, so unless you really need to, we recommend using the name notation arguments, so unless you really need to, we recommend using the name notation
through-out your configuration. throughout your configuration.
[[beans-compound-property-names]] [[beans-compound-property-names]]
@ -2503,13 +2503,13 @@ declared return type of the lookup method:
public abstract class CommandManager { public abstract class CommandManager {
public Object process(Object commandState) { public Object process(Object commandState) {
MyCommand command = createCommand(); Command command = createCommand();
command.setState(commandState); command.setState(commandState);
return command.execute(); return command.execute();
} }
@Lookup @Lookup
protected abstract MyCommand createCommand(); protected abstract Command createCommand();
} }
---- ----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
@ -2806,7 +2806,7 @@ prototype-scoped bean repeatedly at runtime. You cannot dependency-inject a
prototype-scoped bean into your singleton bean, because that injection occurs only prototype-scoped bean into your singleton bean, because that injection occurs only
once, when the Spring container instantiates the singleton bean and resolves 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 and injects its dependencies. If you need a new instance of a prototype bean at
runtime more than once, see <<beans-factory-method-injection>> runtime more than once, see <<beans-factory-method-injection>>.
@ -2984,7 +2984,7 @@ The Spring container creates a new instance of the `AppPreferences` bean by usin
`appPreferences` bean is scoped at the `ServletContext` level and stored as a regular `appPreferences` bean is scoped at the `ServletContext` level and stored as a regular
`ServletContext` attribute. This is somewhat similar to a Spring singleton bean but `ServletContext` attribute. This is somewhat similar to a Spring singleton bean but
differs in two important ways: It is a singleton per `ServletContext`, not per Spring differs in two important ways: It is a singleton per `ServletContext`, not per Spring
'ApplicationContext' (for which there may be several in any given web application), `ApplicationContext` (for which there may be several in any given web application),
and it is actually exposed and therefore visible as a `ServletContext` attribute. and it is actually exposed and therefore visible as a `ServletContext` attribute.
When using annotation-driven components or Java configuration, you can use the When using annotation-driven components or Java configuration, you can use the
@ -3100,7 +3100,7 @@ to the HTTP `Session`-scoped bean (`userPreferences`). The salient point here is
`userManager` bean is a singleton: it is instantiated exactly once per `userManager` bean is a singleton: it is instantiated exactly once per
container, and its dependencies (in this case only one, the `userPreferences` bean) are container, and its dependencies (in this case only one, the `userPreferences` bean) are
also injected only once. This means that the `userManager` bean operates only on the also injected only once. This means that the `userManager` bean operates only on the
exact same `userPreferences` object (that is, the one with which it was originally injected. exact same `userPreferences` object (that is, the one with which it was originally injected).
This is not the behavior you want when injecting a shorter-lived scoped bean into a This is not the behavior you want when injecting a shorter-lived scoped bean into a
longer-lived scoped bean (for example, injecting an HTTP `Session`-scoped collaborating longer-lived scoped bean (for example, injecting an HTTP `Session`-scoped collaborating
@ -3928,7 +3928,7 @@ shows the definition of the BeanNameAware interface:
---- ----
The callback is invoked after population of normal bean properties but before an The callback is invoked after population of normal bean properties but before an
initialization callback such as `InitializingBean`, `afterPropertiesSet`, or a custom initialization callback such as `InitializingBean.afterPropertiesSet()` or a custom
init-method. init-method.
@ -3960,7 +3960,7 @@ dependency type. The following table summarizes the most important `Aware` inter
| `BeanFactoryAware` | `BeanFactoryAware`
| Declaring `BeanFactory`. | Declaring `BeanFactory`.
| <<beans-factory-aware>> | <<beans-beanfactory>>
| `BeanNameAware` | `BeanNameAware`
| Name of the declaring bean. | Name of the declaring bean.
@ -4142,7 +4142,7 @@ or it may wrap a bean with a proxy. Some Spring AOP infrastructure classes are
implemented as bean post-processors in order to provide proxy-wrapping logic. implemented as bean post-processors in order to provide proxy-wrapping logic.
An `ApplicationContext` automatically detects any beans that are defined in the An `ApplicationContext` automatically detects any beans that are defined in the
configuration metadata that implements the `BeanPostProcessor` interface. The configuration metadata that implement the `BeanPostProcessor` interface. The
`ApplicationContext` registers these beans as post-processors so that they can be called `ApplicationContext` registers these beans as post-processors so that they can be called
later, upon bean creation. Bean post-processors can be deployed in the container in the later, upon bean creation. Bean post-processors can be deployed in the container in the
same fashion as any other beans. same fashion as any other beans.
@ -4677,7 +4677,7 @@ example:
lateinit var movieFinder: MovieFinder lateinit var movieFinder: MovieFinder
// ... // ...
} }
---- ----
This annotation indicates that the affected bean property must be populated at This annotation indicates that the affected bean property must be populated at
@ -5373,7 +5373,7 @@ Letting qualifier values select against target bean names, within the type-match
candidates, does not require a `@Qualifier` annotation at the injection point. candidates, does not require a `@Qualifier` annotation at the injection point.
If there is no other resolution indicator (such as a qualifier or a primary marker), If there is no other resolution indicator (such as a qualifier or a primary marker),
for a non-unique dependency situation, Spring matches the injection point name for a non-unique dependency situation, Spring matches the injection point name
(that is, the field name or parameter name) against the target bean names and choose the (that is, the field name or parameter name) against the target bean names and chooses the
same-named candidate, if any. same-named candidate, if any.
==== ====
@ -6075,7 +6075,7 @@ will get properties from `application.properties` and `application.yml` files.
Built-in converter support provided by Spring allows simple type conversion (to `Integer` Built-in converter support provided by Spring allows simple type conversion (to `Integer`
or `int` for example) to be automatically handled. Multiple comma-separated values can be or `int` for example) to be automatically handled. Multiple comma-separated values can be
automatically converted to String array without extra effort. automatically converted to `String` array without extra effort.
It is possible to provide a default value as following: It is possible to provide a default value as following:
@ -6099,8 +6099,8 @@ It is possible to provide a default value as following:
class MovieRecommender(@Value("\${catalog.name:defaultCatalog}") private val catalog: String) class MovieRecommender(@Value("\${catalog.name:defaultCatalog}") private val catalog: String)
---- ----
A Spring `BeanPostProcessor` uses a `ConversionService` behind the scene to handle the A Spring `BeanPostProcessor` uses a `ConversionService` behind the scenes to handle the
process for converting the String value in `@Value` to the target type. If you want to process for converting the `String` value in `@Value` to the target type. If you want to
provide conversion support for your own custom type, you can provide your own provide conversion support for your own custom type, you can provide your own
`ConversionService` bean instance as the following example shows: `ConversionService` bean instance as the following example shows:
@ -6315,7 +6315,7 @@ is meta-annotated with `@Component`, as the following example shows:
// ... // ...
} }
---- ----
<1> The `Component` causes `@Service` to be treated in the same way as `@Component`. <1> The `@Component` causes `@Service` to be treated in the same way as `@Component`.
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin .Kotlin
@ -6329,7 +6329,7 @@ is meta-annotated with `@Component`, as the following example shows:
// ... // ...
} }
---- ----
<1> The `Component` causes `@Service` to be treated in the same way as `@Component`. <1> The `@Component` causes `@Service` to be treated in the same way as `@Component`.
You can also combine meta-annotations to create "`composed annotations`". For example, You can also combine meta-annotations to create "`composed annotations`". For example,
the `@RestController` annotation from Spring MVC is composed of `@Controller` and the `@RestController` annotation from Spring MVC is composed of `@Controller` and
@ -6591,7 +6591,7 @@ and using "`stub`" repositories instead:
includeFilters = @Filter(type = FilterType.REGEX, pattern = ".*Stub.*Repository"), includeFilters = @Filter(type = FilterType.REGEX, pattern = ".*Stub.*Repository"),
excludeFilters = @Filter(Repository.class)) excludeFilters = @Filter(Repository.class))
public class AppConfig { public class AppConfig {
... // ...
} }
---- ----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
@ -7157,7 +7157,7 @@ configuration, as shown in the following example:
With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor` With Gradle 4.6 and later, the dependency should be declared in the `annotationProcessor`
configuration, as shown in the following example: configuration, as shown in the following example:
[source,groovy,indent=0subs="verbatim,quotes,attributes"] [source,groovy,indent=0,subs="verbatim,quotes,attributes"]
---- ----
dependencies { dependencies {
annotationProcessor "org.springframework:spring-context-indexer:{spring-version}" annotationProcessor "org.springframework:spring-context-indexer:{spring-version}"
@ -7631,7 +7631,7 @@ to reduce subtle bugs that can be hard to track down when operating in "`lite`"
**** ****
The `@Bean` and `@Configuration` annotations are discussed in depth in the following sections. The `@Bean` and `@Configuration` annotations are discussed in depth in the following sections.
First, however, we cover the various ways of creating a spring container using by First, however, we cover the various ways of creating a spring container by using
Java-based configuration. Java-based configuration.
@ -7758,7 +7758,7 @@ To enable component scanning, you can annotate your `@Configuration` class as fo
@Configuration @Configuration
@ComponentScan(basePackages = "com.acme") // <1> @ComponentScan(basePackages = "com.acme") // <1>
public class AppConfig { public class AppConfig {
... // ...
} }
---- ----
<1> This annotation enables component scanning. <1> This annotation enables component scanning.
@ -7892,6 +7892,7 @@ init-param):
`@Bean` is a method-level annotation and a direct analog of the XML `<bean/>` element. `@Bean` is a method-level annotation and a direct analog of the XML `<bean/>` element.
The annotation supports some of the attributes offered by `<bean/>`, such as: The annotation supports some of the attributes offered by `<bean/>`, such as:
* <<beans-factory-lifecycle-initializingbean, init-method>> * <<beans-factory-lifecycle-initializingbean, init-method>>
* <<beans-factory-lifecycle-disposablebean, destroy-method>> * <<beans-factory-lifecycle-disposablebean, destroy-method>>
* <<beans-factory-autowire,autowiring>> * <<beans-factory-autowire,autowiring>>
@ -7980,7 +7981,7 @@ return type, as the following example shows:
However, this limits the visibility for advance type prediction to the specified However, this limits the visibility for advance type prediction to the specified
interface type (`TransferService`). Then, with the full type (`TransferServiceImpl`) interface type (`TransferService`). Then, with the full type (`TransferServiceImpl`)
known to the container only once, the affected singleton bean has been instantiated. known to the container only once the affected singleton bean has been instantiated.
Non-lazy singleton beans get instantiated according to their declaration order, Non-lazy singleton beans get instantiated according to their declaration order,
so you may see different type matching results depending on when another component so you may see different type matching results depending on when another component
tries to match by a non-declared type (such as `@Autowired TransferServiceImpl`, tries to match by a non-declared type (such as `@Autowired TransferServiceImpl`,
@ -8295,7 +8296,7 @@ as the following example shows:
@Configuration @Configuration
public class AppConfig { public class AppConfig {
@Bean(name = "myThing") @Bean("myThing")
public Thing thing() { public Thing thing() {
return new Thing(); return new Thing();
} }
@ -8388,7 +8389,7 @@ annotation, as the following example shows:
=== Using the `@Configuration` annotation === Using the `@Configuration` annotation
`@Configuration` is a class-level annotation indicating that an object is a source of `@Configuration` is a class-level annotation indicating that an object is a source of
bean definitions. `@Configuration` classes declare beans through `@Bean` annotated bean definitions. `@Configuration` classes declare beans through `@Bean`-annotated
methods. Calls to `@Bean` methods on `@Configuration` classes can also be used to define methods. Calls to `@Bean` methods on `@Configuration` classes can also be used to define
inter-bean dependencies. See <<beans-java-basic-concepts>> for a general introduction. inter-bean dependencies. See <<beans-java-basic-concepts>> for a general introduction.
@ -9137,7 +9138,7 @@ method that returns `true` or `false`. For example, the following listing shows
val attrs = metadata.getAllAnnotationAttributes(Profile::class.java.name) val attrs = metadata.getAllAnnotationAttributes(Profile::class.java.name)
if (attrs != null) { if (attrs != null) {
for (value in attrs["value"]!!) { for (value in attrs["value"]!!) {
if (context.environment.acceptsProfiles(Profiles .of(*value as Array<String>))) { if (context.environment.acceptsProfiles(Profiles.of(*value as Array<String>))) {
return true return true
} }
} }
@ -9901,7 +9902,7 @@ as a way to provide a default definition for one or more beans. If any
profile is enabled, the default profile does not apply. profile is enabled, the default profile does not apply.
You can change the name of the default profile by using `setDefaultProfiles()` on You can change the name of the default profile by using `setDefaultProfiles()` on
the `Environment` or ,declaratively, by using the `spring.profiles.default` property. the `Environment` or, declaratively, by using the `spring.profiles.default` property.
@ -10720,7 +10721,7 @@ following example shows how to do so:
---- ----
It is also possible to add additional runtime filtering by using the `condition` attribute It is also possible to add additional runtime filtering by using the `condition` attribute
of the annotation that defines a <<expressions, `SpEL` expression>> , which should match of the annotation that defines a <<expressions, `SpEL` expression>>, which should match
to actually invoke the method for a particular event. 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 The following example shows how our notifier can be rewritten to be invoked only if the
@ -10832,10 +10833,12 @@ The following example shows how to do so:
Be aware of the following limitations when using asynchronous events: Be aware of the following limitations when using asynchronous events:
* If an asynchronous event listener throws an `Exception`, it is not propagated to the * If an asynchronous event listener throws an `Exception`, it is not propagated to the
caller. See `AsyncUncaughtExceptionHandler` for more details. caller. See
{api-spring-framework}/aop/interceptor/AsyncUncaughtExceptionHandler.html[`AsyncUncaughtExceptionHandler`]
for more details.
* Asynchronous event listener methods cannot publish a subsequent event by returning a * Asynchronous event listener methods cannot publish a subsequent event by returning a
value. If you need to publish another event as the result of the processing, inject an value. If you need to publish another event as the result of the processing, inject an
{api-spring-framework}/aop/interceptor/AsyncUncaughtExceptionHandler.html[`ApplicationEventPublisher`] {api-spring-framework}/context/ApplicationEventPublisher.html[`ApplicationEventPublisher`]
to publish the event manually. to publish the event manually.
@ -11093,8 +11096,8 @@ For a simple deployment of a Spring ApplicationContext as a Java EE RAR file:
. Package . Package
all application classes into a RAR file (which is a standard JAR file with a different all application classes into a RAR file (which is a standard JAR file with a different
file extension). file extension).
.Add all required library JARs into the root of the RAR archive. . Add all required library JARs into the root of the RAR archive.
.Add a . Add a
`META-INF/ra.xml` deployment descriptor (as shown in the {api-spring-framework}/jca/context/SpringContextResourceAdapter.html[javadoc for `SpringContextResourceAdapter`]) `META-INF/ra.xml` deployment descriptor (as shown in the {api-spring-framework}/jca/context/SpringContextResourceAdapter.html[javadoc for `SpringContextResourceAdapter`])
and the corresponding Spring XML bean definition file(s) (typically and the corresponding Spring XML bean definition file(s) (typically
`META-INF/applicationContext.xml`). `META-INF/applicationContext.xml`).

6
src/docs/asciidoc/core/core-databuffer-codec.adoc
View File

@ -12,7 +12,7 @@ APIs as follows:
* <<databuffers-buffer>> represents a byte buffer, which may be * <<databuffers-buffer>> represents a byte buffer, which may be
<<databuffers-buffer-pooled, pooled>>. <<databuffers-buffer-pooled, pooled>>.
* <<databuffers-utils>> offers utility methods for data buffers. * <<databuffers-utils>> offers utility methods for data buffers.
* <<Codecs>> decode or encode streams data buffer streams into higher level objects. * <<Codecs>> decode or encode data buffer streams into higher level objects.
@ -127,9 +127,9 @@ others that prefetch and cache data items internally, or is using operators such
`filter`, `skip`, and others that leave out items, then `filter`, `skip`, and others that leave out items, then
`doOnDiscard(PooledDataBuffer.class, DataBufferUtils::release)` must be added to the `doOnDiscard(PooledDataBuffer.class, DataBufferUtils::release)` must be added to the
composition chain to ensure such buffers are released prior to being discarded, possibly composition chain to ensure such buffers are released prior to being discarded, possibly
also as a result an error or cancellation signal. also as a result of an error or cancellation signal.
. If a `Decoder` holds on to one or more data buffers in any other way, it must . If a `Decoder` holds on to one or more data buffers in any other way, it must
ensure they are released when fully read, or in case an error or cancellation signals that ensure they are released when fully read, or in case of an error or cancellation signals that
take place before the cached data buffers have been read and released. take place before the cached data buffers have been read and released.
Note that `DataBufferUtils#join` offers a safe and efficient way to aggregate a data Note that `DataBufferUtils#join` offers a safe and efficient way to aggregate a data

2
src/docs/asciidoc/core/core-expressions.adoc
View File

@ -357,7 +357,7 @@ the list:
// Turn on: // Turn on:
// - auto null reference initialization // - auto null reference initialization
// - auto collection growing // - auto collection growing
SpelParserConfiguration config = new SpelParserConfiguration(true,true); SpelParserConfiguration config = new SpelParserConfiguration(true, true);
ExpressionParser parser = new SpelExpressionParser(config); ExpressionParser parser = new SpelExpressionParser(config);

9
src/docs/asciidoc/core/core-validation.adoc
View File

@ -382,7 +382,7 @@ properties:
---- ----
The following code snippets show some examples of how to retrieve and manipulate some of The following code snippets show some examples of how to retrieve and manipulate some of
the properties of instantiated `Companies` and `Employees`: the properties of instantiated ``Company``s and ``Employee``s:
[source,java,indent=0,subs="verbatim,quotes",role="primary"] [source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java .Java
@ -629,7 +629,7 @@ Note that all bean factories and application contexts automatically use a number
built-in property editors, through their use of a `BeanWrapper` to built-in property editors, through their use of a `BeanWrapper` to
handle property conversions. The standard property editors that the `BeanWrapper` handle property conversions. The standard property editors that the `BeanWrapper`
registers are listed in the <<beans-beans-conversion, previous section>>. registers are listed in the <<beans-beans-conversion, previous section>>.
Additionally, `ApplicationContexts` also override or add additional editors to handle Additionally, ``ApplicationContext``s also override or add additional editors to handle
resource lookups in a manner appropriate to the specific application context type. resource lookups in a manner appropriate to the specific application context type.
Standard JavaBeans `PropertyEditor` instances are used to convert property values Standard JavaBeans `PropertyEditor` instances are used to convert property values
@ -790,7 +790,7 @@ The following example shows how to create your own `PropertyEditorRegistrar` imp
See also the `org.springframework.beans.support.ResourceEditorRegistrar` for an example See also the `org.springframework.beans.support.ResourceEditorRegistrar` for an example
`PropertyEditorRegistrar` implementation. Notice how in its implementation of the `PropertyEditorRegistrar` implementation. Notice how in its implementation of the
`registerCustomEditors(..)` method ,it creates new instances of each property editor. `registerCustomEditors(..)` method, it creates new instances of each property editor.
The next example shows how to configure a `CustomEditorConfigurer` and inject an instance of our The next example shows how to configure a `CustomEditorConfigurer` and inject an instance of our
`CustomPropertyEditorRegistrar` into it: `CustomPropertyEditorRegistrar` into it:
@ -1347,6 +1347,7 @@ listing shows the definition of the `AnnotationFormatterFactory` interface:
---- ----
To create an implementation: To create an implementation:
. Parameterize A to be the field `annotationType` with which you wish to associate . Parameterize A to be the field `annotationType` with which you wish to associate
formatting logic -- for example `org.springframework.format.annotation.DateTimeFormat`. formatting logic -- for example `org.springframework.format.annotation.DateTimeFormat`.
. Have `getFieldTypes()` return the types of fields on which the annotation can be used. . Have `getFieldTypes()` return the types of fields on which the annotation can be used.
@ -1470,7 +1471,7 @@ The following example uses `@DateTimeFormat` to format a `java.util.Date` as an
.Kotlin .Kotlin
---- ----
class MyModel( class MyModel(
@DateTimeFormat(iso= ISO.DATE) private val date: Date @DateTimeFormat(iso=ISO.DATE) private val date: Date
) )
---- ----

39
src/docs/asciidoc/data-access.adoc
View File

@ -445,7 +445,7 @@ relevant `TransactionManager`.
[[tx-resource-synchronization-high]] [[tx-resource-synchronization-high]]
==== High-level Synchronization Approach ==== High-level Synchronization Approach
The preferred approach is to use Spring's highest-level template based persistence The preferred approach is to use Spring's highest-level template-based persistence
integration APIs or to use native ORM APIs with transaction-aware factory beans or integration APIs or to use native ORM APIs with transaction-aware factory beans or
proxies for managing the native resource factories. These transaction-aware solutions proxies for managing the native resource factories. These transaction-aware solutions
internally handle resource creation and reuse, cleanup, optional transaction internally handle resource creation and reuse, cleanup, optional transaction
@ -1878,7 +1878,7 @@ rollback rules, timeouts, and other features.
==== Transaction Propagation ==== Transaction Propagation
This section describes some semantics of transaction propagation in Spring. Note This section describes some semantics of transaction propagation in Spring. Note
that this section is not an introduction to transaction propagation proper. Rather, it that this section is not a proper introduction to transaction propagation. Rather, it
details some of the semantics regarding transaction propagation in Spring. details some of the semantics regarding transaction propagation in Spring.
In Spring-managed transactions, be aware of the difference between physical and In Spring-managed transactions, be aware of the difference between physical and
@ -2121,7 +2121,7 @@ declarative approach:
<aop:config> <aop:config>
<aop:pointcut id="entryPointMethod" expression="execution(* x.y..*Service.*(..))"/> <aop:pointcut id="entryPointMethod" expression="execution(* x.y..*Service.*(..))"/>
<!-- runs after the profiling advice (c.f. the order attribute) --> <!-- runs after the profiling advice (cf. the order attribute) -->
<aop:advisor advice-ref="txAdvice" pointcut-ref="entryPointMethod" order="2"/> <aop:advisor advice-ref="txAdvice" pointcut-ref="entryPointMethod" order="2"/>
<!-- order value is higher than the profiling aspect --> <!-- order value is higher than the profiling aspect -->
@ -2164,7 +2164,7 @@ container by means of an AspectJ aspect. To do so, first annotate your classes
(and optionally your classes' methods) with the `@Transactional` annotation, (and optionally your classes' methods) with the `@Transactional` annotation,
and then link (weave) your application with the and then link (weave) your application with the
`org.springframework.transaction.aspectj.AnnotationTransactionAspect` defined in the `org.springframework.transaction.aspectj.AnnotationTransactionAspect` defined in the
`spring-aspects.jar` file. You must also configure The aspect with a transaction `spring-aspects.jar` file. You must also configure the aspect with a transaction
manager. You can use the Spring Framework's IoC container to take care of 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 dependency-injecting the aspect. The simplest way to configure the transaction
management aspect is to use the `<tx:annotation-driven/>` element and specify the `mode` management aspect is to use the `<tx:annotation-driven/>` element and specify the `mode`
@ -2585,8 +2585,7 @@ following example shows how to do so:
TransactionStatus status = txManager.getTransaction(def); TransactionStatus status = txManager.getTransaction(def);
try { try {
// put your business logic here // put your business logic here
} } catch (MyException ex) {
catch (MyException ex) {
txManager.rollback(status); txManager.rollback(status);
throw ex; throw ex;
} }
@ -3295,7 +3294,7 @@ For example, it may be better to write the preceding code snippet as follows:
}; };
public List<Actor> findAllActors() { public List<Actor> findAllActors() {
return this.jdbcTemplate.query( "select first_name, last_name from t_actor", actorRowMapper); return this.jdbcTemplate.query("select first_name, last_name from t_actor", actorRowMapper);
} }
---- ----
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
@ -3605,7 +3604,7 @@ variable and the corresponding value that is plugged into the `namedParameters`
variable (of type `MapSqlParameterSource`). variable (of type `MapSqlParameterSource`).
Alternatively, you can pass along named parameters and their corresponding values to a Alternatively, you can pass along named parameters and their corresponding values to a
`NamedParameterJdbcTemplate` instance by using the `Map`-based style.The remaining `NamedParameterJdbcTemplate` instance by using the `Map`-based style. The remaining
methods exposed by the `NamedParameterJdbcOperations` and implemented by the methods exposed by the `NamedParameterJdbcOperations` and implemented by the
`NamedParameterJdbcTemplate` class follow a similar pattern and are not covered here. `NamedParameterJdbcTemplate` class follow a similar pattern and are not covered here.
@ -3743,7 +3742,7 @@ See also <<jdbc-JdbcTemplate-idioms>> for guidelines on using the
==== Using `SQLExceptionTranslator` ==== Using `SQLExceptionTranslator`
`SQLExceptionTranslator` is an interface to be implemented by classes that can translate `SQLExceptionTranslator` is an interface to be implemented by classes that can translate
between `SQLExceptions` and Spring's own `org.springframework.dao.DataAccessException`, between ``SQLException``s and Spring's own `org.springframework.dao.DataAccessException`,
which is agnostic in regard to data access strategy. Implementations can be generic (for which is agnostic in regard to data access strategy. Implementations can be generic (for
example, using SQLState codes for JDBC) or proprietary (for example, using Oracle error example, using SQLState codes for JDBC) or proprietary (for example, using Oracle error
codes) for greater precision. codes) for greater precision.
@ -3801,7 +3800,7 @@ You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example sh
if (sqlEx.errorCode == -12345) { if (sqlEx.errorCode == -12345) {
return DeadlockLoserDataAccessException(task, sqlEx) return DeadlockLoserDataAccessException(task, sqlEx)
} }
return null; return null
} }
} }
---- ----
@ -4034,7 +4033,7 @@ The following example updates a column for a certain primary key:
In the preceding example, In the preceding example,
an SQL statement has placeholders for row parameters. You can pass the parameter values an SQL statement has placeholders for row parameters. You can pass the parameter values
in as varargs or ,alternatively, as an array of objects. Thus, you should explicitly wrap primitives in as varargs or, alternatively, as an array of objects. Thus, you should explicitly wrap primitives
in the primitive wrapper classes, or you should use auto-boxing. in the primitive wrapper classes, or you should use auto-boxing.
@ -4577,7 +4576,7 @@ The following example shows a batch update that uses a batch size of 100:
} }
---- ----
The batch update methods for this call returns an array of `int` arrays that contains an The batch update method for this call returns an array of `int` arrays that contains an
array entry for each batch with an array of the number of affected rows for each update. array entry for each batch with an array of the number of affected rows for each update.
The top-level array's length indicates the number of batches run, and the second level The top-level array's length indicates the number of batches run, and the second level
array's length indicates the number of updates in that batch. The number of updates in array's length indicates the number of updates in that batch. The number of updates in
@ -5173,11 +5172,9 @@ as the following example shows:
---- ----
public class JdbcActorDao implements ActorDao { public class JdbcActorDao implements ActorDao {
private JdbcTemplate jdbcTemplate;
private SimpleJdbcCall funcGetActorName; private SimpleJdbcCall funcGetActorName;
public void setDataSource(DataSource dataSource) { public void setDataSource(DataSource dataSource) {
this.jdbcTemplate = new JdbcTemplate(dataSource);
JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource); JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource);
jdbcTemplate.setResultsMapCaseInsensitive(true); jdbcTemplate.setResultsMapCaseInsensitive(true);
this.funcGetActorName = new SimpleJdbcCall(jdbcTemplate) this.funcGetActorName = new SimpleJdbcCall(jdbcTemplate)
@ -5443,7 +5440,7 @@ example shows such a method:
The `SqlUpdate` class encapsulates an SQL update. As with a query, an update object is The `SqlUpdate` class encapsulates an SQL update. As with a query, an update object is
reusable, and, as with all `RdbmsOperation` classes, an update can have parameters and is reusable, and, as with all `RdbmsOperation` classes, an update can have parameters and is
defined in SQL. This class provides a number of `update(..)` methods analogous to the defined in SQL. This class provides a number of `update(..)` methods analogous to the
`execute(..)` methods of query objects. The `SQLUpdate` class is concrete. It can be `execute(..)` methods of query objects. The `SqlUpdate` class is concrete. It can be
subclassed -- for example, to add a custom update method. subclassed -- for example, to add a custom update method.
However, you do not have to subclass the `SqlUpdate` However, you do not have to subclass the `SqlUpdate`
class, since it can easily be parameterized by setting SQL and declaring parameters. class, since it can easily be parameterized by setting SQL and declaring parameters.
@ -6031,7 +6028,7 @@ limit is 1000.
In addition to the primitive values in the value list, you can create a `java.util.List` In addition to the primitive values in the value list, you can create a `java.util.List`
of object arrays. This list can support multiple expressions being defined for the `in` of object arrays. This list can support multiple expressions being defined for the `in`
clause, such as `select * from T_ACTOR where (id, last_name) in \((1, 'Johnson'), (2, clause, such as `select * from T_ACTOR where (id, last_name) in \((1, 'Johnson'), (2,
'Harrop'\))`. This, of course, requires that your database supports this syntax. 'Harrop'))`. This, of course, requires that your database supports this syntax.
[[jdbc-complex-types]] [[jdbc-complex-types]]
@ -7093,7 +7090,7 @@ databases, you may want multiple `DatabaseClient` instances, which requires mult
instances. instances.
[[r2dbc-auto-generated-keys]] [[r2dbc-auto-generated-keys]]
== Retrieving Auto-generated Keys === Retrieving Auto-generated Keys
`INSERT` statements may generate keys when inserting rows into a table `INSERT` statements may generate keys when inserting rows into a table
that defines an auto-increment or identity column. To get full control over that defines an auto-increment or identity column. To get full control over
@ -7387,7 +7384,9 @@ examples (one for Java configuration and one for XML configuration) show how to
---- ----
@Repository @Repository
class ProductDaoImpl : ProductDao { class ProductDaoImpl : ProductDao {
// class body here... // class body here...
} }
---- ----
@ -7427,7 +7426,7 @@ cover the other ORM technologies and show brief examples.
NOTE: As of Spring Framework 5.3, Spring requires Hibernate ORM 5.2+ for Spring's NOTE: As of Spring Framework 5.3, Spring requires Hibernate ORM 5.2+ for Spring's
`HibernateJpaVendorAdapter` as well as for a native Hibernate `SessionFactory` setup. `HibernateJpaVendorAdapter` as well as for a native Hibernate `SessionFactory` setup.
Is is strongly recommended to go with Hibernate ORM 5.4 for a newly started application. It is strongly recommended to go with Hibernate ORM 5.4 for a newly started application.
For use with `HibernateJpaVendorAdapter`, Hibernate Search needs to be upgraded to 5.11.6. For use with `HibernateJpaVendorAdapter`, Hibernate Search needs to be upgraded to 5.11.6.
@ -7958,7 +7957,7 @@ persistence unit name. The following XML example configures such a bean:
This form of JPA deployment is the simplest and the most limited. You cannot refer to an This form of JPA deployment is the simplest and the most limited. You cannot refer to an
existing JDBC `DataSource` bean definition, and no support for global transactions existing JDBC `DataSource` bean definition, and no support for global transactions
exists. Furthermore, weaving (byte-code transformation) of persistent classes is exists. Furthermore, weaving (byte-code transformation) of persistent classes is
provider-specific, often requiring a specific JVM agent to specified on startup. This provider-specific, often requiring a specific JVM agent to be specified on startup. This
option is sufficient only for stand-alone applications and test environments, for which option is sufficient only for stand-alone applications and test environments, for which
the JPA specification is designed. the JPA specification is designed.
@ -8093,7 +8092,7 @@ more insight regarding the `LoadTimeWeaver` implementations and their setup, eit
generic or customized to various platforms (such as Tomcat, JBoss and WebSphere). generic or customized to various platforms (such as Tomcat, JBoss and WebSphere).
As described in <<core.adoc#aop-aj-ltw-spring, Spring configuration>>, you can configure As described in <<core.adoc#aop-aj-ltw-spring, Spring configuration>>, you can configure
a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation of the 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 `context:load-time-weaver` XML element. Such a global weaver is automatically picked up
by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example
shows the preferred way of setting up a load-time weaver, delivering auto-detection shows the preferred way of setting up a load-time weaver, delivering auto-detection

27
src/docs/asciidoc/integration.adoc
View File

@ -390,7 +390,7 @@ model and corresponding services:
[source,java,indent=0,subs="verbatim,quotes"] [source,java,indent=0,subs="verbatim,quotes"]
---- ----
public class Account implements Serializable{ public class Account implements Serializable {
private String name; private String name;
@ -445,7 +445,7 @@ section of the Spring AMQP reference.
[[remoting-autodection-remote-interfaces]] [[remoting-autodection-remote-interfaces]]
[NOTE] [NOTE]
==== ====
Auto-detection is not implemented for remote interfaces Auto-detection is not implemented for remote interfaces.
The main reason why auto-detection of implemented interfaces does not occur for remote The main reason why auto-detection of implemented interfaces does not occur for remote
interfaces is to avoid opening too many doors to remote callers. The target object might interfaces is to avoid opening too many doors to remote callers. The target object might
@ -514,7 +514,7 @@ Spring provides full support for the standard Java web services APIs:
* Accessing web services using JAX-WS * Accessing web services using JAX-WS
In addition to stock support for JAX-WS in Spring Core, the Spring portfolio also In addition to stock support for JAX-WS in Spring Core, the Spring portfolio also
features http://www.springframework.org/spring-ws[Spring Web Services], which is a solution for features https://projects.spring.io/spring-ws[Spring Web Services], which is a solution for
contract-first, document-driven web services -- highly recommended for building modern, contract-first, document-driven web services -- highly recommended for building modern,
future-proof web services. future-proof web services.
@ -711,7 +711,7 @@ as the following example shows:
---- ----
NOTE: The above is slightly simplified in that JAX-WS requires endpoint interfaces NOTE: The above is slightly simplified in that JAX-WS requires endpoint interfaces
and implementation classes to be annotated with `@WebService`, `@SOAPBinding` etc and implementation classes to be annotated with `@WebService`, `@SOAPBinding`, etc.
annotations. This means that you cannot (easily) use plain Java interfaces and annotations. This means that you cannot (easily) use plain Java interfaces and
implementation classes as JAX-WS endpoint artifacts; you need to annotate them implementation classes as JAX-WS endpoint artifacts; you need to annotate them
accordingly first. Check the JAX-WS documentation for details on those requirements. accordingly first. Check the JAX-WS documentation for details on those requirements.
@ -1610,7 +1610,7 @@ cache size is set to `1`. You can use the `sessionCacheSize` property to increas
cached sessions. Note that the number of actual cached sessions is more than that cached sessions. Note that the number of actual cached sessions is more than that
number, as sessions are cached based on their acknowledgment mode, so there can be up to number, as sessions are cached based on their acknowledgment mode, so there can be up to
four cached session instances (one for each four cached session instances (one for each
acknowledgment mode) when `sessionCacheSize` is set to one . `MessageProducer` and `MessageConsumer` instances are cached within their acknowledgment mode) when `sessionCacheSize` is set to one. `MessageProducer` and `MessageConsumer` instances are cached within their
owning session and also take into account the unique properties of the producers and owning session and also take into account the unique properties of the producers and
consumers when caching. MessageProducers are cached based on their destination. consumers when caching. MessageProducers are cached based on their destination.
MessageConsumers are cached based on a key composed of the destination, selector, MessageConsumers are cached based on a key composed of the destination, selector,
@ -1621,7 +1621,7 @@ noLocal delivery flag, and the durable subscription name (if creating durable co
==== Destination Management ==== Destination Management
Destinations, as `ConnectionFactory` instances, are JMS administered objects that you can store Destinations, as `ConnectionFactory` instances, are JMS administered objects that you can store
and retrieved in JNDI. When configuring a Spring application context, you can use the and retrieve in JNDI. When configuring a Spring application context, you can use the
JNDI `JndiObjectFactoryBean` factory class or `<jee:jndi-lookup>` to perform dependency JNDI `JndiObjectFactoryBean` factory class or `<jee:jndi-lookup>` to perform dependency
injection on your object's references to JMS destinations. However, this strategy injection on your object's references to JMS destinations. However, this strategy
is often cumbersome if there are a large number of destinations in the application or if there is often cumbersome if there are a large number of destinations in the application or if there
@ -1734,7 +1734,7 @@ use a proper cache level in such a case.
This container also has recoverable capabilities when the broker goes down. By default, This container also has recoverable capabilities when the broker goes down. By default,
a simple `BackOff` implementation retries every five seconds. You can specify a simple `BackOff` implementation retries every five seconds. You can specify
a custom `BackOff` implementation for more fine-grained recovery options. See a custom `BackOff` implementation for more fine-grained recovery options. See
api-spring-framework/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example. {api-spring-framework}/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example.
NOTE: Like its sibling (<<jms-mdp-simple, `SimpleMessageListenerContainer`>>), NOTE: Like its sibling (<<jms-mdp-simple, `SimpleMessageListenerContainer`>>),
`DefaultMessageListenerContainer` supports native JMS transactions and allows for `DefaultMessageListenerContainer` supports native JMS transactions and allows for
@ -1747,7 +1747,7 @@ Any such arrangements are significantly more efficient than the alternative:
wrapping your entire processing with an XA transaction (through configuring your wrapping your entire processing with an XA transaction (through configuring your
`DefaultMessageListenerContainer` with an `JtaTransactionManager`) to cover the `DefaultMessageListenerContainer` with an `JtaTransactionManager`) to cover the
reception of the JMS message as well as the execution of the business logic in your reception of the JMS message as well as the execution of the business logic in your
message listener (including database operations etc). message listener (including database operations, etc.).
IMPORTANT: The default `AUTO_ACKNOWLEDGE` mode does not provide proper reliability guarantees. IMPORTANT: The default `AUTO_ACKNOWLEDGE` mode does not provide proper reliability guarantees.
Messages can get lost when listener execution fails (since the provider automatically Messages can get lost when listener execution fails (since the provider automatically
@ -1864,7 +1864,7 @@ content. The overloaded methods `convertAndSend()` and `receiveAndConvert()` met
`JmsTemplate` delegate the conversion process to an instance of the `MessageConverter` `JmsTemplate` delegate the conversion process to an instance of the `MessageConverter`
interface. This interface defines a simple contract to convert between Java objects and interface. This interface defines a simple contract to convert between Java objects and
JMS messages. The default implementation (`SimpleMessageConverter`) supports conversion JMS messages. The default implementation (`SimpleMessageConverter`) supports conversion
between `String` and `TextMessage`, `byte[]` and `BytesMesssage`, and `java.util.Map` between `String` and `TextMessage`, `byte[]` and `BytesMessage`, and `java.util.Map`
and `MapMessage`. By using the converter, you and your application code can focus on the and `MapMessage`. By using the converter, you and your application code can focus on the
business object that is being sent or received through JMS and not be concerned with the business object that is being sent or received through JMS and not be concerned with the
details of how it is represented as a JMS message. details of how it is represented as a JMS message.
@ -4392,7 +4392,7 @@ email when someone places an order:
+ order.getCustomer().getLastName() + order.getCustomer().getLastName()
+ ", thank you for placing order. Your order number is " + ", thank you for placing order. Your order number is "
+ order.getOrderNumber()); + order.getOrderNumber());
try{ try {
this.mailSender.send(msg); this.mailSender.send(msg);
} }
catch (MailException ex) { catch (MailException ex) {
@ -5646,15 +5646,16 @@ compliant caches (such as Ehcache 3.x). See <<cache-plug>> for more information
plugging in other cache stores and providers. plugging in other cache stores and providers.
IMPORTANT: The caching abstraction has no special handling for multi-threaded and IMPORTANT: The caching abstraction has no special handling for multi-threaded and
multi-process environments, as such features are handled by the cache implementation. . multi-process environments, as such features are handled by the cache implementation.
If you have a multi-process environment (that is, an application deployed on several nodes), If you have a multi-process environment (that is, an application deployed on several nodes),
you need to configure your cache provider accordingly. Depending on your use cases, a copy you need to configure your cache provider accordingly. Depending on your use cases, a copy
of the same data on several nodes can be enough. However, if you change the data during of the same data on several nodes can be enough. However, if you change the data during
the course of the application, you may need to enable other propagation mechanisms. the course of the application, you may need to enable other propagation mechanisms.
Caching a particular item is a direct equivalent of the typical get-if-not-found-then- Caching a particular item is a direct equivalent of the typical
proceed-and-put-eventually code blocks found with programmatic cache interaction. get-if-not-found-then-proceed-and-put-eventually code blocks
found with programmatic cache interaction.
No locks are applied, and several threads may try to load the same item concurrently. No locks are applied, and several threads may try to load the same item concurrently.
The same applies to eviction. If several threads are trying to update or evict data The same applies to eviction. If several threads are trying to update or evict data
concurrently, you may use stale data. Certain cache providers offer advanced features concurrently, you may use stale data. Certain cache providers offer advanced features

2
src/docs/asciidoc/overview.adoc
View File

@ -44,7 +44,7 @@ parallel, the Spring WebFlux reactive web framework.
A note about modules: Spring's framework jars allow for deployment to JDK 9's module path A note about modules: Spring's framework jars allow for deployment to JDK 9's module path
("Jigsaw"). For use in Jigsaw-enabled applications, the Spring Framework 5 jars come with ("Jigsaw"). For use in Jigsaw-enabled applications, the Spring Framework 5 jars come with
"Automatic-Module-Name" manifest entries which define stable language-level module names "Automatic-Module-Name" manifest entries which define stable language-level module names
("spring.core", "spring.context" etc) independent from jar artifact names (the jars follow ("spring.core", "spring.context", etc.) independent from jar artifact names (the jars follow
the same naming pattern with "-" instead of ".", e.g. "spring-core" and "spring-context"). the same naming pattern with "-" instead of ".", e.g. "spring-core" and "spring-context").
Of course, Spring's framework jars keep working fine on the classpath on both JDK 8 and 9+. Of course, Spring's framework jars keep working fine on the classpath on both JDK 8 and 9+.

1
src/docs/asciidoc/testing.adoc
View File

@ -503,6 +503,7 @@ The following example shows such a case:
// class body... // class body...
} }
---- ----
<1> Declaring an initializer class.
[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
.Kotlin .Kotlin

6
src/docs/asciidoc/web/integration.adoc
View File

@ -29,12 +29,12 @@ entry points into a server-side application, and it delegates to service objects
(facades) that are defined in a service layer to satisfy business-specific (and (facades) that are defined in a service layer to satisfy business-specific (and
presentation-technology agnostic) use cases. In Spring, these service objects, any other presentation-technology agnostic) use cases. In Spring, these service objects, any other
business-specific objects, data-access objects, and others exist in a distinct "`business business-specific objects, data-access objects, and others exist in a distinct "`business
context`", which contains no web or presentation layer objects (presentation objects context`", which contains no web or presentation layer objects (presentation objects,
,such as Spring MVC controllers, are typically configured in a distinct "`presentation such as Spring MVC controllers, are typically configured in a distinct "`presentation
context`"). This section details how you can configure a Spring container (a context`"). This section details how you can configure a Spring container (a
`WebApplicationContext`) that contains all of the 'business beans' in your application. `WebApplicationContext`) that contains all of the 'business beans' in your application.
Moving on to specifics, all you one need to do is declare a Moving on to specifics, all you need to do is declare a
{api-spring-framework}/web/context/ContextLoaderListener.html[`ContextLoaderListener`] {api-spring-framework}/web/context/ContextLoaderListener.html[`ContextLoaderListener`]
in the standard Java EE servlet `web.xml` file of your web application and add a in the standard Java EE servlet `web.xml` file of your web application and add a
`contextConfigLocation`<context-param/> section (in the same file) that defines which `contextConfigLocation`<context-param/> section (in the same file) that defines which

2
src/docs/asciidoc/web/web-uris.adoc
View File

@ -278,7 +278,7 @@ You can shorten it further still with a full URI template, as the following exam
---- ----
The `WebClient` and the `RestTemplate` expand and encode URI templates internally through The `WebClient` and the `RestTemplate` expand and encode URI templates internally through
the `UriBuilderFactory` strategy. Both can be configured with a custom strategy. the `UriBuilderFactory` strategy. Both can be configured with a custom strategy,
as the following example shows: as the following example shows:
[source,java,indent=0,subs="verbatim,quotes",role="primary"] [source,java,indent=0,subs="verbatim,quotes",role="primary"]

2
src/docs/asciidoc/web/webflux-view.adoc
View File

@ -232,7 +232,7 @@ Java 8+. Using the latest update release available is highly recommended.
line should be added for Kotlin script support. See line should be added for Kotlin script support. See
https://github.com/sdeleuze/kotlin-script-templating[this example] for more detail. https://github.com/sdeleuze/kotlin-script-templating[this example] for more detail.
You need to have the script templating library. One way to do that for Javascript is You need to have the script templating library. One way to do that for JavaScript is
through https://www.webjars.org/[WebJars]. through https://www.webjars.org/[WebJars].

2
src/docs/asciidoc/web/webmvc-cors.adoc
View File

@ -50,7 +50,7 @@ Each `HandlerMapping` can be
{api-spring-framework}/web/servlet/handler/AbstractHandlerMapping.html#setCorsConfigurations-java.util.Map-[configured] {api-spring-framework}/web/servlet/handler/AbstractHandlerMapping.html#setCorsConfigurations-java.util.Map-[configured]
individually with URL pattern-based `CorsConfiguration` mappings. In most cases, applications individually with URL pattern-based `CorsConfiguration` mappings. In most cases, applications
use the MVC Java configuration or the XML namespace to declare such mappings, which results use the MVC Java configuration or the XML namespace to declare such mappings, which results
in a single global map being passed to all `HandlerMappping` instances. in a single global map being passed to all `HandlerMapping` instances.
You can combine global CORS configuration at the `HandlerMapping` level with more You can combine global CORS configuration at the `HandlerMapping` level with more
fine-grained, handler-level CORS configuration. For example, annotated controllers can use fine-grained, handler-level CORS configuration. For example, annotated controllers can use

4
src/docs/asciidoc/web/webmvc-functional.adoc
View File

@ -103,7 +103,7 @@ as the following example shows:
If you register the `RouterFunction` as a bean, for instance by exposing it in a 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 <<webmvc-fn-running>>. `@Configuration` class, it will be auto-detected by the servlet, as explained in <<webmvc-fn-running>>.
@ -475,7 +475,7 @@ For instance, the router function builder offers the method `GET(String, Handler
Besides HTTP method-based mapping, the route builder offers a way to introduce additional Besides HTTP method-based mapping, the route builder offers a way to introduce additional
predicates when mapping to requests. predicates when mapping to requests.
For each HTTP method there is an overloaded variant that takes a `RequestPredicate` as a For each HTTP method there is an overloaded variant that takes a `RequestPredicate` as a
parameter, though which additional constraints can be expressed. parameter, through which additional constraints can be expressed.
[[webmvc-fn-predicates]] [[webmvc-fn-predicates]]

4
src/docs/asciidoc/web/webmvc-view.adoc
View File

@ -615,7 +615,7 @@ Java 8+. Using the latest update release available is highly recommended.
line should be added for Kotlin script support. See line should be added for Kotlin script support. See
https://github.com/sdeleuze/kotlin-script-templating[this example] for more details. https://github.com/sdeleuze/kotlin-script-templating[this example] for more details.
You need to have the script templating library. One way to do that for Javascript is You need to have the script templating library. One way to do that for JavaScript is
through https://www.webjars.org/[WebJars]. through https://www.webjars.org/[WebJars].
@ -1697,7 +1697,7 @@ located in the `WEB-INF/defs` directory. At initialization of the `WebApplicatio
the files are loaded, and the definitions factory are initialized. After that has the files are loaded, and the definitions factory are initialized. After that has
been done, the Tiles included in the definition files can be used as views within your been done, the Tiles included in the definition files can be used as views within your
Spring web application. To be able to use the views, you have to have a `ViewResolver` Spring web application. To be able to use the views, you have to have a `ViewResolver`
as with any other view technology in Spring : typically a convenient `TilesViewResolver`. as with any other view technology in Spring: typically a convenient `TilesViewResolver`.
You can specify locale-specific Tiles definitions by adding an underscore and then You can specify locale-specific Tiles definitions by adding an underscore and then
the locale, as the following example shows: the locale, as the following example shows:

34
src/docs/asciidoc/web/webmvc.adoc
View File

@ -580,12 +580,12 @@ itself, excluding the `contextPath` and any `servletMapping` prefix, if present.
The `servletPath` and `pathInfo` are decoded and that makes them impossible to compare The `servletPath` and `pathInfo` are decoded and that makes them impossible to compare
directly to the full `requestURI` in order to derive the lookupPath and that makes it directly to the full `requestURI` in order to derive the lookupPath and that makes it
necessary to decode the `requestUri`. However this introduces its own issues because the necessary to decode the `requestURI`. However this introduces its own issues because the
path may contain encoded reserved characters such as `"/"` or `";"` that can in turn path may contain encoded reserved characters such as `"/"` or `";"` that can in turn
alter the structure of the path after they are decoded which can also lead to security alter the structure of the path after they are decoded which can also lead to security
issues. In addition, Servlet containers may normalize the `servletPath` to varying issues. In addition, Servlet containers may normalize the `servletPath` to varying
degrees which makes it further impossible to perform `startsWith` comparisons against degrees which makes it further impossible to perform `startsWith` comparisons against
the `requestUri`. the `requestURI`.
This is why it is best to avoid reliance on the `servletPath` which comes with the This is why it is best to avoid reliance on the `servletPath` which comes with the
prefix-based `servletPath` mapping type. If the `DispatcherServlet` is mapped as the prefix-based `servletPath` mapping type. If the `DispatcherServlet` is mapped as the
@ -597,7 +597,7 @@ a `UrlPathHelper` with `alwaysUseFullPath=true` via <<mvc-config-path-matching>>
the MVC config. the MVC config.
Fortunately the default Servlet mapping `"/"` is a good choice. However, there is still Fortunately the default Servlet mapping `"/"` is a good choice. However, there is still
an issue in that the `requestUri` needs to be decoded to make it possible to compare to an issue in that the `requestURI` needs to be decoded to make it possible to compare to
controller mappings. This is again undesirable because of the potential to decode controller mappings. This is again undesirable because of the potential to decode
reserved characters that alter the path structure. If such characters are not expected, reserved characters that alter the path structure. If such characters are not expected,
then you can reject them (like the Spring Security HTTP firewall), or you can configure then you can reject them (like the Spring Security HTTP firewall), or you can configure
@ -787,7 +787,7 @@ The following table provides more details on the `ViewResolver` hierarchy:
you can use the `removeFromCache(String viewName, Locale loc)` method. you can use the `removeFromCache(String viewName, Locale loc)` method.
| `UrlBasedViewResolver` | `UrlBasedViewResolver`
| Simple implementation of the `ViewResolver` interface that affects the direct | Simple implementation of the `ViewResolver` interface that effects the direct
resolution of logical view names to URLs without an explicit mapping definition. resolution of logical view names to URLs without an explicit mapping definition.
This is appropriate if your logical names match the names of your view resources This is appropriate if your logical names match the names of your view resources
in a straightforward manner, without the need for arbitrary mappings. in a straightforward manner, without the need for arbitrary mappings.
@ -1545,8 +1545,8 @@ There are also HTTP method specific shortcut variants of `@RequestMapping`:
The shortcuts are <<mvc-ann-requestmapping-composed>> that are provided because, The shortcuts are <<mvc-ann-requestmapping-composed>> that are provided because,
arguably, most controller methods should be mapped to a specific HTTP method versus 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, using `@RequestMapping`, which, by default, matches to all HTTP methods.
a `@RequestMapping` is still needed at the class level to express shared mappings. A `@RequestMapping` is still needed at the class level to express shared mappings.
The following example has type and method level mappings: The following example has type and method level mappings:
@ -1723,7 +1723,7 @@ one of the following depending on whether use of parsed `PathPattern` is enabled
* {api-spring-framework}/web/util/pattern/PathPattern.html#SPECIFICITY_COMPARATOR[`PathPattern.SPECIFICITY_COMPARATOR`] * {api-spring-framework}/web/util/pattern/PathPattern.html#SPECIFICITY_COMPARATOR[`PathPattern.SPECIFICITY_COMPARATOR`]
* {api-spring-framework}/util/AntPathMatcher.html#getPatternComparator-java.lang.String-[`AntPathMatcher.getPatternComparator(String path)`] * {api-spring-framework}/util/AntPathMatcher.html#getPatternComparator-java.lang.String-[`AntPathMatcher.getPatternComparator(String path)`]
Both help to sorts patterns with more specific ones on top. A pattern is less specific if Both help to sort patterns with more specific ones on top. A pattern is less specific if
it has a lower count of URI variables (counted as 1), single wildcards (counted as 1), it has a lower count of URI variables (counted as 1), single wildcards (counted as 1),
and double wildcards (counted as 2). Given an equal score, the longer pattern is chosen. and double wildcards (counted as 2). Given an equal score, the longer pattern is chosen.
Given the same score and length, the pattern with more URI variables than wildcards is Given the same score and length, the pattern with more URI variables than wildcards is
@ -1752,7 +1752,7 @@ using the `Accept` header should be the preferred choice.
Over time, the use of file name extensions has proven problematic in a variety of ways. Over time, the use of file name extensions has proven problematic in a variety of ways.
It can cause ambiguity when overlain with the use of URI variables, path parameters, and It can cause ambiguity when overlain with the use of URI variables, path parameters, and
URI encoding. Reasoning about URL-based authorization URI encoding. Reasoning about URL-based authorization
and security (see next section for more details) also become more difficult. 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: To completely disable the use of path extensions in versions prior to 5.3, set the following:
@ -2171,7 +2171,7 @@ and others) and is equivalent to `required=false`.
| If a method argument is not matched to any of the earlier values in this table and it is | If a method argument is not matched to any of the earlier values in this table and it is
a simple type (as determined by a simple type (as determined by
{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty],
it is a resolved as a `@RequestParam`. Otherwise, it is resolved as a `@ModelAttribute`. it is resolved as a `@RequestParam`. Otherwise, it is resolved as a `@ModelAttribute`.
|=== |===
@ -2300,7 +2300,7 @@ argument as `@Nullable`.
==== ====
As of 5.3, non-null arguments will be enforced even after type conversion. If your handler As of 5.3, non-null arguments will be enforced even after type conversion. If your handler
method intends to accept a null value as well, either declare your argument as `@Nullable` method intends to accept a null value as well, either declare your argument as `@Nullable`
or mark it as `required=false` in the corresponding `@RequestParam` etc annotation. This is or mark it as `required=false` in the corresponding `@RequestParam`, etc. annotation. This is
a best practice and the recommended solution for regressions encountered in a 5.3 upgrade. a best practice and the recommended solution for regressions encountered in a 5.3 upgrade.
Alternatively, you may specifically handle e.g. the resulting `MissingPathVariableException` Alternatively, you may specifically handle e.g. the resulting `MissingPathVariableException`
@ -2777,8 +2777,8 @@ alternatively, set `@ModelAttribute(binding=false)`, as the following example sh
<1> Setting `@ModelAttribute(binding=false)`. <1> Setting `@ModelAttribute(binding=false)`.
You can automatically apply validation after data binding by adding the You can automatically apply validation after data binding by adding the
`javax.validation.Valid` annotation or Spring's `@Validated` annotation ( `javax.validation.Valid` annotation or Spring's `@Validated` annotation
<<core.adoc#validation-beanvalidation, Bean Validation>> and (<<core.adoc#validation-beanvalidation, Bean Validation>> and
<<core.adoc#validation, Spring validation>>). The following example shows how to do so: <<core.adoc#validation, Spring validation>>). The following example shows how to do so:
[source,java,indent=0,subs="verbatim,quotes",role="primary"] [source,java,indent=0,subs="verbatim,quotes",role="primary"]
@ -2841,7 +2841,7 @@ The following example uses the `@SessionAttributes` annotation:
---- ----
@Controller @Controller
@SessionAttributes("pet") // <1> @SessionAttributes("pet") // <1>
public class EditPetForm { class EditPetForm {
// ... // ...
} }
---- ----
@ -2870,7 +2870,6 @@ storage, as the following example shows:
// ... // ...
} }
} }
}
---- ----
<1> Storing the `Pet` value in the Servlet session. <1> Storing the `Pet` value in the Servlet session.
<2> Clearing the `Pet` value from the Servlet session. <2> Clearing the `Pet` value from the Servlet session.
@ -4357,7 +4356,7 @@ Spring MVC has an extensive integration with Servlet 3.0 asynchronous request
<<mvc-ann-async-processing,processing>>: <<mvc-ann-async-processing,processing>>:
* <<mvc-ann-async-deferredresult, `DeferredResult`>> and <<mvc-ann-async-callable, `Callable`>> * <<mvc-ann-async-deferredresult, `DeferredResult`>> and <<mvc-ann-async-callable, `Callable`>>
return values in controller methods and provide basic support for a single asynchronous return values in controller methods provide basic support for a single asynchronous
return value. return value.
* Controllers can <<mvc-ann-async-http-streaming,stream>> multiple values, including * Controllers can <<mvc-ann-async-http-streaming,stream>> multiple values, including
<<mvc-ann-async-sse, SSE>> and <<mvc-ann-async-output-stream, raw data>>. <<mvc-ann-async-sse, SSE>> and <<mvc-ann-async-output-stream, raw data>>.
@ -4889,7 +4888,7 @@ use case-oriented approach that focuses on the common scenarios:
val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic() val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic()
---- ----
`WebContentGenerator` also accept a simpler `cachePeriod` property (defined in seconds) that `WebContentGenerator` also accepts a simpler `cachePeriod` property (defined in seconds) that
works as follows: works as follows:
* A `-1` value does not generate a `Cache-Control` response header. * A `-1` value does not generate a `Cache-Control` response header.
@ -4941,7 +4940,7 @@ settings to a `ResponseEntity`, as the following example shows:
} }
---- ----
The preceding example sends an 304 (NOT_MODIFIED) response with an empty body if the comparison The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison
to the conditional request headers indicates that the content has not changed. Otherwise, the to the conditional request headers indicates that the content has not changed. Otherwise, the
`ETag` and `Cache-Control` headers are added to the response. `ETag` and `Cache-Control` headers are added to the response.
@ -5104,6 +5103,7 @@ following example shows:
@Configuration @Configuration
@EnableWebMvc @EnableWebMvc
class WebConfig : WebMvcConfigurer { class WebConfig : WebMvcConfigurer {
// Implement configuration methods... // Implement configuration methods...
} }
---- ----

6
src/docs/asciidoc/web/websocket.adoc
View File

@ -1118,7 +1118,7 @@ Contract for sending a message that enables loose coupling between producers and
`SubscribableChannel` that uses an `Executor` for delivering messages. `SubscribableChannel` that uses an `Executor` for delivering messages.
Both the Java configuration (that is, `@EnableWebSocketMessageBroker`) and the XML namespace configuration Both the Java configuration (that is, `@EnableWebSocketMessageBroker`) and the XML namespace configuration
(that is,`<websocket:message-broker>`) use the preceding components to assemble a message (that is, `<websocket:message-broker>`) use the preceding components to assemble a message
workflow. The following diagram shows the components used when the simple built-in message workflow. The following diagram shows the components used when the simple built-in message
broker is enabled: broker is enabled:
@ -1191,7 +1191,7 @@ is established, STOMP frames begin to flow on it.
. The client sends a SUBSCRIBE frame with a destination header of `/topic/greeting`. Once received . The client sends a SUBSCRIBE frame with a destination header of `/topic/greeting`. Once received
and decoded, the message is sent to the `clientInboundChannel` and is then routed to the and decoded, the message is sent to the `clientInboundChannel` and is then routed to the
message broker, which stores the client subscription. message broker, which stores the client subscription.
. The client sends a aSEND frame to `/app/greeting`. The `/app` prefix helps to route it to . The client sends a SEND frame to `/app/greeting`. The `/app` prefix helps to route it to
annotated controllers. After the `/app` prefix is stripped, the remaining `/greeting` annotated controllers. After the `/app` prefix is stripped, the remaining `/greeting`
part of the destination is mapped to the `@MessageMapping` method in `GreetingController`. part of the destination is mapped to the `@MessageMapping` method in `GreetingController`.
. The value returned from `GreetingController` is turned into a Spring `Message` with . The value returned from `GreetingController` is turned into a Spring `Message` with
@ -1768,7 +1768,7 @@ WebSocket and SockJS requests.
Therefore, applications that wish to avoid the use of cookies may not have any good Therefore, applications that wish to avoid the use of cookies may not have any good
alternatives for authentication at the HTTP protocol level. Instead of using cookies, alternatives for authentication at the HTTP protocol level. Instead of using cookies,
they may prefer to authenticate with headers at the STOMP messaging protocol level they may prefer to authenticate with headers at the STOMP messaging protocol level.
Doing so requires two simple steps: Doing so requires two simple steps:
. Use the STOMP client to pass authentication headers at connect time. . Use the STOMP client to pass authentication headers at connect time.