Spring Framework Reference Documentation
4.0.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 , Rob Winch
Copyright © 2004-2013
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
4.0.0.RELEASE
Spring Framework
Reference Documentation ii
Table of Contents
I. Overview of Spring Framework ................................................................................................ 1
1. Getting Started With Spring ............................................................................................ 2
2. Introduction to Spring Framework .................................................................................... 3
2.1. Dependency Injection and Inversion of Control ...................................................... 3
2.2. Modules .............................................................................................................. 3
Core Container .................................................................................................. 4
Data Access/Integration ...................................................................................... 4
Web .................................................................................................................. 5
AOP and Instrumentation ................................................................................... 5
Test ................................................................................................................... 5
2.3. Usage scenarios ................................................................................................. 5
Dependency Management and Naming Conventions ............................................ 9
Spring Dependencies and Depending on Spring .......................................... 9
Maven Dependency Management ............................................................. 10
Maven "Bill Of Materials" Dependency ....................................................... 10
Gradle Dependency Management ............................................................. 11
Ivy Dependency Management ................................................................... 11
Distribution Zip Files ................................................................................. 12
Logging ............................................................................................................ 12
Not Using Commons Logging ................................................................... 12
Using SLF4J ............................................................................................ 13
Using Log4J ............................................................................................. 14
II. What’s New in Spring Framework 4.x .................................................................................... 16
3. New Features and Enhancements in Spring Framework 4.0 ............................................ 17
3.1. Improved Getting Started Experience .................................................................. 17
3.2. Removed Deprecated Packages and Methods .................................................... 17
3.3. Java 8 (as well as 6 and 7) ............................................................................... 17
3.4. Java EE 6 and 7 ............................................................................................... 18
3.5. Groovy Bean Definition DSL .............................................................................. 18
3.6. Core Container Improvements ............................................................................ 19
3.7. General Web Improvements ............................................................................... 19
3.8. WebSocket, SockJS, and STOMP Messaging ..................................................... 19
3.9. Testing Improvements ........................................................................................ 20
III. Core Technologies .............................................................................................................. 21
4. The IoC container ........................................................................................................ 22
4.1. Introduction to the Spring IoC container and beans .............................................. 22
4.2. Container overview ............................................................................................ 22
Configuration metadata ..................................................................................... 23
Instantiating a container .................................................................................... 24
Composing XML-based configuration metadata .......................................... 25
Using the container .......................................................................................... 26
4.3. Bean overview ................................................................................................... 27
Naming beans .................................................................................................. 28
Aliasing a bean outside the bean definition ................................................ 28
Instantiating beans ........................................................................................... 29
Instantiation with a constructor .................................................................. 29
Instantiation with a static factory method .................................................... 30
Spring Framework
4.0.0.RELEASE
Spring Framework
Reference Documentation iii
Instantiation using an instance factory method ........................................... 30
4.4. Dependencies ................................................................................................... 32
Dependency injection ....................................................................................... 32
Constructor-based dependency injection .................................................... 32
Setter-based dependency injection ............................................................ 34
Dependency resolution process ................................................................. 35
Examples of dependency injection ............................................................. 36
Dependencies and configuration in detail ........................................................... 38
Straight values (primitives, Strings, and so on) ........................................... 38
References to other beans (collaborators) .................................................. 40
Inner beans .............................................................................................. 41
Collections ............................................................................................... 41
Null and empty string values ..................................................................... 44
XML shortcut with the p-namespace .......................................................... 44
XML shortcut with the c-namespace .......................................................... 46
Compound property names ....................................................................... 46
Using depends-on ............................................................................................ 47
Lazy-initialized beans ....................................................................................... 47
Autowiring collaborators .................................................................................... 48
Limitations and disadvantages of autowiring ............................................... 49
Excluding a bean from autowiring .............................................................. 50
Method injection ............................................................................................... 50
Lookup method injection ........................................................................... 51
Arbitrary method replacement ................................................................... 53
4.5. Bean scopes ..................................................................................................... 54
The singleton scope ......................................................................................... 55
The prototype scope ......................................................................................... 55
Singleton beans with prototype-bean dependencies ............................................ 56
Request, session, and global session scopes .................................................... 56
Initial web configuration ............................................................................ 57
Request scope ......................................................................................... 58
Session scope .......................................................................................... 58
Global session scope ............................................................................... 58
Scoped beans as dependencies ................................................................ 58
Custom scopes ................................................................................................ 60
Creating a custom scope .......................................................................... 60
Using a custom scope .............................................................................. 61
4.6. Customizing the nature of a bean ....................................................................... 62
Lifecycle callbacks ............................................................................................ 62
Initialization callbacks ............................................................................... 63
Destruction callbacks ................................................................................ 64
Default initialization and destroy methods .................................................. 64
Combining lifecycle mechanisms ............................................................... 66
Startup and shutdown callbacks ................................................................ 66
Shutting down the Spring IoC container gracefully in non-web applications
................................................................................................................. 68
ApplicationContextAware and BeanNameAware ................................................. 68
Other Aware interfaces ..................................................................................... 69
4.7. Bean definition inheritance ................................................................................. 71
4.8. Container Extension Points ................................................................................ 72
Spring Framework
4.0.0.RELEASE
Spring Framework
Reference Documentation iv
Customizing beans using a BeanPostProcessor ................................................. 72
Example: Hello World, BeanPostProcessor-style ........................................ 74
Example: The RequiredAnnotationBeanPostProcessor ............................... 75
Customizing configuration metadata with a BeanFactoryPostProcessor ................ 75
Example: the Class name substitution PropertyPlaceholderConfigurer .......... 76
Example: the PropertyOverrideConfigurer .................................................. 77
Customizing instantiation logic with a FactoryBean ............................................. 78
4.9. Annotation-based container configuration ............................................................ 79
@Required ....................................................................................................... 80
@Autowired ..................................................................................................... 80
Fine-tuning annotation-based autowiring with qualifiers ....................................... 83
Using generics as autowiring qualifiers .............................................................. 89
CustomAutowireConfigurer ................................................................................ 90
@Resource ...................................................................................................... 90
@PostConstruct and @PreDestroy .................................................................... 92
4.10. Classpath scanning and managed components ................................................. 92
@Component and further stereotype annotations ............................................... 93
Meta-annotations .............................................................................................. 93
Automatically detecting classes and registering bean definitions .......................... 94
Using filters to customize scanning ................................................................... 95
Defining bean metadata within components ....................................................... 96
Naming autodetected components ..................................................................... 97
Providing a scope for autodetected components ................................................ 98
Providing qualifier metadata with annotations ..................................................... 99
4.11. Using JSR 330 Standard Annotations ............................................................... 99
Dependency Injection with @Inject and @Named ............................................. 100
@Named: a standard equivalent to the @Component annotation ....................... 100
Limitations of the standard approach ............................................................... 101
4.12. Java-based container configuration ................................................................. 102
Basic concepts: @Bean and @Configuration ................................................... 102
Instantiating the Spring container using AnnotationConfigApplicationContext ....... 103
Simple construction ................................................................................ 103
Building the container programmatically using register(Class<?>…) ........... 104
Enabling component scanning with scan(String…) .................................... 104
Support for web applications with AnnotationConfigWebApplicationContext
............................................................................................................... 105
Using the @Bean annotation .......................................................................... 106
Declaring a bean .................................................................................... 107
Receiving lifecycle callbacks ................................................................... 107
Specifying bean scope ............................................................................ 108
Customizing bean naming ....................................................................... 109
Bean aliasing ......................................................................................... 109
Bean description ..................................................................................... 110
Using the @Configuration annotation ............................................................... 110
Injecting inter-bean dependencies ............................................................ 110
Lookup method injection ......................................................................... 111
Further information about how Java-based configuration works internally .... 111
Composing Java-based configurations ............................................................. 112
Using the @Import annotation ................................................................. 112
Conditionally including @Configuration classes or @Beans ....................... 116
Spring Framework
4.0.0.RELEASE
Spring Framework
Reference Documentation v
Combining Java and XML configuration ................................................... 117
4.13. Bean definition profiles and environment abstraction ........................................ 120
4.14. PropertySource Abstraction ............................................................................ 120
4.15. Registering a LoadTimeWeaver ...................................................................... 120
4.16. Additional Capabilities of the ApplicationContext .............................................. 120
Internationalization using MessageSource ........................................................ 121
Standard and Custom Events .......................................................................... 124
Convenient access to low-level resources ........................................................ 127
Convenient ApplicationContext instantiation for web applications ....................... 128
Deploying a Spring ApplicationContext as a J2EE RAR file ............................... 128
4.17. The BeanFactory ........................................................................................... 129
BeanFactory or ApplicationContext? ................................................................ 129
Glue code and the evil singleton ..................................................................... 131
5. Resources .................................................................................................................. 132
5.1. Introduction ..................................................................................................... 132
5.2. The Resource interface .................................................................................... 132
5.3. Built-in Resource implementations .................................................................... 133
UrlResource ................................................................................................... 133
ClassPathResource ........................................................................................ 133
FileSystemResource ....................................................................................... 134
ServletContextResource .................................................................................. 134
InputStreamResource ..................................................................................... 134
ByteArrayResource ......................................................................................... 134
5.4. The ResourceLoader ....................................................................................... 134
5.5. The ResourceLoaderAware interface ................................................................ 135
5.6. Resources as dependencies ............................................................................. 136
5.7. Application contexts and Resource paths .......................................................... 137
Constructing application contexts ..................................................................... 137
Constructing ClassPathXmlApplicationContext instances - shortcuts .......... 137
Wildcards in application context constructor resource paths ............................... 138
Ant-style Patterns ................................................................................... 138
The Classpath*: portability classpath*: prefix ............................................ 139
Other notes relating to wildcards ............................................................. 139
FileSystemResource caveats .......................................................................... 140
6. Validation, Data Binding, and Type Conversion ............................................................ 141
6.1. Introduction ..................................................................................................... 141
6.2. Validation using Spring’s Validator interface ...................................................... 141
6.3. Resolving codes to error messages .................................................................. 143
6.4. Bean manipulation and the BeanWrapper ......................................................... 144
Setting and getting basic and nested properties ............................................... 144
Built-in PropertyEditor implementations ............................................................ 146
Registering additional custom PropertyEditors .......................................... 149
6.5. Spring Type Conversion ................................................................................... 151
Converter SPI ................................................................................................ 151
ConverterFactory ............................................................................................ 152
GenericConverter ........................................................................................... 153
ConditionalGenericConverter ................................................................... 154
ConversionService API ................................................................................... 154
Configuring a ConversionService ..................................................................... 154
Using a ConversionService programmatically ................................................... 155
