Merge branch '5.1.x'
This commit is contained in:
Juergen Hoeller
@@ -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"]
|
||||
|
||||
@@ -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"]
|
||||
|
||||
Reference in New Issue
Block a user