Spring Framework Reference Documentation
3.2.0.RELEASE
Rod Johnson , Juergen Hoeller , Keith Donald , Colin Sampaleanu , Rob Harrop , Thomas
Risberg , Alef Arendsen , Darren Davison , Dmitriy Kopylenko , Mark Pollack , Thierry
Templier , Erwin Vervaet , Portia Tung , Ben Hale , Adrian Colyer , John Lewis , Costin Leau ,
Mark Fisher , Sam Brannen , Ramnivas Laddad , Arjen Poutsma , Chris Beams , Tareq
Abedrabbo , Andy Clement , Dave Syer , Oliver Gierke , Rossen Stoyanchev , Phillip Webb
Copyright © 2004-2012
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee
for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
Spring Framework
3.2.0.RELEASE
Spring Framework
Reference Documentation ii
Table of Contents
I. Overview of Spring Framework ................................................................................................ 1
1. Introduction to Spring Framework .................................................................................... 2
1.1. Dependency Injection and Inversion of Control ...................................................... 2
1.2. Modules .............................................................................................................. 2
Core Container .................................................................................................. 3
Data Access/Integration ...................................................................................... 3
Web .................................................................................................................. 4
AOP and Instrumentation ................................................................................... 4
Test ................................................................................................................... 4
1.3. Usage scenarios ................................................................................................. 5
Dependency Management and Naming Conventions ............................................ 8
Spring Dependencies and Depending on Spring ......................................... 10
Maven Dependency Management ............................................................. 10
Ivy Dependency Management ................................................................... 11
Logging ............................................................................................................ 12
Not Using Commons Logging ................................................................... 13
Using SLF4J ............................................................................................ 13
Using Log4J ............................................................................................. 14
II. What's New in Spring 3 ........................................................................................................ 16
2. New Features and Enhancements in Spring Framework 3.0 ............................................ 17
2.1. Java 5 .............................................................................................................. 17
2.2. Improved documentation .................................................................................... 17
2.3. New articles and tutorials ................................................................................... 17
2.4. New module organization and build system ......................................................... 18
2.5. Overview of new features .................................................................................. 19
Core APIs updated for Java 5 ........................................................................... 19
Spring Expression Language ............................................................................ 19
The Inversion of Control (IoC) container ............................................................ 20
Java based bean metadata ....................................................................... 20
Defining bean metadata within components ............................................... 21
General purpose type conversion system and field formatting system .................. 22
The Data Tier .................................................................................................. 22
The Web Tier ................................................................................................... 22
Comprehensive REST support .................................................................. 22
@MVC additions ...................................................................................... 22
Declarative model validation ............................................................................. 22
Early support for Java EE 6 .............................................................................. 22
Support for embedded databases ...................................................................... 23
3. New Features and Enhancements in Spring Framework 3.1 ............................................ 24
3.1. Cache Abstraction ............................................................................................. 24
3.2. Bean Definition Profiles ...................................................................................... 24
3.3. Environment Abstraction .................................................................................... 24
3.4. PropertySource Abstraction ................................................................................ 24
3.5. Code equivalents for Spring's XML namespaces ................................................. 24
3.6. Support for Hibernate 4.x ................................................................................... 25
3.7. TestContext framework support for @Configuration classes and bean definition
profiles ..................................................................................................................... 25
Spring Framework
3.2.0.RELEASE
Spring Framework
Reference Documentation iii
3.8. c: namespace for more concise constructor injection ............................................ 25
3.9. Support for injection against non-standard JavaBeans setters ............................... 25
3.10. Support for Servlet 3 code-based configuration of Servlet Container .................... 26
3.11. Support for Servlet 3 MultipartResolver ............................................................. 26
3.12. JPA EntityManagerFactory bootstrapping without persistence.xml ....................... 26
3.13. New HandlerMethod-based Support Classes For Annotated Controller
Processing ............................................................................................................... 26
3.14. "consumes" and "produces" conditions in @RequestMapping ............................ 27
3.15. Flash Attributes and RedirectAttributes .................................................... 27
3.16. URI Template Variable Enhancements .............................................................. 27
3.17. @Valid On @RequestBody Controller Method Arguments ................................ 28
3.18. @RequestPart Annotation On Controller Method Arguments ............................. 28
3.19. UriComponentsBuilder and UriComponents .............................................. 28
4. New Features and Enhancements in Spring Framework 3.2 ............................................ 29
4.1. Support for Servlet 3 based asynchronous request processing .............................. 29
4.2. Spring MVC Test framework .............................................................................. 29
4.3. Content negotiation improvements ...................................................................... 29
4.4. @ControllerAdvice annotation ...................................................................... 29
4.5. Matrix variables ................................................................................................. 30
4.6. Abstract base class for code-based Servlet 3+ container initialization .................... 30
4.7. ResponseEntityExceptionHandler class ..................................................... 30
4.8. Support for generic types in the RestTemplate and in @RequestBody
arguments ................................................................................................................ 30
4.9. Jackson JSON 2 and related improvements ........................................................ 30
4.10. Tiles 3 ............................................................................................................. 31
4.11. @RequestBody improvements ......................................................................... 31
4.12. HTTP PATCH method ...................................................................................... 31
4.13. Excluded patterns in mapped interceptors ......................................................... 31
4.14. Using meta-annotations for injection points and for bean definition methods ......... 31
4.15. Initial support for JCache 0.5 ............................................................................ 31
4.16. Support for @DateTimeFormat without Joda Time ........................................... 31
4.17. Global date & time formatting ........................................................................... 31
4.18. New Testing Features ...................................................................................... 32
4.19. Concurrency refinements across the framework ................................................. 32
4.20. New Gradle-based build and move to GitHub .................................................... 32
4.21. Refined Java SE 7 / OpenJDK 7 support .......................................................... 32
III. Core Technologies .............................................................................................................. 33
5. The IoC container ........................................................................................................ 34
5.1. Introduction to the Spring IoC container and beans .............................................. 34
5.2. Container overview ............................................................................................ 34
Configuration metadata ..................................................................................... 35
Instantiating a container .................................................................................... 36
Composing XML-based configuration metadata .......................................... 37
Using the container .......................................................................................... 38
5.3. Bean overview ................................................................................................... 39
Naming beans .................................................................................................. 40
Aliasing a bean outside the bean definition ................................................ 40
Instantiating beans ........................................................................................... 41
Instantiation with a constructor .................................................................. 41
Instantiation with a static factory method .................................................... 42
Spring Framework
3.2.0.RELEASE
Spring Framework
Reference Documentation iv
Instantiation using an instance factory method ........................................... 42
5.4. Dependencies ................................................................................................... 44
Dependency injection ....................................................................................... 44
Constructor-based dependency injection .................................................... 44
Setter-based dependency injection ............................................................ 46
Dependency resolution process ................................................................. 47
Examples of dependency injection ............................................................. 48
Dependencies and configuration in detail ........................................................... 50
Straight values (primitives, Strings, and so on) ....................................... 50
References to other beans (collaborators) .................................................. 52
Inner beans .............................................................................................. 53
Collections ............................................................................................... 53
Null and empty string values ..................................................................... 56
XML shortcut with the p-namespace .......................................................... 56
XML shortcut with the c-namespace .......................................................... 58
Compound property names ....................................................................... 58
Using depends-on .......................................................................................... 59
Lazy-initialized beans ....................................................................................... 59
Autowiring collaborators .................................................................................... 60
Limitations and disadvantages of autowiring ............................................... 61
Excluding a bean from autowiring .............................................................. 61
Method injection ............................................................................................... 62
Lookup method injection ........................................................................... 63
Arbitrary method replacement ................................................................... 64
5.5. Bean scopes ..................................................................................................... 65
The singleton scope ......................................................................................... 66
The prototype scope ......................................................................................... 67
Singleton beans with prototype-bean dependencies ............................................ 68
Request, session, and global session scopes .................................................... 68
Initial web configuration ............................................................................ 69
Request scope ......................................................................................... 69
Session scope .......................................................................................... 70
Global session scope ............................................................................... 70
Scoped beans as dependencies ................................................................ 70
Custom scopes ................................................................................................ 72
Creating a custom scope .......................................................................... 72
Using a custom scope .............................................................................. 73
5.6. Customizing the nature of a bean ....................................................................... 74
Lifecycle callbacks ............................................................................................ 74
Initialization callbacks ............................................................................... 75
Destruction callbacks ................................................................................ 75
Default initialization and destroy methods .................................................. 76
Combining lifecycle mechanisms ............................................................... 77
Startup and shutdown callbacks ................................................................ 78
Shutting down the Spring IoC container gracefully in non-web applications
................................................................................................................. 79
ApplicationContextAware and BeanNameAware ........................................ 80
Other Aware interfaces .................................................................................... 81
5.7. Bean definition inheritance ................................................................................. 82
5.8. Container Extension Points ................................................................................ 83
Spring Framework
3.2.0.RELEASE
Spring Framework
Reference Documentation v
Customizing beans using a BeanPostProcessor ............................................ 83
Example: Hello World, BeanPostProcessor-style .................................... 85
Example: The RequiredAnnotationBeanPostProcessor ..................... 86
Customizing configuration metadata with a BeanFactoryPostProcessor ........ 87
Example: the PropertyPlaceholderConfigurer ................................. 88
Example: the PropertyOverrideConfigurer ....................................... 89
Customizing instantiation logic with a FactoryBean .......................................... 90
5.9. Annotation-based container configuration ............................................................ 91
@Required ...................................................................................................... 92
@Autowired .................................................................................................... 92
Fine-tuning annotation-based autowiring with qualifiers ....................................... 95
CustomAutowireConfigurer ...................................................................... 100
@Resource .................................................................................................... 101
@PostConstruct and @PreDestroy ............................................................ 102
5.10. Classpath scanning and managed components ................................................ 102
@Component and further stereotype annotations .............................................. 103
Automatically detecting classes and registering bean definitions ........................ 103
Using filters to customize scanning .................................................................. 104
Defining bean metadata within components ..................................................... 105
Naming autodetected components ................................................................... 106
Providing a scope for autodetected components ............................................... 107
Providing qualifier metadata with annotations ................................................... 108
5.11. Using JSR 330 Standard Annotations ............................................................. 108
Dependency Injection with @Inject and @Named ............................................ 109
@Named: a standard equivalent to the @Component annotation ......................... 109
Limitations of the standard approach ............................................................... 110
5.12. Java-based container configuration ................................................................. 111
Basic concepts: @Configuration and @Bean ................................................ 111
Instantiating the Spring container using
AnnotationConfigApplicationContext .................................................. 111
Simple construction ................................................................................ 112
Building the container programmatically using register(Class<?>...)
............................................................................................................... 112
Enabling component scanning with scan(String...) ........................... 112
Support for web applications with
AnnotationConfigWebApplicationContext .................................... 113
Composing Java-based configurations ............................................................. 114
Using the @Import annotation ................................................................ 114
Combining Java and XML configuration ................................................... 117
Using the @Bean annotation ............................................................................ 120
Declaring a bean .................................................................................... 120
Injecting dependencies ........................................................................... 120
Receiving lifecycle callbacks ................................................................... 121
Specifying bean scope ............................................................................ 122
Customizing bean naming ....................................................................... 123
Bean aliasing ......................................................................................... 123
Further information about how Java-based configuration works internally ............ 124
5.13. Registering a LoadTimeWeaver .................................................................... 125
5.14. Additional Capabilities of the ApplicationContext ...................................... 125
Internationalization using MessageSource ...................................................... 126
