Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Asciidoc revision (chapter declarations, javadoc references, etc)

Browse Source
This commit is contained in:
Juergen Hoeller
2018-10-25 15:15:58 +02:00
parent 67bd3f670f
commit a61d107606
33 changed files with 473 additions and 940 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
src/docs/asciidoc/core/core-aop-api.adoc
View File

@@ -1,8 +1,6 @@
[[aop-api]]
= Spring AOP APIs
The previous chapter described the Spring's support for AOP with
@AspectJ and schema-based aspect definitions. In this chapter, we discuss the lower-level
Spring AOP APIs and the AOP support typically used in Spring 1.2 applications. For new
@@ -14,6 +12,7 @@ in Spring 5.
[[aop-api-pointcuts]]
== Pointcut API in Spring
@@ -129,7 +128,6 @@ Spring provides several convenient pointcut implementations. You can use some of
Others are intended to be subclassed in application-specific pointcuts.
[[aop-api-pointcuts-static]]
==== Static Pointcuts
@@ -198,8 +196,6 @@ pointcut and advice, as the following example shows:
You can use `RegexpMethodPointcutAdvisor` with any `Advice` type.
[[aop-api-pointcuts-attribute-driven]]
===== Attribute-driven Pointcuts
@@ -207,7 +203,6 @@ An important type of static pointcut is a metadata-driven pointcut. This uses th
values of metadata attributes (typically, source-level metadata).
[[aop-api-pointcuts-dynamic]]
==== Dynamic pointcuts
@@ -276,6 +271,7 @@ for example, "`all methods that change instance variables in the target object.`
[[aop-api-advice]]
== Advice API in Spring
@@ -366,7 +362,6 @@ are not currently interoperable between frameworks, and the AOP Alliance does no
currently define pointcut interfaces.
[[aop-api-advice-before]]
==== Before Advice
@@ -425,7 +420,6 @@ The following example shows a before advice in Spring, which counts all method i
TIP: Before advice can be used with any pointcut.
[[aop-api-advice-throws]]
==== Throws Advice
@@ -511,7 +505,6 @@ exception that is incompatible with the target method's signature!_
TIP: Throws advice can be used with any pointcut.
[[aop-api-advice-after-returning]]
==== After Returning Advice
@@ -562,7 +555,6 @@ thrown up the interceptor chain instead of the return value.
TIP: After returning advice can be used with any pointcut.
[[aop-api-advice-introduction]]
==== Introduction Advice
@@ -738,6 +730,8 @@ and stateful mixins.
[[aop-api-advisor]]
== The Advisor API in Spring
@@ -756,6 +750,7 @@ chain.
[[aop-pfb]]
== Using the `ProxyFactoryBean` to Create AOP Proxies
@@ -1085,6 +1080,7 @@ two global advisors:
[[aop-concise-proxy]]
== Concise Proxy Definitions
@@ -1164,6 +1160,7 @@ pre-instantiate it.
[[aop-prog]]
== Creating AOP Proxies Programmatically with the `ProxyFactory`
@@ -1205,6 +1202,7 @@ as you should in general.
[[aop-api-advised]]
== Manipulating Advised Objects
@@ -1298,6 +1296,7 @@ required.
[[aop-autoproxy]]
== Using the "auto-proxy" facility
@@ -1327,7 +1326,6 @@ This section covers the auto-proxy creators provided by the
`org.springframework.aop.framework.autoproxy` package.
[[aop-api-autoproxy]]
==== `BeanNameAutoProxyCreator`
@@ -1435,6 +1433,7 @@ preceding example has a configurable order value. The default setting is unorder
[[aop-targetsource]]
== Using `TargetSource` Implementations
@@ -1552,7 +1551,7 @@ The following listig shows an example configuration:
Note that the target object (`businessObjectTarget` in the preceding example) must be a
prototype. This lets the `PoolingTargetSource` implementation create new instances
of the target to grow the pool as necessary. See the {api-spring-framework}aop/target/AbstractPoolingTargetSource.html[Javadoc of
of the target to grow the pool as necessary. See the {api-spring-framework}aop/target/AbstractPoolingTargetSource.html[javadoc of
`AbstractPoolingTargetSource`] and the concrete subclass you wish to use for information
about its properties. `maxSize` is the most basic and is always guaranteed to be present.
@@ -1661,6 +1660,7 @@ any case, since not unsetting it might result in problematic behavior. Spring's
[[aop-extensibility]]
== Defining New Advice Types
@@ -1674,5 +1674,5 @@ support for new custom advice types be added without changing the core framework
The only constraint on a custom `Advice` type is that it must implement the
`org.aopalliance.aop.Advice` marker interface.
See the {api-spring-framework}/aop/framework/adapter/package-frame.html[`org.springframework.aop.framework.adapter` Javadoc] for further
information.
See the {api-spring-framework}/aop/framework/adapter/package-frame.html[`org.springframework.aop.framework.adapter`]
javadoc for further information.

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

@@ -37,6 +37,7 @@ Spring AOP, and can skip most of this chapter.
[[aop-introduction-defn]]
== AOP Concepts
@@ -115,6 +116,7 @@ multiple objects (such as all business operations in the service layer).
[[aop-introduction-spring-defn]]
== Spring AOP Capabilities and Goals
@@ -175,6 +177,7 @@ style.
[[aop-introduction-proxies]]
== AOP Proxies
@@ -195,6 +198,7 @@ implementation detail actually means.
[[aop-ataspectj]]
== @AspectJ support
@@ -244,7 +248,6 @@ annotation, as the following example shows:
====
[[aop-enable-aspectj-xml]]
==== Enabling @AspectJ Support with XML Configuration
@@ -458,7 +461,6 @@ it is natural and straightforward to identify specific beans by name.
====
[[aop-pointcuts-combining]]
==== Combining Pointcut Expressions
@@ -486,8 +488,6 @@ of any public method.
trading module.
====
It is a best practice to build more complex pointcut expressions out of smaller named
components, as shown earlier. When referring to pointcuts by name, normal Java visibility
rules apply (you can see private pointcuts in the same type, protected pointcuts in the
@@ -824,7 +824,6 @@ match the wildcard expression `*Service`:
====
[[writing-good-pointcuts]]
==== Writing Good Pointcuts
@@ -918,7 +917,6 @@ following example:
====
[[aop-advice-after-returning]]
==== After Returning Advice
@@ -983,7 +981,6 @@ Please note that it is not possible to return a totally different reference when
using after returning advice.
[[aop-advice-after-throwing]]
==== After Throwing Advice
@@ -1072,7 +1069,6 @@ The following example shows how to use after finally advice:
====
[[aop-ataspectj-around-advice]]
==== Around Advice
@@ -1136,7 +1132,6 @@ many times, or not at all within the body of the around advice. All of these are
legal.
[[aop-ataspectj-advice-params]]
==== Advice Parameters
@@ -1161,7 +1156,7 @@ a first parameter of type `ProceedingJoinPoint`, which is a subclass of `JoinPoi
* `getSignature()`: Returns a description of the method that is being advised.
* `toString()`: Prints a useful description of the method being advised.
See the https://www.eclipse.org/aspectj/doc/released/runtime-api/org/aspectj/lang/JoinPoint.html[Javadoc] for more detail.
See the https://www.eclipse.org/aspectj/doc/released/runtime-api/org/aspectj/lang/JoinPoint.html[javadoc] for more detail.
[[aop-ataspectj-advice-params-passing]]
===== Passing Parameters to Advice
@@ -1646,6 +1641,7 @@ expression so that only `@Idempotent` operations match, as follows:
[[aop-schema]]
== Schema-based AOP Support
@@ -1846,7 +1842,6 @@ The schema-based AOP support uses the same five kinds of advice as the @AspectJ
exactly the same semantics.
[[aop-schema-advice-before]]
==== Before Advice
@@ -1899,7 +1894,6 @@ join point matched by the pointcut expression), the `doAccessCheck` method on th
bean is invoked.
[[aop-schema-advice-after-returning]]
==== After Returning Advice
@@ -1957,7 +1951,6 @@ example, you can decleare the method signature as follows:
====
[[aop-schema-advice-after-throwing]]
==== After Throwing Advice
@@ -2015,7 +2008,6 @@ example, the method signature may be declared as follows:
====
[[aop-schema-advice-after-finally]]
==== After (Finally) Advice
@@ -2039,7 +2031,6 @@ by using the `after` element, as the following example shows:
====
[[aop-schema-advice-around]]
==== Around Advice
@@ -2092,7 +2083,6 @@ The implementation of the `doBasicProfiling` advice can be exactly the same as i
====
[[aop-schema-params]]
==== Advice Parameters
@@ -2244,7 +2234,6 @@ ms % Task name
====
[[aop-ordering]]
==== Advice Ordering
@@ -2502,6 +2491,7 @@ pointcut expression so that only `@Idempotent` operations match, as follows:
[[aop-choosing]]
== Choosing which AOP Declaration Style to Use
@@ -2613,6 +2603,7 @@ co-exist without any difficulty.
[[aop-proxying]]
== Proxying Mechanisms
@@ -2823,6 +2814,7 @@ it is not a proxy-based AOP framework.
[[aop-aspectj-programmatic]]
== Programmatic Creation of @AspectJ Proxies
@@ -2855,7 +2847,8 @@ The basic usage for this class is very simple, as the following example shows:
----
====
See the {api-spring-framework}/aop/aspectj/annotation/AspectJProxyFactory.html[Javadoc] for more information.
See the {api-spring-framework}/aop/aspectj/annotation/AspectJProxyFactory.html[javadoc] for more information.
@@ -3058,7 +3051,6 @@ with the container. Doing so results in double initialization, once through the
container and once through the aspect.
[[aop-configurable-testing]]
==== Unit Testing `@Configurable` Objects
@@ -3072,7 +3064,6 @@ see a warning message each time that you construct an `@Configurable` object ind
that it has not been configured by Spring.
[[aop-configurable-container]]
==== Working with Multiple Application Contexts
@@ -3474,7 +3465,6 @@ and then easily exclude from builds of the application being deployed
into UAT or production.
[[aop-aj-ltw-the-aspects]]
==== Aspects
@@ -3484,7 +3474,6 @@ Your aspects are then both valid AspectJ and Spring AOP aspects.
Furthermore, the compiled aspect classes need to be available on the classpath.
[[aop-aj-ltw-aop_dot_xml]]
==== 'META-INF/aop.xml'
@@ -3520,10 +3509,10 @@ adding one or more `java.lang.instrument.ClassFileTransformers` to a `ClassLoade
runtime, which opens the door to all manner of interesting applications, one of which
happens to be the LTW of aspects.
TIP: If you are unfamiliar with the idea of runtime class file transformation, se
the Javadoc API documentation for the `java.lang.instrument` package
before continuing. While that documentation is not comprehensive, at least you can see the
key interfaces and classes (for reference as you read through this section).
TIP: If you are unfamiliar with the idea of runtime class file transformation, see the
javadoc API documentation for the `java.lang.instrument` package before continuing.
While that documentation is not comprehensive, at least you can see the key interfaces
and classes (for reference as you read through this section).
Configuring a `LoadTimeWeaver` for a particular `ApplicationContext` can be as easy as
adding one line. (Note that you almost certainly need to use an
@@ -3660,7 +3649,7 @@ retrieved from the Spring container by using the well known name, `loadTimeWeave
Remember that the `LoadTimeWeaver` exists only as a mechanism for Spring's LTW
infrastructure to add one or more `ClassFileTransformers`. The actual
`ClassFileTransformer` that does the LTW is the `ClassPreProcessorAgentAdapter` (from
the `org.aspectj.weaver.loadtime` package) class. See the class-level Javadoc of the
the `org.aspectj.weaver.loadtime` package) class. See the class-level javadoc of the
`ClassPreProcessorAgentAdapter` class for further details, because the specifics of how
the weaving is actually effected is beyond the scope of this document.
@@ -3774,8 +3763,6 @@ to your artifact a file named `WEB-INF/jboss-scanning.xml` with the following co
----
====
[[aop-aj-ltw-environment-generic]]
===== Generic Java Applications
@@ -3806,11 +3793,11 @@ support) a dedicated LTW.
[[aop-resources]]
== Further Resources
More information on AspectJ can be found on the http://www.eclipse.org/aspectj[AspectJ
website].
More information on AspectJ can be found on the http://www.eclipse.org/aspectj[AspectJ website].
_Eclipse AspectJ_ by Adrian Colyer et. al. (Addison-Wesley, 2005) provides a
comprehensive introduction and reference for the AspectJ language.

11
src/docs/asciidoc/core/core-appendix.adoc
View File

@@ -30,8 +30,9 @@ correct schema so that the tags in the `util` namespace are available to you):
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
__xmlns:util="http://www.springframework.org/schema/util"__ xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
__http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"__> <!-- bean definitions here -->
__http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"__>
<!-- bean definitions here -->
</beans>
----
====
@@ -322,7 +323,7 @@ bean, there is no need to refer to it at all, as the following example shows:
====
You can specifically set the result type in the actual definition. This is not necessary
for most use cases, but it can sometimes be useful. See the Javadoc for more info on
for most use cases, but it can sometimes be useful. See the javadoc for more info on
this feature.
@@ -576,8 +577,9 @@ are available to you):
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
__xmlns:aop="http://www.springframework.org/schema/aop"__ xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
__http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd"__> <!-- bean definitions here -->
__http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd"__>
<!-- bean definitions here -->
</beans>
----
====
@@ -602,8 +604,9 @@ available to you:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
__xmlns:context="http://www.springframework.org/schema/context"__ xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
__http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd"__> <!-- bean definitions here -->
__http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd"__>
<!-- bean definitions here -->
</beans>
----
====

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

@@ -5,6 +5,7 @@ This chapter covers Spring's Inversion of Control (IoC) container.
[[beans-introduction]]
== Introduction to the Spring IoC Container and Beans
@@ -3072,7 +3073,7 @@ To integrate your custom scopes into the Spring container, you need to implement
`org.springframework.beans.factory.config.Scope` interface, which is described in this
section. For an idea of how to implement your own scopes, see the `Scope`
implementations that are supplied with the Spring Framework itself and the
{api-spring-framework}/beans/factory/config/Scope.html[`Scope` Javadoc],
{api-spring-framework}/beans/factory/config/Scope.html[`Scope`] javadoc,
which explains the methods you need to implement in more detail.
The `Scope` interface has four methods to get objects from the scope, remove them from
@@ -3115,7 +3116,7 @@ destroyed or when the specified object in the scope is destroyed:
----
====
See the {api-spring-framework}/beans/factory/config/Scope.html#registerDestructionCallback[Javadoc]
See the {api-spring-framework}/beans/factory/config/Scope.html#registerDestructionCallback[javadoc]
or a Spring scope implementation for more information on destruction callbacks.
The following method obtains the conversation identifier for the underlying scope:
@@ -3963,12 +3964,13 @@ after the Spring container finishes instantiating, configuring, and initializing
you can plug in one or more `BeanPostProcessor` implementations.
You can configure multiple `BeanPostProcessor` instances, and you can control the order
in which these `BeanPostProcessor` instances execute by setting the `order` property. You can
set this property only if the `BeanPostProcessor` implements the `Ordered` interface. If
you write your own `BeanPostProcessor`, you should consider implementing 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
<<beans-factory-programmatically-registering-beanpostprocessors, programmatic
in which these `BeanPostProcessor` instances execute by setting the `order` property.
You can set this property only if the `BeanPostProcessor` implements the `Ordered`
interface. If you write your own `BeanPostProcessor`, you should consider implementing
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 <<beans-factory-programmatically-registering-beanpostprocessors, programmatic
registration of `BeanPostProcessor` instances>>.
[NOTE]
@@ -4184,7 +4186,7 @@ You can configure multiple `BeanFactoryPostProcessor` instances, and you can con
which these `BeanFactoryPostProcessor` instances run by setting the `order` property.
However, you can only set this property if the `BeanFactoryPostProcessor` implements the
`Ordered` interface. If you write your own `BeanFactoryPostProcessor`, you should
consider implementing the `Ordered` interface, too. See the Javadoc of the
consider implementing the `Ordered` interface, too. See the javadoc of the
{api-spring-framework}/beans/factory/config/BeanFactoryPostProcessor.html[`BeanFactoryPostProcessor`] and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces for more details.
[NOTE]
@@ -4302,7 +4304,7 @@ the following three supported integer values:
* `override` (2): Check system properties first, before trying the specified
properties files. This lets system properties override any other property source.
See the {api-spring-framework}/beans/factory/config/PropertyPlaceholderConfigurer.html[`PropertyPlaceholderConfigurer`] Javadoc for more information.
See the {api-spring-framework}/beans/factory/config/PropertyPlaceholderConfigurer.html[`PropertyPlaceholderConfigurer`] javadoc for more information.
[TIP]
=====
@@ -7778,8 +7780,8 @@ method that returns `true` or `false`. For example, the following listing shows
----
====
See the {api-spring-framework}/context/annotation/Conditional.html[
`@Conditional` Javadoc] for more detail.
See the {api-spring-framework}/context/annotation/Conditional.html[`@Conditional`]
javadoc for more detail.
[[beans-java-combining]]
@@ -8617,8 +8619,8 @@ may implement `LoadTimeWeaverAware`, thereby receiving a reference to the load-t
weaver instance. This is particularly useful in combination with
<<data-access.adoc#orm-jpa,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 <<aop-aj-ltw>>.
Consult the {api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`]
javadoc for more detail. For more on AspectJ load-time weaving, see <<aop-aj-ltw>>.
@@ -8863,8 +8865,8 @@ file format but is more flexible than the standard JDK based
`ResourceBundleMessageSource` implementation. In particular, it allows for reading
files from any Spring resource location (not only from the classpath) and supports hot
reloading of bundle property files (while efficiently caching them in between).
See the {api-spring-framework}/context/support/ReloadableResourceBundleMessageSource.html[`ReloadableResourceBundleMessageSource` javadoc]
for details.
See the {api-spring-framework}/context/support/ReloadableResourceBundleMessageSource.html[`ReloadableResourceBundleMessageSource`]
javadoc for details.

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

@@ -9,6 +9,7 @@ platforms (that is, Servlet 3.1+).
== `DataBufferFactory`
The `DataBufferFactory` offers functionality to allocate new data buffers as well as to wrap
@@ -21,9 +22,9 @@ Wrapping does not involve allocation. It decorates the given data with a `DataBu
implementation.
There are two implementation of `DataBufferFactory`: the `NettyDataBufferFactory`
(for Netty platforms, such as Reactor Netty) and
`DefaultDataBufferFactory` (for other platforms, such as
Servlet 3.1+ servers).
(for Netty platforms, such as Reactor Netty) and `DefaultDataBufferFactory`
(for other platforms, such as Servlet 3.1+ servers).
@@ -153,6 +154,7 @@ streaming solution would.
[[codecs]]
== Codecs

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

@@ -54,6 +54,7 @@ The expression language supports the following functionality:
[[expressions-evaluation]]
== Evaluation
@@ -322,19 +323,18 @@ someArray[0].someProperty.someOtherProperty < 0.1
----
====
Because the preceding expression involves array access, some property de-referencing, and numeric operations, the performance
gain can be very noticeable. In an example micro benchmark run of 50000 iterations, it
took 75ms to evaluate by using the interpreter and only 3ms using the compiled version
of the expression.
Because the preceding expression involves array access, some property de-referencing,
and numeric operations, the performance gain can be very noticeable. In an example
micro benchmark run of 50000 iterations, it took 75ms to evaluate by using the
interpreter and only 3ms using the compiled version of the expression.
[[expressions-compiler-configuration]]
==== Compiler Configuration
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 (<<expressions-parser-configuration,discussed earlier>>) or
by using a system property when SpEL usage is embedded inside another component. This section
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 (<<expressions-parser-configuration,discussed earlier>>)
or by using a system property when SpEL usage is embedded inside another component. This section
discusses both of these options.
The compiler can operate in one of three modes, which are captured
@@ -409,6 +409,7 @@ More types of expression will be compilable in the future.
[[expressions-beandef]]
== Expressions in Bean Definitions
@@ -574,6 +575,7 @@ examples show:
[[expressions-language-ref]]
== Language Reference
@@ -596,6 +598,8 @@ topics:
* <<expressions-operator-elvis>>
* <<expressions-operator-safe-navigation>>
[[expressions-ref-literal]]
=== Literal Expressions
@@ -886,7 +890,6 @@ which the expression is embedded (such as in an XML document). The textual equiv
All of the textual operators are case-insensitive.
[[expressions-operators-logical]]
==== Logical Operators
@@ -932,7 +935,6 @@ The following example shows how to use the logical operators
====
[[expressions-operators-mathematical]]
==== Mathematical Operators
@@ -977,7 +979,6 @@ following example shows the mathematical operators in use:
====
[[expressions-assignment]]
==== The Assignment Operator
@@ -1075,7 +1076,6 @@ following example shows how to use variables:
====
[[expressions-this-root]]
==== The `#this` and `#root` Variables
@@ -1457,6 +1457,7 @@ The definition of `TemplateParserContext` follows:
[[expressions-example-classes]]
== Classes Used in the Examples

4
src/docs/asciidoc/core/core-null-safety.adoc
View File

@@ -27,6 +27,7 @@ NOTE: Libraries like Reactor or Spring Data provide null-safe APIs that use this
== Use cases
In addition to providing an explicit declaration for Spring Framework API nullability,
@@ -38,6 +39,9 @@ They are also used to make Spring API null-safe in Kotlin projects, since Kotlin
supports https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details
are available in the <<languages#kotlin-null-safety,Kotlin support documentation>>.
== JSR 305 meta-annotations
Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305]

60
src/docs/asciidoc/core/core-resources.adoc
View File

@@ -14,6 +14,7 @@ Spring. It includes the following topics:
[[resources-introduction]]
== Introduction
@@ -28,6 +29,7 @@ such as a method to check for the existence of the resource being pointed to.
[[resources-resource]]
== The Resource Interface
@@ -114,6 +116,7 @@ wrapped `URL` to do its work.
[[resources-implementations]]
== Built-in Resource Implementations
@@ -163,18 +166,18 @@ to the filesystem. To address this, the various `Resource` implementations alway
resolution as a `java.net.URL`.
A `ClassPathResource` is created by Java code by explicitly using the `ClassPathResource`
constructor but is often created implicitly when you call an API method that
takes a `String` argument meant to represent a path. For the latter case, a
JavaBeans `PropertyEditor` recognizes the special prefix, `classpath:`, on the string
path and creates a `ClassPathResource` in that case.
constructor but is often created implicitly when you call an API method that takes a
`String` argument meant to represent a path. For the latter case, a JavaBeans
`PropertyEditor` recognizes the special prefix, `classpath:`, on the string path and
creates a `ClassPathResource` in that case.
[[resources-implementations-filesystemresource]]
=== `FileSystemResource`
This is a `Resource` implementation for `java.io.File` handles. It supports
resolution as a `File` and as a `URL`.
This is a `Resource` implementation for `java.io.File` and `java.nio.file.Path` handles.
It supports resolution as a `File` and as a `URL`.
@@ -316,6 +319,7 @@ The following table summarizes the strategy for converting `String` objects to `
[[resources-resourceloaderaware]]
== The `ResourceLoaderAware` interface
@@ -360,6 +364,7 @@ annotation. For more information, see <<beans-autowired-annotation>>.
[[resources-as-dependencies]]
== Resources as Dependencies
@@ -411,6 +416,7 @@ The following two examples show how to force a `ClassPathResource` and a
[[resources-app-ctx]]
== Application Contexts and Resource Paths
@@ -470,7 +476,6 @@ Using `FileSystemXmlApplicationContext` loads the bean definitions from the clas
unprefixed paths are still treated as filesystem paths.
[[resources-app-ctx-classpathxml]]
==== Constructing `ClassPathXmlApplicationContext` Instances -- Shortcuts
@@ -506,8 +511,8 @@ files named `services.xml` and `daos.xml` (which are on the classpath) can be in
----
====
See the {api-spring-framework}/jca/context/SpringContextResourceAdapter.html[`ClassPathXmlApplicationContext` Javadoc] for details
on the various constructors.
See the {api-spring-framework}/jca/context/SpringContextResourceAdapter.html[`ClassPathXmlApplicationContext`]
javadoc for details on the various constructors.
@@ -532,7 +537,6 @@ You cannot use the `classpath*:` prefix to construct an actual `Resource`, as
a resource points to just one resource at a time.
[[resources-app-ctx-ant-patterns-in-paths]]
==== Ant-style Patterns
@@ -561,26 +565,23 @@ the wildcards.
[[resources-app-ctx-portability]]
===== Implications on Portability
If the specified path is already a file URL (either implicitly because
the base `ResourceLoader` is a filesystem one or explicitly), wildcarding is guaranteed to work in
a completely portable fashion.
If the specified path is already a file URL (either implicitly because the base
`ResourceLoader` is a filesystem one or explicitly), wildcarding is guaranteed to
work in a completely portable fashion.
If the specified path is a classpath location, the resolver must obtain the last
non-wildcard path segment URL by making a `Classloader.getResource()` call. Since this is just
a node of the path (not the file at the end), it is actually undefined (in the
`ClassLoader` Javadoc) exactly what sort of a URL is returned in this case. In
practice, it is always a `java.io.File` representing the directory (where the classpath
resource resolves to a filesystem location) or a jar URL of some sort w(here the
classpath resource resolves to a jar location). Still, there is a portability concern on
this operation.
non-wildcard path segment URL by making a `Classloader.getResource()` call. Since this
is just a node of the path (not the file at the end), it is actually undefined (in the
`ClassLoader` javadoc) exactly what sort of a URL is returned in this case. In practice,
it is always a `java.io.File` representing the directory (where the classpath resource
resolves to a filesystem location) or a jar URL of some sort (where the classpath resource
resolves to a jar location). Still, there is a portability concern on this operation.
If a jar URL is obtained for the last non-wildcard segment, the resolver must be able to
get a `java.net.JarURLConnection` from it or manually parse the jar URL, to be able to
walk the contents of the jar and resolve the wildcard. This does work in most
environments but fails in others, and we strongly recommend that the wildcard
resolution of resources coming from jars be thoroughly tested in your specific
environment before you rely on it.
walk the contents of the jar and resolve the wildcard. This does work in most environments
but fails in others, and we strongly recommend that the wildcard resolution of resources
coming from jars be thoroughly tested in your specific environment before you rely on it.
[[resources-classpath-wildcards]]
@@ -621,7 +622,6 @@ class loader hierarchy and then, off each resource, the same `PathMatcher` resol
strategy described earlier is used for the wildcard subpath.
[[resources-wildcards-in-path-other-stuff]]
==== Other Notes Relating to Wildcards
@@ -640,10 +640,10 @@ as well, but this is not guaranteed to lead to portable behavior.
[NOTE]
====
The scanning of classpath packages requires the presence of corresponding directory
entries in the classpath. When you build JARs with Ant, do not
activate the files-only switch of the JAR task. Also, classpath directories may not
get exposed based on security policies in some environments -- for example, stand-alone applications on
JDK 1.7.0_45 and higher (which requires 'Trusted-Library' to be set up in your manifests. See
entries in the classpath. When you build JARs with Ant, do not activate the files-only
switch of the JAR task. Also, classpath directories may not get exposed based on security
policies in some environments -- for example, stand-alone applications on JDK 1.7.0_45
and higher (which requires 'Trusted-Library' to be set up in your manifests. See
http://stackoverflow.com/questions/19394570/java-jre-7u45-breaks-classloader-getresources).
On JDK 9's module path (Jigsaw), Spring's classpath scanning generally works as expected.

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

@@ -1,8 +1,6 @@
[[validation]]
= Validation, Data Binding, and Type Conversion
There are pros and cons for considering validation as business logic, and Spring offers
a design for validation (and data binding) that does not exclude either one of them.
Specifically, validation should not be tied to the web tier and should be easy to localize,
@@ -45,6 +43,7 @@ plugging in validation logic without the use of annotations.
[[validator]]
== Validation by Using Spring's Validator Interface
@@ -105,10 +104,10 @@ example implements `Validator` for `Person` instances:
----
====
The `static` `rejectIfEmpty(..)` method on the `ValidationUtils` class
is used to reject the `name` property if it is `null` or the empty string. See
at the {api-spring-framework}/validation/ValidationUtils.html[`ValidationUtils` Javadoc] to see what functionality it provides besides the
example shown previously.
The `static` `rejectIfEmpty(..)` method on the `ValidationUtils` class is used to
reject the `name` property if it is `null` or the empty string. Have a look at the
{api-spring-framework}/validation/ValidationUtils.html[`ValidationUtils`] javadoc
to see what functionality it provides besides the example shown previously.
While it is certainly possible to implement a single `Validator` class to validate each
of the nested objects in a rich object, it may be better to encapsulate the validation
@@ -166,7 +165,8 @@ as the following example shows:
Validation errors are reported to the `Errors` object passed to the validator. In the case
of Spring Web MVC, you can use the `<spring:bind/>` tag to inspect the error messages, but
you can also inspect the `Errors` object yourself. More information about the
methods it offers can be found in the {api-spring-framework}validation/Errors.html[Javadoc].
methods it offers can be found in the {api-spring-framework}validation/Errors.html[javadoc].
@@ -191,14 +191,14 @@ the field name and the second includes the type of the field). This is done as a
convenience to aid developers when targeting error messages.
More information on the `MessageCodesResolver` and the default strategy can be found
in the Javadoc of
{api-spring-framework}/validation/MessageCodesResolver.html[`MessageCodesResolver`]
and
in the javadoc of
{api-spring-framework}/validation/MessageCodesResolver.html[`MessageCodesResolver`] and
{api-spring-framework}/validation/DefaultMessageCodesResolver.html[`DefaultMessageCodesResolver`],
respectively.
[[beans-beans]]
== Bean Manipulation and the `BeanWrapper`
@@ -210,16 +210,16 @@ more information about JavaBeans and the specification, see
http://docs.oracle.com/javase/8/docs/api/java/beans/package-summary.html[javabeans].
One quite important class in the beans package is the `BeanWrapper` interface and its
corresponding implementation (`BeanWrapperImpl`). As quoted from the Javadoc, the
corresponding implementation (`BeanWrapperImpl`). As quoted from the javadoc, the
`BeanWrapper` offers functionality to set and get property values (individually or in
bulk), get property descriptors, and query properties to determine if they are
readable or writable. Also, the `BeanWrapper` offers support for nested properties,
enabling the setting of properties on sub-properties to an unlimited depth. The
`BeanWrapper` also supports the ability to add standard JavaBeans `PropertyChangeListeners`
and `VetoableChangeListeners`, without the need for supporting code in the target class.
Last but not least, the `BeanWrapper` provides support for setting indexed
properties. The `BeanWrapper` usually is not used by application code directly but is used by
the `DataBinder` and the `BeanFactory`.
Last but not least, the `BeanWrapper` provides support for setting indexed properties.
The `BeanWrapper` usually is not used by application code directly but is used by the
`DataBinder` and the `BeanFactory`.
The way the `BeanWrapper` works is partly indicated by its name: it wraps a bean to
perform actions on that bean, such as setting and retrieving properties.
@@ -229,9 +229,9 @@ perform actions on that bean, such as setting and retrieving properties.
[[beans-beans-conventions]]
=== Setting and Getting Basic and Nested Properties
Setting and getting properties is done by using the `setPropertyValue`, `setPropertyValues`,
`getPropertyValue`, and `getPropertyValues` methods that both come with a couple of overloaded variants.
Springs Javadoc describes them all in more detail.
Setting and getting properties is done by using the `setPropertyValue`,
`setPropertyValues`, `getPropertyValue`, and `getPropertyValues` methods which come
with a couple of overloaded variants. Springs javadoc describes them in more detail.
The JavaBeans specification has conventions for indicating properties of an
object. The following table shows some examples of these conventions:
@@ -359,7 +359,7 @@ behavior can be achieved by registering custom editors of type
`java.beans.PropertyEditor`. Registering custom editors on a `BeanWrapper` or,
alternatively, in a specific IoC container (as mentioned in the previous chapter), gives it
the knowledge of how to convert properties to the desired type. For more about
`PropertyEditor`, see https://docs.oracle.com/javase/8/docs/api/java/beans/package-summary.html[the Javadoc of the `java.beans` package from Oracle].
`PropertyEditor`, see https://docs.oracle.com/javase/8/docs/api/java/beans/package-summary.html[the javadoc of the `java.beans` package from Oracle].
A couple of examples where property editing is used in Spring:
@@ -431,8 +431,8 @@ the various `PropertyEditor` implementations that Spring provides:
| Can resolve strings to `java.util.regex.Pattern` objects and vice-versa.
| `PropertiesEditor`
| Can convert strings (formatted with the format defined in the Javadoc
of the `java.util.Properties` class) to `Properties` objects. By default, registered
| Can convert strings (formatted with the format defined in the javadoc of the
`java.util.Properties` class) to `Properties` objects. By default, registered
by `BeanWrapperImpl`.
| `StringTrimmerEditor`
@@ -625,8 +625,6 @@ Finally, the following example shows how to use `CustomEditorConfigurer` to regi
----
====
[[beans-beans-conversion-customeditor-registration-per]]
===== Using `PropertyEditorRegistrar`
@@ -724,6 +722,7 @@ registration code be encapsulated in a class and then shared amongst as many
[[core-convert]]
== Spring Type Conversion
@@ -881,9 +880,9 @@ the target collection type to resolve the collection's element type. This lets e
element in the source array be converted to the collection element type before the
collection is set on the target field.
NOTE: Because `GenericConverter` is a more complex SPI interface, you should use it only when you need it.
Favor `Converter` or `ConverterFactory` for basic type conversion needs.
NOTE: Because `GenericConverter` is a more complex SPI interface, you should use
it only when you need it. Favor `Converter` or `ConverterFactory` for basic type
conversion needs.
[[core-convert-ConditionalGenericConverter-SPI]]
@@ -1067,6 +1066,7 @@ no need to create a specific converter to convert from a `Collection` of `S` to
[[format]]
== Spring Field Formatting
@@ -1387,6 +1387,7 @@ See <<web.adoc#mvc-config-conversion, Conversion and Formatting>> in the Spring
[[format-configuring-formatting-globaldatetimeformat]]
== Configuring a Global Date and Time Format
@@ -1613,7 +1614,6 @@ the Spring Validation API, as the following example shows:
====
[[validation-beanvalidation-spring-constraints]]
==== Configuring Custom Constraints
@@ -1681,10 +1681,10 @@ through a `MethodValidationPostProcessor` bean definition, as follows:
----
====
To be eligible for Spring-driven method validation, all target classes need
to be annotated with Spring's `@Validated` annotation. (Optionally, you can also declare the
validation groups to use.) See the {api-spring-framework}/validation/beanvalidation/MethodValidationPostProcessor.html[`MethodValidationPostProcessor` Javadoc]
for setup details with the Hibernate Validator and Bean Validation 1.1 providers.
To be eligible for Spring-driven method validation, all target classes need to be annotated with
Spring's `@Validated` annotation. (Optionally, you can also declare the validation groups to use.)
See the {api-spring-framework}/validation/beanvalidation/MethodValidationPostProcessor.html[`MethodValidationPostProcessor`]
javadoc for setup details with the Hibernate Validator and Bean Validation 1.1 providers.
[[validation-beanvalidation-spring-other]]
@@ -1693,7 +1693,8 @@ for setup details with the Hibernate Validator and Bean Validation 1.1 providers
The default `LocalValidatorFactoryBean` configuration suffices for most
cases. There are a number of configuration options for various Bean Validation
constructs, from message interpolation to traversal resolution. See the
{api-spring-framework}/validation/beanvalidation/LocalValidatorFactoryBean.html[`LocalValidatorFactoryBean` Javadoc] for more information on these options.
{api-spring-framework}/validation/beanvalidation/LocalValidatorFactoryBean.html[`LocalValidatorFactoryBean`]
javadoc for more information on these options.

1
src/docs/asciidoc/data-access-appendix.adoc
View File

@@ -2,6 +2,7 @@
[[xsd-schemas]]
== XML Schemas

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

@@ -16,6 +16,7 @@ with which the Spring Framework integrates.
[[transaction]]
== Transaction Management
@@ -88,7 +89,6 @@ negatives of EJB in general are so great that this is not an attractive proposit
especially in the face of compelling alternatives for declarative transaction management.
[[transaction-local]]
==== Local Transactions
@@ -102,7 +102,6 @@ single transaction resource.) Another downside is that local transactions are in
to the programming model.
[[transaction-programming-model]]
==== Spring Framework's Consistent Programming Model
@@ -390,7 +389,6 @@ also discusses how transaction synchronization is (optionally) triggered through
relevant `PlatformTransactionManager`.
[[tx-resource-synchronization-high]]
==== High-level Synchronization Approach
@@ -405,7 +403,6 @@ for JDBC access by using the `JdbcTemplate`. These solutions are detailed in sub
chapters of this reference documentation.
[[tx-resource-synchronization-low]]
==== Low-level Synchronization Approach
@@ -449,7 +446,6 @@ with the relevant APIs. For example, if you use the Spring `JdbcTemplate` or
behind the scenes and you need not write any special code.
[[tx-resource-synchronization-tadsp]]
==== `TransactionAwareDataSourceProxy`
@@ -529,7 +525,6 @@ declarative transaction management follows EJB convention (roll back is automati
on unchecked exceptions), it is often useful to customize this behavior.
[[tx-decl-explained]]
==== Understanding the Spring Framework's Declarative Transaction Implementation
@@ -554,7 +549,6 @@ The following images shows a Conceptual view of calling a method on a transactio
image::images/tx.png[]
[[transaction-declarative-first-example]]
==== Example of Declarative Transaction Implementation
@@ -788,7 +782,6 @@ insertFoo(..) method of the DefaultFooService class have been truncated for clar
====
[[transaction-declarative-rolling-back]]
==== Rolling Back a Declarative Transaction
@@ -888,7 +881,6 @@ possible. Programmatic rollback is available should you absolutely need it, but
usage flies in the face of achieving a clean POJO-based architecture.
[[transaction-declarative-diff-tx]]
==== Configuring Different Transactional Semantics for Different Beans
@@ -1009,7 +1001,6 @@ transactional settings:
====
[[transaction-declarative-txadvice-settings]]
==== <tx:advice/> Settings
@@ -1073,7 +1064,6 @@ that are nested within `<tx:advice/>` and `<tx:attributes/>` tags:
|===
[[transaction-declarative-annotations]]
==== Using `@Transactional`
@@ -1148,15 +1138,16 @@ transactional by adding only one line of XML configuration:
<1> The line that makes the bean instance transactional.
====
TIP: You can omit the `transaction-manager` attribute in the `<tx:annotation-driven/>` tag if
the bean name of the `PlatformTransactionManager` that you want to wire in has the name,
TIP: You can omit the `transaction-manager` attribute in the `<tx:annotation-driven/>` tag
if the bean name of the `PlatformTransactionManager` that you want to wire in has the name,
`transactionManager`. If the `PlatformTransactionManager` bean that you want to
dependency-inject has any other name, you have to use the `transaction-manager`
attribute, as in the preceding example.
dependency-inject has any other name, you have to use the `transaction-manager` attribute,
as in the preceding example.
NOTE: If you
use Java-based configuration, the `@EnableTransactionManagement` annotation provides equivalent support . You can add the annotation to a `@Configuration` class.
See the {api-spring-framework}/transaction/annotation/EnableTransactionManagement.html[Javadoc] for full details.
NOTE: If you use Java-based configuration, the `@EnableTransactionManagement` annotation
provides equivalent support . You can add the annotation to a `@Configuration` class.
See the {api-spring-framework}/transaction/annotation/EnableTransactionManagement.html[javadoc]
for full details.
.Method visibility and `@Transactional`
****
@@ -1205,7 +1196,7 @@ any kind of method.
| XML Attribute| Annotation Attribute| Default| Description
| `transaction-manager`
| N/A (See {api-spring-framework}/transaction/annotation/TransactionManagementConfigurer.html[`TransactionManagementConfigurer` Javadoc])
| N/A (see {api-spring-framework}/transaction/annotation/TransactionManagementConfigurer.html[`TransactionManagementConfigurer`] javadoc)
| `transactionManager`
| Name of the transaction manager to use. Required only if the name of the transaction
manager is not `transactionManager`, as in the preceding example.
@@ -1285,8 +1276,6 @@ precedence over the transactional settings defined at the class level.
----
====
[[transaction-declarative-attransactional-settings]]
===== `@Transactional` Settings
@@ -1355,8 +1344,6 @@ transactions, the transaction name is always the fully-qualified class name + `.
`handlePayment(..)` method of the `BusinessService` class started a transaction, the
name of the transaction would be: `com.example.BusinessService.handlePayment`.
[[tx-multiple-tx-mgrs-with-attransactional]]
===== Multiple Transaction Managers with `@Transactional`
@@ -1408,8 +1395,6 @@ transaction managers, differentiated by the `order` and `account` qualifiers. Th
default `<tx:annotation-driven>` target bean name, `transactionManager`, is still
used if no specifically qualified `PlatformTransactionManager` bean is found.
[[tx-custom-attributes]]
===== Custom Shortcut Annotations
@@ -1457,7 +1442,6 @@ In the preceding example, we used the syntax to define the transaction manager q
have included propagation behavior, rollback rules, timeouts, and other features.
[[tx-propagation]]
==== Transaction Propagation
@@ -1468,8 +1452,6 @@ details some of the semantics regarding transaction propagation in Spring.
In Spring-managed transactions, be aware of the difference between physical and
logical transactions, and how the propagation setting applies to this difference.
[[tx-propagation-required]]
===== Understanding `PROPAGATION_REQUIRED`
@@ -1507,8 +1489,6 @@ is not aware) silently marks a transaction as rollback-only, the outer caller st
calls commit. The outer caller needs to receive an `UnexpectedRollbackException` to
indicate clearly that a rollback was performed instead.
[[tx-propagation-requires_new]]
===== Understanding `PROPAGATION_REQUIRES_NEW`
@@ -1523,8 +1503,6 @@ status and with an inner transaction's locks released immediately after its comp
Such an independent inner transaction can also declare its own isolation level, timeout,
and read-only settings and not inherit an outer transaction's characteristics.
[[tx-propagation-nested]]
===== Understanding `PROPAGATION_NESTED`
@@ -1536,7 +1514,6 @@ is typically mapped onto JDBC savepoints, so it works only with JDBC resource
transactions. See Spring's {api-spring-framework}/jdbc/datasource/DataSourceTransactionManager.html[`DataSourceTransactionManager`].
[[transaction-declarative-applying-more-than-just-tx-advice]]
==== Advising Transactional Operations
@@ -1722,7 +1699,6 @@ order value.
You can configure additional aspects in similar fashion.
[[transaction-declarative-aspectj]]
==== Using `@Transactional` with AspectJ
@@ -1789,7 +1765,6 @@ transaction management. The second approach is similar to using the JTA
`UserTransaction` API, although exception handling is less cumbersome.
[[tx-prog-template]]
==== Using the `TransactionTemplate`
@@ -1875,8 +1850,6 @@ Code within the callback can roll the transaction back by calling the
----
====
[[tx-prog-template-settings]]
===== Specifying Transaction Settings
@@ -1933,7 +1906,6 @@ different settings (for example, a different isolation level), you need to creat
two distinct `TransactionTemplate` instances.
[[transaction-programmatic-ptm]]
==== Using the `PlatformTransactionManager`
@@ -2035,8 +2007,10 @@ Spring's transaction abstraction is generally application server-agnostic. Addit
Spring's `JtaTransactionManager` class (which can optionally perform a JNDI lookup for
the JTA `UserTransaction` and `TransactionManager` objects) autodetects the location for
the latter object, which varies by application server. Having access to the JTA
`TransactionManager` allows for enhanced transaction semantics -- in particular, supporting
transaction suspension. See the {api-spring-framework}/transaction/jta/JtaTransactionManager.html[`JtaTransactionManager` Javadoc] for details.
`TransactionManager` allows for enhanced transaction semantics -- in particular,
supporting transaction suspension. See the
{api-spring-framework}/transaction/jta/JtaTransactionManager.html[`JtaTransactionManager`]
javadoc for details.
Spring's `JtaTransactionManager` is the standard choice to run on Java EE application
servers and is known to work on all common servers. Advanced functionality, such as
@@ -2055,7 +2029,6 @@ Rather, they are chosen automatically, with the standard
`JtaTransactionManager` as the default fallback.
[[transaction-application-server-integration-websphere]]
==== IBM WebSphere
@@ -2066,7 +2039,6 @@ Spring-driven transaction suspension (suspend and resume as initiated by
`PROPAGATION_REQUIRES_NEW`) is officially supported by IBM.
[[transaction-application-server-integration-weblogic]]
==== Oracle WebLogic Server
@@ -2085,7 +2057,6 @@ per-transaction isolation levels, and proper resuming of transactions in all cas
This section describes solutions to some commmon problems.
[[transaction-solutions-to-common-problems-wrong-ptm]]
==== Using the Wrong Transaction Manager for a Specific `DataSource`
@@ -2262,6 +2233,7 @@ configure the application context to take advantage of these annotations.
[[jdbc]]
== Data Access with JDBC
@@ -2401,7 +2373,6 @@ including error handling. It includes the following topics:
* <<jdbc-auto-genereted-keys>>
[[jdbc-JdbcTemplate]]
==== Using `JdbcTemplate`
@@ -2437,19 +2408,12 @@ corresponding to the fully qualified class name of the template instance (typica
`JdbcTemplate`, but it may be different if you use a custom subclass of the
`JdbcTemplate` class).
[[jdbc-JdbcTemplate-examples]]
===== Examples of JdbcTemplate class usage
This section provides some examples of `JdbcTemplate` class usage. These examples are
not an exhaustive list of all of the functionality exposed by the `JdbcTemplate`. See
the attendant {api-spring-framework}/jdbc/core/JdbcTemplate.html[Javadoc] for that.
The following sections provide some examples of `JdbcTemplate` usage. These examples
are not an exhaustive list of all of the functionality exposed by the `JdbcTemplate`.
See the attendant {api-spring-framework}/jdbc/core/JdbcTemplate.html[javadoc] for that.
[[jdbc-JdbcTemplate-examples-query]]
====== Querying (`SELECT`)
===== Querying (`SELECT`)
The following query gets the number of rows in a relation:
@@ -2549,10 +2513,8 @@ preceding code snippet as follows:
----
====
[[jdbc-JdbcTemplate-examples-update]]
====== Updating (`INSERT`, `UPDATE`, and `DELETE`) with `JdbcTemplate`
===== Updating (`INSERT`, `UPDATE`, and `DELETE`) with `JdbcTemplate`
You can use the `update(..)` method to perform insert, update, and delete operations.
Parameter values are usually provided as variable argumets or, alternatively, as an object array.
@@ -2593,10 +2555,8 @@ The following example deletes an entry:
----
====
[[jdbc-JdbcTemplate-examples-other]]
====== Other `JdbcTemplate` Operations
===== Other `JdbcTemplate` Operations
You can use the `execute(..)` method to run any arbitrary SQL. Consequently, the
method is often used for DDL statements. It is heavily overloaded with variants that take
@@ -2625,8 +2585,6 @@ The following example invokes a stored procedure:
More sophisticated stored procedure support is <<jdbc-StoredProcedure,covered later>>.
[[jdbc-JdbcTemplate-idioms]]
===== `JdbcTemplate` Best Practices
@@ -2764,7 +2722,6 @@ databases, you may want multiple `JdbcTemplate` instances, which requires multip
configured `JdbcTemplate` instances.
[[jdbc-NamedParameterJdbcTemplate]]
==== Using `NamedParameterJdbcTemplate`
@@ -2911,7 +2868,6 @@ See also <<jdbc-JdbcTemplate-idioms>> for guidelines on using the
`NamedParameterJdbcTemplate` class in the context of an application.
[[jdbc-SQLExceptionTranslator]]
==== Using `SQLExceptionTranslator`
@@ -3007,7 +2963,6 @@ The custom translator is passed a data source in order to look up the error code
`sql-error-codes.xml`.
[[jdbc-statements-executing]]
==== Running Statements
@@ -3039,7 +2994,6 @@ fully functional class that creates a new table:
====
[[jdbc-statements-querying]]
==== Running Queries
@@ -3108,7 +3062,6 @@ The returned list would resemble the following:
====
[[jdbc-updates]]
==== Updating the Database
@@ -3142,7 +3095,6 @@ in as varargs or ,alternatively, as an array of objects. Thus, you should explic
in the primitive wrapper classes, or you should use auto-boxing.
[[jdbc-auto-genereted-keys]]
==== Retrieving Auto-generated Keys
@@ -3194,7 +3146,6 @@ This section covers:
* <<jdbc-DataSourceTransactionManager>>
[[jdbc-datasource]]
==== Using `DataSource`
@@ -3298,7 +3249,6 @@ The following example shows C3P0 configuration:
====
[[jdbc-DataSourceUtils]]
==== Using `DataSourceUtils`
@@ -3307,7 +3257,6 @@ The `DataSourceUtils` class is a convenient and powerful helper class that provi
supports thread-bound connections with, for example, `DataSourceTransactionManager`.
[[jdbc-SmartDataSource]]
==== Implementing `SmartDataSource`
@@ -3317,7 +3266,6 @@ classes that use it query whether the connection should be closed after a given
operation. This usage is efficient when you know that you need to reuse a connection.
[[jdbc-AbstractDataSource]]
==== Extending `AbstractDataSource`
@@ -3327,7 +3275,6 @@ You should extend the `AbstractDataSource` class if you write your own `DataSour
implementation.
[[jdbc-SingleConnectionDataSource]]
==== Using `SingleConnectionDataSource`
@@ -3377,8 +3324,8 @@ participating in Spring managed transactions. It is generally preferable to writ
own new code by using the higher level abstractions for resource management, such as
`JdbcTemplate` or `DataSourceUtils`.
See the {api-spring-framework}/jdbc/datasource/TransactionAwareDataSourceProxy.html[`TransactionAwareDataSourceProxy` Javadoc] for more details.
See the {api-spring-framework}/jdbc/datasource/TransactionAwareDataSourceProxy.html[`TransactionAwareDataSourceProxy`]
javadoc for more details.
[[jdbc-DataSourceTransactionManager]]
@@ -3416,7 +3363,6 @@ prepared statement. By grouping updates into batches, you limit the number of ro
to the database.
[[jdbc-batch-classic]]
==== Basic Batch Operations with `JdbcTemplate`
@@ -3467,7 +3413,6 @@ you interrupt a batch once the input source is exhausted. The `isBatchExhausted`
lets you signal the end of the batch.
[[jdbc-batch-list]]
==== Batch Operations with a List of Objects
@@ -3566,7 +3511,6 @@ that derives the SQL type from the Java-declared property type even for a null v
====
[[jdbc-batch-multi]]
==== Batch Operations with Multiple Batches
@@ -3678,7 +3622,6 @@ names of the table, as defined in the database. This is because we read the meta
to construct the actual insert statement.
[[jdbc-simple-jdbc-insert-2]]
==== Retrieving Auto-generated Keys by Using `SimpleJdbcInsert`
@@ -3726,7 +3669,6 @@ multiple auto-generated columns or the generated values are non-numeric, you can
use a `KeyHolder` that is returned from the `executeAndReturnKeyHolder` method.
[[jdbc-simple-jdbc-insert-3]]
==== Specifying Columns for a `SimpleJdbcInsert`
@@ -3767,7 +3709,6 @@ The execution of the insert is the same as if you had relied on the metadata to
which columns to use.
[[jdbc-simple-jdbc-parameters]]
==== Using `SqlParameterSource` to Provide Parameter Values
@@ -3841,7 +3782,6 @@ As you can see, the configuration is the same. Only the executing code has to ch
use these alternative input classes.
[[jdbc-simple-jdbc-call-1]]
==== Calling a Stored Procedure with `SimpleJdbcCall`
@@ -3960,7 +3900,6 @@ By taking this action, you avoid conflicts in the case used for the names of you
returned `out` parameters.
[[jdbc-simple-jdbc-call-2]]
==== Explicitly Declaring Parameters to Use for a `SimpleJdbcCall`
@@ -4018,7 +3957,6 @@ The execution and end results of the two examples are the same. The second examp
details explicitly rather than relying on metadata.
[[jdbc-params]]
==== How to Define `SqlParameters`
@@ -4057,7 +3995,6 @@ option is to specify an `SqlReturnType` that provides an opportunity to define
customized handling of the return values.
[[jdbc-simple-jdbc-call-3]]
==== Calling a Stored Function by Using `SimpleJdbcCall`
@@ -4120,9 +4057,8 @@ as the following example shows:
----
====
The `executeFunction` method used returns a `String` that contains the return value from the function
call.
The `executeFunction` method used returns a `String` that contains the return value from the
function call.
[[jdbc-simple-jdbc-call-4]]
@@ -4139,8 +4075,8 @@ results must match the order in which you declare the `RowMapper`
implementations. The name specified is still used to store the processed list of results
in the results map that is returned from the `execute` statement.
The next example (for MySQL) uses a stored procedure that takes no IN parameters and returns all
rows from the `t_actor` table:
The next example (for MySQL) uses a stored procedure that takes no IN parameters and returns
all rows from the `t_actor` table:
====
[source,sql,indent=0]
@@ -4153,9 +4089,9 @@ rows from the `t_actor` table:
----
====
To call this procedure, you can declare the `RowMapper`. Because the class to which you want to map
follows the JavaBean rules, you can use a `BeanPropertyRowMapper` that is
created by passing in the required class to map to in the `newInstance` method.
To call this procedure, you can declare the `RowMapper`. Because the class to which you want
to map follows the JavaBean rules, you can use a `BeanPropertyRowMapper` that is created by
passing in the required class to map to in the `newInstance` method.
The following example shows how to do so:
====
@@ -4212,7 +4148,6 @@ you should continue to use these classes.
====
[[jdbc-SqlQuery]]
==== Understanding `SqlQuery`
@@ -4225,7 +4160,6 @@ mapping rows to Java classes. Other implementations that extend `SqlQuery` are
`MappingSqlQueryWithParameters` and `UpdatableSqlQuery`.
[[jdbc-MappingSqlQuery]]
==== Using `MappingSqlQuery`
@@ -4308,7 +4242,6 @@ example shows such a method:
====
[[jdbc-SqlUpdate]]
==== Using `SqlUpdate`
@@ -4353,7 +4286,6 @@ The following example creates a custom update method named `execute`:
====
[[jdbc-StoredProcedure]]
==== Using `StoredProcedure`
@@ -4585,7 +4517,6 @@ Common problems with parameters and data values exist in the different approache
provided by Spring Framework's JDBC support. This section covers how to address them.
[[jdbc-type-information]]
==== Providing SQL Type Information for Parameters
@@ -4608,7 +4539,6 @@ You can provide SQL type information in several ways:
for registering the SQL type for any of the named parameter values.
[[jdbc-lob]]
==== Handling BLOB and CLOB objects
@@ -4714,7 +4644,6 @@ The following example shows how to do so:
====
[[jdbc-in-clause]]
==== Passing in Lists of Values for IN Clause
@@ -4740,7 +4669,6 @@ clause, such as `select * from T_ACTOR where (id, last_name) in \((1, 'Johnson')
'Harrop'\))`. This, of course, requires that your database supports this syntax.
[[jdbc-complex-types]]
==== Handling Complex Types for Stored Procedure Calls
@@ -4843,7 +4771,6 @@ natively. You can also use an extensible API to plug in new embedded database ty
`DataSource` implementations.
[[jdbc-why-embedded-database]]
==== Why Use an Embedded Database?
@@ -4852,7 +4779,6 @@ lightweight nature. Benefits include ease of configuration, quick startup time,
testability, and the ability to rapidly evolve your SQL during development.
[[jdbc-embedded-database-xml]]
==== Creating an Embedded Database by Using Spring XML
@@ -4877,7 +4803,6 @@ embedded database is made available to the Spring container as a bean of type
`javax.sql.DataSource` that can then be injected into data access objects as needed.
[[jdbc-embedded-database-java]]
==== Creating an Embedded Database Programmatically
@@ -4904,8 +4829,8 @@ db.shutdown()
----
====
See the {api-spring-framework}/jdbc/datasource/embedded/EmbeddedDatabaseBuilder.html[Javadoc for `EmbeddedDatabaseBuilder`] for further details on all supported
options.
See the {api-spring-framework}/jdbc/datasource/embedded/EmbeddedDatabaseBuilder.html[javadoc for `EmbeddedDatabaseBuilder`]
for further details on all supported options.
You can also use the `EmbeddedDatabaseBuilder` to create an embedded database by using Java
configuration, as the following example shows:
@@ -4933,7 +4858,6 @@ public class DataSourceConfig {
====
[[jdbc-embedded-database-types]]
==== Selecting the Embedded Database Type
@@ -4944,8 +4868,6 @@ supports. It includes the following topics:
* <<jdbc-embedded-database-using-H2>>
* <<jdbc-embedded-database-using-Derby>>
[[jdbc-embedded-database-using-HSQL]]
===== Using HSQL
@@ -4954,8 +4876,6 @@ explicitly specified. To specify HSQL explicitly, set the `type` attribute of th
`embedded-database` tag to `HSQL`. If you use the builder API, call the
`setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.HSQL`.
[[jdbc-embedded-database-using-H2]]
===== Using H2
@@ -4963,8 +4883,6 @@ Spring supports the H2 database. To enable H2, set the `type` attribute of the
`embedded-database` tag to `H2`. If you use the builder API, call the
`setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.H2`.
[[jdbc-embedded-database-using-Derby]]
===== Using Derby
@@ -4973,7 +4891,6 @@ attribute of the `embedded-database` tag to `DERBY`. If you use the builder API,
call the `setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.DERBY`.
[[jdbc-embedded-database-dao-testing]]
==== Testing Data Access Logic with an Embedded Database
@@ -5020,7 +4937,6 @@ Framework>> and configuring the embedded database as a bean in the Spring
====
[[jdbc-embedded-database-unique-names]]
==== Generating Unique Names for Embedded Databases
@@ -5052,7 +4968,6 @@ the following options.
* `<jdbc:embedded-database generate-name="true" ... >`
[[jdbc-embedded-database-extension]]
==== Extending the Embedded Database Support
@@ -5076,7 +4991,6 @@ and initializing a `DataSource` for an application. However, you may sometimes n
an instance that runs on a server somewhere.
[[jdbc-initializing-datasource-xml]]
==== Initializing a Database by Using Spring XML
@@ -5175,8 +5089,6 @@ is `@@` and overrides that default for the `db-schema` script.
If you need more control than you get from the XML namespace, you can use the
`DataSourceInitializer` directly and define it as a component in your application.
[[jdbc-client-component-initialization]]
===== Initialization of Other Components that Depend on the Database
@@ -5227,6 +5139,7 @@ Ensuring that the database initializer is initialized first can also be easy. So
[[orm]]
== Object Relational Mapping (ORM) Data Access
@@ -5322,7 +5235,6 @@ transaction managers, business services that use the data access objects and tra
managers, web view resolvers, web controllers that use the business services, and so on.
[[orm-resource-mngmnt]]
==== Resource and Transaction Management
@@ -5418,7 +5330,6 @@ Note that the Hibernate team does not maintain any versions prior to 5.1 anymore
is likely to focus on 5.3+ exclusively soon.
[[orm-session-factory-setup]]
==== `SessionFactory` Setup in a Spring Container
@@ -5498,7 +5409,6 @@ See <<orm-jpa-hibernate,Native Hibernate Setup for JPA>> for details.
====
[[orm-hibernate-straight]]
==== Implementing DAOs Based on the Plain Hibernate API
@@ -5579,7 +5489,6 @@ In summary, you can implement DAOs based on the plain Hibernate API, while still
able to participate in Spring-managed transactions.
[[orm-hibernate-tx-declarative]]
==== Declarative Transaction Demarcation
@@ -5663,7 +5572,6 @@ opting into `@Transactional` processing at runtime. The following example shows
====
[[orm-hibernate-tx-programmatic]]
==== Programmatic Transaction Demarcation
@@ -5724,11 +5632,10 @@ and an example for a business method implementation:
Spring's `TransactionInterceptor` lets any checked application exception be thrown
with the callback code, while `TransactionTemplate` is restricted to unchecked
exceptions within the callback. `TransactionTemplate` triggers a rollback in case of an
unchecked application exception or if the transaction is marked rollback-only by the
application (by setting `TransactionStatus`). By default, `TransactionInterceptor` behaves the same way
but allows configurable rollback policies per method.
exceptions within the callback. `TransactionTemplate` triggers a rollback in case of
an unchecked application exception or if the transaction is marked rollback-only by
the application (by setting `TransactionStatus`). By default, `TransactionInterceptor`
behaves the same way but allows configurable rollback policies per method.
[[orm-hibernate-tx-strategies]]
@@ -5769,7 +5676,6 @@ exposes the Hibernate transaction as a JDBC transaction if you have set up the p
`dataSource` property of the `HibernateTransactionManager` class.
[[orm-hibernate-resources]]
==== Comparing Container-managed and Locally Defined Resources
@@ -5816,7 +5722,6 @@ Hibernate `SessionFactory` through the JCA connector adds value only when used i
conjunction with EJBs.
[[orm-hibernate-invalid-jdbc-access-error]]
==== Spurious Application Server Warnings with Hibernate
@@ -5898,7 +5803,6 @@ API] in a manner similar to the integration with Hibernate while being aware of
the underlying implementation in order to provide additional features.
[[orm-jpa-setup]]
==== Three Options for JPA Setup in a Spring Environment
@@ -5909,8 +5813,6 @@ that is used by the application to obtain an entity manager.
* <<orm-jpa-setup-jndi>>
* <<orm-jpa-setup-lcemfb>>
[[orm-jpa-setup-lemfb]]
===== Using `LocalEntityManagerFactoryBean`
@@ -5942,8 +5844,6 @@ provider-specific, often requiring a specific JVM agent to specified on startup.
option is sufficient only for stand-alone applications and test environments, for which
the JPA specification is designed.
[[orm-jpa-setup-jndi]]
===== Obtaining an EntityManagerFactory from JNDI
@@ -5982,8 +5882,6 @@ JNDI-retrieved persistence units should match the persistence unit names that th
application uses to refer to them (for example, in `@PersistenceUnit` and
`@PersistenceContext` annotations).
[[orm-jpa-setup-lcemfb]]
===== Using `LocalContainerEntityManagerFactoryBean`
@@ -6126,8 +6024,6 @@ This is especially important when the hosting applications rely on different JPA
implementations, because the JPA transformers are applied only at the class-loader level and
are, thus, isolated from each other.
[[orm-jpa-setup-multiple]]
===== Dealing with Multiple Persistence Units
@@ -6175,8 +6071,6 @@ affect all hosted units) or programmatically (through the
`PersistenceUnitManager` is specified, one is created and used internally by
`LocalContainerEntityManagerFactoryBean`.
[[orm-jpa-setup-background]]
===== Background Bootstrapping
@@ -6204,7 +6098,6 @@ block until the background bootstrapping has completed. In particular, when you
Spring Data JPA, make sure to set up deferred bootstrapping for its repositories as well.
[[orm-jpa-dao]]
==== Implementing DAOs Based on JPA: `EntityManagerFactory` and `EntityManager`
@@ -6351,7 +6244,6 @@ the injections are applied automatically by the Spring container. This is appeal
a non-invasiveness perspective and can feel more natural to JPA developers.
[[orm-jpa-tx]]
==== Spring-driven JPA transactions
@@ -6376,7 +6268,6 @@ This makes particular sense in combination with `LocalSessionFactoryBean` setup.
See <<orm-jpa-hibernate,Native Hibernate Setup for JPA Interaction>> for details.
[[orm-jpa-dialect]]
==== Understanding `JpaDialect` and `JpaVendorAdapter`
@@ -6403,9 +6294,9 @@ way of auto-configuring an `EntityManagerFactory` setup for Hibernate or Eclipse
respectively. Note that those provider adapters are primarily designed for use with
Spring-driven transaction management (that is, for use with `JpaTransactionManager`).
See the {api-spring-framework}/orm/jpa/JpaDialect.html[`JpaDialect`] and {api-spring-framework}/orm/jpa/JpaVendorAdapter.html[`JpaVendorAdapter`] Javadoc for more details of its operations
and how they are used within Spring's JPA support.
See the {api-spring-framework}/orm/jpa/JpaDialect.html[`JpaDialect`] and
{api-spring-framework}/orm/jpa/JpaVendorAdapter.html[`JpaVendorAdapter`] javadoc for
more details of its operations and how they are used within Spring's JPA support.
[[orm-jpa-jta]]
@@ -6443,7 +6334,6 @@ might require special definitions in your server configuration (making the deplo
less portable) but is set up for the server's JTA environment.
[[orm-jpa-hibernate]]
==== Native Hibernate Setup and Native Hibernate Transactions for JPA Interaction
@@ -6481,6 +6371,7 @@ property. On the programmatic `LocalSessionFactoryBuilder`, an overloaded
[[oxm]]
== Marshalling XML by Using Object-XML Mappers
@@ -6506,7 +6397,6 @@ Some of the benefits of using Spring for your O/X mapping needs are:
* <<oxm-consistent-exception-hierarchy>>
[[oxm-ease-of-configuration]]
==== Ease of configuration
@@ -6517,7 +6407,6 @@ configuration is available for a number of marshallers, making the configuration
simpler.
[[oxm-consistent-interfaces]]
==== Consistent Interfaces
@@ -6530,7 +6419,6 @@ and some by Castor) in a non-intrusive fashion, letting you use the strength of
technology.
[[oxm-consistent-exception-hierarchy]]
==== Consistent Exception Hierarchy
@@ -6548,7 +6436,6 @@ unmarshaller deserializes XML stream to an object. This section describes
the two Spring interfaces used for this purpose.
[[oxm-marshaller]]
==== Understanding `Marshaller`
@@ -6595,7 +6482,6 @@ marshaller, or have a common base class. Refer to the later sections in this cha
to determine how your O-X technology manages this.
[[oxm-unmarshaller]]
==== Understanding `Unmarshaller`
@@ -6641,7 +6527,6 @@ This means that you can wire up one marshaller class and refer to it both as a
marshaller and as an unmarshaller in your `applicationContext.xml`.
[[oxm-xmlmappingexception]]
==== Understanding `XmlMappingException`
@@ -6846,7 +6731,6 @@ The corresponding integration classes reside in the `org.springframework.oxm.jax
package.
[[oxm-jaxb2]]
==== Using `Jaxb2Marshaller`
@@ -6878,8 +6762,6 @@ validation is performed by specifying one or more schema resources to the bean,
----
====
[[oxm-jaxb2-xsd]]
===== XML Configuration Namespace
@@ -6938,7 +6820,6 @@ http://castor-data-binding.github.io/castor[Castor web site]. The Spring
integration classes reside in the `org.springframework.oxm.castor` package.
[[oxm-castor-marshaller]]
==== Using `CastorMarshaller`
@@ -6957,7 +6838,6 @@ interface. It can be wired up as follows:
====
[[oxm-castor-mapping]]
==== Mapping
@@ -6981,8 +6861,6 @@ with a classpath resource:
----
====
[[oxm-castor-xsd]]
===== XML Configuration Namespace
@@ -7048,7 +6926,6 @@ site]. The Spring integration classes reside in the `org.springframework.oxm.jib
package.
[[oxm-jibx-marshaller]]
==== Using `JibxMarshaller`
@@ -7074,8 +6951,6 @@ A `JibxMarshaller` is configured for a single class. If you want to marshal mult
classes, you have to configure multiple `JibxMarshaller` instances with different `targetClass`
property values.
[[oxm-jibx-xsd]]
===== XML Configuration Namespace
@@ -7121,7 +6996,6 @@ web site]. The Spring integration classes reside in the
`org.springframework.oxm.xstream` package.
[[oxm-xstream-marshaller]]
==== Using `XStreamMarshaller`
@@ -7184,4 +7058,5 @@ within Web services.
include::data-access-appendix.adoc[leveloffset=+1]

13
src/docs/asciidoc/integration-appendix.adoc
View File

@@ -1,6 +1,8 @@
= Appendix
[[xsd-schemas]]
== XML Schemas
@@ -28,8 +30,8 @@ correct schema so that the elements in the `jee` namespace are available to you:
__xmlns:jee="http://www.springframework.org/schema/jee"__ xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
__http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-jee.xsd"__>
<!-- bean definitions here -->
<!-- bean definitions here -->
</beans>
----
====
@@ -39,8 +41,7 @@ correct schema so that the elements in the `jee` namespace are available to you:
[[xsd-schemas-jee-jndi-lookup]]
==== <jee:jndi-lookup/> (simple)
The following example shows how to use JNDI to look up a data source without the `jee`
schema:
The following example shows how to use JNDI to look up a data source without the `jee` schema:
====
[source,xml,indent=0]
@@ -329,8 +330,9 @@ are available to you:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
__xmlns:jms="http://www.springframework.org/schema/jms"__ xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
__http://www.springframework.org/schema/jms http://www.springframework.org/schema/jms/spring-jms.xsd"__> <!-- bean definitions here -->
__http://www.springframework.org/schema/jms http://www.springframework.org/schema/jms/spring-jms.xsd"__>
<!-- bean definitions here -->
</beans>
----
====
@@ -366,8 +368,9 @@ the correct schema so that the elements in the `cache` namespace are available t
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
__xmlns:cache="http://www.springframework.org/schema/cache"__ xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
__http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd"__> <!-- bean definitions here -->
__http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd"__>
<!-- bean definitions here -->
</beans>
----
====

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

File diff suppressed because it is too large Load Diff

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

@@ -7,7 +7,6 @@
:tabsize: 4
:docinfo1:
include::languages/kotlin.adoc[leveloffset=+1]
include::languages/groovy.adoc[leveloffset=+1]

4
src/docs/asciidoc/languages/dynamic-languages.adoc
View File

@@ -952,7 +952,9 @@ are available to you:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
__xmlns:lang="http://www.springframework.org/schema/lang"__ xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
__http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang.xsd"__> <!-- bean definitions here -->
__http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang.xsd"__>
<!-- bean definitions here -->
</beans>
----

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

@@ -113,7 +113,7 @@ libraries that depend on Spring.
* Care about API design. The Spring team puts a lot of thought and time into making APIs
that are intuitive and that hold up across many versions and many years.
* Set high standards for code quality. The Spring Framework puts a strong emphasis on
meaningful, current, and accurate Javadoc. It is one of very few projects that can claim
meaningful, current, and accurate javadoc. It is one of very few projects that can claim
clean code structure with no circular dependencies between packages.

2
src/docs/asciidoc/testing-webtestclient.adoc
View File

@@ -12,6 +12,7 @@ related to use of the `WebTestClient`.
[[webtestclient-setup]]
== Setup
@@ -137,6 +138,7 @@ are readily available following `bindToServer`. For all others, you need to use
[[webtestclient-tests]]
== Writing Tests

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

File diff suppressed because it is too large Load Diff

3
src/docs/asciidoc/web-reactive.adoc
View File

@@ -23,6 +23,7 @@ include::web/webflux-websocket.adoc[leveloffset=+1]
[[webflux-test]]
== Testing
[.small]#<<web.adoc#testing,Same in Spring MVC>>#
@@ -37,6 +38,7 @@ server. You can use the `WebTestClient` for end-to-end integration tests, too.
//[[webflux-threading-model]]
//=== Threading model
// TODO Once we have content for this heading, we should un-comment the heading and
@@ -44,6 +46,7 @@ server. You can use the `WebTestClient` for end-to-end integration tests, too.
[[webflux-reactive-libraries]]
== Reactive Libraries

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

@@ -14,8 +14,10 @@ popular third party web frameworks.
[[web-integration-common]]
== Common Configuration
Before diving into the integration specifics of each supported web framework, let us
first take a look at the Spring configuration that is not specific to any one web
framework. (This section is equally applicable to Spring's own web framework, Spring
@@ -105,6 +107,7 @@ has more detail on its specific integration strategies.
[[jsf]]
== JSF
@@ -173,6 +176,7 @@ The following example shows how to use `FacesContextUtils`:
[[struts]]
== Apache Struts 2.x
@@ -189,6 +193,7 @@ built-in Spring integration shipped with Struts.
[[tapestry]]
== Tapestry 5.x
@@ -205,8 +210,10 @@ Spring].
[[web-integration-resources]]
== Further Resources
The following links go to further resources about the various web frameworks described in this
chapter.

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

@@ -1,4 +1,3 @@
[[web-uricomponents]]
= UriComponents
[.small]#Spring MVC and Spring WebFlux#

5
src/docs/asciidoc/web/webflux-cors.adoc
View File

@@ -7,6 +7,7 @@ describes how to do so.
[[webflux-cors-intro]]
== Introduction
[.small]#<<web.adoc#mvc-cors-intro,Same as in Spring MVC>>#
@@ -23,6 +24,7 @@ powerful workarounds based on IFRAME or JSONP.
[[webflux-cors-processing]]
== Processing
[.small]#<<web.adoc#mvc-cors-processing,Same as in Spring MVC>>#
@@ -72,6 +74,7 @@ To learn more from the source or to make advanced customizations, see:
[[webflux-cors-controller]]
== `@CrossOrigin`
[.small]#<<web.adoc#mvc-cors-controller,Same as in Spring MVC>>#
@@ -170,6 +173,7 @@ public class AccountController {
[[webflux-cors-global]]
== Global Configuration
[.small]#<<web.adoc#mvc-cors-global,Same as in Spring MVC>>#
@@ -220,6 +224,7 @@ public class WebConfig implements WebFluxConfigurer {
[[webflux-cors-webfilter]]
== CORS `WebFilter`
[.small]#<<web.adoc#mvc-cors-filter,Same as in Spring MVC>>#

5
src/docs/asciidoc/web/webflux-functional.adoc
View File

@@ -8,6 +8,7 @@ the same <<web-reactive.adoc#webflux-reactive-spring-web>> foundation.
[[webflux-fn-overview]]
== Overview
@@ -71,6 +72,7 @@ Most applications can run through the WebFlux Java configuration, see <<webflux-
[[webflux-fn-handler-functions]]
== HandlerFunction
@@ -245,6 +247,7 @@ found. If it is not found, we use `switchIfEmpty(Mono<T>)` to return a 404 Not F
[[webflux-fn-router-functions]]
== `RouterFunction`
@@ -320,6 +323,7 @@ RouterFunction<ServerResponse> personRoute =
[[webflux-fn-running]]
== Running a Server
@@ -394,6 +398,7 @@ public class WebConfig implements WebFluxConfigurer {
[[webflux-fn-handler-filter-function]]
== `HandlerFilterFunction`

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

@@ -3,9 +3,10 @@
[.small]#<<web.adoc#mvc-view,Same as in Spring MVC>>#
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-viewresolution>>.
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-viewresolution>>.
@@ -29,6 +30,7 @@ http://forum.thymeleaf.org/Thymeleaf-3-0-8-JUST-PUBLISHED-td4030687.html[announc
[[webflux-view-freemarker]]
== FreeMarker
[.small]#<<web.adoc#mvc-view-freemarker,Same as in Spring MVC>>#
@@ -116,6 +118,7 @@ the `Configuration` object.
[[webflux-view-script]]
== Script Views
[.small]#<<web.adoc#mvc-view-script,Same as in Spring MVC>>#
@@ -280,6 +283,7 @@ for more configuration examples.
[[webflux-view-httpmessagewriter]]
== JSON and XML
[.small]#<<web.adoc#mvc-view-jackson,Same as in Spring MVC>>#

6
src/docs/asciidoc/web/webflux-webclient.adoc
View File

@@ -14,6 +14,7 @@ and others can be plugged in through a `ClientHttpConnector`.
[[webflux-client-builder]]
== Configuration
@@ -241,6 +242,7 @@ shows:
[[webflux-client-retrieve]]
== `retrieve()`
@@ -294,6 +296,7 @@ as the following example shows:
[[webflux-client-exchange]]
== `exchange()`
@@ -335,6 +338,7 @@ is closed and is not placed back in the pool.
[[webflux-client-body]]
== Request Body
@@ -497,6 +501,7 @@ inline-style, through the built-in `BodyInserters`, as the following example sho
[[webflux-client-filter]]
== Client Filters
@@ -581,6 +586,7 @@ WebClient client = webClient.mutate()
[[webflux-client-testing]]
== Testing

3
src/docs/asciidoc/web/webflux-websocket.adoc
View File

@@ -5,12 +5,11 @@
This part of the reference documentation covers support for reactive-stack WebSocket
messaging.
include::websocket-intro.adoc[leveloffset=+1]
[[webflux-websocket-server]]
== WebSocket API
[.small]#<<web.adoc#websocket-server,Same as in the Servlet stack>>#

61
src/docs/asciidoc/web/webflux.adoc
View File

@@ -17,6 +17,7 @@ for example, Spring MVC controllers with the reactive `WebClient`.
[[webflux-new-framework]]
== Overview
@@ -291,6 +292,7 @@ libraries, see their respective documentation.
[[webflux-reactive-spring-web]]
== Reactive Core
@@ -452,7 +454,6 @@ access not only to the request and response, but also to request and session att
access to parsed form data, multipart data, and more.
[[webflux-web-handler-api-special-beans]]
==== Special bean types
@@ -505,7 +506,6 @@ The table below lists the components that `WebHttpHandlerBuilder` detects:
|===
[[webflux-form-data]]
==== Form Data
@@ -525,7 +525,6 @@ The `DefaultServerWebExchange` uses the configured `HttpMessageReader` to parse
(see the <<webflux-web-handler-api,Web Handler API>>).
[[webflux-multipart]]
==== Multipart Data
[.small]#<<web.adoc#mvc-multipart,Same as in Spring MVC>>#
@@ -555,7 +554,6 @@ parsing multipart data in full. By contrast, you can use `@RequestBody` to decod
content to `Flux<Part>` without collecting to a `MultiValueMap`.
[[webflux-forwarded-headers]]
==== Forwarded Headers
[.small]#<<web.adoc#filters-forwarded-headers,Same as in Spring MVC>>#
@@ -598,7 +596,6 @@ as declaring it as a Spring bean and (optionally) expressing precedence by using
the bean declaration or by implementing `Ordered`.
[[webflux-filters-cors]]
==== CORS
[.small]#<<web.adoc#filters-cors,Same as in Spring MVC>>#
@@ -669,7 +666,6 @@ JSON, Jackson Smile, JAXB2, Protocol Buffers, and other web-specific HTTP messag
readers and writers for form data, multipart requests, and server-sent events.
[[webflux-codecs-jackson]]
==== Jackson JSON
@@ -702,7 +698,6 @@ or a sequence of strings represent serialized JSON content, to be rendered by th
use `Flux#collectToList()` and provide a `Mono<List<String>>` to be serialized.
[[webflux-codecs-forms]]
==== Form Data
@@ -719,7 +714,6 @@ request body. For this reason, applications are expected to go through `ServerWe
consistently for access to the cached form data versus reading from the raw request body.
[[webflux-codecs-multipart]]
==== Multipart Data
@@ -741,7 +735,6 @@ for repeated, map-like access to parts, or otherwise rely on the
`SynchronossPartHttpMessageReader` for a one-time access to `Flux<Part>`.
[[webflux-codecs-streaming]]
==== Streaming
[.small]#<<web.adoc#mvc-ann-async-http-streaming,Same as in Spring MVC>>#
@@ -786,7 +779,6 @@ while a fully formatted prefix based on that ID is available from
,while a fully formatted prefix is available from `ClientRequest#logPrefix()`.
[[webflux-logging-sensitive-data]]
==== Logging Sensitive Data
[.small]#<<web.adoc#mvc-logging-sensitive-data,Same as in Spring MVC>>#
@@ -829,6 +821,7 @@ WebClient webClient = WebClient.builder()
[[webflux-dispatcher-handler]]
== `DispatcherHandler`
[.small]#<<web.adoc#mvc-servlet,Same as in Spring MVC>>#
@@ -1012,7 +1005,6 @@ supported through a dedicated <<webflux-resulthandling,HandlerResultHandler>> th
instance. The `View` is then used to render the response.
[[webflux-viewresolution-handling]]
==== Handling
[.small]#<<web.adoc#mvc-handling,Same as in Spring MVC>>#
@@ -1049,7 +1041,6 @@ dedicated configuration API for view resolution.
See <<webflux-view>> for more on the view technologies integrated with Spring WebFlux.
[[webflux-redirecting-redirect-prefix]]
==== Redirecting
[.small]#<<web.adoc#mvc-redirecting-redirect-prefix,Same as in Spring MVC>>#
@@ -1081,6 +1072,7 @@ always selected and used if they match the requested media type.
[[webflux-controller]]
== Annotated Controllers
[.small]#<<web.adoc#mvc-controller,Same as in Spring MVC>>#
@@ -1192,7 +1184,6 @@ The following example uses type and method level mappings:
====
[[webflux-ann-requestmapping-uri-templates]]
==== URI Patterns
[.small]#<<web.adoc#mvc-ann-requestmapping-uri-templates,Same as in Spring MVC>>#
@@ -1295,7 +1286,6 @@ Catch-all patterns (for example, `**`, `{*varName}`) are excluded from the scori
sorted last instead. If two patterns are both catch-all, the longer is chosen.
[[webflux-ann-requestmapping-consumes]]
==== Consumable Media Types
[.small]#<<web.adoc#mvc-ann-requestmapping-consumes,Same as in Spring MVC>>#
@@ -1325,7 +1315,6 @@ TIP: `MediaType` provides constants for commonly used media types -- for example
`APPLICATION_JSON_VALUE` and `APPLICATION_XML_VALUE`.
[[webflux-ann-requestmapping-produces]]
==== Producible Media Types
[.small]#<<web.adoc#mvc-ann-requestmapping-produces,Same as in Spring MVC>>#
@@ -1361,7 +1350,6 @@ TIP: `MediaType` provides constants for commonly used media types -- e.g.
`APPLICATION_JSON_UTF8_VALUE`, `APPLICATION_XML_VALUE`.
[[webflux-ann-requestmapping-params-and-headers]]
==== Parameters and Headers
[.small]#<<web.adoc#mvc-ann-requestmapping-params-and-headers,Same as in Spring MVC>>#
@@ -1397,7 +1385,6 @@ You can also use the same with request header conditions, as the follwing exampl
====
[[webflux-ann-requestmapping-head-options]]
==== HTTP HEAD, OPTIONS
[.small]#<<web.adoc#mvc-ann-requestmapping-head-options,Same as in Spring MVC>>#
@@ -1419,7 +1406,6 @@ You can explicitly map a `@RequestMapping` method to HTTP HEAD and HTTP OPTIONS,
is not necessary in the common case.
[[webflux-ann-requestmapping-composed]]
==== Custom Annotations
[.small]#<<web.adoc#mvc-ann-requestmapping-composed,Same as in Spring MVC>>#
@@ -1441,7 +1427,6 @@ logic. This is a more advanced option that requires sub-classing
you can check the custom attribute and return your own `RequestCondition`.
[[webflux-ann-requestmapping-registration]]
==== Explicit Registrations
[.small]#<<web.adoc#mvc-ann-requestmapping-registration,Same as in Spring MVC>>#
@@ -1487,7 +1472,6 @@ public class MyConfig {
supported controller method arguments and return values.
[[webflux-ann-arguments]]
==== Method Arguments
[.small]#<<web.adoc#mvc-ann-arguments,Same as in Spring MVC>>#
@@ -1697,7 +1681,6 @@ can be customized through a `WebDataBinder` (see <<mvc-ann-initbinder>>) or by r
<<core.adoc#format, Spring Field Formatting>>).
[[webflux-ann-matrix-variables]]
==== Matrix Variables
[.small]#<<web.adoc#mvc-ann-matrix-variables,Same as in Spring MVC>>#
@@ -1791,7 +1774,6 @@ To get all matrix variables, use a `MultiValueMap`, as the following example sho
====
[[webflux-ann-requestparam]]
==== `@RequestParam`
[.small]#<<web.adoc#mvc-ann-requestparam,Same as in Spring MVC>>#
@@ -1847,7 +1829,6 @@ and is not resolved by any other argument resolver is treated as if it were anno
with `@RequestParam`.
[[webflux-ann-requestheader]]
==== `@RequestHeader`
[.small]#<<web.adoc#mvc-ann-requestheader,Same as in Spring MVC>>#
@@ -1900,7 +1881,6 @@ example, a method parameter annotated with `@RequestHeader("Accept")` may be of
`String` but also of `String[]` or `List<String>`.
[[webflux-ann-cookievalue]]
==== `@CookieValue`
[.small]#<<web.adoc#mvc-ann-cookievalue,Same as in Spring MVC>>#
@@ -1936,7 +1916,6 @@ Type conversion is applied automatically if the target method parameter type is
`String`. See <<mvc-ann-typeconversion>>.
[[webflux-ann-modelattrib-method-args]]
==== `@ModelAttribute`
[.small]#<<web.adoc#mvc-ann-modelattrib-method-args,Same as in Spring MVC>>#
@@ -2044,7 +2023,6 @@ and is not resolved by any other argument resolver is treated as if it were anno
with `@ModelAttribute`.
[[webflux-ann-sessionattributes]]
==== `@SessionAttributes`
[.small]#<<web.adoc#mvc-ann-sessionattributes,Same as in Spring MVC>>#
@@ -2101,7 +2079,6 @@ as the following example shows:
====
[[webflux-ann-sessionattribute]]
==== `@SessionAttribute`
[.small]#<<web.adoc#mvc-ann-sessionattribute,Same as in Spring MVC>>#
@@ -2151,7 +2128,6 @@ as the following example shows:
====
[[webflux-multipart-forms]]
==== Multipart Content
[.small]#<<web.adoc#mvc-multipart-forms,Same as in Spring MVC>>#
@@ -2295,7 +2271,6 @@ To access multipart data sequentially, in streaming fashion, you can use `@Reque
====
[[webflux-ann-requestbody]]
==== `@RequestBody`
[.small]#<<web.adoc#mvc-ann-requestbody,Same as in Spring MVC>>#
@@ -2352,7 +2327,6 @@ example uses a `BindingResult` argument`:
====
[[webflux-ann-httpentity]]
==== `HttpEntity`
[.small]#<<web.adoc#mvc-ann-httpentity,Same as in Spring MVC>>#
@@ -2373,7 +2347,6 @@ container object that exposes request headers and the body. The following exampl
====
[[webflux-ann-responsebody]]
==== `@ResponseBody`
[.small]#<<web.adoc#mvc-ann-responsebody,Same as in Spring MVC>>#
@@ -2409,7 +2382,6 @@ You can use the <<webflux-config-message-codecs>> option of the <<webflux-config
configure or customize message writing.
[[webflux-ann-responseentity]]
==== `ResponseEntity`
[.small]#<<web.adoc#mvc-ann-responseentity,Same as in Spring MVC>>#
@@ -2434,8 +2406,6 @@ produce the `ResponseEntity` asynchronously, and/or single and multi-value react
for the body.
[[webflux-ann-jackson]]
==== Jackson JSON
@@ -2549,9 +2519,8 @@ The following example adds one attribute only:
----
====
NOTE: When a name is not explicitly specified, a default name is chosen based on the `Object`
type, as explained in the Javadoc for
{api-spring-framework}/core/Conventions.html[`Conventions`].
NOTE: When a name is not explicitly specified, a default name is chosen based on the type,
as explained in the javadoc for {api-spring-framework}/core/Conventions.html[`Conventions`].
You can always assign an explicit name by using the overloaded `addAttribute` method or
through the name attribute on `@ModelAttribute` (for a return value).
@@ -2714,7 +2683,6 @@ Support for `@ExceptionHandler` methods in Spring WebFlux is provided by the
for more detail.
[[webflux-ann-rest-exceptions]]
==== REST API exceptions
[.small]#<<web.adoc#mvc-ann-rest-exceptions,Same as in Spring MVC>>#
@@ -2779,30 +2747,26 @@ as the following example shows:
The preceding selectors are evaluated at runtime and may negatively impact
performance if you use them extensively. See the
{api-spring-framework}/web/bind/annotation/ControllerAdvice.html[`@ControllerAdvice`]
Javadoc for more details.
javadoc for more details.
include::webflux-functional.adoc[leveloffset=+1]
[[webflux-uri-building]]
== URI Links
[.small]#<<web.adoc#mvc-uri-building,Same as in Spring MVC>>#
This section describes various options available in the Spring Framework to prepare URIs.
include::web-uris.adoc[leveloffset=+2]
include::webflux-cors.adoc[leveloffset=+1]
[[webflux-web-security]]
== Web Security
[.small]#<<web.adoc#mvc-web-security,Same as in Spring MVC>>#
@@ -2816,12 +2780,11 @@ reference documentation, including:
* {doc-spring-security}/html5/#csrf[CSRF Protection]
* {doc-spring-security}/html5/#headers[Security Response Headers]
include::webflux-view.adoc[leveloffset=+1]
[[webflux-caching]]
== HTTP Caching
[.small]#<<web.adoc#mvc-caching,Same as in Spring MVC>>#
@@ -2946,6 +2909,7 @@ for optimal performance. See the section on configuring <<webflux-config-static-
[[webflux-config]]
== WebFlux Config
[.small]#<<web.adoc#mvc-config,Same as in Spring MVC>>#
@@ -3358,7 +3322,7 @@ match to incoming URLs without versions (for example, `/jquery/jquery.min.js` to
[.small]#<<web.adoc#mvc-config-path-matching,Same as in Spring MVC>>#
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.
{api-spring-framework}/web/reactive/config/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc.
The following example shows how to use `PathMatchConfigurer`:
====
@@ -3430,6 +3394,7 @@ the classpath.
[[webflux-http2]]
== HTTP/2
[.small]#<<web.adoc#mvc-http2,Same as in Spring MVC>>#

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

@@ -5,6 +5,7 @@ This section describes options for client-side access to REST endpoints.
[[webmvc-resttemplate]]
== `RestTemplate`
@@ -21,6 +22,7 @@ See <<integration.adoc#rest-client-access,REST Endpoints>> for details.
[[webmvc-webclient]]
== `WebClient`

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

@@ -7,6 +7,7 @@ describes how to do so.
[[mvc-cors-intro]]
== Introduction
[.small]#<<web-reactive.adoc#webflux-cors-intro,Same as in Spring WebFlux>>#
@@ -23,6 +24,7 @@ powerful workarounds based on IFRAME or JSONP.
[[mvc-cors-processing]]
== Processing
[.small]#<<web-reactive.adoc#webflux-cors-processing,Same as in Spring WebFlux>>#
@@ -72,6 +74,7 @@ To learn more from the source or make advanced customizations, check the code be
[[mvc-cors-controller]]
== `@CrossOrigin`
[.small]#<<web-reactive.adoc#webflux-cors-controller,Same as in Spring WebFlux>>#
@@ -167,6 +170,7 @@ public class AccountController {
[[mvc-cors-global]]
== Global Configuration
[.small]#<<web-reactive.adoc#webflux-cors-global,Same as in Spring WebFlux>>#
@@ -191,7 +195,6 @@ should only be used where appropriate.
[[mvc-cors-global-java]]
=== Java Configuration
[.small]#<<web-reactive.adoc#webflux-cors-global,Same as in Spring WebFlux>>#
@@ -253,6 +256,7 @@ as the following example shows:
[[mvc-cors-filter]]
== CORS Filter
[.small]#<<web-reactive.adoc#webflux-cors-webfilter,Same as in Spring WebFlux>>#

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

@@ -9,14 +9,15 @@ We assume you are already familiar with <<mvc-viewresolver>>.
[[mvc-view-thymeleaf]]
== Thymeleaf
[.small]#<<web-reactive.adoc#webflux-view-thymeleaf,Same as in Spring WebFlux>>#
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 for independent work on UI templates (for example, by a designer) without the need for a
running server. If you want to replace JSPs, Thymeleaf offers one of the most
templates that can be previewed in a browser by double-clicking, which is very helpful
for independent work on UI templates (for example, by a designer) without the need for
a running server. If you want to replace JSPs, Thymeleaf offers one of the most
extensive set of features to make such a transition easier. Thymeleaf is actively
developed and maintained. For a more complete introduction, see the
http://www.thymeleaf.org/[Thymeleaf] project home page.
@@ -28,6 +29,7 @@ See http://www.thymeleaf.org/documentation.html[Thymeleaf+Spring] for more detai
[[mvc-view-freemarker]]
== FreeMarker
[.small]#<<web-reactive.adoc#webflux-view-freemarker,Same as in Spring WebFlux>>#
@@ -149,7 +151,6 @@ web or business tier. Spring also has support for the same functionality in Free
with additional convenience macros for generating form input elements themselves.
[[mvc-view-bind-macros]]
==== The Bind Macros
@@ -164,7 +165,6 @@ directly, the file is called `spring.ftl` and is in the
`org.springframework.web.servlet.view.freemarker` package.
[[mvc-view-simple-binding]]
==== Simple Binding
@@ -212,7 +212,6 @@ simplify the use of HTML escaping, and you should use these macros wherever poss
They are explained in the next section.
[[mvc-views-form-macros]]
==== Input macros
@@ -304,8 +303,6 @@ The parameters to any of the above macros have consistent meanings:
The following sections outline examples of the macros (some in FTL and some in VTL). Where usage
differences exist between the two languages, they are explained in the notes.
[[mvc-views-form-macros-input]]
===== Input Fields
@@ -353,8 +350,6 @@ The `formTextarea` macro works the same way as the `formInput` macro and accepts
parameter list. Commonly, the second parameter (attributes) is used to pass style
information or `rows` and `cols` attributes for the `textarea`.
[[mvc-views-form-macros-select]]
===== Selection Fields
@@ -438,7 +433,6 @@ user still sees the more user-friendly city names, as follows:
====
[[mvc-views-form-macros-html-escaping]]
==== HTML Escaping
@@ -484,6 +478,7 @@ In similar fashion, you can specify HTML escaping per field, as the following ex
[[mvc-view-groovymarkup]]
== Groovy Markup
@@ -570,6 +565,7 @@ syntax. The following example shows a sample template for an HTML page:
[[mvc-view-script]]
== Script Views
[.small]#<<web-reactive.adoc#webflux-view-script,Same as in Spring WebFlux>>#
@@ -787,6 +783,7 @@ for more configuration examples.
[[mvc-view-jsp]]
== JSP and JSTL
@@ -878,7 +875,6 @@ We go through the form tags and look at an example of how each tag is used. We h
included generated HTML snippets where certain tags require further commentary.
[[mvc-view-jsp-formtaglib-configuration]]
==== Configuration
@@ -898,7 +894,6 @@ where `form` is the tag name prefix you want to use for the tags from this libra
====
[[mvc-view-jsp-formtaglib-formtag]]
==== The Form Tag
@@ -996,7 +991,6 @@ following example shows:
====
[[mvc-view-jsp-formtaglib-inputtag]]
==== The `input` Tag
@@ -1254,7 +1248,6 @@ password value to be shown, you can set the value of the `showPassword` attribut
====
[[mvc-view-jsp-formtaglib-selecttag]]
==== The `select` Tag
@@ -1420,7 +1413,6 @@ This tag renders an HTML `textarea` element. The following HTML shows typical ou
====
[[mvc-view-jsp-formtaglib-hiddeninputtag]]
==== The `hidden` Tag
@@ -1448,7 +1440,6 @@ If we choose to submit the `house` value as a hidden one, the HTML would be as f
====
[[mvc-view-jsp-formtaglib-errorstag]]
==== The `errors` Tag
@@ -1682,7 +1673,6 @@ The following example shows the corresponding `@Controller` method:
====
[[mvc-view-jsp-formtaglib-html5]]
==== HTML5 Tags
@@ -1696,6 +1686,7 @@ is the default type.
[[mvc-view-tiles]]
== Tiles
@@ -1793,7 +1784,6 @@ resolve. The following bean defines a `UrlBasedViewResolver`:
====
[[mvc-view-tiles-resource]]
==== `ResourceBundleViewResolver`
@@ -1811,7 +1801,6 @@ classes (taken from the Pet Clinic sample):
</bean>
----
[source,java,indent=0]
[subs="verbatim,quotes"]
----
@@ -1834,7 +1823,6 @@ different view technologies.
Note that the `TilesView` class supports JSTL (the JSP Standard Tag Library).
[[mvc-view-tiles-preparer]]
==== `SimpleSpringPreparerFactory` and `SpringBeanPreparerFactory`
@@ -1882,6 +1870,7 @@ how to define a set a `SpringBeanPreparerFactory` property on a `TilesConfigurer
[[mvc-view-feeds]]
== RSS and Atom
@@ -1949,6 +1938,7 @@ https://spring.io/blog/2009/03/16/adding-an-atom-view-to-an-application-using-sp
[[mvc-view-document]]
== PDF and Excel
@@ -2006,7 +1996,7 @@ A controller can return such a view either from an external view definition
[[mvc-view-document-pdf]]
[[mvc-view-document-excel]]
=== Excel Views
Since Spring Framework 4.2,
@@ -2020,6 +2010,7 @@ an external definition (by name) or as a `View` instance from the handler method
[[mvc-view-jackson]]
== Jackson
[.small]#<<web-reactive.adoc#webflux-view-httpmessagewriter,Same as in Spring WebFlux>>#
@@ -2078,6 +2069,7 @@ by the `Marshaller`. For more information on the functionality in the
[[mvc-view-xslt]]
== XSLT Views

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

@@ -19,6 +19,8 @@ ranges, see the Spring Framework
https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Versions[Wiki].
[[mvc-servlet]]
== DispatcherServlet
[.small]#<<web-reactive.adoc#webflux-dispatcher-handler,Same as in Spring WebFlux>>#
@@ -221,7 +223,7 @@ The following table lists the special beans detected by the `DispatcherHandler`:
|===
| Bean type| Explanation
| <<mvc-handlermapping,`HandlerMapping`>>
| `HandlerMapping`
| Map a request to a handler along with a list of
<<mvc-handlermapping-interceptor, interceptors>> for pre- and post-processing.
The mapping is based on some criteria, the details of which vary by `HandlerMapping`
@@ -264,6 +266,7 @@ The following table lists the special beans detected by the `DispatcherHandler`:
|===
[[mvc-servlet-config]]
=== Web MVC Config
[.small]#<<web-reactive.adoc#webflux-framework-config,Same as in Spring WebFlux>>#
@@ -570,7 +573,6 @@ exceptions, for `@ResponseStatus` annotated exceptions, and for support of
`@ExceptionHandler` methods. You can customize that list or replace it.
[[mvc-ann-customer-servlet-container-error-page]]
==== Container Error Page
@@ -656,15 +658,16 @@ The following table provides more details on the `ViewResolver` hierarchy:
| `UrlBasedViewResolver`
| Simple implementation of the `ViewResolver` interface that affects the direct
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 in a
straightforward manner, without the need for arbitrary mappings.
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
in a straightforward manner, without the need for arbitrary mappings.
| `InternalResourceViewResolver`
| Convenient subclass of `UrlBasedViewResolver` that supports `InternalResourceView` (in
effect, Servlets and JSPs) and subclasses such as `JstlView` and `TilesView`. You can
specify the view class for all views generated by this resolver by using
`setViewClass(..)`. See the {api-spring-framework}/web/reactive/result/view/UrlBasedViewResolver.html[`UrlBasedViewResolver` Javadoc] for details.
specify the view class for all views generated by this resolver by using `setViewClass(..)`.
See the {api-spring-framework}/web/reactive/result/view/UrlBasedViewResolver.html[`UrlBasedViewResolver`]
javadoc for details.
| `FreeMarkerViewResolver`
| Convenient subclass of `UrlBasedViewResolver` that supports `FreeMarkerView` and
@@ -697,7 +700,6 @@ configuration. The <<mvc-config>> provides a dedicated configuration API for
rendering without controller logic.
[[mvc-redirecting-redirect-prefix]]
==== Redirecting
[.small]#<<web-reactive.adoc#webflux-redirecting-redirect-prefix,Same as in Spring WebFlux>>#
@@ -716,7 +718,6 @@ Note that, if a controller method is annotated with the `@ResponseStatus`, the a
value takes precedence over the response status set by `RedirectView`.
[[mvc-redirecting-forward-prefix]]
==== Forwarding
@@ -729,7 +730,6 @@ technology but still want to force a forward of a resource to be handled by the
Servlet/JSP engine. Note that you may also chain multiple view resolvers, instead.
[[mvc-multiple-representations]]
==== Content Negotiation
[.small]#<<web-reactive.adoc#webflux-multiple-representations,Same as in Spring WebFlux>>#
@@ -783,7 +783,6 @@ Spring.
* <<mvc-localeresolver-interceptor>>
[[mvc-timezone]]
==== Time Zone
@@ -797,7 +796,6 @@ by any Date/Time `Converter` and `Formatter` objects that are registered with Sp
`ConversionService`.
[[mvc-localeresolver-acceptheader]]
==== Header Resolver
@@ -807,7 +805,6 @@ the client's operating system. Note that this resolver does not support time zon
information.
[[mvc-localeresolver-cookie]]
==== Cookie Resolver
@@ -856,7 +853,6 @@ The following table describes the properties `CookieLocaleResolver`:
|===
[[mvc-localeresolver-session]]
==== Session Resolver
@@ -871,17 +867,16 @@ such as the Spring Session project. This `SessionLocaleResolver` evaluates and
modifies the corresponding `HttpSession` attributes against the current `HttpServletRequest`.
[[mvc-localeresolver-interceptor]]
==== Locale Interceptor
You can enable changing of locales by adding the `LocaleChangeInterceptor` to one of the
handler mappings (see <<mvc-handlermapping>>). It detects a parameter in the request
and changes the locale. It calls `setLocale()` on the `LocaleResolver` that also exists
in the context. The next example shows that calls to all `{asterisk}.view` resources
`HandlerMapping` definitions. It detects a parameter in the request and changes the locale
accordingly, calling the `setLocale` method on the `LocaleResolver` in the dispatcher's
application context. The next example shows that calls to all `{asterisk}.view` resources
that contain a parameter named `siteLanguage` now changes the locale. So, for example,
a request for the URL, `http://www.sf.net/home.view?siteLanguage=nl`,
changes the site language to Dutch. The following example shows how to intercept the locale:
a request for the URL, `http://www.sf.net/home.view?siteLanguage=nl`, changes the site
language to Dutch. The following example shows how to intercept the locale:
====
[source,xml,indent=0]
@@ -920,7 +915,6 @@ resources, typically style sheets and images, that affect the visual style of th
application.
[[mvc-themeresolver-defining]]
==== Defining a theme
@@ -976,14 +970,13 @@ example, we could have a `/WEB-INF/classes/cool_nl.properties` that references a
background image with Dutch text on it.
[[mvc-themeresolver-resolving]]
==== Resolving Themes
After you define themes, as described in the <<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
After you define themes, as described in the <<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
alter the request's theme. The following table describes the theme resolvers provided by Spring:
[[mvc-theme-resolver-impls-tbl]]
@@ -1025,9 +1018,8 @@ wraps the current `HttpServletRequest` as `MultipartHttpServletRequest` to
provide access to resolved parts in addition to exposing them as request parameters.
[[mvc-multipart-resolver-commons]]
==== Apache `FileUpload`
==== Apache Commons `FileUpload`
To use Apache Commons `FileUpload`, you can configure a bean of type
`CommonsMultipartResolver` with a name of `multipartResolver`. You also need to
@@ -1085,7 +1077,6 @@ Good logging comes from the experience of using the logs. If you spot anything t
not meet the stated goals, please let us know.
[[mvc-logging-sensitive-data]]
==== Sensitive Data
[.small]#<<web-reactive.adoc#webflux-logging-sensitive-data,Same as in Spring WebFlux>>#
@@ -1129,6 +1120,7 @@ public class MyInitializer
[[filters]]
== Filters
[.small]#<<web-reactive.adoc#webflux-filters,Same as in Spring WebFlux>>#
@@ -1210,6 +1202,7 @@ See the sections on <<mvc-cors>> and the <<mvc-cors-filter>> for more details.
[[mvc-controller]]
== Annotated Controllers
[.small]#<<web-reactive.adoc#webflux-controller,Same as in Spring WebFlux>>#
@@ -1301,7 +1294,6 @@ every method inherits the type-level `@ResponseBody` annotation and, therefore,
directly to the response body versus view resolution and rendering with an HTML template.
[[mvc-ann-requestmapping-proxying]]
==== AOP Proxies
@@ -1363,11 +1355,9 @@ The following example has type and method level mappings:
====
[[mvc-ann-requestmapping-uri-templates]]
==== URI patterns
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-uri-templates,Same as in Spring
WebFlux>>#
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-uri-templates,Same as in Spring WebFlux>>#
You can map requests by using the following glob patterns and wildcards:
@@ -1443,8 +1433,7 @@ NOTE: Spring MVC uses the `PathMatcher` contract and the `AntPathMatcher` implem
[[mvc-ann-requestmapping-pattern-comparison]]
==== Pattern Comparison
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-pattern-comparison,Same as in Spring
WebFlux>>#
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-pattern-comparison,Same as in Spring WebFlux>>#
When multiple patterns match a URL, they must be compared to find the best match. This is done
by using `AntPathMatcher.getPatternComparator(String path)`, which looks for patterns that are more
@@ -1459,10 +1448,10 @@ The default mapping pattern (`/{asterisk}{asterisk}`) is excluded from scoring a
sorted last. Also, prefix patterns (such as `/public/{asterisk}{asterisk}`) are considered less
specific than other pattern that do not have double wildcards.
For the full details, see {api-spring-framework}/util/AntPathMatcher.AntPatternComparator.html[`AntPatternComparator`] in {api-spring-framework}/util/AntPathMatcher.html[`AntPathMatcher`] and also keep mind that
you can customize the {api-spring-framework}/util/PathMatcher.html[`PathMatcher`] implementation. See <<mvc-config-path-matching>>
in the configuration section.
For the full details, see {api-spring-framework}/util/AntPathMatcher.AntPatternComparator.html[`AntPatternComparator`]
in {api-spring-framework}/util/AntPathMatcher.html[`AntPathMatcher`] and also keep mind that
you can customize the {api-spring-framework}/util/PathMatcher.html[`PathMatcher`] implementation.
See <<mvc-config-path-matching>> in the configuration section.
[[mvc-ann-requestmapping-suffix-pattern-match]]
@@ -1495,7 +1484,6 @@ restricting them to a list of explicitly registered extensions through the
`mediaTypes` property of <<mvc-config-content-negotiation,ContentNegotiationConfigurer>>.
[[mvc-ann-requestmapping-rfd]]
==== Suffix Match and RFD
@@ -1524,7 +1512,6 @@ See http://pivotal.io/security/cve-2015-5211[CVE-2015-5211] for additional
recommendations related to RFD.
[[mvc-ann-requestmapping-consumes]]
==== Consumable Media Types
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-consumes,Same as in Spring WebFlux>>#
@@ -1555,7 +1542,6 @@ TIP: `MediaType` provides constants for commonly used media types, such as
`APPLICATION_JSON_VALUE` and `APPLICATION_XML_VALUE`.
[[mvc-ann-requestmapping-produces]]
==== Producible Media Types
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-produces,Same as in Spring WebFlux>>#
@@ -1592,11 +1578,9 @@ TIP: `MediaType` provides constants for commonly used media types, such as
`APPLICATION_JSON_UTF8_VALUE` and `APPLICATION_XML_VALUE`.
[[mvc-ann-requestmapping-params-and-headers]]
==== Parameters, headers
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-params-and-headers,Same as in Spring
WebFlux>>#
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-params-and-headers,Same as in Spring WebFlux>>#
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
@@ -1633,7 +1617,6 @@ TIP: You can match `Content-Type` and `Accept` with the headers condition, but i
instead.
[[mvc-ann-requestmapping-head-options]]
==== HTTP HEAD, OPTIONS
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-head-options,Same as in Spring WebFlux>>#
@@ -1660,7 +1643,6 @@ You can explicitly map the `@RequestMapping` method to HTTP HEAD and HTTP OPTION
is not necessary in the common case.
[[mvc-ann-requestmapping-composed]]
==== Custom Annotations
[.small]#<<web-reactive.adoc#mvc-ann-requestmapping-head-options,Same as in Spring WebFlux>>#
@@ -1682,7 +1664,6 @@ logic. This is a more advanced option that requires subclassing
you can check the custom attribute and return your own `RequestCondition`.
[[mvc-ann-requestmapping-registration]]
==== Explicit Registrations
[.small]#<<web-reactive.adoc#webflux-ann-requestmapping-registration,Same as in Spring WebFlux>>#
@@ -1729,7 +1710,6 @@ public class MyConfig {
supported controller method arguments and return values.
[[mvc-ann-arguments]]
==== Method Arguments
[.small]#<<web-reactive.adoc#webflux-ann-arguments,Same as in Spring WebFlux>>#
@@ -1865,7 +1845,6 @@ and others) and is equivalent to `required=false`.
|===
[[mvc-ann-return-types]]
==== Return Values
[.small]#<<web-reactive.adoc#webflux-ann-return-types,Same as in Spring WebFlux>>#
@@ -1982,7 +1961,6 @@ through a `WebDataBinder` (see <<mvc-ann-initbinder>>) or by registering
<<core.adoc#format, Spring Field Formatting>>.
[[mvc-ann-matrix-variables]]
==== Matrix Variables
[.small]#<<web-reactive.adoc#webflux-ann-matrix-variables,Same as in Spring WebFlux>>#
@@ -2080,7 +2058,6 @@ you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through
`<mvc:annotation-driven enable-matrix-variables="true"/>`.
[[mvc-ann-requestparam]]
==== `@RequestParam`
[.small]#<<web-reactive.adoc#webflux-ann-requestparam,Same as in Spring WebFlux>>#
@@ -2135,7 +2112,6 @@ and is not resolved by any other argument resolver, is treated as if it were ann
with `@RequestParam`.
[[mvc-ann-requestheader]]
==== `@RequestHeader`
[.small]#<<web-reactive.adoc#webflux-ann-requestheader,Same as in Spring WebFlux>>#
@@ -2188,7 +2164,6 @@ example, a method parameter annotated with `@RequestHeader("Accept")` can be of
`String` but also `String[]` or `List<String>`.
[[mvc-ann-cookievalue]]
==== `@CookieValue`
[.small]#<<web-reactive.adoc#webflux-ann-cookievalue,Same as in Spring WebFlux>>#
@@ -2224,7 +2199,6 @@ if the target method parameter type is not
`String`, type conversion is applied automatically. See <<mvc-ann-typeconversion>>.
[[mvc-ann-modelattrib-method-args]]
==== `@ModelAttribute`
[.small]#<<web-reactive.adoc#webflux-ann-modelattrib-method-args,Same as in Spring WebFlux>>#
@@ -2352,7 +2326,6 @@ and is not resolved by any other argument resolver is treated as if it were anno
with `@ModelAttribute`.
[[mvc-ann-sessionattributes]]
==== `@SessionAttributes`
[.small]#<<web-reactive.adoc#webflux-ann-sessionattributes,Same as in Spring WebFlux>>#
@@ -2409,7 +2382,6 @@ storage, as the following example shows:
====
[[mvc-ann-sessionattribute]]
==== `@SessionAttribute`
[.small]#<<web-reactive.adoc#webflux-ann-sessionattribute,Same as in Spring WebFlux>>#
@@ -2440,7 +2412,6 @@ workflow, consider using `@SessionAttributes` as described in
<<mvc-ann-sessionattributes>>.
[[mvc-ann-requestattrib]]
==== `@RequestAttribute`
[.small]#<<web-reactive.adoc#webflux-ann-requestattrib,Same as in Spring WebFlux>>#
@@ -2462,7 +2433,6 @@ or `HandlerInterceptor`):
====
[[mvc-redirecting-passing-data]]
==== Redirect Attributes
@@ -2508,7 +2478,6 @@ other redirect attributes, flash attributes are saved in the HTTP session (and,
not appear in the URL). See <<mvc-flash-attributes>> for more information.
[[mvc-flash-attributes]]
==== Flash Attributes
@@ -2555,7 +2524,6 @@ Therefore, we recommend that you use flash attributes mainly for redirect scenar
****
[[mvc-multipart-forms]]
==== Multipart
[.small]#<<web-reactive.adoc#webflux-multipart-forms,Same as in Spring WebFlux>>#
@@ -2692,7 +2660,6 @@ public String handle(**@Valid** @RequestPart("meta-data") MetaData metadata,
====
[[mvc-ann-requestbody]]
==== `@RequestBody`
[.small]#<<web-reactive.adoc#webflux-ann-requestbody,Same as in Spring WebFlux>>#
@@ -2734,7 +2701,6 @@ as the following example shows:
====
[[mvc-ann-httpentity]]
==== HttpEntity
[.small]#<<web-reactive.adoc#webflux-ann-httpentity,Same as in Spring WebFlux>>#
@@ -2754,7 +2720,6 @@ container object that exposes request headers and body. The following listing sh
====
[[mvc-ann-responsebody]]
==== `@ResponseBody`
[.small]#<<web-reactive.adoc#webflux-ann-responsebody,Same as in Spring WebFlux>>#
@@ -2789,7 +2754,6 @@ You can combine `@ResponseBody` methods with JSON serialization views.
See <<mvc-ann-jackson>> for details.
[[mvc-ann-responseentity]]
==== ResponseEntity
[.small]#<<web-reactive.adoc#webflux-ann-responseentity,Same as in Spring WebFlux>>#
@@ -2814,15 +2778,11 @@ to produce the `ResponseEntity` asynchronously, and/or single and multi-value re
types for the body.
[[mvc-ann-jackson]]
==== Jackson JSON
Spring offers support for the Jackson JSON library.
[[mvc-ann-jsonview]]
===== Jackson Serialization Views
[.small]#<<web-reactive.adoc#webflux-ann-jsonview,Same as in Spring WebFlux>>#
@@ -2952,17 +2912,15 @@ The following example adds only one attribute:
====
NOTE: When a name is not explicitly specified, a default name is chosen based on the `Object`
type, as explained in the Javadoc for
{api-spring-framework}/core/Conventions.html[`Conventions`].
type, as explained in the javadoc for {api-spring-framework}/core/Conventions.html[`Conventions`].
You can always assign an explicit name by using the overloaded `addAttribute` method or
through the `name` attribute on `@ModelAttribute` (for a return value).
You can also use `@ModelAttribute` as a method-level annotation on `@RequestMapping`
methods, in which case the return value of the `@RequestMapping` method is interpreted as a
model attribute. This is typically not required, as it is the default behavior in HTML
controllers, unless the return value is a `String` that would otherwise be interpreted
as a view name (see also <<mvc-coc-r2vnt>>). `@ModelAttribute` can also help to customize
the model attribute name, as the following example shows:
You can also use `@ModelAttribute` as a method-level annotation on `@RequestMapping` methods,
in which case the return value of the `@RequestMapping` method is interpreted as a model
attribute. This is typically not required, as it is the default behavior in HTML controllers,
unless the return value is a `String` that would otherwise be interpreted as a view name.
`@ModelAttribute` can also customize the model attribute name, as the following example shows:
====
[source,java,indent=0]
@@ -3146,7 +3104,6 @@ Support for `@ExceptionHandler` methods in Spring MVC is built on the `Dispatche
level, <<mvc-exceptionhandlers,HandlerExceptionResolver>> mechanism.
[[mvc-ann-exceptionhandler-args]]
==== Method Arguments
@@ -3338,7 +3295,8 @@ as the following example shows:
The selectors in the preceding example are evaluated at runtime and may negatively impact
performance if used extensively. See the
{api-spring-framework}/web/bind/annotation/ControllerAdvice.html[`@ControllerAdvice`]
Javadoc for more details.
javadoc for more details.
@@ -3348,8 +3306,6 @@ Javadoc for more details.
This section describes various options available in the Spring Framework to work with URI's.
include::web-uris.adoc[leveloffset=+2]
@@ -3551,6 +3507,7 @@ capital letters of the class and the method name (for example, the `getThing` me
[[mvc-ann-async]]
== Asynchronous Requests
[.small]#<<mvc-ann-async-vs-webflux,Compared to WebFlux>>#
@@ -3674,7 +3631,6 @@ https://spring.io/blog/2012/05/07/spring-mvc-3-2-preview-introducing-servlet-3-a
blog posts] that introduced asynchronous request processing support in Spring MVC 3.2.
[[mvc-ann-async-exceptions]]
==== Exception Handling
@@ -3689,7 +3645,6 @@ When you use `Callable`, similar processing logic occurs, the main difference be
the result is returned from the `Callable` or an exception is raised by it.
[[mvc-ann-async-interception]]
==== Interception
@@ -3704,9 +3659,9 @@ lifecycle of an asynchronous request (for example, to handle a timeout event). S
for more details.
`DeferredResult` provides `onTimeout(Runnable)` and `onCompletion(Runnable)` callbacks.
See the {api-spring-framework}/web/context/request/async/DeferredResult.html[Javadoc of `DeferredResult`] for more details. `Callable` can be substituted for
`WebAsyncTask` that exposes additional methods for timeout and completion callbacks.
See the {api-spring-framework}/web/context/request/async/DeferredResult.html[javadoc of `DeferredResult`]
for more details. `Callable` can be substituted for `WebAsyncTask` that exposes additional
methods for timeout and completion callbacks.
[[mvc-ann-async-vs-webflux]]
@@ -3732,10 +3687,10 @@ Spring MVC even supports streaming, including reactive back pressure. However, i
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.
Another fundamental difference is that Spring MVC does not support asynchronous or
reactive types in controller method arguments (for example, `@RequestBody`, `@RequestPart`, and
others), nor does it have any explicit support for asynchronous and reactive types as
model attributes. Spring WebFlux does support all that.
Another fundamental difference is that Spring MVC does not support asynchronous or reactive
types in controller method arguments (for example, `@RequestBody`, `@RequestPart`, and others),
nor does it have any explicit support for asynchronous and reactive types as model attributes.
Spring WebFlux does support all that.
@@ -3748,7 +3703,6 @@ What if you want to produce multiple asynchronous values and have those written
response? This section describes how to do so.
[[mvc-ann-async-objects]]
==== Objects
@@ -3790,7 +3744,6 @@ This call, in turn, performs one final `ASYNC` dispatch to the application, duri
invokes the configured exception resolvers and completes the request.
[[mvc-ann-async-sse]]
==== SSE
@@ -3830,7 +3783,6 @@ a wide range of browsers.
See also <<mvc-ann-async-objects,previous section>> for notes on exception handling.
[[mvc-ann-async-output-stream]]
==== Raw Data
@@ -3919,7 +3871,6 @@ The asynchronous request processing feature must be enabled at the Servlet conta
The MVC configuration also exposes several options for asynchronous requests.
[[mvc-ann-async-configuration-servlet3]]
==== Servlet Container
@@ -3935,7 +3886,6 @@ In `web.xml` configuration, you can add `<async-supported>true</async-supported>
`<dispatcher>ASYNC</dispatcher>` to filter mappings.
[[mvc-ann-async-configuration-spring-mvc]]
==== Spring MVC
@@ -3959,12 +3909,11 @@ Note that you can also set the default timeout value on a `DeferredResult`,
a `ResponseBodyEmitter`, and an `SseEmitter`. For a `Callable`, you can use `WebAsyncTask` to provide
a timeout value.
include::webmvc-cors.adoc[leveloffset=+1]
[[mvc-web-security]]
== Web Security
[.small]#<<web-reactive.adoc#webflux-web-security,Same as in Spring WebFlux>>#
@@ -3982,6 +3931,7 @@ http://hdiv.org/[HDIV] is another web security framework that integrates with Sp
[[mvc-caching]]
== HTTP Caching
[.small]#<<web-reactive.adoc#webflux-caching,Same as in Spring WebFlux>>#
@@ -4122,12 +4072,11 @@ for optimal performance. See the section on configuring <<mvc-config-static-reso
You can use the `ShallowEtagHeaderFilter` to add "`shallow`" `eTag` values that are computed from the
response content and, thus, save bandwidth but not CPU time. See <<filters-shallow-etag>>.
include::webmvc-view.adoc[leveloffset=+1]
[[mvc-config]]
== MVC Config
[.small]#<<web-reactive.adoc#webflux-config,Same as in Spring WebFlux>>#
@@ -4901,7 +4850,7 @@ The following example shows how to achieve the same configuration in XML:
You can customize options related to path matching and treatment of the URL.
For details on the individual options, see the
{api-spring-framework}/web/servlet/config/annotation/PathMatchConfigurer.html[`PathMatchConfigurer`] Javadoc.
{api-spring-framework}/web/servlet/config/annotation/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc.
The following example shows how to customize path matching in Java configuration:
@@ -5019,6 +4968,7 @@ by letting it be detected through a `<component-scan/>` declaration.
[[mvc-http2]]
== HTTP/2
[.small]#<<web-reactive.adoc#webflux-http2,Same as in Spring WebFlux>>#

2
src/docs/asciidoc/web/websocket-intro.adoc
View File

@@ -57,6 +57,7 @@ instructions of the cloud provider related to WebSocket support.
[[websocket-intro-architecture]]
== HTTP Versus WebSocket
@@ -82,6 +83,7 @@ In the absence of that, they need to come up with their own conventions.
[[websocket-intro-when-to-use]]
== When to Use WebSockets

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

@@ -7,12 +7,11 @@ This part of the reference documentation covers support for Servlet stack, WebSo
messaging that includes raw WebSocket interactions, WebSocket emulation through SockJS, and
publish-subscribe messaging through STOMP as a sub-protocol over WebSocket.
include::websocket-intro.adoc[leveloffset=+1]
[[websocket-server]]
== WebSocket API
[.small]#<<web-reactive.adoc#webflux-websocket-server,Same as in Spring WebFlux>>#
@@ -478,6 +477,7 @@ The following example shows the XML configuration equivalent of the preceding ex
[[websocket-fallback]]
== SockJS Fallback
@@ -846,7 +846,8 @@ jettyHttpClient.setExecutor(new QueuedThreadPool(1000));
----
====
The following example shows the server-side SockJS-related properties (see Javadoc for details) that you should also consider customizing:
The following example shows the server-side SockJS-related properties (see javadoc for details)
that you should also consider customizing:
====
[source,java,indent=0]
@@ -874,6 +875,7 @@ The following example shows the server-side SockJS-related properties (see Javad
[[websocket-stomp]]
== STOMP
@@ -1263,7 +1265,6 @@ methods, as described in the following topics:
* <<websocket-stomp-exception-handler>>
[[websocket-stomp-message-mapping]]
==== `@MessageMapping`
@@ -1526,15 +1527,16 @@ public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
=== External Broker
The simple broker is great for getting started but supports only a subset of
STOMP commands (it does not support acks, receipts, and some other features), relies on a simple
message-sending loop, and is not suitable for clustering. As an alternative, you can upgrade your applications
to use a full-featured message broker.
STOMP commands (it does not support acks, receipts, and some other features),
relies on a simple message-sending loop, and is not suitable for clustering.
As an alternative, you can upgrade your applications to use a full-featured
message broker.
See the STOMP documentation for your message broker of choice (such as
http://www.rabbitmq.com/stomp.html[RabbitMQ],
http://activemq.apache.org/stomp.html[ActiveMQ], and others), install the broker,
and run it with STOMP support enabled. Then you can enable the STOMP broker relay (instead of the simple broker) in the
Spring configuration.
and run it with STOMP support enabled. Then you can enable the STOMP broker relay
(instead of the simple broker) in the Spring configuration.
The following example configuration enables a full-featured broker:
@@ -1600,8 +1602,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 <<websocket-stomp-handle-send>>, to broadcast messages to
subscribed WebSocket clients.
in <<websocket-stomp-handle-send>>, to broadcast messages to subscribed WebSocket clients.
In effect, the broker relay enables robust and scalable message broadcasting.
@@ -1612,10 +1613,10 @@ In effect, the broker relay enables robust and scalable message broadcasting.
A STOMP broker relay maintains a single "`system`" TCP connection to the broker.
This connection is used for messages originating from the server-side application
only, not for receiving messages. You can configure the STOMP credentials (that is, the STOMP frame `login` and `passcode` headers)
for this connection. This
is exposed in both the XML namespace and Java configuration as the
`systemLogin` and `systemPasscode` properties with default values of `guest` and `guest`.
only, not for receiving messages. You can configure the STOMP credentials (that is,
the STOMP frame `login` and `passcode` headers) for this connection. This is exposed
in both the XML namespace and Java configuration as the `systemLogin` and
`systemPasscode` properties with default values of `guest` and `guest`.
The STOMP broker relay also creates a separate TCP connection for every connected
WebSocket client. You can configure the STOMP credentials that are used for all TCP
@@ -2397,8 +2398,8 @@ In fact, if the capacity is left at its default value of Integer.MAX_VALUE,
the thread pool never increases beyond the core pool size, since
all additional tasks are queued.
See the Javadoc of `ThreadPoolExecutor` to learn how these
properties work and understand the various queuing strategies.
See the javadoc of `ThreadPoolExecutor` to learn how these properties work and
understand the various queuing strategies.
====
On the `clientOutboundChannel` side, it is all about sending messages to WebSocket
@@ -2419,9 +2420,8 @@ messages to a client.
The general idea is that, at any given time, only a single thread can be used
to send to a client. All additional messages, meanwhile, get buffered, and you
can use these properties to decide how long sending a message is allowed to
take and how much data can be buffered in the meantime. See the
Javadoc and documentation of the XML schema for this configuration for
important additional details.
take and how much data can be buffered in the meantime. See the javadoc and
documentation of the XML schema for important additional details.
The following example shows a possible configuration: