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

Merge branch '5.2.x'

Browse Source
This commit is contained in:
Sam Brannen
2020-07-20 18:38:32 +02:00
parent 6b6e8be313 1c83b3fc22
commit 3d64f8162c
14 changed files with 254 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -106,7 +106,7 @@ proxy is created to avoid the need for a test on every method invocation. If the
two-argument `matches` method returns `true` for a given method, and the `isRuntime()` method
for the MethodMatcher returns `true`, the three-argument matches method is invoked on
every method invocation. This lets a pointcut look at the arguments passed to the
method invocation immediately before the target advice is to execute.
method invocation immediately before the target advice starts.
Most `MethodMatcher` implementations are static, meaning that their `isRuntime()` method returns `false`.
In this case, the three-argument `matches` method is never invoked.
@@ -232,7 +232,7 @@ The main example is the `control flow` pointcut.
===== Control Flow Pointcuts
Spring control flow pointcuts are conceptually similar to AspectJ `cflow` pointcuts,
although less powerful. (There is currently no way to specify that a pointcut executes
although less powerful. (There is currently no way to specify that a pointcut runs
below a join point matched by another pointcut.) A control flow pointcut matches the
current call stack. For example, it might fire if the join point was invoked by a method
in the `com.mycompany.web` package or by the `SomeCaller` class. Control flow pointcuts
@@ -425,7 +425,7 @@ The following listing shows the `MethodBeforeAdvice` interface:
.Kotlin
----
interface MethodBeforeAdvice : BeforeAdvice {
fun before(m: Method, args: Array<Any>, target: Any)
}
----
@@ -435,8 +435,8 @@ field before advice, although the usual objects apply to field interception and
unlikely for Spring to ever implement it.)
Note that the return type is `void`. Before advice can insert custom behavior before the join
point executes but cannot change the return value. If a before advice throws an
exception, it aborts further execution of the interceptor chain. The exception
point runs but cannot change the return value. If a before advice throws an
exception, it stops further execution of the interceptor chain. The exception
propagates back up the interceptor chain. If it is unchecked or on the signature of
the invoked method, it is passed directly to the client. Otherwise, it is
wrapped in an unchecked exception by the AOP proxy.
@@ -465,7 +465,7 @@ The following example shows a before advice in Spring, which counts all method i
class CountingBeforeAdvice : MethodBeforeAdvice {
var count: Int = 0
override fun before(m: Method, args: Array<Any>, target: Any?) {
++count
}
@@ -509,7 +509,7 @@ The following advice is invoked if a `RemoteException` is thrown (including from
.Kotlin
----
class RemoteThrowsAdvice : ThrowsAdvice {
fun afterThrowing(ex: RemoteException) {
// Do something with remote exception
}
@@ -563,7 +563,7 @@ methods can be combined in a single class. The following listing shows the final
.Kotlin
----
class CombinedThrowsAdvice : ThrowsAdvice {
fun afterThrowing(ex: RemoteException) {
// Do something with remote exception
}
@@ -604,7 +604,7 @@ An after returning advice in Spring must implement the
.Kotlin
----
interface AfterReturningAdvice : Advice {
fun afterReturning(returnValue: Any, m: Method, args: Array<Any>, target: Any)
}
----
@@ -639,7 +639,7 @@ not thrown exceptions:
var count: Int = 0
private set
override fun afterReturning(returnValue: Any?, m: Method, args: Array<Any>, target: Any?) {
++count
}
@@ -707,7 +707,7 @@ rather than the method, level. You can only use introduction advice with the
interface IntroductionAdvisor : Advisor, IntroductionInfo {
val classFilter: ClassFilter
@Throws(IllegalArgumentException::class)
fun validateInterfaces()
}
@@ -829,7 +829,7 @@ The following example shows the example `LockMixin` class:
fun locked(): Boolean {
return this.locked
}
override fun invoke(invocation: MethodInvocation): Any? {
if (locked() && invocation.method.name.indexOf("set") == 0) {
throw LockedException()

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

@@ -83,9 +83,9 @@ Spring AOP includes the following types of advice:
an exception).
* After returning advice: Advice to be run after a join point completes
normally (for example, if a method returns without throwing an exception).
* After throwing advice: Advice to be executed if a method exits by throwing an
* After throwing advice: Advice to be run if a method exits by throwing an
exception.
* After (finally) advice: Advice to be executed regardless of the means by which a
* After (finally) advice: Advice to be run regardless of the means by which a
join point exits (normal or exceptional return).
* Around advice: Advice that surrounds a join point such as a method invocation.
This is the most powerful kind of advice. Around advice can perform custom behavior
@@ -219,7 +219,7 @@ To use @AspectJ aspects in a Spring configuration, you need to enable Spring sup
configuring Spring AOP based on @AspectJ aspects and auto-proxying beans based on
whether or not they are advised by those aspects. By auto-proxying, we mean that, if Spring
determines that a bean is advised by one or more aspects, it automatically generates
a proxy for that bean to intercept method invocations and ensures that advice is executed
a proxy for that bean to intercept method invocations and ensures that advice is run
as needed.
The @AspectJ support can be enabled with XML- or Java-style configuration. In either
@@ -334,7 +334,7 @@ hence, excludes it from auto-proxying.
=== Declaring a Pointcut
Pointcuts determine join points of interest and thus enable us to control
when advice executes. Spring AOP only supports method execution join points for Spring
when advice runs. Spring AOP only supports method execution join points for Spring
beans, so you can think of a pointcut as matching the execution of methods on Spring
beans. A pointcut declaration has two parts: a signature comprising a name and any
parameters and a pointcut expression that determines exactly which method
@@ -395,7 +395,7 @@ expressions:
annotation (the execution of methods declared in types with the given annotation when
using Spring AOP).
* `@annotation`: Limits matching to join points where the subject of the join point
(the method being executed in Spring AOP) has the given annotation.
(the method being run in Spring AOP) has the given annotation.
.Other pointcut types
****
@@ -1211,8 +1211,8 @@ The following example shows how to use after finally advice:
==== Around Advice
The last kind of advice is around advice. Around advice runs "`around`" a matched method's
execution. It has the opportunity to do work both before and after the method executes
and to determine when, how, and even if the method actually gets to execute at all.
execution. It has the opportunity to do work both before and after the method runs
and to determine when, how, and even if the method actually gets to run at all.
Around advice is often used if you need to share state before and after a method
execution in a thread-safe manner (starting and stopping a timer, for example). Always
use the least powerful form of advice that meets your requirements (that is, do not use
@@ -1221,7 +1221,7 @@ around advice if before advice would do).
Around advice is declared by using the `@Around` annotation. The first parameter of the
advice method must be of type `ProceedingJoinPoint`. Within the body of the advice,
calling `proceed()` on the `ProceedingJoinPoint` causes the underlying method to
execute. The `proceed` method can also pass in an `Object[]`. The values
run. The `proceed` method can also pass in an `Object[]`. The values
in the array are used as the arguments to the method execution when it proceeds.
NOTE: The behavior of `proceed` when called with an `Object[]` is a little different than the
@@ -1783,15 +1783,15 @@ annotation. Consider the following example:
}
----
In the preceding example, the effect of the `'perthis'` clause is that one aspect
instance is created for each unique service object that executes a business service (each
unique object bound to 'this' at join points matched by the pointcut expression). The
aspect instance is created the first time that a method is invoked on the service object.
The aspect goes out of scope when the service object goes out of scope. Before the aspect
instance is created, none of the advice within it executes. As soon as the aspect
instance has been created, the advice declared within it executes at matched join points,
but only when the service object is the one with which this aspect is associated. See the
AspectJ Programming Guide for more information on `per` clauses.
In the preceding example, the effect of the `perthis` clause is that one aspect instance
is created for each unique service object that performs a business service (each unique
object bound to `this` at join points matched by the pointcut expression). The aspect
instance is created the first time that a method is invoked on the service object. The
aspect goes out of scope when the service object goes out of scope. Before the aspect
instance is created, none of the advice within it runs. As soon as the aspect instance
has been created, the advice declared within it runs at matched join points, but only
when the service object is the one with which this aspect is associated. See the AspectJ
Programming Guide for more information on `per` clauses.
The `pertarget` instantiation model works in exactly the same way as `perthis`, but it
creates one aspect instance for each unique target object at matched join points.
@@ -2188,7 +2188,7 @@ significantly improve the readability of your code.
The `method` attribute identifies a method (`doAccessCheck`) that provides the body of
the advice. This method must be defined for the bean referenced by the aspect element
that contains the advice. Before a data access operation is executed (a method execution
that contains the advice. Before a data access operation is performed (a method execution
join point matched by the pointcut expression), the `doAccessCheck` method on the aspect
bean is invoked.
@@ -2250,7 +2250,7 @@ example, you can declare the method signature as follows:
[[aop-schema-advice-after-throwing]]
==== After Throwing Advice
After throwing advice executes when a matched method execution exits by throwing an
After throwing advice runs when a matched method execution exits by throwing an
exception. It is declared inside an `<aop:aspect>` by using the `after-throwing` element,
as the following example shows:
@@ -2325,8 +2325,8 @@ by using the `after` element, as the following example shows:
==== Around Advice
The last kind of advice is around advice. Around advice runs "around" a matched method
execution. It has the opportunity to do work both before and after the method executes
and to determine when, how, and even if the method actually gets to execute at all.
execution. It has the opportunity to do work both before and after the method runs
and to determine when, how, and even if the method actually gets to run at all.
Around advice is often used to share state before and after a method
execution in a thread-safe manner (starting and stopping a timer, for example). Always
use the least powerful form of advice that meets your requirements. Do not use around
@@ -2335,7 +2335,7 @@ advice if before advice can do the job.
You can declare around advice by using the `aop:around` element. The first parameter of the
advice method must be of type `ProceedingJoinPoint`. Within the body of the advice,
calling `proceed()` on the `ProceedingJoinPoint` causes the underlying method to
execute. The `proceed` method may also be called with an `Object[]`. The values
run. The `proceed` method may also be called with an `Object[]`. The values
in the array are used as the arguments to the method execution when it proceeds. See
<<aop-ataspectj-around-advice>> for notes on calling `proceed` with an `Object[]`.
The following example shows how to declare around advice in XML:
@@ -2563,7 +2563,7 @@ ms % Task name
[[aop-ordering]]
==== Advice Ordering
When multiple pieces of advice need to execute at the same join point (executing method)
When multiple pieces of advice need to run at the same join point (executing method)
the ordering rules are as described in <<aop-ataspectj-advice-ordering>>. The precedence
between aspects is determined via the `order` attribute in the `<aop:aspect>` element or
by either adding the `@Order` annotation to the bean that backs the aspect or by having
@@ -2772,7 +2772,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl
class ConcurrentOperationExecutor : Ordered {
private val DEFAULT_MAX_RETRIES = 2
private var maxRetries = DEFAULT_MAX_RETRIES
private var order = 1
@@ -2787,7 +2787,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl
fun setOrder(order: Int) {
this.order = order
}
fun doConcurrentOperation(pjp: ProceedingJoinPoint): Any {
var numAttempts = 0
var lockFailureException: PessimisticLockingFailureException
@@ -3160,13 +3160,13 @@ The key thing to understand here is that the client code inside the `main(..)` m
of the `Main` class has a reference to the proxy. This means that method calls on that
object reference are calls on the proxy. As a result, the proxy can delegate to all of
the interceptors (advice) that are relevant to that particular method call. However,
once the call has finally reached the target object (the `SimplePojo`, reference in
once the call has finally reached the target object (the `SimplePojo` reference in
this case), any method calls that it may make on itself, such as `this.bar()` or
`this.foo()`, are going to be invoked against the `this` reference, and not the proxy.
This has important implications. It means that self-invocation is not going to result
in the advice associated with a method invocation getting a chance to execute.
in the advice associated with a method invocation getting a chance to run.
Okay, so what is to be done about this? The best approach (the term, "`best,`" is used
Okay, so what is to be done about this? The best approach (the term "best" is used
loosely here) is to refactor your code such that the self-invocation does not happen.
This does entail some work on your part, but it is the best, least-invasive approach.
The next approach is absolutely horrendous, and we hesitate to point it out, precisely
@@ -3433,7 +3433,7 @@ exact semantics of "`after returning from the initialization of a new object`" a
fine. In this context, "`after initialization`" means that the dependencies are
injected after the object has been constructed. This means that the dependencies
are not available for use in the constructor bodies of the class. If you want the
dependencies to be injected before the constructor bodies execute and thus be
dependencies to be injected before the constructor bodies run and thus be
available for use in the body of the constructors, you need to define this on the
`@Configurable` declaration, as follows:

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

@@ -1471,7 +1471,7 @@ The following example shows various values being set:
<property name="driverClassName" value="com.mysql.jdbc.Driver"/>
<property name="url" value="jdbc:mysql://localhost:3306/mydb"/>
<property name="username" value="root"/>
<property name="password" value="masterkaoli"/>
<property name="password" value="misterkaoli"/>
</bean>
----
@@ -1491,7 +1491,7 @@ XML configuration:
p:driverClassName="com.mysql.jdbc.Driver"
p:url="jdbc:mysql://localhost:3306/mydb"
p:username="root"
p:password="masterkaoli"/>
p:password="misterkaoli"/>
</beans>
----
@@ -3193,10 +3193,10 @@ 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
the scope, and let them be destroyed.
The session scope
implementation, for example, returns the session-scoped bean (if it does not exist,
the method returns a new instance of the bean, after having bound it to the session for
future reference). The following method returns the object from the underlying scope:
The session scope implementation, for example, returns the session-scoped bean (if it
does not exist, the method returns a new instance of the bean, after having bound it to
the session for future reference). The following method returns the object from the
underlying scope:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
@@ -3209,10 +3209,10 @@ future reference). The following method returns the object from the underlying s
fun get(name: String, objectFactory: ObjectFactory<*>): Any
----
The session scope
implementation, for example, removes the session-scoped bean from the underlying session.
The object should be returned, but you can return null if the object with the specified
name is not found. The following method removes the object from the underlying scope:
The session scope implementation, for example, removes the session-scoped bean from the
underlying session. The object should be returned, but you can return `null` if the
object with the specified name is not found. The following method removes the object from
the underlying scope:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
@@ -3225,7 +3225,7 @@ name is not found. The following method removes the object from the underlying s
fun remove(name: String): Any
----
The following method registers the callbacks the scope should execute when it is
The following method registers a callback that the scope should invoke when it is
destroyed or when the specified object in the scope is destroyed:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
@@ -3255,7 +3255,6 @@ The following method obtains the conversation identifier for the underlying scop
fun getConversationId(): String
----
This identifier is different for each scope. For a session scoped implementation, this
identifier can be the session identifier.
@@ -3628,7 +3627,7 @@ following example:
class DefaultBlogService : BlogService {
private var blogDao: BlogDao? = null
// this is (unsurprisingly) the initialization callback method
fun init() {
if (blogDao == null) {
@@ -3689,10 +3688,10 @@ As of Spring 2.5, you have three options for controlling bean lifecycle behavior
annotations>>. You can combine these mechanisms to control a given bean.
NOTE: If multiple lifecycle mechanisms are configured for a bean and each mechanism is
configured with a different method name, then each configured method is executed in the
configured with a different method name, then each configured method is run in the
order listed after this note. However, if the same method name is configured -- for example,
`init()` for an initialization method -- for more than one of these lifecycle mechanisms,
that method is executed once, as explained in the
that method is run once, as explained in the
<<beans-factory-lifecycle-default-init-destroy-methods, preceding section>>.
Multiple lifecycle mechanisms configured for the same bean, with different
@@ -3782,7 +3781,7 @@ consider implementing `org.springframework.context.SmartLifecycle` instead.
Also, please note that stop notifications are not guaranteed to come before destruction.
On regular shutdown, all `Lifecycle` beans first receive a stop notification before
the general destruction callbacks are being propagated. However, on hot refresh during a
context's lifetime or on aborted refresh attempts, only destroy methods are called.
context's lifetime or on stopped refresh attempts, only destroy methods are called.
====
The order of startup and shutdown invocations can be important. If a "`depends-on`"
@@ -4183,7 +4182,7 @@ Spring container finishes instantiating, configuring, and initializing a bean, y
plug in one or more custom `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.
in which these `BeanPostProcessor` instances run 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
@@ -4444,7 +4443,7 @@ in one container are not post-processed by `BeanFactoryPostProcessor` instances
container, even if both containers are part of the same hierarchy.
====
A bean factory post-processor is automatically executed when it is declared inside an
A bean factory post-processor is automatically run when it is declared inside an
`ApplicationContext`, in order to apply changes to the configuration metadata that
define the container. Spring includes a number of predefined bean factory
post-processors, such as `PropertyOverrideConfigurer` and
@@ -4991,7 +4990,7 @@ The same applies for typed collections, as the following example shows:
@Autowired
lateinit var movieCatalogs: Set<MovieCatalog>
// ...
}
----
@@ -5040,7 +5039,7 @@ corresponding bean names, as the following example shows:
@Autowired
lateinit var movieCatalogs: Map<String, MovieCatalog>
// ...
}
----
@@ -5846,7 +5845,7 @@ configuration:
@Bean
fun stringStore() = StringStore()
@Bean
fun integerStore() = IntegerStore()
}
@@ -5994,7 +5993,7 @@ named `movieFinder` injected into its setter method:
@Resource
private lateinit var movieFinder: MovieFinder
}
----
@@ -6482,7 +6481,7 @@ You can also override the value for the `proxyMode`, as the following example sh
@Service
@SessionScope(proxyMode = ScopedProxyMode.INTERFACES)
class SessionScopedUserService : UserService {
// ...
// ...
}
----
@@ -6532,7 +6531,7 @@ are eligible for such autodetection:
----
@Repository
class JpaMovieFinder : MovieFinder {
// implementation elided for clarity
// implementation elided for clarity
}
----
@@ -7157,7 +7156,7 @@ technique:
@Component
@Genre("Action")
class ActionMovieCatalog : MovieCatalog {
// ...
// ...
}
----
@@ -9891,7 +9890,7 @@ it programmatically against the `Environment` API which is available through an
val ctx = AnnotationConfigApplicationContext().apply {
environment.setActiveProfiles("development")
register(SomeConfig::class.java, StandaloneDataConfig::class.java, JndiDataConfig::class.java)
refresh()
refresh()
}
----
@@ -10330,7 +10329,7 @@ are as follows:
argument.required=The {0} argument is required.
----
The next example shows a program to execute the `MessageSource` functionality.
The next example shows a program to run the `MessageSource` functionality.
Remember that all `ApplicationContext` implementations are also `MessageSource`
implementations and so can be cast to the `MessageSource` interface.

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

@@ -273,7 +273,7 @@ application contexts may be used to obtain `Resource` instances.
When you call `getResource()` on a specific application context, and the location path
specified doesn't have a specific prefix, you get back a `Resource` type that is
appropriate to that particular application context. For example, assume the following
snippet of code was executed against a `ClassPathXmlApplicationContext` instance:
snippet of code was run against a `ClassPathXmlApplicationContext` instance:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
@@ -286,7 +286,7 @@ snippet of code was executed against a `ClassPathXmlApplicationContext` instance
val template = ctx.getResource("some/resource/path/myTemplate.txt")
----
Against a `ClassPathXmlApplicationContext`, that code returns a `ClassPathResource`. If the same method were executed
Against a `ClassPathXmlApplicationContext`, that code returns a `ClassPathResource`. If the same method were run
against a `FileSystemXmlApplicationContext` instance, it would return a
`FileSystemResource`. For a `WebApplicationContext`, it would return a
`ServletContextResource`. It would similarly return appropriate objects for each context.

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

@@ -1097,7 +1097,7 @@ might match only if the target entity type declares a static finder method (for
=== The `ConversionService` API
`ConversionService` defines a unified API for executing type conversion logic at
runtime. Converters are often executed behind the following facade interface:
runtime. Converters are often run behind the following facade interface:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
.Java
@@ -1218,7 +1218,7 @@ it like you would for any other bean. The following example shows how to do so:
----
@Service
class MyService(private val conversionService: ConversionService) {
fun doIt() {
conversionService.convert(...)
}