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

Fix link references between documents

Browse Source 
Issue: SPR-14997
This commit is contained in:
Brian Clozel
2017-03-29 14:20:12 +02:00
parent 924adaec6c
commit dea4825a9f
12 changed files with 275 additions and 285 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
src/docs/asciidoc/appendix.adoc
View File

@@ -3,7 +3,8 @@
:doc-root: https://docs.spring.io
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
:wiki-spring-framework: https://github.com/spring-projects/spring-framework/wiki
:toc: left
:toclevels: 2
[[spring-whats-new]]
== What's New in the Spring Framework
@@ -36,13 +37,14 @@ the respective sections of the reference manual.
=== Classic ORM usage
This section documents the classic usage patterns that you might encounter in a legacy
Spring application. For the currently recommended usage patterns, please refer to the
<<orm,ORM>> chapter.
<<data-access.adoc#orm,ORM>> chapter.
[[classic-spring-hibernate]]
==== Hibernate
For the currently recommended usage patterns for Hibernate see <<orm-hibernate>>.
For the currently recommended usage patterns for Hibernate see
<<data-access.adoc#orm-hibernate,the Hibernate section>>.
[[orm-hibernate-template]]
@@ -238,8 +240,8 @@ used.
[[classic-spring-aysnc-messages]]
==== Asynchronous Message Reception
<<jms-receiving-async-message-listener-adapter,MessageListenerAdapter's>> are used in
conjunction with Spring's <<jms-mdp,message listener containers>> to support
<<integration.adoc#jms-receiving-async-message-listener-adapter,MessageListenerAdapter's>> are used in
conjunction with Spring's <<integration.adoc#jms-mdp,message listener containers>> to support
asynchronous message reception by exposing almost any class as a Message-driven POJO. If
you are using the JMS 1.0.2 API, you will want to use the 1.0.2 specific classes such as
`MessageListenerAdapter102`, `SimpleMessageListenerContainer102`, and
@@ -264,7 +266,7 @@ differentiate between a `javax.jms.QueueConnection` and a `javax.jmsTopicConnect
==== Transaction Management
In a JMS 1.0.2 environment the class `JmsTransactionManager102` provides support for
managing JMS transactions for a single Connection Factory. Please refer to the reference
documentation on <<jms-tx,JMS Transaction Management>> for more information on this
documentation on <<integration.adoc#jms-tx,JMS Transaction Management>> for more information on this
functionality.
@@ -273,7 +275,7 @@ functionality.
== Classic Spring AOP Usage
In this appendix we discuss the lower-level Spring AOP APIs and the AOP support used in
Spring 1.2 applications. For new applications, we recommend the use of the Spring 2.0
AOP support described in the <<aop,AOP>> chapter, but when working with existing
AOP support described in the <<core.adoc#aop,AOP>> chapter, but when working with existing
applications, or when reading books and articles, you may come across Spring 1.2 style
examples. Spring 2.0 is fully backwards compatible with Spring 1.2 and everything
described in this appendix is fully supported in Spring 2.0.
@@ -1037,14 +1039,16 @@ 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 (see below and also <<aop-pfb-proxy-types>>).
* Specify whether to use CGLIB (see below and also <<core.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:
* `proxyTargetClass`: `true` if the target class is to be proxied, rather than the
target class' interfaces. If this property value is set to `true`, then CGLIB proxies
will be created (but see also below <<aop-pfb-proxy-types>>).
will be created (but see also below
<<core.adoc#aop-pfb-proxy-types,JDK- and CGLIB-based proxies>>).
* `optimize`: controls whether or not aggressive optimizations are applied to proxies
__created via CGLIB__. One should not blithely use this setting unless one fully
understands how the relevant AOP proxy handles optimization. This is currently used
@@ -1067,7 +1071,8 @@ Some key properties are inherited from `org.springframework.aop.framework.ProxyC
Other properties specific to `ProxyFactoryBean` include:
* `proxyInterfaces`: array of String interface names. If this isn't supplied, a CGLIB
proxy for the target class will be used (but see also below <<aop-pfb-proxy-types>>).
proxy for the target class will be used (but see also below
<<core.adoc#aop-pfb-proxy-types,JDK- and CGLIB-based proxies>>).
* `interceptorNames`: 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 will be the first to be able to intercept the
@@ -1079,7 +1084,8 @@ factories. You can't mention bean references here since doing so would result in
You can append an interceptor name with an asterisk ( `*`). This will result in the
application of all advisor beans with names starting with the part before the asterisk
to be applied. An example of using this feature can be found in <<aop-global-advisors>>.
to be applied. An example of using this feature can be found in
<<core.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
@@ -1377,7 +1383,7 @@ this case, the transaction propagation settings:
Note that in the example above, we have explicitly marked the parent bean definition as
__abstract__ by using the __abstract__ attribute, as described
<<beans-child-bean-definitions,previously>>, so that it may not actually ever be
<<core.adoc#beans-child-bean-definitions,previously>>, so that it may not actually ever be
instantiated. Application contexts (but not simple bean factories) will by default
pre-instantiate all singletons. It is therefore important (at least for singleton beans)
that if you have a (parent) bean definition which you intend to use only as a template,
@@ -2462,7 +2468,7 @@ Before...
The above configuration uses a Spring `FactoryBean` implementation, the
`PropertiesFactoryBean`, to instantiate a `java.util.Properties` instance with values
loaded from the supplied <<resources, `Resource`>> location).
loaded from the supplied <<core.adoc#resources, `Resource`>> location).
After...
@@ -2907,8 +2913,8 @@ The `lang` tags deal with exposing objects that have been written in a dynamic l
such as JRuby or Groovy as beans in the Spring container.
These tags (and the dynamic language support) are comprehensively covered in the chapter
entitled <<dynamic-language>>. Please do consult that chapter for full details on this
support and the `lang` tags themselves.
entitled <<integration.adoc#dynamic-language,Dynamic language support>>.
Please do consult that chapter for full details on this support and the `lang` tags themselves.
In the interest of completeness, to use the tags in the `lang` schema, you need to have
the following preamble at the top of your Spring XML configuration file; the text in the
@@ -2934,9 +2940,10 @@ are available to you.
==== the jms schema
The `jms` tags deal with configuring JMS-related beans such as Spring's
<<jms-mdp,MessageListenerContainers>>. These tags are detailed in the section of the
<<jms,JMS chapter>> entitled <<jms-namespace>>. Please do consult that chapter for full
details on this support and the `jms` tags themselves.
<<integration.adoc#jms-mdp,MessageListenerContainers>>. These tags are detailed in the
section of the <<integration.adoc#jms,JMS chapter>> entitled <<integration.adoc#jms-namespace,
JMS namespace support>>. Please do consult that chapter for full details on this support
and the `jms` tags themselves.
In the interest of completeness, to use the tags in the `jms` schema, you need to have
the following preamble at the top of your Spring XML configuration file; the text in the
@@ -2962,7 +2969,8 @@ are available to you.
==== the tx (transaction) schema
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 <<transaction>>.
for transactions. These tags are covered in the chapter entitled
<<data-access.adoc#transaction,Transaction Management>>.
[TIP]
====
@@ -3010,7 +3018,8 @@ using AOP). The above XML snippet contains the relevant lines needed to referenc
The `aop` tags deal with configuring all things AOP in Spring: this includes 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 <<aop>>.
These tags are comprehensively covered in the chapter entitled <<core.adoc#aop,
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
@@ -3064,8 +3073,8 @@ The `context` schema was only introduced in Spring 2.5.
===== <property-placeholder/>
This element activates the replacement of `${...}` placeholders, resolved against the
specified properties file (as a <<resources,Spring resource location>>). This element is
a convenience mechanism that sets up a<<beans-factory-placeholderconfigurer,
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,
`PropertyPlaceholderConfigurer`>> for you; if you need more control over the
`PropertyPlaceholderConfigurer`, just define one yourself explicitly.
@@ -3074,8 +3083,8 @@ a convenience mechanism that sets up a<<beans-factory-placeholderconfigurer,
===== <annotation-config/>
Activates the Spring infrastructure for various annotations to be detected in bean
classes: Spring's <<beans-required-annotation, `@Required`>> and
<<beans-annotation-config, `@Autowired`>>, as well as JSR 250's `@PostConstruct`,
classes: Spring's <<core.adoc#beans-required-annotation, `@Required`>> and
<<core.adoc#beans-annotation-config, `@Autowired`>>, as well as JSR 250's `@PostConstruct`,
`@PreDestroy` and `@Resource` (if available), and JPA's `@PersistenceContext` and
`@PersistenceUnit` (if available). Alternatively, you can choose to activate the
individual `BeanPostProcessors` for those annotations explicitly.
@@ -3083,33 +3092,37 @@ individual `BeanPostProcessors` for those annotations explicitly.
[NOTE]
====
This element does __not__ activate processing of Spring's
<<transaction-declarative-annotations, `@Transactional`>> annotation. Use the
<<tx-decl-explained, `<tx:annotation-driven/>`>> element for that purpose.
<<data-access.adoc#transaction-declarative-annotations, `@Transactional`>> annotation. Use the
<<data-access.adoc#tx-decl-explained, `<tx:annotation-driven/>`>> element for that purpose.
====
[[xsd-config-body-schemas-context-component-scan]]
===== <component-scan/>
This element is detailed in <<beans-annotation-config>>.
This element is detailed in <<core.adoc#beans-annotation-config,
Annotation-based container configuration>>.
[[xsd-config-body-schemas-context-ltw]]
===== <load-time-weaver/>
This element is detailed in <<aop-aj-ltw>>.
This element is detailed in <<core.adoc#aop-aj-ltw,
Load-time weaving with AspectJ in the Spring Framework>>.
[[xsd-config-body-schemas-context-sc]]
===== <spring-configured/>
This element is detailed in <<aop-atconfigurable>>.
This element is detailed in <<core.adoc#aop-atconfigurable,
Using AspectJ to dependency inject domain objects with Spring>>.
[[xsd-config-body-schemas-context-mbe]]
===== <mbean-export/>
This element is detailed in <<jmx-context-mbeanexport>>.
This element is detailed in <<integration.adoc#jmx-context-mbeanexport,
Configuring annotation based MBean export>>.
@@ -3134,8 +3147,9 @@ distribution.
==== the jdbc schema
The `jdbc` tags allow you to quickly configure an embedded database or initialize an
existing data source. These tags are documented in <<jdbc-embedded-database-support>>
and <<jdbc-intializing-datasource>> respectively.
existing data source. These tags are documented in
<<data-access.adoc#jdbc-embedded-database-support,Embedded database support>>
and <<data-access.adoc#jdbc-initializing-datasource,Initializing a DataSource>> respectively.
To use the tags 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 the
@@ -3161,7 +3175,8 @@ correct schema so that the tags in the `jdbc` namespace are available to you.
The `cache` tags can be used to enable support for Spring's `@CacheEvict`, `@CachePut`
and `@Caching` annotations. It it also supports declarative XML-based caching. See
<<cache-annotation-enable>> and <<cache-declarative-xml>> for details.
<<integration.adoc#cache-annotation-enable,Enable caching annotations>> and
<<integration.adoc#cache-declarative-xml,Declarative XML-based caching>> for details.
To use the tags 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
@@ -3188,7 +3203,8 @@ the correct schema so that the tags in the `cache` namespace are available to yo
Last but not least we have the tags in the `beans` schema. These are the same tags that
have been in Spring since the very dawn of the framework. Examples of the various tags
in the `beans` schema are not shown here because they are quite comprehensively covered
in <<beans-factory-properties-detailed>> (and indeed in that entire <<beans,chapter>>).
in <<core.adoc#beans-factory-properties-detailed,Dependencies and configuration in detail>>
(and indeed in that entire <<core.adoc#beans,chapter>>).
One thing that is new to the beans tags themselves in Spring 2.0 is the idea of
arbitrary bean metadata. In Spring 2.0 it is now possible to add zero or more key /
@@ -3365,7 +3381,7 @@ The `NamespaceHandler` interface is pretty simple in that it features just three
* `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<<beans-factory-scopes,out-of-the-box scopes Spring 2.0 supports>>. We'll start by
the<<core.adoc#beans-factory-scopes,out-of-the-box scopes Spring 2.0 supports>>. We'll start by
highlighting a simple example, without using decoration, after which we will show
decoration in a somewhat more advanced example.

15
src/docs/asciidoc/core.adoc
View File

@@ -2,9 +2,9 @@
= Core Technologies
:doc-root: https://docs.spring.io
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
:toc: left
:toclevels: 2
[partintro]
--
This part of the reference documentation covers all of those technologies that are
absolutely integral to the Spring Framework.
@@ -19,17 +19,6 @@ Coverage of Spring's integration with AspectJ (currently the richest - in terms
features - and certainly most mature AOP implementation in the Java enterprise space) is
also provided.
* <<beans>>
* <<resources>>
* <<validation>>
* <<expressions>>
* <<aop>>
* <<aop-api>>
--
include::core/core-beans.adoc[leveloffset=+1]
include::core/core-resources.adoc[leveloffset=+1]

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

@@ -259,8 +259,9 @@ element:
<aop:aspectj-autoproxy/>
----
This assumes that you are using schema support as described in <<xsd-configuration>>. See
<<xsd-config-body-schemas-aop>> for how to import the tags in the `aop` namespace.
This assumes that you are using schema support as described in <<appendix.adoc#xsd-configuration,
XML Schema-based configuration>>. See <<appendix.adoc#xsd-config-body-schemas-aop, the AOP schema>>
for how to import the tags in the `aop` namespace.
@@ -572,7 +573,7 @@ write:
----
The `<aop:config>` and `<aop:advisor>` elements are discussed in <<aop-schema>>. The
transaction elements are discussed in <<transaction>>.
transaction elements are discussed in <<data-access.adoc#transaction, Transaction Management>>.
[[aop-pointcuts-examples]]
@@ -1552,7 +1553,9 @@ the new __syntax__ and refer the reader to the discussion in the previous sectio
of advice parameters.
To use the aop namespace tags described in this section, you need to import the
`spring-aop` schema as described in <<xsd-configuration>>. See <<xsd-config-body-schemas-aop>>
`spring-aop` schema as described in <<appendix.adoc#xsd-configuration,
XML Schema-based configuration>>.
See <<appendix.adoc#xsd-config-body-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
@@ -2790,7 +2793,7 @@ using Java based configuration simply add `@EnableSpringConfigured` to any
}
----
If you prefer XML based configuration, the Spring <<xsd-config-body-schemas-context,
If you prefer XML based configuration, the Spring <<appendix.adoc#xsd-config-body-schemas-context,
`context` namespace>> defines a convenient `context:spring-configured` element:
[source,xml,indent=0]
@@ -3030,8 +3033,8 @@ profiling tool to that specific area immediately afterwards.
[NOTE]
====
The example presented here uses XML style configuration, it is also possible to
configure and use @AspectJ with <<beans-java,Java Configuration>>. Specifically the
`@EnableLoadTimeWeaving` annotation can be used as an alternative to
configure and use @AspectJ with <<beans-java,Java Configuration>>.
Specifically the `@EnableLoadTimeWeaving` annotation can be used as an alternative to
`<context:load-time-weaver/>` (see <<aop-aj-ltw-spring,below>> for details).
====

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

@@ -6,7 +6,8 @@
== Introduction to the Spring IoC container and beans
This chapter covers the Spring Framework implementation of the Inversion of Control
(IoC) footnote:[See pass:specialcharacters,macros[<<background-ioc>>] ] principle. IoC
(IoC) footnote:[See pass:specialcharacters,macros[<<overview.adoc#background-ioc,
Inversion of Control>>] ] principle. IoC
is also known as __dependency injection__ (DI). It is a process whereby objects define
their dependencies, that is, the other objects they work with, only through constructor
arguments, arguments to a factory method, or properties that are set on the object
@@ -1042,8 +1043,8 @@ 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 <<jmx,JMX MBeans>> is therefore a compelling use case for setter
injection.
later. Management through <<integration.adoc#jmx,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
with third-party classes for which you do not have the source, the choice is made for you.
@@ -1718,8 +1719,8 @@ The above configuration is equivalent to the following Java code:
The p-namespace enables you to use the `bean` element's attributes, instead of nested
`<property/>` elements, to describe your property values and/or collaborating beans.
Spring supports extensible configuration formats <<xsd-configuration,with namespaces>>, which are
based on an XML Schema definition. The `beans` configuration format discussed in this
Spring supports extensible configuration formats <<appendix.adoc#xsd-configuration,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.
@@ -2429,7 +2430,7 @@ The following scopes are supported out of the box. You can also create
| Scopes a single bean definition to the lifecycle of a `ServletContext`. Only valid in
the context of a web-aware Spring `ApplicationContext`.
| <<websocket-stomp-websocket-scope,websocket>>
| <<web.adoc#websocket-stomp-websocket-scope,websocket>>
| Scopes a single bean definition to the lifecycle of a `WebSocket`. Only valid in
the context of a web-aware Spring `ApplicationContext`.
|===
@@ -2779,11 +2780,12 @@ 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
<<xsd-configuration>>). Why do definitions of beans scoped at the `request`, `session`
and custom-scope levels require the `<aop:scoped-proxy/>` element? Let's examine the
following singleton bean definition and contrast it with what you need to define for
the aforementioned scopes (note that the following `userPreferences` bean definition
as it stands is __incomplete__).
<<appendix.adoc#xsd-configuration, XML Schema-based configuration>>).
Why do definitions of beans scoped at the `request`, `session` and custom-scope
levels require the `<aop:scoped-proxy/>` element?
Let's examine the following singleton bean definition and contrast it with
what you need to define for the aforementioned scopes (note that the following
`userPreferences` bean definition as it stands is __incomplete__).
[source,xml,indent=0]
[subs="verbatim,quotes"]
@@ -3583,7 +3585,7 @@ dependency type:
| `BootstrapContextAware`
| Resource adapter `BootstrapContext` the container runs in. Typically available only in
JCA aware ``ApplicationContext``s
| <<cci>>
| <<integration.adoc#cci, JCA CCI>>
| `LoadTimeWeaverAware`
| Defined __weaver__ for processing class definition at load time
@@ -3596,7 +3598,7 @@ dependency type:
| `NotificationPublisherAware`
| Spring JMX notification publisher
| <<jmx-notifications>>
| <<integration.adoc#jmx-notifications, Notifications>>
| `ResourceLoaderAware`
| Configured loader for low-level access to resources
@@ -3605,12 +3607,12 @@ dependency type:
| `ServletConfigAware`
| Current `ServletConfig` the container runs in. Valid only in a web-aware Spring
`ApplicationContext`
| <<mvc>>
| <<web.adoc#mvc, Spring MVC>>
| `ServletContextAware`
| Current `ServletContext` the container runs in. Valid only in a web-aware Spring
`ApplicationContext`
| <<mvc>>
| <<web.adoc#mvc, Spring MVC>>
|===
Note again that usage of these interfaces ties your code to the Spring API and does not
@@ -3884,7 +3886,7 @@ Notice how the `InstantiationTracingBeanPostProcessor` is simply defined. It doe
even have a name, and because it is a bean it can be dependency-injected just like 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
<<dynamic-language>>.)
<<integration.adoc#dynamic-language, Dynamic language support>>.)
The following simple Java application executes the preceding code and configuration:
@@ -4266,7 +4268,7 @@ as well as the aforementioned
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
<<mvc-servlet>> for more information.
<<web.adoc#mvc-servlet, The DispatcherServlet>> for more information.
====
@@ -5231,7 +5233,7 @@ than using the traditional XML files. Take a look at the `@Configuration`, `@Bea
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
<<orm-exception-translation>>.
<<data-access.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.
@@ -5323,7 +5325,7 @@ Or with an overridden value for the `proxyMode` as follows:
}
----
For further details, consult the <<annotation-programming-model,Spring Annotation Programming Model>>.
For further details, consult the <<appendix.adoc#annotation-programming-model,Spring Annotation Programming Model>>.
[[beans-scanning-autodetection]]
@@ -7693,7 +7695,8 @@ In addition, profiles may also be activated declaratively through the
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
profiles can be declared via the `@ActiveProfiles` annotation in the `spring-test` module
(see <<testcontext-ctx-management-env-profiles>>).
(see <<testing.adoc#testcontext-ctx-management-env-profiles,
Context configuration with environment profiles>>).
Note that profiles are not an "either-or" proposition; it is possible to activate multiple
profiles at once. Programmatically, simply provide multiple profile names to the
@@ -7936,9 +7939,10 @@ Alternatively for XML configuration use the `context:load-time-weaver` element:
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 <<orm-jpa,Spring's JPA
support>> where load-time weaving may be necessary for JPA class transformation. Consult
the `LocalContainerEntityManagerFactoryBean` javadocs for more detail. For more on
weaver instance. This is particularly useful in combination with
<<data-acess.adoc#orm-jpa,Spring's JPA support>> where load-time weaving may be necessary
for JPA class transformation.
Consult the `LocalContainerEntityManagerFactoryBean` javadocs for more detail. For more on
AspectJ load-time weaving, see <<aop-aj-ltw>>.
@@ -8483,7 +8487,7 @@ events instead.
==== Asynchronous Listeners
If you want a particular listener to process events asynchronously, simply reuse the
<<scheduling-annotation-support-async,regular `@Async` support>>:
<<integration.adoc#scheduling-annotation-support-async,regular `@Async` support>>:
[source,java,indent=0]
[subs="verbatim,quotes"]

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

@@ -1,10 +1,7 @@
[[validation]]
= Validation, Data Binding, and Type Conversion
[[validation-introduction]]
== Introduction
@@ -666,7 +663,7 @@ Next we configure a `CustomEditorConfigurer` and inject an instance of our
----
Finally, and in a bit of a departure from the focus of this chapter, for those of you
using <<mvc,Spring's MVC web framework>>, using `PropertyEditorRegistrars` in
using <<web.adoc#mvc,Spring's MVC web framework>>, using `PropertyEditorRegistrars` in
conjunction with data-binding `Controllers` (such as `SimpleFormController`) can be very
convenient. Find below an example of using a `PropertyEditorRegistrar` in the
implementation of an `initBinder(..)` method:
@@ -961,7 +958,7 @@ either of the Converter, ConverterFactory, or GenericConverter interfaces.
----
It is also common to use a ConversionService within a Spring MVC application. See
<<mvc-config-conversion>> in the Spring MVC chapter.
<<web.adoc#mvc-config-conversion, 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
@@ -1313,7 +1310,7 @@ converter and formatter registration.
[[format-configuring-formatting-mvc]]
=== Configuring Formatting in Spring MVC
See <<mvc-config-conversion>> in the Spring MVC chapter.
See <<web.adoc#mvc-config-conversion, Conversion and Formatting>> in the Spring MVC chapter.
@@ -1406,7 +1403,8 @@ If you are using Spring MVC remember to explicitly configure the conversion serv
is used. For Java based `@Configuration` this means extending the
`WebMvcConfigurationSupport` class and overriding the `mvcConversionService()` method.
For XML you should use the `'conversion-service'` attribute of the
`mvc:annotation-driven` element. See <<mvc-config-conversion>> for details.
`mvc:annotation-driven` element.
See <<web.adoc#mvc-config-conversion, Conversion and Formatting>> for details.
@@ -1635,5 +1633,5 @@ locally on a DataBinder instance. See <<validation-mvc-configuring>>.
[[validation-mvc]]
=== Spring MVC 3 Validation
See <<mvc-config-validation>> in the Spring MVC chapter.
See <<web.adoc#mvc-config-validation, Validation>> in the Spring MVC chapter.

67
src/docs/asciidoc/data-access.adoc
View File

@@ -2,9 +2,9 @@
= Data Access
:doc-root: https://docs.spring.io
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
:toc: left
:toclevels: 2
[partintro]
--
This part of the reference documentation is concerned with data access and the
interaction between the data access layer and the business or service layer.
@@ -12,14 +12,6 @@ Spring's comprehensive transaction management support is covered in some detail,
followed by thorough coverage of the various data access frameworks and technologies
that the Spring Framework integrates with.
* <<transaction>>
* <<dao>>
* <<jdbc>>
* <<orm>>
* <<oxm>>
--
[[transaction]]
== Transaction Management
@@ -309,9 +301,11 @@ infrastructure.
[NOTE]
====
The above definition of the `dataSource` bean uses the `<jndi-lookup/>` tag from the
`jee` namespace. For more information on schema-based configuration, see <<xsd-configuration>>,
and for more information on the `<jee/>` tags see the section entitled
<<xsd-config-body-schemas-jee>>.
`jee` namespace. For more information on schema-based configuration, see
<<appendix.adoc#xsd-configuration, XML Schema-based configuration>>,
and for more information on the `<jee/>`
tags see the section entitled <<appendix.adoc#xsd-config-body-schemas-jee,
the JEE schema>>.
====
You can also use Hibernate local transactions easily, as shown in the following
@@ -540,7 +534,7 @@ 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
<<aop-understanding-aop-proxies,__via AOP proxies__>>, and that the transactional advice
<<core.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 `PlatformTransactionManager` implementation to drive
@@ -548,7 +542,7 @@ transactions __around method invocations__.
[NOTE]
====
Spring AOP is covered in <<aop>>.
Spring AOP is covered in <<core.adoc#aop, the AOP section>>.
====
Conceptually, calling a method on a transactional proxy looks like this...
@@ -703,7 +697,7 @@ using an advisor. The result indicates that at the execution of a `fooServiceOpe
the advice defined by `txAdvice` will be run.
The expression defined within the `<aop:pointcut/>` element is an AspectJ pointcut
expression; see <<aop>> for more details on pointcut expressions in Spring.
expression; see <<core.adoc#aop, 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
do this is simply to change the pointcut expression to match any operation in your
@@ -721,7 +715,7 @@ service layer. For example:
[NOTE]
====
__In this example it is assumed that all your service interfaces are defined in the
`x.y.service` package; see <<aop>> for more details.__
`x.y.service` package; see <<core.adoc#aop, the AOP section>> for more details.__
====
Now that we've analyzed the configuration, you may be asking yourself, "__Okay... but
@@ -1210,8 +1204,8 @@ 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 load-time weaving (or compile-time
weaving) enabled. (See <<aop-aj-ltw-spring>> for details on how to set up load-time
weaving.)
weaving) enabled. (See <<core.adoc#aop-aj-ltw-spring, Spring configuration>>
for details on how to set up load-time weaving.)
| `proxy-target-class`
| `proxyTargetClass`
@@ -1220,16 +1214,16 @@ any kind of method.
for classes annotated with the `@Transactional` annotation. If the
`proxy-target-class` attribute is set to `true`, then 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 <<aop-proxying>> for a detailed examination
of the different proxy types.)
interface-based proxies are created. (See <<core.adoc#aop-proxying, Proxying mechanisms>>
for a detailed examination of the different proxy types.)
| `order`
| `order`
| 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 <<aop-ataspectj-advice-ordering>>.) No specified ordering means that the
AOP subsystem determines the order of the advice.
advice, see <<core.adoc#aop-ataspectj-advice-ordering, Advice ordering>>.)
No specified ordering means that the AOP subsystem determines the order of the advice.
|===
[NOTE]
@@ -1248,7 +1242,7 @@ different proxy types.)
`@Transactional` on beans in the same application context they are defined in. This
means that, if you put annotation driven configuration in a `WebApplicationContext` for
a `DispatcherServlet`, it only checks for `@Transactional` beans in your controllers,
and not your services. See <<mvc-servlet>> for more information.
and not your services. See <<web.adoc#mvc-servlet, MVC>> for more information.
====
The most derived location takes precedence when evaluating the transactional settings
@@ -1395,7 +1389,7 @@ used if no specifically qualified PlatformTransactionManager bean is found.
[[tx-custom-attributes]]
===== Custom shortcut annotations
If you find you are repeatedly using the same attributes with `@Transactional` on many
different methods, then <<beans-meta-annotations,Spring's meta-annotation support>> allows
different methods, then <<core.adoc#beans-meta-annotations,Spring's meta-annotation support>> allows
you to define custom shortcut annotations for your specific use cases. For example,
defining the following annotations
@@ -1511,13 +1505,13 @@ When you invoke the `updateFoo(Foo)` method, you want to see the following actio
[NOTE]
====
This chapter is not concerned with explaining AOP in any great detail (except as it
applies to transactions). See <<aop>> for detailed coverage of the following AOP
applies to transactions). See <<core.adoc#aop, AOP>> for detailed coverage of the following AOP
configuration and AOP in general.
====
Here is the code for a simple profiling aspect discussed above. The ordering of advice
is controlled through the `Ordered` interface. For full details on advice ordering, see
<<aop-ataspectj-advice-ordering>>.
<<core.adoc#aop-ataspectj-advice-ordering, Advice ordering>>.
.
[source,java,indent=0]
[subs="verbatim,quotes"]
@@ -1694,7 +1688,7 @@ you how to do it programmatically.
[NOTE]
====
Prior to continuing, you may want to read <<transaction-declarative-annotations>> and
<<aop>> respectively.
<<core.adoc#aop, AOP>> respectively.
====
[source,java,indent=0]
@@ -1724,8 +1718,8 @@ annotated, regardless of visibility.
To weave your applications with the `AnnotationTransactionAspect` you must either build
your application with AspectJ (see the
http://www.eclipse.org/aspectj/doc/released/devguide/index.html[AspectJ Development
Guide]) or use load-time weaving. See <<aop-aj-ltw>> for a discussion of load-time
weaving with AspectJ.
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.
@@ -4689,7 +4683,7 @@ Embedded databases provide a lightweight way to test data access code. The follo
data access integration test template that uses an embedded database. Using a template
like this 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 <<testcontext-framework,Spring TestContext
shared within a test suite, consider using the <<testing.adoc#testcontext-framework,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>>.
@@ -4935,8 +4929,8 @@ tools through Dependency Injection. They can participate in Spring's resource an
transaction management, and they comply with Spring's generic transaction and DAO
exception hierarchies. The recommended integration style is to code DAOs against plain
Hibernate or JPA APIs. The older style of using Spring's DAO templates is no longer
recommended; however, coverage of this style can be found in the <<classic-spring-orm>>
in the appendices.
recommended; however, coverage of this style can be found in the
<<appendix.adoc#classic-spring-orm, Classic ORM usage>> in the appendices.
Spring adds significant enhancements to the ORM layer of your choice when you create
data access applications. You can leverage as much of the integration support as you
@@ -5727,9 +5721,10 @@ Spring provides a number of `LoadTimeWeaver` implementations for various environ
allowing `ClassTransformer` instances to be applied only __per class loader__ and not
per VM.
Refer to <<aop-aj-ltw-spring>> in the AOP chapter for more insight regarding the
`LoadTimeWeaver` implementations and their setup, either generic or customized to
various platforms (such as Tomcat, WebLogic, GlassFish, Resin and JBoss).
Refer to <<core.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, WebLogic, GlassFish,
Resin and JBoss).
As described in the aforementioned section, you can configure a context-wide
`LoadTimeWeaver` using the `@EnableLoadTimeWeaving` annotation of

31
src/docs/asciidoc/index.adoc
View File

@@ -4,16 +4,33 @@ The Spring Framework team and contributors https://github.com/spring-projects/sp
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
<<overview.adoc#spring-introduction,Overview>>
The Spring Framework is a lightweight solution and a potential one-stop-shop for
building your enterprise-ready applications. However, Spring is modular, allowing you to
use only those parts that you need, without having to bring in the rest. You can use the
IoC container, with any web framework on top, but you can also use only the
<<data-access.adoc#orm-hibernate,Hibernate integration code>> or the
<<data-access.adoc#jdbc-introduction,JDBC abstraction layer>>. The Spring Framework supports declarative
transaction management, remote access to your logic through RMI or web services, and various
options for persisting your data.
It offers a full-featured web frameworks such as <<web.adoc#mvc-introduction,Spring MVC>>
and <<web.adoc#web-reactive, Spring WebFlux>>; and it enables you to
integrate <<core.adoc#aop-introduction,AOP>> transparently into your software.
<<core.adoc#spring-core,Core>>
This document is a reference guide to Spring Framework features. Questions on the
Framework itself should be asked on StackOverflow (see https://spring.io/questions[]).
<<testing.adoc#testing,Testing>>
This reference document provides the following sections:
<<data-access.adoc#spring-data-tier,Data Access>>
* <<overview.adoc#spring-introduction,Overview of the Spring Framework>>
<<web.adoc#spring-web,Web>>
* <<core.adoc#spring-core,Core concepts such as IoC and AOP>>
<<integration.adoc#spring-integration,Integration>>
* <<testing.adoc#testing,Testing with Spring>>
<<appendix.adoc#spring-appendices,Appendix>>
* <<data-access.adoc#spring-data-tier,Data Access and transaction management>>
* <<web.adoc#spring-web,Web frameworks>>
* <<integration.adoc#spring-integration,Integration with other technologies>>
* <<appendix.adoc#spring-appendices,Appendix>>

90
src/docs/asciidoc/integration.adoc
View File

@@ -4,23 +4,12 @@
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
:doc-spring-amqp: {doc-root}/spring-amqp/docs/current/reference
:doc-spring-gemfire: {doc-root}/spring-gemfire/docs/current/reference
:toc: left
:toclevels: 2
[partintro]
--
This part of the reference documentation covers the Spring Framework's integration with
a number of Java EE (and related) technologies.
* <<remoting>>
* <<ejb>>
* <<jms>>
* <<jmx>>
* <<cci>>
* <<mail>>
* <<scheduling>>
* <<dynamic-language>>
* <<cache>>
--
[[remoting]]
== Remoting and web services using Spring
@@ -1960,10 +1949,11 @@ message listener (including database operations etc).
==== Transaction management
Spring provides a `JmsTransactionManager` that manages transactions for a single JMS
`ConnectionFactory`. This allows JMS applications to leverage the managed transaction
features of Spring as described in <<transaction>>. 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 on them accordingly.
features of Spring as described in <<data-access.adoc#transaction,Transaction Management>>.
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
on them accordingly.
In a Java EE environment, the `ConnectionFactory` will pool Connections and Sessions, so
those resources are efficiently reused across transactions. In a standalone environment,
@@ -3218,10 +3208,10 @@ are exposed as attributes and all __public__ methods (bar those inherited from t
[NOTE]
====
`MBeanExporter` is a `Lifecycle` bean (see <<beans-factory-lifecycle-processor>>)
and MBeans are exported as late as possible during the application lifecycle by default. It
is possible to configure the `phase` at which the export happens or disable automatic
registration by setting the `autoStartup` flag.
`MBeanExporter` is a `Lifecycle` bean (see <<core.adoc#beans-factory-lifecycle-processor,
Startup and shutdown callbacks>>) and MBeans are exported as late as possible during
the application lifecycle by default. It is possible to configure the `phase` at which
the export happens or disable automatic registration by setting the `autoStartup` flag.
====
@@ -3306,7 +3296,7 @@ be used:
For platforms/cases where the existing `MBeanServer` has a dynamic (or unknown)
`agentId` which is retrieved through lookup methods, one should use
<<beans-factory-class-static-factory-method,factory-method>>:
<<core.adoc#beans-factory-class-static-factory-method,factory-method>>:
[source,xml,indent=0]
[subs="verbatim,quotes"]
@@ -5688,7 +5678,7 @@ the actual execution strategy. Simply switch between `JtaTransactionManager` and
`CciLocalTransactionManager` as needed, keeping your transaction demarcation as-is.
For more information on Spring's transaction facilities, see the chapter entitled
<<transaction>>.
<<data-access.adoc#transaction,Transaction Management>>.
@@ -5887,7 +5877,7 @@ callback interface. Please note in this case that the `mailSender` property is o
[NOTE]
====
The mail code is a crosscutting concern and could well be a candidate for refactoring
into a <<aop,custom Spring AOP aspect>>, which then could be executed at appropriate
into a <<core.adoc#aop,custom Spring AOP aspect>>, which then could be executed at appropriate
joinpoints on the `OrderManager` target.
====
@@ -7045,7 +7035,8 @@ container. Using the dynamic-language-backed beans with a plain `BeanFactory`
implementation is supported, but you have to manage the plumbing of the Spring internals
to do so.
For more information on schema-based configuration, see <<xsd-configuration>>.
For more information on schema-based configuration, see <<appendix.adoc#xsd-configuration,
XML Schema-based configuration>>.
====
[source,xml,indent=0]
@@ -7875,7 +7866,8 @@ this feature.
====
Find below an example of a Spring `org.springframework.validation.Validator` implemented
using the Groovy dynamic language. (See <<validator>> for a discussion of the
using the Groovy dynamic language. (See <<core.adoc#validator,
Validation using Spring’s Validator interface>> for a discussion of the
`Validator` interface.)
[source,groovy,indent=0]
@@ -7917,7 +7909,7 @@ framework actually is unaware that a bean that is being advised might be a scrip
bean, so all of the AOP use cases and functionality that you may be using or aim to use
will work with scripted beans. There is just one (small) thing that you need to be aware
of when advising scripted beans... you cannot use class-based proxies, you must
use <<aop-proxying,interface-based proxies>>.
use <<core.adoc#aop-proxying,interface-based proxies>>.
You are of course not just limited to advising scripted beans... you can also write
aspects themselves in a supported dynamic language and use such beans to advise other
@@ -7931,11 +7923,11 @@ though.
In case it is not immediately obvious, scripted beans can of course be scoped just like
any other bean. The `scope` attribute on the various `<lang:language/>` elements allows
you to control the scope of the underlying scripted bean, just as it does with a regular
bean. (The default scope is <<beans-factory-scopes-singleton,singleton>>, just as it is
bean. (The default scope is <<core.adoc#beans-factory-scopes-singleton,singleton>>, just as it is
with 'regular' beans.)
Find below an example of using the `scope` attribute to define a Groovy bean scoped as
a <<beans-factory-scopes-prototype,prototype>>.
a <<core.adoc#beans-factory-scopes-prototype,prototype>>.
[source,xml,indent=0]
[subs="verbatim,quotes"]
@@ -7958,8 +7950,8 @@ a <<beans-factory-scopes-prototype,prototype>>.
</beans>
----
See <<beans-factory-scopes>> in <<beans>> for a fuller discussion of the scoping support
in the Spring Framework.
See <<core.adoc#beans-factory-scopes,Bean scopes>> in <<core.adoc#beans,The IoC container>>
for a fuller discussion of the scoping support in the Spring Framework.
@@ -7982,8 +7974,8 @@ this chapter.
[[cache-introduction]]
=== Introduction
Since version 3.1, Spring Framework provides support for transparently adding caching
into an existing Spring application. Similar to the <<transaction,transaction>> support,
the caching abstraction allows consistent use of various caching solutions with minimal
into an existing Spring application. Similar to the <<data-acess.adoc#transaction,transaction>>
support, the caching abstraction allows consistent use of various caching solutions with minimal
impact on the code.
As from Spring 4.1, the cache abstraction has been significantly improved with the
@@ -8174,7 +8166,7 @@ they are no use for the cache. Further more what if only one of the two is impor
while the other is not?
For such cases, the `@Cacheable` annotation allows the user to specify how the key is
generated through its `key` attribute. The developer can use <<expressions,SpEL>> to
generated through its `key` attribute. The developer can use <<core.adoc#expressions,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
@@ -8183,7 +8175,7 @@ quite different in signatures as the code base grows; while the default strategy
work for some methods, it rarely does for all methods.
Below are some examples of various SpEL declarations - if you are not familiar with it,
do yourself a favor and read <<expressions>>:
do yourself a favor and read <<core.adoc#expressions,Spring Expression Language>>:
[source,java,indent=0]
[subs="verbatim,quotes"]
@@ -8344,7 +8336,7 @@ Note that `result` still refers to `Book` and not `Optional`.
===== Available caching SpEL evaluation context
Each `SpEL` expression evaluates again a dedicated
<<expressions-language-ref,`context`>>. In addition to the build in parameters, the
<<core.adoc#expressions-language-ref,`context`>>. In addition to the build in parameters, the
framework provides dedicated caching related metadata such as the argument names. The
next table lists the items made available to the context so one can use them for key and
conditional computations:
@@ -8561,7 +8553,7 @@ Alternatively for XML configuration use the `cache:annotation-driven` element:
Both the `cache:annotation-driven` element and `@EnableCaching` annotation allow various
options to be specified that influence the way the caching behavior is added to the
application through AOP. The configuration is intentionally similar with that of
<<tx-annotation-driven-settings, `@Transactional`>>:
<<data-access.adoc#tx-annotation-driven-settings, `@Transactional`>>:
[NOTE]
====
@@ -8611,7 +8603,8 @@ javadoc for more details].
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
<<aop-aj-ltw-spring>> for details on how to set up load-time weaving.)
<<core.adoc#aop-aj-ltw-spring, Spring configuration>> for details on how to set up
load-time weaving.)
| `proxy-target-class`
| `proxyTargetClass`
@@ -8620,16 +8613,16 @@ javadoc for more details].
classes annotated with the `@Cacheable` or `@CacheEvict` annotations. If the
`proxy-target-class` attribute is set to `true`, then 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 <<aop-proxying>> for a detailed examination
of the different proxy types.)
interface-based proxies are created. (See <<core.adoc#aop-proxying,Proxying mechanisms>>
for a detailed examination of the different proxy types.)
| `order`
| `order`
| 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 of AOP advice, see <<aop-ataspectj-advice-ordering>>.) No specified ordering
means that the AOP subsystem determines the order of the advice.
ordering of AOP advice, see <<core.adoc#aop-ataspectj-advice-ordering,Advice ordering>>.)
No specified ordering means that the AOP subsystem determines the order of the advice.
|===
[NOTE]
@@ -8637,8 +8630,8 @@ javadoc for more details].
`<cache:annotation-driven/>` only looks for `@Cacheable/@CachePut/@CacheEvict/@Caching`
on beans in the same application context it is defined in. This means that, if you put
`<cache:annotation-driven/>` in a `WebApplicationContext` for a `DispatcherServlet`, it
only checks for beans in your controllers, and not your services. See <<mvc-servlet>>
for more information.
only checks for beans in your controllers, and not your services.
See <<web.adoc#mvc-servlet,the MVC section>> for more information.
====
.Method visibility and cache annotations
@@ -8694,8 +8687,8 @@ triggers cache population or eviction. This is quite handy as a template mechani
eliminates the need to duplicate cache annotation declarations (especially useful if the
key or condition are specified) or if the foreign imports (`org.springframework`) are
not allowed in your code base. Similar to the rest of the
<<beans-stereotype-annotations,stereotype>> annotations, `@Cacheable`, `@CachePut`,
`@CacheEvict` and `@CacheConfig` can be used as <<beans-meta-annotations,meta-annotations>>,
<<core.adoc#beans-stereotype-annotations,stereotype>> annotations, `@Cacheable`, `@CachePut`,
`@CacheEvict` and `@CacheConfig` can be used as <<core.adoc#beans-meta-annotations,meta-annotations>>,
that is annotations that can annotate other annotations. To wit, let us replace a common
`@Cacheable` declaration with our own, custom annotation:
@@ -8867,7 +8860,7 @@ caches, a consistent and identical key generation implementation should be used.
If annotations are not an option (no access to the sources or no external code), one can
use XML for declarative caching. So instead of annotating the methods for caching, one
specifies the target method and the caching directives externally (similar to the
declarative transaction management <<transaction-declarative-first-example,advice>>).
declarative transaction management <<data-access.adoc#transaction-declarative-first-example,advice>>).
The previous example can be translated into:
[source,xml,indent=0]
@@ -8899,7 +8892,8 @@ evicting data. Both definitions are working 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
<<aop>>). In the example above, all methods from the `BookService` are considered and
<<core.adoc#aop, Aspect Oriented Programming with Spring>>).
In the example above, all methods from the `BookService` are considered and
the cache advice applied to them.
The declarative XML caching supports all of the annotation-based model so moving between

89
src/docs/asciidoc/overview.adoc
View File

@@ -2,34 +2,8 @@
= Overview of Spring Framework
:doc-root: https://docs.spring.io
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
[partintro]
--
The Spring Framework is a lightweight solution and a potential one-stop-shop for
building your enterprise-ready applications. However, Spring is modular, allowing you to
use only those parts that you need, without having to bring in the rest. You can use the
IoC container, with any web framework on top, but you can also use only the
<<orm-hibernate,Hibernate integration code>> or the <<jdbc-introduction,JDBC abstraction
layer>>. The Spring Framework supports declarative transaction management, remote access
to your logic through RMI or web services, and various options for persisting your data.
It offers a full-featured <<mvc-introduction,MVC framework>>, and enables you to
integrate <<aop-introduction,AOP>> transparently into your software.
Spring is designed to be non-intrusive, meaning that your domain logic code generally
has no dependencies on the framework itself. In your integration layer (such as the data
access layer), some dependencies on the data access technology and the Spring libraries
will exist. However, it should be easy to isolate these dependencies from the rest of
your code base.
This document is a reference guide to Spring Framework features. If you have any
requests, comments, or questions on this document, please post them on the
https://groups.google.com/forum/#!forum/spring-framework-contrib[user mailing
list]. Questions on the Framework itself should be asked on StackOverflow
(see https://spring.io/questions[]).
--
:toc: left
:toclevels: 2
[[overview-getting-started-with-spring]]
@@ -127,18 +101,18 @@ in <<dependency-management,Dependency Management tools>>.
[[overview-core-container]]
==== Core Container
The <<beans-introduction,__Core Container__>> consists of the `spring-core`,
The <<core.adoc#beans-introduction,__Core Container__>> consists of the `spring-core`,
`spring-beans`, `spring-context`, `spring-context-support`, and `spring-expression`
(Spring Expression Language) modules.
The `spring-core` and `spring-beans` modules <<beans-introduction,provide the fundamental
parts of the framework>>, including the IoC and Dependency Injection features. The
`BeanFactory` is a sophisticated implementation of the factory pattern. It removes the
The `spring-core` and `spring-beans` modules <<core.adoc#beans-introduction,provide
the fundamental parts of the framework>>, including the IoC and Dependency Injection features.
The `BeanFactory` is a sophisticated implementation of the factory pattern. It removes the
need for programmatic singletons and allows you to decouple the configuration and
specification of dependencies from your actual program logic.
The <<context-introduction,__Context__>> (`spring-context`) module builds on the solid
base provided by the <<beans-introduction,__Core and Beans__>> modules: it is a means to
The <<core.adoc#context-introduction,__Context__>> (`spring-context`) module builds on the solid
base provided by the <<core.adoc#beans-introduction,__Core and Beans__>> modules: it is a means to
access objects in a framework-style manner that is similar to a JNDI registry. The
Context module inherits its features from the Beans module and adds support for
internationalization (using, for example, resource bundles), event propagation, resource
@@ -149,7 +123,7 @@ The `ApplicationContext` interface is the focal point of the Context module.
into a Spring application context, in particular for caching (EhCache, JCache) and
scheduling (CommonJ, Quartz).
The `spring-expression` module provides a powerful <<expressions,__Expression
The `spring-expression` module provides a powerful <<core.adoc#expressions,__Expression
Language__>> for querying and manipulating an object graph at runtime. It is an extension
of the unified expression language (unified EL) as specified in the JSP 2.1
specification. The language supports setting and getting property values, property
@@ -161,7 +135,7 @@ list aggregations.
[[overview-aop-instrumentation]]
==== AOP and Instrumentation
The `spring-aop` module provides an <<aop-introduction,__AOP__>> Alliance-compliant
The `spring-aop` module provides an <<core.adoc#aop-introduction,__AOP__>> Alliance-compliant
aspect-oriented programming implementation allowing you to define, for example,
method interceptors and pointcuts to cleanly decouple code that implements functionality
that should be separated. Using source-level metadata functionality, you can also
@@ -189,25 +163,26 @@ annotation based programming model.
The __Data Access/Integration__ layer consists of the JDBC, ORM, OXM, JMS, and
Transaction modules.
The `spring-jdbc` module provides a <<jdbc-introduction,JDBC>>-abstraction layer that
removes the need to do tedious JDBC coding and parsing of database-vendor specific error
codes.
The `spring-jdbc` module provides a <<data-access.adoc#jdbc-introduction,JDBC>>-abstraction
layer that removes the need to do tedious JDBC coding and parsing of database-vendor
specific error codes.
The `spring-tx` module supports <<transaction,programmatic and declarative transaction>>
The `spring-tx` module supports <<data-access.adoc#transaction,programmatic and declarative transaction>>
management for classes that implement special interfaces and for __all your POJOs (Plain
Old Java Objects)__.
The `spring-orm` module provides integration layers for popular
<<orm-introduction,object-relational mapping>> APIs, including <<orm-jpa,JPA>> and
<<orm-hibernate,Hibernate>>. Using the `spring-orm` module you can use these
O/R-mapping frameworks in combination with all of the other features Spring offers,
such as the simple declarative transaction management feature mentioned previously.
<<data-access.adoc#orm-introduction,object-relational mapping>> APIs,
including <<data-access.adoc#orm-jpa,JPA>> and <<data-access.adoc#orm-hibernate,Hibernate>>.
Using the `spring-orm` module you can use these O/R-mapping frameworks in combination with
all of the other features Spring offers, such as the simple declarative transaction
management feature mentioned previously.
The `spring-oxm` module provides an abstraction layer that supports <<oxm,Object/XML
mapping>> implementations such as JAXB, Castor, JiBX and XStream.
The `spring-oxm` module provides an abstraction layer that supports
<<data-access.adoc#oxm,Object/XML mapping>> implementations such as JAXB, Castor, JiBX and XStream.
The `spring-jms` module (<<jms,Java Messaging Service>>) contains features for producing and
consuming messages. Since Spring Framework 4.1, it provides integration with the
The `spring-jms` module (<<integration.adoc#jms,Java Messaging Service>>) contains features for
producing and consuming messages. Since Spring Framework 4.1, it provides integration with the
`spring-messaging` module.
@@ -222,7 +197,7 @@ Servlet listeners and a web-oriented application context. It also contains an HT
and the web-related parts of Spring's remoting support.
The `spring-webmvc` module (also known as the __Web-Servlet__ module) contains Spring's
model-view-controller (<<mvc-introduction,__MVC__>>) and REST Web Services implementation
model-view-controller (<<web.adoc#mvc-introduction,__MVC__>>) and REST Web Services implementation
for web applications. Spring's MVC framework provides a clean separation between domain
model code and web forms and integrates with all of the other features of the Spring
Framework.
@@ -230,11 +205,11 @@ Framework.
[[overview-testing]]
==== Test
The `spring-test` module supports the <<unit-testing,unit testing>> and
<<integration-testing,integration testing>> of Spring components with JUnit or TestNG. It
provides consistent <<testcontext-ctx-management,loading>> of Spring
``ApplicationContext``s and <<testcontext-ctx-management-caching,caching>> of those
contexts. It also provides <<mock-objects,mock objects>> that you can use to test your
The `spring-test` module supports the <<testing.adoc#unit-testing,unit testing>> and
<<testing.adoc#integration-testing,integration testing>> of Spring components with JUnit or TestNG. It
provides consistent <<testing.adoc#testcontext-ctx-management,loading>> of Spring
``ApplicationContext``s and <<testing.adoc#testcontext-ctx-management-caching,caching>> of those
contexts. It also provides <<testing.adoc#mock-objects,mock objects>> that you can use to test your
code in isolation.
@@ -249,8 +224,8 @@ framework integration.
.Typical full-fledged Spring web application
image::images/overview-full.png[]
Spring's <<transaction-declarative,declarative transaction management features>> make
the web application fully transactional, just as it would be if you used EJB
Spring's <<data-access.adoc#transaction-declarative,declarative transaction management features>>
make the web application fully transactional, just as it would be if you used EJB
container-managed transactions. All your custom business logic can be implemented with
simple POJOs and managed by Spring's IoC container. Additional services include support
for sending email and validation that is independent of the web layer, which lets you
@@ -282,7 +257,7 @@ existing applications is not difficult.
.EJBs - Wrapping existing POJOs
image::images/overview-ejb.png[]
The Spring Framework also provides an <<ejb,access and abstraction layer>> for
The Spring Framework also provides an <<integration.adoc#ejb,access and abstraction layer>> for
Enterprise JavaBeans, enabling you to reuse your existing POJOs and wrap them in
stateless session beans for use in scalable, fail-safe web applications that might need
declarative security.

43
src/docs/asciidoc/testing.adoc
View File

@@ -3,9 +3,9 @@
:doc-root: https://docs.spring.io
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
:doc-spring-boot: {doc-root}/spring-boot/docs/current/reference
:toc: left
:toclevels: 2
[partintro]
--
The adoption of the test-driven-development (TDD) approach to software
development is certainly advocated by the Spring team, and so coverage of Spring's
support for integration testing is covered (alongside best practices for unit testing).
@@ -14,7 +14,6 @@ integration testing easier (in that the presence of setter methods and appropria
constructors on classes makes them easier to wire together in a test without having to
set up service locator registries and suchlike)... the chapter dedicated solely to
testing will hopefully convince you of this as well.
--
[[testing-introduction]]
@@ -26,8 +25,6 @@ thorough treatment of testing in the enterprise is beyond the scope of this refe
manual.)__
[[unit-testing]]
== Unit Testing
Dependency Injection should make your code less dependent on the container than it would
@@ -57,10 +54,11 @@ support classes.
[[mock-objects-env]]
==== Environment
The `org.springframework.mock.env` package contains mock implementations of the
`Environment` and `PropertySource` abstractions (see <<beans-definition-profiles>>
and <<beans-property-source-abstraction>>). `MockEnvironment` and
`MockPropertySource` are useful for developing __out-of-container__ tests for code that
depends on environment-specific properties.
`Environment` and `PropertySource` abstractions (see
<<core.adoc#beans-definition-profiles, Bean definition profiles>>
and <<core.adoc#beans-property-source-abstraction, PropertySource abstraction>>).
`MockEnvironment` and `MockPropertySource` are useful for developing
__out-of-container__ tests for code that depends on environment-specific properties.
[[mock-objects-jndi]]
@@ -158,7 +156,7 @@ This will enable you to test things such as:
The Spring Framework provides first-class support for integration testing in the
`spring-test` module. The name of the actual JAR file might include the release version
and might also be in the long `org.springframework.test` form, depending on where you
get it from (see the <<dependency-management,section on Dependency Management>> for an
get it from (see the <<core.adoc#dependency-management,section on Dependency Management>> for an
explanation). This library includes the `org.springframework.test` package, which
contains valuable classes for integration testing with a Spring container. This testing
does not rely on an application server or other deployment environment. Such tests are
@@ -312,8 +310,9 @@ provide convenience methods which delegate to the aforementioned methods in
The `spring-jdbc` module provides support for configuring and launching an embedded
database which can be used in integration tests that interact with a database. For
details, see <<jdbc-embedded-database-support>> and
<<jdbc-embedded-database-dao-testing>>.
details, see <<data-access.adoc#jdbc-embedded-database-support, Embedded database support>>
and <<data-access.adoc#jdbc-embedded-database-dao-testing, Testing data access logic
with an embedded database>>.
@@ -978,7 +977,7 @@ well as any __set up__ or __tear down__ of the test fixture.
[[integration-testing-annotations-meta]]
==== Meta-Annotation Support for Testing
It is possible to use most test-related annotations as
<<beans-meta-annotations,meta-annotations>> in order to create custom _composed
<<core.adoc#beans-meta-annotations,meta-annotations>> in order to create custom _composed
annotations_ and reduce configuration duplication across a test suite.
Each of the following may be used as meta-annotations in conjunction with the
@@ -1053,7 +1052,7 @@ configuration of individual test classes as follows:
public class UserRepositoryTests { }
----
For further details, consult the <<annotation-programming-model,Spring Annotation Programming Model>>.
For further details, consult the <<core.adoc#annotation-programming-model,Spring Annotation Programming Model>>.
[[testcontext-framework]]
@@ -1442,7 +1441,7 @@ a default location based on the name of the test class. If your class is named
===== Context configuration with Groovy scripts
To load an `ApplicationContext` for your tests using Groovy scripts that utilize the
<<groovy-bean-definition-dsl,Groovy Bean Definition DSL>>, annotate your test class with
<<core.adoc#groovy-bean-definition-dsl,Groovy Bean Definition DSL>>, annotate your test class with
`@ContextConfiguration` and configure the `locations` or `value` attribute with an array
that contains the resource locations of Groovy scripts. Resource lookup semantics for
Groovy scripts are the same as those described for <<testcontext-ctx-management-xml,XML
@@ -1516,7 +1515,8 @@ The following listing demonstrates how to combine both in an integration test.
===== Context configuration with annotated classes
To load an `ApplicationContext` for your tests using __annotated classes__ (see
<<beans-java>>), annotate your test class with `@ContextConfiguration` and configure the
<<core.adoc#beans-java, Java-based container configuration>>),
annotate your test class with `@ContextConfiguration` and configure the
`classes` attribute with an array that contains references to annotated classes.
[source,java,indent=0]
@@ -2660,7 +2660,7 @@ instantiated. Thus the use of `@Autowired` or `@Inject` for constructors has no
for test classes.
====
Because `@Autowired` is used to perform <<beans-factory-autowire, __autowiring by type__
Because `@Autowired` is used to perform <<core.adoc#beans-factory-autowire, __autowiring by type__
>>, if you have multiple bean definitions of the same type, you cannot rely on this
approach for those particular beans. In that case, you can use `@Autowired` in
conjunction with `@Qualifier`. As of Spring 3.0 you may also choose to use `@Inject` in
@@ -2813,7 +2813,7 @@ request-scoped and session-scoped beans by following these steps.
The following code snippet displays the XML configuration for a login use case. Note
that the `userService` bean has a dependency on a request-scoped `loginAction` bean.
Also, the `LoginAction` is instantiated using <<expressions,SpEL expressions>> that
Also, the `LoginAction` is instantiated using <<core.adoc#expressions,SpEL expressions>> that
retrieve the username and password from the current HTTP request. In our test, we will
want to configure these request parameters via the mock managed by the TestContext
framework.
@@ -2954,7 +2954,7 @@ application code that is invoked via tests). Spring-managed and application-mana
transactions will typically participate in test-managed transactions; however, caution
should be taken if Spring-managed or application-managed transactions are configured with
any _propagation_ type other than `REQUIRED` or `SUPPORTS` (see the discussion on
<<tx-propagation,transaction propagation>> for details).
<<data-access.adoc#tx-propagation,transaction propagation>> for details).
[[testcontext-tx-enabling-transactions]]
===== Enabling and disabling transactions
@@ -3236,8 +3236,9 @@ When writing integration tests against a relational database, it is often benefi
to execute SQL scripts to modify the database schema or insert test data into tables.
The `spring-jdbc` module provides support for _initializing_ an embedded or existing
database by executing SQL scripts when the Spring `ApplicationContext` is loaded. See
<<jdbc-embedded-database-support>> and <<jdbc-embedded-database-dao-testing>> for
details.
<<data-access.adoc#jdbc-embedded-database-support, Embedded database support>> and
<<data-access.adoc#jdbc-embedded-database-dao-testing,
Testing data access logic with an embedded database>> for details.
Although it is very useful to initialize a database for testing _once_ when the
`ApplicationContext` is loaded, sometimes it is essential to be able to modify the

9
src/docs/asciidoc/web.adoc
View File

@@ -2,9 +2,9 @@
= The Web
:doc-root: https://docs.spring.io
:api-spring-framework: {doc-root}/spring-framework/docs/{spring-version}/javadoc-api/org/springframework
:toc: left
:toclevels: 2
[partintro]
--
This part of the reference documentation covers Spring Framework's support for the
presentation tier (and specifically web-based presentation tiers) including support
for WebSocket-style messaging in web applications.
@@ -16,11 +16,6 @@ integration with other web technologies, such as <<jsf,JSF>>.
The section then concludes with comprehensive coverage of the Spring Framework
<<websocket>> (including <<websocket-stomp>>).
* <<mvc>>
* <<view>>
* <<web-integration>>
* <<websocket>>
--
include::web/web-mvc.adoc[leveloffset=+1]

47
src/docs/asciidoc/web/web-mvc.adoc
View File

@@ -30,8 +30,8 @@ the first edition. Alternatively, see
You cannot add advice to final methods when you use Spring MVC. For example, you cannot
add advice to the `AbstractController.setSynchronizeOnSession()` method. Refer to
<<aop-understanding-aop-proxies>> for more information on AOP proxies and why you cannot
add advice to final methods.
<<core.adoc#aop-understanding-aop-proxies, Understanding AOP proxies>>
for more information on AOP proxies and why you cannot add advice to final methods.
****
In Spring Web MVC you can use any object as a command or form-backing object; you do not
@@ -106,14 +106,15 @@ Spring's web module includes many unique web support features:
* __A simple yet powerful JSP tag library known as the Spring tag library that provides
support for features such as data binding and themes__. The custom tags allow for
maximum flexibility in terms of markup code. For information on the tag library
descriptor, see the appendix entitled <<spring-tld>>
descriptor, see the appendix entitled <<appendix.adoc#spring-tld, Spring TLD>>
* __A JSP form tag library, introduced in Spring 2.0, that makes writing forms in JSP
pages much easier.__ For information on the tag library descriptor, see the appendix
entitled <<spring-form-tld>>
entitled <<appendix.adoc#spring-form-tld, Spring Form TLD>>
* __Beans whose lifecycle is scoped to the current HTTP request or HTTP `Session`.__
This is not a specific feature of Spring MVC itself, but rather of the
`WebApplicationContext` container(s) that Spring MVC uses. These bean scopes are
described in <<beans-factory-scopes-other>>
described in <<core.adoc#beans-factory-scopes-other, Request, session, application,
and WebSocket scopes>>
@@ -217,10 +218,11 @@ Below is the `web.xml` equivalent of the above code based example:
----
As detailed in <<context-introduction>>, `ApplicationContext` instances in Spring can be
scoped. In the Web MVC framework, each `DispatcherServlet` has its own
`WebApplicationContext`, which inherits all the beans already defined in the root
`WebApplicationContext`. The root `WebApplicationContext` should contain all the
As detailed in <<core.adoc#context-introduction,Additional Capabilities of the ApplicationContext>>,
`ApplicationContext` instances in Spring can be scoped.
In the Web MVC framework, each `DispatcherServlet` has its own `WebApplicationContext`,
which inherits all the beans already defined in the root `WebApplicationContext`.
The root `WebApplicationContext` should contain all the
infrastructure beans that should be shared between your other contexts and Servlet
instances. These inherited beans can be overridden in the servlet-specific
scope, and you can define new scope-specific beans local to a given Servlet instance.
@@ -1766,8 +1768,9 @@ The next step is data binding. The `WebDataBinder` class matches request paramet
-- including query string parameters and form fields -- to model attribute fields by
name. Matching fields are populated after type conversion (from String to the target
field type) has been applied where necessary. Data binding and validation are covered in
<<validation>>. Customizing the data binding process for a controller level is covered
in <<mvc-ann-webdatabinder>>.
<<core.adoc#validation, Validation>>.
Customizing the data binding process for a controller level is covered in
<<mvc-ann-webdatabinder>>.
As a result of data binding there may be errors such as missing required fields or type
conversion errors. To check for such errors add a `BindingResult` argument immediately
@@ -1856,8 +1859,8 @@ annotation:
}
----
See <<validation-beanvalidation>> and <<validation>> for details on how to configure and
use validation.
See <<core.adoc#validation-beanvalidation, Bean validation>> and
<<core.adoc#validation, Spring validation>> for details on how to configure and use validation.
@@ -2058,7 +2061,7 @@ an `@ModelAttribute` parameter) they're bound to. If the target type is not `Str
Spring automatically converts to the appropriate type. All simple types such as int,
long, Date, etc. are supported. You can further customize the conversion process through
a `WebDataBinder` (see <<mvc-ann-webdatabinder>>) or by registering `Formatters` with
the `FormattingConversionService` (see <<format>>).
the `FormattingConversionService` (see <<core.adoc#format, Spring Field Formatting>>).
[[mvc-ann-webdatabinder]]
@@ -2606,7 +2609,7 @@ the timeout value. The class constructor of `WebAsyncTask` also allows providing
[[mvc-ann-tests]]
=== Testing Controllers
The `spring-test` module offers first class support for testing annotated controllers.
See <<spring-mvc-test-framework>>.
See <<testing.adoc#spring-mvc-test-framework, Spring MVC Test Framework>>.
@@ -4814,11 +4817,11 @@ requests with annotated controller methods using annotations such as `@RequestMa
It also enables the following:
. Spring 3 style type conversion through a <<core-convert,ConversionService>> instance
. Spring 3 style type conversion through a <<core.adoc#core-convert,ConversionService>> instance
in addition to the JavaBeans PropertyEditors used for Data Binding.
. Support for <<format,formatting>> Number fields using the `@NumberFormat` annotation
. Support for <<core.adoc#format,formatting>> Number fields using the `@NumberFormat` annotation
through the `ConversionService`.
. Support for <<format,formatting>> `Date`, `Calendar`, `Long`, and Joda Time fields using the
. Support for <<core.adoc#format,formatting>> `Date`, `Calendar`, `Long`, and Joda Time fields using the
`@DateTimeFormat` annotation.
. Support for <<mvc-config-validation,validating>> `@Controller` inputs with `@Valid`, if
a JSR-303 Provider is present on the classpath.
@@ -4971,20 +4974,20 @@ To register custom formatters and converters simply supply a `ConversionService`
[NOTE]
====
See <<format-FormatterRegistrar-SPI>> and the `FormattingConversionServiceFactoryBean`
for more information on when to use FormatterRegistrars.
See <<core.adoc#format-FormatterRegistrar-SPI,FormatterRegistrar SPI>>
and the `FormattingConversionServiceFactoryBean` for more information on when to use FormatterRegistrars.
====
[[mvc-config-validation]]
=== Validation
Spring provides a <<validator,Validator interface>> that can be used for validation in all layers
Spring provides a <<core.adoc#validator,Validator interface>> that can be used for validation in all layers
of an application. In Spring MVC you can configure it for use as a global `Validator` instance, to be used
whenever an `@Valid` or `@Validated` controller method argument is encountered, and/or as a local
`Validator` within a controller through an `@InitBinder` method. Global and local validator
instances can be combined to provide composite validation.
Spring also <<validation-beanvalidation-overview,supports JSR-303/JSR-349>> Bean Validation
Spring also <<core.adoc#validation-beanvalidation-overview,supports JSR-303/JSR-349>> Bean Validation
via `LocalValidatorFactoryBean` which adapts the Spring `org.springframework.validation.Validator`
interface to the Bean Validation `javax.validation.Validator` contract. This class can be
plugged into Spring MVC as a global validator as described next.