From a61d1076067162106c49e399322676093174167d Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Thu, 25 Oct 2018 15:15:58 +0200 Subject: [PATCH] Asciidoc revision (chapter declarations, javadoc references, etc) --- src/docs/asciidoc/core/core-aop-api.adoc | 28 +- src/docs/asciidoc/core/core-aop.adoc | 49 ++- src/docs/asciidoc/core/core-appendix.adoc | 11 +- src/docs/asciidoc/core/core-beans.adoc | 34 +- .../asciidoc/core/core-databuffer-codec.adoc | 8 +- src/docs/asciidoc/core/core-expressions.adoc | 25 +- src/docs/asciidoc/core/core-null-safety.adoc | 4 + src/docs/asciidoc/core/core-resources.adoc | 60 ++-- src/docs/asciidoc/core/core-validation.adoc | 63 ++-- src/docs/asciidoc/data-access-appendix.adoc | 1 + src/docs/asciidoc/data-access.adoc | 209 +++--------- src/docs/asciidoc/integration-appendix.adoc | 13 +- src/docs/asciidoc/integration.adoc | 298 ++++++------------ src/docs/asciidoc/languages.adoc | 1 - .../asciidoc/languages/dynamic-languages.adoc | 4 +- src/docs/asciidoc/overview.adoc | 2 +- src/docs/asciidoc/testing-webtestclient.adoc | 2 + src/docs/asciidoc/testing.adoc | 268 +++------------- src/docs/asciidoc/web-reactive.adoc | 3 + src/docs/asciidoc/web/integration.adoc | 7 + src/docs/asciidoc/web/web-uris.adoc | 1 - src/docs/asciidoc/web/webflux-cors.adoc | 5 + src/docs/asciidoc/web/webflux-functional.adoc | 5 + src/docs/asciidoc/web/webflux-view.adoc | 10 +- src/docs/asciidoc/web/webflux-webclient.adoc | 6 + src/docs/asciidoc/web/webflux-websocket.adoc | 3 +- src/docs/asciidoc/web/webflux.adoc | 61 +--- src/docs/asciidoc/web/webmvc-client.adoc | 2 + src/docs/asciidoc/web/webmvc-cors.adoc | 6 +- src/docs/asciidoc/web/webmvc-view.adoc | 36 +-- src/docs/asciidoc/web/webmvc.adoc | 150 +++------ src/docs/asciidoc/web/websocket-intro.adoc | 2 + src/docs/asciidoc/web/websocket.adoc | 40 +-- 33 files changed, 475 insertions(+), 942 deletions(-) diff --git a/src/docs/asciidoc/core/core-aop-api.adoc b/src/docs/asciidoc/core/core-aop-api.adoc index 8ca9d26bb6..e9b50444b1 100644 --- a/src/docs/asciidoc/core/core-aop-api.adoc +++ b/src/docs/asciidoc/core/core-aop-api.adoc @@ -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. diff --git a/src/docs/asciidoc/core/core-aop.adoc b/src/docs/asciidoc/core/core-aop.adoc index b9a45bd298..25a4a8e732 100644 --- a/src/docs/asciidoc/core/core-aop.adoc +++ b/src/docs/asciidoc/core/core-aop.adoc @@ -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. diff --git a/src/docs/asciidoc/core/core-appendix.adoc b/src/docs/asciidoc/core/core-appendix.adoc index 01dea17252..f33484b984 100644 --- a/src/docs/asciidoc/core/core-appendix.adoc +++ b/src/docs/asciidoc/core/core-appendix.adoc @@ -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"__> + __http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"__> + ---- ==== @@ -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"__> + __http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd"__> + ---- ==== @@ -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"__> + __http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd"__> + ---- ==== diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 3dc19f8a49..f1e8cdad98 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -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 -<>. [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 <> 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 <>. +Consult the {api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`] +javadoc for more detail. For more on AspectJ load-time weaving, see <>. @@ -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. diff --git a/src/docs/asciidoc/core/core-databuffer-codec.adoc b/src/docs/asciidoc/core/core-databuffer-codec.adoc index 706c21abe8..c530657fcc 100644 --- a/src/docs/asciidoc/core/core-databuffer-codec.adoc +++ b/src/docs/asciidoc/core/core-databuffer-codec.adoc @@ -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 diff --git a/src/docs/asciidoc/core/core-expressions.adoc b/src/docs/asciidoc/core/core-expressions.adoc index c4b0d609b9..d9f1006781 100644 --- a/src/docs/asciidoc/core/core-expressions.adoc +++ b/src/docs/asciidoc/core/core-expressions.adoc @@ -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 (<>) 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 (<>) +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-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 diff --git a/src/docs/asciidoc/core/core-null-safety.adoc b/src/docs/asciidoc/core/core-null-safety.adoc index d3a78657df..95b7ed82be 100644 --- a/src/docs/asciidoc/core/core-null-safety.adoc +++ b/src/docs/asciidoc/core/core-null-safety.adoc @@ -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 <>. + + + == JSR 305 meta-annotations Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305] diff --git a/src/docs/asciidoc/core/core-resources.adoc b/src/docs/asciidoc/core/core-resources.adoc index 634dd89548..78d5eb06dd 100644 --- a/src/docs/asciidoc/core/core-resources.adoc +++ b/src/docs/asciidoc/core/core-resources.adoc @@ -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 <>. + [[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. diff --git a/src/docs/asciidoc/core/core-validation.adoc b/src/docs/asciidoc/core/core-validation.adoc index 2ad222cbe9..bbad3ba393 100644 --- a/src/docs/asciidoc/core/core-validation.adoc +++ b/src/docs/asciidoc/core/core-validation.adoc @@ -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 `` 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 <> 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. diff --git a/src/docs/asciidoc/data-access-appendix.adoc b/src/docs/asciidoc/data-access-appendix.adoc index 4833f882d5..f9aaaff040 100644 --- a/src/docs/asciidoc/data-access-appendix.adoc +++ b/src/docs/asciidoc/data-access-appendix.adoc @@ -2,6 +2,7 @@ + [[xsd-schemas]] == XML Schemas diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index 214edfafdc..7048536937 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -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]] ==== Settings @@ -1073,7 +1064,6 @@ that are nested within `` and `` 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 `` 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 `` 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 `` 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-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-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 <> 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-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-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-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 <> 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-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 <> 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-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] diff --git a/src/docs/asciidoc/integration-appendix.adoc b/src/docs/asciidoc/integration-appendix.adoc index 19b77c0f28..12079dc62f 100644 --- a/src/docs/asciidoc/integration-appendix.adoc +++ b/src/docs/asciidoc/integration-appendix.adoc @@ -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"__> - + ---- ==== @@ -39,8 +41,7 @@ correct schema so that the elements in the `jee` namespace are available to you: [[xsd-schemas-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"__> + __http://www.springframework.org/schema/jms http://www.springframework.org/schema/jms/spring-jms.xsd"__> + ---- ==== @@ -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"__> + __http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd"__> + ---- ==== diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 1e8d0fc2c6..286f8b7367 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -14,6 +14,7 @@ a number of Java EE (and related) technologies. + [[remoting]] == Remoting and Web Services with Spring @@ -108,7 +109,6 @@ such additional invocation context when you use the RMI invoker, so you can, for plug in security frameworks or custom security credentials. - [[remoting-rmi-server]] ==== Exporting the Service by Using `RmiServiceExporter` @@ -158,7 +158,6 @@ NOTE: The `servicePort` property has been omitted (it defaults to 0). This means anonymous port is used to communicate with the service. - [[remoting-rmi-client]] ==== Linking in the Service at the Client @@ -214,7 +213,6 @@ Hessian offers a binary HTTP-based remoting protocol. It is developed by Caucho, information about Hessian itself at http://www.caucho.com[]. - [[remoting-caucho-protocols-hessian]] ==== Wiring up `DispatcherServlet` for Hessian @@ -252,7 +250,6 @@ pointing to specific exporter beans. In this case, each servlet name needs to ma its target exporter. - [[remoting-caucho-protocols-hessian-server]] ==== Exposing Your Beans by Using `HessianServiceExporter` @@ -316,7 +313,6 @@ the target exporter. The following example shows how to do so: ==== - [[remoting-caucho-protocols-hessian-client]] ==== Linking in the Service on the Client @@ -341,7 +337,6 @@ the `AccountService` to manage accounts, as the following example shows: ==== - [[remoting-caucho-protocols-security]] ==== Applying HTTP Basic Authentication to a Service Exposed through Hessian @@ -408,7 +403,6 @@ and http://openjdk.java.net/jeps/290. ==== - [[remoting-httpinvoker-server]] ==== Exposing the Service Object @@ -469,7 +463,6 @@ servlet name matching the bean name of the target exporter, as the following exa ==== - [[remoting-httpinvoker-client]] ==== Linking in the Service at the Client @@ -520,7 +513,6 @@ contract-first, document-driven web services -- highly recommended for building future-proof web services. - [[remoting-web-services-jaxws-export-servlet]] ==== Exposing Servlet-based Web Services by Using JAX-WS @@ -579,7 +571,6 @@ EE 5 environments, using the standard contract for JAX-WS servlet endpoint deplo See the various Java EE 5 web service tutorials for details. - [[remoting-web-services-jaxws-export-standalone]] ==== Exporting Standalone Web Services by Using JAX-WS @@ -642,7 +633,6 @@ and Spring's `@Autowired` configuration annotation is still honored): ==== - [[remoting-web-services-jaxws-export-ri]] ==== Exporting Web Services by Using JAX-WS RI's Spring Support @@ -666,7 +656,6 @@ See https://jax-ws-commons.java.net/spring/[https://jax-ws-commons.java.net/spri for details on setup and usage style. - [[remoting-web-services-jaxws-access]] ==== Accessing Web Services by Using JAX-WS @@ -811,7 +800,6 @@ the client and server: ==== - [[remoting-jms-server]] ==== Server-side Configuration @@ -864,7 +852,6 @@ On the server, you need to expose the service object that uses the ==== - [[remoting-jms-client]] ==== Client-side Configuration @@ -1001,7 +988,6 @@ scenarios. The `RestTemplate` will be deprecated in a future version and will no major new features added going forward. - [[rest-resttemplate]] ==== Using `RestTemplate` @@ -1061,7 +1047,6 @@ preparation and response extraction through callback interfaces. |=== - [[rest-resttemplate-create]] ===== Initialization @@ -1090,8 +1075,6 @@ TIP: Note that the `java.net` implementation for HTTP requests can raise an exce accessing the status of a response that represents an error (such as 401). If this is an issue, switch to another HTTP client library. - - [[rest-resttemplate-uri]] ===== URIs @@ -1141,8 +1124,6 @@ methods that accepts a `URI`. For more details on working with and encoding URIs, see <>. - - [[rest-template-headers]] ===== Headers @@ -1169,8 +1150,6 @@ You can use the `exchange()` methods to specify request headers, as the followin You can obtain response headers through many `RestTemplate` method variants that return `ResponseEntity`. - - [[rest-template-body]] ===== Body @@ -1209,8 +1188,6 @@ By default, `RestTemplate` registers all built-in to determine what optional conversion libraries are present. You can also set the message converters to use explicitly. - - [[rest-message-conversion]] ===== Message Conversion [.small]#<># @@ -1289,7 +1266,6 @@ and writes the media type supported by the Java I/O API. |=== - [[rest-template-jsonview]] ===== Jackson JSON Views @@ -1310,8 +1286,6 @@ to serialize only a subset of the object properties, as the following example sh ---- ==== - - [[rest-template-multipart]] ===== Multipart @@ -1356,7 +1330,6 @@ set the `Content-Type` to `multipart/form-data`. This is always the case when yo `MultipartBodyBuilder` which ensures an `HttpEntity` wrapper. - [[rest-async-resttemplate]] ==== Using `AsyncRestTemplate` (Deprecated) @@ -1365,6 +1338,7 @@ use the <> instead. + [[ejb]] == Enterprise JavaBeans (EJB) Integration @@ -1421,7 +1395,6 @@ not write another Service Locator, another JNDI lookup, or duplicate methods in a hand-coded Business Delegate unless you actually add real value in such code. - [[ejb-access-local]] ==== Accessing Local SLSBs @@ -1539,7 +1512,6 @@ Although not of interest to the majority of Spring users, those doing programmatic AOP work with EJBs may want to look at `LocalSlsbInvokerInterceptor`. - [[ejb-access-remote]] ==== Accessing Remote SLSBs @@ -1570,7 +1542,6 @@ the client code knowing or caring. Of course, this is optional: Nothing stops you from declaring `RemoteException` in your business interface. - [[ejb-access-ejb2-ejb3]] ==== Accessing EJB 2.x SLSBs Versus EJB 3 SLSBs @@ -1587,6 +1558,7 @@ lookups provides consistent and more explicit EJB access configuration. + [[jms]] == JMS (Java Message Service) @@ -1643,6 +1615,7 @@ resource into Spring's transaction management mechanisms. This section describes how to use Spring's JMS components. + [[jms-jmstemplate]] ==== Using `JmsTemplate` @@ -1705,8 +1678,6 @@ the EJB or servlet deployment descriptors. To ensure the use of these features w `JmsTemplate` inside an EJB, the client application should ensure that it references the managed implementation of the `ConnectionFactory`. - - [[jms-caching-resources]] ===== Caching Messaging Resources @@ -1725,8 +1696,6 @@ Between the `ConnectionFactory` and the `Send` operation, three intermediate objects are created and destroyed. To optimize the resource usage and increase performance, Spring provides two implementations of `ConnectionFactory`. - - [[jms-connection-factory]] ===== Using `SingleConnectionFactory` @@ -1737,8 +1706,6 @@ standalone environments so that the same connection can be used for multiple `JmsTemplate` calls that may span any number of transactions. `SingleConnectionFactory` takes a reference to a standard `ConnectionFactory` that would typically come from JNDI. - - [[jdbc-connection-factory-caching]] ===== Using `CachingConnectionFactory` @@ -1800,7 +1767,6 @@ property `defaultDestination`. The default destination is with send and receive operations that do not refer to a specific destination. - [[jms-mdp]] ==== Message Listener Containers @@ -1854,8 +1820,6 @@ the provider) or when the listener container shuts down (you can configure this the `acceptMessagesWhileStopping` flag). Make sure to use transacted sessions in case of reliability needs (for example, for reliable queue handling and durable topic subscriptions). - - [[jms-mdp-default]] ===== Using `DefaultMessageListenerContainer` @@ -1899,7 +1863,6 @@ the `acceptMessagesWhileStopping` flag). Make sure to use transacted sessions in reliability needs (for example, for reliable queue handling and durable topic subscriptions). - [[jms-tx]] ==== Transaction Management @@ -2000,7 +1963,6 @@ If you created the `JmsTemplate` and specified a default destination, the `send(MessageCreator c)` sends a message to that destination. - [[jms-msg-conversion]] ==== Using Message Converters @@ -2068,7 +2030,6 @@ MapMessage={ ==== - [[jms-callbacks]] ==== Using `SessionCallback` and `ProducerCallback` @@ -2097,7 +2058,6 @@ potentially be blocked indefinitely. The `receiveTimeout` property specifies how the receiver should wait before giving up waiting for a message. - [[jms-asynchronousMessageReception]] ==== Asynchronous reception: Message-Driven POJOs @@ -2165,9 +2125,9 @@ containers that ships with Spring (in this case, `DefaultMessageListenerContaine ---- ==== -See the Spring Javadoc of the various message listener containers (all of which implement {api-spring-framework}/jms/listener/MessageListenerContainer.html[MessageListenerContainer]) for a full -description of the features supported by each implementation. - +See the Spring javadoc of the various message listener containers (all of which implement +{api-spring-framework}/jms/listener/MessageListenerContainer.html[MessageListenerContainer]) +for a full description of the features supported by each implementation. [[jms-receiving-async-session-aware-message-listener]] @@ -2207,7 +2167,6 @@ interface, when using the `SessionAwareMessageListener` interface, it is the responsibility of the client code to handle any thrown exceptions. - [[jms-receiving-async-message-listener-adapter]] ==== Using `MessageListenerAdapter` @@ -2363,7 +2322,6 @@ If no `Destination` is found, an `InvalidDestinationException` is thrown call stack). - [[jms-tx-participation]] ==== Processing Messages Within Transactions @@ -2511,22 +2469,24 @@ from JNDI (by using ``). The Spring-based message listeners can then interact with the server-hosted `ResourceAdapter`, which also use the server's built-in `WorkManager`. -See the Javadoc for {api-spring-framework}/jms/listener/endpoint/JmsMessageEndpointManager.html[`JmsMessageEndpointManager`], {api-spring-framework}/jms/listener/endpoint/JmsActivationSpecConfig.html[`JmsActivationSpecConfig`], -and {api-spring-framework}/jca/support/ResourceAdapterFactoryBean.html[`ResourceAdapterFactoryBean`] for more details. +See the javadoc for {api-spring-framework}/jms/listener/endpoint/JmsMessageEndpointManager.html[`JmsMessageEndpointManager`], +{api-spring-framework}/jms/listener/endpoint/JmsActivationSpecConfig.html[`JmsActivationSpecConfig`], +and {api-spring-framework}/jca/support/ResourceAdapterFactoryBean.html[`ResourceAdapterFactoryBean`] +for more details. Spring also provides a generic JCA message endpoint manager that is not tied to JMS: `org.springframework.jca.endpoint.GenericMessageEndpointManager`. This component allows for using any message listener type (such as a CCI `MessageListener`) and any provider-specific `ActivationSpec` object. See your JCA provider's documentation to -find out about the actual capabilities of your connector, and see -the {api-spring-framework}/jca/endpoint/GenericMessageEndpointManager.html[`GenericMessageEndpointManager`] Javadoc for the Spring-specific configuration details. +find out about the actual capabilities of your connector, and see the +{api-spring-framework}/jca/endpoint/GenericMessageEndpointManager.html[`GenericMessageEndpointManager`] +javadoc for the Spring-specific configuration details. NOTE: JCA-based message endpoint management is very analogous to EJB 2.1 Message-Driven Beans. It uses the same underlying resource provider contract. As with EJB 2.1 MDBs, you can use any -message listener interface supported by your JCA provider in the Spring -context as well. Spring nevertheless provides explicit "`convenience`" support for JMS, -because JMS is the most common endpoint API used with the JCA endpoint management -contract. +message listener interface supported by your JCA provider in the Spring context as well. +Spring nevertheless provides explicit "`convenience`" support for JMS, because JMS is the +most common endpoint API used with the JCA endpoint management contract. @@ -2566,7 +2526,6 @@ several JMS destinations with the same method by adding additional `@JmsListener declarations to it. - [[jms-annotated-support]] ==== Enable Listener Endpoint Annotations @@ -2596,13 +2555,15 @@ your `@Configuration` classes, as the following example shows: By default, the infrastructure looks for a bean named `jmsListenerContainerFactory` as the source for the factory to use to create message listener containers. In this -case (and ignoring the JMS infrastructure setup), you can invoke the `processOrder` method -with a core poll size of three threads and a maximum pool size of ten threads. +case (and ignoring the JMS infrastructure setup), you can invoke the `processOrder` +method with a core poll size of three threads and a maximum pool size of ten threads. -You can customize the listener container factory to use for each annotation or you can configure -an explicit default by implementing the `JmsListenerConfigurer` -interface. The default is required only if at least one endpoint is registered -without a specific container factory. See the Javadoc of classes that implement {api-spring-framework}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`] for details and examples. +You can customize the listener container factory to use for each annotation or you can +configure an explicit default by implementing the `JmsListenerConfigurer` interface. +The default is required only if at least one endpoint is registered without a specific +container factory. See the javadoc of classes that implement +{api-spring-framework}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`] +for details and examples. If you prefer <>, you can use the `` element, as the following example shows: @@ -2624,7 +2585,6 @@ element, as the following example shows: ==== - [[jms-annotated-programmatic-registration]] ==== Programmatic Endpoint Registration @@ -2663,7 +2623,6 @@ Note that you could skip the use of `@JmsListener` altogether and programmatically register only your endpoints through `JmsListenerConfigurer`. - [[jms-annotated-method-signature]] ==== Annotated Endpoint Method Signature @@ -2748,7 +2707,6 @@ annotate the payload with `@Valid` and configure the necessary validator, as the ==== - [[jms-annotated-response]] ==== Response Management @@ -2965,10 +2923,10 @@ as the following example shows: ---- ==== -The following table describes all available attributes. See the class-level Javadoc -of the {api-spring-framework}/jms/listener/AbstractMessageListenerContainer.html[`AbstractMessageListenerContainer`] and its concrete subclasses for more details -on the individual properties. The Javadoc also provides a discussion of transaction -choices and message redelivery scenarios. +The following table describes all available attributes. See the class-level javadoc +of the {api-spring-framework}/jms/listener/AbstractMessageListenerContainer.html[`AbstractMessageListenerContainer`] +and its concrete subclasses for more details on the individual properties. The javadoc +also provides a discussion of transaction choices and message redelivery scenarios. [[jms-namespace-listener-container-tbl]] .Attributes of the JMS element @@ -3158,6 +3116,7 @@ The following table describes the available configuration options for the JCA va + [[jmx]] == JMX @@ -3273,7 +3232,6 @@ the application lifecycle. You can configure the `phase` at which the export happens or disable automatic registration by setting the `autoStartup` flag. - [[jmx-exporting-mbeanserver]] ==== Creating an MBeanServer @@ -3328,7 +3286,6 @@ supplied to the `MBeanExporter` through the `server` property. When you supply y correctly, you must have a JMX implementation on your classpath. - [[jmx-mbean-server]] ==== Reusing an Existing `MBeanServer` @@ -3381,7 +3338,6 @@ as the following example shows: ==== - [[jmx-exporting-lazy]] ==== Lazily Initialized MBeans @@ -3392,7 +3348,6 @@ defers obtaining the bean from the container until the first invocation on the p occurs. - [[jmx-exporting-auto]] ==== Automatic Registration of MBeans @@ -3419,7 +3374,6 @@ registration has its bean name used as the `ObjectName`. You can override this b as detailed in <>. - [[jmx-exporting-registration-behavior]] ==== Controlling the Registration Behavior @@ -3504,7 +3458,6 @@ attributes and operations, Spring JMX provides a comprehensive and extensible me for controlling the management interfaces of your beans. - [[jmx-interface-assembler]] ==== Using the `MBeanInfoAssembler` Interface @@ -3519,7 +3472,6 @@ saw in the examples in the preceding sections). Spring provides two additional i interface by using either source-level metadata or any arbitrary interface. - [[jmx-interface-metadata]] ==== Using Source-level Metadata: Java Annotations @@ -3667,7 +3619,6 @@ through the assembler property. This is all that is required to take advantage o metadata-driven management interfaces for your Spring-exposed MBeans. - [[jmx-interface-metadata-types]] ==== Source-level Metadata Types @@ -3754,7 +3705,6 @@ metadata types: |=== - [[jmx-interface-autodetect]] ==== Using the `AutodetectCapableMBeanInfoAssembler` Interface @@ -3804,7 +3754,6 @@ meaning. You can address this issue by changing the default behavior for `Object creation as defined in <>. - [[jmx-interface-java]] ==== Defining Management Interfaces by Using Java Interfaces @@ -3896,7 +3845,6 @@ on the bean and uses all of the interfaces implemented by that bean to create th management interface. - [[jmx-interface-methodnames]] ==== Using `MethodNameBasedMBeanInfoAssembler` @@ -4005,7 +3953,6 @@ If no entry in the `Properties` instance can be found, the bean key name is used the `ObjectName`. - [[jmx-naming-metadata]] ==== Using `MetadataNamingStrategy` @@ -4059,7 +4006,6 @@ example, the generated `ObjectName` for the following bean would be ==== - [[jmx-context-mbeanexport]] ==== Configuring Annotation-based MBean Export @@ -4220,7 +4166,6 @@ snippet of configuration: ==== - [[jmx-jsr160-client]] ==== Client-side Connectors @@ -4238,7 +4183,6 @@ To create an `MBeanServerConnection` to a remote JSR-160-enabled `MBeanServer`, ==== - [[jmx-jsr160-protocols]] ==== JMX over Hessian or SOAP @@ -4566,7 +4510,6 @@ indeed, what a `NotificationFilter` is, see the section of the JMX specification (1.2) entitled 'The JMX Notification Model'.) - [[jmx-notifications-publishing]] ==== Publishing Notifications @@ -4583,27 +4526,27 @@ The key interface in Spring's JMX notification publication support is the exported as an MBean through an `MBeanExporter` instance can implement the related `NotificationPublisherAware` interface to gain access to a `NotificationPublisher` instance. The `NotificationPublisherAware` interface supplies an instance of a -`NotificationPublisher` to the implementing bean through a simple setter method, which the -bean can then use to publish `Notifications`. - -As stated in the {api-spring-framework}/jmx/export/notification/NotificationPublisher.html[Javadoc of the `NotificationPublisher` interface], managed beans that -publish events through the `NotificationPublisher` mechanism are not responsible for -the state management of any notification listeners. Spring's JMX support -takes care of handling all the JMX infrastructure issues. All you need to do, as an -application developer, is implement the `NotificationPublisherAware` interface and start -publishing events by using the supplied `NotificationPublisher` instance. Note that the -`NotificationPublisher` is set after the managed bean has been registered with -an `MBeanServer`. - -Using a `NotificationPublisher` instance is quite straightforward. You create -a JMX `Notification` instance (or an instance of an appropriate `Notification` -subclass), populate the notification with the data pertinent to the event that is to be +`NotificationPublisher` to the implementing bean through a simple setter method, +which the bean can then use to publish `Notifications`. + +As stated in the javadoc of the +{api-spring-framework}/jmx/export/notification/NotificationPublisher.html[`NotificationPublisher`] +interface, managed beans that publish events through the `NotificationPublisher` +mechanism are not responsible for the state management of notification listeners. +Spring's JMX support takes care of handling all the JMX infrastructure issues. +All you need to do, as an application developer, is implement the +`NotificationPublisherAware` interface and start publishing events by using the +supplied `NotificationPublisher` instance. Note that the `NotificationPublisher` +is set after the managed bean has been registered with an `MBeanServer`. + +Using a `NotificationPublisher` instance is quite straightforward. You create a JMX +`Notification` instance (or an instance of an appropriate `Notification` subclass), +populate the notification with the data pertinent to the event that is to be published, and invoke the `sendNotification(Notification)` on the `NotificationPublisher` instance, passing in the `Notification`. -In the following example, exported instances of the `JmxTestBean` -publish a `NotificationEvent` every time the `add(int, int)` operation is -invoked: +In the following example, exported instances of the `JmxTestBean` publish a +`NotificationEvent` every time the `add(int, int)` operation is invoked: ==== [source,java,indent=0] @@ -4661,11 +4604,12 @@ homepage] at Oracle. specification] (JSR-000003). * The http://jcp.org/aboutJava/communityprocess/final/jsr160/index.html[JMX Remote API specification] (JSR-000160). -* The http://mx4j.sourceforge.net/[MX4J homepage]. (MX4Jan is an open-source implementation of +* The http://mx4j.sourceforge.net/[MX4J homepage]. (MX4J is an open-source implementation of various JMX specs.) + [[cci]] == JCA CCI @@ -4707,7 +4651,6 @@ following topics: * <> - [[cci-config-connector]] ==== Connector Configuration @@ -4738,7 +4681,6 @@ current thread. The resource is not aware of any global Java EE transactions tha might be running. - [[cci-config-connectionfactory]] ==== `ConnectionFactory` Configuration in Spring @@ -4784,7 +4726,6 @@ the corresponding implementation of the `ManagedConnectionFactory` interface for connector. This interface is part of the JCA SPI specification. - [[cci-config-cci-connections]] ==== Configuring CCI Connections @@ -4848,7 +4789,6 @@ The following example shows how to configure a `ConnectionSpecConnectionFactoryA ==== - [[cci-config-single-connection]] ==== Using a Single CCI Connection @@ -4904,7 +4844,6 @@ includes the following topics: * <> - [[cci-record-creator]] ==== Record Conversion @@ -4990,7 +4929,6 @@ The following example shows how to use the `RecordExtractor` interface: ==== - [[cci-using-template]] ==== Using `CciTemplate` @@ -5108,7 +5046,6 @@ The following listing shows the `CciTemplate` interface definition: ==== - [[cci-using-dao]] ==== Using DAO Support @@ -5146,7 +5083,6 @@ The following example shows how to use `CciDaoSupport`: ==== - [[automatic-output-generation]] ==== Automatic Output Record Generation @@ -5189,7 +5125,6 @@ NOTE: As the `CciTemplate` class is thread-safe, it is usually configured as a s instance. - [[template-summary]] ==== `CciTemplate` `Interaction` Summary @@ -5244,7 +5179,6 @@ corresponding methods called on the CCI `Interaction` interface: |=== - [[cci-straight]] ==== Using a CCI Connection and an Interaction Directly @@ -5293,7 +5227,6 @@ NOTE: `InteractionSpec` objects can either be shared across multiple template ca created inside every callback method. This is completely up to the DAO implementation. - [[cci-template-example]] ==== Example of `CciTemplate` Usage @@ -5452,15 +5385,14 @@ the followig example: The `org.springframework.jca.cci.object` package contains support classes that let you access the EIS in a different style: through reusable operation objects, analogous to -Spring's JDBC operation objects (see the <>). This usually encapsulates the -CCI API. An application-level input object is passed to the operation object, so it -can construct the input record and then convert the received record data to an -application-level output object and return it. +Spring's JDBC operation objects (see the <>). +This usually encapsulates the CCI API. An application-level input object is passed to +the operation object, so it can construct the input record and then convert the +received record data to an application-level output object and return it. NOTE: This approach is internally based on the `CciTemplate` class and the -`RecordCreator` or `RecordExtractor` interfaces, reusing the machinery of Spring's core -CCI support. - +`RecordCreator` or `RecordExtractor` interfaces, reusing the machinery of Spring's +core CCI support. [[cci-object-mapping-record]] @@ -5537,7 +5469,6 @@ with a specific `InteractionSpec`. The following example shows how to do so: ==== - [[cci-object-mapping-comm-area]] ==== Using `MappingCommAreaOperation` @@ -5571,7 +5502,6 @@ listing shows the relevant method signatures: ==== - [[cci-automatic-record-gen]] ==== Automatic Output Record Generation @@ -5581,7 +5511,6 @@ operation object provides a corresponding `setOutputRecordCreator(..)` method. F further information, see <>. - [[cci-object-summary]] ==== Summary @@ -5735,7 +5664,6 @@ follows: ==== - [[cci-objects-mapping-comm-area-example]] ==== Example of `MappingCommAreaOperation` Usage @@ -5902,6 +5830,7 @@ For more information on Spring's transaction facilities, see + [[mail]] == Email @@ -5924,17 +5853,17 @@ low-level resource handling on behalf of the client. The `org.springframework.mail` package is the root level package for the Spring Framework's email support. The central interface for sending emails is the `MailSender` -interface. A simple value object that encapsulates the properties of a simple mail such as -`from` and `to` (plus many others) is the `SimpleMailMessage` class. This package +interface. A simple value object that encapsulates the properties of a simple mail such +as `from` and `to` (plus many others) is the `SimpleMailMessage` class. This package also contains a hierarchy of checked exceptions that provide a higher level of abstraction over the lower level mail system exceptions, with the root exception being -`MailException`. See the {api-spring-framework}/mail/MailException.html[Javadoc] for more information on the rich mail -exception hierarchy. +`MailException`. See the {api-spring-framework}/mail/MailException.html[javadoc] +for more information on the rich mail exception hierarchy. The `org.springframework.mail.javamail.JavaMailSender` interface adds specialized -JavaMail features, such as MIME message support to the `MailSender` interface (from -which it inherits). `JavaMailSender` also provides a callback interface called `org.springframework.mail.javamail.MimeMessagePreparator` for preparing -a `MimeMessage`. +JavaMail features, such as MIME message support to the `MailSender` interface +(from which it inherits). `JavaMailSender` also provides a callback interface called +`org.springframework.mail.javamail.MimeMessagePreparator` for preparing a `MimeMessage`. @@ -5959,7 +5888,6 @@ Further assume that we have a requirement stating that an email message with an order number needs to be generated and sent to a customer who placed the relevant order. - [[mail-usage-simple]] ==== Basic `MailSender` and `SimpleMailMessage` Usage @@ -6038,7 +5966,6 @@ The following example shows the bean definitions for the preceding code: ==== - [[mail-usage-mime]] ==== Using `JavaMailSender` and `MimeMessagePreparator` @@ -6101,7 +6028,7 @@ into a <>, which then could be executed joinpoints on the `OrderManager` target. The Spring Framework's mail support ships with the standard JavaMail implementation. -See the relevant Javadoc for more information. +See the relevant javadoc for more information. @@ -6131,7 +6058,6 @@ to create a `MimeMessage`, as the following example shows: ==== - [[mail-javamail-mime-attachments]] ==== Sending Attachments and Inline Resources @@ -6139,8 +6065,6 @@ Multipart email messages allow for both attachments and inline resources. Exampl inline resources includee an image or a stylesheet that you want to use in your message but that you do not want displayed as an attachment. - - [[mail-javamail-mime-attachments-attachment]] ===== Attachments @@ -6170,8 +6094,6 @@ with a single JPEG image attachment: ---- ==== - - [[mail-javamail-mime-attachments-inline]] ===== Inline Resources @@ -6208,7 +6130,6 @@ and the resource are very important. Be sure to first add the text and then the resources. If you are doing it the other way around, it does not work. - [[mail-templates]] ==== Creating Email Content by Using a Templating Library @@ -6234,6 +6155,7 @@ FreeMarker, it becomes quite easy to do. + [[scheduling]] == Task Execution and Scheduling @@ -6275,7 +6197,6 @@ JMS's `AbstractMessageListenerContainer`, and Quartz integration all use the behavior, you can also use this abstraction for your own needs. - [[scheduling-task-executor-types]] ==== `TaskExecutor` Types @@ -6313,7 +6234,6 @@ The variants that Spring provides are as follows: replacing a CommonJ WorkManager for that purpose. - [[scheduling-task-executor-usage]] ==== Using a `TaskExecutor` @@ -6426,7 +6346,6 @@ methods are for simple, periodic execution, but the method that accepts a `Trigg much more flexible. - [[scheduling-trigger-interface]] ==== `Trigger` Interface @@ -6469,7 +6388,6 @@ default). The following listing shows the available methods for `Trigger` implem ==== - [[scheduling-trigger-implementations]] ==== `Trigger` Implementations @@ -6498,7 +6416,6 @@ Such a component could take advantage of dependency injection so that you can co externally and, therefore, easily modify or extend them. - [[scheduling-task-scheduler-implementations]] ==== `TaskScheduler` implementations @@ -6528,7 +6445,6 @@ Spring provides annotation support for both task scheduling and asynchronous met execution. - [[scheduling-enable-annotation-support]] ==== Enable Scheduling Annotations @@ -6547,10 +6463,13 @@ To enable support for `@Scheduled` and `@Async` annotations, you can add `@Enabl ---- ==== -You can pick and choose the relevant annotations for your application. For -example, if you need only support for `@Scheduled`, you can omit `@EnableAsync`. For more -fine-grained control, you can additionally implement the `SchedulingConfigurer` interface, -the `AsyncConfigurer` interface, or both. See the {api-spring-framework}/scheduling/annotation/SchedulingConfigurer.html[`SchedulingConfigurer`] and {api-spring-framework}/scheduling/annotation/AsyncConfigurer.html[`AsyncConfigurer`] Javadoc for full details. +You can pick and choose the relevant annotations for your application. For example, +if you need only support for `@Scheduled`, you can omit `@EnableAsync`. For more +fine-grained control, you can additionally implement the `SchedulingConfigurer` +interface, the `AsyncConfigurer` interface, or both. See the +{api-spring-framework}/scheduling/annotation/SchedulingConfigurer.html[`SchedulingConfigurer`] +and {api-spring-framework}/scheduling/annotation/AsyncConfigurer.html[`AsyncConfigurer`] +javadoc for full details. If you prefer XML configuration, you can use the `` element, as the following example shows: @@ -6575,7 +6494,6 @@ cannot get intercepted that way. For a more advanced mode of interception, consi switching to `aspectj` mode in combination with compile-time or load-time weaving. - [[scheduling-annotation-support-scheduled]] ==== The `@Scheduled` annotation @@ -6660,7 +6578,6 @@ container and once through the `@Configurable` aspect), with the consequence of ==== - [[scheduling-annotation-support-async]] ==== The `@Async` annotation @@ -6760,7 +6677,6 @@ However, you can manually set up Spring's `AsyncExecutionInterceptor` with Sprin in combination with a custom pointcut. - [[scheduling-annotation-support-qualification]] ==== Executor Qualification with `@Async` @@ -6786,7 +6702,6 @@ container, or it may be the name of a qualifier associated with any `Executor` ( specified with the `` element or Spring's `@Qualifier` annotation). - [[scheduling-annotation-support-exception]] ==== Exception Management with `@Async` @@ -6950,7 +6865,6 @@ The following example sets the `keep-alive` value to two minutes: ==== - [[scheduling-task-namespace-scheduled-tasks]] ==== The 'scheduled-tasks' Element @@ -7008,7 +6922,6 @@ http://quartz-scheduler.org[]. For convenience purposes, Spring offers a couple classes that simplify using Quartz within Spring-based applications. - [[scheduling-quartz-jobdetail]] ==== Using the `JobDetailFactoryBean` @@ -7071,7 +6984,6 @@ of the job, respectively. By default, the name of the job matches the bean name of the `JobDetailFactoryBean` (`exampleJob` in the preceding example above). - [[scheduling-quartz-method-invoking-job]] ==== Using the `MethodInvokingJobDetailFactoryBean` @@ -7140,7 +7052,6 @@ job does not start before the first one has finished. To make jobs resulting fro NOTE: By default, jobs will run in a concurrent fashion. - [[scheduling-quartz-cron]] ==== Wiring up Jobs by Using Triggers and `SchedulerFactoryBean` @@ -7197,11 +7108,10 @@ seconds and one running every morning at 6 AM. To finalize everything, we need t ---- ==== -More properties are available for the `SchedulerFactoryBean`, such as the -calendars used by the job details, properties to customize Quartz with, and otehrs. See -the -{api-spring-framework}/scheduling/quartz/SchedulerFactoryBean.html[`SchedulerFactoryBean` -Javadoc] for more information. +More properties are available for the `SchedulerFactoryBean`, such as the calendars +used by the job details, properties to customize Quartz with, and others. See the +{api-spring-framework}/scheduling/quartz/SchedulerFactoryBean.html[`SchedulerFactoryBean`] +javadoc for more information. @@ -7307,7 +7217,6 @@ For caching declaration, Spring's caching abstraction provides a set of Java ann * `@CacheConfig`: Shares some common cache-related settings at class-level. - [[cache-annotations-cacheable]] ==== The `@Cacheable` Annotation @@ -7348,8 +7257,6 @@ The following example uses `@Cacheable` on the `findBook` method: ---- ==== - - [[cache-annotations-cacheable-default-key]] ===== Default Key Generation @@ -7381,8 +7288,6 @@ If you want to keep using the previous key strategy, you can configure the depre hash-based `KeyGenerator` implementation. ==== - - [[cache-annotations-cacheable-key]] ===== Custom Key Generation Declaration @@ -7450,8 +7355,6 @@ so, specify the name of the `KeyGenerator` bean implementation to use, as the fo NOTE: The `key` and `keyGenerator` parameters are mutually exclusive and an operation that specifies both results in an exception. - - [[cache-annotations-cacheable-default-cache-resolver]] ===== Default Cache Resolution @@ -7462,8 +7365,6 @@ retrieves the caches defined at the operation level by using the configured To provide a different default cache resolver, you need to implement the `org.springframework.cache.interceptor.CacheResolver` interface. - - [[cache-annotations-cacheable-cache-resolver]] ===== Custom Cache Resolution @@ -7511,8 +7412,6 @@ results in an exception. as a custom `CacheManager` is ignored by the `CacheResolver` implementation. This is probably not what you expect. ==== - - [[cache-annotations-cacheable-synchronized]] ===== Synchronized Caching @@ -7540,8 +7439,6 @@ NOTE: This is an optional feature, and your favorite cache library may not suppo `CacheManager` implementations provided by the core framework support it. See the documentation of your cache provider for more details. - - [[cache-annotations-cacheable-condition]] ===== Conditional Caching @@ -7594,15 +7491,13 @@ supported wrapper, so the previous example can be rewritten as follows: Note that `result` still refers to `Book` and not `Optional`. As it might be `null`, we should use the safe navigation operator. - - [[cache-spel-context]] ===== Available Caching SpEL Evaluation Context Each `SpEL` expression evaluates against a dedicated <>. In addition to the built-in parameters, the -framework provides dedicated caching-related metadata, such as the argument names. The -following table describes the items made available to the context so that you can use them for key and +framework provides dedicated caching-related metadata, such as the argument names. The following +table describes the items made available to the context so that you can use them for key and conditional computations: [[cache-spel-context-tbl]] @@ -7643,7 +7538,7 @@ conditional computations: | Argument name | Evaluation context | Name of any of the method arguments. If the names are not available - (prehaps due to having no debug information), the argument names are also available under the `#a<#arg>` + (perhaps due to having no debug information), the argument names are also available under the `#a<#arg>` where `#arg` stands for the argument index (starting from `0`). | `#iban` or `#a0` (you can also use `#p0` or `#p<#arg>` notation as an alias). @@ -7657,7 +7552,6 @@ conditional computations: |=== - [[cache-annotations-put]] ==== The `@CachePut` Annotation @@ -7684,7 +7578,6 @@ on the result object (that is, the `#result` variable), as these are validated u the exclusion. - [[cache-annotations-evict]] ==== The `@CacheEvict` annotation @@ -7730,7 +7623,6 @@ cache). This is not the case with `@Cacheable` which adds or updates data into t and, thus, requires a result. - [[cache-annotations-caching]] ==== The `@Caching` Annotation @@ -7750,7 +7642,6 @@ The following example uses two `@CacheEvict` annotations: ==== - [[cache-annotations-config]] ==== The `@CacheConfig` annotation @@ -7787,7 +7678,6 @@ gives three levels of customizations for each cache operation: * At the operation level. - [[cache-annotation-enable]] ==== Enabling Caching Annotations @@ -7827,8 +7717,8 @@ Alternatively, for XML configuration you can use the `cache:annotation-driven` e ---- ==== -Both the `cache:annotation-driven` element and the `@EnableCaching` annotation let you specify various -options that influence the way the caching behavior is added to the +Both the `cache:annotation-driven` element and the `@EnableCaching` annotation let you +specify various options that influence the way the caching behavior is added to the application through AOP. The configuration is intentionally similar with that of <>. @@ -7837,9 +7727,9 @@ for interception of calls through the proxy only. Local calls within the same cl cannot get intercepted that way. For a more advanced mode of interception, consider switching to `aspectj` mode in combination with compile-time or load-time weaving. -NOTE: For more detail about advanced customizations (using Java configuration) that are required to implement `CachingConfigurer`, -see {api-spring-framework}/cache/annotation/CachingConfigurer.html[the -Javadoc]. +NOTE: For more detail about advanced customizations (using Java configuration) that are +required to implement `CachingConfigurer`, see the +{api-spring-framework}/cache/annotation/CachingConfigurer.html[javadoc]. [[cache-annotation-driven-settings]] .Cache annotation settings @@ -7848,7 +7738,7 @@ Javadoc]. | XML Attribute | Annotation Attribute | Default | Description | `cache-manager` -| N/A (See {api-spring-framework}/cache/annotation/CachingConfigurer.html[the `CachingConfigurer` Javadoc]) +| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) | `cacheManager` | The name of the cache manager to use. A default `CacheResolver` is initialized behind the scenes with this cache manager (or `cacheManager` if not set). For more @@ -7856,19 +7746,19 @@ Javadoc]. attribute. | `cache-resolver` -| N/A (See {api-spring-framework}/cache/annotation/CachingConfigurer.html[the`CachingConfigurer` Javadoc]) +| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) | A `SimpleCacheResolver` using the configured `cacheManager`. | The bean name of the CacheResolver that is to be used to resolve the backing caches. This attribute is not required and needs to be specified only as an alternative to the 'cache-manager' attribute. | `key-generator` -| N/A (See {api-spring-framework}/cache/annotation/CachingConfigurer.html[the`CachingConfigurer` Javadoc]) +| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) | `SimpleKeyGenerator` | Name of the custom key generator to use. | `error-handler` -| N/A (See {api-spring-framework}/cache/annotation/CachingConfigurer.html[the`CachingConfigurer` Javadoc]) +| N/A (see the {api-spring-framework}/cache/annotation/CachingConfigurer.html[`CachingConfigurer`] javadoc) | `SimpleCacheErrorHandler` | The name of the custom cache error handler to use. By default, any exception thrown during a cache related operation is thrown back at the client. @@ -7938,7 +7828,6 @@ the expected behavior, so you should not rely on this feature in your initializa code (that is, `@PostConstruct`). - [[cache-annotation-stereotype]] ==== Using Custom Annotations @@ -8018,7 +7907,6 @@ caching abstraction, you can switch to these standard annotations without changi your cache storage (or configuration, for that matter). - [[cache-jsr-107-summary]] ==== Feature Summary @@ -8062,7 +7950,7 @@ to the Spring's `CacheResolver` interface, except that JCache supports only a si cache. By default, a simple implementation retrieves the cache to use based on the name declared on the annotation. It should be noted that, if no cache name is specified on the annotation, a default is automatically generated. See the -Javadoc of `@CacheResult#cacheName()` for more information. +javadoc of `@CacheResult#cacheName()` for more information. `CacheResolver` instances are retrieved by a `CacheResolverFactory`. It is possible to customize the factory for each cache operation, as the following example shows: @@ -8203,7 +8091,6 @@ them, you need to declare an appropriate `CacheManager` (an entity that controls and manages `Cache` instances and that can be used to retrieve these for storage). - [[cache-store-configuration-jdk]] ==== JDK `ConcurrentMap`-based Cache @@ -8235,7 +8122,6 @@ very fast, but it does not provide any management, persistence capabilities, or eviction contracts. - [[cache-store-configuration-ehcache]] ==== Ehcache-based Cache @@ -8263,7 +8149,6 @@ is then wired into the dedicated `CacheManager` implementation. Note that the en ehcache-specific configuration is read from `ehcache.xml`. - [[cache-store-configuration-caffeine]] ==== Caffeine Cache @@ -8305,7 +8190,6 @@ the https://github.com/ben-manes/caffeine/wiki[Caffeine documentation] for more information about those. - [[cache-store-configuration-gemfire]] ==== GemFire-based Cache @@ -8339,7 +8223,6 @@ example shows how to do so: ==== - [[cache-store-configuration-noop]] ==== Dealing with Caches without a Backing Store @@ -8404,4 +8287,5 @@ through the backing cache (when configuring it) or through its native API. + include::integration-appendix.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/languages.adoc b/src/docs/asciidoc/languages.adoc index c4ec56b062..695c5641f8 100644 --- a/src/docs/asciidoc/languages.adoc +++ b/src/docs/asciidoc/languages.adoc @@ -7,7 +7,6 @@ :tabsize: 4 :docinfo1: - include::languages/kotlin.adoc[leveloffset=+1] include::languages/groovy.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/languages/dynamic-languages.adoc b/src/docs/asciidoc/languages/dynamic-languages.adoc index 4549c3bcb1..44bb67b8b5 100644 --- a/src/docs/asciidoc/languages/dynamic-languages.adoc +++ b/src/docs/asciidoc/languages/dynamic-languages.adoc @@ -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"__> + __http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang.xsd"__> + + ---- diff --git a/src/docs/asciidoc/overview.adoc b/src/docs/asciidoc/overview.adoc index 11b4f2ae44..c844756258 100644 --- a/src/docs/asciidoc/overview.adoc +++ b/src/docs/asciidoc/overview.adoc @@ -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. diff --git a/src/docs/asciidoc/testing-webtestclient.adoc b/src/docs/asciidoc/testing-webtestclient.adoc index 1f3505d835..c772dce04c 100644 --- a/src/docs/asciidoc/testing-webtestclient.adoc +++ b/src/docs/asciidoc/testing-webtestclient.adoc @@ -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 diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc index 0d340a7dff..2425e0352b 100644 --- a/src/docs/asciidoc/testing.adoc +++ b/src/docs/asciidoc/testing.adoc @@ -17,6 +17,7 @@ set up service locator registries and similar structures). + [[testing-introduction]] == Introduction to Spring Testing @@ -28,6 +29,7 @@ manual.) + [[unit-testing]] == Unit Testing @@ -61,7 +63,6 @@ Spring includes a number of packages dedicated to mocking: * <> - [[mock-objects-env]] ==== Environment @@ -73,7 +74,6 @@ and <> out-of-container tests for code that depends on environment-specific properties. - [[mock-objects-jndi]] ==== JNDI @@ -84,7 +84,6 @@ names in test code as they do in a Java EE container, you can reuse both applica and configuration in testing scenarios without modification. - [[mock-objects-servlet]] ==== Servlet API @@ -101,7 +100,6 @@ The Spring MVC Test framework builds on the mock Servlet API objects to provide integration testing framework for Spring MVC. See <>. - [[mock-objects-web-reactive]] ==== Spring Web Reactive @@ -136,7 +134,6 @@ categories: * <> - [[unit-testing-utilities]] ==== General Testing Utilities @@ -167,7 +164,6 @@ utilities, see {api-spring-framework}/aop/support/AopUtils.html[`AopUtils`] and {api-spring-framework}/aop/framework/AopProxyUtils.html[`AopProxyUtils`]. - [[unit-testing-spring-mvc]] ==== Spring MVC Testing Utilities @@ -186,6 +182,7 @@ Framework>> instead. + [[integration-testing]] == Integration Testing @@ -245,7 +242,6 @@ The next few sections describe each goal and provide links to implementation and configuration details. - [[testing-ctx-management]] ==== Context Management and Caching @@ -303,7 +299,6 @@ See dependency injection of test fixtures with the <>. - [[testing-tx]] ==== Transaction Management @@ -329,7 +324,6 @@ framework to cause the transaction to commit instead of roll back by using the See transaction management with the <>. - [[testing-support-classes]] ==== Support Classes for Integration Testing @@ -398,13 +392,12 @@ includes the following topics: * <> - [[integration-testing-annotations-spring]] ==== Spring Testing Annotations The Spring Framework provides the following set of Spring-specific annotations that you can use in your unit and integration tests in conjunction with the TestContext framework. -See the corresponding Javadoc for further information, including default attribute +See the corresponding javadoc for further information, including default attribute values, attribute aliases, and other details. Spring's testing annotations include the following: @@ -425,8 +418,6 @@ Spring's testing annotations include the following: * <> * <> - - [[spring-testing-annotation-bootstrapwith]] ===== `@BootstrapWith` @@ -436,8 +427,6 @@ specify a custom `TestContextBootstrapper`. See the <> section for further details. - - [[spring-testing-annotation-contextconfiguration]] ===== `@ContextConfiguration` @@ -521,8 +510,6 @@ configuration classes as well as context initializers that are declared by super See <> and the `@ContextConfiguration` javadocs for further details. - - [[spring-testing-annotation-webappconfiguration]] ===== `@WebAppConfiguration` @@ -571,10 +558,8 @@ resource. The following example shows how to specify a classpath resource: Note that `@WebAppConfiguration` must be used in conjunction with `@ContextConfiguration`, either within a single test class or within a test class hierarchy. See the -{api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration` -Javadoc] for further details. - - +{api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`] +javadoc for further details. [[spring-testing-annotation-contexthierarchy]] ===== `@ContextHierarchy` @@ -617,11 +602,9 @@ If you need to merge or override the configuration for a given level of the cont hierarchy within a test class hierarchy, you must explicitly name that level by supplying the same value to the `name` attribute in `@ContextConfiguration` at each corresponding level in the class hierarchy. See <> and the -{api-spring-framework}/test/context/ContextHierarchy.html[`@ContextHierarchy` Javadoc] +{api-spring-framework}/test/context/ContextHierarchy.html[`@ContextHierarchy`] javadoc for further examples. - - [[spring-testing-annotation-activeprofiles]] ===== `@ActiveProfiles` @@ -667,7 +650,7 @@ programmatically by implementing a custom and registering it by using the `resolver` attribute of `@ActiveProfiles`. See <> and the -{api-spring-framework}/test/context/ActiveProfiles.html[`@ActiveProfiles` Javadoc] for +{api-spring-framework}/test/context/ActiveProfiles.html[`@ActiveProfiles`] javadoc for examples and further details. [[spring-testing-annotation-testpropertysource]] @@ -715,8 +698,6 @@ The following example demonstrates how to declare inlined properties: <1> Declare `timezone` and `port` properties. ==== - - [[spring-testing-annotation-dirtiescontext]] ===== `@DirtiesContext` @@ -863,9 +844,8 @@ as the following example shows. ==== For further details regarding the `EXHAUSTIVE` and `CURRENT_LEVEL` algorithms, see the -{api-spring-framework}/test/annotation/DirtiesContext.HierarchyMode.html[`DirtiesContext.HierarchyMode` Javadoc]. - - +{api-spring-framework}/test/annotation/DirtiesContext.HierarchyMode.html[`DirtiesContext.HierarchyMode`] +javadoc. [[spring-testing-annotation-testexecutionlisteners]] ===== `@TestExecutionListeners` @@ -891,10 +871,8 @@ The following example shows how to register two `TestExecutionListener` implemen ==== By default, `@TestExecutionListeners` supports inherited listeners. See the -{api-spring-framework}/test/context/TestExecutionListeners.html[Javadoc] for an example -and further details. - - +{api-spring-framework}/test/context/TestExecutionListeners.html[javadoc] +for an example and further details. [[spring-testing-annotation-commit]] ===== `@Commit` @@ -920,8 +898,6 @@ The following example shows how to use the `@Commit` annotation: <1> Commit the result of the test to the database. ==== - - [[spring-testing-annotation-rollback]] ===== `@Rollback` @@ -952,8 +928,6 @@ result is committed to the database): <1> Do not roll back the result. ==== - - [[spring-testing-annotation-beforetransaction]] ===== `@BeforeTransaction` @@ -998,8 +972,6 @@ transaction by using Spring's `@Transactional` annotation. As of Spring Framewor <1> Run this method after a transaction. ==== - - [[spring-testing-annotation-sql]] ===== `@Sql` @@ -1022,8 +994,6 @@ it: See <> for further details. - - [[spring-testing-annotation-sqlconfig]] ===== `@SqlConfig` @@ -1046,8 +1016,6 @@ configured with the `@Sql` annotation. The following example shows how to use it <1> Set the comment prefix and the separator in SQL scripts. ==== - - [[spring-testing-annotation-sqlgroup]] ===== `@SqlGroup` @@ -1074,7 +1042,6 @@ annotation. The following example shows how to declare an SQL group: ==== - [[integration-testing-annotations-standard]] ==== Standard Annotation Support @@ -1110,7 +1077,6 @@ you use test lifecycle callbacks from the underlying test framework instead of ==== - [[integration-testing-annotations-junit4]] ==== Spring JUnit 4 Testing Annotations @@ -1123,8 +1089,6 @@ rules>>, or <> * <> - - [[integration-testing-annotations-junit4-ifprofilevalue]] ===== `@IfProfileValue` @@ -1172,8 +1136,6 @@ Consider the following example: <1> Run this test for unit tests and integration tests. ==== - - [[integration-testing-annotations-junit4-profilevaluesourceconfiguration]] ===== `@ProfileValueSourceConfiguration` @@ -1195,8 +1157,6 @@ use `@ProfileValueSourceConfiguration`: <1> Use a custom profile value source. ==== - - [[integration-testing-annotations-junit4-timed]] ===== `@Timed` @@ -1227,8 +1187,6 @@ preemptively fails the test if the test takes too long. Spring's `@Timed`, on th hand, does not preemptively fail the test but rather waits for the test to complete before failing. - - [[integration-testing-annotations-junit4-repeat]] ===== `@Repeat` @@ -1253,7 +1211,6 @@ how to use the `@Repeat` annotation: ==== - [[integration-testing-annotations-junit-jupiter]] ==== Spring JUnit Jupiter Testing Annotations @@ -1266,8 +1223,6 @@ programming model in JUnit 5): * <> * <> - - [[integration-testing-annotations-junit-jupiter-springjunitconfig]] ===== `@SpringJUnitConfig` @@ -1308,11 +1263,9 @@ location of a configuration file: <1> Specify the location of a configuration file. ==== -See <> as well as the -{api-spring-framework}/test/context/junit/jupiter/SpringJUnitConfig.html[Javadoc for -`@SpringJUnitConfig`] and `@ContextConfiguration` for further details. - - +See <> as well as the javadoc for +{api-spring-framework}/test/context/junit/jupiter/SpringJUnitConfig.html[`@SpringJUnitConfig`] +and `@ContextConfiguration` for further details. [[integration-testing-annotations-junit-jupiter-springjunitwebconfig]] ===== `@SpringJUnitWebConfig` @@ -1357,14 +1310,12 @@ the location of a configuration file: <1> Specify the location of a configuration file. ==== -See <> as well as the Javadoc for +See <> as well as the javadoc for {api-spring-framework}/test/context/junit/jupiter/web/SpringJUnitWebConfig.html[`@SpringJUnitWebConfig`], {api-spring-framework}/test/context/ContextConfiguration.html[`@ContextConfiguration`], and {api-spring-framework}/test/context/web/WebAppConfiguration.html[`@WebAppConfiguration`] for further details. - - [[integration-testing-annotations-junit-jupiter-enabledif]] ===== `@EnabledIf` @@ -1404,8 +1355,6 @@ example, you can create a custom `@EnabledOnMac` annotation as follows: ---- ==== - - [[integration-testing-annotations-junit-jupiter-disabledif]] ===== `@DisabledIf` @@ -1446,7 +1395,6 @@ example, you can create a custom `@DisabledOnMac` annotation as follows: ==== - [[integration-testing-annotations-meta]] ==== Meta-Annotation Support for Testing @@ -1658,7 +1606,6 @@ management>>), <>, and <> sections. - [[testcontext-key-abstractions]] ==== Key Abstractions @@ -1671,10 +1618,9 @@ in turn, manages a `TestContext` that holds the context of the current test. The and delegates to `TestExecutionListener` implementations, which instrument the actual test execution by providing dependency injection, managing transactions, and so on. A `SmartContextLoader` is responsible for loading an `ApplicationContext` for a given test -class. See the {api-spring-framework}/test/context/package-summary.html[Javadoc] and the +class. See the {api-spring-framework}/test/context/package-summary.html[javadoc] and the Spring test suite for further information and examples of various implementations. - ===== `TestContext` `TestContext` encapsulates the context in which a test is executed (agnostic of the @@ -1682,8 +1628,6 @@ actual testing framework in use) and provides context management and caching sup the test instance for which it is responsible. The `TestContext` also delegates to a `SmartContextLoader` to load an `ApplicationContext` if requested. - - ===== `TestContextManager` `TestContextManager` is the main entry point into the Spring TestContext Framework and is @@ -1774,7 +1718,6 @@ directly but rather to extend `AbstractTestContextBootstrapper` or one of its co subclasses instead. - [[testcontext-tel-config]] ==== `TestExecutionListener` Configuration @@ -1794,17 +1737,14 @@ by default, exactly in the following order: * `SqlScriptsTestExecutionListener`: Runs SQL scripts configured by using the `@Sql` annotation. - [[testcontext-tel-config-registering-tels]] ===== Registering Custom `TestExecutionListener` Implementations -You can register custom `TestExecutionListener` implementations for a test class and its -subclasses by using the `@TestExecutionListeners` annotation. See -<> and the -{api-spring-framework}/test/context/TestExecutionListeners.html[Javadoc for -`@TestExecutionListeners`] for details and examples. - - +You can register custom `TestExecutionListener` implementations for a test class +and its subclasses by using the `@TestExecutionListeners` annotation. +See <> and the javadoc for +{api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners`] +for details and examples. [[testcontext-tel-config-automatic-discovery]] ===== Automatic Discovery of Default `TestExecutionListener` Implementations @@ -1823,8 +1763,6 @@ can contribute their own `TestExecutionListener` implementations to the list of listeners in the same manner through their own `META-INF/spring.factories` properties file. - - [[testcontext-tel-config-ordering]] ===== Ordering `TestExecutionListener` Implementations @@ -1836,7 +1774,7 @@ Spring's `AnnotationAwareOrderComparator`, which honors Spring's `Ordered` inter `TestExecutionListener` implementations provided by Spring implement `Ordered` with appropriate values. Third-party frameworks and developers should therefore make sure that their default `TestExecutionListener` implementations are registered in the proper order -by implementing `Ordered` or declaring `@Order`. See the Javadoc for the `getOrder()` +by implementing `Ordered` or declaring `@Order`. See the javadoc for the `getOrder()` methods of the core default `TestExecutionListener` implementations for details on what values are assigned to each core listener. @@ -1910,7 +1848,6 @@ be replaced with the following: ==== - [[testcontext-ctx-management]] ==== Context Management @@ -2000,8 +1937,6 @@ advanced use cases. * <> * <> - - [[testcontext-ctx-management-xml]] ===== Context Configuration with XML resources @@ -2073,8 +2008,6 @@ example shows how to do so: <1> Loading configuration from the default location. ==== - - [[testcontext-ctx-management-groovy]] ===== Context Configuration with Groovy Scripts @@ -2157,8 +2090,6 @@ The following listing shows how to combine both in an integration test: ==== ===== - - [[testcontext-ctx-management-javaconfig]] ===== Context Configuration with Annotated Classes @@ -2191,7 +2122,7 @@ The term "`annotated class`" can refer to any of the following: * A JSR-330 compliant class that is annotated with `javax.inject` annotations. * Any other class that contains `@Bean` methods. -See the Javadoc of +See the javadoc of {api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] and {api-spring-framework}/context/annotation/Bean.html[`@Bean`] for further information regarding the configuration and semantics of annotated classes, paying special attention @@ -2203,7 +2134,7 @@ TestContext framework tries to detect the presence of default configuration clas Specifically, `AnnotationConfigContextLoader` and `AnnotationConfigWebContextLoader` detect all `static` nested classes of the test class that meet the requirements for configuration class implementations, as specified in the -{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] Javadoc. +{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] javadoc. Note that the name of the configuration class is arbitrary. In addition, a test class can contain more than one `static` nested configuration class if desired. In the following example, the `OrderServiceTest` class declares a `static` nested configuration class @@ -2245,8 +2176,6 @@ class: <1> Loading configuration information from the nested class. ==== - - [[testcontext-ctx-management-mixed-config]] ===== Mixing XML, Groovy Scripts, and Annotated Classes @@ -2280,7 +2209,6 @@ define either a set of XML or Groovy resource locations or a set of `@Configurat classes from which your production `ApplicationContext` is loaded, but you still have the freedom to include or import the other type of configuration. - [[testcontext-ctx-management-initializers]] ===== Context Configuration with Context Initializers @@ -2334,8 +2262,6 @@ files or configuration classes. The following example shows how to do so: <1> Specifying configuration by using only an initializer. ==== - - [[testcontext-ctx-management-inheritance]] ===== Context Configuration Inheritance @@ -2440,8 +2366,6 @@ extend another and use both its own initializer and the superclass's initializer <2> Initializer defined in the subclass. ==== - - [[testcontext-ctx-management-env-profiles]] ===== Context Configuration with Environment Profiles @@ -2739,11 +2663,11 @@ programmatically instead of declaratively -- for example, based on: * The presence of custom class-level annotations. * Other concerns. -To resolve active bean definition profiles programmatically, you can implement a custom -`ActiveProfilesResolver` and register it by using the `resolver` attribute of -`@ActiveProfiles`. For further information, see the corresponding -{api-spring-framework}/test/context/ActiveProfilesResolver.html[Javadoc]. The following -example demonstrates how to implement and register a custom +To resolve active bean definition profiles programmatically, you can implement +a custom `ActiveProfilesResolver` and register it by using the `resolver` +attribute of `@ActiveProfiles`. For further information, see the corresponding +{api-spring-framework}/test/context/ActiveProfilesResolver.html[javadoc]. +The following example demonstrates how to implement and register a custom `OperatingSystemActiveProfilesResolver`: ==== @@ -2778,8 +2702,6 @@ example demonstrates how to implement and register a custom ---- ==== - - [[testcontext-ctx-management-property-sources]] ===== Context Configuration with Test Property Sources @@ -2862,8 +2784,6 @@ The following example sets two inlined properties: <1> Setting two properties by using two variations of the key-value syntax. ==== - - ====== Default Properties File Detection If `@TestPropertySource` is declared as an empty annotation (that is, without explicit @@ -2968,8 +2888,6 @@ to define properties in both a subclass and its superclass by using inline prope ---- ==== - - [[testcontext-ctx-management-web]] ===== Loading a `WebApplicationContext` @@ -3131,8 +3049,6 @@ managed per test method by the `ServletTestExecutionListener`. ==== -- - - [[testcontext-ctx-management-caching]] ===== Context Caching @@ -3210,7 +3126,6 @@ the next test. Note that support for the `@DirtiesContext` annotation is provide `DirtiesContextBeforeModesTestExecutionListener` and the `DirtiesContextTestExecutionListener`, which are enabled by default. - [[testcontext-ctx-management-ctx-hierarchies]] ===== Context Hierarchies @@ -3373,11 +3288,10 @@ NOTE: If you use `@DirtiesContext` in a test whose context is configured as part context hierarchy, you can use the `hierarchyMode` flag to control how the context cache is cleared. For further details, see the discussion of `@DirtiesContext` in <> and the -{api-spring-framework}/test/annotation/DirtiesContext.html[`@DirtiesContext` Javadoc]. +{api-spring-framework}/test/annotation/DirtiesContext.html[`@DirtiesContext`] javadoc. -- - [[testcontext-fixture-di]] ==== Dependency Injection of Test Fixtures @@ -3536,7 +3450,6 @@ bean by name there (as shown earlier, assuming that `myDataSource` is the bean ` ===== - [[testcontext-web-scoped-beans]] ==== Testing Request- and Session-scoped Beans @@ -3673,7 +3586,6 @@ configured theme. The following example shows how to do so: ==== - [[testcontext-tx]] ==== Transaction Management @@ -3685,7 +3597,6 @@ transactions, however, you must configure a `PlatformTransactionManager` bean in details are provided later). In addition, you must declare Spring's `@Transactional` annotation either at the class or the method level for your tests. - [[testcontext-tx-test-managed-transactions]] ===== Test-managed Transactions @@ -3700,7 +3611,6 @@ caution if Spring-managed or application-managed transactions are configured wit propagation type other than `REQUIRED` or `SUPPORTS` (see the discussion on <> for details). - [[testcontext-tx-enabling-transactions]] ===== Enabling and Disabling Transactions @@ -3771,8 +3681,6 @@ clean up the database after the `createUser()` method runs, since any changes ma database are automatically rolled back by the `TransactionalTestExecutionListener`. See <> for an additional example. - - [[testcontext-tx-rollback-and-commit-behavior]] ===== Transaction Rollback and Commit Behavior @@ -3791,9 +3699,9 @@ end the current test-managed transaction or to configure the current test-manage transaction for rollback or commit. Support for `TestTransaction` is automatically available whenever the `TransactionalTestExecutionListener` is enabled. -The following example demonstrates some of the features of `TestTransaction` (see the -{api-spring-framework}/test/context/transaction/TestTransaction.html[Javadoc for -`TestTransaction`] for further details): +The following example demonstrates some of the features of `TestTransaction`. See the +javadoc for {api-spring-framework}/test/context/transaction/TestTransaction.html[`TestTransaction`] +for further details. ==== [source,java,indent=0] @@ -3828,8 +3736,6 @@ The following example demonstrates some of the features of `TestTransaction` (se ---- ==== - - [[testcontext-tx-before-and-after-tx]] ===== Running Code Outside of a Transaction @@ -3849,8 +3755,6 @@ run within a transaction. In addition, methods annotated with `@BeforeTransactio `@AfterTransaction` are not run for test methods that are not configured to run within a transaction. - - [[testcontext-tx-mgr-config]] ===== Configuring a Transaction Manager @@ -3860,12 +3764,10 @@ of `PlatformTransactionManager` within the test's `ApplicationContext`, you can qualifier by using `@Transactional("myTxMgr")` or `@Transactional(transactionManager = "myTxMgr")`, or `TransactionManagementConfigurer` can be implemented by an `@Configuration` class. Consult the -{api-spring-framework}/test/context/transaction/TestContextTransactionUtils.html#retrieveTransactionManager-org.springframework.test.context.TestContext-java.lang.String-[Javadoc +{api-spring-framework}/test/context/transaction/TestContextTransactionUtils.html#retrieveTransactionManager-org.springframework.test.context.TestContext-java.lang.String-[javadoc for `TestContextTransactionUtils.retrieveTransactionManager()`] for details on the algorithm used to look up a transaction manager in the test's `ApplicationContext`. - - [[testcontext-tx-annotation-demo]] ===== Demonstration of All Transaction-related Annotations @@ -3994,7 +3896,6 @@ The following example shows matching methods for JPA: ===== - [[testcontext-executing-sql]] ==== Executing SQL Scripts @@ -4026,7 +3927,7 @@ integration test methods. scripts and is mainly intended for internal use within the framework. However, if you require full control over how SQL scripts are parsed and executed, `ScriptUtils` may suit your needs better than some of the other alternatives described later. See the -{api-spring-framework}/jdbc/datasource/init/ScriptUtils.html[Javadoc] for individual +{api-spring-framework}/jdbc/datasource/init/ScriptUtils.html[javadoc] for individual methods in `ScriptUtils` for further details. `ResourceDatabasePopulator` provides an object-based API for programmatically populating, @@ -4035,7 +3936,7 @@ resources. `ResourceDatabasePopulator` provides options for configuring the char encoding, statement separator, comment delimiters, and error handling flags used when parsing and running the scripts. Each of the configuration options has a reasonable default value. See the -{api-spring-framework}/jdbc/datasource/init/ResourceDatabasePopulator.html[Javadoc] for +{api-spring-framework}/jdbc/datasource/init/ResourceDatabasePopulator.html[javadoc] for details on default values. To run the scripts configured in a `ResourceDatabasePopulator`, you can invoke either the `populate(Connection)` method to execute the populator against a `java.sql.Connection` or the `execute(DataSource)` method @@ -4064,11 +3965,9 @@ Note that `ResourceDatabasePopulator` internally delegates to `ScriptUtils` for and running SQL scripts. Similarly, the `executeSqlScript(..)` methods in <> and <> -internally use a `ResourceDatabasePopulator` to run SQL scripts. See the Javadoc for the +internally use a `ResourceDatabasePopulator` to run SQL scripts. See the javadoc for the various `executeSqlScript(..)` methods for further details. - - [[testcontext-executing-sql-declaratively]] ===== Executing SQL scripts declaratively with @Sql @@ -4080,8 +3979,6 @@ before or after an integration test method. Note that method-level declarations class-level declarations and that support for `@Sql` is provided by the `SqlScriptsTestExecutionListener`, which is enabled by default. - - ====== Path Resource Semantics Each path is interpreted as a Spring `Resource`. A plain path (for example, @@ -4116,8 +4013,6 @@ within a JUnit Jupiter based integration test class: ---- ==== - - ====== Default Script Detection If no SQL scripts are specified, an attempt is made to detect a `default` script, @@ -4130,8 +4025,6 @@ depending on where `@Sql` is declared. If a default cannot be detected, an defined in the class `com.example.MyTest`, the corresponding default script is `classpath:com/example/MyTest.testMethod.sql`. - - ====== Declaring Multiple `@Sql` Sets If you need to configure multiple sets of SQL scripts for a given test class or test @@ -4217,7 +4110,7 @@ serves as global configuration for all SQL scripts within the test class hierarc declared directly by using the `config` attribute of the `@Sql` annotation, `@SqlConfig` serves as local configuration for the SQL scripts declared within the enclosing `@Sql` annotation. Every attribute in `@SqlConfig` has an implicit default value, which is -documented in the Javadoc of the corresponding attribute. Due to the rules defined for +documented in the javadoc of the corresponding attribute. Due to the rules defined for annotation attributes in the Java Language Specification, it is, unfortunately, not possible to assign a value of `null` to an annotation attribute. Thus, in order to support overrides of inherited global configuration, `@SqlConfig` attributes have an @@ -4230,7 +4123,7 @@ configuration, therefore, overrides global configuration. The configuration options provided by `@Sql` and `@SqlConfig` are equivalent to those supported by `ScriptUtils` and `ResourceDatabasePopulator` but are a superset of those -provided by the `` XML namespace element. See the Javadoc of +provided by the `` XML namespace element. See the javadoc of individual attributes in {api-spring-framework}/test/context/jdbc/Sql.html[`@Sql`] and {api-spring-framework}/test/context/jdbc/SqlConfig.html[`@SqlConfig`] for details. @@ -4255,7 +4148,7 @@ attributes of `@SqlConfig`. Furthermore, you can control the transaction propaga behavior by setting the `transactionMode` attribute of `@SqlConfig` (for example, whether scripts should be run in an isolated transaction). Although a thorough discussion of all supported options for transaction management with `@Sql` is beyond the scope of this -reference manual, the Javadoc for +reference manual, the javadoc for {api-spring-framework}/test/context/jdbc/SqlConfig.html[`@SqlConfig`] and {api-spring-framework}/test/context/jdbc/SqlScriptsTestExecutionListener.html[`SqlScriptsTestExecutionListener`] provide detailed information, and the following example shows a typical testing scenario @@ -4303,7 +4196,6 @@ run, since any changes made to the database (either within the test method or wi details). - [[testcontext-parallel-test-execution]] ==== Parallel Test Execution @@ -4345,20 +4237,17 @@ caching>> for details. WARNING: Parallel test execution in the Spring TestContext Framework is only possible if the underlying `TestContext` implementation provides a copy constructor, as explained in -the {api-spring-framework}/test/context/TestContext.html[Javadoc for `TestContext`]. The +the javadoc for {api-spring-framework}/test/context/TestContext.html[`TestContext`]. The `DefaultTestContext` used in Spring provides such a constructor. However, if you use a third-party library that provides a custom `TestContext` implementation, you need to verify that it is suitable for parallel test execution. - [[testcontext-support-classes]] ==== TestContext Framework Support Classes This section describes the various classes that support the Spring TestContext Framework. - - [[testcontext-junit4-runner]] ===== Spring JUnit 4 Runner @@ -4396,8 +4285,6 @@ In the preceding example, `@TestExecutionListeners` is configured with an empty disable the default listeners, which otherwise would require an `ApplicationContext` to be configured through `@ContextConfiguration`. - - [[testcontext-junit4-rules]] ===== Spring JUnit 4 Rules @@ -4478,8 +4365,6 @@ to be tied to a Spring-specific class hierarchy, you can configure your own cust classes by using `@RunWith(SpringRunner.class)` or <>. - - [[testcontext-junit-jupiter-extension]] ===== SpringExtension for JUnit Jupiter @@ -4572,8 +4457,6 @@ Similarly, the following example uses `@SpringJUnitWebConfig` to create a See the documentation for `@SpringJUnitConfig` and `@SpringJUnitWebConfig` in <> for further details. - - [[testcontext-junit-jupiter-di]] ===== Dependency Injection with `SpringExtension` @@ -4587,8 +4470,6 @@ Specifically, `SpringExtension` can inject dependencies from the test's `@BeforeAll`, `@AfterAll`, `@BeforeEach`, `@AfterEach`, `@Test`, `@RepeatedTest`, `@ParameterizedTest`, and others. - - [[testcontext-junit-jupiter-di-constructor]] ====== Constructor Injection @@ -4629,7 +4510,6 @@ In the following example, Spring injects the `OrderService` bean from the Note that this feature lets test dependencies be `final` and therefore immutable. - [[testcontext-junit-jupiter-di-method]] ====== Method Injection @@ -4684,7 +4564,6 @@ into the `placeOrderRepeatedly()` test method simultaneously. Note that the use of `@RepeatedTest` from JUnit Jupiter lets the test method gain access to the `RepetitionInfo`. - [[testcontext-support-classes-testng]] ===== TestNG Support Classes @@ -4747,7 +4626,6 @@ For more information on the differences between out-of-container and end-to-end integration tests, see <>. - [[spring-mvc-test-server]] ==== Server-Side Tests @@ -4810,8 +4688,6 @@ syntax is supported through the Jayway https://github.com/jayway/JsonPath[JsonPa project]. Many other options for verifying the result of the performed request are discussed later in this document. - - [[spring-mvc-test-server-static-imports]] ===== Static Imports @@ -4825,8 +4701,6 @@ lets you use content assist after typing the first character of the static metho Other IDEs (such as IntelliJ) may not require any additional configuration. Check the support for code completion on static members. - - [[spring-mvc-test-server-setup-options]] ===== Setup Choices @@ -4942,8 +4816,6 @@ answer. However, using the `standaloneSetup` does imply the need for additional Alternatively, you can write all your tests with `webAppContextSetup`, in order to always test against your actual Spring MVC configuration. - - [[spring-mvc-test-server-setup-steps]] ===== Setup Features @@ -4985,11 +4857,9 @@ You can use it as follows: ---- ==== -See the {api-spring-framework}/test/web/servlet/setup/ConfigurableMockMvcBuilder.html[Javadoc -for `ConfigurableMockMvcBuilder`] for a list of all MockMvc builder features or use the -IDE to explore the available options. - - +See the javadoc for +{api-spring-framework}/test/web/servlet/setup/ConfigurableMockMvcBuilder.html[`ConfigurableMockMvcBuilder`] +for a list of all MockMvc builder features or use the IDE to explore the available options. [[spring-mvc-test-server-performing-requests]] ===== Performing Requests @@ -5083,8 +4953,6 @@ If the same property is also specified on a given request, it overrides the defa value. That is why the HTTP method and URI in the default request do not matter, since they must be specified on every request. - - [[spring-mvc-test-server-defining-expectations]] ===== Defining Expectations @@ -5205,8 +5073,6 @@ resulting links by using XPath expressions: ---- ==== - - [[spring-mvc-test-server-filters]] ===== Filter Registrations @@ -5224,8 +5090,6 @@ instances, as the following example shows: Registered filters are invoked through the `MockFilterChain` from `spring-test`, and the last filter delegates to the `DispatcherServlet`. - - [[spring-mvc-test-vs-end-to-end-integration-tests]] ===== Differences Between Out-of-Container and End-to-End Integration Tests @@ -5272,8 +5136,6 @@ same time, it is important not to lose sight of the fact that the response is th important thing to check. In short, there is room here for multiple styles and strategies of testing even within the same project. - - [[spring-mvc-test-server-resources]] ===== Further Server-Side Test Examples @@ -5305,8 +5167,6 @@ NOTE: MockMvc works with templating technologies that do not rely on a Servlet C (for example, Thymeleaf, FreeMarker, and others), but it does not work with JSPs, since they rely on the Servlet container. - - [[spring-mvc-test-server-htmlunit-why]] ===== Why HtmlUnit Integration? @@ -5408,8 +5268,6 @@ the input to a user for creating a message. In addition, our form view can poten use additional resources that impact the behavior of the page, such as JavaScript validation. - - [[spring-mvc-test-server-htmlunit-why-integration]] ====== Integration Testing to the Rescue? @@ -5440,8 +5298,6 @@ and without side effects. We can then implement a small number of true end-to-en integration tests that validate simple workflows to ensure that everything works together properly. - - [[spring-mvc-test-server-htmlunit-why-mockmvc]] ====== Enter HtmlUnit Integration @@ -5449,8 +5305,6 @@ So how can we achieve a balance between testing the interactions of our pages an retain good performance within our test suite? The answer is: "`By integrating MockMvc with HtmlUnit.`" - - [[spring-mvc-test-server-htmlunit-options]] ====== HtmlUnit Integration Options @@ -5464,16 +5318,12 @@ You have a number of options when you want to integrate MockMvc with HtmlUnit: use Groovy for testing, ease development, and reuse code between integration and end-to-end testing. - - [[spring-mvc-test-server-htmlunit-mah]] ===== MockMvc and HtmlUnit This section describes how to integrate MockMvc and HtmlUnit. Use this option if you want to use the raw HtmlUnit libraries. - - [[spring-mvc-test-server-htmlunit-mah-setup]] ====== MockMvc and HtmlUnit Setup @@ -5509,8 +5359,6 @@ This ensures that any URL that references `localhost` as the server is directed requested by using a network connection, as normal. This lets us easily test the use of CDNs. - - [[spring-mvc-test-server-htmlunit-mah-usage]] ====== MockMvc and HtmlUnit Usage @@ -5573,8 +5421,6 @@ the behavior of JavaScript within our pages. See the http://htmlunit.sourceforge.net/gettingStarted.html[HtmlUnit documentation] for additional information about using HtmlUnit. - - [[spring-mvc-test-server-htmlunit-mah-advanced-builder]] ====== Advanced `MockMvcWebClientBuilder` @@ -5649,8 +5495,6 @@ the full power of MockMvc at our fingertips. TIP: For additional information on creating a `MockMvc` instance, see <>. - - [[spring-mvc-test-server-htmlunit-webdriver]] ===== MockMvc and WebDriver @@ -5658,8 +5502,6 @@ In the previous sections, we have seen how to use MockMvc in conjunction with th HtmlUnit APIs. In this section, we use additional abstractions within the Selenium http://docs.seleniumhq.org/projects/webdriver/[WebDriver] to make things even easier. - - [[spring-mvc-test-server-htmlunit-webdriver-why]] ====== Why WebDriver and MockMvc? @@ -5755,8 +5597,6 @@ https://github.com/SeleniumHQ/selenium/wiki/PageObjects[Page Object Pattern]. Wh can certainly do this with HtmlUnit, WebDriver provides some tools that we explore in the following sections to make this pattern much easier to implement. - - [[spring-mvc-test-server-htmlunit-webdriver-setup]] ====== MockMvc and WebDriver Setup @@ -5791,8 +5631,6 @@ directed to our `MockMvc` instance without the need for a real HTTP connection. URL is requested by using a network connection, as normal. This lets us easily test the use of CDNs. - - [[spring-mvc-test-server-htmlunit-webdriver-usage]] ====== MockMvc and WebDriver Usage @@ -5923,8 +5761,6 @@ as follows: For additional information on using WebDriver, see the Selenium https://github.com/SeleniumHQ/selenium/wiki/Getting-Started[WebDriver documentation]. - - [[spring-mvc-test-server-htmlunit-webdriver-advanced-builder]] ====== Advanced `MockMvcHtmlUnitDriverBuilder` @@ -5999,16 +5835,12 @@ the full power of MockMvc at our fingertips. TIP: For additional information on creating a `MockMvc` instance, see <>. - - [[spring-mvc-test-server-htmlunit-geb]] ===== MockMvc and Geb In the previous section, we saw how to use MockMvc with WebDriver. In this section, we use http://www.gebish.org/[Geb] to make our tests even Groovy-er. - - [[spring-mvc-test-server-htmlunit-geb-why]] ====== Why Geb and MockMvc? @@ -6017,8 +5849,6 @@ Geb is backed by WebDriver, so it offers many of the WebDriver. However, Geb makes things even easier by taking care of some of the boilerplate code for us. - - [[spring-mvc-test-server-htmlunit-geb-setup]] ====== MockMvc and Geb Setup @@ -6044,8 +5874,6 @@ This ensures that any URL referencing `localhost` as the server is directed to o requested by using a network connection as normal. This lets us easily test the use of CDNs. - - [[spring-mvc-test-server-htmlunit-geb-usage]] ====== MockMvc and Geb Usage @@ -6148,7 +5976,6 @@ For further details on how to get the most out of Geb, see http://www.gebish.org/manual/current/[The Book of Geb] user's manual. - [[spring-mvc-test-client]] ==== Client-Side REST Tests @@ -6249,8 +6076,6 @@ Assist -> Favorites. That allows using content assist after typing the first cha the static method name. Other IDEs (such IntelliJ) may not require any additional configuration. Check for the support for code completion on static members. - - [[spring-mvc-test-client-resources]] ===== Further Examples of Client-side REST Tests @@ -6258,8 +6083,6 @@ Spring MVC Test's own tests include https://github.com/spring-projects/spring-framework/tree/master/spring-test/src/test/java/org/springframework/test/web/client/samples[example tests] of client-side REST tests. - - include::testing-webtestclient.adoc[leveloffset=+2] @@ -6370,6 +6193,7 @@ for connection settings. See the PetClinic application for an example. + [[testing-resources]] == Further Resources See the following resources for more information about testing: diff --git a/src/docs/asciidoc/web-reactive.adoc b/src/docs/asciidoc/web-reactive.adoc index 2a4594ccdf..d8a05ad8ea 100644 --- a/src/docs/asciidoc/web-reactive.adoc +++ b/src/docs/asciidoc/web-reactive.adoc @@ -23,6 +23,7 @@ include::web/webflux-websocket.adoc[leveloffset=+1] + [[webflux-test]] == Testing [.small]#<># @@ -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 diff --git a/src/docs/asciidoc/web/integration.adoc b/src/docs/asciidoc/web/integration.adoc index 5a73bbcc9c..0d130d8edf 100644 --- a/src/docs/asciidoc/web/integration.adoc +++ b/src/docs/asciidoc/web/integration.adoc @@ -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. diff --git a/src/docs/asciidoc/web/web-uris.adoc b/src/docs/asciidoc/web/web-uris.adoc index 1eb04c5450..7c1453a58f 100644 --- a/src/docs/asciidoc/web/web-uris.adoc +++ b/src/docs/asciidoc/web/web-uris.adoc @@ -1,4 +1,3 @@ - [[web-uricomponents]] = UriComponents [.small]#Spring MVC and Spring WebFlux# diff --git a/src/docs/asciidoc/web/webflux-cors.adoc b/src/docs/asciidoc/web/webflux-cors.adoc index e2bd5fbcaf..66d6e738d4 100644 --- a/src/docs/asciidoc/web/webflux-cors.adoc +++ b/src/docs/asciidoc/web/webflux-cors.adoc @@ -7,6 +7,7 @@ describes how to do so. + [[webflux-cors-intro]] == Introduction [.small]#<># @@ -23,6 +24,7 @@ powerful workarounds based on IFRAME or JSONP. + [[webflux-cors-processing]] == Processing [.small]#<># @@ -72,6 +74,7 @@ To learn more from the source or to make advanced customizations, see: + [[webflux-cors-controller]] == `@CrossOrigin` [.small]#<># @@ -170,6 +173,7 @@ public class AccountController { + [[webflux-cors-global]] == Global Configuration [.small]#<># @@ -220,6 +224,7 @@ public class WebConfig implements WebFluxConfigurer { + [[webflux-cors-webfilter]] == CORS `WebFilter` [.small]#<># diff --git a/src/docs/asciidoc/web/webflux-functional.adoc b/src/docs/asciidoc/web/webflux-functional.adoc index 9cf7a3bfac..f42e883be6 100644 --- a/src/docs/asciidoc/web/webflux-functional.adoc +++ b/src/docs/asciidoc/web/webflux-functional.adoc @@ -8,6 +8,7 @@ the same <> foundation. + [[webflux-fn-overview]] == Overview @@ -71,6 +72,7 @@ Most applications can run through the WebFlux Java configuration, see <)` to return a 404 Not F + [[webflux-fn-router-functions]] == `RouterFunction` @@ -320,6 +323,7 @@ RouterFunction personRoute = + [[webflux-fn-running]] == Running a Server @@ -394,6 +398,7 @@ public class WebConfig implements WebFluxConfigurer { + [[webflux-fn-handler-filter-function]] == `HandlerFilterFunction` diff --git a/src/docs/asciidoc/web/webflux-view.adoc b/src/docs/asciidoc/web/webflux-view.adoc index 4844488c42..2377ba15a7 100644 --- a/src/docs/asciidoc/web/webflux-view.adoc +++ b/src/docs/asciidoc/web/webflux-view.adoc @@ -3,9 +3,10 @@ [.small]#<># 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 <>. +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 <>. + @@ -29,6 +30,7 @@ http://forum.thymeleaf.org/Thymeleaf-3-0-8-JUST-PUBLISHED-td4030687.html[announc + [[webflux-view-freemarker]] == FreeMarker [.small]#<># @@ -116,6 +118,7 @@ the `Configuration` object. + [[webflux-view-script]] == Script Views [.small]#<># @@ -280,6 +283,7 @@ for more configuration examples. + [[webflux-view-httpmessagewriter]] == JSON and XML [.small]#<># diff --git a/src/docs/asciidoc/web/webflux-webclient.adoc b/src/docs/asciidoc/web/webflux-webclient.adoc index 2171fc6641..074892451c 100644 --- a/src/docs/asciidoc/web/webflux-webclient.adoc +++ b/src/docs/asciidoc/web/webflux-webclient.adoc @@ -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 diff --git a/src/docs/asciidoc/web/webflux-websocket.adoc b/src/docs/asciidoc/web/webflux-websocket.adoc index 8465007a8e..53c28c601a 100644 --- a/src/docs/asciidoc/web/webflux-websocket.adoc +++ b/src/docs/asciidoc/web/webflux-websocket.adoc @@ -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]#<># diff --git a/src/docs/asciidoc/web/webflux.adoc b/src/docs/asciidoc/web/webflux.adoc index c1fd40917e..f5fbba7a96 100644 --- a/src/docs/asciidoc/web/webflux.adoc +++ b/src/docs/asciidoc/web/webflux.adoc @@ -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-multipart]] ==== Multipart Data [.small]#<># @@ -555,7 +554,6 @@ parsing multipart data in full. By contrast, you can use `@RequestBody` to decod content to `Flux` without collecting to a `MultiValueMap`. - [[webflux-forwarded-headers]] ==== Forwarded Headers [.small]#<># @@ -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]#<># @@ -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>` 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`. - [[webflux-codecs-streaming]] ==== Streaming [.small]#<># @@ -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]#<># @@ -829,6 +821,7 @@ WebClient webClient = WebClient.builder() + [[webflux-dispatcher-handler]] == `DispatcherHandler` [.small]#<># @@ -1012,7 +1005,6 @@ supported through a dedicated <> th instance. The `View` is then used to render the response. - [[webflux-viewresolution-handling]] ==== Handling [.small]#<># @@ -1049,7 +1041,6 @@ dedicated configuration API for view resolution. See <> for more on the view technologies integrated with Spring WebFlux. - [[webflux-redirecting-redirect-prefix]] ==== Redirecting [.small]#<># @@ -1081,6 +1072,7 @@ always selected and used if they match the requested media type. + [[webflux-controller]] == Annotated Controllers [.small]#<># @@ -1192,7 +1184,6 @@ The following example uses type and method level mappings: ==== - [[webflux-ann-requestmapping-uri-templates]] ==== URI Patterns [.small]#<># @@ -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]#<># @@ -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]#<># @@ -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]#<># @@ -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]#<># @@ -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]#<># @@ -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]#<># @@ -1487,7 +1472,6 @@ public class MyConfig { supported controller method arguments and return values. - [[webflux-ann-arguments]] ==== Method Arguments [.small]#<># @@ -1697,7 +1681,6 @@ can be customized through a `WebDataBinder` (see <>) or by r <>). - [[webflux-ann-matrix-variables]] ==== Matrix Variables [.small]#<># @@ -1791,7 +1774,6 @@ To get all matrix variables, use a `MultiValueMap`, as the following example sho ==== - [[webflux-ann-requestparam]] ==== `@RequestParam` [.small]#<># @@ -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]#<># @@ -1900,7 +1881,6 @@ example, a method parameter annotated with `@RequestHeader("Accept")` may be of `String` but also of `String[]` or `List`. - [[webflux-ann-cookievalue]] ==== `@CookieValue` [.small]#<># @@ -1936,7 +1916,6 @@ Type conversion is applied automatically if the target method parameter type is `String`. See <>. - [[webflux-ann-modelattrib-method-args]] ==== `@ModelAttribute` [.small]#<># @@ -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]#<># @@ -2101,7 +2079,6 @@ as the following example shows: ==== - [[webflux-ann-sessionattribute]] ==== `@SessionAttribute` [.small]#<># @@ -2151,7 +2128,6 @@ as the following example shows: ==== - [[webflux-multipart-forms]] ==== Multipart Content [.small]#<># @@ -2295,7 +2271,6 @@ To access multipart data sequentially, in streaming fashion, you can use `@Reque ==== - [[webflux-ann-requestbody]] ==== `@RequestBody` [.small]#<># @@ -2352,7 +2327,6 @@ example uses a `BindingResult` argument`: ==== - [[webflux-ann-httpentity]] ==== `HttpEntity` [.small]#<># @@ -2373,7 +2347,6 @@ container object that exposes request headers and the body. The following exampl ==== - [[webflux-ann-responsebody]] ==== `@ResponseBody` [.small]#<># @@ -2409,7 +2382,6 @@ You can use the <> option of the <># @@ -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]#<># @@ -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]#<># 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]#<># @@ -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]#<># @@ -2946,6 +2909,7 @@ for optimal performance. See the section on configuring <># @@ -3358,7 +3322,7 @@ match to incoming URLs without versions (for example, `/jquery/jquery.min.js` to [.small]#<># 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]#<># diff --git a/src/docs/asciidoc/web/webmvc-client.adoc b/src/docs/asciidoc/web/webmvc-client.adoc index 570a3b9dc1..56c96d5059 100644 --- a/src/docs/asciidoc/web/webmvc-client.adoc +++ b/src/docs/asciidoc/web/webmvc-client.adoc @@ -5,6 +5,7 @@ This section describes options for client-side access to REST endpoints. + [[webmvc-resttemplate]] == `RestTemplate` @@ -21,6 +22,7 @@ See <> for details. + [[webmvc-webclient]] == `WebClient` diff --git a/src/docs/asciidoc/web/webmvc-cors.adoc b/src/docs/asciidoc/web/webmvc-cors.adoc index d48a6c13c4..144edaa56c 100644 --- a/src/docs/asciidoc/web/webmvc-cors.adoc +++ b/src/docs/asciidoc/web/webmvc-cors.adoc @@ -7,6 +7,7 @@ describes how to do so. + [[mvc-cors-intro]] == Introduction [.small]#<># @@ -23,6 +24,7 @@ powerful workarounds based on IFRAME or JSONP. + [[mvc-cors-processing]] == Processing [.small]#<># @@ -72,6 +74,7 @@ To learn more from the source or make advanced customizations, check the code be + [[mvc-cors-controller]] == `@CrossOrigin` [.small]#<># @@ -167,6 +170,7 @@ public class AccountController { + [[mvc-cors-global]] == Global Configuration [.small]#<># @@ -191,7 +195,6 @@ should only be used where appropriate. - [[mvc-cors-global-java]] === Java Configuration [.small]#<># @@ -253,6 +256,7 @@ as the following example shows: + [[mvc-cors-filter]] == CORS Filter [.small]#<># diff --git a/src/docs/asciidoc/web/webmvc-view.adoc b/src/docs/asciidoc/web/webmvc-view.adoc index 282faba398..2959121733 100644 --- a/src/docs/asciidoc/web/webmvc-view.adoc +++ b/src/docs/asciidoc/web/webmvc-view.adoc @@ -9,14 +9,15 @@ We assume you are already familiar with <>. + [[mvc-view-thymeleaf]] == Thymeleaf [.small]#<># 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]#<># @@ -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]#<># @@ -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): ---- - [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]#<># @@ -2078,6 +2069,7 @@ by the `Marshaller`. For more information on the functionality in the + [[mvc-view-xslt]] == XSLT Views diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index 07da1850d4..3fb45f2567 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -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]#<># @@ -221,7 +223,7 @@ The following table lists the special beans detected by the `DispatcherHandler`: |=== | Bean type| Explanation -| <> +| `HandlerMapping` | Map a request to a handler along with a list of <> 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]#<># @@ -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 <> provides a dedicated configuration API for rendering without controller logic. - [[mvc-redirecting-redirect-prefix]] ==== Redirecting [.small]#<># @@ -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]#<># @@ -783,7 +783,6 @@ Spring. * <> - [[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 <>). 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 <>, 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 <>, +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]#<># @@ -1129,6 +1120,7 @@ public class MyInitializer + [[filters]] == Filters [.small]#<># @@ -1210,6 +1202,7 @@ See the sections on <> and the <> for more details. + [[mvc-controller]] == Annotated Controllers [.small]#<># @@ -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]#<># +[.small]#<># 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]#<># +[.small]#<># 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 <> -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 <> 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-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]#<># @@ -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]#<># @@ -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]#<># +[.small]#<># 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]#<># @@ -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]#<># @@ -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]#<># @@ -1729,7 +1710,6 @@ public class MyConfig { supported controller method arguments and return values. - [[mvc-ann-arguments]] ==== Method Arguments [.small]#<># @@ -1865,7 +1845,6 @@ and others) and is equivalent to `required=false`. |=== - [[mvc-ann-return-types]] ==== Return Values [.small]#<># @@ -1982,7 +1961,6 @@ through a `WebDataBinder` (see <>) or by registering <>. - [[mvc-ann-matrix-variables]] ==== Matrix Variables [.small]#<># @@ -2080,7 +2058,6 @@ you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through ``. - [[mvc-ann-requestparam]] ==== `@RequestParam` [.small]#<># @@ -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]#<># @@ -2188,7 +2164,6 @@ example, a method parameter annotated with `@RequestHeader("Accept")` can be of `String` but also `String[]` or `List`. - [[mvc-ann-cookievalue]] ==== `@CookieValue` [.small]#<># @@ -2224,7 +2199,6 @@ if the target method parameter type is not `String`, type conversion is applied automatically. See <>. - [[mvc-ann-modelattrib-method-args]] ==== `@ModelAttribute` [.small]#<># @@ -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]#<># @@ -2409,7 +2382,6 @@ storage, as the following example shows: ==== - [[mvc-ann-sessionattribute]] ==== `@SessionAttribute` [.small]#<># @@ -2440,7 +2412,6 @@ workflow, consider using `@SessionAttributes` as described in <>. - [[mvc-ann-requestattrib]] ==== `@RequestAttribute` [.small]#<># @@ -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 <> 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]#<># @@ -2692,7 +2660,6 @@ public String handle(**@Valid** @RequestPart("meta-data") MetaData metadata, ==== - [[mvc-ann-requestbody]] ==== `@RequestBody` [.small]#<># @@ -2734,7 +2701,6 @@ as the following example shows: ==== - [[mvc-ann-httpentity]] ==== HttpEntity [.small]#<># @@ -2754,7 +2720,6 @@ container object that exposes request headers and body. The following listing sh ==== - [[mvc-ann-responsebody]] ==== `@ResponseBody` [.small]#<># @@ -2789,7 +2754,6 @@ You can combine `@ResponseBody` methods with JSON serialization views. See <> for details. - [[mvc-ann-responseentity]] ==== ResponseEntity [.small]#<># @@ -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]#<># @@ -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 <>). `@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, <> 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]#<># @@ -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 <> 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 `true `ASYNC` 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]#<># @@ -3982,6 +3931,7 @@ http://hdiv.org/[HDIV] is another web security framework that integrates with Sp + [[mvc-caching]] == HTTP Caching [.small]#<># @@ -4122,12 +4072,11 @@ for optimal performance. See the section on configuring <>. - - include::webmvc-view.adoc[leveloffset=+1] + [[mvc-config]] == MVC Config [.small]#<># @@ -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 `` declaration. + [[mvc-http2]] == HTTP/2 [.small]#<># diff --git a/src/docs/asciidoc/web/websocket-intro.adoc b/src/docs/asciidoc/web/websocket-intro.adoc index 0b2e6535ce..29fe911700 100644 --- a/src/docs/asciidoc/web/websocket-intro.adoc +++ b/src/docs/asciidoc/web/websocket-intro.adoc @@ -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 diff --git a/src/docs/asciidoc/web/websocket.adoc b/src/docs/asciidoc/web/websocket.adoc index 09eb64299e..bb8b20f115 100644 --- a/src/docs/asciidoc/web/websocket.adoc +++ b/src/docs/asciidoc/web/websocket.adoc @@ -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]#<># @@ -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-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 <>, to broadcast messages to -subscribed WebSocket clients. +in <>, 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: -- GitLab