Merge branch '5.1.x'

jhoeller · jhoeller · commit 0b50d1eff38e · 2019-05-09T14:29:37.000+02:00
diff --git a/src/docs/asciidoc/integration-appendix.adoc b/src/docs/asciidoc/integration-appendix.adoc
@@ -176,10 +176,10 @@ different properties with `jee`:
 [[xsd-schemas-jee-local-slsb]]
 ==== `<jee:local-slsb/>` (Simple)
 
-The `<jee:local-slsb/>` element configures a reference to a local EJB Stateless SessionBean.
+The `<jee:local-slsb/>` element configures a reference to a local EJB Stateless Session Bean.
 
-The following example shows how to configures a reference to a local EJB Stateless
-SessionBean without `jee`:
+The following example shows how to configures a reference to a local EJB Stateless Session Bean
+without `jee`:
 
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
@@ -191,8 +191,8 @@ SessionBean without `jee`:
 	</bean>
 ----
 
-The following example shows how to configures a reference to a local EJB Stateless
-SessionBean with `jee`:
+The following example shows how to configures a reference to a local EJB Stateless Session Bean
+with `jee`:
 
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
@@ -206,10 +206,10 @@ SessionBean with `jee`:
 [[xsd-schemas-jee-local-slsb-complex]]
 ==== `<jee:local-slsb/>` (Complex)
 
-The `<jee:local-slsb/>` element configures a reference to a local EJB Stateless SessionBean.
+The `<jee:local-slsb/>` element configures a reference to a local EJB Stateless Session Bean.
 
-The following example shows how to configures a reference to a local EJB Stateless
-SessionBean and a number of properties without `jee`:
+The following example shows how to configures a reference to a local EJB Stateless Session Bean
+and a number of properties without `jee`:
 
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
@@ -224,8 +224,8 @@ SessionBean and a number of properties without `jee`:
 	</bean>
 ----
 
-The following example shows how to configures a reference to a local EJB Stateless
-SessionBean and a number of properties with `jee`:
+The following example shows how to configures a reference to a local EJB Stateless Session Bean
+and a number of properties with `jee`:
 
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
@@ -242,11 +242,10 @@ SessionBean and a number of properties with `jee`:
 [[xsd-schemas-jee-remote-slsb]]
 ==== <jee:remote-slsb/>
 
-The `<jee:remote-slsb/>` element configures a reference to a `remote` EJB Stateless
-SessionBean.
+The `<jee:remote-slsb/>` element configures a reference to a `remote` EJB Stateless Session Bean.
 
-The following example shows how to configures a reference to a remote EJB Stateless
-SessionBean without `jee`:
+The following example shows how to configures a reference to a remote EJB Stateless Session Bean
+without `jee`:
 
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
@@ -263,8 +262,8 @@ SessionBean without `jee`:
 	</bean>
 ----
 
-The following example shows how to configures a reference to a remote EJB Stateless
-SessionBean with `jee`:
+The following example shows how to configures a reference to a remote EJB Stateless Session Bean
+with `jee`:
 
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc
@@ -19,8 +19,8 @@ a number of Java EE (and related) technologies.
 == Remoting and Web Services with Spring
 
 Spring features integration classes for remoting support with various technologies.
-The remoting support eases the development of remote-enabled services, implemented by
-your usual POJOs. Currently, Spring supports the following remoting technologies:
+The remoting support eases the development of remote-enabled services, implemented
+by your usual POJOs. Currently, Spring supports the following remoting technologies:
 
 * *Remote Method Invocation (RMI)*: Through the use of  `RmiProxyFactoryBean` and
   `RmiServiceExporter`, Spring supports both traditional RMI (with `java.rmi.Remote`
@@ -34,10 +34,11 @@ your usual POJOs. Currently, Spring supports the following remoting technologies
   `HessianServiceExporter`, you can transparently expose your services through the
   lightweight binary HTTP-based protocol provided by Caucho.
 * *JAX-WS*: Spring provides remoting support for web services through JAX-WS.
-* *JMS*: Remoting by using JMS as the underlying protocol is supported through the
-  `JmsInvokerServiceExporter` and `JmsInvokerProxyFactoryBean` classes.
-* *AMQP*: Remoting by using AMQP as the underlying protocol is supported by the Spring
-  AMQP project.
+* *JMS*: Remoting via JMS as the underlying protocol is supported through the
+  `JmsInvokerServiceExporter` and `JmsInvokerProxyFactoryBean` classes in the
+   `spring-jms` module.
+* *AMQP*: Remoting via AMQP as the underlying protocol is supported by the
+  separate Spring AMQP project.
 
 While discussing the remoting capabilities of Spring, we use the following domain
 model and corresponding services:
@@ -86,9 +87,9 @@ model and corresponding services:
 	}
 ----
 
-This section starts by exposing the service to a remote client by using RMI and talk a bit about
-the drawbacks of using RMI. It then continues with an example that uses Hessian as the
-protocol.
+This section starts by exposing the service to a remote client by using RMI and talk a bit
+about the drawbacks of using RMI. It then continues with an example that uses Hessian as
+the protocol.
 
 
 
@@ -141,8 +142,8 @@ The following example shows how to do so:
 In the preceding example, we override the port for the RMI registry. Often, your application
 server also maintains an RMI registry, and it is wise to not interfere with that one.
 Furthermore, the service name is used to bind the service. So, in the preceding example, the
-service is bound at `'rmi://HOST:1199/AccountService'`. We use this URL later on
-to link in the service at the client side.
+service is bound at `'rmi://HOST:1199/AccountService'`. We use this URL later on to link in
+the service at the client side.
 
 NOTE: The `servicePort` property has been omitted (it defaults to 0). This means that an
 anonymous port is used to communicate with the service.
@@ -6776,16 +6777,17 @@ You can find a further explanation of the differences between a buffer and a cac
 https://en.wikipedia.org/wiki/Cache_(computing)#The_difference_between_buffer_and_cache[here].
 ****
 
-At its core, the cache abstraction applies caching to Java methods, thus reducing the number
-of executions based on the information available in the cache. That is, each time a
-targeted method is invoked, the abstraction applies a caching behavior that checks
-whether the method has been already executed for the given arguments. If it has been executed,
-the cached result is returned without having to execute the actual method. If the method has
-not been executed, then it is executed, and the result is cached and returned to the user so that, the
-next time the method is invoked, the cached result is returned. This way, expensive
-methods (whether CPU- or IO-bound) can be executed only once for a given set of
-parameters and the result reused without having to actually execute the method again.
-The caching logic is applied transparently without any interference to the invoker.
+At its core, the cache abstraction applies caching to Java methods, thus reducing the
+number of executions based on the information available in the cache. That is, each time
+a targeted method is invoked, the abstraction applies a caching behavior that checks
+whether the method has been already executed for the given arguments. If it has been
+executed, the cached result is returned without having to execute the actual method.
+If the method has not been executed, then it is executed, and the result is cached and
+returned to the user so that, the next time the method is invoked, the cached result is
+returned. This way, expensive methods (whether CPU- or IO-bound) can be executed only
+once for a given set of parameters and the result reused without having to actually
+execute the method again. The caching logic is applied transparently without any
+interference to the invoker.
 
 IMPORTANT: This approach works only for methods that are guaranteed to return the same
 output (result) for a given input (or arguments) no matter how many times it is executed.
@@ -6794,12 +6796,11 @@ The caching abstraction provides other cache-related operations, such as the abi
 to update the content of the cache or to remove one or all entries. These are useful if
 the cache deals with data that can change during the course of the application.
 
-As with other services in the Spring Framework, the caching service is an
-abstraction (not a cache implementation) and requires the use of actual storage to
-store the cache data -- that is, the abstraction frees you from having to write
-the caching logic but does not provide the actual data store. This abstraction is
-materialized by the `org.springframework.cache.Cache` and
-`org.springframework.cache.CacheManager` interfaces.
+As with other services in the Spring Framework, the caching service is an abstraction
+(not a cache implementation) and requires the use of actual storage to store the cache data --
+that is, the abstraction frees you from having to write the caching logic but does not
+provide the actual data store. This abstraction is materialized by the
+`org.springframework.cache.Cache` and `org.springframework.cache.CacheManager` interfaces.
 
 Spring provides <<cache-store-configuration, a few implementations>> of that abstraction:
 JDK `java.util.concurrent.ConcurrentMap` based caches, https://www.ehcache.org/[Ehcache 2.x],
@@ -6844,11 +6845,12 @@ For caching declaration, Spring's caching abstraction provides a set of Java ann
 [[cache-annotations-cacheable]]
 ==== The `@Cacheable` Annotation
 
-As the name implies, you can use `@Cacheable` to demarcate methods that are cacheable -- that
-is, methods for which the result is stored in the cache so that, on subsequent invocations
-(with the same arguments), the value in the cache is returned without having to actually
-execute the method. In its simplest form, the annotation declaration requires the name
-of the cache associated with the annotated method, as the following example shows:
+As the name implies, you can use `@Cacheable` to demarcate methods that are cacheable --
+that is, methods for which the result is stored in the cache so that, on subsequent
+invocations (with the same arguments), the value in the cache is returned without
+having to actually execute the method. In its simplest form, the annotation declaration
+requires the name of the cache associated with the annotated method, as the following
+example shows:
 
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -6860,10 +6862,9 @@ of the cache associated with the annotated method, as the following example show
 In the preceding snippet, the `findBook` method is associated with the cache named `books`.
 Each time the method is called, the cache is checked to see whether the invocation has
 already been executed and does not have to be repeated. While in most cases, only one
-cache is declared, the annotation lets multiple names be specified so that more
-than one cache is being used. In this case, each of the caches is checked before
-executing the method -- if at least one cache is hit, the associated value is
-returned.
+cache is declared, the annotation lets multiple names be specified so that more than one
+cache is being used. In this case, each of the caches is checked before executing the
+method -- if at least one cache is hit, the associated value is returned.
 
 NOTE: All the other caches that do not contain the value are also updated, even though
 the cached method was not actually executed.
@@ -6880,17 +6881,17 @@ The following example uses `@Cacheable` on the `findBook` method:
 [[cache-annotations-cacheable-default-key]]
 ===== Default Key Generation
 
-Since caches are essentially key-value stores, each invocation of a cached method needs
-to be translated into a suitable key for cache access. The caching
-abstraction uses a simple `KeyGenerator` based on the following algorithm:
+Since caches are essentially key-value stores, each invocation of a cached method
+needs to be translated into a suitable key for cache access. The caching abstraction
+uses a simple `KeyGenerator` based on the following algorithm:
 
 * If no params are given, return `SimpleKey.EMPTY`.
 * If only one param is given, return that instance.
 * If more than one param is given, return a `SimpleKey` that contains all parameters.
 
 This approach works well for most use-cases, as long as parameters have natural keys
-and implement valid `hashCode()` and `equals()` methods. If that is not the case, you need to change the
-strategy.
+and implement valid `hashCode()` and `equals()` methods. If that is not the case,
+you need to change the strategy.
 
 To provide a different default key generator, you need to implement the
 `org.springframework.cache.interceptor.KeyGenerator` interface.
@@ -6956,8 +6957,9 @@ The preceding snippets show how easy it is to select a certain argument, one of
 properties, or even an arbitrary (static) method.
 
 If the algorithm responsible for generating the key is too specific or if it needs
-to be shared, you can define a custom `keyGenerator` on the operation. To do
-so, specify the name of the `KeyGenerator` bean implementation to use, as the following example shows:
+to be shared, you can define a custom `keyGenerator` on the operation. To do so,
+specify the name of the `KeyGenerator` bean implementation to use, as the following
+example shows:
 
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -6985,8 +6987,8 @@ To provide a different default cache resolver, you need to implement the
 The default cache resolution fits well for applications that work with a
 single `CacheManager` and have no complex cache resolution requirements.
 
-For applications that work with several cache managers, you can
-set the `cacheManager` to use for each operation, as the following example shows:
+For applications that work with several cache managers, you can set the
+`cacheManager` to use for each operation, as the following example shows:
 
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -7034,8 +7036,8 @@ of caching.
 
 For those particular cases, you can use the `sync` attribute to instruct the underlying
 cache provider to lock the cache entry while the value is being computed. As a result,
-only one thread is busy computing the value, while the others are blocked until the
-entry is updated in the cache. The following example shows how to use the `sync` attribute:
+only one thread is busy computing the value, while the others are blocked until the entry
+is updated in the cache. The following example shows how to use the `sync` attribute:
 
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -7046,8 +7048,8 @@ entry is updated in the cache. The following example shows how to use the `sync`
 <1> Using the `sync` attribute.
 
 
-NOTE: This is an optional feature, and your favorite cache library may not support it. All
-`CacheManager` implementations provided by the core framework support it. See the
+NOTE: This is an optional feature, and your favorite cache library may not support it.
+All `CacheManager` implementations provided by the core framework support it. See the
 documentation of your cache provider for more details.
 
 [[cache-annotations-cacheable-condition]]
@@ -7161,11 +7163,11 @@ available to the context so that you can use them for key and conditional comput
 [[cache-annotations-put]]
 ==== The `@CachePut` Annotation
 
-When the cache needs to be updated without interfering with the method
-execution, you can use the `@CachePut` annotation. That is, the method is always
-executed and its result is placed into the cache (according to the `@CachePut` options). It
-supports the same options as `@Cacheable` and should be used for cache population rather
-than method flow optimization. The following example uses the `@CachePut` annotation:
+When the cache needs to be updated without interfering with the method execution,
+you can use the `@CachePut` annotation. That is, the method is always executed and its
+result is placed into the cache (according to the `@CachePut` options). It supports
+the same options as `@Cacheable` and should be used for cache population rather than
+method flow optimization. The following example uses the `@CachePut` annotation:
 
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -7177,11 +7179,11 @@ than method flow optimization. The following example uses the `@CachePut` annota
 IMPORTANT: Using `@CachePut` and `@Cacheable` annotations on the same method is generally
 strongly discouraged because they have different behaviors. While the latter causes the
 method execution to be skipped by using the cache, the former forces the execution in
-order to execute a cache update. This leads to unexpected behavior and, with the exception of
-specific corner-cases (such as annotations having conditions that exclude them from each
+order to execute a cache update. This leads to unexpected behavior and, with the exception
+of specific corner-cases (such as annotations having conditions that exclude them from each
 other), such declarations should be avoided. Note also that such conditions should not rely
-on the result object (that is, the `#result` variable), as these are validated up-front to confirm
-the exclusion.
+on the result object (that is, the `#result` variable), as these are validated up-front to
+confirm the exclusion.
 
 
 [[cache-annotations-evict]]
@@ -7207,11 +7209,11 @@ all entries from the `books` cache:
 <1> Using the `allEntries` attribute to evict all entries from the cache.
 
 
-This option comes in handy when an entire cache region needs to be cleared out. Rather
-than evicting each entry (which would take a long time, since it is inefficient), all the
-entries are removed in one operation, as the preceding example shows. Note that the framework ignores
-any key specified in this scenario as it does not apply (the entire cache is evicted, not
-only one entry).
+This option comes in handy when an entire cache region needs to be cleared out.
+Rather than evicting each entry (which would take a long time, since it is inefficient),
+all the entries are removed in one operation, as the preceding example shows.
+Note that the framework ignores any key specified in this scenario as it does not apply
+(the entire cache is evicted, not only one entry).
 
 You can also indicate whether the eviction should occur after (the default) or before
 the method executes by using the `beforeInvocation` attribute. The former provides the
@@ -7222,10 +7224,9 @@ The latter (`beforeInvocation=true`) causes the eviction to always occur before
 method is invoked. This is useful in cases where the eviction does not need to be tied
 to the method outcome.
 
-Note that `void` methods can be used with `@CacheEvict` - as the
-methods act as a trigger, the return values are ignored (as they do not interact with the
-cache). This is not the case with `@Cacheable` which adds or updates data into the cache
-and, thus, requires a result.
+Note that `void` methods can be used with `@CacheEvict` - as the methods act as a trigger,
+the return values are ignored (as they do not interact with the cache). This is not the case
+with `@Cacheable` which adds or updates data into the cache and, thus, requires a result.
 
 
 [[cache-annotations-caching]]
@@ -7714,9 +7715,9 @@ or eviction contracts.
 
 NOTE: Ehcache 3.x is fully JSR-107 compliant and no dedicated support is required for it.
 
-The Ehcache 2.x implementation is located in the `org.springframework.cache.ehcache` package.
-Again, to use it, you need to declare the appropriate `CacheManager`. The following
-example shows how to do so:
+The Ehcache 2.x implementation is located in the `org.springframework.cache.ehcache`
+package. Again, to use it, you need to declare the appropriate `CacheManager`.
+The following example shows how to do so:
 
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
