root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Fix cross references

This commit is contained in:
Rob Winch 2023-04-19 10:26:17 -05:00 committed by rstoyanchev
parent 6b341ddf19
commit 139cde47e2
296 changed files with 1505 additions and 1505 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
framework-docs/modules/ROOT/pages/appendix.adoc
View File

@ -30,7 +30,7 @@ for details.
| `spring.expression.compiler.mode`
| The mode to use when compiling expressions for the
<<core.adoc#expressions-compiler-configuration, Spring Expression Language>>.
xref:core/expressions/evaluation.adoc#expressions-compiler-configuration[Spring Expression Language].
| `spring.getenv.ignore`
| Instructs Spring to ignore operating system environment variables if a Spring
@ -41,12 +41,12 @@ for details.
| `spring.index.ignore`
| Instructs Spring to ignore the components index located in
`META-INF/spring.components`. See <<core.adoc#beans-scanning-index, Generating an Index
of Candidate Components>>.
`META-INF/spring.components`. See xref:core/beans/classpath-scanning.adoc#beans-scanning-index[Generating an Index of Candidate Components]
.
| `spring.jdbc.getParameterType.ignore`
| Instructs Spring to ignore `java.sql.ParameterMetaData.getParameterType` completely.
See the note in <<data-access.adoc#jdbc-batch-list, Batch Operations with a List of Objects>>.
See the note in xref:data-access/jdbc/advanced.adoc#jdbc-batch-list[Batch Operations with a List of Objects].
| `spring.jndi.ignore`
| Instructs Spring to ignore a default JNDI environment, as an optimization for scenarios
@ -62,17 +62,17 @@ for details.
| `spring.test.constructor.autowire.mode`
| The default _test constructor autowire mode_ to use if `@TestConstructor` is not present
on a test class. See <<testing.adoc#integration-testing-annotations-testconstructor,
Changing the default test constructor autowire mode>>.
on a test class. See xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[Changing the default test constructor autowire mode]
.
| `spring.test.context.cache.maxSize`
| The maximum size of the context cache in the _Spring TestContext Framework_. See
<<testing.adoc#testcontext-ctx-management-caching, Context Caching>>.
xref:testing/testcontext-framework/ctx-management/caching.adoc[Context Caching].
| `spring.test.enclosing.configuration`
| The default _enclosing configuration inheritance mode_ to use if
`@NestedTestConfiguration` is not present on a test class. See
<<testing.adoc#integration-testing-annotations-nestedtestconfiguration, Changing the
default enclosing configuration inheritance mode>>.
xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[Changing the default enclosing configuration inheritance mode]
.
|===

2
framework-docs/modules/ROOT/pages/core/aop-api/concise-proxy.adoc
View File

@ -58,7 +58,7 @@ we override the transaction propagation settings:
Note that in the parent bean example, we explicitly marked the parent bean definition as
being abstract by setting the `abstract` attribute to `true`, as described
<<beans-child-bean-definitions, previously>>, so that it may not actually ever be
xref:core/beans/child-bean-definitions.adoc[previously], so that it may not actually ever be
instantiated. Application contexts (but not simple bean factories), by default,
pre-instantiate all singletons. Therefore, it is important (at least for singleton beans)
that, if you have a (parent) bean definition that you intend to use only as a template,

8
framework-docs/modules/ROOT/pages/core/aop-api/pfb.adoc
View File

@ -40,7 +40,7 @@ In common with most `FactoryBean` implementations provided with Spring, the
`ProxyFactoryBean` class is itself a JavaBean. Its properties are used to:
* Specify the target you want to proxy.
* Specify whether to use CGLIB (described later and see also <<aop-pfb-proxy-types>>).
* Specify whether to use CGLIB (described later and see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]).
Some key properties are inherited from `org.springframework.aop.framework.ProxyConfig`
(the superclass for all AOP proxy factories in Spring). These key properties include
@ -48,7 +48,7 @@ the following:
* `proxyTargetClass`: `true` if the target class is to be proxied, rather than the
target class's interfaces. If this property value is set to `true`, then CGLIB proxies
are created (but see also <<aop-pfb-proxy-types>>).
are created (but see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]).
* `optimize`: Controls whether or not aggressive optimizations are applied to proxies
created through CGLIB. You should not blithely use this setting unless you fully
understand how the relevant AOP proxy handles optimization. This is currently used
@ -66,7 +66,7 @@ the following:
Other properties specific to `ProxyFactoryBean` include the following:
* `proxyInterfaces`: An array of `String` interface names. If this is not supplied, a CGLIB
proxy for the target class is used (but see also <<aop-pfb-proxy-types>>).
proxy for the target class is used (but see also xref:core/aop-api/pfb.adoc#aop-pfb-proxy-types[JDK- and CGLIB-based proxies]).
* `interceptorNames`: A `String` array of `Advisor`, interceptor, or other advice names to
apply. Ordering is significant, on a first come-first served basis. That is to say
that the first interceptor in the list is the first to be able to intercept the
@ -78,7 +78,7 @@ factories. You cannot mention bean references here, since doing so results in th
+
You can append an interceptor name with an asterisk (`*`). Doing so results in the
application of all advisor beans with names that start with the part before the asterisk
to be applied. You can find an example of using this feature in <<aop-global-advisors>>.
to be applied. You can find an example of using this feature in xref:core/aop-api/pfb.adoc#aop-global-advisors[Using "`Global`" Advisors].
* singleton: Whether or not the factory should return a single object, no matter how
often the `getObject()` method is called. Several `FactoryBean` implementations offer

2
framework-docs/modules/ROOT/pages/core/aop-api/pointcuts.adoc
View File

@ -92,7 +92,7 @@ Since 2.0, the most important type of pointcut used by Spring is
`org.springframework.aop.aspectj.AspectJExpressionPointcut`. This is a pointcut that
uses an AspectJ-supplied library to parse an AspectJ pointcut expression string.
See the <<aop, previous chapter>> for a discussion of supported AspectJ pointcut primitives.
See the xref:core/aop.adoc[previous chapter] for a discussion of supported AspectJ pointcut primitives.

6
framework-docs/modules/ROOT/pages/core/aop.adoc
View File

@ -15,18 +15,18 @@ to), AOP complements Spring IoC to provide a very capable middleware solution.
.Spring AOP with AspectJ pointcuts
****
Spring provides simple and powerful ways of writing custom aspects by using either a
<<aop-schema, schema-based approach>> or the <<aop-ataspectj, @AspectJ annotation style>>.
xref:core/aop/schema.adoc[schema-based approach] or the xref:core/aop/ataspectj.adoc[@AspectJ annotation style].
Both of these styles offer fully typed advice and use of the AspectJ pointcut language
while still using Spring AOP for weaving.
This chapter discusses the schema- and @AspectJ-based AOP support.
The lower-level AOP support is discussed in <<aop-api, the following chapter>>.
The lower-level AOP support is discussed in xref:core/aop-api.adoc[the following chapter].
****
AOP is used in the Spring Framework to:
* Provide declarative enterprise services. The most important such service is
<<data-access.adoc#transaction-declarative, declarative transaction management>>.
xref:data-access/transaction/declarative.adoc[declarative transaction management].
* Let users implement custom aspects, complementing their use of OOP with AOP.
NOTE: If you are interested only in generic declarative services or other pre-packaged

2
framework-docs/modules/ROOT/pages/core/aop/aspectj-programmatic.adoc
View File

@ -4,7 +4,7 @@
In addition to declaring aspects in your configuration by using either `<aop:config>`
or `<aop:aspectj-autoproxy>`, it is also possible to programmatically create proxies
that advise target objects. For the full details of Spring's AOP API, see the
<<aop-api, next chapter>>. Here, we want to focus on the ability to automatically
xref:core/aop-api.adoc[next chapter]. Here, we want to focus on the ability to automatically
create proxies by using @AspectJ aspects.
You can use the `org.springframework.aop.aspectj.annotation.AspectJProxyFactory` class

2
framework-docs/modules/ROOT/pages/core/aop/ataspectj.adoc
View File

@ -9,7 +9,7 @@ for pointcut parsing and matching. The AOP runtime is still pure Spring AOP, tho
there is no dependency on the AspectJ compiler or weaver.
NOTE: Using the AspectJ compiler and weaver enables use of the full AspectJ language and
is discussed in <<aop-using-aspectj>>.
is discussed in xref:core/aop/using-aspectj.adoc[Using AspectJ with Spring Applications].

28
framework-docs/modules/ROOT/pages/core/aop/ataspectj/advice.adoc
View File

@ -3,7 +3,7 @@
Advice is associated with a pointcut expression and runs before, after, or around method
executions matched by the pointcut. The pointcut expression may be either an _inline
pointcut_ or a reference to a <<aop-common-pointcuts,_named pointcut_>>.
pointcut_ or a reference to a xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[_named pointcut_].
[[aop-advice-before]]
@ -44,7 +44,7 @@ The following example uses an inline pointcut expression.
}
----
If we use a <<aop-common-pointcuts,named pointcut>>, we can rewrite the preceding example
If we use a xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[named pointcut], we can rewrite the preceding example
as follows:
[source,java,indent=0,subs="verbatim",role="primary"]
@ -352,7 +352,7 @@ execution-only semantics. You only need to be aware of this difference if you co
`@AspectJ` aspects written for Spring and use `proceed` with arguments with the AspectJ
compiler and weaver. There is a way to write such aspects that is 100% compatible across
both Spring AOP and AspectJ, and this is discussed in the
<<aop-ataspectj-advice-proceeding-with-the-call, following section on advice parameters>>.
xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-proceeding-with-the-call[following section on advice parameters].
====
The value returned by the around advice is the return value seen by the caller of the
@ -536,7 +536,7 @@ The following shows the advice that matches the execution of `@Auditable` method
// ...
}
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
[source,kotlin,indent=0,subs="verbatim",role="secondary"]
.Kotlin
@ -547,7 +547,7 @@ The following shows the advice that matches the execution of `@Auditable` method
// ...
}
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
[[aop-ataspectj-advice-params-generics]]
=== Advice Parameters and Generics
@ -633,7 +633,7 @@ of determining parameter names, an exception will be thrown.
`AspectJAnnotationParameterNameDiscoverer` :: Uses parameter names that have been explicitly
specified by the user via the `argNames` attribute in the corresponding advice or
pointcut annotation. See <<aop-ataspectj-advice-params-names-explicit>> for details.
pointcut annotation. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params-names-explicit[Explicit Argument Names] for details.
`KotlinReflectionParameterNameDiscoverer` :: Uses Kotlin reflection APIs to determine
parameter names. This discoverer is only used if such APIs are present on the classpath.
`StandardReflectionParameterNameDiscoverer` :: Uses the standard `java.lang.reflect.Parameter`
@ -679,7 +679,7 @@ The following example shows how to use the `argNames` attribute:
// ... use code and bean
}
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
<2> Declares `bean` and `auditable` as the argument names.
[source,kotlin,indent=0,subs="verbatim",role="secondary"]
@ -693,7 +693,7 @@ The following example shows how to use the `argNames` attribute:
// ... use code and bean
}
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
<2> Declares `bean` and `auditable` as the argument names.
If the first parameter is of type `JoinPoint`, `ProceedingJoinPoint`, or
@ -712,7 +712,7 @@ point object, the `argNames` attribute does not need to include it:
// ... use code, bean, and jp
}
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
<2> Declares `bean` and `auditable` as the argument names.
[source,kotlin,indent=0,subs="verbatim",role="secondary"]
@ -726,7 +726,7 @@ point object, the `argNames` attribute does not need to include it:
// ... use code, bean, and jp
}
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
<2> Declares `bean` and `auditable` as the argument names.
The special treatment given to the first parameter of type `JoinPoint`,
@ -743,7 +743,7 @@ the `argNames` attribute:
// ... use jp
}
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
[source,kotlin,indent=0,subs="verbatim",role="secondary"]
.Kotlin
@ -753,7 +753,7 @@ the `argNames` attribute:
// ... use jp
}
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
[[aop-ataspectj-advice-proceeding-with-the-call]]
@ -776,7 +776,7 @@ The following example shows how to do so:
return pjp.proceed(new Object[] {newPattern});
}
----
<1> References the `inDataAccessLayer` named pointcut defined in <<aop-common-pointcuts>>.
<1> References the `inDataAccessLayer` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions].
[source,kotlin,indent=0,subs="verbatim",role="secondary"]
.Kotlin
@ -790,7 +790,7 @@ The following example shows how to do so:
return pjp.proceed(arrayOf<Any>(newPattern))
}
----
<1> References the `inDataAccessLayer` named pointcut defined in <<aop-common-pointcuts>>.
<1> References the `inDataAccessLayer` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions].
In many cases, you do this binding anyway (as in the preceding example).

4
framework-docs/modules/ROOT/pages/core/aop/ataspectj/aspectj-support.adoc
View File

@ -47,8 +47,8 @@ element, as the following example shows:
----
This assumes that you use schema support as described in
<<core.adoc#core.appendix.xsd-schemas, XML Schema-based configuration>>.
See <<core.adoc#core.appendix.xsd-schemas-aop, the AOP schema>> for how to
xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration].
See xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-aop[the AOP schema] for how to
import the tags in the `aop` namespace.

4
framework-docs/modules/ROOT/pages/core/aop/ataspectj/example.adoc
View File

@ -56,7 +56,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl
}
}
----
<1> References the `businessService` named pointcut defined in <<aop-common-pointcuts>>.
<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions].
[source,kotlin,indent=0,subs="verbatim",role="secondary"]
.Kotlin
@ -97,7 +97,7 @@ call `proceed` multiple times. The following listing shows the basic aspect impl
}
}
----
<1> References the `businessService` named pointcut defined in <<aop-common-pointcuts>>.
<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions].
Note that the aspect implements the `Ordered` interface so that we can set the precedence of
the aspect higher than the transaction advice (we want a fresh transaction each time we

20
framework-docs/modules/ROOT/pages/core/aop/ataspectj/pointcuts.adoc
View File

@ -99,7 +99,7 @@ If a pointcut is strictly meant to be public-only, even in a CGLIB proxy scenari
potential non-public interactions through proxies, it needs to be defined accordingly.
If your interception needs include method calls or even constructors within the target
class, consider the use of Spring-driven <<aop-aj-ltw, native AspectJ weaving>> instead
class, consider the use of Spring-driven xref:core/aop/using-aspectj.adoc#aop-aj-ltw[native AspectJ weaving] instead
of Spring's proxy-based AOP framework. This constitutes a different mode of AOP usage
with different characteristics, so be sure to make yourself familiar with weaving
before making a decision.
@ -350,8 +350,8 @@ could write the following which references the
</tx:advice>
----
The `<aop:config>` and `<aop:advisor>` elements are discussed in <<aop-schema>>. The
transaction elements are discussed in <<data-access.adoc#transaction, Transaction Management>>.
The `<aop:config>` and `<aop:advisor>` elements are discussed in xref:core/aop/schema.adoc[Schema-based AOP Support]. The
transaction elements are discussed in xref:data-access/transaction.adoc[Transaction Management].
[[aop-pointcuts-examples]]
@ -444,7 +444,7 @@ sub-packages:
this(com.xyz.service.AccountService)
----
+
NOTE: `this` is more commonly used in a binding form. See the section on <<aop-advice>>
NOTE: `this` is more commonly used in a binding form. See the section on xref:core/aop/ataspectj/advice.adoc[Declaring Advice]
for how to make the proxy object available in the advice body.
* Any join point (method execution only in Spring AOP) where the target object
@ -455,7 +455,7 @@ implements the `AccountService` interface:
target(com.xyz.service.AccountService)
----
+
NOTE: `target` is more commonly used in a binding form. See the <<aop-advice>> section
NOTE: `target` is more commonly used in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section
for how to make the target object available in the advice body.
* Any join point (method execution only in Spring AOP) that takes a single parameter
@ -466,7 +466,7 @@ and where the argument passed at runtime is `Serializable`:
args(java.io.Serializable)
----
+
NOTE: `args` is more commonly used in a binding form. See the <<aop-advice>> section
NOTE: `args` is more commonly used in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section
for how to make the method arguments available in the advice body.
+
Note that the pointcut given in this example is different from `execution(*
@ -482,7 +482,7 @@ parameter of type `Serializable`.
@target(org.springframework.transaction.annotation.Transactional)
----
+
NOTE: You can also use `@target` in a binding form. See the <<aop-advice>> section for
NOTE: You can also use `@target` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for
how to make the annotation object available in the advice body.
* Any join point (method execution only in Spring AOP) where the declared type of the
@ -493,7 +493,7 @@ target object has an `@Transactional` annotation:
@within(org.springframework.transaction.annotation.Transactional)
----
+
NOTE: You can also use `@within` in a binding form. See the <<aop-advice>> section for
NOTE: You can also use `@within` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section for
how to make the annotation object available in the advice body.
* Any join point (method execution only in Spring AOP) where the executing method has an
@ -504,7 +504,7 @@ how to make the annotation object available in the advice body.
@annotation(org.springframework.transaction.annotation.Transactional)
----
+
NOTE: You can also use `@annotation` in a binding form. See the <<aop-advice>> section
NOTE: You can also use `@annotation` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section
for how to make the annotation object available in the advice body.
* Any join point (method execution only in Spring AOP) which takes a single parameter,
@ -515,7 +515,7 @@ and where the runtime type of the argument passed has the `@Classified` annotati
@args(com.xyz.security.Classified)
----
+
NOTE: You can also use `@args` in a binding form. See the <<aop-advice>> section
NOTE: You can also use `@args` in a binding form. See the xref:core/aop/ataspectj/advice.adoc[Declaring Advice] section
how to make the annotation object(s) available in the advice body.
* Any join point (method execution only in Spring AOP) on a Spring bean named

4
framework-docs/modules/ROOT/pages/core/aop/introduction-defn.adoc
View File

@ -8,8 +8,8 @@ However, it would be even more confusing if Spring used its own terminology.
* Aspect: A modularization of a concern that cuts across multiple classes.
Transaction management is a good example of a crosscutting concern in enterprise Java
applications. In Spring AOP, aspects are implemented by using regular classes
(the <<aop-schema, schema-based approach>>) or regular classes annotated with the
`@Aspect` annotation (the <<aop-ataspectj, @AspectJ style>>).
(the xref:core/aop/schema.adoc[schema-based approach]) or regular classes annotated with the
`@Aspect` annotation (the xref:core/aop/ataspectj.adoc[@AspectJ style]).
* Join point: A point during the execution of a program, such as the execution of a
method or the handling of an exception. In Spring AOP, a join point always
represents a method execution.

4
framework-docs/modules/ROOT/pages/core/aop/introduction-proxies.adoc
View File

@ -8,12 +8,12 @@ Spring AOP can also use CGLIB proxies. This is necessary to proxy classes rather
interfaces. By default, CGLIB is used if a business object does not implement an
interface. As it is good practice to program to interfaces rather than classes, business
classes normally implement one or more business interfaces. It is possible to
<<aop-proxying, force the use of CGLIB>>, in those (hopefully rare) cases where you
xref:core/aop/proxying.adoc[force the use of CGLIB], in those (hopefully rare) cases where you
need to advise a method that is not declared on an interface or where you need to
pass a proxied object to a method as a concrete type.
It is important to grasp the fact that Spring AOP is proxy-based. See
<<aop-understanding-aop-proxies>> for a thorough examination of exactly what this
xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[Understanding AOP Proxies] for a thorough examination of exactly what this
implementation detail actually means.

4
framework-docs/modules/ROOT/pages/core/aop/introduction-spring-defn.adoc
View File

@ -30,7 +30,7 @@ frameworks such as AspectJ are valuable and that they are complementary, rather
competition. Spring seamlessly integrates Spring AOP and IoC with AspectJ, to enable
all uses of AOP within a consistent Spring-based application
architecture. This integration does not affect the Spring AOP API or the AOP Alliance
API. Spring AOP remains backward-compatible. See <<aop-api, the following chapter>>
API. Spring AOP remains backward-compatible. See xref:core/aop-api.adoc[the following chapter]
for a discussion of the Spring AOP APIs.
[NOTE]
@ -52,7 +52,7 @@ configuration-style approach. The fact that this chapter chooses to introduce th
@AspectJ-style approach first should not be taken as an indication that the Spring team
favors the @AspectJ annotation-style approach over the Spring XML configuration-style.
See <<aop-choosing>> for a more complete discussion of the advantages and disadvantages of
See xref:core/aop/choosing.adoc[Choosing which AOP Declaration Style to Use] for a more complete discussion of the advantages and disadvantages of
each style.
====

30
framework-docs/modules/ROOT/pages/core/aop/schema.adoc
View File

@ -5,12 +5,12 @@ If you prefer an XML-based format, Spring also offers support for defining aspec
using the `aop` namespace tags. The exact same pointcut expressions and advice kinds
as when using the @AspectJ style are supported. Hence, in this section we focus on
that syntax and refer the reader to the discussion in the previous section
(<<aop-ataspectj>>) for an understanding of writing pointcut expressions and the binding
(xref:core/aop/ataspectj.adoc[@AspectJ support]) for an understanding of writing pointcut expressions and the binding
of advice parameters.
To use the aop namespace tags described in this section, you need to import the
`spring-aop` schema, as described in <<core.adoc#core.appendix.xsd-schemas,
XML Schema-based configuration>>. See <<core.adoc#core.appendix.xsd-schemas-aop, the AOP schema>>
`spring-aop` schema, as described in xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration]
. See xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-aop[the AOP schema]
for how to import the tags in the `aop` namespace.
Within your Spring configurations, all aspect and advisor elements must be placed within
@ -19,7 +19,7 @@ application context configuration). An `<aop:config>` element can contain pointc
advisor, and aspect elements (note that these must be declared in that order).
WARNING: The `<aop:config>` style of configuration makes heavy use of Spring's
<<aop-autoproxy, auto-proxying>> mechanism. This can cause issues (such as advice
xref:core/aop-api/autoproxy.adoc[auto-proxying] mechanism. This can cause issues (such as advice
not being woven) if you already use explicit auto-proxying through the use of
`BeanNameAutoProxyCreator` or something similar. The recommended usage pattern is to
use either only the `<aop:config>` style or only the `AutoProxyCreator` style and
@ -75,7 +75,7 @@ be defined as follows:
----
Note that the pointcut expression itself uses the same AspectJ pointcut expression
language as described in <<aop-ataspectj>>. If you use the schema based declaration
language as described in xref:core/aop/ataspectj.adoc[@AspectJ support]. If you use the schema based declaration
style, you can also refer to _named pointcuts_ defined in `@Aspect` types within the
pointcut expression. Thus, another way of defining the above pointcut would be as follows:
@ -88,7 +88,7 @@ pointcut expression. Thus, another way of defining the above pointcut would be a
</aop:config>
----
<1> References the `businessService` named pointcut defined in <<aop-common-pointcuts>>.
<1> References the `businessService` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions].
Declaring a pointcut _inside_ an aspect is very similar to declaring a top-level pointcut,
as the following example shows:
@ -203,10 +203,10 @@ Before advice runs before a matched method execution. It is declared inside an
----
In the example above, `dataAccessOperation` is the `id` of a _named pointcut_ defined at
the top (`<aop:config>`) level (see <<aop-schema-pointcuts>>).
the top (`<aop:config>`) level (see xref:core/aop/schema.adoc#aop-schema-pointcuts[Declaring a Pointcut]).
NOTE: As we noted in the discussion of the @AspectJ style, using _named pointcuts_ can
significantly improve the readability of your code. See <<aop-common-pointcuts>> for
significantly improve the readability of your code. See xref:core/aop/ataspectj/pointcuts.adoc#aop-common-pointcuts[Sharing Named Pointcut Definitions] for
details.
To define the pointcut inline instead, replace the `pointcut-ref` attribute with a
@ -379,7 +379,7 @@ Invoking `proceed()` without arguments will result in the caller's original argu
being supplied to the underlying method when it is invoked. For advanced use cases, there
is an overloaded variant of the `proceed()` method which accepts an array of arguments
(`Object[]`). The values in the array will be used as the arguments to the underlying
method when it is invoked. See <<aop-ataspectj-around-advice>> for notes on calling
method when it is invoked. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-around-advice[Around Advice] for notes on calling
`proceed` with an `Object[]`.
The following example shows how to declare around advice in XML:
@ -426,11 +426,11 @@ The implementation of the `doBasicProfiling` advice can be exactly the same as i
The schema-based declaration style supports fully typed advice in the same way as
described for the @AspectJ support -- by matching pointcut parameters by name against
advice method parameters. See <<aop-ataspectj-advice-params>> for details. If you wish
advice method parameters. See xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params[Advice Parameters] for details. If you wish
to explicitly specify argument names for the advice methods (not relying on the
detection strategies previously described), you can do so by using the `arg-names`
attribute of the advice element, which is treated in the same manner as the `argNames`
attribute in an advice annotation (as described in <<aop-ataspectj-advice-params-names>>).
attribute in an advice annotation (as described in xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-params-names[Determining Argument Names]).
The following example shows how to specify an argument name in XML:
[source,xml,indent=0,subs="verbatim"]
@ -440,7 +440,7 @@ The following example shows how to specify an argument name in XML:
method="audit"
arg-names="auditable" />
----
<1> References the `publicMethod` named pointcut defined in <<aop-pointcuts-combining>>.
<1> References the `publicMethod` named pointcut defined in xref:core/aop/ataspectj/pointcuts.adoc#aop-pointcuts-combining[Combining Pointcut Expressions].
The `arg-names` attribute accepts a comma-delimited list of parameter names.
@ -608,7 +608,7 @@ ms % Task name
=== Advice Ordering
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
the ordering rules are as described in xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[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
the bean implement the `Ordered` interface.
@ -718,7 +718,7 @@ The concept of "advisors" comes from the AOP support defined in Spring
and does not have a direct equivalent in AspectJ. An advisor is like a small
self-contained aspect that has a single piece of advice. The advice itself is
represented by a bean and must implement one of the advice interfaces described in
<<aop-api-advice-types>>. Advisors can take advantage of AspectJ pointcut expressions.
xref:core/aop-api/advice.adoc#aop-api-advice-types[Advice Types in Spring]. Advisors can take advantage of AspectJ pointcut expressions.
Spring supports the advisor concept with the `<aop:advisor>` element. You most
commonly see it used in conjunction with transactional advice, which also has its own
@ -756,7 +756,7 @@ use the `order` attribute to define the `Ordered` value of the advisor.
== An AOP Schema Example
This section shows how the concurrent locking failure retry example from
<<aop-ataspectj-example>> looks when rewritten with the schema support.
xref:core/aop/ataspectj/example.adoc[An AOP Example] looks when rewritten with the schema support.
The execution of business services can sometimes fail due to concurrency issues (for
example, a deadlock loser). If the operation is retried, it is likely to succeed

24
framework-docs/modules/ROOT/pages/core/aop/using-aspectj.adoc
View File

@ -8,10 +8,10 @@ alone.
Spring ships with a small AspectJ aspect library, which is available stand-alone in your
distribution as `spring-aspects.jar`. You need to add this to your classpath in order
to use the aspects in it. <<aop-atconfigurable>> and <<aop-ajlib-other>> discuss the
content of this library and how you can use it. <<aop-aj-configure>> discusses how to
to use the aspects in it. xref:core/aop/using-aspectj.adoc#aop-atconfigurable[Using AspectJ to Dependency Inject Domain Objects with Spring] and xref:core/aop/using-aspectj.adoc#aop-ajlib-other[Other Spring aspects for AspectJ] discuss the
content of this library and how you can use it. xref:core/aop/using-aspectj.adoc#aop-aj-configure[Configuring AspectJ Aspects by Using Spring IoC] discusses how to
dependency inject AspectJ aspects that are woven using the AspectJ compiler. Finally,
<<aop-aj-ltw>> provides an introduction to load-time weaving for Spring applications
xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework] provides an introduction to load-time weaving for Spring applications
that use AspectJ.
@ -108,7 +108,7 @@ annotation. You can specify either `@Configurable(autowire=Autowire.BY_TYPE)` or
`@Configurable(autowire=Autowire.BY_NAME)` for autowiring by type or by name,
respectively. As an alternative, it is preferable to specify explicit, annotation-driven
dependency injection for your `@Configurable` beans through `@Autowired` or `@Inject`
at the field or method level (see <<beans-annotation-config>> for further details).
at the field or method level (see xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration] for further details).
Finally, you can enable Spring dependency checking for the object references in the newly
created and configured object by using the `dependencyCheck` attribute (for example,
@ -158,7 +158,7 @@ Programming Guide].
For this to work, the annotated types must be woven with the AspectJ weaver. You can
either use a build-time Ant or Maven task to do this (see, for example, the
https://www.eclipse.org/aspectj/doc/released/devguide/antTasks.html[AspectJ Development
Environment Guide]) or load-time weaving (see <<aop-aj-ltw>>). The
Environment Guide]) or load-time weaving (see xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework]). The
`AnnotationBeanConfigurerAspect` itself needs to be configured by Spring (in order to obtain
a reference to the bean factory that is to be used to configure new objects). If you
use Java-based configuration, you can add `@EnableSpringConfigured` to any
@ -182,7 +182,7 @@ use Java-based configuration, you can add `@EnableSpringConfigured` to any
----
If you prefer XML based configuration, the Spring
<<core.adoc#core.appendix.xsd-schemas-context, `context` namespace>>
xref:core/appendix/xsd-schemas.adoc#core.appendix.xsd-schemas-context[`context` namespace]
defines a convenient `context:spring-configured` element, which you can use as follows:
[source,xml,indent=0,subs="verbatim"]
@ -387,7 +387,7 @@ per-`ClassLoader` basis, which is more fine-grained and which can make more
sense in a 'single-JVM-multiple-application' environment (such as is found in a typical
application server environment).
Further, <<aop-aj-ltw-environments, in certain environments>>, this support enables
Further, xref:core/aop/using-aspectj.adoc#aop-aj-ltw-environments[in certain environments], this support enables
load-time weaving without making any modifications to the application server's launch
script that is needed to add `-javaagent:path/to/aspectjweaver.jar` or (as we describe
later in this section) `-javaagent:path/to/spring-instrument.jar`. Developers configure
@ -410,9 +410,9 @@ quickly get some performance metrics. We can then apply a finer-grained profilin
tool to that specific area immediately afterwards.
NOTE: The example presented here uses XML configuration. You can also configure and
use @AspectJ with <<beans-java, Java configuration>>. Specifically, you can use the
use @AspectJ with xref:core/beans/java.adoc[Java configuration]. Specifically, you can use the
`@EnableLoadTimeWeaving` annotation as an alternative to `<context:load-time-weaver/>`
(see <<aop-aj-ltw-spring, below>> for details).
(see xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[below] for details).
The following example shows the profiling aspect, which is not fancy.
It is a time-based profiler that uses the @AspectJ-style of aspect declaration:
@ -692,8 +692,8 @@ for AspectJ LTW:
* `spring-aop.jar`
* `aspectjweaver.jar`
If you use the <<aop-aj-ltw-environments-generic, Spring-provided agent to enable
instrumentation>>, you also need:
If you use the xref:core/aop/using-aspectj.adoc#aop-aj-ltw-environments-generic[Spring-provided agent to enable instrumentation]
, you also need:
* `spring-instrument.jar`
@ -900,7 +900,7 @@ containers.
Tomcat, JBoss/WildFly, IBM WebSphere Application Server and Oracle WebLogic Server all
provide a general app `ClassLoader` that is capable of local instrumentation. Spring's
native LTW may leverage those ClassLoader implementations to provide AspectJ weaving.
You can simply enable load-time weaving, as <<aop-using-aspectj, described earlier>>.
You can simply enable load-time weaving, as xref:core/aop/using-aspectj.adoc[described earlier].
Specifically, you do not need to modify the JVM launch script to add
`-javaagent:path/to/spring-instrument.jar`.

8
framework-docs/modules/ROOT/pages/core/aot.adoc
View File

@ -3,7 +3,7 @@
This chapter covers Spring's Ahead of Time (AOT) optimizations.
For AOT support specific to integration tests, see <<testing.adoc#testcontext-aot, Ahead of Time Support for Tests>>.
For AOT support specific to integration tests, see xref:testing/testcontext-framework/aot.adoc[Ahead of Time Support for Tests].
[[core.aot.introduction]]
== Introduction to Ahead of Time Optimizations
@ -57,12 +57,12 @@ Let's look at a basic example:
include::code:AotProcessingSample[tag=myapplication]
Starting this application with the regular runtime involves a number of steps including classpath scanning, configuration class parsing, bean instantiation, and lifecycle callback handling.
Refresh for AOT processing only applies a subset of what happens with a <<beans-introduction,regular `refresh`>>.
Refresh for AOT processing only applies a subset of what happens with a xref:core/beans/introduction.adoc[regular `refresh`].
AOT processing can be triggered as follows:
include::code:AotProcessingSample[tag=aotcontext]
In this mode, <<beans-factory-extension-factory-postprocessors,`BeanFactoryPostProcessor` implementations>> are invoked as usual.
In this mode, xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[`BeanFactoryPostProcessor` implementations] are invoked as usual.
This includes configuration class parsing, import selectors, classpath scanning, etc.
Such steps make sure that the `BeanRegistry` contains the relevant bean definitions for the application.
If bean definitions are guarded by conditions (such as `@Profile`), these are discarded at this stage.
@ -108,7 +108,7 @@ It does so using a dedicated `BeanRegistrationAotProcessor`.
This interface is used as follows:
* Implemented by a `BeanPostProcessor` bean, to replace its runtime behavior.
For instance <<beans-factory-extension-bpp-examples-aabpp,`AutowiredAnnotationBeanPostProcessor`>> implements this interface to generate code that injects members annotated with `@Autowired`.
For instance xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp-examples-aabpp[`AutowiredAnnotationBeanPostProcessor`] implements this interface to generate code that injects members annotated with `@Autowired`.
* Implemented by a type registered in `META-INF/spring/aot.factories` with a key equal to the fully qualified name of the interface.
Typically used when the bean definition needs to be tuned for specific features of the core framework.

16
framework-docs/modules/ROOT/pages/core/appendix/xml-custom.adoc
View File

@ -10,16 +10,16 @@ integrate such parsers into the Spring IoC container.
To facilitate authoring configuration files that use a schema-aware XML editor,
Spring's extensible XML configuration mechanism is based on XML Schema. If you are not
familiar with Spring's current XML configuration extensions that come with the standard
Spring distribution, you should first read the previous section on <<core.appendix.xsd-schemas>>.
Spring distribution, you should first read the previous section on xref:core/appendix/xsd-schemas.adoc[XML Schemas].
To create new XML configuration extensions:
. <<core.appendix.xsd-custom-schema, Author>> an XML schema to describe your custom element(s).
. <<core.appendix.xsd-custom-namespacehandler, Code>> a custom `NamespaceHandler` implementation.
. <<core.appendix.xsd-custom-parser, Code>> one or more `BeanDefinitionParser` implementations
. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-schema[Author] an XML schema to describe your custom element(s).
. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-namespacehandler[Code] a custom `NamespaceHandler` implementation.
. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-parser[Code] one or more `BeanDefinitionParser` implementations
(this is where the real work is done).
. <<core.appendix.xsd-custom-registration, Register>> your new artifacts with Spring.
. xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-registration[Register] your new artifacts with Spring.
For a unified example, we create an
XML extension (a custom XML element) that lets us configure objects of the type
@ -129,7 +129,7 @@ The `NamespaceHandler` interface features three methods:
* `BeanDefinitionHolder decorate(Node, BeanDefinitionHolder, ParserContext)`: Called
when Spring encounters an attribute or nested element of a different namespace.
The decoration of one or more bean definitions is used (for example) with the
<<core.adoc#beans-factory-scopes, scopes that Spring supports>>.
xref:core/beans/factory-scopes.adoc[scopes that Spring supports].
We start by highlighting a simple example, without using decoration, after which
we show decoration in a somewhat more advanced example.
@ -541,7 +541,7 @@ setter property for the `components` property. The following listing shows such
This works nicely, but it exposes a lot of Spring plumbing to the end user. What we are
going to do is write a custom extension that hides away all of this Spring plumbing.
If we stick to <<core.appendix.xsd-custom-introduction, the steps described previously>>, we start off
If we stick to xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-introduction[the steps described previously], we start off
by creating the XSD schema to define the structure of our custom tag, as the following
listing shows:
@ -568,7 +568,7 @@ listing shows:
</xsd:schema>
----
Again following <<core.appendix.xsd-custom-introduction, the process described earlier>>,
Again following xref:core/appendix/xml-custom.adoc#core.appendix.xsd-custom-introduction[the process described earlier],
we then create a custom `NamespaceHandler`:
[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"]

46
framework-docs/modules/ROOT/pages/core/appendix/xsd-schemas.adoc
View File

@ -312,7 +312,7 @@ Consider the following example:
The preceding configuration uses a Spring `FactoryBean` implementation (the
`PropertiesFactoryBean`) to instantiate a `java.util.Properties` instance with values
loaded from the supplied <<core.adoc#resources, `Resource`>> location).
loaded from the supplied xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[`Resource`] location).
The following example uses a `util:properties` element to make a more concise representation:
@ -494,8 +494,8 @@ If no `set-class` attribute is supplied, the container chooses a `Set` implement
The `aop` tags deal with configuring all things AOP in Spring, including Spring's
own proxy-based AOP framework and Spring's integration with the AspectJ AOP framework.
These tags are comprehensively covered in the chapter entitled <<core.adoc#aop,
Aspect Oriented Programming with Spring>>.
These tags are comprehensively covered in the chapter entitled xref:core/aop.adoc[Aspect Oriented Programming with Spring]
.
In the interest of completeness, to use the tags in the `aop` schema, you need to have
the following preamble at the top of your Spring XML configuration file (the text in the
@ -548,9 +548,9 @@ available to you:
=== Using `<property-placeholder/>`
This element activates the replacement of `${...}` placeholders, which are resolved against a
specified properties file (as a <<core.adoc#resources, Spring resource location>>). This element
is a convenience mechanism that sets up a <<core.adoc#beans-factory-placeholderconfigurer,
`PropertySourcesPlaceholderConfigurer`>> for you. If you need more control over the specific
specified properties file (as a xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Spring resource location]). This element
is a convenience mechanism that sets up a xref:core/beans/factory-extension.adoc#beans-factory-placeholderconfigurer[`PropertySourcesPlaceholderConfigurer`]
for you. If you need more control over the specific
`PropertySourcesPlaceholderConfigurer` setup, you can explicitly define it as a bean yourself.
@ -559,50 +559,50 @@ is a convenience mechanism that sets up a <<core.adoc#beans-factory-placeholderc
This element activates the Spring infrastructure to detect annotations in bean classes:
* Spring's <<core.adoc#beans-factory-metadata, `@Configuration`>> model
* <<core.adoc#beans-annotation-config, `@Autowired`/`@Inject`>>, `@Value`, and `@Lookup`
* Spring's xref:core/beans/basics.adoc#beans-factory-metadata[`@Configuration`] model
* xref:core/beans/annotation-config.adoc[`@Autowired`/`@Inject`], `@Value`, and `@Lookup`
* JSR-250's `@Resource`, `@PostConstruct`, and `@PreDestroy` (if available)
* JAX-WS's `@WebServiceRef` and EJB 3's `@EJB` (if available)
* JPA's `@PersistenceContext` and `@PersistenceUnit` (if available)
* Spring's <<core.adoc#context-functionality-events-annotation, `@EventListener`>>
* Spring's xref:core/beans/context-introduction.adoc#context-functionality-events-annotation[`@EventListener`]
Alternatively, you can choose to explicitly activate the individual `BeanPostProcessors`
for those annotations.
NOTE: This element does not activate processing of Spring's
<<data-access.adoc#transaction-declarative-annotations, `@Transactional`>> annotation;
xref:data-access/transaction/declarative/annotations.adoc[`@Transactional`] annotation;
you can use the <<data-access.adoc#tx-decl-explained, `<tx:annotation-driven/>`>>
element for that purpose. Similarly, Spring's
<<integration.adoc#cache-annotations, caching annotations>> need to be explicitly
<<integration.adoc#cache-annotation-enable, enabled>> as well.
xref:integration/cache/annotations.adoc[caching annotations] need to be explicitly
xref:integration/cache/annotations.adoc#cache-annotation-enable[enabled] as well.
[[core.appendix.xsd-schemas-context-component-scan]]
=== Using `<component-scan/>`
This element is detailed in the section on <<core.adoc#beans-annotation-config,
annotation-based container configuration>>.
This element is detailed in the section on xref:core/beans/annotation-config.adoc[annotation-based container configuration]
.
[[core.appendix.xsd-schemas-context-ltw]]
=== Using `<load-time-weaver/>`
This element is detailed in the section on <<core.adoc#aop-aj-ltw,
load-time weaving with AspectJ in the Spring Framework>>.
This element is detailed in the section on xref:core/aop/using-aspectj.adoc#aop-aj-ltw[load-time weaving with AspectJ in the Spring Framework]
.
[[core.appendix.xsd-schemas-context-sc]]
=== Using `<spring-configured/>`
This element is detailed in the section on <<core.adoc#aop-atconfigurable,
using AspectJ to dependency inject domain objects with Spring>>.
This element is detailed in the section on xref:core/aop/using-aspectj.adoc#aop-atconfigurable[using AspectJ to dependency inject domain objects with Spring]
.
[[core.appendix.xsd-schemas-context-mbe]]
=== Using `<mbean-export/>`
This element is detailed in the section on <<integration.adoc#jmx-context-mbeanexport,
configuring annotation-based MBean export>>.
This element is detailed in the section on xref:integration/jmx/naming.adoc#jmx-context-mbeanexport[configuring annotation-based MBean export]
.
@ -612,13 +612,13 @@ configuring annotation-based MBean export>>.
Last but not least, we have the elements in the `beans` schema. These elements
have been in Spring since the very dawn of the framework. Examples of the various elements
in the `beans` schema are not shown here because they are quite comprehensively covered
in <<core.adoc#beans-factory-properties-detailed, dependencies and configuration in detail>>
(and, indeed, in that entire <<core.adoc#beans, chapter>>).
in xref:core/beans/dependencies/factory-properties-detailed.adoc[dependencies and configuration in detail]
(and, indeed, in that entire xref:web/webmvc-view/mvc-xslt.adoc#mvc-view-xslt-beandefs[chapter]).
Note that you can add zero or more key-value pairs to `<bean/>` XML definitions.
What, if anything, is done with this extra metadata is totally up to your own custom
logic (and so is typically only of use if you write your own custom elements as described
in the appendix entitled <<core.appendix.xml-custom>>).
in the appendix entitled xref:core/appendix/xml-custom.adoc[XML Schema Authoring]).
The following example shows the `<meta/>` element in the context of a surrounding `<bean/>`
(note that, without any logic to interpret it, the metadata is effectively useless

12
framework-docs/modules/ROOT/pages/core/beans/annotation-config.adoc
View File

@ -14,7 +14,7 @@ while others argue that annotated classes are no longer POJOs and, furthermore,
configuration becomes decentralized and harder to control.
No matter the choice, Spring can accommodate both styles and even mix them together.
It is worth pointing out that through its <<beans-java, JavaConfig>> option, Spring lets
It is worth pointing out that through its xref:core/beans/java.adoc[JavaConfig] option, Spring lets
annotations be used in a non-invasive way, without touching the target components'
source code and that, in terms of tooling, all configuration styles are supported by
https://spring.io/tools[Spring Tools] for Eclipse, Visual Studio Code, and Theia.
@ -24,15 +24,15 @@ An alternative to XML setup is provided by annotation-based configuration, which
on bytecode metadata for wiring up components instead of XML declarations. Instead of
using XML to describe a bean wiring, the developer moves the configuration into the
component class itself by using annotations on the relevant class, method, or field
declaration. As mentioned in <<beans-factory-extension-bpp-examples-aabpp>>, using a
declaration. As mentioned in xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp-examples-aabpp[Example: The `AutowiredAnnotationBeanPostProcessor`], using a
`BeanPostProcessor` in conjunction with annotations is a common means of extending the
Spring IoC container. For example, the <<beans-autowired-annotation, `@Autowired`>>
annotation provides the same capabilities as described in <<beans-factory-autowire>> but
Spring IoC container. For example, the xref:core/beans/annotation-config/autowired.adoc[`@Autowired`]
annotation provides the same capabilities as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators] but
with more fine-grained control and wider applicability. In addition, Spring provides
support for JSR-250 annotations, such as `@PostConstruct` and `@PreDestroy`, as well as
support for JSR-330 (Dependency Injection for Java) annotations contained in the
`jakarta.inject` package such as `@Inject` and `@Named`. Details about those annotations
can be found in the <<beans-standard-annotations, relevant section>>.
can be found in the xref:core/beans/standard-annotations.adoc[relevant section].
[NOTE]
====
@ -74,7 +74,7 @@ The `<context:annotation-config/>` element implicitly registers the following po
application context in which it is defined. This means that, if you put
`<context:annotation-config/>` in a `WebApplicationContext` for a `DispatcherServlet`,
it only checks for `@Autowired` beans in your controllers, and not your services. See
<<web.adoc#mvc-servlet, The DispatcherServlet>> for more information.
xref:web/webmvc/mvc-servlet.adoc[The DispatcherServlet] for more information.
====

4
framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired-qualifiers.adoc
View File

@ -296,8 +296,8 @@ demonstrates both approaches:
----
--
In <<beans-classpath-scanning>>, you can see an annotation-based alternative to
providing the qualifier metadata in XML. Specifically, see <<beans-scanning-qualifiers>>.
In xref:core/beans/classpath-scanning.adoc[Classpath Scanning and Managed Components], you can see an annotation-based alternative to
providing the qualifier metadata in XML. Specifically, see xref:core/beans/classpath-scanning.adoc#beans-scanning-qualifiers[Providing Qualifier Metadata with Annotations].
In some cases, using an annotation without a value may suffice. This can be
useful when the annotation serves a more generic purpose and can be applied across

4
framework-docs/modules/ROOT/pages/core/beans/annotation-config/autowired.adoc
View File

@ -4,7 +4,7 @@
[NOTE]
====
JSR 330's `@Inject` annotation can be used in place of Spring's `@Autowired` annotation in the
examples included in this section. See <<beans-standard-annotations,here>> for more details.
examples included in this section. See xref:core/beans/standard-annotations.adoc[here] for more details.
====
You can apply the `@Autowired` annotation to constructors, as the following example shows:
@ -38,7 +38,7 @@ necessary if the target bean defines only one constructor to begin with. However
several constructors are available and there is no primary/default constructor, at least
one of the constructors must be annotated with `@Autowired` in order to instruct the
container which one to use. See the discussion on
<<beans-autowired-annotation-constructor-resolution, constructor resolution>> for details.
xref:core/beans/annotation-config/autowired.adoc#beans-autowired-annotation-constructor-resolution[constructor resolution] for details.
====
You can also apply the `@Autowired` annotation to _traditional_ setter methods,

6
framework-docs/modules/ROOT/pages/core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc
View File

@ -5,8 +5,8 @@ The `CommonAnnotationBeanPostProcessor` not only recognizes the `@Resource` anno
but also the JSR-250 lifecycle annotations: `jakarta.annotation.PostConstruct` and
`jakarta.annotation.PreDestroy`. Introduced in Spring 2.5, the support for these
annotations offers an alternative to the lifecycle callback mechanism described in
<<beans-factory-lifecycle-initializingbean,initialization callbacks>> and
<<beans-factory-lifecycle-disposablebean,destruction callbacks>>. Provided that the
xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[initialization callbacks] and
xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[destruction callbacks]. Provided that the
`CommonAnnotationBeanPostProcessor` is registered within the Spring `ApplicationContext`,
a method carrying one of these annotations is invoked at the same point in the lifecycle
as the corresponding Spring lifecycle interface method or explicitly declared callback
@ -47,7 +47,7 @@ cleared upon destruction:
----
For details about the effects of combining various lifecycle mechanisms, see
<<beans-factory-lifecycle-combined-effects>>.
xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-combined-effects[Combining Lifecycle Mechanisms].
[NOTE]
====

2
framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc
View File

@ -149,7 +149,7 @@ provide conversion support for your own custom type, you can provide your own
}
----
When `@Value` contains a <<expressions, `SpEL` expression>> the value will be dynamically
When `@Value` contains a xref:core/expressions.adoc[`SpEL` expression] the value will be dynamically
computed at runtime as the following example shows:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]

18
framework-docs/modules/ROOT/pages/core/beans/basics.adoc
View File

@ -22,7 +22,7 @@ additional metadata formats.
In most application scenarios, explicit user code is not required to instantiate one or
more instances of a Spring IoC container. For example, in a web application scenario, a
simple eight (or so) lines of boilerplate web descriptor XML in the `web.xml` file
of the application typically suffices (see <<context-create>>). If you use the
of the application typically suffices (see xref:core/beans/context-introduction.adoc#context-create[Convenient ApplicationContext Instantiation for Web Applications]). If you use the
https://spring.io/tools[Spring Tools for Eclipse] (an Eclipse-powered development
environment), you can easily create this boilerplate configuration with a few mouse clicks or
keystrokes.
@ -52,13 +52,13 @@ Spring IoC container.
NOTE: XML-based metadata is not the only allowed form of configuration metadata.
The Spring IoC container itself is totally decoupled from the format in which this
configuration metadata is actually written. These days, many developers choose
<<beans-java, Java-based configuration>> for their Spring applications.
xref:core/beans/java.adoc[Java-based configuration] for their Spring applications.
For information about using other forms of metadata with the Spring container, see:
* <<beans-annotation-config,Annotation-based configuration>>: define beans using
* xref:core/beans/annotation-config.adoc[Annotation-based configuration]: define beans using
annotation-based configuration metadata.
* <<beans-java, Java-based configuration>>: define beans external to your application
* xref:core/beans/java.adoc[Java-based configuration]: define beans external to your application
classes by using Java rather than XML files. To use these features, see the
{api-spring-framework}/context/annotation/Configuration.html[`@Configuration`],
{api-spring-framework}/context/annotation/Bean.html[`@Bean`],
@ -107,7 +107,7 @@ class name.
The value of the `id` attribute can be used to refer to collaborating objects. The XML
for referring to collaborating objects is not shown in this example. See
<<beans-dependencies,Dependencies>> for more information.
xref:core/beans/dependencies.adoc[Dependencies] for more information.
@ -133,9 +133,9 @@ as the local file system, the Java `CLASSPATH`, and so on.
[NOTE]
====
After you learn about Spring's IoC container, you may want to know more about Spring's
`Resource` abstraction (as described in <<resources>>), which provides a convenient
`Resource` abstraction (as described in xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources]), which provides a convenient
mechanism for reading an InputStream from locations defined in a URI syntax. In particular,
`Resource` paths are used to construct applications contexts, as described in <<resources-app-ctx>>.
`Resource` paths are used to construct applications contexts, as described in xref:core/resources.adoc#resources-app-ctx[Application Contexts and Resource Paths].
====
The following example shows the service layer objects `(services.xml)` configuration file:
@ -191,7 +191,7 @@ on the JPA Object-Relational Mapping standard). The `property name` element refe
name of the JavaBean property, and the `ref` element refers to the name of another bean
definition. This linkage between `id` and `ref` elements expresses the dependency between
collaborating objects. For details of configuring an object's dependencies, see
<<beans-dependencies,Dependencies>>.
xref:core/beans/dependencies.adoc[Dependencies].
[[beans-factory-xml-import]]
@ -202,7 +202,7 @@ XML configuration file represents a logical layer or module in your architecture
You can use the application context constructor to load bean definitions from all these
XML fragments. This constructor takes multiple `Resource` locations, as was shown in the
<<beans-factory-instantiation, previous section>>. Alternatively, use one or more
xref:core/beans/basics.adoc#beans-factory-instantiation[previous section]. Alternatively, use one or more
occurrences of the `<import/>` element to load bean definitions from another file or
files. The following example shows how to do so:

2
framework-docs/modules/ROOT/pages/core/beans/beanfactory.adoc
View File

@ -43,7 +43,7 @@ by convention (that is, by bean name or by bean type -- in particular, post-proc
while a plain `DefaultListableBeanFactory` is agnostic about any special beans.
For many extended container features, such as annotation processing and AOP proxying,
the <<beans-factory-extension-bpp, `BeanPostProcessor` extension point>> is essential.
the xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[`BeanPostProcessor` extension point] is essential.
If you use only a plain `DefaultListableBeanFactory`, such post-processors do not
get detected and activated by default. This situation could be confusing, because
nothing is actually wrong with your bean configuration. Rather, in such a scenario,

14
framework-docs/modules/ROOT/pages/core/beans/classpath-scanning.adoc
View File

@ -3,7 +3,7 @@
Most examples in this chapter use XML to specify the configuration metadata that produces
each `BeanDefinition` within the Spring container. The previous section
(<<beans-annotation-config>>) demonstrates how to provide a lot of the configuration
(xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration]) demonstrates how to provide a lot of the configuration
metadata through source-level annotations. Even in those examples, however, the "base"
bean definitions are explicitly defined in the XML file, while the annotations drive only
the dependency injection. This section describes an option for implicitly detecting the
@ -29,7 +29,7 @@ use these features.
The `@Repository` annotation is a marker for any class that fulfills the role or
stereotype of a repository (also known as Data Access Object or DAO). Among the uses
of this marker is the automatic translation of exceptions, as described in
<<data-access.adoc#orm-exception-translation, Exception Translation>>.
xref:data-access/orm/general.adoc#orm-exception-translation[Exception Translation].
Spring provides further stereotype annotations: `@Component`, `@Service`, and
`@Controller`. `@Component` is a generic stereotype for any Spring-managed component.
@ -52,7 +52,7 @@ supported as a marker for automatic exception translation in your persistence la
Many of the annotations provided by Spring can be used as meta-annotations in your
own code. A meta-annotation is an annotation that can be applied to another annotation.
For example, the `@Service` annotation mentioned <<beans-stereotype-annotations, earlier>>
For example, the `@Service` annotation mentioned xref:core/beans/classpath-scanning.adoc#beans-stereotype-annotations[earlier]
is meta-annotated with `@Component`, as the following example shows:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
@ -723,7 +723,7 @@ definitions, there is no notion of bean definition inheritance, and inheritance
hierarchies at the class level are irrelevant for metadata purposes.
For details on web-specific scopes such as "`request`" or "`session`" in a Spring context,
see <<beans-factory-scopes-other>>. As with the pre-built annotations for those scopes,
see xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other[Request, Session, Application, and WebSocket Scopes]. As with the pre-built annotations for those scopes,
you may also compose your own scoping annotations by using Spring's meta-annotation
approach: for example, a custom annotation meta-annotated with `@Scope("prototype")`,
possibly also declaring a custom scoped-proxy mode.
@ -762,7 +762,7 @@ an annotation and a bean definition shows:
----
When using certain non-singleton scopes, it may be necessary to generate proxies for the
scoped objects. The reasoning is described in <<beans-factory-scopes-other-injection>>.
scoped objects. The reasoning is described in xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[Scoped Beans as Dependencies].
For this purpose, a scoped-proxy attribute is available on the component-scan
element. The three possible values are: `no`, `interfaces`, and `targetClass`. For example,
the following configuration results in standard JDK dynamic proxies:
@ -798,7 +798,7 @@ the following configuration results in standard JDK dynamic proxies:
[[beans-scanning-qualifiers]]
== Providing Qualifier Metadata with Annotations
The `@Qualifier` annotation is discussed in <<beans-autowired-annotation-qualifiers>>.
The `@Qualifier` annotation is discussed in xref:core/beans/annotation-config/autowired-qualifiers.adoc[Fine-tuning Annotation-based Autowiring with Qualifiers].
The examples in that section demonstrate the use of the `@Qualifier` annotation and
custom qualifier annotations to provide fine-grained control when you resolve autowire
candidates. Because those examples were based on XML bean definitions, the qualifier
@ -930,7 +930,7 @@ on the classpath. If an index is partially available for some libraries (or use
but could not be built for the whole application, you can fall back to a regular classpath
arrangement (as though no index were present at all) by setting `spring.index.ignore` to
`true`, either as a JVM system property or via the
<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism.
xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism.

14
framework-docs/modules/ROOT/pages/core/beans/context-introduction.adoc
View File

@ -1,7 +1,7 @@
[[context-introduction]]
= Additional Capabilities of the `ApplicationContext`
As discussed in the <<beans, chapter introduction>>, the `org.springframework.beans.factory`
As discussed in the xref:web/webmvc-view/mvc-xslt.adoc#mvc-view-xslt-beandefs[chapter introduction], the `org.springframework.beans.factory`
package provides basic functionality for managing and manipulating beans, including in a
programmatic way. The `org.springframework.context` package adds the
{api-spring-framework}/context/ApplicationContext.html[`ApplicationContext`]
@ -266,7 +266,7 @@ class and the `ApplicationListener` interface. If a bean that implements the
Essentially, this is the standard Observer design pattern.
TIP: As of Spring 4.2, the event infrastructure has been significantly improved and offers
an <<context-functionality-events-annotation, annotation-based model>> as well as the
an xref:core/beans/context-introduction.adoc#context-functionality-events-annotation[annotation-based model] as well as the
ability to publish any arbitrary event (that is, an object that does not necessarily
extend from `ApplicationEvent`). When such an object is published, we wrap it in an
event for you.
@ -555,7 +555,7 @@ following example shows how to do so:
----
It is also possible to add additional runtime filtering by using the `condition` attribute
of the annotation that defines a <<expressions, `SpEL` expression>>, which should match
of the annotation that defines a xref:core/expressions.adoc[`SpEL` expression], which should match
to actually invoke the method for a particular event.
The following example shows how our notifier can be rewritten to be invoked only if the
@ -631,7 +631,7 @@ method signature to return the event that should be published, as the following
----
NOTE: This feature is not supported for
<<context-functionality-events-async, asynchronous listeners>>.
xref:core/beans/context-introduction.adoc#context-functionality-events-async[asynchronous listeners].
The `handleBlockedListEvent()` method publishes a new `ListUpdateEvent` for every
`BlockedListEvent` that it handles. If you need to publish several events, you can return
@ -642,7 +642,7 @@ a `Collection` or an array of events instead.
=== Asynchronous Listeners
If you want a particular listener to process events asynchronously, you can reuse the
<<integration.adoc#scheduling-annotation-support-async, regular `@Async` support>>.
xref:integration/scheduling.adoc#scheduling-annotation-support-async[regular `@Async` support].
The following example shows how to do so:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
@ -771,7 +771,7 @@ an event.
== Convenient Access to Low-level Resources
For optimal usage and understanding of application contexts, you should familiarize
yourself with Spring's `Resource` abstraction, as described in <<resources>>.
yourself with Spring's `Resource` abstraction, as described in xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources].
An application context is a `ResourceLoader`, which can be used to load `Resource` objects.
A `Resource` is essentially a more feature rich version of the JDK `java.net.URL` class.
@ -847,7 +847,7 @@ Here is an example of instrumentation in the `AnnotationConfigApplicationContext
The application context is already instrumented with multiple steps.
Once recorded, these startup steps can be collected, displayed and analyzed with specific tools.
For a complete list of existing startup steps, you can check out the
<<core.appendix.application-startup-steps, dedicated appendix section>>.
xref:core/appendix/application-startup-steps.adoc[dedicated appendix section].
The default `ApplicationStartup` implementation is a no-op variant, for minimal overhead.
This means no metrics will be collected during application startup by default.

4
framework-docs/modules/ROOT/pages/core/beans/context-load-time-weaver.adoc
View File

@ -35,11 +35,11 @@ Alternatively, for XML configuration, you can use the `context:load-time-weaver`
Once configured for the `ApplicationContext`, any bean within that `ApplicationContext`
may implement `LoadTimeWeaverAware`, thereby receiving a reference to the load-time
weaver instance. This is particularly useful in combination with
<<data-access.adoc#orm-jpa, Spring's JPA support>> where load-time weaving may be
xref:data-access/orm/jpa.adoc[Spring's JPA support] where load-time weaving may be
necessary for JPA class transformation.
Consult the
{api-spring-framework}/orm/jpa/LocalContainerEntityManagerFactoryBean.html[`LocalContainerEntityManagerFactoryBean`]
javadoc for more detail. For more on AspectJ load-time weaving, see <<aop-aj-ltw>>.
javadoc for more detail. For more on AspectJ load-time weaving, see xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework].

44
framework-docs/modules/ROOT/pages/core/beans/definition.adoc
View File

@ -27,31 +27,31 @@ The following table describes these properties:
| Property| Explained in...
| Class
| <<beans-factory-class>>
| xref:core/beans/definition.adoc#beans-factory-class[Instantiating Beans]
| Name
| <<beans-beanname>>
| xref:core/beans/definition.adoc#beans-beanname[Naming Beans]
| Scope
| <<beans-factory-scopes>>
| xref:core/beans/factory-scopes.adoc[Bean Scopes]
| Constructor arguments
| <<beans-factory-collaborators>>
| xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection]
| Properties
| <<beans-factory-collaborators>>
| xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection]
| Autowiring mode
| <<beans-factory-autowire>>
| xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators]
| Lazy initialization mode
| <<beans-factory-lazy-init>>
| xref:core/beans/dependencies/factory-lazy-init.adoc[Lazy-initialized Beans]
| Initialization method
| <<beans-factory-lifecycle-initializingbean>>
| xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[Initialization Callbacks]
| Destruction method
| <<beans-factory-lifecycle-disposablebean>>
| xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[Destruction Callbacks]
|===
In addition to bean definitions that contain information on how to create a specific
@ -95,8 +95,8 @@ You are not required to supply a `name` or an `id` for a bean. If you do not sup
`name` or `id` explicitly, the container generates a unique name for that bean. However,
if you want to refer to that bean by name, through the use of the `ref` element or a
Service Locator style lookup, you must provide a name.
Motivations for not supplying a name are related to using <<beans-inner-beans,inner
beans>> and <<beans-factory-autowire,autowiring collaborators>>.
Motivations for not supplying a name are related to using xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-inner-beans[inner beans]
and xref:core/beans/dependencies/factory-autowire.adoc[autowiring collaborators].
.Bean Naming Conventions
****
@ -163,7 +163,7 @@ creating a namespace), yet they refer to the same bean.
.Java-configuration
****
If you use Java Configuration, the `@Bean` annotation can be used to provide aliases.
See <<beans-java-bean-annotation>> for details.
See xref:core/beans/java/bean-annotation.adoc[Using the `@Bean` Annotation] for details.
****
@ -179,7 +179,7 @@ If you use XML-based configuration metadata, you specify the type (or class) of
that is to be instantiated in the `class` attribute of the `<bean/>` element. This
`class` attribute (which, internally, is a `Class` property on a `BeanDefinition`
instance) is usually mandatory. (For exceptions, see
<<beans-factory-class-instance-factory-method>> and <<beans-child-bean-definitions>>.)
xref:core/beans/definition.adoc#beans-factory-class-instance-factory-method[Instantiation by Using an Instance Factory Method] and xref:core/beans/child-bean-definitions.adoc[Bean Definition Inheritance].)
You can use the `Class` property in one of two ways:
* Typically, to specify the bean class to be constructed in the case where the container
@ -232,7 +232,7 @@ With XML-based configuration metadata you can specify your bean class as follows
For details about the mechanism for supplying arguments to the constructor (if required)
and setting object instance properties after the object is constructed, see
<<beans-factory-collaborators,Injecting Dependencies>>.
xref:core/beans/dependencies/factory-collaborators.adoc[Injecting Dependencies].
[[beans-factory-class-static-factory-method]]
@ -286,14 +286,14 @@ The following example shows a class that would work with the preceding bean defi
For details about the mechanism for supplying (optional) arguments to the factory method
and setting object instance properties after the object is returned from the factory,
see <<beans-factory-properties-detailed,Dependencies and Configuration in Detail>>.
see xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail].
[[beans-factory-class-instance-factory-method]]
=== Instantiation by Using an Instance Factory Method
Similar to instantiation through a <<beans-factory-class-static-factory-method,static
factory method>>, instantiation with an instance factory method invokes a non-static
Similar to instantiation through a xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[static factory method]
, instantiation with an instance factory method invokes a non-static
method of an existing bean from the container to create a new bean. To use this
mechanism, leave the `class` attribute empty and, in the `factory-bean` attribute,
specify the name of a bean in the current (or parent or ancestor) container that contains
@ -398,15 +398,15 @@ The following example shows the corresponding class:
----
This approach shows that the factory bean itself can be managed and configured through
dependency injection (DI). See <<beans-factory-properties-detailed,Dependencies and
Configuration in Detail>>.
dependency injection (DI). See xref:core/beans/dependencies/factory-properties-detailed.adoc[Dependencies and Configuration in Detail]
.
NOTE: In Spring documentation, "factory bean" refers to a bean that is configured in the
Spring container and that creates objects through an
<<beans-factory-class-instance-factory-method,instance>> or
<<beans-factory-class-static-factory-method,static>> factory method. By contrast,
xref:core/beans/definition.adoc#beans-factory-class-instance-factory-method[instance] or
xref:core/beans/definition.adoc#beans-factory-class-static-factory-method[static] factory method. By contrast,
`FactoryBean` (notice the capitalization) refers to a Spring-specific
<<beans-factory-extension-factorybean, `FactoryBean`>> implementation class.
xref:core/beans/factory-extension.adoc#beans-factory-extension-factorybean[`FactoryBean`] implementation class.
[[beans-factory-type-determination]]

12
framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-autowire.adoc
View File

@ -8,7 +8,7 @@ advantages:
* Autowiring can significantly reduce the need to specify properties or constructor
arguments. (Other mechanisms such as a bean template
<<beans-child-bean-definitions,discussed elsewhere in this chapter>> are also valuable
xref:core/beans/child-bean-definitions.adoc[discussed elsewhere in this chapter] are also valuable
in this regard.)
* Autowiring can update a configuration as your objects evolve. For example, if you need
to add a dependency to a class, that dependency can be satisfied automatically without
@ -16,7 +16,7 @@ advantages:
during development, without negating the option of switching to explicit wiring when
the code base becomes more stable.
When using XML-based configuration metadata (see <<beans-factory-collaborators>>), you
When using XML-based configuration metadata (see xref:core/beans/dependencies/factory-collaborators.adoc[Dependency Injection]), you
can specify the autowire mode for a bean definition with the `autowire` attribute of the
`<bean/>` element. The autowiring functionality has four modes. You specify autowiring
per bean and can thus choose which ones to autowire. The following table describes the
@ -89,11 +89,11 @@ In the latter scenario, you have several options:
* Abandon autowiring in favor of explicit wiring.
* Avoid autowiring for a bean definition by setting its `autowire-candidate` attributes
to `false`, as described in the <<beans-factory-autowire-candidate, next section>>.
to `false`, as described in the xref:core/beans/dependencies/factory-autowire.adoc#beans-factory-autowire-candidate[next section].
* Designate a single bean definition as the primary candidate by setting the
`primary` attribute of its `<bean/>` element to `true`.
* Implement the more fine-grained control available with annotation-based configuration,
as described in <<beans-annotation-config>>.
as described in xref:core/beans/annotation-config.adoc[Annotation-based Container Configuration].
@ -103,8 +103,8 @@ In the latter scenario, you have several options:
On a per-bean basis, you can exclude a bean from autowiring. In Spring's XML format, set
the `autowire-candidate` attribute of the `<bean/>` element to `false`. The container
makes that specific bean definition unavailable to the autowiring infrastructure
(including annotation style configurations such as <<beans-autowired-annotation,
`@Autowired`>>).
(including annotation style configurations such as xref:core/beans/annotation-config/autowired.adoc[`@Autowired`]
).
NOTE: The `autowire-candidate` attribute is designed to only affect type-based autowiring.
It does not affect explicit references by name, which get resolved even if the

14
framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-collaborators.adoc
View File

@ -16,8 +16,8 @@ not know the location or class of the dependencies. As a result, your classes be
to test, particularly when the dependencies are on interfaces or abstract base classes,
which allow for stub or mock implementations to be used in unit tests.
DI exists in two major variants: <<beans-constructor-injection,Constructor-based
dependency injection>> and <<beans-setter-injection,Setter-based dependency injection>>.
DI exists in two major variants: xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[Constructor-based dependency injection]
and xref:core/beans/dependencies/factory-collaborators.adoc#beans-setter-injection[Setter-based dependency injection].
[[beans-constructor-injection]]
@ -279,7 +279,7 @@ load an entire Spring IoC container instance.
****
Since you can mix constructor-based and setter-based DI, it is a good rule of thumb to
use constructors for mandatory dependencies and setter methods or configuration methods
for optional dependencies. Note that use of the <<beans-autowired-annotation, @Autowired>>
for optional dependencies. Note that use of the xref:core/beans/annotation-config/autowired.adoc[@Autowired]
annotation on a setter method can be used to make the property be a required dependency;
however, constructor injection with programmatic validation of arguments is preferable.
@ -294,7 +294,7 @@ Setter injection should primarily only be used for optional dependencies that ca
assigned reasonable default values within the class. Otherwise, not-null checks must be
performed everywhere the code uses the dependency. One benefit of setter injection is that
setter methods make objects of that class amenable to reconfiguration or re-injection
later. Management through <<integration.adoc#jmx,JMX MBeans>> is therefore a compelling
later. Management through xref:integration/jmx.adoc[JMX MBeans] is therefore a compelling
use case for setter injection.
Use the DI style that makes the most sense for a particular class. Sometimes, when dealing
@ -326,7 +326,7 @@ The container performs bean dependency resolution as follows:
The Spring container validates the configuration of each bean as the container is created.
However, the bean properties themselves are not set until the bean is actually created.
Beans that are singleton-scoped and set to be pre-instantiated (the default) are created
when the container is created. Scopes are defined in <<beans-factory-scopes>>. Otherwise,
when the container is created. Scopes are defined in xref:core/beans/factory-scopes.adoc[Bean Scopes]. Otherwise,
the bean is created only when it is requested. Creation of a bean potentially causes a
graph of beans to be created, as the bean's dependencies and its dependencies'
dependencies (and so on) are created and assigned. Note that resolution mismatches among
@ -373,8 +373,8 @@ to being injected into the dependent bean. This means that, if bean A has a depe
bean B, the Spring IoC container completely configures bean B prior to invoking the
setter method on bean A. In other words, the bean is instantiated (if it is not a
pre-instantiated singleton), its dependencies are set, and the relevant lifecycle
methods (such as a <<beans-factory-lifecycle-initializingbean, configured init method>>
or the <<beans-factory-lifecycle-initializingbean,InitializingBean callback method>>)
methods (such as a xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[configured init method]
or the xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[InitializingBean callback method])
are invoked.

2
framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-dependson.adoc
View File

@ -31,7 +31,7 @@ delimiters):
----
NOTE: The `depends-on` attribute can specify both an initialization-time dependency and,
in the case of <<beans-factory-scopes-singleton,singleton>> beans only, a corresponding
in the case of xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton] beans only, a corresponding
destruction-time dependency. Dependent beans that define a `depends-on` relationship
with a given bean are destroyed first, prior to the given bean itself being destroyed.
Thus, `depends-on` can also control shutdown order.

2
framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-lazy-init.adoc
View File

@ -2,7 +2,7 @@
= Lazy-initialized Beans
By default, `ApplicationContext` implementations eagerly create and configure all
<<beans-factory-scopes-singleton,singleton>> beans as part of the initialization
xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton] beans as part of the initialization
process. Generally, this pre-instantiation is desirable, because errors in the
configuration or surrounding environment are discovered immediately, as opposed to hours
or even days later. When this behavior is not desirable, you can prevent

14
framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-method-injection.adoc
View File

@ -2,7 +2,7 @@
= Method Injection
In most application scenarios, most beans in the container are
<<beans-factory-scopes-singleton,singletons>>. When a singleton bean needs to
xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singletons]. When a singleton bean needs to
collaborate with another singleton bean or a non-singleton bean needs to collaborate
with another non-singleton bean, you typically handle the dependency by defining one
bean as a property of the other. A problem arises when the bean lifecycles are
@ -11,9 +11,9 @@ perhaps on each method invocation on A. The container creates the singleton bean
once, and thus only gets one opportunity to set the properties. The container cannot
provide bean A with a new instance of bean B every time one is needed.
A solution is to forego some inversion of control. You can <<beans-factory-aware,make
bean A aware of the container>> by implementing the `ApplicationContextAware` interface,
and by <<beans-factory-client,making a `getBean("B")` call to the container>> ask for (a
A solution is to forego some inversion of control. You can xref:core/beans/factory-nature.adoc#beans-factory-aware[make bean A aware of the container]
by implementing the `ApplicationContextAware` interface,
and by xref:core/beans/basics.adoc#beans-factory-client[making a `getBean("B")` call to the container] ask for (a
typically new) bean B instance every time bean A needs it. The following example
shows this approach:
@ -104,7 +104,7 @@ https://spring.io/blog/2004/08/06/method-injection/[this blog entry].
Lookup method injection is the ability of the container to override methods on
container-managed beans and return the lookup result for another named bean in the
container. The lookup typically involves a prototype bean, as in the scenario described
in <<beans-factory-method-injection, the preceding section>>. The Spring Framework
in xref:core/beans/dependencies/factory-method-injection.adoc[the preceding section]. The Spring Framework
implements this method injection by using bytecode generation from the CGLIB library to
dynamically generate a subclass that overrides the method.
@ -198,7 +198,7 @@ the original class. Consider the following example:
The bean identified as `commandManager` calls its own `createCommand()` method
whenever it needs a new instance of the `myCommand` bean. You must be careful to deploy
the `myCommand` bean as a prototype if that is actually what is needed. If it is
a <<beans-factory-scopes-singleton,singleton>>, the same instance of the `myCommand`
a xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton], the same instance of the `myCommand`
bean is returned each time.
Alternatively, within the annotation-based component model, you can declare a lookup
@ -277,7 +277,7 @@ apply to explicitly registered or explicitly imported bean classes.
[TIP]
====
Another way of accessing differently scoped target beans is an `ObjectFactory`/
`Provider` injection point. See <<beans-factory-scopes-other-injection>>.
`Provider` injection point. See xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[Scoped Beans as Dependencies].
You may also find the `ServiceLocatorFactoryBean` (in the
`org.springframework.beans.factory.config` package) to be useful.

20
framework-docs/modules/ROOT/pages/core/beans/dependencies/factory-properties-detailed.adoc
View File

@ -1,7 +1,7 @@
[[beans-factory-properties-detailed]]
= Dependencies and Configuration in Detail
As mentioned in the <<beans-factory-collaborators, previous section>>, you can define bean
As mentioned in the xref:core/beans/dependencies/factory-collaborators.adoc[previous section], you can define bean
properties and constructor arguments as references to other managed beans (collaborators)
or as values defined inline. Spring's XML-based configuration metadata supports
sub-element types within its `<property/>` and `<constructor-arg/>` elements for this
@ -13,7 +13,7 @@ purpose.
The `value` attribute of the `<property/>` element specifies a property or constructor
argument as a human-readable string representation. Spring's
<<core-convert-ConversionService-API, conversion service>> is used to convert these
xref:core/validation/convert.adoc#core-convert-ConversionService-API[conversion service] is used to convert these
values from a `String` to the actual type of the property or argument.
The following example shows various values being set:
@ -28,7 +28,7 @@ The following example shows various values being set:
</bean>
----
The following example uses the <<beans-p-namespace,p-namespace>> for even more succinct
The following example uses the xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-p-namespace[p-namespace] for even more succinct
XML configuration:
[source,xml,indent=0,subs="verbatim,quotes"]
@ -112,7 +112,7 @@ container validate at deployment time that the referenced, named bean actually
exists. In the second variation, no validation is performed on the value that is passed
to the `targetName` property of the `client` bean. Typos are only discovered (with most
likely fatal results) when the `client` bean is actually instantiated. If the `client`
bean is a <<beans-factory-scopes,prototype>> bean, this typo and the resulting exception
bean is a xref:core/beans/factory-scopes.adoc[prototype] bean, this typo and the resulting exception
may only be discovered long after the container is deployed.
NOTE: The `local` attribute on the `idref` element is no longer supported in the 4.0 beans
@ -120,7 +120,7 @@ XSD, since it does not provide value over a regular `bean` reference any more. C
your existing `idref local` references to `idref bean` when upgrading to the 4.0 schema.
A common place (at least in versions earlier than Spring 2.0) where the `<idref/>` element
brings value is in the configuration of <<aop-pfb-1,AOP interceptors>> in a
brings value is in the configuration of xref:core/aop-api/pfb.adoc#aop-pfb-1[AOP interceptors] in a
`ProxyFactoryBean` bean definition. Using `<idref/>` elements when you specify the
interceptor names prevents you from misspelling an interceptor ID.
@ -277,7 +277,7 @@ collection elements overriding values specified in the parent collection.
This section on merging discusses the parent-child bean mechanism. Readers unfamiliar
with parent and child bean definitions may wish to read the
<<beans-child-bean-definitions,relevant section>> before continuing.
xref:core/beans/child-bean-definitions.adoc[relevant section] before continuing.
The following example demonstrates collection merging:
@ -451,7 +451,7 @@ The preceding configuration is equivalent to the following Java code:
The p-namespace lets you use the `bean` element's attributes (instead of nested
`<property/>` elements) to describe your property values collaborating beans, or both.
Spring supports extensible configuration formats <<core.adoc#core.appendix.xsd-schemas,with namespaces>>,
Spring supports extensible configuration formats xref:core/appendix/xsd-schemas.adoc[with namespaces],
which are based on an XML Schema definition. The `beans` configuration format discussed in
this chapter is defined in an XML Schema document. However, the p-namespace is not defined
in an XSD file and exists only in the core of Spring.
@ -526,12 +526,12 @@ three approaches at the same time.
[[beans-c-namespace]]
== XML Shortcut with the c-namespace
Similar to the <<beans-p-namespace>>, the c-namespace, introduced in Spring
Similar to the xref:core/beans/dependencies/factory-properties-detailed.adoc#beans-p-namespace[XML Shortcut with the p-namespace], the c-namespace, introduced in Spring
3.1, allows inlined attributes for configuring the constructor arguments rather
then nested `constructor-arg` elements.
The following example uses the `c:` namespace to do the same thing as the from
<<beans-constructor-injection>>:
xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[Constructor-based Dependency Injection]:
[source,xml,indent=0,subs="verbatim,quotes"]
----
@ -580,7 +580,7 @@ A corresponding index notation is also available for `<constructor-arg>` element
not commonly used since the plain order of declaration is usually sufficient there.
In practice, the constructor resolution
<<beans-factory-ctor-arguments-resolution,mechanism>> is quite efficient in matching
xref:core/beans/dependencies/factory-collaborators.adoc#beans-factory-ctor-arguments-resolution[mechanism] is quite efficient in matching
arguments, so unless you really need to, we recommend using the name notation
throughout your configuration.

12
framework-docs/modules/ROOT/pages/core/beans/environment.adoc
View File

@ -3,8 +3,8 @@
The {api-spring-framework}/core/env/Environment.html[`Environment`] interface
is an abstraction integrated in the container that models two key
aspects of the application environment: <<beans-definition-profiles, profiles>>
and <<beans-property-source-abstraction, properties>>.
aspects of the application environment: xref:core/beans/environment.adoc#beans-definition-profiles[profiles]
and xref:core/beans/environment.adoc#beans-property-source-abstraction[properties].
A profile is a named, logical group of bean definitions to be registered with the
container only if the given profile is active. Beans may be assigned to a profile
@ -200,7 +200,7 @@ NOTE: You cannot mix the `&` and `|` operators without using parentheses. For ex
`production & us-east | eu-central` is not a valid expression. It must be expressed as
`production & (us-east | eu-central)`.
You can use `@Profile` as a <<beans-meta-annotations, meta-annotation>> for the purpose
You can use `@Profile` as a xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotation] for the purpose
of creating a custom composed annotation. The following example defines a custom
`@Production` annotation that you can use as a drop-in replacement for
`@Profile("production")`:
@ -437,10 +437,10 @@ it programmatically against the `Environment` API which is available through an
In addition, you can also declaratively activate profiles through the
`spring.profiles.active` property, which may be specified through system environment
variables, JVM system properties, servlet context parameters in `web.xml`, or even as an
entry in JNDI (see <<beans-property-source-abstraction>>). In integration tests, active
entry in JNDI (see xref:core/beans/environment.adoc#beans-property-source-abstraction[`PropertySource` Abstraction]). In integration tests, active
profiles can be declared by using the `@ActiveProfiles` annotation in the `spring-test`
module (see <<testing.adoc#testcontext-ctx-management-env-profiles,
context configuration with environment profiles>>).
module (see xref:testing/testcontext-framework/ctx-management/env-profiles.adoc[context configuration with environment profiles]
).
Note that profiles are not an "`either-or`" proposition. You can activate multiple
profiles at once. Programmatically, you can provide multiple profile names to the

10
framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc
View File

@ -24,8 +24,8 @@ interface. If you write your own `BeanPostProcessor`, you should consider implem
the `Ordered` interface, too. For further details, see the javadoc of the
{api-spring-framework}/beans/factory/config/BeanPostProcessor.html[`BeanPostProcessor`]
and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces. See also the note
on <<beans-factory-programmatically-registering-beanpostprocessors, programmatic
registration of `BeanPostProcessor` instances>>.
on xref:core/beans/factory-extension.adoc#beans-factory-programmatically-registering-beanpostprocessors[programmatic registration of `BeanPostProcessor` instances]
.
[NOTE]
====
@ -41,7 +41,7 @@ another container, even if both containers are part of the same hierarchy.
To change the actual bean definition (that is, the blueprint that defines the bean),
you instead need to use a `BeanFactoryPostProcessor`, as described in
<<beans-factory-extension-factory-postprocessors>>.
xref:core/beans/factory-extension.adoc#beans-factory-extension-factory-postprocessors[Customizing Configuration Metadata with a `BeanFactoryPostProcessor`].
====
The `org.springframework.beans.factory.config.BeanPostProcessor` interface consists of
@ -192,7 +192,7 @@ Notice how the `InstantiationTracingBeanPostProcessor` is merely defined. It doe
even have a name, and, because it is a bean, it can be dependency-injected as you would any
other bean. (The preceding configuration also defines a bean that is backed by a Groovy
script. The Spring dynamic language support is detailed in the chapter entitled
<<languages.adoc#dynamic-language, Dynamic Language Support>>.)
xref:languages/dynamic.adoc[Dynamic Language Support].)
The following Java application runs the preceding code and configuration:
@ -268,7 +268,7 @@ and {api-spring-framework}/core/Ordered.html[`Ordered`] interfaces for more deta
====
If you want to change the actual bean instances (that is, the objects that are created
from the configuration metadata), then you instead need to use a `BeanPostProcessor`
(described earlier in <<beans-factory-extension-bpp>>). While it is technically possible
(described earlier in xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[Customizing Beans by Using a `BeanPostProcessor`]). While it is technically possible
to work with bean instances within a `BeanFactoryPostProcessor` (for example, by using
`BeanFactory.getBean()`), doing so causes premature bean instantiation, violating the
standard container lifecycle. This may cause negative side effects, such as bypassing

64
framework-docs/modules/ROOT/pages/core/beans/factory-nature.adoc
View File

@ -4,9 +4,9 @@
The Spring Framework provides a number of interfaces you can use to customize the nature
of a bean. This section groups them as follows:
* <<beans-factory-lifecycle>>
* <<beans-factory-aware>>
* <<aware-list>>
* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[Lifecycle Callbacks]
* xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`]
* xref:core/beans/factory-nature.adoc#aware-list[Other `Aware` Interfaces]
@ -23,7 +23,7 @@ perform certain actions upon initialization and destruction of your beans.
The JSR-250 `@PostConstruct` and `@PreDestroy` annotations are generally considered best
practice for receiving lifecycle callbacks in a modern Spring application. Using these
annotations means that your beans are not coupled to Spring-specific interfaces.
For details, see <<beans-postconstruct-and-predestroy-annotations>>.
For details, see xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[Using `@PostConstruct` and `@PreDestroy`].
If you do not want to use the JSR-250 annotations but you still want to remove
coupling, consider `init-method` and `destroy-method` bean definition metadata.
@ -33,7 +33,7 @@ Internally, the Spring Framework uses `BeanPostProcessor` implementations to pro
callback interfaces it can find and call the appropriate methods. If you need custom
features or other lifecycle behavior Spring does not by default offer, you can
implement a `BeanPostProcessor` yourself. For more information, see
<<beans-factory-extension>>.
xref:core/beans/factory-extension.adoc[Container Extension Points].
In addition to the initialization and destruction callbacks, Spring-managed objects may
also implement the `Lifecycle` interface so that those objects can participate in the
@ -56,11 +56,11 @@ bean. The `InitializingBean` interface specifies a single method:
We recommend that you do not use the `InitializingBean` interface, because it
unnecessarily couples the code to Spring. Alternatively, we suggest using
the <<beans-postconstruct-and-predestroy-annotations, `@PostConstruct`>> annotation or
the xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PostConstruct`] annotation or
specifying a POJO initialization method. In the case of XML-based configuration metadata,
you can use the `init-method` attribute to specify the name of the method that has a void
no-argument signature. With Java configuration, you can use the `initMethod` attribute of
`@Bean`. See <<beans-java-lifecycle-callbacks>>. Consider the following example:
`@Bean`. See xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receiving Lifecycle Callbacks]. Consider the following example:
[source,xml,indent=0,subs="verbatim,quotes"]
----
@ -135,11 +135,11 @@ bean get a callback when the container that contains it is destroyed. The
We recommend that you do not use the `DisposableBean` callback interface, because it
unnecessarily couples the code to Spring. Alternatively, we suggest using
the <<beans-postconstruct-and-predestroy-annotations, `@PreDestroy`>> annotation or
the xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PreDestroy`] annotation or
specifying a generic method that is supported by bean definitions. With XML-based
configuration metadata, you can use the `destroy-method` attribute on the `<bean/>`.
With Java configuration, you can use the `destroyMethod` attribute of `@Bean`. See
<<beans-java-lifecycle-callbacks>>. Consider the following definition:
xref:core/beans/java/bean-annotation.adoc#beans-java-lifecycle-callbacks[Receiving Lifecycle Callbacks]. Consider the following definition:
[source,xml,indent=0,subs="verbatim,quotes"]
----
@ -204,7 +204,7 @@ TIP: You can assign the `destroy-method` attribute of a `<bean>` element a speci
`java.lang.AutoCloseable` or `java.io.Closeable` would therefore match.) You can also set
this special `(inferred)` value on the `default-destroy-method` attribute of a
`<beans>` element to apply this behavior to an entire set of beans (see
<<beans-factory-lifecycle-default-init-destroy-methods>>). Note that this is the
xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-default-init-destroy-methods[Default Initialization and Destroy Methods]). Note that this is the
default behavior with Java configuration.
[[beans-factory-lifecycle-default-init-destroy-methods]]
@ -221,8 +221,8 @@ callback method names on every bean. This means that you, as an application
developer, can write your application classes and use an initialization callback called
`init()`, without having to configure an `init-method="init"` attribute with each bean
definition. The Spring IoC container calls that method when the bean is created (and in
accordance with the standard lifecycle callback contract <<beans-factory-lifecycle,
described previously>>). This feature also enforces a consistent naming convention for
accordance with the standard lifecycle callback contract xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[described previously]
). This feature also enforces a consistent naming convention for
initialization and destroy method callbacks.
Suppose that your initialization callback methods are named `init()` and your destroy
@ -308,18 +308,18 @@ interacts directly with the raw target bean.
As of Spring 2.5, you have three options for controlling bean lifecycle behavior:
* The <<beans-factory-lifecycle-initializingbean, `InitializingBean`>> and
<<beans-factory-lifecycle-disposablebean, `DisposableBean`>> callback interfaces
* The xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[`InitializingBean`] and
xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[`DisposableBean`] callback interfaces
* Custom `init()` and `destroy()` methods
* The <<beans-postconstruct-and-predestroy-annotations, `@PostConstruct` and `@PreDestroy`
annotations>>. You can combine these mechanisms to control a given bean.
* The xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[`@PostConstruct` and `@PreDestroy` 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 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 run once, as explained in the
<<beans-factory-lifecycle-default-init-destroy-methods, preceding section>>.
xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-default-init-destroy-methods[preceding section].
Multiple lifecycle mechanisms configured for the same bean, with different
initialization methods, are called as follows:
@ -542,18 +542,18 @@ it couples the code to Spring and does not follow the Inversion of Control style
where collaborators are provided to beans as properties. Other methods of the
`ApplicationContext` provide access to file resources, publishing application events,
and accessing a `MessageSource`. These additional features are described in
<<context-introduction>>.
xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`].
Autowiring is another alternative to obtain a reference to the
`ApplicationContext`. The _traditional_ `constructor` and `byType` autowiring modes
(as described in <<beans-factory-autowire>>) can provide a dependency of type
(as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators]) can provide a dependency of type
`ApplicationContext` for a constructor argument or a setter method parameter,
respectively. For more flexibility, including the ability to autowire fields and
multiple parameter methods, use the annotation-based autowiring features. If you do,
the `ApplicationContext` is autowired into a field, constructor argument, or method
parameter that expects the `ApplicationContext` type if the field, constructor, or
method in question carries the `@Autowired` annotation. For more information, see
<<beans-autowired-annotation>>.
xref:core/beans/annotation-config/autowired.adoc[Using `@Autowired`].
When an `ApplicationContext` creates a class that implements the
`org.springframework.beans.factory.BeanNameAware` interface, the class is provided with
@ -577,7 +577,7 @@ init-method.
[[aware-list]]
== Other `Aware` Interfaces
Besides `ApplicationContextAware` and `BeanNameAware` (discussed <<beans-factory-aware, earlier>>),
Besides `ApplicationContextAware` and `BeanNameAware` (discussed xref:core/beans/factory-nature.adoc#beans-factory-aware[earlier]),
Spring offers a wide range of `Aware` callback interfaces that let beans indicate to the container
that they require a certain infrastructure dependency. As a general rule, the name indicates the
dependency type. The following table summarizes the most important `Aware` interfaces:
@ -589,50 +589,50 @@ dependency type. The following table summarizes the most important `Aware` inter
| `ApplicationContextAware`
| Declaring `ApplicationContext`.
| <<beans-factory-aware>>
| xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`]
| `ApplicationEventPublisherAware`
| Event publisher of the enclosing `ApplicationContext`.
| <<context-introduction>>
| xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`]
| `BeanClassLoaderAware`
| Class loader used to load the bean classes.
| <<beans-factory-class>>
| xref:core/beans/definition.adoc#beans-factory-class[Instantiating Beans]
| `BeanFactoryAware`
| Declaring `BeanFactory`.
| <<beans-beanfactory>>
| xref:core/beans/beanfactory.adoc[The `BeanFactory` API]
| `BeanNameAware`
| Name of the declaring bean.
| <<beans-factory-aware>>
| xref:core/beans/factory-nature.adoc#beans-factory-aware[`ApplicationContextAware` and `BeanNameAware`]
| `LoadTimeWeaverAware`
| Defined weaver for processing class definition at load time.
| <<aop-aj-ltw>>
| xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time Weaving with AspectJ in the Spring Framework]
| `MessageSourceAware`
| Configured strategy for resolving messages (with support for parameterization and
internationalization).
| <<context-introduction>>
| xref:core/beans/context-introduction.adoc[Additional Capabilities of the `ApplicationContext`]
| `NotificationPublisherAware`
| Spring JMX notification publisher.
| <<integration.adoc#jmx-notifications, Notifications>>
| xref:integration/jmx/notifications.adoc[Notifications]
| `ResourceLoaderAware`
| Configured loader for low-level access to resources.
| <<resources>>
| xref:web/webflux-webclient/client-builder.adoc#webflux-client-builder-reactor-resources[Resources]
| `ServletConfigAware`
| Current `ServletConfig` the container runs in. Valid only in a web-aware Spring
`ApplicationContext`.
| <<web.adoc#mvc, Spring MVC>>
| xref:web/webmvc.adoc#mvc[Spring MVC]
| `ServletContextAware`
| Current `ServletContext` the container runs in. Valid only in a web-aware Spring
`ApplicationContext`.
| <<web.adoc#mvc, Spring MVC>>
| xref:web/webmvc.adoc#mvc[Spring MVC]
|===
Note again that using these interfaces ties your code to the Spring API and does not

32
framework-docs/modules/ROOT/pages/core/beans/factory-scopes.adoc
View File

@ -14,7 +14,7 @@ through configuration instead of having to bake in the scope of an object at the
class level. Beans can be defined to be deployed in one of a number of scopes.
The Spring Framework supports six scopes, four of which are available only if
you use a web-aware `ApplicationContext`. You can also create
<<beans-factory-scopes-custom,a custom scope.>>
xref:core/beans/factory-scopes.adoc#beans-factory-scopes-custom[a custom scope.]
The following table describes the supported scopes:
@ -24,27 +24,27 @@ The following table describes the supported scopes:
|===
| Scope| Description
| <<beans-factory-scopes-singleton,singleton>>
| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-singleton[singleton]
| (Default) Scopes a single bean definition to a single object instance for each Spring IoC
container.
| <<beans-factory-scopes-prototype,prototype>>
| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-prototype[prototype]
| Scopes a single bean definition to any number of object instances.
| <<beans-factory-scopes-request,request>>
| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-request[request]
| Scopes a single bean definition to the lifecycle of a single HTTP request. That is,
each HTTP request has its own instance of a bean created off the back of a single bean
definition. Only valid in the context of a web-aware Spring `ApplicationContext`.
| <<beans-factory-scopes-session,session>>
| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-session[session]
| Scopes a single bean definition to the lifecycle of an HTTP `Session`. Only valid in
the context of a web-aware Spring `ApplicationContext`.
| <<beans-factory-scopes-application,application>>
| xref:core/beans/factory-scopes.adoc#beans-factory-scopes-application[application]
| Scopes a single bean definition to the lifecycle of a `ServletContext`. Only valid in
the context of a web-aware Spring `ApplicationContext`.
| <<web.adoc#websocket-stomp-websocket-scope,websocket>>
| xref:web/websocket/stomp/scope.adoc[websocket]
| Scopes a single bean definition to the lifecycle of a `WebSocket`. Only valid in
the context of a web-aware Spring `ApplicationContext`.
|===
@ -53,7 +53,7 @@ NOTE: A thread scope is available but is not registered by default. For more inf
see the documentation for
{api-spring-framework}/context/support/SimpleThreadScope.html[`SimpleThreadScope`].
For instructions on how to register this or any other custom scope, see
<<beans-factory-scopes-custom-using>>.
xref:core/beans/factory-scopes.adoc#beans-factory-scopes-custom-using[Using a Custom Scope].
@ -125,13 +125,13 @@ objects regardless of scope, in the case of prototypes, configured destruction
lifecycle callbacks are not called. The client code must clean up prototype-scoped
objects and release expensive resources that the prototype beans hold. To get
the Spring container to release resources held by prototype-scoped beans, try using a
custom <<beans-factory-extension-bpp,bean post-processor>>, which holds a reference to
custom xref:core/beans/factory-extension.adoc#beans-factory-extension-bpp[bean post-processor], which holds a reference to
beans that need to be cleaned up.
In some respects, the Spring container's role in regard to a prototype-scoped bean is a
replacement for the Java `new` operator. All lifecycle management past that point must
be handled by the client. (For details on the lifecycle of a bean in the Spring
container, see <<beans-factory-lifecycle>>.)
container, see xref:core/beans/factory-nature.adoc#beans-factory-lifecycle[Lifecycle Callbacks].)
@ -149,7 +149,7 @@ prototype-scoped bean repeatedly at runtime. You cannot dependency-inject a
prototype-scoped bean into your singleton bean, because that injection occurs only
once, when the Spring container instantiates the singleton bean and resolves
and injects its dependencies. If you need a new instance of a prototype bean at
runtime more than once, see <<beans-factory-method-injection>>.
runtime more than once, see xref:core/beans/dependencies/factory-method-injection.adoc[Method Injection].
@ -362,7 +362,7 @@ following example shows how to do so:
WebSocket scope is associated with the lifecycle of a WebSocket session and applies to
STOMP over WebSocket applications, see
<<web.adoc#websocket-stomp-websocket-scope,WebSocket scope>> for more details.
xref:web/websocket/stomp/scope.adoc[WebSocket scope] for more details.
@ -399,7 +399,7 @@ several additional access variants, including `getIfAvailable` and `getIfUnique`
The JSR-330 variant of this is called `Provider` and is used with a `Provider<MyTargetBean>`
declaration and a corresponding `get()` call for every retrieval attempt.
See <<beans-standard-annotations,here>> for more details on JSR-330 overall.
See xref:core/beans/standard-annotations.adoc[here] for more details on JSR-330 overall.
====
The configuration in the following example is only one line, but it is important to
@ -433,8 +433,8 @@ understand the "`why`" as well as the "`how`" behind it:
To create such a proxy, you insert a child `<aop:scoped-proxy/>` element into a scoped
bean definition (see <<beans-factory-scopes-other-injection-proxies>> and
<<core.adoc#core.appendix.xsd-schemas, XML Schema-based configuration>>).
bean definition (see xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection-proxies[Choosing the Type of Proxy to Create] and
xref:core/appendix/xsd-schemas.adoc[XML Schema-based configuration]).
Why do definitions of beans scoped at the `request`, `session` and custom-scope
levels require the `<aop:scoped-proxy/>` element?
Consider the following singleton bean definition and contrast it with
@ -521,7 +521,7 @@ interfaces. The following example shows a proxy based on an interface:
----
For more detailed information about choosing class-based or interface-based proxying,
see <<aop-proxying>>.
see xref:core/aop/proxying.adoc[Proxying Mechanisms].

2
framework-docs/modules/ROOT/pages/core/beans/introduction.adoc
View File

@ -30,7 +30,7 @@ and the `ApplicationContext` adds more enterprise-specific functionality. The
`ApplicationContext` is a complete superset of the `BeanFactory` and is used exclusively
in this chapter in descriptions of Spring's IoC container. For more information on using
the `BeanFactory` instead of the `ApplicationContext,` see the section covering the
<<beans-beanfactory, `BeanFactory` API>>.
xref:core/beans/beanfactory.adoc[`BeanFactory` API].
In Spring, the objects that form the backbone of your application and that are managed
by the Spring IoC container are called beans. A bean is an object that is

18
framework-docs/modules/ROOT/pages/core/beans/java.adoc
View File

@ -4,15 +4,15 @@
This section covers how to use annotations in your Java code to configure the Spring
container. It includes the following topics:
* <<beans-java-basic-concepts>>
* <<beans-java-instantiating-container>>
* <<beans-java-bean-annotation>>
* <<beans-java-configuration-annotation>>
* <<beans-java-composing-configuration-classes>>
* <<beans-definition-profiles>>
* <<beans-property-source-abstraction>>
* <<beans-using-propertysource>>
* <<beans-placeholder-resolution-in-statements>>
* xref:core/beans/java/basic-concepts.adoc[Basic Concepts: `@Bean` and `@Configuration`]
* xref:core/beans/java/instantiating-container.adoc[Instantiating the Spring Container by Using `AnnotationConfigApplicationContext`]
* xref:core/beans/java/bean-annotation.adoc[Using the `@Bean` Annotation]
* xref:core/beans/java/configuration-annotation.adoc[Using the `@Configuration` annotation]
* xref:core/beans/java/composing-configuration-classes.adoc[Composing Java-based Configurations]
* xref:core/beans/environment.adoc#beans-definition-profiles[Bean Definition Profiles]
* xref:core/beans/environment.adoc#beans-property-source-abstraction[`PropertySource` Abstraction]
* xref:core/beans/environment.adoc#beans-using-propertysource[Using `@PropertySource`]
* xref:core/beans/environment.adoc#beans-placeholder-resolution-in-statements[Placeholder Resolution in Statements]

28
framework-docs/modules/ROOT/pages/core/beans/java/bean-annotation.adoc
View File

@ -4,9 +4,9 @@
`@Bean` is a method-level annotation and a direct analog of the XML `<bean/>` element.
The annotation supports some of the attributes offered by `<bean/>`, such as:
* <<beans-factory-lifecycle-initializingbean, init-method>>
* <<beans-factory-lifecycle-disposablebean, destroy-method>>
* <<beans-factory-autowire,autowiring>>
* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-initializingbean[init-method]
* xref:core/beans/factory-nature.adoc#beans-factory-lifecycle-disposablebean[destroy-method]
* xref:core/beans/dependencies/factory-autowire.adoc[autowiring]
* `name`.
You can use the `@Bean` annotation in a `@Configuration`-annotated or in a
@ -160,7 +160,7 @@ parameter, as the following example shows:
The resolution mechanism is pretty much identical to constructor-based dependency
injection. See <<beans-constructor-injection, the relevant section>> for more details.
injection. See xref:core/beans/dependencies/factory-collaborators.adoc#beans-constructor-injection[the relevant section] for more details.
[[beans-java-lifecycle-callbacks]]
@ -168,17 +168,17 @@ injection. See <<beans-constructor-injection, the relevant section>> for more de
Any classes defined with the `@Bean` annotation support the regular lifecycle callbacks
and can use the `@PostConstruct` and `@PreDestroy` annotations from JSR-250. See
<<beans-postconstruct-and-predestroy-annotations, JSR-250 annotations>> for further
xref:core/beans/annotation-config/postconstruct-and-predestroy-annotations.adoc[JSR-250 annotations] for further
details.
The regular Spring <<beans-factory-nature, lifecycle>> callbacks are fully supported as
The regular Spring xref:core/beans/factory-nature.adoc[lifecycle] callbacks are fully supported as
well. If a bean implements `InitializingBean`, `DisposableBean`, or `Lifecycle`, their
respective methods are called by the container.
The standard set of `*Aware` interfaces (such as <<beans-beanfactory, BeanFactoryAware>>,
<<beans-factory-aware, BeanNameAware>>,
<<context-functionality-messagesource, MessageSourceAware>>,
<<beans-factory-aware, ApplicationContextAware>>, and so on) are also fully supported.
The standard set of `*Aware` interfaces (such as xref:core/beans/beanfactory.adoc[BeanFactoryAware],
xref:core/beans/factory-nature.adoc#beans-factory-aware[BeanNameAware],
xref:core/beans/context-introduction.adoc#context-functionality-messagesource[MessageSourceAware],
xref:core/beans/factory-nature.adoc#beans-factory-aware[ApplicationContextAware], and so on) are also fully supported.
The `@Bean` annotation supports specifying arbitrary initialization and destruction
callback methods, much like Spring XML's `init-method` and `destroy-method` attributes
@ -331,7 +331,7 @@ Spring includes the `@Scope` annotation so that you can specify the scope of a b
You can specify that your beans defined with the `@Bean` annotation should have a
specific scope. You can use any of the standard scopes specified in the
<<beans-factory-scopes, Bean Scopes>> section.
xref:core/beans/factory-scopes.adoc[Bean Scopes] section.
The default scope is `singleton`, but you can override this with the `@Scope` annotation,
as the following example shows:
@ -367,7 +367,7 @@ as the following example shows:
=== `@Scope` and `scoped-proxy`
Spring offers a convenient way of working with scoped dependencies through
<<beans-factory-scopes-other-injection, scoped proxies>>. The easiest way to create
xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[scoped proxies]. The easiest way to create
such a proxy when using the XML configuration is the `<aop:scoped-proxy/>` element.
Configuring your beans in Java with a `@Scope` annotation offers equivalent support
with the `proxyMode` attribute. The default is `ScopedProxyMode.DEFAULT`, which
@ -376,7 +376,7 @@ has been configured at the component-scan instruction level. You can specify
`ScopedProxyMode.TARGET_CLASS`, `ScopedProxyMode.INTERFACES` or `ScopedProxyMode.NO`.
If you port the scoped proxy example from the XML reference documentation (see
<<beans-factory-scopes-other-injection, scoped proxies>>) to our `@Bean` using Java,
xref:core/beans/factory-scopes.adoc#beans-factory-scopes-other-injection[scoped proxies]) to our `@Bean` using Java,
it resembles the following:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]
@ -448,7 +448,7 @@ as the following example shows:
[[beans-java-bean-aliasing]]
== Bean Aliasing
As discussed in <<beans-beanname>>, it is sometimes desirable to give a single bean
As discussed in xref:core/beans/definition.adoc#beans-beanname[Naming Beans], it is sometimes desirable to give a single bean
multiple names, otherwise known as bean aliasing. The `name` attribute of the `@Bean`
annotation accepts a String array for this purpose. The following example shows how to set
a number of aliases for a bean:

4
framework-docs/modules/ROOT/pages/core/beans/java/composing-configuration-classes.adoc
View File

@ -101,7 +101,7 @@ issue, because no compiler is involved, and you can declare
When using `@Configuration` classes, the Java compiler places constraints on
the configuration model, in that references to other beans must be valid Java syntax.
Fortunately, solving this problem is simple. As <<beans-java-dependencies, we already discussed>>,
Fortunately, solving this problem is simple. As xref:core/beans/java/bean-annotation.adoc#beans-java-dependencies[we already discussed],
a `@Bean` method can have an arbitrary number of parameters that describe the bean
dependencies. Consider the following more real-world scenario with several `@Configuration`
classes, each depending on beans declared in the others:
@ -474,7 +474,7 @@ created before the current bean, beyond what the latter's direct dependencies im
It is often useful to conditionally enable or disable a complete `@Configuration` class
or even individual `@Bean` methods, based on some arbitrary system state. One common
example of this is to use the `@Profile` annotation to activate beans only when a specific
profile has been enabled in the Spring `Environment` (see <<beans-definition-profiles>>
profile has been enabled in the Spring `Environment` (see xref:core/beans/environment.adoc#beans-definition-profiles[Bean Definition Profiles]
for details).
The `@Profile` annotation is actually implemented by using a much more flexible annotation

4
framework-docs/modules/ROOT/pages/core/beans/java/configuration-annotation.adoc
View File

@ -4,7 +4,7 @@
`@Configuration` is a class-level annotation indicating that an object is a source of
bean definitions. `@Configuration` classes declare beans through `@Bean`-annotated
methods. Calls to `@Bean` methods on `@Configuration` classes can also be used to define
inter-bean dependencies. See <<beans-java-basic-concepts>> for a general introduction.
inter-bean dependencies. See xref:core/beans/java/basic-concepts.adoc[Basic Concepts: `@Bean` and `@Configuration`] for a general introduction.
[[beans-java-injecting-dependencies]]
@ -56,7 +56,7 @@ by using plain `@Component` classes.
[[beans-java-method-injection]]
== Lookup Method Injection
As noted earlier, <<beans-factory-method-injection, lookup method injection>> is an
As noted earlier, xref:core/beans/dependencies/factory-method-injection.adoc[lookup method injection] is an
advanced feature that you should use rarely. It is useful in cases where a
singleton-scoped bean has a dependency on a prototype-scoped bean. Using Java for this
type of configuration provides a natural means for implementing this pattern. The

2
framework-docs/modules/ROOT/pages/core/beans/java/instantiating-container.adoc
View File

@ -177,7 +177,7 @@ following example shows:
}
----
NOTE: Remember that `@Configuration` classes are <<beans-meta-annotations, meta-annotated>>
NOTE: Remember that `@Configuration` classes are xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotated]
with `@Component`, so they are candidates for component-scanning. In the preceding example,
assuming that `AppConfig` is declared within the `com.acme` package (or any package
underneath), it is picked up during the call to `scan()`. Upon `refresh()`, all its `@Bean`

14
framework-docs/modules/ROOT/pages/core/databuffer-codec.adoc
View File

@ -8,10 +8,10 @@ XNIO, Jetty uses pooled byte buffers with a callback to be released, and so on.
The `spring-core` module provides a set of abstractions to work with various byte buffer
APIs as follows:
* <<databuffers-factory>> abstracts the creation of a data buffer.
* <<databuffers-buffer>> represents a byte buffer, which may be
<<databuffers-buffer-pooled, pooled>>.
* <<databuffers-utils>> offers utility methods for data buffers.
* xref:core/databuffer-codec.adoc#databuffers-factory[`DataBufferFactory`] abstracts the creation of a data buffer.
* xref:core/databuffer-codec.adoc#databuffers-buffer[`DataBuffer`] represents a byte buffer, which may be
xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[pooled].
* xref:core/databuffer-codec.adoc#databuffers-utils[`DataBufferUtils`] offers utility methods for data buffers.
* <<Codecs>> decode or encode data buffer streams into higher level objects.
@ -45,7 +45,7 @@ Below is a partial list of benefits:
* Read and write with independent positions, i.e. not requiring a call to `flip()` to
alternate between read and write.
* Capacity expanded on demand as with `java.lang.StringBuilder`.
* Pooled buffers and reference counting via <<databuffers-buffer-pooled>>.
* Pooled buffers and reference counting via xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[`PooledDataBuffer`].
* View a buffer as `java.nio.ByteBuffer`, `InputStream`, or `OutputStream`.
* Determine the index, or the last index, for a given byte.
@ -104,7 +104,7 @@ The `org.springframework.core.codec` package provides the following strategy int
The `spring-core` module provides `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and
`String` encoder and decoder implementations. The `spring-web` module adds Jackson JSON,
Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders. See
<<web-reactive.adoc#webflux-codecs, Codecs>> in the WebFlux section.
xref:web/webflux/reactive-spring.adoc#webflux-codecs[Codecs] in the WebFlux section.
@ -113,7 +113,7 @@ Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders. See
== Using `DataBuffer`
When working with data buffers, special care must be taken to ensure buffers are released
since they may be <<databuffers-buffer-pooled, pooled>>. We'll use codecs to illustrate
since they may be xref:core/databuffer-codec.adoc#databuffers-buffer-pooled[pooled]. We'll use codecs to illustrate
how that works but the concepts apply more generally. Let's see what codecs must do
internally to manage data buffers.

2
framework-docs/modules/ROOT/pages/core/expressions.adoc
View File

@ -23,7 +23,7 @@ infrastructure classes, such as the parser. Most Spring users need not deal with
this infrastructure and can, instead, author only expression strings for evaluation.
An example of this typical use is the integration of SpEL into creating XML or
annotation-based bean definitions, as shown in
<<expressions-beandef, Expression support for defining bean definitions>>.
xref:core/expressions/beandef.adoc[Expression support for defining bean definitions].
This chapter covers the features of the expression language, its API, and its language
syntax. In several places, `Inventor` and `Society` classes are used as the target

6
framework-docs/modules/ROOT/pages/core/expressions/evaluation.adoc
View File

@ -3,7 +3,7 @@
This section introduces the simple use of SpEL interfaces and its expression language.
The complete language reference can be found in
<<expressions-language-ref, Language Reference>>.
xref:core/expressions/language-ref.adoc[Language Reference].
The following code introduces the SpEL API to evaluate the literal string expression,
`Hello World`.
@ -376,7 +376,7 @@ interpreter and only 3ms using the compiled version of the expression.
The compiler is not turned on by default, but you can turn it on in either of two
different ways. You can turn it on by using the parser configuration process
(<<expressions-parser-configuration, discussed earlier>>) or by using a Spring property
(xref:core/expressions/evaluation.adoc#expressions-parser-configuration[discussed earlier]) or by using a Spring property
when SpEL usage is embedded inside another component. This section discusses both of
these options.
@ -443,7 +443,7 @@ The second way to configure the compiler is for use when SpEL is embedded inside
other component and it may not be possible to configure it through a configuration
object. In these cases, it is possible to set the `spring.expression.compiler.mode`
property via a JVM system property (or via the
<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism) to one of the
xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism) to one of the
`SpelCompilerMode` enum values (`off`, `immediate`, or `mixed`).

30
framework-docs/modules/ROOT/pages/core/expressions/language-ref.adoc
View File

@ -4,21 +4,21 @@
This section describes how the Spring Expression Language works. It covers the following
topics:
* <<expressions-ref-literal>>
* <<expressions-properties-arrays>>
* <<expressions-inline-lists>>
* <<expressions-inline-maps>>
* <<expressions-array-construction>>
* <<expressions-methods>>
* <<expressions-operators>>
* <<expressions-types>>
* <<expressions-constructors>>
* <<expressions-ref-variables>>
* <<expressions-ref-functions>>
* <<expressions-bean-references>>
* <<expressions-operator-ternary>>
* <<expressions-operator-elvis>>
* <<expressions-operator-safe-navigation>>
* xref:core/expressions/language-ref/literal.adoc[Literal Expressions]
* xref:core/expressions/language-ref/properties-arrays.adoc[Properties, Arrays, Lists, Maps, and Indexers]
* xref:core/expressions/language-ref/inline-lists.adoc[Inline Lists]
* xref:core/expressions/language-ref/inline-maps.adoc[Inline Maps]
* xref:core/expressions/language-ref/array-construction.adoc[Array Construction]
* xref:core/expressions/language-ref/methods.adoc[Methods]
* xref:core/expressions/language-ref/operators.adoc[Operators]
* xref:core/expressions/language-ref/types.adoc[Types]
* xref:core/expressions/language-ref/constructors.adoc[Constructors]
* xref:core/expressions/language-ref/variables.adoc[Variables]
* xref:core/expressions/language-ref/functions.adoc[Functions]
* xref:core/expressions/language-ref/bean-references.adoc[Bean References]
* xref:core/expressions/language-ref/operator-ternary.adoc[Ternary Operator (If-Then-Else)]
* xref:core/expressions/language-ref/operator-elvis.adoc[The Elvis Operator]
* xref:core/expressions/language-ref/operator-safe-navigation.adoc[Safe Navigation Operator]

8
framework-docs/modules/ROOT/pages/core/expressions/language-ref/operators.adoc
View File

@ -3,10 +3,10 @@
The Spring Expression Language supports the following kinds of operators:
* <<expressions-operators-relational>>
* <<expressions-operators-logical>>
* <<expressions-operators-mathematical>>
* <<expressions-assignment>>
* xref:core/expressions/language-ref/operators.adoc#expressions-operators-relational[Relational Operators]
* xref:core/expressions/language-ref/operators.adoc#expressions-operators-logical[Logical Operators]
* xref:core/expressions/language-ref/operators.adoc#expressions-operators-mathematical[Mathematical Operators]
* xref:core/expressions/language-ref/operators.adoc#expressions-assignment[The Assignment Operator]
[[expressions-operators-relational]]

4
framework-docs/modules/ROOT/pages/core/expressions/language-ref/properties-arrays.adoc
View File

@ -3,8 +3,8 @@
Navigating with property references is easy. To do so, use a period to indicate a nested
property value. The instances of the `Inventor` class, `pupin` and `tesla`, were
populated with data listed in the <<expressions-example-classes, Classes used in the
examples>> section. To navigate "down" the object graph and get Tesla's year of birth and
populated with data listed in the xref:core/expressions/example-classes.adoc[Classes used in the examples]
section. To navigate "down" the object graph and get Tesla's year of birth and
Pupin's city of birth, we use the following expressions:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]

2
framework-docs/modules/ROOT/pages/core/null-safety.adoc
View File

@ -39,7 +39,7 @@ warnings related to null-safety in order to avoid `NullPointerException` at runt
They are also used to make Spring API null-safe in Kotlin projects, since Kotlin natively
supports https://kotlinlang.org/docs/reference/null-safety.html[null-safety]. More details
are available in the <<languages#kotlin-null-safety, Kotlin support documentation>>.
are available in the xref:languages/kotlin/null-safety.adoc[Kotlin support documentation].

46
framework-docs/modules/ROOT/pages/core/resources.adoc
View File

@ -4,14 +4,14 @@
This chapter covers how Spring handles resources and how you can work with resources in
Spring. It includes the following topics:
* <<resources-introduction>>
* <<resources-resource>>
* <<resources-implementations>>
* <<resources-resourceloader>>
* <<resources-resourcepatternresolver>>
* <<resources-resourceloaderaware>>
* <<resources-as-dependencies>>
* <<resources-app-ctx>>
* xref:core/resources.adoc#resources-introduction[Introduction]
* xref:core/resources.adoc#resources-resource[The `Resource` Interface]
* xref:core/resources.adoc#resources-implementations[Built-in `Resource` Implementations]
* xref:core/resources.adoc#resources-resourceloader[The `ResourceLoader` Interface]
* xref:core/resources.adoc#resources-resourcepatternresolver[The `ResourcePatternResolver` Interface]
* xref:core/resources.adoc#resources-resourceloaderaware[The `ResourceLoaderAware` Interface]
* xref:core/resources.adoc#resources-as-dependencies[Resources as Dependencies]
* xref:core/resources.adoc#resources-app-ctx[Application Contexts and Resource Paths]
@ -133,13 +133,13 @@ work.
Spring includes several built-in `Resource` implementations:
* <<resources-implementations-urlresource>>
* <<resources-implementations-classpathresource>>
* <<resources-implementations-filesystemresource>>
* <<resources-implementations-pathresource>>
* <<resources-implementations-servletcontextresource>>
* <<resources-implementations-inputstreamresource>>
* <<resources-implementations-bytearrayresource>>
* xref:core/resources.adoc#resources-implementations-urlresource[`UrlResource`]
* xref:core/resources.adoc#resources-implementations-classpathresource[`ClassPathResource`]
* xref:core/resources.adoc#resources-implementations-filesystemresource[`FileSystemResource`]
* xref:core/resources.adoc#resources-implementations-pathresource[`PathResource`]
* xref:core/resources.adoc#resources-implementations-servletcontextresource[`ServletContextResource`]
* xref:core/resources.adoc#resources-implementations-inputstreamresource[`InputStreamResource`]
* xref:core/resources.adoc#resources-implementations-bytearrayresource[`ByteArrayResource`]
For a complete list of `Resource` implementations available in Spring, consult the
"All Known Implementing Classes" section of the
@ -349,7 +349,7 @@ objects:
| file:
| `\file:///data/config.xml`
| Loaded as a `URL` from the filesystem. See also <<resources-filesystemresource-caveats>>.
| Loaded as a `URL` from the filesystem. See also xref:core/resources.adoc#resources-filesystemresource-caveats[`FileSystemResource` Caveats].
| https:
| `\https://myserver/logo.png`
@ -385,11 +385,11 @@ for all matching resources from the class path. Note that the resource location
expected to be a path without placeholders in this case -- for example,
`classpath*:/config/beans.xml`. JAR files or different directories in the class path can
contain multiple files with the same path and the same name. See
<<resources-app-ctx-wildcards-in-resource-paths>> and its subsections for further details
xref:core/resources.adoc#resources-app-ctx-wildcards-in-resource-paths[Wildcards in Application Context Constructor Resource Paths] and its subsections for further details
on wildcard support with the `classpath*:` resource prefix.
A passed-in `ResourceLoader` (for example, one supplied via
<<resources-resourceloaderaware,`ResourceLoaderAware`>> semantics) can be checked whether
xref:core/resources.adoc#resources-resourceloaderaware[`ResourceLoaderAware`] semantics) can be checked whether
it implements this extended interface too.
`PathMatchingResourcePatternResolver` is a standalone implementation that is usable
@ -444,18 +444,18 @@ interface (which can be considered a utility interface) and not to the whole Spr
In application components, you may also rely upon autowiring of the `ResourceLoader` as
an alternative to implementing the `ResourceLoaderAware` interface. The _traditional_
`constructor` and `byType` autowiring modes (as described in <<beans-factory-autowire>>)
`constructor` and `byType` autowiring modes (as described in xref:core/beans/dependencies/factory-autowire.adoc[Autowiring Collaborators])
are capable of providing a `ResourceLoader` for either a constructor argument or a
setter method parameter, respectively. For more flexibility (including the ability to
autowire fields and multiple parameter methods), consider using the annotation-based
autowiring features. In that case, the `ResourceLoader` is autowired into a field,
constructor argument, or method parameter that expects the `ResourceLoader` type as long
as the field, constructor, or method in question carries the `@Autowired` annotation.
For more information, see <<beans-autowired-annotation>>.
For more information, see xref:core/beans/annotation-config/autowired.adoc[Using `@Autowired`].
NOTE: To load one or more `Resource` objects for a resource path that contains wildcards
or makes use of the special `classpath*:` resource prefix, consider having an instance of
<<resources-resourcepatternresolver,`ResourcePatternResolver`>> autowired into your
xref:core/resources.adoc#resources-resourcepatternresolver[`ResourcePatternResolver`] autowired into your
application components instead of `ResourceLoader`.
@ -531,8 +531,8 @@ latter being used to access a file in the filesystem):
If the `MyBean` class is refactored for use with annotation-driven configuration, the
path to `myTemplate.txt` can be stored under a key named `template.path` -- for example,
in a properties file made available to the Spring `Environment` (see
<<beans-environment>>). The template path can then be referenced via the `@Value`
annotation using a property placeholder (see <<beans-value-annotations>>). Spring will
xref:core/beans/environment.adoc[Environment Abstraction]). The template path can then be referenced via the `@Value`
annotation using a property placeholder (see xref:core/beans/annotation-config/value-annotations.adoc[Using `@Value`]). Spring will
retrieve the value of the template path as a string, and a special `PropertyEditor` will
convert the string to a `Resource` object to be injected into the `MyBean` constructor.
The following example demonstrates how to achieve this.

4
framework-docs/modules/ROOT/pages/core/validation.adoc
View File

@ -30,9 +30,9 @@ implementations. They are also discussed in this chapter.
Spring supports Java Bean Validation through setup infrastructure and an adaptor to
Spring's own `Validator` contract. Applications can enable Bean Validation once globally,
as described in <<validation-beanvalidation>>, and use it exclusively for all validation
as described in xref:core/validation/beanvalidation.adoc[Java Bean Validation], and use it exclusively for all validation
needs. In the web layer, applications can further register controller-local Spring
`Validator` instances per `DataBinder`, as described in <<validation-binder>>, which can
`Validator` instances per `DataBinder`, as described in xref:core/validation/beanvalidation.adoc#validation-binder[Configuring a `DataBinder`], which can
be useful for plugging in custom validation logic.

8
framework-docs/modules/ROOT/pages/core/validation/beans-beans.adoc
View File

@ -57,7 +57,7 @@ details. The below table shows some examples of these conventions:
(This next section is not vitally important to you if you do not plan to work with
the `BeanWrapper` directly. If you use only the `DataBinder` and the `BeanFactory`
and their default implementations, you should skip ahead to the
<<beans-beans-conversion, section on `PropertyEditors`>>.)
xref:core/validation/beans-beans.adoc#beans-beans-conversion[section on `PropertyEditors`].)
The following two example classes use the `BeanWrapper` to get and set
properties:
@ -378,7 +378,7 @@ where it can be automatically detected and applied.
Note that all bean factories and application contexts automatically use a number of
built-in property editors, through their use of a `BeanWrapper` to
handle property conversions. The standard property editors that the `BeanWrapper`
registers are listed in the <<beans-beans-conversion, previous section>>.
registers are listed in the xref:core/validation/beans-beans.adoc#beans-beans-conversion[previous section].
Additionally, ``ApplicationContext``s also override or add additional editors to handle
resource lookups in a manner appropriate to the specific application context type.
@ -495,7 +495,7 @@ You can write a corresponding registrar and reuse it in each case.
`PropertyEditorRegistry`, an interface that is implemented by the Spring `BeanWrapper`
(and `DataBinder`). `PropertyEditorRegistrar` instances are particularly convenient
when used in conjunction with `CustomEditorConfigurer` (described
<<beans-beans-conversion-customeditor-registration, here>>), which exposes a property
xref:core/validation/beans-beans.adoc#beans-beans-conversion-customeditor-registration[here]), which exposes a property
called `setPropertyEditorRegistrars(..)`. `PropertyEditorRegistrar` instances added
to a `CustomEditorConfigurer` in this fashion can easily be shared with `DataBinder` and
Spring MVC controllers. Furthermore, it avoids the need for synchronization on custom
@ -562,7 +562,7 @@ of our `CustomPropertyEditorRegistrar` into it:
----
Finally (and in a bit of a departure from the focus of this chapter) for those of you
using <<web.adoc#mvc, Spring's MVC web framework>>, using a `PropertyEditorRegistrar` in
using xref:web/webmvc.adoc#mvc[Spring's MVC web framework], using a `PropertyEditorRegistrar` in
conjunction with data-binding web controllers can be very convenient. The following
example uses a `PropertyEditorRegistrar` in the implementation of an `@InitBinder` method:

8
framework-docs/modules/ROOT/pages/core/validation/beanvalidation.adoc
View File

@ -265,10 +265,10 @@ for setup details with the Hibernate Validator and Bean Validation 1.1 providers
[TIP]
====
Method validation relies on <<core.adoc#aop-introduction-proxies,AOP Proxies>> around the
Method validation relies on xref:core/aop/introduction-proxies.adoc[AOP Proxies] around the
target classes, either JDK dynamic proxies for methods on interfaces or CGLIB proxies.
There are certain limitations with the use of proxies, some of which are described in
<<core.adoc#aop-understanding-aop-proxies,Understanding AOP Proxies>>. In addition remember
xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[Understanding AOP Proxies]. In addition remember
to always use methods and accessors on proxied classes; direct field access will not work.
====
@ -333,11 +333,11 @@ You can also configure a `DataBinder` with multiple `Validator` instances throug
`dataBinder.addValidators` and `dataBinder.replaceValidators`. This is useful when
combining globally configured bean validation with a Spring `Validator` configured
locally on a DataBinder instance. See
<<web.adoc#mvc-config-validation,Spring MVC Validation Configuration>>.
xref:web/webmvc/mvc-config/validation.adoc[Spring MVC Validation Configuration].
[[validation-mvc]]
== Spring MVC 3 Validation
See <<web.adoc#mvc-config-validation, Validation>> in the Spring MVC chapter.
See xref:web/webmvc/mvc-config/validation.adoc[Validation] in the Spring MVC chapter.

2
framework-docs/modules/ROOT/pages/core/validation/conversion.adoc
View File

@ -2,7 +2,7 @@
= Resolving Codes to Error Messages
We covered databinding and validation. This section covers outputting messages that correspond
to validation errors. In the example shown in the <<validator, preceding section>>,
to validation errors. In the example shown in the xref:core/validation/validator.adoc[preceding section],
we rejected the `name` and `age` fields. If we want to output the error messages by using a
`MessageSource`, we can do so using the error code we provide when rejecting the field
('name' and 'age' in this case). When you call (either directly, or indirectly, by using,

4
framework-docs/modules/ROOT/pages/core/validation/convert.adoc
View File

@ -246,10 +246,10 @@ any of the `Converter`, `ConverterFactory`, or `GenericConverter` interfaces.
----
It is also common to use a `ConversionService` within a Spring MVC application. See
<<web.adoc#mvc-config-conversion, Conversion and Formatting>> in the Spring MVC chapter.
xref:web/webmvc/mvc-config/conversion.adoc[Conversion and Formatting] in the Spring MVC chapter.
In certain situations, you may wish to apply formatting during conversion. See
<<format-FormatterRegistry-SPI>> for details on using `FormattingConversionServiceFactoryBean`.
xref:core/validation/format.adoc#format-FormatterRegistry-SPI[The `FormatterRegistry` SPI] for details on using `FormattingConversionServiceFactoryBean`.

4
framework-docs/modules/ROOT/pages/core/validation/format-configuring-formatting-globaldatetimeformat.adoc
View File

@ -108,8 +108,8 @@ If you prefer XML-based configuration, you can use a
Note there are extra considerations when configuring date and time formats in web
applications. Please see
<<web.adoc#mvc-config-conversion, WebMVC Conversion and Formatting>> or
<<web-reactive.adoc#webflux-config-conversion, WebFlux Conversion and Formatting>>.
xref:web/webmvc/mvc-config/conversion.adoc[WebMVC Conversion and Formatting] or
xref:web/webflux/config.adoc#webflux-config-conversion[WebFlux Conversion and Formatting].

4
framework-docs/modules/ROOT/pages/core/validation/format.adoc
View File

@ -1,7 +1,7 @@
[[format]]
= Spring Field Formatting
As discussed in the previous section, <<core-convert, `core.convert`>> is a
As discussed in the previous section, xref:core/validation/convert.adoc[`core.convert`] is a
general-purpose type conversion system. It provides a unified `ConversionService` API as
well as a strongly typed `Converter` SPI for implementing conversion logic from one type
to another. A Spring container uses this system to bind bean property values. In
@ -356,7 +356,7 @@ converter and formatter registration.
[[format-configuring-formatting-mvc]]
== Configuring Formatting in Spring MVC
See <<web.adoc#mvc-config-conversion, Conversion and Formatting>> in the Spring MVC chapter.
See xref:web/webmvc/mvc-config/conversion.adoc[Conversion and Formatting] in the Spring MVC chapter.

10
framework-docs/modules/ROOT/pages/data-access/appendix.adoc
View File

@ -9,8 +9,8 @@
This part of the appendix lists XML schemas for data access, including the following:
* <<xsd-schemas-tx>>
* <<xsd-schemas-jdbc>>
* xref:data-access/appendix.adoc#xsd-schemas-tx[The `tx` Schema]
* xref:data-access/appendix.adoc#xsd-schemas-jdbc[The `jdbc` Schema]
@ -19,7 +19,7 @@ This part of the appendix lists XML schemas for data access, including the follo
The `tx` tags deal with configuring all of those beans in Spring's comprehensive support
for transactions. These tags are covered in the chapter entitled
<<data-access.adoc#transaction, Transaction Management>>.
xref:data-access/transaction.adoc[Transaction Management].
TIP: We strongly encourage you to look at the `'spring-tx.xsd'` file that ships with the
Spring distribution. This file contains the XML Schema for Spring's transaction
@ -68,8 +68,8 @@ to you.
The `jdbc` elements let you quickly configure an embedded database or initialize an
existing data source. These elements are documented in
<<data-access.adoc#jdbc-embedded-database-support, Embedded Database Support>> and
<<data-access.adoc#jdbc-initializing-datasource, Initializing a DataSource>>, respectively.
xref:data-access/jdbc/embedded-database-support.adoc[Embedded Database Support] and
xref:data-access/jdbc/initializing-datasource.adoc[Initializing a DataSource], respectively.
To use the elements in the `jdbc` schema, you need to have the following preamble at the
top of your Spring XML configuration file. The text in the following snippet references

2
framework-docs/modules/ROOT/pages/data-access/jdbc/advanced.adoc
View File

@ -198,7 +198,7 @@ While this usually works well, there is a potential for issues (for example, wit
case, which can be expensive with your JDBC driver. You should use a recent driver
version and consider setting the `spring.jdbc.getParameterType.ignore` property to `true`
(as a JVM system property or via the
<<appendix.adoc#appendix-spring-properties,`SpringProperties`>> mechanism) if you encounter
xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism) if you encounter
a performance issue (as reported on Oracle 12c, JBoss, and PostgreSQL).
Alternatively, you might consider specifying the corresponding JDBC types explicitly,

16
framework-docs/modules/ROOT/pages/data-access/jdbc/connections.adoc
View File

@ -3,14 +3,14 @@
This section covers:
* <<jdbc-datasource>>
* <<jdbc-DataSourceUtils>>
* <<jdbc-SmartDataSource>>
* <<jdbc-AbstractDataSource>>
* <<jdbc-SingleConnectionDataSource>>
* <<jdbc-DriverManagerDataSource>>
* <<jdbc-TransactionAwareDataSourceProxy>>
* <<jdbc-DataSourceTransactionManager>>
* xref:data-access/jdbc/connections.adoc#jdbc-datasource[Using `DataSource`]
* xref:data-access/jdbc/connections.adoc#jdbc-DataSourceUtils[Using `DataSourceUtils`]
* xref:data-access/jdbc/connections.adoc#jdbc-SmartDataSource[Implementing `SmartDataSource`]
* xref:data-access/jdbc/connections.adoc#jdbc-AbstractDataSource[Extending `AbstractDataSource`]
* xref:data-access/jdbc/connections.adoc#jdbc-SingleConnectionDataSource[Using `SingleConnectionDataSource`]
* xref:data-access/jdbc/connections.adoc#jdbc-DriverManagerDataSource[Using `DriverManagerDataSource`]
* xref:data-access/jdbc/connections.adoc#jdbc-TransactionAwareDataSourceProxy[Using `TransactionAwareDataSourceProxy`]
* xref:data-access/jdbc/connections.adoc#jdbc-DataSourceTransactionManager[Using `DataSourceTransactionManager`]
[[jdbc-datasource]]

22
framework-docs/modules/ROOT/pages/data-access/jdbc/core.adoc
View File

@ -4,13 +4,13 @@
This section covers how to use the JDBC core classes to control basic JDBC processing,
including error handling. It includes the following topics:
* <<jdbc-JdbcTemplate>>
* <<jdbc-NamedParameterJdbcTemplate>>
* <<jdbc-SQLExceptionTranslator>>
* <<jdbc-statements-executing>>
* <<jdbc-statements-querying>>
* <<jdbc-updates>>
* <<jdbc-auto-generated-keys>>
* xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate[Using `JdbcTemplate`]
* xref:data-access/jdbc/core.adoc#jdbc-NamedParameterJdbcTemplate[Using `NamedParameterJdbcTemplate`]
* xref:data-access/jdbc/core.adoc#jdbc-SQLExceptionTranslator[Using `SQLExceptionTranslator`]
* xref:data-access/jdbc/core.adoc#jdbc-statements-executing[Running Statements]
* xref:data-access/jdbc/core.adoc#jdbc-statements-querying[Running Queries]
* xref:data-access/jdbc/core.adoc#jdbc-updates[Updating the Database]
* xref:data-access/jdbc/core.adoc#jdbc-auto-generated-keys[Retrieving Auto-generated Keys]
[[jdbc-JdbcTemplate]]
@ -26,7 +26,7 @@ SQL and extract results. The `JdbcTemplate` class:
* Updates statements and stored procedure calls
* Performs iteration over `ResultSet` instances and extraction of returned parameter values.
* Catches JDBC exceptions and translates them to the generic, more informative, exception
hierarchy defined in the `org.springframework.dao` package. (See <<dao-exceptions>>.)
hierarchy defined in the `org.springframework.dao` package. (See xref:data-access/dao.adoc#dao-exceptions[Consistent Exception Hierarchy].)
When you use the `JdbcTemplate` for your code, you need only to implement callback
interfaces, giving them a clearly defined contract. Given a `Connection` provided by the
@ -270,7 +270,7 @@ The following example invokes a stored procedure:
----
More sophisticated stored procedure support is <<jdbc-StoredProcedure, covered later>>.
More sophisticated stored procedure support is xref:data-access/jdbc/object.adoc#jdbc-StoredProcedure[covered later].
[[jdbc-JdbcTemplate-idioms]]
=== `JdbcTemplate` Best Practices
@ -282,7 +282,7 @@ The `JdbcTemplate` is stateful, in that it maintains a reference to a `DataSourc
this state is not conversational state.
A common practice when using the `JdbcTemplate` class (and the associated
<<jdbc-NamedParameterJdbcTemplate, `NamedParameterJdbcTemplate`>> class) is to
xref:data-access/jdbc/core.adoc#jdbc-NamedParameterJdbcTemplate[`NamedParameterJdbcTemplate`] class) is to
configure a `DataSource` in your Spring configuration file and then dependency-inject
that shared `DataSource` bean into your DAO classes. The `JdbcTemplate` is created in
the setter for the `DataSource`. This leads to DAOs that resemble the following:
@ -607,7 +607,7 @@ functionality that is present only in the `JdbcTemplate` class, you can use the
`getJdbcOperations()` method to access the wrapped `JdbcTemplate` through the
`JdbcOperations` interface.
See also <<jdbc-JdbcTemplate-idioms>> for guidelines on using the
See also xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate-idioms[`JdbcTemplate` Best Practices] for guidelines on using the
`NamedParameterJdbcTemplate` class in the context of an application.

10
framework-docs/modules/ROOT/pages/data-access/jdbc/embedded-database-support.adoc
View File

@ -129,9 +129,9 @@ configuration, as the following example shows:
This section covers how to select one of the three embedded databases that Spring
supports. It includes the following topics:
* <<jdbc-embedded-database-using-HSQL>>
* <<jdbc-embedded-database-using-H2>>
* <<jdbc-embedded-database-using-Derby>>
* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-HSQL[Using HSQL]
* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-H2[Using H2]
* xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-using-Derby[Using Derby]
[[jdbc-embedded-database-using-HSQL]]
=== Using HSQL
@ -163,9 +163,9 @@ Embedded databases provide a lightweight way to test data access code. The next
data access integration test template that uses an embedded database. Using such a template
can be useful for one-offs when the embedded database does not need to be reused across test
classes. However, if you wish to create an embedded database that is shared within a test suite,
consider using the <<testing.adoc#testcontext-framework, Spring TestContext Framework>> and
consider using the xref:testing/testcontext-framework.adoc[Spring TestContext Framework] and
configuring the embedded database as a bean in the Spring `ApplicationContext` as described
in <<jdbc-embedded-database-xml>> and <<jdbc-embedded-database-java>>. The following listing
in xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-xml[Creating an Embedded Database by Using Spring XML] and xref:data-access/jdbc/embedded-database-support.adoc#jdbc-embedded-database-java[Creating an Embedded Database Programmatically]. The following listing
shows the test template:
[source,java,indent=0,subs="verbatim,quotes",role="primary"]

4
framework-docs/modules/ROOT/pages/data-access/jdbc/object.adoc
View File

@ -10,7 +10,7 @@ procedures and run update, delete, and insert statements.
[NOTE]
====
Many Spring developers believe that the various RDBMS operation classes described below
(with the exception of the <<jdbc-StoredProcedure, `StoredProcedure`>> class) can often
(with the exception of the xref:data-access/jdbc/object.adoc#jdbc-StoredProcedure[`StoredProcedure`] class) can often
be replaced with straight `JdbcTemplate` calls. Often, it is simpler to write a DAO
method that calls a method on a `JdbcTemplate` directly (as opposed to
encapsulating a query as a full-blown class).
@ -236,7 +236,7 @@ The SQL type is specified using the `java.sql.Types` constants.
The first line (with the `SqlParameter`) declares an IN parameter. You can use IN parameters
both for stored procedure calls and for queries using the `SqlQuery` and its
subclasses (covered in <<jdbc-SqlQuery>>).
subclasses (covered in xref:data-access/jdbc/object.adoc#jdbc-SqlQuery[Understanding `SqlQuery`]).
The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in the
stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters

10
framework-docs/modules/ROOT/pages/data-access/jdbc/packages.adoc
View File

@ -8,19 +8,19 @@ various callback interfaces, plus a variety of related classes. A subpackage nam
`org.springframework.jdbc.core.simple` contains the `SimpleJdbcInsert` and
`SimpleJdbcCall` classes. Another subpackage named
`org.springframework.jdbc.core.namedparam` contains the `NamedParameterJdbcTemplate`
class and the related support classes. See <<jdbc-core>>, <<jdbc-advanced-jdbc>>, and
<<jdbc-simple-jdbc>>.
class and the related support classes. See xref:data-access/jdbc/core.adoc[Using the JDBC Core Classes to Control Basic JDBC Processing and Error Handling], xref:data-access/jdbc/advanced.adoc[JDBC Batch Operations], and
xref:data-access/jdbc/simple.adoc[Simplifying JDBC Operations with the `SimpleJdbc` Classes].
* `datasource`: The `org.springframework.jdbc.datasource` package contains a utility class for easy
`DataSource` access and various simple `DataSource` implementations that you can use for
testing and running unmodified JDBC code outside of a Jakarta EE container. A subpackage
named `org.springfamework.jdbc.datasource.embedded` provides support for creating
embedded databases by using Java database engines, such as HSQL, H2, and Derby. See
<<jdbc-connections>> and <<jdbc-embedded-database-support>>.
xref:data-access/jdbc/connections.adoc[Controlling Database Connections] and xref:data-access/jdbc/embedded-database-support.adoc[Embedded Database Support].
* `object`: The `org.springframework.jdbc.object` package contains classes that represent RDBMS
queries, updates, and stored procedures as thread-safe, reusable objects. See
<<jdbc-object>>. This approach is modeled by JDO, although objects returned by queries
xref:data-access/jdbc/object.adoc[Modeling JDBC Operations as Java Objects]. This approach is modeled by JDO, although objects returned by queries
are naturally disconnected from the database. This higher-level of JDBC abstraction
depends on the lower-level abstraction in the `org.springframework.jdbc.core` package.
@ -30,7 +30,7 @@ translated to exceptions defined in the `org.springframework.dao` package. This
that code using the Spring JDBC abstraction layer does not need to implement JDBC or
RDBMS-specific error handling. All translated exceptions are unchecked, which gives you
the option of catching the exceptions from which you can recover while letting other
exceptions be propagated to the caller. See <<jdbc-SQLExceptionTranslator>>.
exceptions be propagated to the caller. See xref:data-access/jdbc/core.adoc#jdbc-SQLExceptionTranslator[Using `SQLExceptionTranslator`].

6
framework-docs/modules/ROOT/pages/data-access/jdbc/simple.adoc
View File

@ -437,7 +437,7 @@ returned `out` parameters.
Earlier in this chapter, we described how parameters are deduced from metadata, but you can declare them
explicitly if you wish. You can do so by creating and configuring `SimpleJdbcCall` with
the `declareParameters` method, which takes a variable number of `SqlParameter` objects
as input. See the <<jdbc-params, next section>> for details on how to define an `SqlParameter`.
as input. See the xref:data-access/jdbc/simple.adoc#jdbc-params[next section] for details on how to define an `SqlParameter`.
NOTE: Explicit declarations are necessary if the database you use is not a Spring-supported
database. Currently, Spring supports metadata lookup of stored procedure calls for the
@ -510,7 +510,7 @@ details explicitly rather than relying on metadata.
== How to Define `SqlParameters`
To define a parameter for the `SimpleJdbc` classes and also for the RDBMS operations
classes (covered in <<jdbc-object>>) you can use `SqlParameter` or one of its subclasses.
classes (covered in xref:data-access/jdbc/object.adoc[Modeling JDBC Operations as Java Objects]) you can use `SqlParameter` or one of its subclasses.
To do so, you typically specify the parameter name and SQL type in the constructor. The SQL type
is specified by using the `java.sql.Types` constants. Earlier in this chapter, we saw declarations
similar to the following:
@ -530,7 +530,7 @@ similar to the following:
The first line with the `SqlParameter` declares an IN parameter. You can use IN parameters
for both stored procedure calls and for queries by using the `SqlQuery` and its
subclasses (covered in <<jdbc-SqlQuery>>).
subclasses (covered in xref:data-access/jdbc/object.adoc#jdbc-SqlQuery[Understanding `SqlQuery`]).
The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in a
stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters

8
framework-docs/modules/ROOT/pages/data-access/orm/general.adoc
View File

@ -2,7 +2,7 @@
= General ORM Integration Considerations
This section highlights considerations that apply to all ORM technologies.
The <<orm-hibernate>> section provides more details and also show these features and
The xref:data-access/orm/hibernate.adoc[Hibernate] section provides more details and also show these features and
configurations in a concrete context.
The major goal of Spring's ORM integration is clear application layering (with any data
@ -31,18 +31,18 @@ interceptors for the ORM technologies.
The infrastructure provides proper resource handling and appropriate conversion of
specific API exceptions to an unchecked infrastructure exception hierarchy. Spring
introduces a DAO exception hierarchy, applicable to any data access strategy. For direct
JDBC, the `JdbcTemplate` class mentioned in a <<jdbc-JdbcTemplate, previous section>>
JDBC, the `JdbcTemplate` class mentioned in a xref:data-access/jdbc/core.adoc#jdbc-JdbcTemplate[previous section]
provides connection handling and proper conversion of `SQLException` to the
`DataAccessException` hierarchy, including translation of database-specific SQL error
codes to meaningful exception classes. For ORM technologies, see the
<<orm-exception-translation, next section>> for how to get the same exception
xref:data-access/orm/general.adoc#orm-exception-translation[next section] for how to get the same exception
translation benefits.
When it comes to transaction management, the `JdbcTemplate` class hooks in to the Spring
transaction support and supports both JTA and JDBC transactions, through respective
Spring transaction managers. For the supported ORM technologies, Spring offers Hibernate
and JPA support through the Hibernate and JPA transaction managers as well as JTA support.
For details on transaction support, see the <<transaction>> chapter.
For details on transaction support, see the xref:data-access/transaction.adoc[Transaction Management] chapter.
[[orm-exception-translation]]

8
framework-docs/modules/ROOT/pages/data-access/orm/hibernate.adoc
View File

@ -21,7 +21,7 @@ To avoid tying application objects to hard-coded resource lookups, you can defin
resources (such as a JDBC `DataSource` or a Hibernate `SessionFactory`) as beans in the
Spring container. Application objects that need to access resources receive references
to such predefined instances through bean references, as illustrated in the DAO
definition in the <<orm-hibernate-straight, next section>>.
definition in the xref:data-access/orm/hibernate.adoc#orm-hibernate-straight[next section].
The following excerpt from an XML application context definition shows how to set up a
JDBC `DataSource` and a Hibernate `SessionFactory` on top of it:
@ -83,7 +83,7 @@ property. On the programmatic `LocalSessionFactoryBuilder`, there is an overload
As of Spring Framework 5.1, such a native Hibernate setup can also expose a JPA
`EntityManagerFactory` for standard JPA interaction next to native Hibernate access.
See <<orm-jpa-hibernate, Native Hibernate Setup for JPA>> for details.
See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate Setup for JPA] for details.
====
@ -185,7 +185,7 @@ container by using either Java annotations or XML. This declarative transaction
lets you keep business services free of repetitive transaction demarcation code and
focus on adding business logic, which is the real value of your application.
NOTE: Before you continue, we are strongly encourage you to read <<transaction-declarative>>
NOTE: Before you continue, we are strongly encourage you to read xref:data-access/transaction/declarative.adoc[Declarative Transaction Management]
if you have not already done so.
You can annotate the service layer with `@Transactional` annotations and instruct the
@ -447,7 +447,7 @@ to which it synchronizes (along with Spring). You have two options for doing thi
* Pass your Spring `JtaTransactionManager` bean to your Hibernate setup. The easiest
way is a bean reference into the `jtaTransactionManager` property for your
`LocalSessionFactoryBean` bean (see <<transaction-strategies-hibernate>>).
`LocalSessionFactoryBean` bean (see xref:data-access/transaction/strategies.adoc#transaction-strategies-hibernate[Hibernate Transaction Setup]).
Spring then makes the corresponding JTA strategies available to Hibernate.
* You may also configure Hibernate's JTA-related properties explicitly, in particular
"hibernate.transaction.coordinator_class", "hibernate.connection.handling_mode"

2
framework-docs/modules/ROOT/pages/data-access/orm/introduction.adoc
View File

@ -48,7 +48,7 @@ The benefits of using the Spring Framework to create your ORM DAOs include:
aspect-oriented programming (AOP) style method interceptor either through the
`@Transactional` annotation or by explicitly configuring the transaction AOP advice in
an XML configuration file. In both cases, transaction semantics and exception handling
(rollback and so on) are handled for you. As discussed in <<orm-resource-mngmnt>>,
(rollback and so on) are handled for you. As discussed in xref:data-access/orm/general.adoc#orm-resource-mngmnt[Resource and Transaction Management],
you can also swap various transaction managers, without affecting your ORM-related code.
For example, you can swap between local transactions and JTA, with the same full services
(such as declarative transactions) available in both scenarios. Additionally,

22
framework-docs/modules/ROOT/pages/data-access/orm/jpa.adoc
View File

@ -14,9 +14,9 @@ the underlying implementation in order to provide additional features.
The Spring JPA support offers three ways of setting up the JPA `EntityManagerFactory`
that is used by the application to obtain an entity manager.
* <<orm-jpa-setup-lemfb>>
* <<orm-jpa-setup-jndi>>
* <<orm-jpa-setup-lcemfb>>
* xref:data-access/orm/jpa.adoc#orm-jpa-setup-lemfb[Using `LocalEntityManagerFactoryBean`]
* xref:data-access/orm/jpa.adoc#orm-jpa-setup-jndi[Obtaining an EntityManagerFactory from JNDI]
* xref:data-access/orm/jpa.adoc#orm-jpa-setup-lcemfb[Using `LocalContainerEntityManagerFactoryBean`]
[[orm-jpa-setup-lemfb]]
=== Using `LocalEntityManagerFactoryBean`
@ -92,7 +92,7 @@ NOTE: If you want to specifically configure a Hibernate setup, an immediate alte
is to set up a native Hibernate `LocalSessionFactoryBean` instead of a plain JPA
`LocalContainerEntityManagerFactoryBean`, letting it interact with JPA access code
as well as native Hibernate access code.
See <<orm-jpa-hibernate, Native Hibernate setup for JPA interaction>> for details.
See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate setup for JPA interaction] for details.
The `LocalContainerEntityManagerFactoryBean` gives full control over
`EntityManagerFactory` configuration and is appropriate for environments where
@ -172,11 +172,11 @@ Spring provides a number of `LoadTimeWeaver` implementations for various environ
letting `ClassTransformer` instances be applied only for each class loader and not
for each VM.
See the <<core.adoc#aop-aj-ltw-spring, Spring configuration>> in the AOP chapter for
See the xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration] in the AOP chapter for
more insight regarding the `LoadTimeWeaver` implementations and their setup, either
generic or customized to various platforms (such as Tomcat, JBoss and WebSphere).
As described in <<core.adoc#aop-aj-ltw-spring, Spring configuration>>, you can configure
As described in xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration], you can configure
a context-wide `LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation or the
`context:load-time-weaver` XML element. Such a global weaver is automatically picked up
by all JPA `LocalContainerEntityManagerFactoryBean` instances. The following example
@ -452,7 +452,7 @@ a non-invasiveness perspective and can feel more natural to JPA developers.
[[orm-jpa-tx]]
== Spring-driven JPA transactions
NOTE: We strongly encourage you to read <<transaction-declarative>>, if you have not
NOTE: We strongly encourage you to read xref:data-access/transaction/declarative.adoc[Declarative Transaction Management], if you have not
already done so, to get more detailed coverage of Spring's declarative transaction support.
The recommended strategy for JPA is local transactions through JPA's native transaction
@ -464,12 +464,12 @@ Spring JPA also lets a configured `JpaTransactionManager` expose a JPA transacti
to JDBC access code that accesses the same `DataSource`, provided that the registered
`JpaDialect` supports retrieval of the underlying JDBC `Connection`.
Spring provides dialects for the EclipseLink and Hibernate JPA implementations.
See the <<orm-jpa-dialect, next section>> for details on the `JpaDialect` mechanism.
See the xref:data-access/orm/jpa.adoc#orm-jpa-dialect[next section] for details on the `JpaDialect` mechanism.
NOTE: As an immediate alternative, Spring's native `HibernateTransactionManager` is capable
of interacting with JPA access code, adapting to several Hibernate specifics and providing
JDBC interaction. This makes particular sense in combination with `LocalSessionFactoryBean`
setup. See <<orm-jpa-hibernate, Native Hibernate Setup for JPA Interaction>> for details.
setup. See xref:data-access/orm/jpa.adoc#orm-jpa-hibernate[Native Hibernate Setup for JPA Interaction] for details.
[[orm-jpa-dialect]]
@ -529,7 +529,7 @@ Hibernate 5.0 but not any more in Hibernate 5.1+. For a JTA setup, make sure to
your persistence unit transaction type as "JTA". Alternatively, set Hibernate 5.2's
`hibernate.connection.handling_mode` property to
`DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT` to restore Hibernate's own default.
See <<orm-hibernate-invalid-jdbc-access-error>> for related notes.
See xref:data-access/orm/hibernate.adoc#orm-hibernate-invalid-jdbc-access-error[Spurious Application Server Warnings with Hibernate] for related notes.
* Alternatively, consider obtaining the `EntityManagerFactory` from your application
server itself (that is, through a JNDI lookup instead of a locally declared
@ -565,7 +565,7 @@ seamlessly integrating with `@Bean` style configuration (no `FactoryBean` involv
====
`LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background
bootstrapping, just as the JPA `LocalContainerEntityManagerFactoryBean` does.
See <<orm-jpa-setup-background, Background Bootstrapping>> for an introduction.
See xref:data-access/orm/jpa.adoc#orm-jpa-setup-background[Background Bootstrapping] for an introduction.
On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor`
property. On the programmatic `LocalSessionFactoryBuilder`, an overloaded

14
framework-docs/modules/ROOT/pages/data-access/oxm.adoc
View File

@ -18,9 +18,9 @@ stream, or a SAX handler.
Some of the benefits of using Spring for your O/X mapping needs are:
* <<oxm-ease-of-configuration>>
* <<oxm-consistent-interfaces>>
* <<oxm-consistent-exception-hierarchy>>
* xref:data-access/oxm.adoc#oxm-ease-of-configuration[Ease of configuration]
* xref:data-access/oxm.adoc#oxm-consistent-interfaces[Consistent Interfaces]
* xref:data-access/oxm.adoc#oxm-consistent-exception-hierarchy[Consistent Exception Hierarchy]
[[oxm-ease-of-configuration]]
@ -57,7 +57,7 @@ These runtime exceptions wrap the original exception so that no information is l
[[oxm-marshaller-unmarshaller]]
== `Marshaller` and `Unmarshaller`
As stated in the <<oxm-introduction, introduction>>, a marshaller serializes an object
As stated in the xref:data-access/oxm.adoc#oxm-introduction[introduction], a marshaller serializes an object
to XML, and an unmarshaller deserializes XML stream to an object. This section describes
the two Spring interfaces used for this purpose.
@ -332,8 +332,8 @@ preamble of the XML configuration file. The following example shows how to do so
The schema makes the following elements available:
* <<oxm-jaxb2-xsd, `jaxb2-marshaller`>>
* <<oxm-jibx-xsd, `jibx-marshaller`>>
* xref:data-access/oxm.adoc#oxm-jaxb2-xsd[`jaxb2-marshaller`]
* xref:data-access/oxm.adoc#oxm-jibx-xsd[`jibx-marshaller`]
Each tag is explained in its respective marshaller's section. As an example, though,
the configuration of a JAXB2 marshaller might resemble the following:
@ -353,7 +353,7 @@ The JAXB binding compiler translates a W3C XML Schema into one or more Java clas
generate a schema from annotated Java classes.
Spring supports the JAXB 2.0 API as XML marshalling strategies, following the
`Marshaller` and `Unmarshaller` interfaces described in <<oxm-marshaller-unmarshaller>>.
`Marshaller` and `Unmarshaller` interfaces described in xref:data-access/oxm.adoc#oxm-marshaller-unmarshaller[`Marshaller` and `Unmarshaller`].
The corresponding integration classes reside in the `org.springframework.oxm.jaxb`
package.

28
framework-docs/modules/ROOT/pages/data-access/r2dbc.adoc
View File

@ -11,11 +11,11 @@ specification effort to standardize access to SQL databases using reactive patte
The Spring Framework's R2DBC abstraction framework consists of two different packages:
* `core`: The `org.springframework.r2dbc.core` package contains the `DatabaseClient`
class plus a variety of related classes. See <<r2dbc-core>>.
class plus a variety of related classes. See xref:data-access/r2dbc.adoc#r2dbc-core[Using the R2DBC Core Classes to Control Basic R2DBC Processing and Error Handling].
* `connection`: The `org.springframework.r2dbc.connection` package contains a utility class
for easy `ConnectionFactory` access and various simple `ConnectionFactory` implementations
that you can use for testing and running unmodified R2DBC. See <<r2dbc-connections>>.
that you can use for testing and running unmodified R2DBC. See xref:data-access/r2dbc.adoc#r2dbc-connections[Controlling Database Connections].
[[r2dbc-core]]
@ -24,12 +24,12 @@ that you can use for testing and running unmodified R2DBC. See <<r2dbc-connectio
This section covers how to use the R2DBC core classes to control basic R2DBC processing,
including error handling. It includes the following topics:
* <<r2dbc-DatabaseClient>>
* <<r2dbc-DatabaseClient-examples-statement>>
* <<r2dbc-DatabaseClient-examples-query>>
* <<r2dbc-DatabaseClient-examples-update>>
* <<r2dbc-DatabaseClient-filter>>
* <<r2dbc-auto-generated-keys>>
* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient[Using `DatabaseClient`]
* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-statement[Executing Statements]
* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-query[Querying (`SELECT`)]
* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-examples-update[Updating (`INSERT`, `UPDATE`, and `DELETE`) with `DatabaseClient`]
* xref:data-access/r2dbc.adoc#r2dbc-DatabaseClient-filter[Statement Filters]
* xref:data-access/r2dbc.adoc#r2dbc-auto-generated-keys[Retrieving Auto-generated Keys]
[[r2dbc-DatabaseClient]]
=== Using `DatabaseClient`
@ -44,7 +44,7 @@ SQL and extract results. The `DatabaseClient` class:
* Update statements and stored procedure calls
* Performs iteration over `Result` instances
* Catches R2DBC exceptions and translates them to the generic, more informative, exception
hierarchy defined in the `org.springframework.dao` package. (See <<dao-exceptions>>.)
hierarchy defined in the `org.springframework.dao` package. (See xref:data-access/dao.adoc#dao-exceptions[Consistent Exception Hierarchy].)
The client has a functional, fluent API using reactive types for declarative composition.
@ -543,11 +543,11 @@ requests the generated key for the desired column.
This section covers:
* <<r2dbc-ConnectionFactory>>
* <<r2dbc-ConnectionFactoryUtils>>
* <<r2dbc-SingleConnectionFactory>>
* <<r2dbc-TransactionAwareConnectionFactoryProxy>>
* <<r2dbc-R2dbcTransactionManager>>
* xref:data-access/r2dbc.adoc#r2dbc-ConnectionFactory[Using `ConnectionFactory`]
* xref:data-access/r2dbc.adoc#r2dbc-ConnectionFactoryUtils[Using `ConnectionFactoryUtils`]
* xref:data-access/r2dbc.adoc#r2dbc-SingleConnectionFactory[Using `SingleConnectionFactory`]
* xref:data-access/r2dbc.adoc#r2dbc-TransactionAwareConnectionFactoryProxy[Using `TransactionAwareConnectionFactoryProxy`]
* xref:data-access/r2dbc.adoc#r2dbc-R2dbcTransactionManager[Using `R2dbcTransactionManager`]
[[r2dbc-ConnectionFactory]]

22
framework-docs/modules/ROOT/pages/data-access/transaction.adoc
View File

@ -7,34 +7,34 @@ management that delivers the following benefits:
* A consistent programming model across different transaction APIs, such as Java
Transaction API (JTA), JDBC, Hibernate, and the Java Persistence API (JPA).
* Support for <<transaction-declarative, declarative transaction management>>.
* A simpler API for <<transaction-programmatic, programmatic>> transaction management
* Support for xref:data-access/transaction/declarative.adoc[declarative transaction management].
* A simpler API for xref:data-access/transaction/programmatic.adoc[programmatic] transaction management
than complex transaction APIs, such as JTA.
* Excellent integration with Spring's data access abstractions.
The following sections describe the Spring Framework's transaction features and
technologies:
* <<transaction-motivation, Advantages of the Spring Framework's transaction support
model>> describes why you would use the Spring Framework's transaction abstraction
* xref:data-access/transaction/motivation.adoc[Advantages of the Spring Framework's transaction support model]
describes why you would use the Spring Framework's transaction abstraction
instead of EJB Container-Managed Transactions (CMT) or choosing to drive local
transactions through a proprietary API, such as Hibernate.
* <<transaction-strategies, Understanding the Spring Framework transaction abstraction>>
* xref:data-access/transaction/strategies.adoc[Understanding the Spring Framework transaction abstraction]
outlines the core classes and describes how to configure and obtain `DataSource`
instances from a variety of sources.
* <<tx-resource-synchronization, Synchronizing resources with transactions>> describes
* xref:data-access/transaction/tx-resource-synchronization.adoc[Synchronizing resources with transactions] describes
how the application code ensures that resources are created, reused, and cleaned up
properly.
* <<transaction-declarative, Declarative transaction management>> describes support for
* xref:data-access/transaction/declarative.adoc[Declarative transaction management] describes support for
declarative transaction management.
* <<transaction-programmatic, Programmatic transaction management>> covers support for
* xref:data-access/transaction/programmatic.adoc[Programmatic transaction management] covers support for
programmatic (that is, explicitly coded) transaction management.
* <<transaction-event, Transaction bound event>> describes how you could use application
* xref:data-access/transaction/event.adoc[Transaction bound event] describes how you could use application
events within a transaction.
The chapter also includes discussions of best practices,
<<transaction-application-server-integration, application server integration>>,
and <<transaction-solutions-to-common-problems, solutions to common problems>>.
xref:data-access/transaction/application-server-integration.adoc[application server integration],
and xref:data-access/transaction/solutions-to-common-problems.adoc[solutions to common problems].

2
framework-docs/modules/ROOT/pages/data-access/transaction/declarative.adoc
View File

@ -22,7 +22,7 @@ necessary. The differences between the two types of transaction management are:
* You can apply the Spring Framework declarative transaction management to any class,
not merely special classes such as EJBs.
* The Spring Framework offers declarative
<<transaction-declarative-rolling-back, rollback rules>>, a feature with no EJB
xref:data-access/transaction/declarative/rolling-back.adoc[rollback rules], a feature with no EJB
equivalent. Both programmatic and declarative support for rollback rules is provided.
* The Spring Framework lets you customize transactional behavior by using AOP.
For example, you can insert custom behavior in the case of transaction rollback. You

24
framework-docs/modules/ROOT/pages/data-access/transaction/declarative/annotations.adoc
View File

@ -70,7 +70,7 @@ Consider the following class definition:
Used at the class level as above, the annotation indicates a default for all methods of
the declaring class (as well as its subclasses). Alternatively, each method can be
annotated individually. See <<transaction-declarative-annotations-method-visibility>> for
annotated individually. See xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-annotations-method-visibility[null] for
further details on which methods Spring considers transactional. Note that a class-level
annotation does not apply to ancestor classes up the class hierarchy; in such a scenario,
inherited methods need to be locally redeclared in order to participate in a
@ -182,7 +182,7 @@ programming arrangements as the following listing shows:
----
Note that there are special considerations for the returned `Publisher` with regards to
Reactive Streams cancellation signals. See the <<tx-prog-operator-cancel>> section under
Reactive Streams cancellation signals. See the xref:data-access/transaction/programmatic.adoc#tx-prog-operator-cancel[Cancel Signals] section under
"Using the TransactionalOperator" for more details.
@ -221,7 +221,7 @@ Note, however, that transactional methods in interface-based proxies must always
----
The _Spring TestContext Framework_ supports non-private `@Transactional` test methods by
default. See <<testing.adoc#testcontext-tx,Transaction Management>> in the testing
default. See xref:testing/testcontext-framework/tx.adoc[Transaction Management] in the testing
chapter for examples.
====
@ -276,7 +276,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method.
affected classes with Spring's AspectJ transaction aspect, modifying the target class
byte code to apply to any kind of method call. AspectJ weaving requires
`spring-aspects.jar` in the classpath as well as having load-time weaving (or compile-time
weaving) enabled. (See <<core.adoc#aop-aj-ltw-spring, Spring configuration>>
weaving) enabled. (See xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration]
for details on how to set up load-time weaving.)
| `proxy-target-class`
@ -286,7 +286,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method.
for classes annotated with the `@Transactional` annotation. If the
`proxy-target-class` attribute is set to `true`, class-based proxies are created.
If `proxy-target-class` is `false` or if the attribute is omitted, then standard JDK
interface-based proxies are created. (See <<core.adoc#aop-proxying, Proxying Mechanisms>>
interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms]
for a detailed examination of the different proxy types.)
| `order`
@ -294,7 +294,7 @@ is modified) to support `@Transactional` runtime behavior on any kind of method.
| `Ordered.LOWEST_PRECEDENCE`
| Defines the order of the transaction advice that is applied to beans annotated with
`@Transactional`. (For more information about the rules related to ordering of AOP
advice, see <<core.adoc#aop-ataspectj-advice-ordering, Advice Ordering>>.)
advice, see xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice Ordering].)
No specified ordering means that the AOP subsystem determines the order of the advice.
|===
@ -307,14 +307,14 @@ NOTE: The `proxy-target-class` attribute controls what type of transactional pro
created for classes annotated with the `@Transactional` annotation. If
`proxy-target-class` is set to `true`, class-based proxies are created. If
`proxy-target-class` is `false` or if the attribute is omitted, standard JDK
interface-based proxies are created. (See <<core.adoc#aop-proxying, Proxying Mechanisms>>
interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms]
for a discussion of the different proxy types.)
NOTE: `@EnableTransactionManagement` and `<tx:annotation-driven/>` look for
`@Transactional` only on beans in the same application context in which they are defined.
This means that, if you put annotation-driven configuration in a `WebApplicationContext`
for a `DispatcherServlet`, it checks for `@Transactional` beans only in your controllers
and not in your services. See <<web.adoc#mvc-servlet, MVC>> for more information.
and not in your services. See xref:web/webmvc/mvc-servlet.adoc[MVC] for more information.
The most derived location takes precedence when evaluating the transactional settings
for a method. In the case of the following example, the `DefaultFooService` class is
@ -382,7 +382,7 @@ properties of the `@Transactional` annotation:
|===
| Property| Type| Description
| <<tx-multiple-tx-mgrs-with-attransactional,value>>
| xref:data-access/transaction/declarative/annotations.adoc#tx-multiple-tx-mgrs-with-attransactional[value]
| `String`
| Optional qualifier that specifies the transaction manager to be used.
@ -394,7 +394,7 @@ properties of the `@Transactional` annotation:
| Array of `String` labels to add an expressive description to the transaction.
| Labels may be evaluated by transaction managers to associate implementation-specific behavior with the actual transaction.
| <<tx-propagation,propagation>>
| xref:data-access/transaction/declarative/tx-propagation.adoc[propagation]
| `enum`: `Propagation`
| Optional propagation setting.
@ -431,7 +431,7 @@ properties of the `@Transactional` annotation:
| Optional array of exception name patterns that must not cause rollback.
|===
TIP: See <<transaction-declarative-rollback-rules, Rollback rules>> for further details
TIP: See xref:data-access/transaction/declarative/rolling-back.adoc#transaction-declarative-rollback-rules[Rollback rules] for further details
on rollback rule semantics, patterns, and warnings regarding possible unintentional
matches for pattern-based rollback rules.
@ -523,7 +523,7 @@ is still used if no specifically qualified `TransactionManager` bean is found.
== Custom Composed Annotations
If you find you repeatedly use the same attributes with `@Transactional` on many different
methods, <<core.adoc#beans-meta-annotations, Spring's meta-annotation support>> lets you
methods, xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[Spring's meta-annotation support] lets you
define custom composed annotations for your specific use cases. For example, consider the
following annotation definitions:

4
framework-docs/modules/ROOT/pages/data-access/transaction/declarative/applying-more-than-just-tx-advice.adoc
View File

@ -13,7 +13,7 @@ When you invoke the `updateFoo(Foo)` method, you want to see the following actio
* The profiling aspect reports the exact duration of the whole transactional method invocation.
NOTE: This chapter is not concerned with explaining AOP in any great detail (except as it
applies to transactions). See <<core.adoc#aop,AOP>> for detailed coverage of the AOP
applies to transactions). See xref:core/aop.adoc[AOP] for detailed coverage of the AOP
configuration and AOP in general.
The following code shows the simple profiling aspect discussed earlier:
@ -95,7 +95,7 @@ The following code shows the simple profiling aspect discussed earlier:
The ordering of advice
is controlled through the `Ordered` interface. For full details on advice ordering, see
<<core.adoc#aop-ataspectj-advice-ordering,Advice ordering>>.
xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice ordering].
The following configuration creates a `fooService` bean that has profiling and
transactional aspects applied to it in the desired order:

10
framework-docs/modules/ROOT/pages/data-access/transaction/declarative/aspectj.adoc
View File

@ -10,12 +10,12 @@ and then link (weave) your application with the
manager. You can use the Spring Framework's IoC container to take care of
dependency-injecting the aspect. The simplest way to configure the transaction
management aspect is to use the `<tx:annotation-driven/>` element and specify the `mode`
attribute to `aspectj` as described in <<transaction-declarative-annotations>>. Because
attribute to `aspectj` as described in xref:data-access/transaction/declarative/annotations.adoc[Using `@Transactional`]. Because
we focus here on applications that run outside of a Spring container, we show
you how to do it programmatically.
NOTE: Prior to continuing, you may want to read <<transaction-declarative-annotations>> and
<<core.adoc#aop, AOP>> respectively.
NOTE: Prior to continuing, you may want to read xref:data-access/transaction/declarative/annotations.adoc[Using `@Transactional`] and
xref:core/aop.adoc[AOP] respectively.
The following example shows how to create a transaction manager and configure the
`AnnotationTransactionAspect` to use it:
@ -53,8 +53,8 @@ regardless of visibility.
To weave your applications with the `AnnotationTransactionAspect`, you must either build
your application with AspectJ (see the
https://www.eclipse.org/aspectj/doc/released/devguide/index.html[AspectJ Development
Guide]) or use load-time weaving. See <<core.adoc#aop-aj-ltw,Load-time weaving with
AspectJ in the Spring Framework>> for a discussion of load-time weaving with AspectJ.
Guide]) or use load-time weaving. See xref:core/aop/using-aspectj.adoc#aop-aj-ltw[Load-time weaving with AspectJ in the Spring Framework]
for a discussion of load-time weaving with AspectJ.

4
framework-docs/modules/ROOT/pages/data-access/transaction/declarative/first-example.adoc
View File

@ -187,7 +187,7 @@ advisor. The result indicates that, at the execution of a `fooServiceOperation`,
the advice defined by `txAdvice` is run.
The expression defined within the `<aop:pointcut/>` element is an AspectJ pointcut
expression. See <<core.adoc#aop, the AOP section>> for more details on pointcut
expression. See xref:core/aop.adoc[the AOP section] for more details on pointcut
expressions in Spring.
A common requirement is to make an entire service layer transactional. The best way to
@ -203,7 +203,7 @@ service layer. The following example shows how to do so:
----
NOTE: In the preceding example, it is assumed that all your service interfaces are defined
in the `x.y.service` package. See <<core.adoc#aop, the AOP section>> for more details.
in the `x.y.service` package. See xref:core/aop.adoc[the AOP section] for more details.
Now that we have analyzed the configuration, you may be asking yourself,
"What does all this configuration actually do?"

4
framework-docs/modules/ROOT/pages/data-access/transaction/declarative/rolling-back.adoc
View File

@ -6,7 +6,7 @@ classes, typically service layer classes, declaratively in your application. Thi
describes how you can control the rollback of transactions in a simple, declarative
fashion in XML configuration. For details on controlling rollback semantics declaratively
with the `@Transactional` annotation, see
<<transaction-declarative-attransactional-settings>>.
xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-attransactional-settings[`@Transactional` Settings].
The recommended way to indicate to the Spring Framework's transaction infrastructure
that a transaction's work is to be rolled back is to throw an `Exception` from code that
@ -51,7 +51,7 @@ thrown, and the rules are based on exception types or exception patterns.
Rollback rules may be configured in XML via the `rollback-for` and `no-rollback-for`
attributes, which allow rules to be defined as patterns. When using
<<transaction-declarative-attransactional-settings,`@Transactional`>>, rollback rules may
xref:data-access/transaction/declarative/annotations.adoc#transaction-declarative-attransactional-settings[`@Transactional`], rollback rules may
be configured via the `rollbackFor`/`noRollbackFor` and
`rollbackForClassName`/`noRollbackForClassName` attributes, which allow rules to be
defined based on exception types or patterns, respectively.

4
framework-docs/modules/ROOT/pages/data-access/transaction/declarative/tx-decl-explained.adoc
View File

@ -9,13 +9,13 @@ infrastructure in the context of transaction-related issues.
The most important concepts to grasp with regard to the Spring Framework's declarative
transaction support are that this support is enabled
<<core.adoc#aop-understanding-aop-proxies, via AOP proxies>> and that the transactional
xref:core/aop/proxying.adoc#aop-understanding-aop-proxies[via AOP proxies] and that the transactional
advice is driven by metadata (currently XML- or annotation-based). The combination of AOP
with transactional metadata yields an AOP proxy that uses a `TransactionInterceptor` in
conjunction with an appropriate `TransactionManager` implementation to drive transactions
around method invocations.
NOTE: Spring AOP is covered in <<core.adoc#aop, the AOP section>>.
NOTE: Spring AOP is covered in xref:core/aop.adoc[the AOP section].
Spring Framework's `TransactionInterceptor` provides transaction management for
imperative and reactive programming models. The interceptor detects the desired flavor of

2
framework-docs/modules/ROOT/pages/data-access/transaction/declarative/txadvice-settings.adoc
View File

@ -4,7 +4,7 @@
This section summarizes the various transactional settings that you can specify by using
the `<tx:advice/>` tag. The default `<tx:advice/>` settings are:
* The <<tx-propagation, propagation setting>> is `REQUIRED.`
* The xref:data-access/transaction/declarative/tx-propagation.adoc[propagation setting] is `REQUIRED.`
* The isolation level is `DEFAULT.`
* The transaction is read-write.
* The transaction timeout defaults to the default timeout of the underlying transaction

4
framework-docs/modules/ROOT/pages/data-access/transaction/programmatic.adoc
View File

@ -139,7 +139,7 @@ Code within the callback can roll the transaction back by calling the
You can specify transaction settings (such as the propagation mode, the isolation level,
the timeout, and so forth) on the `TransactionTemplate` either programmatically or in
configuration. By default, `TransactionTemplate` instances have the
<<transaction-declarative-txadvice-settings,default transactional settings>>. The
xref:data-access/transaction/declarative/txadvice-settings.adoc[default transactional settings]. The
following example shows the programmatic customization of the transactional settings for
a specific `TransactionTemplate:`
@ -302,7 +302,7 @@ the full output must be consumed to allow the transaction to complete.
You can specify transaction settings (such as the propagation mode, the isolation level,
the timeout, and so forth) for the `TransactionalOperator`. By default,
`TransactionalOperator` instances have
<<transaction-declarative-txadvice-settings,default transactional settings>>. The
xref:data-access/transaction/declarative/txadvice-settings.adoc[default transactional settings]. The
following example shows customization of the transactional settings for a specific
`TransactionalOperator:`

2
framework-docs/modules/ROOT/pages/data-access/transaction/solutions-to-common-problems.adoc
View File

@ -12,7 +12,7 @@ transactional technologies and requirements. Used properly, the Spring Framework
provides a straightforward and portable abstraction. If you use global
transactions, you must use the
`org.springframework.transaction.jta.JtaTransactionManager` class (or an
<<transaction-application-server-integration,application server-specific subclass>> of
xref:data-access/transaction/application-server-integration.adoc[application server-specific subclass] of
it) for all your transactional operations. Otherwise, the transaction infrastructure
tries to perform local transactions on such resources as container `DataSource`
instances. Such local transactions do not make sense, and a good application server

8
framework-docs/modules/ROOT/pages/data-access/transaction/strategies.adoc
View File

@ -22,7 +22,7 @@ transaction management. The following listing shows the definition of the
----
This is primarily a service provider interface (SPI), although you can use it
<<transaction-programmatic-ptm, programmatically>> from your application code. Because
xref:data-access/transaction/programmatic.adoc#transaction-programmatic-ptm[programmatically] from your application code. Because
`PlatformTransactionManager` is an interface, it can be easily mocked or stubbed as
necessary. It is not tied to a lookup strategy, such as JNDI.
`PlatformTransactionManager` implementations are defined like any other object (or bean)
@ -63,7 +63,7 @@ listing shows the transaction strategy defined by
----
The reactive transaction manager is primarily a service provider interface (SPI),
although you can use it <<transaction-programmatic-rtm, programmatically>> from your
although you can use it xref:data-access/transaction/programmatic.adoc#transaction-programmatic-rtm[programmatically] from your
application code. Because `ReactiveTransactionManager` is an interface, it can be easily
mocked or stubbed as necessary.
@ -75,7 +75,7 @@ The `TransactionDefinition` interface specifies:
example, code can continue running in the existing transaction (the common case), or
the existing transaction can be suspended and a new transaction created. Spring
offers all of the transaction propagation options familiar from EJB CMT. To read
about the semantics of transaction propagation in Spring, see <<tx-propagation>>.
about the semantics of transaction propagation in Spring, see xref:data-access/transaction/declarative/tx-propagation.adoc[Transaction Propagation].
* Isolation: The degree to which this transaction is isolated from the work of other
transactions. For example, can this transaction see uncommitted writes from other
transactions?
@ -179,7 +179,7 @@ infrastructure.
NOTE: The preceding definition of the `dataSource` bean uses the `<jndi-lookup/>` tag
from the `jee` namespace. For more information see
<<integration.adoc#integration.appendix.xsd-schemas-jee, The JEE Schema>>.
xref:integration/appendix.adoc#integration.appendix.xsd-schemas-jee[The JEE Schema].
NOTE: If you use JTA, your transaction manager definition should look the same, regardless
of what data access technology you use, be it JDBC, Hibernate JPA, or any other supported

16
framework-docs/modules/ROOT/pages/index.adoc
View File

@ -3,22 +3,22 @@
= Spring Framework Documentation
[horizontal]
<<overview.adoc#overview, Overview>> :: History, Design Philosophy, Feedback,
xref:web/websocket/stomp/overview.adoc[Overview] :: History, Design Philosophy, Feedback,
Getting Started.
<<core.adoc#spring-core, Core>> :: IoC Container, Events, Resources, i18n,
xref:core.adoc[Core] :: IoC Container, Events, Resources, i18n,
Validation, Data Binding, Type Conversion, SpEL, AOP, AOT.
<<testing.adoc#testing, Testing>> :: Mock Objects, TestContext Framework,
Spring MVC Test, WebTestClient.
<<data-access.adoc#spring-data-tier, Data Access>> :: Transactions, DAO Support,
xref:data-access.adoc[Data Access] :: Transactions, DAO Support,
JDBC, R2DBC, O/R Mapping, XML Marshalling.
<<web.adoc#spring-web, Web Servlet>> :: Spring MVC, WebSocket, SockJS,
xref:web.adoc[Web Servlet] :: Spring MVC, WebSocket, SockJS,
STOMP Messaging.
<<web-reactive.adoc#spring-web-reactive, Web Reactive>> :: Spring WebFlux, WebClient,
xref:testing/unit.adoc#mock-objects-web-reactive[Web Reactive] :: Spring WebFlux, WebClient,
WebSocket, RSocket.
<<integration.adoc#spring-integration, Integration>> :: REST Clients, JMS, JCA, JMX,
xref:integration.adoc[Integration] :: REST Clients, JMS, JCA, JMX,
Email, Tasks, Scheduling, Caching, Observability.
<<languages.adoc#languages, Languages>> :: Kotlin, Groovy, Dynamic Languages.
<<appendix.adoc#appendix, Appendix>> :: Spring properties.
xref:languages.adoc[Languages] :: Kotlin, Groovy, Dynamic Languages.
xref:testing/appendix.adoc[Appendix] :: Spring properties.
https://github.com/spring-projects/spring-framework/wiki[Wiki] :: What's New,
Upgrade Notes, Supported Versions, additional cross-version information.

12
framework-docs/modules/ROOT/pages/integration/appendix.adoc
View File

@ -272,9 +272,9 @@ with `jee`:
=== The `jms` Schema
The `jms` elements deal with configuring JMS-related beans, such as Spring's
<<integration.adoc#jms-mdp, Message Listener Containers>>. These elements are detailed in the
section of the <<integration.adoc#jms, JMS chapter>> entitled <<integration.adoc#jms-namespace,
JMS Namespace Support>>. See that chapter for full details on this support
xref:integration/jms/using.adoc#jms-mdp[Message Listener Containers]. These elements are detailed in the
section of the xref:integration/jms.adoc[JMS chapter] entitled xref:integration/jms/namespace.adoc[JMS Namespace Support]
. See that chapter for full details on this support
and the `jms` elements themselves.
In the interest of completeness, to use the elements in the `jms` schema, you need to have
@ -305,7 +305,7 @@ are available to you:
=== Using `<context:mbean-export/>`
This element is detailed in
<<integration.adoc#jmx-context-mbeanexport, Configuring Annotation-based MBean Export>>.
xref:integration/jmx/naming.adoc#jmx-context-mbeanexport[Configuring Annotation-based MBean Export].
@ -314,8 +314,8 @@ This element is detailed in
You can use the `cache` elements to enable support for Spring's `@CacheEvict`, `@CachePut`,
and `@Caching` annotations. It it also supports declarative XML-based caching. See
<<integration.adoc#cache-annotation-enable, Enabling Caching Annotations>> and
<<integration.adoc#cache-declarative-xml, Declarative XML-based Caching>> for details.
xref:integration/cache/annotations.adoc#cache-annotation-enable[Enabling Caching Annotations] and
xref:integration/cache/declarative-xml.adoc[Declarative XML-based Caching] for details.
To use the elements in the `cache` schema, you need to have the following preamble at the
top of your Spring XML configuration file. The text in the following snippet references

4
framework-docs/modules/ROOT/pages/integration/cache.adoc
View File

@ -2,12 +2,12 @@
= Cache Abstraction
Since version 3.1, the Spring Framework provides support for transparently adding caching to
an existing Spring application. Similar to the <<data-access.adoc#transaction, transaction>>
an existing Spring application. Similar to the xref:data-access/transaction.adoc[transaction]
support, the caching abstraction allows consistent use of various caching solutions with
minimal impact on the code.
In Spring Framework 4.1, the cache abstraction was significantly extended with support
for <<cache-jsr-107,JSR-107 annotations>> and more customization options.
for xref:integration/cache/jsr-107.adoc[JSR-107 annotations] and more customization options.

28
framework-docs/modules/ROOT/pages/integration/cache/annotations.adoc vendored
View File

@ -94,16 +94,16 @@ they are no use for the cache. Furthermore, what if only one of the two is impor
while the other is not?
For such cases, the `@Cacheable` annotation lets you specify how the key is generated
through its `key` attribute. You can use <<core.adoc#expressions, SpEL>> to pick the
through its `key` attribute. You can use xref:core/expressions.adoc[SpEL] to pick the
arguments of interest (or their nested properties), perform operations, or even
invoke arbitrary methods without having to write any code or implement any interface.
This is the recommended approach over the
<<cache-annotations-cacheable-default-key, default generator>>, since methods tend to be
xref:integration/cache/annotations.adoc#cache-annotations-cacheable-default-key[default generator], since methods tend to be
quite different in signatures as the code base grows. While the default strategy might
work for some methods, it rarely works for all methods.
The following examples use various SpEL declarations (if you are not familiar with SpEL,
do yourself a favor and read <<core.adoc#expressions, Spring Expression Language>>):
do yourself a favor and read xref:core/expressions.adoc[Spring Expression Language]):
[source,java,indent=0,subs="verbatim,quotes"]
----
@ -162,7 +162,7 @@ For applications that work with several cache managers, you can set the
You can also replace the `CacheResolver` entirely in a fashion similar to that of
replacing <<cache-annotations-cacheable-key, key generation>>. The resolution is
replacing xref:integration/cache/annotations.adoc#cache-annotations-cacheable-key[key generation]. The resolution is
requested for every cache operation, letting the implementation actually resolve
the caches to use based on runtime arguments. The following example shows how to
specify a `CacheResolver`:
@ -256,12 +256,12 @@ as follows:
----
Note that `#result` still refers to `Book` and not `Optional<Book>`. Since it might be
`null`, we use SpEL's <<core.adoc#expressions-operator-safe-navigation, safe navigation operator>>.
`null`, we use SpEL's xref:core/expressions/language-ref/operator-safe-navigation.adoc[safe navigation operator].
[[cache-spel-context]]
=== Available Caching SpEL Evaluation Context
Each `SpEL` expression evaluates against a dedicated <<core.adoc#expressions-language-ref, `context`>>.
Each `SpEL` expression evaluates against a dedicated xref:core/expressions/language-ref.adoc[`context`].
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 conditional computations:
@ -472,7 +472,7 @@ 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
application through AOP. The configuration is intentionally similar with that of
<<data-access.adoc#tx-annotation-driven-settings, `@Transactional`>>.
xref:data-access/transaction/declarative/annotations.adoc#tx-annotation-driven-settings[`@Transactional`].
NOTE: The default advice mode for processing caching annotations is `proxy`, which allows
for interception of calls through the proxy only. Local calls within the same class
@ -524,7 +524,7 @@ required to implement `CachingConfigurer`, see the
affected classes with Spring's AspectJ caching aspect, modifying the target class byte
code to apply to any kind of method call. AspectJ weaving requires `spring-aspects.jar`
in the classpath as well as load-time weaving (or compile-time weaving) enabled. (See
<<core.adoc#aop-aj-ltw-spring, Spring configuration>> for details on how to set up
xref:core/aop/using-aspectj.adoc#aop-aj-ltw-spring[Spring configuration] for details on how to set up
load-time weaving.)
| `proxy-target-class`
@ -534,7 +534,7 @@ required to implement `CachingConfigurer`, see the
classes annotated with the `@Cacheable` or `@CacheEvict` annotations. If the
`proxy-target-class` attribute is set to `true`, class-based proxies are created.
If `proxy-target-class` is `false` or if the attribute is omitted, standard JDK
interface-based proxies are created. (See <<core.adoc#aop-proxying, Proxying Mechanisms>>
interface-based proxies are created. (See xref:core/aop/proxying.adoc[Proxying Mechanisms]
for a detailed examination of the different proxy types.)
| `order`
@ -542,7 +542,7 @@ required to implement `CachingConfigurer`, see the
| Ordered.LOWEST_PRECEDENCE
| Defines the order of the cache advice that is applied to beans annotated with
`@Cacheable` or `@CacheEvict`. (For more information about the rules related to
ordering AOP advice, see <<core.adoc#aop-ataspectj-advice-ordering, Advice Ordering>>.)
ordering AOP advice, see xref:core/aop/ataspectj/advice.adoc#aop-ataspectj-advice-ordering[Advice Ordering].)
No specified ordering means that the AOP subsystem determines the order of the advice.
|===
@ -550,7 +550,7 @@ NOTE: `<cache:annotation-driven/>` looks for `@Cacheable/@CachePut/@CacheEvict/@
only on beans in the same application context in which it is defined. This means that,
if you put `<cache:annotation-driven/>` in a `WebApplicationContext` for a
`DispatcherServlet`, it checks for beans only in your controllers, not your services.
See <<web.adoc#mvc-servlet, the MVC section>> for more information.
See xref:web/webmvc/mvc-servlet.adoc[the MVC section] for more information.
.Method visibility and cache annotations
****
@ -595,9 +595,9 @@ triggers cache population or eviction. This is quite handy as a template mechani
as it eliminates the need to duplicate cache annotation declarations, which is
especially useful if the key or condition are specified or if the foreign imports
(`org.springframework`) are not allowed in your code base. Similarly to the rest
of the <<core.adoc#beans-stereotype-annotations, stereotype>> annotations, you can
of the xref:core/beans/classpath-scanning.adoc#beans-stereotype-annotations[stereotype] annotations, you can
use `@Cacheable`, `@CachePut`, `@CacheEvict`, and `@CacheConfig` as
<<core.adoc#beans-meta-annotations, meta-annotations>> (that is, annotations that
xref:core/beans/classpath-scanning.adoc#beans-meta-annotations[meta-annotations] (that is, annotations that
can annotate other annotations). In the following example, we replace a common
`@Cacheable` declaration with our own custom annotation:
@ -630,7 +630,7 @@ preceding code:
Even though `@SlowService` is not a Spring annotation, the container automatically picks
up its declaration at runtime and understands its meaning. Note that, as mentioned
<<cache-annotation-enable, earlier>>, annotation-driven behavior needs to be enabled.
xref:integration/cache/annotations.adoc#cache-annotation-enable[earlier], annotation-driven behavior needs to be enabled.

4
framework-docs/modules/ROOT/pages/integration/cache/declarative-xml.adoc vendored
View File

@ -5,7 +5,7 @@ If annotations are not an option (perhaps due to having no access to the sources
or no external code), you can use XML for declarative caching. So, instead of
annotating the methods for caching, you can specify the target method and the
caching directives externally (similar to the declarative transaction management
<<data-access.adoc#transaction-declarative-first-example, advice>>). The example
xref:data-access/transaction/declarative/first-example.adoc[advice]). The example
from the previous section can be translated into the following example:
[source,xml,indent=0]
@ -37,7 +37,7 @@ data. Both definitions work against the `books` cache.
The `aop:config` definition applies the cache advice to the appropriate points in the
program by using the AspectJ pointcut expression (more information is available in
<<core.adoc#aop, Aspect Oriented Programming with Spring>>). In the preceding example,
xref:core/aop.adoc[Aspect Oriented Programming with Spring]). In the preceding example,
all methods from the `BookService` are considered and the cache advice is applied to them.
The declarative XML caching supports all of the annotation-based model, so moving between

4
framework-docs/modules/ROOT/pages/integration/cache/jsr-107.adoc vendored
View File

@ -74,8 +74,8 @@ bean lifecycle callbacks, such as dependency injection.
Keys are generated by a `javax.cache.annotation.CacheKeyGenerator` that serves the
same purpose as Spring's `KeyGenerator`. By default, all method arguments are taken
into account, unless at least one parameter is annotated with `@CacheKey`. This is
similar to Spring's <<cache-annotations-cacheable-key, custom key generation
declaration>>. For instance, the following are identical operations, one using
similar to Spring's xref:integration/cache/annotations.adoc#cache-annotations-cacheable-key[custom key generation declaration]
. For instance, the following are identical operations, one using
Spring's abstraction and the other using JCache:
[source,java,indent=0,subs="verbatim,quotes"]

2
framework-docs/modules/ROOT/pages/integration/cache/store-configuration.adoc vendored
View File

@ -40,7 +40,7 @@ or eviction contracts.
== Ehcache-based Cache
Ehcache 3.x is fully JSR-107 compliant and no dedicated support is required for it. See
<<cache-store-configuration-jsr107>> for details.
xref:integration/cache/store-configuration.adoc#cache-store-configuration-jsr107[JSR-107 Cache] for details.
[[cache-store-configuration-caffeine]]

4
framework-docs/modules/ROOT/pages/integration/cache/strategies.adoc vendored
View File

@ -45,10 +45,10 @@ that is, the abstraction frees you from having to write the caching logic but do
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:
Spring provides xref:integration/cache/store-configuration.adoc[a few implementations] of that abstraction:
JDK `java.util.concurrent.ConcurrentMap` based caches, Gemfire cache,
https://github.com/ben-manes/caffeine/wiki[Caffeine], and JSR-107 compliant caches (such
as Ehcache 3.x). See <<cache-plug>> for more information on plugging in other cache
as Ehcache 3.x). See xref:integration/cache/plug.adoc[Plugging-in Different Back-end Caches] for more information on plugging in other cache
stores and providers.
IMPORTANT: The caching abstraction has no special handling for multi-threaded and

2
framework-docs/modules/ROOT/pages/integration/email.adoc
View File

@ -181,7 +181,7 @@ callback interface. In the following example, the `mailSender` property is of ty
----
NOTE: The mail code is a crosscutting concern and could well be a candidate for
refactoring into a <<core.adoc#aop, custom Spring AOP aspect>>, which could then
refactoring into a xref:core/aop.adoc[custom Spring AOP aspect], which could then
be run at appropriate joinpoints on the `OrderManager` target.
The Spring Framework's mail support ships with the standard JavaMail implementation.

6
framework-docs/modules/ROOT/pages/integration/jms/annotated.adoc
View File

@ -18,7 +18,7 @@ bean as a JMS listener endpoint. The following example shows how to use it:
The idea of the preceding example is that, whenever a message is available on the
`jakarta.jms.Destination` `myDestination`, the `processOrder` method is invoked
accordingly (in this case, with the content of the JMS message, similar to
what the <<jms-receiving-async-message-listener-adapter, `MessageListenerAdapter`>>
what the xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[`MessageListenerAdapter`]
provides).
The annotated endpoint infrastructure creates a message listener container
@ -67,7 +67,7 @@ container factory. See the javadoc of classes that implement
{api-spring-framework}/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`]
for details and examples.
If you prefer <<jms-namespace, XML configuration>>, you can use the `<jms:annotation-driven>`
If you prefer xref:integration/jms/namespace.adoc[XML configuration], you can use the `<jms:annotation-driven>`
element, as the following example shows:
[source,xml,indent=0,subs="verbatim,quotes"]
@ -197,7 +197,7 @@ annotate the payload with `@Valid` and configure the necessary validator, as the
[[jms-annotated-response]]
== Response Management
The existing support in <<jms-receiving-async-message-listener-adapter, `MessageListenerAdapter`>>
The existing support in xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[`MessageListenerAdapter`]
already lets your method have a non-`void` return type. When that is the case, the result of
the invocation is encapsulated in a `jakarta.jms.Message`, sent either in the destination specified
in the `JMSReplyTo` header of the original message or in the default destination configured on

6
framework-docs/modules/ROOT/pages/integration/jms/namespace.adoc
View File

@ -24,8 +24,8 @@ namespace elements, you need to reference the JMS schema, as the following examp
The namespace consists of three top-level elements: `<annotation-driven/>`, `<listener-container/>`
and `<jca-listener-container/>`. `<annotation-driven/>` enables the use of <<jms-annotated,
annotation-driven listener endpoints>>. `<listener-container/>` and `<jca-listener-container/>`
and `<jca-listener-container/>`. `<annotation-driven/>` enables the use of xref:integration/jms/annotated.adoc[annotation-driven listener endpoints]
. `<listener-container/>` and `<jca-listener-container/>`
define shared listener container configuration and can contain `<listener/>` child elements.
The following example shows a basic configuration for two listeners:
@ -42,7 +42,7 @@ The following example shows a basic configuration for two listeners:
The preceding example is equivalent to creating two distinct listener container bean
definitions and two distinct `MessageListenerAdapter` bean definitions, as shown
in <<jms-receiving-async-message-listener-adapter>>. In addition to the attributes shown
in xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[Using `MessageListenerAdapter`]. In addition to the attributes shown
in the preceding example, the `listener` element can contain several optional ones.
The following table describes all of the available attributes:

4
framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc
View File

@ -21,11 +21,11 @@ the receiver should wait before giving up waiting for a message.
NOTE: Spring also supports annotated-listener endpoints through the use of the `@JmsListener`
annotation and provides an open infrastructure to register endpoints programmatically.
This is, by far, the most convenient way to setup an asynchronous receiver.
See <<jms-annotated-support>> for more details.
See xref:integration/jms/annotated.adoc#jms-annotated-support[Enable Listener Endpoint Annotations] for more details.
In a fashion similar to a Message-Driven Bean (MDB) in the EJB world, the Message-Driven
POJO (MDP) acts as a receiver for JMS messages. The one restriction (but see
<<jms-receiving-async-message-listener-adapter>>) on an MDP is that it must implement
xref:integration/jms/receiving.adoc#jms-receiving-async-message-listener-adapter[Using `MessageListenerAdapter`]) on an MDP is that it must implement
the `jakarta.jms.MessageListener` interface. Note that, if your POJO receives messages
on multiple threads, it is important to ensure that your implementation is thread-safe.

12
framework-docs/modules/ROOT/pages/integration/jms/using.adoc
View File

@ -167,9 +167,9 @@ operations that do not refer to a specific destination.
One of the most common uses of JMS messages in the EJB world is to drive message-driven
beans (MDBs). Spring offers a solution to create message-driven POJOs (MDPs) in a way
that does not tie a user to an EJB container. (See <<jms-receiving-async>> for detailed
that does not tie a user to an EJB container. (See xref:integration/jms/receiving.adoc#jms-receiving-async[Asynchronous reception: Message-Driven POJOs] for detailed
coverage of Spring's MDP support.) Since Spring Framework 4.1, endpoint methods can be
annotated with `@JmsListener` -- see <<jms-annotated>> for more details.
annotated with `@JmsListener` -- see xref:integration/jms/annotated.adoc[Annotation-driven Listener Endpoints] for more details.
A message listener container is used to receive messages from a JMS message queue and
drive the `MessageListener` that is injected into it. The listener container is
@ -184,8 +184,8 @@ boilerplate JMS infrastructure concerns to the framework.
There are two standard JMS message listener containers packaged with Spring, each with
its specialized feature set.
* <<jms-mdp-simple, `SimpleMessageListenerContainer`>>
* <<jms-mdp-default, `DefaultMessageListenerContainer`>>
* xref:integration/jms/using.adoc#jms-mdp-simple[`SimpleMessageListenerContainer`]
* xref:integration/jms/using.adoc#jms-mdp-default[`DefaultMessageListenerContainer`]
[[jms-mdp-simple]]
=== Using `SimpleMessageListenerContainer`
@ -236,7 +236,7 @@ a simple `BackOff` implementation retries every five seconds. You can specify
a custom `BackOff` implementation for more fine-grained recovery options. See
{api-spring-framework}/util/backoff/ExponentialBackOff.html[`ExponentialBackOff`] for an example.
NOTE: Like its sibling (<<jms-mdp-simple, `SimpleMessageListenerContainer`>>),
NOTE: Like its sibling (xref:integration/jms/using.adoc#jms-mdp-simple[`SimpleMessageListenerContainer`]),
`DefaultMessageListenerContainer` supports native JMS transactions and allows for
customizing the acknowledgment mode. If feasible for your scenario, This is strongly
recommended over externally managed transactions -- that is, if you can live with
@ -263,7 +263,7 @@ reliability needs (for example, for reliable queue handling and durable topic su
Spring provides a `JmsTransactionManager` that manages transactions for a single JMS
`ConnectionFactory`. This lets JMS applications leverage the managed-transaction
features of Spring, as described in
<<data-access.adoc#transaction, Transaction Management section of the Data Access chapter>>.
xref:data-access/transaction.adoc[Transaction Management section of the Data Access chapter].
The `JmsTransactionManager` performs local resource transactions, binding a JMS
Connection/Session pair from the specified `ConnectionFactory` to the thread.
`JmsTemplate` automatically detects such transactional resources and operates

Some files were not shown because too many files have changed in this diff Show More