From dea4825a9fcf8e7958d13b04417aab7234b05c0a Mon Sep 17 00:00:00 2001 From: Brian Clozel Date: Wed, 29 Mar 2017 14:20:12 +0200 Subject: [PATCH] Fix link references between documents Issue: SPR-14997 --- src/docs/asciidoc/appendix.adoc | 86 ++++++++++++-------- src/docs/asciidoc/core.adoc | 15 +--- src/docs/asciidoc/core/core-aop.adoc | 17 ++-- src/docs/asciidoc/core/core-beans.adoc | 52 ++++++------ src/docs/asciidoc/core/core-validation.adoc | 14 ++-- src/docs/asciidoc/data-access.adoc | 67 +++++++-------- src/docs/asciidoc/index.adoc | 31 +++++-- src/docs/asciidoc/integration.adoc | 90 ++++++++++----------- src/docs/asciidoc/overview.adoc | 89 ++++++++------------ src/docs/asciidoc/testing.adoc | 43 +++++----- src/docs/asciidoc/web.adoc | 9 +-- src/docs/asciidoc/web/web-mvc.adoc | 47 ++++++----- 12 files changed, 275 insertions(+), 285 deletions(-) diff --git a/src/docs/asciidoc/appendix.adoc b/src/docs/asciidoc/appendix.adoc index 5a67bea7004..4d661e561d2 100644 --- a/src/docs/asciidoc/appendix.adoc +++ b/src/docs/asciidoc/appendix.adoc @@ -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 -<> chapter. +<> chapter. [[classic-spring-hibernate]] ==== Hibernate -For the currently recommended usage patterns for Hibernate see <>. +For the currently recommended usage patterns for Hibernate see +<>. [[orm-hibernate-template]] @@ -238,8 +240,8 @@ used. [[classic-spring-aysnc-messages]] ==== Asynchronous Message Reception -<> are used in -conjunction with Spring's <> to support +<> are used in +conjunction with Spring's <> 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 <> for more information on this +documentation on <> 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 <> chapter, but when working with existing +AOP support described in the <> 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 <>). +* Specify whether to use CGLIB (see below and also <>). 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 <>). + will be created (but see also below + <>). * `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 <>). + proxy for the target class will be used (but see also below + <>). * `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 <>. +to be applied. An example of using this feature can be found in +<>. * 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 -<>, so that it may not actually ever be +<>, 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 <> location). +loaded from the supplied <> 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 <>. Please do consult that chapter for full details on this -support and the `lang` tags themselves. +entitled <>. +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 -<>. These tags are detailed in the section of the -<> entitled <>. Please do consult that chapter for full -details on this support and the `jms` tags themselves. +<>. These tags are detailed in the +section of the <> entitled <>. 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 <>. +for transactions. These tags are covered in the chapter entitled +<>. [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 <>. +These tags are comprehensively covered in the chapter entitled <>. 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. ===== This element activates the replacement of `${...}` placeholders, resolved against the -specified properties file (as a <>). This element is -a convenience mechanism that sets up a<>). This element is +a convenience mechanism that sets up a<> 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< Activates the Spring infrastructure for various annotations to be detected in bean -classes: Spring's <> and -<>, as well as JSR 250's `@PostConstruct`, +classes: Spring's <> and +<>, 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 -<> annotation. Use the -<`>> element for that purpose. +<> annotation. Use the +<`>> element for that purpose. ==== [[xsd-config-body-schemas-context-component-scan]] ===== -This element is detailed in <>. +This element is detailed in <>. [[xsd-config-body-schemas-context-ltw]] ===== -This element is detailed in <>. +This element is detailed in <>. [[xsd-config-body-schemas-context-sc]] ===== -This element is detailed in <>. +This element is detailed in <>. [[xsd-config-body-schemas-context-mbe]] ===== -This element is detailed in <>. +This element is detailed in <>. @@ -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 <> -and <> respectively. +existing data source. These tags are documented in +<> +and <> 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 -<> and <> for details. +<> and +<> 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 <> (and indeed in that entire <>). +in <> +(and indeed in that entire <>). 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<>. We'll start by + the<>. We'll start by highlighting a simple example, without using decoration, after which we will show decoration in a somewhat more advanced example. diff --git a/src/docs/asciidoc/core.adoc b/src/docs/asciidoc/core.adoc index a59ed1d24fa..79d26403838 100644 --- a/src/docs/asciidoc/core.adoc +++ b/src/docs/asciidoc/core.adoc @@ -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. - -* <> -* <> -* <> -* <> -* <> -* <> --- - - - include::core/core-beans.adoc[leveloffset=+1] include::core/core-resources.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/core/core-aop.adoc b/src/docs/asciidoc/core/core-aop.adoc index 26f3b2ecfc9..2ab4510f9b8 100644 --- a/src/docs/asciidoc/core/core-aop.adoc +++ b/src/docs/asciidoc/core/core-aop.adoc @@ -259,8 +259,9 @@ element: ---- -This assumes that you are using schema support as described in <>. See -<> for how to import the tags in the `aop` namespace. +This assumes that you are using schema support as described in <>. See <> +for how to import the tags in the `aop` namespace. @@ -572,7 +573,7 @@ write: ---- The `` and `` elements are discussed in <>. The -transaction elements are discussed in <>. +transaction elements are discussed in <>. [[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 <>. See <> +`spring-aop` schema as described in <>. +See <> 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 <> 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 <>. Specifically the -`@EnableLoadTimeWeaving` annotation can be used as an alternative to +configure and use @AspectJ with <>. +Specifically the `@EnableLoadTimeWeaving` annotation can be used as an alternative to `` (see <> for details). ==== diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 149c1aed713..fdae707305d 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -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[<>] ] principle. IoC +(IoC) footnote:[See pass:specialcharacters,macros[<>] ] 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 <> is therefore a compelling use case for setter -injection. +later. Management through <> 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 `` elements, to describe your property values and/or collaborating beans. -Spring supports extensible configuration formats <>, which are -based on an XML Schema definition. The `beans` configuration format discussed in this +Spring supports extensible configuration formats <>, +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`. -| <> +| <> | 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 `` element into a scoped bean definition (see <> and -<>). Why do definitions of beans scoped at the `request`, `session` -and custom-scope levels require the `` 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__). +<>). +Why do definitions of beans scoped at the `request`, `session` and custom-scope +levels require the `` 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 -| <> +| <> | `LoadTimeWeaverAware` | Defined __weaver__ for processing class definition at load time @@ -3596,7 +3598,7 @@ dependency type: | `NotificationPublisherAware` | Spring JMX notification publisher -| <> +| <> | `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` -| <> +| <> | `ServletContextAware` | Current `ServletContext` the container runs in. Valid only in a web-aware Spring `ApplicationContext` -| <> +| <> |=== 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 -<>.) +<>.) 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 `` in a `WebApplicationContext` for a `DispatcherServlet`, it only checks for `@Autowired` beans in your controllers, and not your services. See -<> for more information. +<> 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 -<>. +<>. 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 <>. +For further details, consult the <>. [[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 <>). In integration tests, active profiles can be declared via the `@ActiveProfiles` annotation in the `spring-test` module -(see <>). +(see <>). 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 <> 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 +<> 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 <>. @@ -8483,7 +8487,7 @@ events instead. ==== Asynchronous Listeners If you want a particular listener to process events asynchronously, simply reuse the -<>: +<>: [source,java,indent=0] [subs="verbatim,quotes"] diff --git a/src/docs/asciidoc/core/core-validation.adoc b/src/docs/asciidoc/core/core-validation.adoc index 64604b6dab6..f181c6e8103 100644 --- a/src/docs/asciidoc/core/core-validation.adoc +++ b/src/docs/asciidoc/core/core-validation.adoc @@ -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 <>, using `PropertyEditorRegistrars` in +using <>, 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 -<> in the Spring MVC chapter. +<> in the Spring MVC chapter. In certain situations you may wish to apply formatting during conversion. See <> for details on using @@ -1313,7 +1310,7 @@ converter and formatter registration. [[format-configuring-formatting-mvc]] === Configuring Formatting in Spring MVC -See <> in the Spring MVC chapter. +See <> 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 <> for details. +`mvc:annotation-driven` element. +See <> for details. @@ -1635,5 +1633,5 @@ locally on a DataBinder instance. See <>. [[validation-mvc]] === Spring MVC 3 Validation -See <> in the Spring MVC chapter. +See <> in the Spring MVC chapter. diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index a7385d925bf..45fe6da1b9f 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -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]] == Transaction Management @@ -309,9 +301,11 @@ infrastructure. [NOTE] ==== The above definition of the `dataSource` bean uses the `` tag from the -`jee` namespace. For more information on schema-based configuration, see <>, -and for more information on the `` tags see the section entitled -<>. +`jee` namespace. For more information on schema-based configuration, see +<>, +and for more information on the `` +tags see the section entitled <>. ==== 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 -<>, and that the transactional advice +<>, 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 <>. +Spring AOP is covered in <>. ==== 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 `` element is an AspectJ pointcut -expression; see <> for more details on pointcut expressions in Spring. +expression; see <> 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 <> for more details.__ +`x.y.service` package; see <> 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 <> for details on how to set up load-time - weaving.) + weaving) enabled. (See <> + 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 <> for a detailed examination - of the different proxy types.) + interface-based proxies are created. (See <> + 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 <>.) No specified ordering means that the - AOP subsystem determines the order of the advice. + advice, see <>.) + 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 <> for more information. +and not your services. See <> 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 <> allows +different methods, then <> 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 <> for detailed coverage of the following AOP +applies to transactions). See <> 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 -<>. +<>. . [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 <> and -<> respectively. +<> 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 <> for a discussion of load-time -weaving with AspectJ. +Guide]) or use load-time weaving. See <> 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 <> and configuring the embedded database as a bean in the Spring `ApplicationContext` as described in <> and <>. @@ -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 <> -in the appendices. +recommended; however, coverage of this style can be found in the +<> 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 <> 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 <> 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 diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc index b3f16704b0f..7ad906aa4d9 100644 --- a/src/docs/asciidoc/index.adoc +++ b/src/docs/asciidoc/index.adoc @@ -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 -<> +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 +<> or the +<>. 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 <> +and <>; and it enables you to +integrate <> transparently into your software. -<> +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[]). -<> +This reference document provides the following sections: -<> +* <> -<> +* <> -<> +* <> -<> \ No newline at end of file +* <> + +* <> + +* <> + +* <> \ No newline at end of file diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 9d28ba6c4a7..261e9db338b 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -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]] == 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 <>. 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 <>. +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 <>) -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 <>) 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 -<>: +<>: [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 -<>. +<>. @@ -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 <>, which then could be executed at appropriate +into a <>, 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 <>. +For more information on schema-based configuration, see <>. ==== [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 <> for a discussion of the +using the Groovy dynamic language. (See <> 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 <>. +use <>. 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 `` elements allows you to control the scope of the underlying scripted bean, just as it does with a regular -bean. (The default scope is <>, just as it is +bean. (The default scope is <>, just as it is with 'regular' beans.) Find below an example of using the `scope` attribute to define a Groovy bean scoped as -a <>. +a <>. [source,xml,indent=0] [subs="verbatim,quotes"] @@ -7958,8 +7950,8 @@ a <>. ---- -See <> in <> for a fuller discussion of the scoping support -in the Spring Framework. +See <> in <> +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 <> support, -the caching abstraction allows consistent use of various caching solutions with minimal +into an existing Spring application. Similar to the <> +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 <> to +generated through its `key` attribute. The developer can use <> 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 <>: +do yourself a favor and read <>: [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 -<>. In addition to the build in parameters, the +<>. 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 -<>: +<>: [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 - <> for details on how to set up load-time weaving.) + <> 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 <> for a detailed examination - of the different proxy types.) + interface-based proxies are created. (See <> + 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 <>.) No specified ordering - means that the AOP subsystem determines the order of the advice. + ordering of AOP advice, see <>.) + No specified ordering means that the AOP subsystem determines the order of the advice. |=== [NOTE] @@ -8637,8 +8630,8 @@ javadoc for more details]. `` only looks for `@Cacheable/@CachePut/@CacheEvict/@Caching` on beans in the same application context it is defined in. This means that, if you put `` in a `WebApplicationContext` for a `DispatcherServlet`, it -only checks for beans in your controllers, and not your services. See <> -for more information. +only checks for beans in your controllers, and not your services. +See <> 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 -<> annotations, `@Cacheable`, `@CachePut`, -`@CacheEvict` and `@CacheConfig` can be used as <>, +<> annotations, `@Cacheable`, `@CachePut`, +`@CacheEvict` and `@CacheConfig` can be used as <>, 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 <>). +declarative transaction management <>). 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 -<>). In the example above, all methods from the `BookService` are considered and +<>). +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 diff --git a/src/docs/asciidoc/overview.adoc b/src/docs/asciidoc/overview.adoc index 61fb5c683f9..5a4118f8adc 100644 --- a/src/docs/asciidoc/overview.adoc +++ b/src/docs/asciidoc/overview.adoc @@ -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 -<> or the <>. 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 <>, and enables you to -integrate <> 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 <>. [[overview-core-container]] ==== Core Container -The <> consists of the `spring-core`, +The <> 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 <>, 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 <>, 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 <> (`spring-context`) module builds on the solid -base provided by the <> modules: it is a means to +The <> (`spring-context`) module builds on the solid +base provided by the <> 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 <> 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 <> Alliance-compliant +The `spring-aop` module provides an <> 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 <>-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 <>-abstraction +layer that removes the need to do tedious JDBC coding and parsing of database-vendor +specific error codes. -The `spring-tx` module supports <> +The `spring-tx` module supports <> 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 -<> APIs, including <> and -<>. 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. +<> APIs, +including <> and <>. +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 <> implementations such as JAXB, Castor, JiBX and XStream. +The `spring-oxm` module provides an abstraction layer that supports +<> implementations such as JAXB, Castor, JiBX and XStream. -The `spring-jms` module (<>) contains features for producing and -consuming messages. Since Spring Framework 4.1, it provides integration with the +The `spring-jms` module (<>) 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 (<>) and REST Web Services implementation +model-view-controller (<>) 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 <> and -<> of Spring components with JUnit or TestNG. It -provides consistent <> of Spring -``ApplicationContext``s and <> of those -contexts. It also provides <> that you can use to test your +The `spring-test` module supports the <> and +<> of Spring components with JUnit or TestNG. It +provides consistent <> of Spring +``ApplicationContext``s and <> of those +contexts. It also provides <> 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 <> make -the web application fully transactional, just as it would be if you used EJB +Spring's <> +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 <> for +The Spring Framework also provides an <> 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. diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc index 7727986caa9..918d3991020 100644 --- a/src/docs/asciidoc/testing.adoc +++ b/src/docs/asciidoc/testing.adoc @@ -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 <> -and <>). `MockEnvironment` and -`MockPropertySource` are useful for developing __out-of-container__ tests for code that -depends on environment-specific properties. +`Environment` and `PropertySource` abstractions (see +<> +and <>). +`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 <> for an +get it from (see the <> 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 <> and -<>. +details, see <> +and <>. @@ -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 -<> in order to create custom _composed +<> 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 <>. +For further details, consult the <>. [[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 -<>, annotate your test class with +<>, 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 <>), annotate your test class with `@ContextConfiguration` and configure the +<>), +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 <>, 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 <> that +Also, the `LoginAction` is instantiated using <> 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 -<> for details). +<> 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 -<> and <> for -details. +<> and +<> 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 diff --git a/src/docs/asciidoc/web.adoc b/src/docs/asciidoc/web.adoc index aa16c07e80a..e39f6862619 100644 --- a/src/docs/asciidoc/web.adoc +++ b/src/docs/asciidoc/web.adoc @@ -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 <>. The section then concludes with comprehensive coverage of the Spring Framework <> (including <>). -* <> -* <> -* <> -* <> --- include::web/web-mvc.adoc[leveloffset=+1] diff --git a/src/docs/asciidoc/web/web-mvc.adoc b/src/docs/asciidoc/web/web-mvc.adoc index 2e366db43ad..6226a5179fc 100644 --- a/src/docs/asciidoc/web/web-mvc.adoc +++ b/src/docs/asciidoc/web/web-mvc.adoc @@ -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 -<> for more information on AOP proxies and why you cannot -add advice to final methods. +<> +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 <> + descriptor, see the appendix entitled <> * __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 <> + entitled <> * __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 <> + described in <> @@ -217,10 +218,11 @@ Below is the `web.xml` equivalent of the above code based example: ---- -As detailed in <>, `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 <>, +`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 -<>. Customizing the data binding process for a controller level is covered -in <>. +<>. +Customizing the data binding process for a controller level is covered in +<>. 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 <> and <> for details on how to configure and -use validation. +See <> and +<> 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 <>) or by registering `Formatters` with -the `FormattingConversionService` (see <>). +the `FormattingConversionService` (see <>). [[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 <>. +See <>. @@ -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 <> instance +. Spring 3 style type conversion through a <> instance in addition to the JavaBeans PropertyEditors used for Data Binding. -. Support for <> Number fields using the `@NumberFormat` annotation +. Support for <> Number fields using the `@NumberFormat` annotation through the `ConversionService`. -. Support for <> `Date`, `Calendar`, `Long`, and Joda Time fields using the +. Support for <> `Date`, `Calendar`, `Long`, and Joda Time fields using the `@DateTimeFormat` annotation. . Support for <> `@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 <> and the `FormattingConversionServiceFactoryBean` -for more information on when to use FormatterRegistrars. +See <> +and the `FormattingConversionServiceFactoryBean` for more information on when to use FormatterRegistrars. ==== [[mvc-config-validation]] === Validation -Spring provides a <> that can be used for validation in all layers +Spring provides a <> 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 <> Bean Validation +Spring also <> 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.