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

Polish recent changes to reference manual

This commit is contained in:
Sam Brannen 2014-09-02 22:15:12 +02:00
parent 98eb0f75bc
commit 1f6c40fd86
1 changed files with 91 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
src/asciidoc/index.adoc
View File

@ -121,122 +121,127 @@ robust, __maintainable__ applications.
=== Modules === Modules
The Spring Framework consists of features organized into about 20 modules. These modules The Spring Framework consists of features organized into about 20 modules. These modules
are grouped into Core Container, Data Access/Integration, Web, AOP (Aspect Oriented are grouped into Core Container, Data Access/Integration, Web, AOP (Aspect Oriented
Programming), Instrumentation, and Test, as shown in the following diagram. Programming), Instrumentation, Messaging, and Test, as shown in the following diagram.
.Overview of the Spring Framework .Overview of the Spring Framework
image::images/spring-overview.png[width=400] image::images/spring-overview.png[width=400]
The next parts will list, for each feature, the available modules with their artifact name and their goal. The following sections list the available modules for each feature along with their
Artifacts names are the reference names to use in <<dependency-management,Dependency Management tools>>. artifact name and the topics they cover. Artifact names correlate to _artifact IDs_ used
in <<dependency-management,Dependency Management tools>>.
[[overview-core-container]] [[overview-core-container]]
==== Core Container ==== Core Container
The <<beans-introduction,__Core Container__>> consists of the `spring-core`, `spring-beans`, `spring-context`, and The <<beans-introduction,__Core Container__>> consists of the `spring-core`,
`spring-expression` (Spring Expression Language) modules. `spring-beans`, `spring-context`, and `spring-expression` (Spring Expression Language)
modules.
The `spring-core` and `spring-beans` modules <<beans-introduction,provide the fundamental parts of the framework>>, The `spring-core` and `spring-beans` modules <<beans-introduction,provide the fundamental
including the IoC and Dependency Injection features. The `BeanFactory` is parts of the framework>>, including the IoC and Dependency Injection features. The
a sophisticated implementation of the factory pattern. It removes the need for `BeanFactory` is a sophisticated implementation of the factory pattern. It removes the
programmatic singletons and allows you to decouple the configuration and specification need for programmatic singletons and allows you to decouple the configuration and
of dependencies from your actual program logic. specification of dependencies from your actual program logic.
The <<context-introduction,__Context__>> (`spring-context`) module builds on the solid base provided by the The <<context-introduction,__Context__>> (`spring-context`) module builds on the solid
<<beans-introduction,__Core and Beans__>> modules: it is a means to access objects in a base provided by the <<beans-introduction,__Core and Beans__>> modules: it is a means to
framework-style manner that is similar to a JNDI registry. The Context module inherits access objects in a framework-style manner that is similar to a JNDI registry. The
its features from the Beans module and adds support for internationalization (using, for Context module inherits its features from the Beans module and adds support for
example, resource bundles), event-propagation, resource-loading, and the transparent internationalization (using, for example, resource bundles), event propagation, resource
creation of contexts by, for example, a servlet container. The Context module also loading, and the transparent creation of contexts by, for example, a Servlet container.
supports Java EE features such as EJB, JMX ,and basic remoting. The `ApplicationContext` The Context module also supports Java EE features such as EJB, JMX, and basic remoting.
interface is the focal point of the Context module. The `ApplicationContext` interface is the focal point of the Context module.
The `spring-expression` module provides a powerful <<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
assignment, method invocation, accessing the content of arrays, collections and indexers,
logical and arithmetic operators, named variables, and retrieval of objects by name from
Spring's IoC container. It also supports list projection and selection as well as common
list aggregations.
The `spring-expression` module provides a powerful <<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 assignment, method
invocation, accessing the context of arrays, collections and indexers, logical and
arithmetic operators, named variables, and retrieval of objects by name from Spring's
IoC container. It also supports list projection and selection as well as common list
aggregations.
[[overview-aop-instrumentation]] [[overview-aop-instrumentation]]
==== AOP and Instrumentation ==== AOP and Instrumentation
The `spring-aop` module provides an <<aop-introduction,__AOP__>> Alliance-compliant The `spring-aop` module provides an <<aop-introduction,__AOP__>> Alliance-compliant
aspect-oriented programming implementation allowing you to define, for example, aspect-oriented programming implementation allowing you to define, for example,
method-interceptors and pointcuts to cleanly decouple code that implements functionality method interceptors and pointcuts to cleanly decouple code that implements functionality
that should be separated. Using source-level metadata functionality, you can also that should be separated. Using source-level metadata functionality, you can also
incorporate behavioral information into your code, in a manner similar to that of .NET incorporate behavioral information into your code, in a manner similar to that of .NET
attributes. attributes.
The separate `spring-aspets` module provides integration with AspectJ. The separate `spring-aspects` module provides integration with AspectJ.
The `spring-instrument` module provides class instrumentation support and classloader The `spring-instrument` module provides class instrumentation support and classloader
implementations to be used in certain application servers. implementations to be used in certain application servers.
[[overview-messaging]] [[overview-messaging]]
==== Messaging ==== Messaging
Spring Framework 4 includes a new `spring-messaging` module with key abstractions from Spring Framework 4 includes a `spring-messaging` module with key abstractions from the
the _Spring Integration_ project such as `Message`, `MessageChannel`, _Spring Integration_ project such as `Message`, `MessageChannel`, `MessageHandler`, and
`MessageHandler` and others to serve as a foundation for messaging-based applications. The others to serve as a foundation for messaging-based applications. The module also
module also includes a set of annotations for mapping messages to methods, similar to the includes a set of annotations for mapping messages to methods, similar to the Spring MVC
Spring MVC annotation based programming model. annotation based programming model.
[[overview-data-access]] [[overview-data-access]]
==== Data Access/Integration ==== Data Access/Integration
The __Data Access/Integration__ layer consists of the JDBC, ORM, OXM, JMS and The __Data Access/Integration__ layer consists of the JDBC, ORM, OXM, JMS, and
Transaction modules. Transaction modules.
The `spring-jdbc` module provides a <<jdbc-introduction,JDBC>>-abstraction layer that removes the The `spring-jdbc` module provides a <<jdbc-introduction,JDBC>>-abstraction layer that
need to do tedious JDBC coding and parsing of database-vendor specific error codes. removes the need to do tedious JDBC coding and parsing of database-vendor specific error
codes.
The `spring-orm` module provides integration layers for popular The `spring-orm` module provides integration layers for popular
<<orm-introduction,object-relational mapping>> APIs, including <<orm-jpa,JPA>>, <<orm-jdo,JDO>>, and <<orm-introduction,object-relational mapping>> APIs, including <<orm-jpa,JPA>>,
<<orm-hibernate,Hibernate>> (see also `spring-orm-hibernate4` for Hibernate 4 support). <<orm-jdo,JDO>>, and <<orm-hibernate,Hibernate>>. Using the `spring-orm` module you can
Using the ORM package you can use all of these O/R-mapping frameworks in combination with all of the use all of these O/R-mapping frameworks in combination with all of the other features
other features Spring offers, such as the simple declarative transaction management feature mentioned previously. 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>> The `spring-oxm` module provides an abstraction layer that supports <<oxm,Object/XML
implementations for JAXB, Castor, XMLBeans, JiBX and XStream. mapping>> implementations such as JAXB, Castor, XMLBeans, JiBX and XStream.
The `spring-jms` module (<<jms,Java Messaging Service>>) contains features for producing and The `spring-jms` module (<<jms,Java Messaging Service>>) contains features for producing and
consuming messages. Since Spring Framework 4.1, it provides an integration with the consuming messages. Since Spring Framework 4.1, it provides integration with the
`spring-messaging` module. `spring-messaging` module.
The `spring-tx` module supports <<transaction,programmatic and declarative transaction>> The `spring-tx` module supports <<transaction,programmatic and declarative transaction>>
management for classes that implement special interfaces and for __all your POJOs (plain management for classes that implement special interfaces and for __all your POJOs (Plain
old Java objects)__. Old Java Objects)__.
[[overview-web]] [[overview-web]]
==== Web ==== Web
The __Web__ layer consists of the `spring-web`, `spring-webmvc`, `spring-websocket` and `spring-webmvc-portlet` modules. The __Web__ layer consists of the `spring-web`, `spring-webmvc`, `spring-websocket`, and
`spring-webmvc-portlet` modules.
The `spring-web` module provides basic web-oriented integration features such as The `spring-web` module provides basic web-oriented integration features such as
multipart file-upload functionality and the initialization of the IoC container using multipart file upload functionality and the initialization of the IoC container using
servlet listeners and a web-oriented application context. It also contains the Servlet listeners and a web-oriented application context. It also contains the
web-related parts of Spring's remoting support. web-related parts of Spring's remoting support.
The `spring-webmvc` module (also known as `__Web-Servlet__) contains Spring's model-view-controller The `spring-webmvc` module (also known as the __Web-Servlet__ module) contains Spring's
(<<mvc-introduction,__MVC__>>) implementation for web applications. Spring's MVC model-view-controller (<<mvc-introduction,__MVC__>>) implementation for web applications.
framework provides a clean separation between domain model code and web forms, and Spring's MVC framework provides a clean separation between domain model code and web
integrates with all the other features of the Spring Framework. forms and integrates with all of the other features of the Spring Framework.
The `spring-webmvc-portlet` module (also __Web-Portlet__ module) provides the MVC implementation to be used in a portlet
environment and mirrors the functionality of Web-Servlet module.
The `spring-webmvc-portlet` module (also known as the __Web-Portlet__ module) provides
the MVC implementation to be used in a Portlet environment and mirrors the functionality
of the `spring-webmvc` module.
[[overview-testing]] [[overview-testing]]
==== Test ==== Test
The `spring-test` module supports the testing of Spring components with JUnit or TestNG. It The `spring-test` module supports the <<unit-testing,unit testing>> and
provides consistent loading of Spring ApplicationContexts and caching of those contexts. <<integration-testing,integration testing>> of Spring components with JUnit or TestNG. It
It also provides mock objects that you can use to test your code in isolation. 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
code in isolation.
@ -993,9 +998,9 @@ Framework 4.0 introduces several new features for use in unit and integration te
Spring 4.1 introduces a much simpler infrastructure <<jms-annotated,to register JMS Spring 4.1 introduces a much simpler infrastructure <<jms-annotated,to register JMS
listener endpoints>> by annotating bean methods with listener endpoints>> by annotating bean methods with
{javadoc-baseurl}/org/springframework/jms/annotation/JmsListener.html[`@JmsListener`]. {javadoc-baseurl}/org/springframework/jms/annotation/JmsListener.html[`@JmsListener`].
The XML namespace has been enhanced to support this new style (`jms:annotation-driven`) The XML namespace has been enhanced to support this new style (`jms:annotation-driven`),
and it is also possible to fully configure the infrastructure using Java config ( and it is also possible to fully configure the infrastructure using Java config
{javadoc-baseurl}/org/springframework/jms/annotation/EnableJms.html[`@EnableJms`], ({javadoc-baseurl}/org/springframework/jms/annotation/EnableJms.html[`@EnableJms`],
`JmsListenerContainerFactory`). It is also possible to register listener endpoints `JmsListenerContainerFactory`). It is also possible to register listener endpoints
programmatically using programmatically using
{javadoc-baseurl}/org/springframework/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`]. {javadoc-baseurl}/org/springframework/jms/annotation/JmsListenerConfigurer.html[`JmsListenerConfigurer`].
@ -1004,18 +1009,18 @@ Spring 4.1 also aligns its JMS support to allow you to benefit from the `spring-
abstraction introduced in 4.0, that is: abstraction introduced in 4.0, that is:
* Message listener endpoints can have a more flexible signature and benefit from * Message listener endpoints can have a more flexible signature and benefit from
standard messaging annotations such as `@Payload`, `@Header`, `@Headers` and `@SendTo`. It standard messaging annotations such as `@Payload`, `@Header`, `@Headers`, and `@SendTo`. It
is also possible to use a standard `Message` in lieu of `javax.jms.Message` as method is also possible to use a standard `Message` in lieu of `javax.jms.Message` as method
argument argument.
* A new {javadoc-baseurl}/org/springframework/jms/core/JmsMessageOperations.html[`JmsMessageOperations`] * A new {javadoc-baseurl}/org/springframework/jms/core/JmsMessageOperations.html[`JmsMessageOperations`]
interface is available and permits `JmsTemplate` like operations using the `Message` interface is available and permits `JmsTemplate` like operations using the `Message`
abstraction abstraction.
Finally, Spring 4.1 provides additional miscellaneous improvements: Finally, Spring 4.1 provides additional miscellaneous improvements:
* Synchronous request-reply operations support in `JmsTemplate` * Synchronous request-reply operations support in `JmsTemplate`
* Listener priority can be specified per `<jms:listener/>` element * Listener priority can be specified per `<jms:listener/>` element
* Recovery options for the message listener container is configurable using a * Recovery options for the message listener container are configurable using a
{javadoc-baseurl}/org/springframework/util/backoff/BackOff.html[`BackOff`] implementation {javadoc-baseurl}/org/springframework/util/backoff/BackOff.html[`BackOff`] implementation
* JMS 2.0 shared consumers are supported * JMS 2.0 shared consumers are supported
@ -1025,35 +1030,35 @@ Spring 4.1 supports <<cache-jsr-107,JCache (JSR-107) annotations>> using Spring'
existing cache configuration and infrastructure abstraction; no changes are required existing cache configuration and infrastructure abstraction; no changes are required
to use the standard annotations. to use the standard annotations.
Spring 4.1 also improves its own abstraction significantly: Spring 4.1 also improves its own caching abstraction significantly:
* Caches can be resolved at runtime using a * Caches can be resolved at runtime using a
<<cache-annotations-cacheable-cache-resolver,`CacheResolver`>>. As a result the <<cache-annotations-cacheable-cache-resolver,`CacheResolver`>>. As a result the
`value` argument defining the cache name(s) to use is no longer mandatory `value` argument defining the cache name(s) to use is no longer mandatory.
* More operation-level customizations: cache resolver, cache manager, key * More operation-level customizations: cache resolver, cache manager, key
generator generator
* A new <<cache-annotations-config,`@CacheConfig` class-level annotation>> allows * A new <<cache-annotations-config,`@CacheConfig` class-level annotation>> allows
to share common settings at class level **without** enabling any cache operation common settings to be shared at the class level **without** enabling any cache operation.
* Better exception handling of cached methods using `CacheErrorHandler` * Better exception handling of cached methods using `CacheErrorHandler`
Spring 4.1 also has a breaking change in the `CacheInterface` as a new Spring 4.1 also has a breaking change in the `CacheInterface` as a new `putIfAbsent`
`putIfAbsent` method has been added. method has been added.
=== Web Improvements === Web Improvements
* The JDK 1.8 `java.util.Optional` is now supported for `@RequestParam`, `@RequestHeader` * JDK 1.8's `java.util.Optional` is now supported for `@RequestParam`, `@RequestHeader`,
and `@MatrixVariable` controller method arguments while `ListenableFuture` is supported as and `@MatrixVariable` controller method arguments, while `ListenableFuture` is supported as
a return value alternative to `DeferredResult` where an underlying service (or perhaps a a return value alternative to `DeferredResult` where an underlying service (or perhaps a
call to `AsyncRestTemplate`) already returns `ListenableFuture`. call to `AsyncRestTemplate`) already returns `ListenableFuture`.
* Jackson's `@JsonView` is supported directly on `@ResponseBody` and `ResponseEntity` * Jackson's `@JsonView` is supported directly on `@ResponseBody` and `ResponseEntity`
controller methods for serializing different amounts of detail for the same POJO, controller methods for serializing different amounts of detail for the same POJO -- for
e.g. summary vs detail page. This is also supported with View-based rendering by example, summary vs. detail page. This is also supported with View-based rendering by
adding the serialization view type as a model attribute under a special key. adding the serialization view type as a model attribute under a special key.
See <<mvc-ann-jsonview>> for details. See <<mvc-ann-jsonview>> for details.
* Jackson based XML serialization is now supported using * Jackson based XML serialization is now supported using
https://github.com/FasterXML/jackson-dataformat-xml[jackson-dataformat-xml] extension. https://github.com/FasterXML/jackson-dataformat-xml[jackson-dataformat-xml] extension.
When using `@EnableWebMvc` or `<mvc:annotation-driven/>`, Jackson will be used by default When using `@EnableWebMvc` or `<mvc:annotation-driven/>`, Jackson will be used by default
instead of JAXB2 if jackson-dataformat-xml classes are found in the classpath. instead of JAXB2 if `jackson-dataformat-xml` classes are found in the classpath.
* JSONP is now supported with Jackson. * JSONP is now supported with Jackson.
* A `@ControllerAdvice` can now also implement `ResponseBodyAdvice` in which case it will be * A `@ControllerAdvice` can now also implement `ResponseBodyAdvice` in which case it will be
called after the controller method returns but before the response is written and called after the controller method returns but before the response is written and
@ -1070,12 +1075,12 @@ Spring 4.1 also has a breaking change in the `CacheInterface` as a new
as JSPs can also build links to controllers by referring to their mappings by name. as JSPs can also build links to controllers by referring to their mappings by name.
A default name is assigned to every `@RequestMapping`. For example `FooController` with method A default name is assigned to every `@RequestMapping`. For example `FooController` with method
`handleFoo` is assigned "FC#handleFoo" by default but the naming strategy is customizable `handleFoo` is assigned "FC#handleFoo" by default but the naming strategy is customizable
and can be also be set explicitly through the new name attribute on `@RequestMapping`. and can be also be set explicitly through the new `name` attribute on `@RequestMapping`.
A new mvcUrl Spring JSP tag makes this easy to use in JSP pages. A new `mvcUrl` Spring JSP tag makes this easy to use in JSP pages.
The same can be done for any other view technology. The same can be done for any other view technology.
* The familiar `ResponseEntity` now has a builder-style API that guides controller methods * The familiar `ResponseEntity` now has a builder-style API that guides controller methods
towards the preparation of server-side responses, e.g. `ResponseEntity.ok()`. towards the preparation of server-side responses, e.g. `ResponseEntity.ok()`.
For the client side there is a new RequestEntity also offering a builder-style API that For the client side there is a new `RequestEntity` also offering a builder-style API that
guides towards the preparation of client-side HTTP requests. guides towards the preparation of client-side HTTP requests.
* MVC Java config and XML namespace: * MVC Java config and XML namespace:
** View resolver configuration -- if you've had to configure view resolution with content ** View resolver configuration -- if you've had to configure view resolution with content
@ -1085,7 +1090,7 @@ Spring 4.1 also has a breaking change in the `CacheInterface` as a new
without the need for controller logic, view controllers now have built-in support for without the need for controller logic, view controllers now have built-in support for
redirecting and setting the response status. An application can use this to configure redirecting and setting the response status. An application can use this to configure
redirect URLs, render 404 responses with a view, send "no content" responses, etc. redirect URLs, render 404 responses with a view, send "no content" responses, etc.
Some use cases https://jira.spring.io/browse/SPR-11543?focusedCommentId=100308&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-100308[listed here]. Some use cases are https://jira.spring.io/browse/SPR-11543?focusedCommentId=100308&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-100308[listed here].
** Path matching -- these frequently used customizations are now built-in and have also been ** Path matching -- these frequently used customizations are now built-in and have also been
backported to 4.0. See <<mvc-config-path-matching>> for details. backported to 4.0. See <<mvc-config-path-matching>> for details.
* http://groovy-lang.org/docs/groovy-2.3.6/html/documentation/markup-template-engine.html[Groovy markup template] * http://groovy-lang.org/docs/groovy-2.3.6/html/documentation/markup-template-engine.html[Groovy markup template]
@ -1120,7 +1125,7 @@ Spring 4.1 also has a breaking change in the `CacheInterface` as a new
* JSON responses can be asserted with https://github.com/skyscreamer/JSONassert[JSON Assert] * JSON responses can be asserted with https://github.com/skyscreamer/JSONassert[JSON Assert]
as an extra option to using JSONPath much like it has been possible to do for XML with as an extra option to using JSONPath much like it has been possible to do for XML with
XMLUnit. XMLUnit.
* `MockMvcBuilder` "recipies" can now be created with the help of `MockMvcConfigurer`. This * `MockMvcBuilder` _recipes_ can now be created with the help of `MockMvcConfigurer`. This
was added to make it easy to apply Spring Security setup but can be used to encapsulate was added to make it easy to apply Spring Security setup but can be used to encapsulate
common setup for any 3rd party framework or within a project. common setup for any 3rd party framework or within a project.
* `MockRestServiceServer` now supports the `AsyncRestTemplate` for client-side testing. * `MockRestServiceServer` now supports the `AsyncRestTemplate` for client-side testing.