0% found this document useful (0 votes)

3K views1,194 pages

Spring Framework Reference Documentation PDF

Uploaded by

chumix23

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

3K views1,194 pages

Spring Framework Reference Documentation PDF

Uploaded by

chumix23

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 1194

Spring Framework Reference Documentation

1 de 1194

http://docs.spring.io/spring/docs/current/spring-framework-reference/h...

Spring Framework Reference

Documentation
Authors
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 , Brian Clozel , Stephane Nicoll , Sebastien
Deleuze

4.3.2.RELEASE

Copyright 2004-2016
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.

Table of Contents

I. Overview of Spring Framework

1. Getting Started with Spring
2. Introduction to the Spring Framework
2.1. Dependency Injection and Inversion of Control
2.2. Modules
2.2.1. Core Container
2.2.2. AOP and Instrumentation
2.2.3. Messaging
2.2.4. Data Access/Integration
2.2.5. Web
2.2.6. Test

2.3. Usage scenarios

2.3.1. Dependency Management and
Naming
Conventions
Search
Documentation

25/08/2016 12:10

Spring Framework Reference Documentation

2 de 1194

Spring Dependencies and Depending on Spring

Maven Dependency Management
Maven "Bill Of Materials" Dependency
Gradle Dependency Management
Ivy Dependency Management
Distribution Zip Files
2.3.2. Logging
Not Using Commons Logging
Using SLF4J
Using Log4J

II. Whats New in Spring Framework 4.x

3. New Features and Enhancements in Spring
Framework 4.0
3.1. Improved Getting Started Experience
3.2. Removed Deprecated Packages and Methods
3.3. Java 8 (as well as 6 and 7)
3.4. Java EE 6 and 7
3.5. Groovy Bean Definition DSL
3.6. Core Container Improvements
3.7. General Web Improvements
3.8. WebSocket, SockJS, and STOMP Messaging
3.9. Testing Improvements

4. New Features and Enhancements in Spring

Framework 4.1
4.1. JMS Improvements
4.2. Caching Improvements
4.3. Web Improvements
4.4. WebSocket Messaging Improvements
4.5. Testing Improvements

5. New Features and Enhancements in Spring

Framework 4.2
5.1. Core Container Improvements
25/08/2016 12:10

Spring Framework Reference Documentation

3 de 1194

5.2. Data Access Improvements

5.3. JMS Improvements
5.4. Web Improvements
5.5. WebSocket Messaging Improvements
5.6. Testing Improvements

6. New Features and Enhancements in Spring

Framework 4.3
6.1. Core Container Improvements
6.2. Data Access Improvements
6.3. Caching Improvements
6.4. JMS Improvements
6.5. Web Improvements
6.6. WebSocket Messaging Improvements
6.7. Testing Improvements
6.8. Support for new library and server generations

III. Core Technologies

7. The IoC container
7.1. Introduction to the Spring IoC container and beans
7.2. Container overview
7.2.1. Configuration metadata
7.2.2. Instantiating a container
Composing XML-based configuration metadata
7.2.3. Using the container

7.3. Bean overview

7.3.1. Naming beans
Aliasing a bean outside the bean definition
7.3.2. Instantiating beans
Instantiation with a constructor
Instantiation with a static factory method
Instantiation using an instance factory method

7.4. Dependencies
7.4.1. Dependency Injection
Constructor-based dependency injection

25/08/2016 12:10

Spring Framework Reference Documentation

4 de 1194

Setter-based dependency injection

Dependency resolution process
Examples of dependency injection
7.4.2. Dependencies and configuration in detail
Straight values (primitives, Strings, and so on)
References to other beans (collaborators)
Inner beans
Collections
Null and empty string values
XML shortcut with the p-namespace
XML shortcut with the c-namespace
Compound property names
7.4.3. Using depends-on
7.4.4. Lazy-initialized beans
7.4.5. Autowiring collaborators
Limitations and disadvantages of autowiring
Excluding a bean from autowiring
7.4.6. Method injection
Lookup method injection
Arbitrary method replacement

7.5. Bean scopes

7.5.1. The singleton scope
7.5.2. The prototype scope
7.5.3. Singleton beans with prototype-bean dependencies
7.5.4. Request, session, global session, application, and WebSocket
scopes
Initial web configuration
Request scope
Session scope
Global session scope
Application scope
Scoped beans as dependencies
7.5.5. Custom scopes
Creating a custom scope
Using a custom scope

7.6. Customizing the nature of a bean

7.6.1. Lifecycle callbacks
Initialization callbacks
Destruction callbacks
Default initialization and destroy methods
Combining lifecycle mechanisms
Startup and shutdown callbacks
Shutting down the Spring IoC container gracefully in non-web
applications
7.6.2. ApplicationContextAware and BeanNameAware
7.6.3. Other Aware interfaces

7.7. Bean definition inheritance

25/08/2016 12:10

Spring Framework Reference Documentation

5 de 1194

7.8.1. Customizing beans using a BeanPostProcessor

Example: Hello World, BeanPostProcessor-style
Example: The RequiredAnnotationBeanPostProcessor
7.8.2. Customizing configuration metadata with a
BeanFactoryPostProcessor
Example: the Class name substitution
PropertyPlaceholderConfigurer
Example: the PropertyOverrideConfigurer
7.8.3. Customizing instantiation logic with a FactoryBean

7.9. Annotation-based container configuration

7.9.1. @Required
7.9.2. @Autowired
7.9.3. Fine-tuning annotation-based autowiring with @Primary
7.9.4. Fine-tuning annotation-based autowiring with qualifiers
7.9.5. Using generics as autowiring qualifiers
7.9.6. CustomAutowireConfigurer
7.9.7. @Resource
7.9.8. @PostConstruct and @PreDestroy

7.10. Classpath scanning and managed components

7.10.1. @Component and further stereotype annotations
7.10.2. Meta-annotations
7.10.3. Automatically detecting classes and registering bean definitions
7.10.4. Using filters to customize scanning
7.10.5. Defining bean metadata within components
7.10.6. Naming autodetected components
7.10.7. Providing a scope for autodetected components
7.10.8. Providing qualifier metadata with annotations

7.11. Using JSR 330 Standard Annotations

7.11.1. Dependency Injection with @Inject and @Named
7.11.2. @Named: a standard equivalent to the @Component annotation
7.11.3. Limitations of JSR-330 standard annotations

7.12. Java-based container configuration

7.12.1. Basic concepts: @Bean and @Configuration
7.12.2. Instantiating the Spring container using
AnnotationConfigApplicationContext
Simple construction
Building the container programmatically using register(Class<?>)
Enabling component scanning with scan(String)
Support for web applications with
AnnotationConfigWebApplicationContext
7.12.3. Using the @Bean annotation
Declaring a bean
Bean dependencies
Receiving lifecycle callbacks
Specifying bean scope
Customizing bean naming
Bean aliasing

25/08/2016 12:10

Spring Framework Reference Documentation

6 de 1194

7.12.4. Using the @Configuration annotation

Injecting inter-bean dependencies
Lookup method injection
Further information about how Java-based configuration works
internally
7.12.5. Composing Java-based configurations
Using the @Import annotation
Conditionally include @Configuration classes or @Bean methods
Combining Java and XML configuration

7.13. Environment abstraction

7.13.1. Bean definition profiles
@Profile
7.13.2. XML bean definition profiles
Activating a profile
Default profile
7.13.3. PropertySource abstraction
7.13.4. @PropertySource
7.13.5. Placeholder resolution in statements

7.14. Registering a LoadTimeWeaver

7.15. Additional Capabilities of the ApplicationContext
7.15.1. Internationalization using MessageSource
7.15.2. Standard and Custom Events
Annotation-based Event Listeners
Asynchronous Listeners
Ordering Listeners
Generic Events
7.15.3. Convenient access to low-level resources
7.15.4. Convenient ApplicationContext instantiation for web applications
7.15.5. Deploying a Spring ApplicationContext as a Java EE RAR file

7.16. The BeanFactory

7.16.1. BeanFactory or ApplicationContext?
7.16.2. Glue code and the evil singleton

8. Resources
8.1. Introduction
8.2. The Resource interface
8.3. Built-in Resource implementations
8.3.1. UrlResource
8.3.2. ClassPathResource
8.3.3. FileSystemResource
8.3.4. ServletContextResource
8.3.5. InputStreamResource
8.3.6. ByteArrayResource

8.4. The ResourceLoader

25/08/2016 12:10

Spring Framework Reference Documentation

7 de 1194

8.5. The ResourceLoaderAware interface

8.6. Resources as dependencies
8.7. Application contexts and Resource paths
8.7.1. Constructing application contexts
Constructing ClassPathXmlApplicationContext instances shortcuts
8.7.2. Wildcards in application context constructor resource paths
Ant-style Patterns
The Classpath*: portability classpath*: prefix
Other notes relating to wildcards
8.7.3. FileSystemResource caveats

9. Validation, Data Binding, and Type Conversion

9.1. Introduction
9.2. Validation using Springs Validator interface
9.3. Resolving codes to error messages
9.4. Bean manipulation and the BeanWrapper
9.4.1. Setting and getting basic and nested properties
9.4.2. Built-in PropertyEditor implementations
Registering additional custom PropertyEditors

9.5. Spring Type Conversion

9.5.1. Converter SPI
9.5.2. ConverterFactory
9.5.3. GenericConverter
ConditionalGenericConverter
9.5.4. ConversionService API
9.5.5. Configuring a ConversionService
9.5.6. Using a ConversionService programmatically

9.6. Spring Field Formatting

9.6.1. Formatter SPI
9.6.2. Annotation-driven Formatting
Format Annotation API
9.6.3. FormatterRegistry SPI
9.6.4. FormatterRegistrar SPI
9.6.5. Configuring Formatting in Spring MVC

9.7. Configuring a global date & time format

9.8. Spring Validation
9.8.1. Overview of the JSR-303 Bean Validation API
9.8.2. Configuring a Bean Validation Provider
Injecting a Validator
Configuring Custom Constraints
Spring-driven Method Validation

25/08/2016 12:10

Spring Framework Reference Documentation

8 de 1194

9.8.3. Configuring a DataBinder

9.8.4. Spring MVC 3 Validation

10. Spring Expression Language (SpEL)

10.1. Introduction
10.2. Feature Overview
10.3. Expression Evaluation using Springs Expression
Interface
10.3.1. The EvaluationContext interface
Type Conversion
10.3.2. Parser configuration
10.3.3. SpEL compilation
Compiler configuration
Compiler limitations

10.4. Expression support for defining bean definitions

10.4.1. XML based configuration
10.4.2. Annotation-based configuration

10.5. Language Reference

10.5.1. Literal expressions
10.5.2. Properties, Arrays, Lists, Maps, Indexers
10.5.3. Inline lists
10.5.4. Inline Maps
10.5.5. Array construction
10.5.6. Methods
10.5.7. Operators
Relational operators
Logical operators
Mathematical operators
10.5.8. Assignment
10.5.9. Types
10.5.10. Constructors
10.5.11. Variables
The #this and #root variables
10.5.12. Functions
10.5.13. Bean references
10.5.14. Ternary Operator (If-Then-Else)
10.5.15. The Elvis Operator
10.5.16. Safe Navigation operator
10.5.17. Collection Selection
10.5.18. Collection Projection
10.5.19. Expression templating

10.6. Classes used in the examples

11. Aspect Oriented Programming with Spring

25/08/2016 12:10

Spring Framework Reference Documentation

9 de 1194

11.1.1. AOP concepts

11.1.2. Spring AOP capabilities and goals
11.1.3. AOP Proxies

11.2. @AspectJ support

11.2.1. Enabling @AspectJ Support
Enabling @AspectJ Support with Java configuration
Enabling @AspectJ Support with XML configuration
11.2.2. Declaring an aspect
11.2.3. Declaring a pointcut
Supported Pointcut Designators
Combining pointcut expressions
Sharing common pointcut definitions
Examples
Writing good pointcuts
11.2.4. Declaring advice
Before advice
After returning advice
After throwing advice
After (finally) advice
Around advice
Advice parameters
Advice ordering
11.2.5. Introductions
11.2.6. Aspect instantiation models
11.2.7. Example

11.3. Schema-based AOP support

11.3.1. Declaring an aspect
11.3.2. Declaring a pointcut
11.3.3. Declaring advice
Before advice
After returning advice
After throwing advice
After (finally) advice
Around advice
Advice parameters
Advice ordering
11.3.4. Introductions
11.3.5. Aspect instantiation models
11.3.6. Advisors
11.3.7. Example

11.4. Choosing which AOP declaration style to use

11.4.1. Spring AOP or full AspectJ?
11.4.2. @AspectJ or XML for Spring AOP?

11.5. Mixing aspect types

11.6. Proxying mechanisms
11.6.1. Understanding AOP proxies

25/08/2016 12:10

Spring Framework Reference Documentation

10 de 1194

11.7. Programmatic creation of @AspectJ Proxies

11.8. Using AspectJ with Spring applications
11.8.1. Using AspectJ to dependency inject domain objects with Spring
Unit testing @Configurable objects
Working with multiple application contexts
11.8.2. Other Spring aspects for AspectJ
11.8.3. Configuring AspectJ aspects using Spring IoC
11.8.4. Load-time weaving with AspectJ in the Spring Framework
A first example
Aspects
'META-INF/aop.xml'
Required libraries (JARS)
Spring configuration
Environment-specific configuration

11.9. Further Resources

12. Spring AOP APIs

12.1. Introduction
12.2. Pointcut API in Spring
12.2.1. Concepts
12.2.2. Operations on pointcuts
12.2.3. AspectJ expression pointcuts
12.2.4. Convenience pointcut implementations
Static pointcuts
Dynamic pointcuts
12.2.5. Pointcut superclasses
12.2.6. Custom pointcuts

12.3. Advice API in Spring

12.3.1. Advice lifecycles
12.3.2. Advice types in Spring
Interception around advice
Before advice
Throws advice
After Returning advice
Introduction advice

12.4. Advisor API in Spring

12.5. Using the ProxyFactoryBean to create AOP proxies
12.5.1. Basics
12.5.2. JavaBean properties
12.5.3. JDK- and CGLIB-based proxies
12.5.4. Proxying interfaces
12.5.5. Proxying classes
12.5.6. Using 'global' advisors

12.6. Concise proxy definitions

25/08/2016 12:10

Spring Framework Reference Documentation

11 de 1194

12.7. Creating AOP proxies programmatically with the

ProxyFactory
12.8. Manipulating advised objects
12.9. Using the "auto-proxy" facility
12.9.1. Autoproxy bean definitions
BeanNameAutoProxyCreator
DefaultAdvisorAutoProxyCreator
AbstractAdvisorAutoProxyCreator
12.9.2. Using metadata-driven auto-proxying

12.10. Using TargetSources

12.10.1. Hot swappable target sources
12.10.2. Pooling target sources
12.10.3. Prototype target sources
12.10.4. ThreadLocal target sources

12.11. Defining new Advice types

12.12. Further resources

IV. Testing
13. Introduction to Spring Testing
14. Unit Testing
14.1. Mock Objects
14.1.1. Environment
14.1.2. JNDI
14.1.3. Servlet API
14.1.4. Portlet API

14.2. Unit Testing support Classes

14.2.1. General testing utilities
14.2.2. Spring MVC

15. Integration Testing

15.1. Overview
15.2. Goals of Integration Testing
15.2.1. Context management and caching
15.2.2. Dependency Injection of test fixtures
15.2.3. Transaction management
15.2.4. Support classes for integration testing

15.3. JDBC Testing Support

25/08/2016 12:10

Spring Framework Reference Documentation

12 de 1194

15.4.1. Spring Testing Annotations

@BootstrapWith
@ContextConfiguration
@WebAppConfiguration
@ContextHierarchy
@ActiveProfiles
@TestPropertySource
@DirtiesContext
@TestExecutionListeners
@Commit
@Rollback
@BeforeTransaction
@AfterTransaction
@Sql
@SqlConfig
@SqlGroup
15.4.2. Standard Annotation Support
15.4.3. Spring JUnit 4 Testing Annotations
@IfProfileValue
@ProfileValueSourceConfiguration
@Timed
@Repeat
15.4.4. Meta-Annotation Support for Testing

15.5. Spring TestContext Framework

15.5.1. Key abstractions
TestContext
TestContextManager
TestExecutionListener
Context Loaders
15.5.2. Bootstrapping the TestContext framework
15.5.3. TestExecutionListener configuration
Registering custom TestExecutionListeners
Automatic discovery of default TestExecutionListeners
Ordering TestExecutionListeners
Merging TestExecutionListeners
15.5.4. Context management
Context configuration with XML resources
Context configuration with Groovy scripts
Context configuration with annotated classes
Mixing XML, Groovy scripts, and annotated classes
Context configuration with context initializers
Context configuration inheritance
Context configuration with environment profiles
Context configuration with test property sources
Loading a WebApplicationContext
Context caching
Context hierarchies
15.5.5. Dependency injection of test fixtures
15.5.6. Testing request and session scoped beans

25/08/2016 12:10

Spring Framework Reference Documentation

13 de 1194

Test-managed transactions
Enabling and disabling transactions
Transaction rollback and commit behavior
Programmatic transaction management
Executing code outside of a transaction
Configuring a transaction manager
Demonstration of all transaction-related annotations
15.5.8. Executing SQL scripts
Executing SQL scripts programmatically
Executing SQL scripts declaratively with @Sql
15.5.9. TestContext Framework support classes
Spring JUnit 4 Runner
Spring JUnit 4 Rules
JUnit 4 support classes
TestNG support classes

15.6. Spring MVC Test Framework

15.6.1. Server-Side Tests
Static Imports
Setup Options
Performing Requests
Defining Expectations
Filter Registrations
Differences between Out-of-Container and End-to-End Integration
Tests
Further Server-Side Test Examples
15.6.2. HtmlUnit Integration
Why HtmlUnit Integration?
MockMvc and HtmlUnit
MockMvc and WebDriver
MockMvc and Geb
15.6.3. Client-Side REST Tests
Static Imports
Further Examples of Client-side REST Tests

15.7. PetClinic Example

16. Further Resources

V. Data Access
17. Transaction Management
17.1. Introduction to Spring Framework transaction
management
17.2. Advantages of the Spring Frameworks transaction
support model

25/08/2016 12:10

Spring Framework Reference Documentation

14 de 1194

17.2.2. Local transactions

17.2.3. Spring Frameworks consistent programming model

17.3. Understanding the Spring Framework transaction

abstraction
17.4. Synchronizing resources with transactions
17.4.1. High-level synchronization approach
17.4.2. Low-level synchronization approach
17.4.3. TransactionAwareDataSourceProxy

17.5. Declarative transaction management

17.5.1. Understanding the Spring Frameworks declarative transaction
implementation
17.5.2. Example of declarative transaction implementation
17.5.3. Rolling back a declarative transaction
17.5.4. Configuring different transactional semantics for different beans
17.5.5. <tx:advice/> settings
17.5.6. Using @Transactional
@Transactional settings
Multiple Transaction Managers with @Transactional
Custom shortcut annotations
17.5.7. Transaction propagation
Required
RequiresNew
Nested
17.5.8. Advising transactional operations
17.5.9. Using @Transactional with AspectJ

17.6. Programmatic transaction management

17.6.1. Using the TransactionTemplate
Specifying transaction settings
17.6.2. Using the PlatformTransactionManager

17.7. Choosing between programmatic and declarative

transaction management
17.8. Transaction bound event
17.9. Application server-specific integration
17.9.1. IBM WebSphere
17.9.2. Oracle WebLogic Server

17.10. Solutions to common problems

17.10.1. Use of the wrong transaction manager for a specific
DataSource

17.11. Further Resources

18. DAO support

18.1. Introduction

25/08/2016 12:10

Spring Framework Reference Documentation

15 de 1194

18.2. Consistent exception hierarchy

18.3. Annotations used for configuring DAO or Repository
classes

19. Data access with JDBC

19.1. Introduction to Spring Framework JDBC
19.1.1. Choosing an approach for JDBC database access
19.1.2. Package hierarchy

19.2. Using the JDBC core classes to control basic JDBC

processing and error handling
19.2.1. JdbcTemplate
Examples of JdbcTemplate class usage
JdbcTemplate best practices
19.2.2. NamedParameterJdbcTemplate
19.2.3. SQLExceptionTranslator
19.2.4. Executing statements
19.2.5. Running queries
19.2.6. Updating the database
19.2.7. Retrieving auto-generated keys

19.3. Controlling database connections

19.3.1. DataSource
19.3.2. DataSourceUtils
19.3.3. SmartDataSource
19.3.4. AbstractDataSource
19.3.5. SingleConnectionDataSource
19.3.6. DriverManagerDataSource
19.3.7. TransactionAwareDataSourceProxy
19.3.8. DataSourceTransactionManager
19.3.9. NativeJdbcExtractor

19.4. JDBC batch operations

19.4.1. Basic batch operations with the JdbcTemplate
19.4.2. Batch operations with a List of objects
19.4.3. Batch operations with multiple batches

19.5. Simplifying JDBC operations with the SimpleJdbc

classes
19.5.1. Inserting data using SimpleJdbcInsert
19.5.2. Retrieving auto-generated keys using SimpleJdbcInsert
19.5.3. Specifying columns for a SimpleJdbcInsert
19.5.4. Using SqlParameterSource to provide parameter values
19.5.5. Calling a stored procedure with SimpleJdbcCall
19.5.6. Explicitly declaring parameters to use for a SimpleJdbcCall
19.5.7. How to define SqlParameters
19.5.8. Calling a stored function using SimpleJdbcCall
19.5.9. Returning ResultSet/REF Cursor from a SimpleJdbcCall

25/08/2016 12:10

Spring Framework Reference Documentation

16 de 1194

19.6. Modeling JDBC operations as Java objects

19.6.1. SqlQuery
19.6.2. MappingSqlQuery
19.6.3. SqlUpdate
19.6.4. StoredProcedure

19.7. Common problems with parameter and data value

handling
19.7.1. Providing SQL type information for parameters
19.7.2. Handling BLOB and CLOB objects
19.7.3. Passing in lists of values for IN clause
19.7.4. Handling complex types for stored procedure calls

19.8. Embedded database support

19.8.1. Why use an embedded database?
19.8.2. Creating an embedded database using Spring XML
19.8.3. Creating an embedded database programmatically
19.8.4. Selecting the embedded database type
Using HSQL
Using H2
Using Derby
19.8.5. Testing data access logic with an embedded database
19.8.6. Generating unique names for embedded databases
19.8.7. Extending the embedded database support

19.9. Initializing a DataSource

19.9.1. Initializing a database using Spring XML
Initialization of other components that depend on the database

20. Object Relational Mapping (ORM) Data Access

20.1. Introduction to ORM with Spring
20.2. General ORM integration considerations
20.2.1. Resource and transaction management
20.2.2. Exception translation

20.3. Hibernate
20.3.1. SessionFactory setup in a Spring container
20.3.2. Implementing DAOs based on plain Hibernate API
20.3.3. Declarative transaction demarcation
20.3.4. Programmatic transaction demarcation
20.3.5. Transaction management strategies
20.3.6. Comparing container-managed and locally defined resources
20.3.7. Spurious application server warnings with Hibernate

20.4. JDO
20.4.1. PersistenceManagerFactory setup
20.4.2. Implementing DAOs based on the plain JDO API
20.4.3. Transaction management
20.4.4. JdoDialect

25/08/2016 12:10

Spring Framework Reference Documentation

17 de 1194

20.5. JPA
20.5.1. Three options for JPA setup in a Spring environment
LocalEntityManagerFactoryBean
Obtaining an EntityManagerFactory from JNDI
LocalContainerEntityManagerFactoryBean
Dealing with multiple persistence units
20.5.2. Implementing DAOs based on plain JPA
20.5.3. Transaction Management
20.5.4. JpaDialect

21. Marshalling XML using O/X Mappers

21.1. Introduction
21.1.1. Ease of configuration
21.1.2. Consistent Interfaces
21.1.3. Consistent Exception Hierarchy

21.2. Marshaller and Unmarshaller

21.2.1. Marshaller
21.2.2. Unmarshaller
21.2.3. XmlMappingException

21.3. Using Marshaller and Unmarshaller

21.4. XML Schema-based Configuration
21.5. JAXB
21.5.1. Jaxb2Marshaller
XML Schema-based Configuration

21.6. Castor
21.6.1. CastorMarshaller
21.6.2. Mapping
XML Schema-based Configuration

21.7. XMLBeans
21.7.1. XmlBeansMarshaller
XML Schema-based Configuration

21.8. JiBX
21.8.1. JibxMarshaller
XML Schema-based Configuration

21.9. XStream
21.9.1. XStreamMarshaller

VI. The Web

22. Web MVC framework
22.1. Introduction to Spring Web MVC framework
25/08/2016 12:10

Spring Framework Reference Documentation

18 de 1194

22.1.1. Features of Spring Web MVC

22.1.2. Pluggability of other MVC implementations

22.2. The DispatcherServlet

22.2.1. Special Bean Types In the WebApplicationContext
22.2.2. Default DispatcherServlet Configuration
22.2.3. DispatcherServlet Processing Sequence

22.3. Implementing Controllers

22.3.1. Defining a controller with @Controller
22.3.2. Mapping Requests With @RequestMapping
Composed @RequestMapping Variants
@Controller and AOP Proxying
New Support Classes for @RequestMapping methods in Spring
MVC 3.1
URI Template Patterns
URI Template Patterns with Regular Expressions
Path Patterns
Path Pattern Comparison
Path Patterns with Placeholders
Suffix Pattern Matching
Suffix Pattern Matching and RFD
Matrix Variables
Consumable Media Types
Producible Media Types
Request Parameters and Header Values
HTTP HEAD and HTTP OPTIONS
22.3.3. Defining @RequestMapping handler methods
Supported method argument types
Supported method return types
Binding request parameters to method parameters with
@RequestParam
Mapping the request body with the @RequestBody annotation
Mapping the response body with the @ResponseBody annotation
Creating REST Controllers with the @RestController annotation
Using HttpEntity
Using @ModelAttribute on a method
Using @ModelAttribute on a method argument
Using @SessionAttributes to store model attributes in the HTTP
session between requests
Using @SessionAttribute to access pre-existing global session
attributes
Using @RequestAttribute to access request attributes
Working with "application/x-www-form-urlencoded" data
Mapping cookie values with the @CookieValue annotation
Mapping request header attributes with the @RequestHeader
annotation
Method Parameters And Type Conversion
Customizing WebDataBinder initialization
Advising controllers with @ControllerAdvice and
@RestControllerAdvice

25/08/2016 12:10

Spring Framework Reference Documentation

19 de 1194

Jackson Serialization View Support

Jackson JSONP Support
22.3.4. Asynchronous Request Processing
Exception Handling for Async Requests
Intercepting Async Requests
HTTP Streaming
HTTP Streaming With Server-Sent Events
HTTP Streaming Directly To The OutputStream
Configuring Asynchronous Request Processing
22.3.5. Testing Controllers

22.4. Handler mappings

22.4.1. Intercepting requests with a HandlerInterceptor

22.5. Resolving views

22.5.1. Resolving views with the ViewResolver interface
22.5.2. Chaining ViewResolvers
22.5.3. Redirecting to Views
RedirectView
The redirect: prefix
The forward: prefix
22.5.4. ContentNegotiatingViewResolver

22.6. Using flash attributes

22.7. Building URIs
22.7.1. Building URIs to Controllers and methods
22.7.2. Building URIs to Controllers and methods from views

22.8. Using locales

22.8.1. Obtaining Time Zone Information
22.8.2. AcceptHeaderLocaleResolver
22.8.3. CookieLocaleResolver
22.8.4. SessionLocaleResolver
22.8.5. LocaleChangeInterceptor

22.9. Using themes

22.9.1. Overview of themes
22.9.2. Defining themes
22.9.3. Theme resolvers

22.10. Springs multipart (file upload) support

22.10.1. Introduction
22.10.2. Using a MultipartResolver with Commons FileUpload
22.10.3. Using a MultipartResolver with Servlet 3.0
22.10.4. Handling a file upload in a form
22.10.5. Handling a file upload request from programmatic clients

22.11. Handling exceptions

22.11.1. HandlerExceptionResolver
22.11.2. @ExceptionHandler
22.11.3. Handling Standard Spring MVC Exceptions

25/08/2016 12:10

Spring Framework Reference Documentation

20 de 1194

22.11.5. Customizing the Default Servlet Container Error Page

22.12. Web Security

22.13. Convention over configuration support
22.13.1. The Controller ControllerClassNameHandlerMapping
22.13.2. The Model ModelMap (ModelAndView)
22.13.3. The View - RequestToViewNameTranslator

22.14. HTTP caching support

22.14.1. Cache-Control HTTP header
22.14.2. HTTP caching support for static resources
22.14.3. Support for the Cache-Control, ETag and Last-Modified
response headers in Controllers
22.14.4. Shallow ETag support

22.15. Code-based Servlet container initialization

22.16. Configuring Spring MVC
22.16.1. Enabling the MVC Java Config or the MVC XML Namespace
22.16.2. Customizing the Provided Configuration
22.16.3. Conversion and Formatting
22.16.4. Validation
22.16.5. Interceptors
22.16.6. Content Negotiation
22.16.7. View Controllers
22.16.8. View Resolvers
22.16.9. Serving of Resources
22.16.10. Falling Back On the "Default" Servlet To Serve Resources
22.16.11. Path Matching
22.16.12. Message Converters
22.16.13. Advanced Customizations with MVC Java Config
22.16.14. Advanced Customizations with the MVC Namespace

23. View technologies

23.1. Introduction
23.2. Thymeleaf
23.3. Groovy Markup Templates
23.3.1. Configuration
23.3.2. Example

23.4. Velocity & FreeMarker

23.4.1. Dependencies
23.4.2. Context configuration
23.4.3. Creating templates
23.4.4. Advanced configuration
velocity.properties
FreeMarker
23.4.5. Bind support and form handling

25/08/2016 12:10

Spring Framework Reference Documentation

21 de 1194

Simple binding
Form input generation macros
HTML escaping and XHTML compliance

23.5. JSP & JSTL

23.5.1. View resolvers
23.5.2. 'Plain-old' JSPs versus JSTL
23.5.3. Additional tags facilitating development
23.5.4. Using Springs form tag library
Configuration
The form tag
The input tag
The checkbox tag
The checkboxes tag
The radiobutton tag
The radiobuttons tag
The password tag
The select tag
The option tag
The options tag
The textarea tag
The hidden tag
The errors tag
HTTP Method Conversion
HTML5 Tags

23.6. Script templates

23.6.1. Dependencies
23.6.2. How to integrate script based templating

23.7. XML Marshalling View

23.8. Tiles
23.8.1. Dependencies
23.8.2. How to integrate Tiles
UrlBasedViewResolver
ResourceBundleViewResolver
SimpleSpringPreparerFactory and SpringBeanPreparerFactory

23.9. XSLT
23.9.1. My First Words
Bean definitions
Standard MVC controller code
Document transformation

23.10. Document views (PDF/Excel)

23.10.1. Introduction
23.10.2. Configuration and setup
Document view definitions
Controller code
Subclassing for Excel views
Subclassing for PDF views

25/08/2016 12:10

Spring Framework Reference Documentation

22 de 1194

23.11. JasperReports
23.11.1. Dependencies
23.11.2. Configuration
Configuring the ViewResolver
Configuring the Views
About Report Files
Using JasperReportsMultiFormatView
23.11.3. Populating the ModelAndView
23.11.4. Working with Sub-Reports
Configuring Sub-Report Files
Configuring Sub-Report Data Sources
23.11.5. Configuring Exporter Parameters

23.12. Feed Views

23.13. JSON Mapping View
23.14. XML Mapping View

24. Integrating with other web frameworks

24.1. Introduction
24.2. Common configuration
24.3. JavaServer Faces 1.2
24.3.1. SpringBeanFacesELResolver (JSF 1.2+)
24.3.2. FacesContextUtils

24.4. Apache Struts 2.x

24.5. Tapestry 5.x
24.6. Further Resources

25. Portlet MVC Framework

25.1. Introduction
25.1.1. Controllers - The C in MVC
25.1.2. Views - The V in MVC
25.1.3. Web-scoped beans

25.2. The DispatcherPortlet

25.3. The ViewRendererServlet
25.4. Controllers
25.4.1. AbstractController and PortletContentGenerator
25.4.2. Other simple controllers
25.4.3. Command Controllers
25.4.4. PortletWrappingController

25.5. Handler mappings

25/08/2016 12:10

Spring Framework Reference Documentation

23 de 1194

25.5.2. ParameterHandlerMapping
25.5.3. PortletModeParameterHandlerMapping
25.5.4. Adding HandlerInterceptors
25.5.5. HandlerInterceptorAdapter
25.5.6. ParameterMappingInterceptor

25.6. Views and resolving them

25.7. Multipart (file upload) support
25.7.1. Using the PortletMultipartResolver
25.7.2. Handling a file upload in a form

25.8. Handling exceptions

25.9. Annotation-based controller configuration
25.9.1. Setting up the dispatcher for annotation support
25.9.2. Defining a controller with @Controller
25.9.3. Mapping requests with @RequestMapping
25.9.4. Supported handler method arguments
25.9.5. Binding request parameters to method parameters with
@RequestParam
25.9.6. Providing a link to data from the model with @ModelAttribute
25.9.7. Specifying attributes to store in a Session with
@SessionAttributes
25.9.8. Customizing WebDataBinder initialization
Customizing data binding with @InitBinder
Configuring a custom WebBindingInitializer

25.10. Portlet application deployment

26. WebSocket Support

26.1. Introduction
26.1.1. WebSocket Fallback Options
26.1.2. A Messaging Architecture
26.1.3. Sub-Protocol Support in WebSocket
26.1.4. Should I Use WebSocket?

26.2. WebSocket API

26.2.1. Create and Configure a WebSocketHandler
26.2.2. Customizing the WebSocket Handshake
26.2.3. WebSocketHandler Decoration
26.2.4. Deployment Considerations
26.2.5. Configuring the WebSocket Engine
26.2.6. Configuring allowed origins

26.3. SockJS Fallback Options

26.3.1. Overview of SockJS
26.3.2. Enable SockJS
26.3.3. HTTP Streaming in IE 8, 9: Ajax/XHR vs IFrame
26.3.4. Heartbeat Messages
26.3.5. Servlet 3 Async Requests

25/08/2016 12:10

Spring Framework Reference Documentation

24 de 1194

26.3.7. SockJS Client

26.4. STOMP Over WebSocket Messaging Architecture

26.4.1. Overview of STOMP
26.4.2. Enable STOMP over WebSocket
26.4.3. Flow of Messages
26.4.4. Annotation Message Handling
26.4.5. Sending Messages
26.4.6. Simple Broker
26.4.7. Full-Featured Broker
26.4.8. Connections To Full-Featured Broker
26.4.9. Using Dot as Separator in @MessageMapping Destinations
26.4.10. Authentication
26.4.11. User Destinations
26.4.12. Listening To ApplicationContext Events and Intercepting
Messages
26.4.13. STOMP Client
26.4.14. WebSocket Scope
26.4.15. Configuration and Performance
26.4.16. Runtime Monitoring
26.4.17. Testing Annotated Controller Methods

27. CORS Support

27.1. Introduction
27.2. Controller method CORS configuration
27.3. Global CORS configuration
27.3.1. JavaConfig
27.3.2. XML namespace

27.4. Advanced Customization

27.5. Filter based CORS support

VII. Integration
28. Remoting and web services using Spring
28.1. Introduction
28.2. Exposing services using RMI
28.2.1. Exporting the service using the RmiServiceExporter
28.2.2. Linking in the service at the client

28.3. Using Hessian or Burlap to remotely call services via

HTTP
28.3.1. Wiring up the DispatcherServlet for Hessian and co.
28.3.2. Exposing your beans by using the HessianServiceExporter

25/08/2016 12:10

Spring Framework Reference Documentation

25 de 1194

28.3.4. Using Burlap

28.3.5. Applying HTTP basic authentication to a service exposed
through Hessian or Burlap

28.4. Exposing services using HTTP invokers

28.4.1. Exposing the service object
28.4.2. Linking in the service at the client

28.5. Web services

28.5.1. Exposing servlet-based web services using JAX-WS
28.5.2. Exporting standalone web services using JAX-WS
28.5.3. Exporting web services using the JAX-WS RIs Spring support
28.5.4. Accessing web services using JAX-WS

28.6. JMS
28.6.1. Server-side configuration
28.6.2. Client-side configuration

28.7. AMQP
28.8. Auto-detection is not implemented for remote
interfaces
28.9. Considerations when choosing a technology
28.10. Accessing RESTful services on the Client
28.10.1. RestTemplate
Working with the URI
Dealing with request and response headers
Jackson JSON Views support
28.10.2. HTTP Message Conversion
StringHttpMessageConverter
FormHttpMessageConverter
ByteArrayHttpMessageConverter
MarshallingHttpMessageConverter
MappingJackson2HttpMessageConverter
MappingJackson2XmlHttpMessageConverter
SourceHttpMessageConverter
BufferedImageHttpMessageConverter
28.10.3. Async RestTemplate

29. Enterprise JavaBeans (EJB) integration

29.1. Introduction
29.2. Accessing EJBs
29.2.1. Concepts
29.2.2. Accessing local SLSBs
29.2.3. Accessing remote SLSBs
29.2.4. Accessing EJB 2.x SLSBs versus EJB 3 SLSBs

29.3. Using Springs EJB implementation support classes

25/08/2016 12:10

Spring Framework Reference Documentation

26 de 1194

30. JMS (Java Message Service)

30.1. Introduction
30.2. Using Spring JMS
30.2.1. JmsTemplate
30.2.2. Connections
Caching Messaging Resources
SingleConnectionFactory
CachingConnectionFactory
30.2.3. Destination Management
30.2.4. Message Listener Containers
SimpleMessageListenerContainer
DefaultMessageListenerContainer
30.2.5. Transaction management

30.3. Sending a Message

30.3.1. Using Message Converters
30.3.2. SessionCallback and ProducerCallback

30.4. Receiving a message

30.4.1. Synchronous Reception
30.4.2. Asynchronous Reception - Message-Driven POJOs
30.4.3. the SessionAwareMessageListener interface
30.4.4. the MessageListenerAdapter
30.4.5. Processing messages within transactions

30.5. Support for JCA Message Endpoints

30.6. Annotation-driven listener endpoints
30.6.1. Enable listener endpoint annotations
30.6.2. Programmatic endpoints registration
30.6.3. Annotated endpoint method signature
30.6.4. Response management

30.7. JMS Namespace Support

31. JMX
31.1. Introduction
31.2. Exporting your beans to JMX
31.2.1. Creating an MBeanServer
31.2.2. Reusing an existing MBeanServer
31.2.3. Lazy-initialized MBeans
31.2.4. Automatic registration of MBeans
31.2.5. Controlling the registration behavior

31.3. Controlling the management interface of your beans

31.3.1. the MBeanInfoAssembler Interface
31.3.2. Using Source-Level Metadata (Java annotations)
31.3.3. Source-Level Metadata Types

25/08/2016 12:10

Spring Framework Reference Documentation

27 de 1194

31.3.5. Defining management interfaces using Java interfaces

31.3.6. Using MethodNameBasedMBeanInfoAssembler

31.4. Controlling the ObjectNames for your beans

31.4.1. Reading ObjectNames from Properties
31.4.2. Using the MetadataNamingStrategy
31.4.3. Configuring annotation based MBean export

31.5. JSR-160 Connectors

31.5.1. Server-side Connectors
31.5.2. Client-side Connectors
31.5.3. JMX over Burlap/Hessian/SOAP

31.6. Accessing MBeans via Proxies

31.7. Notifications
31.7.1. Registering Listeners for Notifications
31.7.2. Publishing Notifications

31.8. Further Resources

32. JCA CCI

32.1. Introduction
32.2. Configuring CCI
32.2.1. Connector configuration
32.2.2. ConnectionFactory configuration in Spring
32.2.3. Configuring CCI connections
32.2.4. Using a single CCI connection

32.3. Using Springs CCI access support

32.3.1. Record conversion
32.3.2. the CciTemplate
32.3.3. DAO support
32.3.4. Automatic output record generation
32.3.5. Summary
32.3.6. Using a CCI Connection and Interaction directly
32.3.7. Example for CciTemplate usage

32.4. Modeling CCI access as operation objects

32.4.1. MappingRecordOperation
32.4.2. MappingCommAreaOperation
32.4.3. Automatic output record generation
32.4.4. Summary
32.4.5. Example for MappingRecordOperation usage
32.4.6. Example for MappingCommAreaOperation usage

32.5. Transactions

33. Email
33.1. Introduction
25/08/2016 12:10

Spring Framework Reference Documentation

28 de 1194

33.2. Usage
33.2.1. Basic MailSender and SimpleMailMessage usage
33.2.2. Using the JavaMailSender and the MimeMessagePreparator

33.3. Using the JavaMail MimeMessageHelper

33.3.1. Sending attachments and inline resources
Attachments
Inline resources
33.3.2. Creating email content using a templating library
A Velocity-based example

34. Task Execution and Scheduling

34.1. Introduction
34.2. The Spring TaskExecutor abstraction
34.2.1. TaskExecutor types
34.2.2. Using a TaskExecutor

34.3. The Spring TaskScheduler abstraction

34.3.1. the Trigger interface
34.3.2. Trigger implementations
34.3.3. TaskScheduler implementations

34.4. Annotation Support for Scheduling and

Asynchronous Execution
34.4.1. Enable scheduling annotations
34.4.2. The @Scheduled Annotation
34.4.3. The @Async Annotation
34.4.4. Executor qualification with @Async
34.4.5. Exception management with @Async

34.5. The Task Namespace

34.5.1. The 'scheduler' element
34.5.2. The 'executor' element
34.5.3. The 'scheduled-tasks' element

34.6. Using the Quartz Scheduler

34.6.1. Using the JobDetailFactoryBean
34.6.2. Using the MethodInvokingJobDetailFactoryBean
34.6.3. Wiring up jobs using triggers and the SchedulerFactoryBean

35. Dynamic language support

35.1. Introduction
35.2. A first example
35.3. Defining beans that are backed by dynamic
languages
35.3.1. Common concepts

25/08/2016 12:10

Spring Framework Reference Documentation

29 de 1194

Refreshable beans
Inline dynamic language source files
Understanding Constructor Injection in the context of dynamiclanguage-backed beans
35.3.2. JRuby beans
35.3.3. Groovy beans
Customizing Groovy objects via a callback
35.3.4. BeanShell beans

35.4. Scenarios
35.4.1. Scripted Spring MVC Controllers
35.4.2. Scripted Validators

35.5. Bits and bobs

35.5.1. AOP - advising scripted beans
35.5.2. Scoping

35.6. Further Resources

36. Cache Abstraction

36.1. Introduction
36.2. Understanding the cache abstraction
36.3. Declarative annotation-based caching
36.3.1. @Cacheable annotation
Default Key Generation
Custom Key Generation Declaration
Default Cache Resolution
Custom cache resolution
Synchronized caching
Conditional caching
Available caching SpEL evaluation context
36.3.2. @CachePut annotation
36.3.3. @CacheEvict annotation
36.3.4. @Caching annotation
36.3.5. @CacheConfig annotation
36.3.6. Enable caching annotations
36.3.7. Using custom annotations

36.4. JCache (JSR-107) annotations

36.4.1. Features summary
36.4.2. Enabling JSR-107 support

36.5. Declarative XML-based caching

36.6. Configuring the cache storage
36.6.1. JDK ConcurrentMap-based Cache
36.6.2. EhCache-based Cache
36.6.3. Caffeine Cache
36.6.4. Guava Cache

25/08/2016 12:10

Spring Framework Reference Documentation

30 de 1194

36.6.6. JSR-107 Cache

36.6.7. Dealing with caches without a backing store

36.7. Plugging-in different back-end caches

36.8. How can I set the TTL/TTI/Eviction policy/XXX
feature?

VIII. Appendices
37. Migrating to Spring Framework 4.x
38. Spring Annotation Programming Model
39. Classic Spring Usage
39.1. Classic ORM usage
39.1.1. Hibernate
The HibernateTemplate
Implementing Spring-based DAOs without callbacks

39.2. JMS Usage

39.2.1. JmsTemplate
39.2.2. Asynchronous Message Reception
39.2.3. Connections
39.2.4. Transaction Management

40. Classic Spring AOP Usage

40.1. Pointcut API in Spring
40.1.1. Concepts
40.1.2. Operations on pointcuts
40.1.3. AspectJ expression pointcuts
40.1.4. Convenience pointcut implementations
Static pointcuts
Dynamic pointcuts
40.1.5. Pointcut superclasses
40.1.6. Custom pointcuts

40.2. Advice API in Spring

40.2.1. Advice lifecycles
40.2.2. Advice types in Spring
Interception around advice
Before advice
Throws advice
After Returning advice
Introduction advice

40.3. Advisor API in Spring

25/08/2016 12:10

Spring Framework Reference Documentation

31 de 1194

40.4. Using the ProxyFactoryBean to create AOP proxies

40.4.1. Basics
40.4.2. JavaBean properties
40.4.3. JDK- and CGLIB-based proxies
40.4.4. Proxying interfaces
40.4.5. Proxying classes
40.4.6. Using 'global' advisors

40.5. Concise proxy definitions

40.6. Creating AOP proxies programmatically with the
ProxyFactory
40.7. Manipulating advised objects
40.8. Using the "autoproxy" facility
40.8.1. Autoproxy bean definitions
BeanNameAutoProxyCreator
DefaultAdvisorAutoProxyCreator
AbstractAdvisorAutoProxyCreator
40.8.2. Using metadata-driven auto-proxying

40.9. Using TargetSources

40.9.1. Hot swappable target sources
40.9.2. Pooling target sources
40.9.3. Prototype target sources
40.9.4. ThreadLocal target sources

40.10. Defining new Advice types

40.11. Further resources

41. XML Schema-based configuration

41.1. Introduction
41.2. XML Schema-based configuration
41.2.1. Referencing the schemas
41.2.2. the util schema
<util:constant/>
<util:property-path/>
<util:properties/>
<util:list/>
<util:map/>
<util:set/>
41.2.3. the jee schema
<jee:jndi-lookup/> (simple)
<jee:jndi-lookup/> (with single JNDI environment setting)
<jee:jndi-lookup/> (with multiple JNDI environment settings)
<jee:jndi-lookup/> (complex)
<jee:local-slsb/> (simple)
<jee:local-slsb/> (complex)

25/08/2016 12:10

Spring Framework Reference Documentation

32 de 1194

<jee:remote-slsb/>
41.2.4. the lang schema
41.2.5. the jms schema
41.2.6. the tx (transaction) schema
41.2.7. the aop schema
41.2.8. the context schema
<property-placeholder/>
<annotation-config/>
<component-scan/>
<load-time-weaver/>
<spring-configured/>
<mbean-export/>
41.2.9. the tool schema
41.2.10. the jdbc schema
41.2.11. the cache schema
41.2.12. the beans schema

42. Extensible XML authoring

42.1. Introduction
42.2. Authoring the schema
42.3. Coding a NamespaceHandler
42.4. BeanDefinitionParser
42.5. Registering the handler and the schema
42.5.1. 'META-INF/spring.handlers'
42.5.2. 'META-INF/spring.schemas'

42.6. Using a custom extension in your Spring XML

configuration
42.7. Meatier examples
42.7.1. Nesting custom tags within custom tags
42.7.2. Custom attributes on 'normal' elements

42.8. Further Resources

43. spring JSP Tag Library

43.1. Introduction
43.2. The argument tag
43.3. The bind tag
43.4. The escapeBody tag
43.5. The eval tag
43.6. The hasBindErrors tag

25/08/2016 12:10

Spring Framework Reference Documentation

33 de 1194

43.7. The htmlEscape tag

43.8. The message tag
43.9. The nestedPath tag
43.10. The param tag
43.11. The theme tag
43.12. The transform tag
43.13. The url tag

Part I. Overview of Spring Framework

25/08/2016 12:10

Spring Framework Reference Documentation

34 de 1194

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 Hibernate
integration code or the JDBC abstraction layer. The Spring Framework supports
declarative transaction management, remote access to your logic through RMI or web
services, and various options for persisting your data. It offers a full-featured MVC
framework, and enables you to integrate AOP transparently into your software.
Spring is designed to be non-intrusive, meaning that your domain logic code generally
has no dependencies on the framework itself. In your integration layer (such as the data
access layer), some dependencies on the data access technology and the Spring
libraries will exist. However, it should be easy to isolate these dependencies from the rest
of your code base.
This document is a reference guide to Spring Framework features. If you have any
requests, comments, or questions on this document, please post them on the user
mailing list. Questions on the Framework itself should be asked on StackOverflow (see
https://spring.io/questions).

1. Getting Started with Spring

This reference guide provides detailed information about the Spring Framework. It
provides comprehensive documentation for all features, as well as some background
about the underlying concepts (such as "Dependency Injection") that Spring has
embraced.
If you are just getting started with Spring, you may want to begin using the Spring
Framework by creating a Spring Boot based application. Spring Boot provides a quick
(and opinionated) way to create a production-ready Spring based application. It is based
on the Spring Framework, favors convention over configuration, and is designed to get
you up and running as quickly as possible.
You can use start.spring.io to generate a basic project or follow one of the "Getting
Started" guides like the Getting Started Building a RESTful Web Service one. As well as
being easier to digest, these guides are very task focused, and most of them are based
on Spring Boot. They also cover other projects from the Spring portfolio that you might
want to consider when solving a particular problem.

2. Introduction to the Spring Framework

25/08/2016 12:10

Spring Framework Reference Documentation

35 de 1194

The Spring Framework is a Java platform that provides comprehensive infrastructure

support for developing Java applications. Spring handles the infrastructure so you can
focus on your application.
Spring enables you to build applications from "plain old Java objects" (POJOs) and to
apply enterprise services non-invasively to POJOs. This capability applies to the Java SE
programming model and to full and partial Java EE.
Examples of how you, as an application developer, can benefit from the Spring platform:
Make a Java method execute in a database transaction without having to deal with
transaction APIs.
Make a local Java method a remote procedure without having to deal with remote
APIs.
Make a local Java method a management operation without having to deal with JMX
APIs.
Make a local Java method a message handler without having to deal with JMS APIs.

2.1 Dependency Injection and Inversion of Control

A Java applicationa loose term that runs the gamut from constrained, embedded
applications to n-tier, server-side enterprise applicationstypically consists of objects
that collaborate to form the application proper. Thus the objects in an application have
dependencies on each other.
Although the Java platform provides a wealth of application development functionality, it
lacks the means to organize the basic building blocks into a coherent whole, leaving that
task to architects and developers. Although you can use design patterns such as Factory,
Abstract Factory, Builder, Decorator, and Service Locator to compose the various classes
and object instances that make up an application, these patterns are simply that: best
practices given a name, with a description of what the pattern does, where to apply it, the
problems it addresses, and so forth. Patterns are formalized best practices that you must
implement yourself in your application.
The Spring Framework Inversion of Control (IoC) component addresses this concern by
providing a formalized means of composing disparate components into a fully working
application ready for use. The Spring Framework codifies formalized design patterns as
first-class objects that you can integrate into your own application(s). Numerous
organizations and institutions use the Spring Framework in this manner to engineer
robust, maintainable applications.

25/08/2016 12:10

Spring Framework Reference Documentation

36 de 1194

Background
"The question is, what aspect of control are [they] inverting?" Martin Fowler posed
this question about Inversion of Control (IoC) on his site in 2004. Fowler suggested
renaming the principle to make it more self-explanatory and came up with
Dependency Injection.

2.2 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 Programming), Instrumentation, Messaging, and Test, as shown in the following
diagram.
Figure 2.1. Overview of the Spring Framework

The following sections list the available modules for each feature along with their artifact

25/08/2016 12:10

Spring Framework Reference Documentation

37 de 1194

names and the topics they cover. Artifact names correlate to artifact IDs used in
Dependency Management tools.

2.2.1 Core Container

The Core Container consists of the spring-core , spring-beans , spring-context ,
spring-context-support , and spring-expression (Spring Expression Language)
modules.
The spring-core and spring-beans modules provide the fundamental parts of the
framework, including the IoC and Dependency Injection features. The BeanFactory is a
sophisticated implementation of the factory pattern. It removes the need for programmatic
singletons and allows you to decouple the configuration and specification of
dependencies from your actual program logic.
The Context ( spring-context ) module builds on the solid base provided by the Core
and Beans modules: it is a means to access objects in a framework-style manner that is
similar to a JNDI registry. The Context module inherits its features from the Beans module
and adds support for internationalization (using, for example, resource bundles), event
propagation, resource loading, and the transparent creation of contexts by, for example, a
Servlet container. The Context module also supports Java EE features such as EJB,
JMX, and basic remoting. The ApplicationContext interface is the focal point of the
Context module. spring-context-support provides support for integrating common
third-party libraries into a Spring application context for caching (EhCache, Guava,
JCache), mailing (JavaMail), scheduling (CommonJ, Quartz) and template engines
(FreeMarker, JasperReports, Velocity).
The spring-expression module provides a powerful 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 Springs IoC container.
It also supports list projection and selection as well as common list aggregations.

2.2.2 AOP and Instrumentation

The spring-aop module provides an AOP Alliance-compliant aspect-oriented
programming implementation allowing you to define, for example, method interceptors
and pointcuts to cleanly decouple code that implements functionality that should be

25/08/2016 12:10

Spring Framework Reference Documentation

38 de 1194

separated. Using source-level metadata functionality, you can also incorporate behavioral
information into your code, in a manner similar to that of .NET attributes.
The separate spring-aspects module provides integration with AspectJ.
The spring-instrument module provides class instrumentation support and
classloader implementations to be used in certain application servers. The
spring-instrument-tomcat module contains Springs instrumentation agent for
Tomcat.

2.2.3 Messaging
Spring Framework 4 includes a spring-messaging module with key abstractions from
the Spring Integration project such as Message , MessageChannel , MessageHandler ,
and others to serve as a foundation for messaging-based applications. The module also
includes a set of annotations for mapping messages to methods, similar to the Spring
MVC annotation based programming model.

2.2.4 Data Access/Integration

The Data Access/Integration layer consists of the JDBC, ORM, OXM, JMS, and
Transaction modules.
The spring-jdbc module provides a JDBC-abstraction layer that removes the need to
do tedious JDBC coding and parsing of database-vendor specific error codes.
The spring-tx module supports programmatic and declarative transaction
management for classes that implement special interfaces and for all your POJOs (Plain
Old Java Objects).
The spring-orm module provides integration layers for popular object-relational
mapping APIs, including JPA, JDO, and Hibernate. Using the spring-orm module you
can use all of 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 Object/XML
mapping implementations such as JAXB, Castor, XMLBeans, JiBX and XStream.
The spring-jms module (Java Messaging Service) contains features for producing and
consuming messages. Since Spring Framework 4.1, it provides integration with the
spring-messaging module.

25/08/2016 12:10

Spring Framework Reference Documentation

39 de 1194

2.2.5 Web
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
multipart file upload functionality and the initialization of the IoC container using Servlet
listeners and a web-oriented application context. It also contains an HTTP client and the
web-related parts of Springs remoting support.
The spring-webmvc module (also known as the Web-Servlet module) contains Springs
model-view-controller (MVC) and REST Web Services implementation for web
applications. Springs 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.
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.

2.2.6 Test
The spring-test module supports the unit testing and integration testing of Spring
components with JUnit or TestNG. It provides consistent loading of Spring
ApplicationContext s and caching of those contexts. It also provides mock objects that
you can use to test your code in isolation.

2.3 Usage scenarios

The building blocks described previously make Spring a logical choice in many scenarios,
from embedded applications that run on resource-constrained devices to full-fledged
enterprise applications that use Springs transaction management functionality and web
framework integration.
Figure 2.2. Typical full-fledged Spring web application

25/08/2016 12:10

Spring Framework Reference Documentation

40 de 1194

Springs declarative transaction management features make the web application fully
transactional, just as it would be if you used EJB container-managed transactions. All
your custom business logic can be implemented with simple POJOs and managed by
Springs IoC container. Additional services include support for sending email and
validation that is independent of the web layer, which lets you choose where to execute
validation rules. Springs ORM support is integrated with JPA, Hibernate and JDO; for
example, when using Hibernate, you can continue to use your existing mapping files and
standard Hibernate SessionFactory configuration. Form controllers seamlessly
integrate the web-layer with the domain model, removing the need for ActionForms or
other classes that transform HTTP parameters to values for your domain model.
Figure 2.3. Spring middle-tier using a third-party web framework

25/08/2016 12:10

Spring Framework Reference Documentation

41 de 1194

Sometimes circumstances do not allow you to completely switch to a different framework.

The Spring Framework does not force you to use everything within it; it is not an all-ornothing solution. Existing front-ends built with Struts, Tapestry, JSF or other UI
frameworks can be integrated with a Spring-based middle-tier, which allows you to use
Spring transaction features. You simply need to wire up your business logic using an
ApplicationContext and use a WebApplicationContext to integrate your web layer.
Figure 2.4. Remoting usage scenario

25/08/2016 12:10

Spring Framework Reference Documentation

42 de 1194

When you need to access existing code through web services, you can use Springs
Hessian- , Burlap- , Rmi- or JaxRpcProxyFactory classes. Enabling remote access
to existing applications is not difficult.
Figure 2.5. EJBs - Wrapping existing POJOs

25/08/2016 12:10

Spring Framework Reference Documentation

43 de 1194

The Spring Framework also provides an access and abstraction layer for Enterprise
JavaBeans, enabling you to reuse your existing POJOs and wrap them in stateless
session beans for use in scalable, fail-safe web applications that might need declarative
security.

2.3.1 Dependency Management and Naming Conventions

Dependency management and dependency injection are different things. To get those
nice features of Spring into your application (like dependency injection) you need to
assemble all the libraries needed (jar files) and get them onto your classpath at runtime,
and possibly at compile time. These dependencies are not virtual components that are
injected, but physical resources in a file system (typically). The process of dependency
management involves locating those resources, storing them and adding them to
classpaths. Dependencies can be direct (e.g. my application depends on Spring at
runtime), or indirect (e.g. my application depends on commons-dbcp which depends on
commons-pool ). The indirect dependencies are also known as "transitive" and it is those
dependencies that are hardest to identify and manage.
If you are going to use Spring you need to get a copy of the jar libraries that comprise the
pieces of Spring that you need. To make this easier Spring is packaged as a set of
modules that separate the dependencies as much as possible, so for example if you dont
want to write a web application you dont need the spring-web modules. To refer to Spring
library modules in this guide we use a shorthand naming convention spring-* or

25/08/2016 12:10

Spring Framework Reference Documentation

44 de 1194

spring-*.jar, where * represents the short name for the module (e.g.
spring-core , spring-webmvc , spring-jms , etc.). The actual jar file name that you
use is normally the module name concatenated with the version number (e.g. springcore-4.3.2.RELEASE.jar).
Each release of the Spring Framework will publish artifacts to the following places:
Maven Central, which is the default repository that Maven queries, and does not
require any special configuration to use. Many of the common libraries that Spring
depends on also are available from Maven Central and a large section of the Spring
community uses Maven for dependency management, so this is convenient for them.
The names of the jars here are in the form spring-*-<version>.jar and the
Maven groupId is org.springframework .
In a public Maven repository hosted specifically for Spring. In addition to the final GA
releases, this repository also hosts development snapshots and milestones. The jar
file names are in the same form as Maven Central, so this is a useful place to get
development versions of Spring to use with other libraries deployed in Maven Central.
This repository also contains a bundle distribution zip file that contains all Spring jars
bundled together for easy download.
So the first thing you need to decide is how to manage your dependencies: we generally
recommend the use of an automated system like Maven, Gradle or Ivy, but you can also
do it manually by downloading all the jars yourself.
You will find bellow the list of Spring artifacts. For a more complete description of each
modules, see Section 2.2, Modules.

Table 2.1. Spring Framework Artifacts

GroupId

ArtifactId

Description

org.springframework spring-aop

Proxy-based AOP support

org.springframework spring-aspects

AspectJ based aspects

org.springframework spring-beans

Beans support, including Groovy

org.springframework spring-context

Application context runtime, including

scheduling and remoting abstractions

org.springframework spring-contextsupport

Support classes for integrating

common third-party libraries into a
Spring application context

25/08/2016 12:10

Spring Framework Reference Documentation

45 de 1194

GroupId

ArtifactId

org.springframework spring-core

Description
Core utilities, used by many other
Spring modules

org.springframework spring-

Spring Expression Language (SpEL)

expression
org.springframework springinstrument
org.springframework spring-

Instrumentation agent for JVM

bootstrapping
Instrumentation agent for Tomcat

instrumenttomcat
org.springframework spring-jdbc

JDBC support package, including

DataSource setup and JDBC access
support

org.springframework spring-jms

JMS support package, including helper

classes to send and receive JMS
messages

org.springframework springmessaging
org.springframework spring-orm

Support for messaging architectures

and protocols
Object/Relational Mapping, including
JPA and Hibernate support

org.springframework spring-oxm

Object/XML Mapping

org.springframework spring-test

Support for unit testing and integration

testing Spring components

org.springframework spring-tx

Transaction infrastructure, including

DAO support and JCA integration

org.springframework spring-web

Web support packages, including client

and web remoting

org.springframework spring-webmvc

REST Web Services and modelview-controller implementation for web

applications

org.springframework spring-webmvcportlet

MVC implementation to be used in a

Portlet environment

25/08/2016 12:10

Spring Framework Reference Documentation

46 de 1194

GroupId

ArtifactId

org.springframework springwebsocket

Description
WebSocket and SockJS
implementations, including STOMP
support

Spring Dependencies and Depending on Spring

Although Spring provides integration and support for a huge range of enterprise and other
external tools, it intentionally keeps its mandatory dependencies to an absolute minimum:
you shouldnt have to locate and download (even automatically) a large number of jar
libraries in order to use Spring for simple use cases. For basic dependency injection there
is only one mandatory external dependency, and that is for logging (see below for a more
detailed description of logging options).
Next we outline the basic steps needed to configure an application that depends on
Spring, first with Maven and then with Gradle and finally using Ivy. In all cases, if anything
is unclear, refer to the documentation of your dependency management system, or look
at some sample code - Spring itself uses Gradle to manage dependencies when it is
building, and our samples mostly use Gradle or Maven.

Maven Dependency Management

If you are using Maven for dependency management you dont even need to supply the
logging dependency explicitly. For example, to create an application context and use
dependency injection to configure an application, your Maven dependencies will look like
this:
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>4.3.2.RELEASE</version>
<scope>runtime</scope>
</dependency>
</dependencies>

Thats it. Note the scope can be declared as runtime if you dont need to compile against
Spring APIs, which is typically the case for basic dependency injection use cases.

25/08/2016 12:10

Spring Framework Reference Documentation

47 de 1194

repository (e.g. for milestones or developer snapshots), you need to specify the repository
location in your Maven configuration. For full releases:
<repositories>
<repository>
<id>io.spring.repo.maven.release</id>
<url>http://repo.spring.io/release/</url>
<snapshots><enabled>false</enabled></snapshots>
</repository>
</repositories>

For milestones:
<repositories>
<repository>
<id>io.spring.repo.maven.milestone</id>
<url>http://repo.spring.io/milestone/</url>
<snapshots><enabled>false</enabled></snapshots>
</repository>
</repositories>

And for snapshots:

<repositories>
<repository>
<id>io.spring.repo.maven.snapshot</id>
<url>http://repo.spring.io/snapshot/</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>

Maven "Bill Of Materials" Dependency

It is possible to accidentally mix different versions of Spring JARs when using Maven. For
example, you may find that a third-party library, or another Spring project, pulls in a
transitive dependency to an older release. If you forget to explicitly declare a direct
dependency yourself, all sorts of unexpected issues can arise.
To overcome such problems Maven supports the concept of a "bill of materials" (BOM)
dependency. You can import the spring-framework-bom in your
dependencyManagement section to ensure that all spring dependencies (both direct and
transitive) are at the same version.
<dependencyManagement>
<dependencies>

25/08/2016 12:10

Spring Framework Reference Documentation

48 de 1194

<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-framework-bom</artifactId>
<version>4.3.2.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

An added benefit of using the BOM is that you no longer need to specify the <version>
attribute when depending on Spring Framework artifacts:
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
</dependency>
<dependencies>

Gradle Dependency Management

To use the Spring repository with the Gradle build system, include the appropriate URL in
the repositories section:
repositories {
mavenCentral()
// and optionally...
maven { url "http://repo.spring.io/release" }
}

You can change the repositories URL from /release to /milestone or

/snapshot as appropriate. Once a repository has been configured, you can declare
dependencies in the usual Gradle way:
dependencies {
compile("org.springframework:spring-context:4.3.2.RELEASE")
testCompile("org.springframework:spring-test:4.3.2.RELEASE")
}

Ivy Dependency Management

25/08/2016 12:10

Spring Framework Reference Documentation

49 de 1194

If you prefer to use Ivy to manage dependencies then there are similar configuration
options.
To configure Ivy to point to the Spring repository add the following resolver to your
ivysettings.xml :
<resolvers>
<ibiblio name="io.spring.repo.maven.release"
m2compatible="true"
root="http://repo.spring.io/release/"/>
</resolvers>

You can change the root URL from /release/ to /milestone/ or /snapshot/ as
appropriate.
Once configured, you can add dependencies in the usual way. For example (in
ivy.xml ):
<dependency org="org.springframework"
name="spring-core" rev="4.3.2.RELEASE" conf="compile->runtime"/>

Distribution Zip Files

Although using a build system that supports dependency management is the
recommended way to obtain the Spring Framework, it is still possible to download a
distribution zip file.
Distribution zips are published to the Spring Maven Repository (this is just for our
convenience, you dont need Maven or any other build system in order to download
them).
To download a distribution zip open a web browser to http://repo.spring.io/release
/org/springframework/spring and select the appropriate subfolder for the version that you
want. Distribution files end -dist.zip , for example spring-framework-{spring-version}RELEASE-dist.zip. Distributions are also published for milestones and snapshots.

2.3.2 Logging
Logging is a very important dependency for Spring because a) it is the only mandatory
external dependency, b) everyone likes to see some output from the tools they are using,
and c) Spring integrates with lots of other tools all of which have also made a choice of
logging dependency. One of the goals of an application developer is often to have unified

25/08/2016 12:10

Spring Framework Reference Documentation

50 de 1194

components. This is more difficult than it might have been since there are so many
choices of logging framework.
The mandatory logging dependency in Spring is the Jakarta Commons Logging API
(JCL). We compile against JCL and we also make JCL Log objects visible for classes
that extend the Spring Framework. Its important to users that all versions of Spring use
the same logging library: migration is easy because backwards compatibility is preserved
even with applications that extend Spring. The way we do this is to make one of the
modules in Spring depend explicitly on commons-logging (the canonical implementation
of JCL), and then make all the other modules depend on that at compile time. If you are
using Maven for example, and wondering where you picked up the dependency on
commons-logging , then it is from Spring and specifically from the central module called
spring-core .
The nice thing about commons-logging is that you dont need anything else to make
your application work. It has a runtime discovery algorithm that looks for other logging
frameworks in well known places on the classpath and uses one that it thinks is
appropriate (or you can tell it which one if you need to). If nothing else is available you get
pretty nice looking logs just from the JDK (java.util.logging or JUL for short). You should
find that your Spring application works and logs happily to the console out of the box in
most situations, and thats important.

Not Using Commons Logging

Unfortunately, the runtime discovery algorithm in commons-logging , while convenient
for the end-user, is problematic. If we could turn back the clock and start Spring now as a
new project it would use a different logging dependency. The first choice would probably
be the Simple Logging Facade for Java ( SLF4J), which is also used by a lot of other
tools that people use with Spring inside their applications.
There are basically two ways to switch off commons-logging :
1. Exclude the dependency from the spring-core module (as it is the only module
that explicitly depends on commons-logging )
2. Depend on a special commons-logging dependency that replaces the library with
an empty jar (more details can be found in the SLF4J FAQ)
To exclude commons-logging, add the following to your dependencyManagement
section:
<dependencies>
<dependency>

25/08/2016 12:10

Spring Framework Reference Documentation

51 de 1194

<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>4.3.2.RELEASE</version>
<exclusions>
<exclusion>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>

Now this application is probably broken because there is no implementation of the JCL
API on the classpath, so to fix it a new one has to be provided. In the next section we
show you how to provide an alternative implementation of JCL using SLF4J as an
example.

Using SLF4J
SLF4J is a cleaner dependency and more efficient at runtime than commons-logging
because it uses compile-time bindings instead of runtime discovery of the other logging
frameworks it integrates. This also means that you have to be more explicit about what
you want to happen at runtime, and declare it or configure it accordingly. SLF4J provides
bindings to many common logging frameworks, so you can usually choose one that you
already use, and bind to that for configuration and management.
SLF4J provides bindings to many common logging frameworks, including JCL, and it also
does the reverse: bridges between other logging frameworks and itself. So to use SLF4J
with Spring you need to replace the commons-logging dependency with the SLF4J-JCL
bridge. Once you have done that then logging calls from within Spring will be translated
into logging calls to the SLF4J API, so if other libraries in your application use that API,
then you have a single place to configure and manage logging.
A common choice might be to bridge Spring to SLF4J, and then provide explicit binding
from SLF4J to Log4J. You need to supply 4 dependencies (and exclude the existing
commons-logging ): the bridge, the SLF4J API, the binding to Log4J, and the Log4J
implementation itself. In Maven you would do that like this
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>4.3.2.RELEASE</version>
<exclusions>

25/08/2016 12:10

Spring Framework Reference Documentation

52 de 1194

<exclusion>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>jcl-over-slf4j</artifactId>
<version>1.5.8</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>1.5.8</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>1.5.8</version>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.14</version>
</dependency>
</dependencies>

That might seem like a lot of dependencies just to get some logging. Well it is, but it is
optional, and it should behave better than the vanilla commons-logging with respect to
classloader issues, notably if you are in a strict container like an OSGi platform. Allegedly
there is also a performance benefit because the bindings are at compile-time not runtime.
A more common choice amongst SLF4J users, which uses fewer steps and generates
fewer dependencies, is to bind directly to Logback. This removes the extra binding step
because Logback implements SLF4J directly, so you only need to depend on two libraries
not four ( jcl-over-slf4j and logback ). If you do that you might also need to exclude
the slf4j-api dependency from other external dependencies (not Spring), because you
only want one version of that API on the classpath.

Using Log4J
Many people use Log4j as a logging framework for configuration and management
purposes. Its efficient and well-established, and in fact its what we use at runtime when
we build and test Spring. Spring also provides some utilities for configuring and initializing

25/08/2016 12:10

Spring Framework Reference Documentation

53 de 1194

Log4j, so it has an optional compile-time dependency on Log4j in some modules.

To make Log4j work with the default JCL dependency ( commons-logging ) all you need
to do is put Log4j on the classpath, and provide it with a configuration file (
log4j.properties or log4j.xml in the root of the classpath). So for Maven users this
is your dependency declaration:
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>4.3.2.RELEASE</version>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.14</version>
</dependency>
</dependencies>

And heres a sample log4j.properties for logging to the console:

log4j.rootCategory=INFO, stdout
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %t %c{2}:%L - %m%n
log4j.category.org.springframework.beans.factory=DEBUG

Runtime Containers with Native JCL

Many people run their Spring applications in a container that itself provides an
implementation of JCL. IBM Websphere Application Server (WAS) is the archetype. This
often causes problems, and unfortunately there is no silver bullet solution; simply
excluding commons-logging from your application is not enough in most situations.
To be clear about this: the problems reported are usually not with JCL per se, or even
with commons-logging : rather they are to do with binding commons-logging to another
framework (often Log4J). This can fail because commons-logging changed the way
they do the runtime discovery in between the older versions (1.0) found in some
containers and the modern versions that most people use now (1.1). Spring does not use
any unusual parts of the JCL API, so nothing breaks there, but as soon as Spring or your
application tries to do any logging you can find that the bindings to Log4J are not working.
In such cases with WAS the easiest thing to do is to invert the class loader hierarchy (IBM
calls it "parent last") so that the application controls the JCL dependency, not the

25/08/2016 12:10

Spring Framework Reference Documentation

54 de 1194

container. That option isnt always open, but there are plenty of other suggestions in the
public domain for alternative approaches, and your mileage may vary depending on the
exact version and feature set of the container.

Part II. Whats New in Spring Framework

4.x
3. New Features and Enhancements in Spring
Framework 4.0
The Spring Framework was first released in 2004; since then there have been significant
major revisions: Spring 2.0 provided XML namespaces and AspectJ support; Spring 2.5
embraced annotation-driven configuration; Spring 3.0 introduced a strong Java 5+
foundation across the framework codebase, and features such as the Java-based
@Configuration model.
Version 4.0 is the latest major release of the Spring Framework and the first to fully
support Java 8 features. You can still use Spring with older versions of Java, however, the
minimum requirement has now been raised to Java SE 6. We have also taken the
opportunity of a major release to remove many deprecated classes and methods.
A migration guide for upgrading to Spring 4.0 is available on the Spring Framework
GitHub Wiki.

3.1 Improved Getting Started Experience

The new spring.io website provides a whole series of "Getting Started" guides to help you
learn Spring. You can read more about the guides in the Chapter 1, Getting Started with
Spring section in this document. The new website also provides a comprehensive
overview of the many additional projects that are released under the Spring umbrella.
If you are a Maven user you may also be interested in the helpful bill of materials POM
file that is now published with each Spring Framework release.

25/08/2016 12:10

Spring Framework Reference Documentation

55 de 1194

3.2 Removed Deprecated Packages and Methods

All deprecated packages, and many deprecated classes and methods have been
removed with version 4.0. If you are upgrading from a previous release of Spring, you
should ensure that you have fixed any deprecated calls that you were making to outdated
APIs.
For a complete set of changes, check out the API Differences Report.
Note that optional third-party dependencies have been raised to a 2010/2011 minimum
(i.e. Spring 4 generally only supports versions released in late 2010 or later now): notably,
Hibernate 3.6+, EhCache 2.1+, Quartz 1.8+, Groovy 1.8+, and Joda-Time 2.0+. As an
exception to the rule, Spring 4 requires the recent Hibernate Validator 4.3+, and support
for Jackson has been focused on 2.0+ now (with Jackson 1.8/1.9 support retained for the
time being where Spring 3.2 had it; now just in deprecated form).

3.3 Java 8 (as well as 6 and 7)

Spring Framework 4.0 provides support for several Java 8 features. You can make use of
lambda expressions and method references with Springs callback interfaces. There is
first-class support for java.time (JSR-310), and several existing annotations have been
retrofitted as @Repeatable . You can also use Java 8s parameter name discovery
(based on the -parameters compiler flag) as an alternative to compiling your code with
debug information enabled.
Spring remains compatible with older versions of Java and the JDK: concretely, Java SE
6 (specifically, a minimum level equivalent to JDK 6 update 18, as released in January
2010) and above are still fully supported. However, for newly started development
projects based on Spring 4, we recommend the use of Java 7 or 8.

3.4 Java EE 6 and 7

Java EE version 6 or above is now considered the baseline for Spring Framework 4, with
the JPA 2.0 and Servlet 3.0 specifications being of particular relevance. In order to remain
compatible with Google App Engine and older application servers, it is possible to deploy
a Spring 4 application into a Servlet 2.5 environment. However, Servlet 3.0+ is strongly
recommended and a prerequisite in Springs test and mock packages for test setups in
development environments.

25/08/2016 12:10

Spring Framework Reference Documentation

56 de 1194

If you are a WebSphere 7 user, be sure to install the JPA 2.0 feature pack.
On WebLogic 10.3.4 or higher, install the JPA 2.0 patch that comes with it.
This turns both of those server generations into Spring 4 compatible
deployment environments.

On a more forward-looking note, Spring Framework 4.0 supports the Java EE 7 level of
applicable specifications now: in particular, JMS 2.0, JTA 1.2, JPA 2.1, Bean Validation
1.1, and JSR-236 Concurrency Utilities. As usual, this support focuses on individual use
of those specifications, e.g. on Tomcat or in standalone environments. However, it works
equally well when a Spring application is deployed to a Java EE 7 server.
Note that Hibernate 4.3 is a JPA 2.1 provider and therefore only supported as of Spring
Framework 4.0. The same applies to Hibernate Validator 5.0 as a Bean Validation 1.1
provider. Neither of the two are officially supported with Spring Framework 3.2.

3.5 Groovy Bean Definition DSL

Beginning with Spring Framework 4.0, it is possible to define external bean configuration
using a Groovy DSL. This is similar in concept to using XML bean definitions but allows
for a more concise syntax. Using Groovy also allows you to easily embed bean definitions
directly in your bootstrap code. For example:
def reader = new GroovyBeanDefinitionReader(myApplicationContext)
reader.beans {
dataSource(BasicDataSource) {
driverClassName = "org.hsqldb.jdbcDriver"
url = "jdbc:hsqldb:mem:grailsDB"
username = "sa"
password = ""
settings = [mynew:"setting"]
}
sessionFactory(SessionFactory) {
dataSource = dataSource
}
myService(MyService) {
nestedBean = { AnotherBean bean ->
dataSource = dataSource
}
}
}

For more information consult the GroovyBeanDefinitionReader javadocs.

25/08/2016 12:10

Spring Framework Reference Documentation

57 de 1194

3.6 Core Container Improvements

There have been several general improvements to the core container:
Spring now treats generic types as a form of qualifier when injecting Beans. For
example, if you are using a Spring Data Repository you can now easily inject a
specific implementation:
@Autowired Repository<Customer> customerRepository .
If you use Springs meta-annotation support, you can now develop custom
annotations that expose specific attributes from the source annotation.
Beans can now be ordered when they are autowired into lists and arrays. Both the
@Order annotation and Ordered interface are supported.
The @Lazy annotation can now be used on injection points, as well as on @Bean
definitions.
The @Description annotation has been introduced for developers using
Java-based configuration.
A generalized model for conditionally filtering beans has been added via the
@Conditional annotation. This is similar to @Profile support but allows for
user-defined strategies to be developed programmatically.
CGLIB-based proxy classes no longer require a default constructor. Support is
provided via the objenesis library which is repackaged inline and distributed as part of
the Spring Framework. With this strategy, no constructor at all is being invoked for
proxy instances anymore.
There is managed time zone support across the framework now, e.g. on
LocaleContext .

3.7 General Web Improvements

Deployment to Servlet 2.5 servers remains an option, but Spring Framework 4.0 is now
focused primarily on Servlet 3.0+ environments. If you are using the Spring MVC Test
Framework you will need to ensure that a Servlet 3.0 compatible JAR is in your test
classpath.
In addition to the WebSocket support mentioned later, the following general
improvements have been made to Springs Web modules:
You can use the new @RestController annotation with Spring MVC applications,
removing the need to add @ResponseBody to each of your @RequestMapping
methods.
The AsyncRestTemplate class has been added, allowing non-blocking

25/08/2016 12:10

Spring Framework Reference Documentation

58 de 1194

asynchronous support when developing REST clients.

Spring now offers comprehensive timezone support when developing Spring MVC
applications.

3.8 WebSocket, SockJS, and STOMP Messaging

A new spring-websocket module provides comprehensive support for WebSocketbased, two-way communication between client and server in web applications. It is
compatible with JSR-356, the Java WebSocket API, and in addition provides
SockJS-based fallback options (i.e. WebSocket emulation) for use in browsers that dont
yet support the WebSocket protocol (e.g. Internet Explorer < 10).
A new spring-messaging module adds support for STOMP as the WebSocket
sub-protocol to use in applications along with an annotation programming model for
routing and processing STOMP messages from WebSocket clients. As a result an
@Controller can now contain both @RequestMapping and @MessageMapping
methods for handling HTTP requests and messages from WebSocket-connected clients.
The new spring-messaging module also contains key abstractions formerly from the
Spring Integration project such as Message , MessageChannel , MessageHandler , and
others to serve as a foundation for messaging-based applications.
For further details, including a more thorough introduction, see the Chapter 26,
WebSocket Support section.

3.9 Testing Improvements

In addition to pruning of deprecated code within the spring-test module, Spring
Framework 4.0 introduces several new features for use in unit and integration testing.
Almost all annotations in the spring-test module (e.g.,
@ContextConfiguration , @WebAppConfiguration , @ContextHierarchy ,
@ActiveProfiles , etc.) can now be used as meta-annotations to create custom
composed annotations and reduce configuration duplication across a test suite.
Active bean definition profiles can now be resolved programmatically, simply by
implementing a custom ActiveProfilesResolver and registering it via the
resolver attribute of @ActiveProfiles .
A new SocketUtils class has been introduced in the spring-core module which
enables you to scan for free TCP and UDP server ports on localhost. This
functionality is not specific to testing but can prove very useful when writing

25/08/2016 12:10

Spring Framework Reference Documentation

59 de 1194

in-memory SMTP server, FTP server, Servlet container, etc.

As of Spring 4.0, the set of mocks in the org.springframework.mock.web
package is now based on the Servlet 3.0 API. Furthermore, several of the Servlet API
mocks (e.g., MockHttpServletRequest , MockServletContext , etc.) have been
updated with minor enhancements and improved configurability.

4. New Features and Enhancements in Spring

Framework 4.1
4.1 JMS Improvements
Spring 4.1 introduces a much simpler infrastructure to register JMS listener endpoints by
annotating bean methods with @JmsListener . 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 ( @EnableJms ,
JmsListenerContainerFactory ). It is also possible to register listener endpoints
programmatically using JmsListenerConfigurer .
Spring 4.1 also aligns its JMS support to allow you to benefit from the
spring-messaging abstraction introduced in 4.0, that is:
Message listener endpoints can have a more flexible signature and benefit from
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 argument.
A new JmsMessageOperations interface is available and permits JmsTemplate
like operations using the Message abstraction.
Finally, Spring 4.1 provides additional miscellaneous improvements:
Synchronous request-reply operations support in JmsTemplate
Listener priority can be specified per <jms:listener/> element
Recovery options for the message listener container are configurable using a
BackOff implementation
JMS 2.0 shared consumers are supported

4.2 Caching Improvements

25/08/2016 12:10

Spring Framework Reference Documentation

60 de 1194

configuration and infrastructure abstraction; no changes are required to use the standard
annotations.
Spring 4.1 also improves its own caching abstraction significantly:
Caches can be resolved at runtime using a CacheResolver . As a result the value
argument defining the cache name(s) to use is no longer mandatory.
More operation-level customizations: cache resolver, cache manager, key generator
A new @CacheConfig class-level annotation allows common settings to be shared at
the class level without enabling any cache operation.
Better exception handling of cached methods using CacheErrorHandler
Spring 4.1 also has a breaking change in the Cache interface as a new putIfAbsent
method has been added.

4.3 Web Improvements

The existing support for resource handling based on the
ResourceHttpRequestHandler has been expanded with new abstractions
ResourceResolver , ResourceTransformer , and ResourceUrlProvider . A
number of built-in implementations provide support for versioned resource URLs (for
effective HTTP caching), locating gzipped resources, generating an HTML 5
AppCache manifests, and more. See Section 22.16.9, Serving of Resources.
JDK 1.8s java.util.Optional is now supported for @RequestParam ,
@RequestHeader , and @MatrixVariable controller method arguments.
ListenableFuture is supported as a return value alternative to DeferredResult
where an underlying service (or perhaps a call to AsyncRestTemplate ) already
returns ListenableFuture .
@ModelAttribute methods are now invoked in an order that respects interdependencies. See SPR-6299.
Jacksons @JsonView is supported directly on @ResponseBody and
ResponseEntity controller methods for serializing different amounts of detail for the
same POJO (e.g. 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. See the section called Jackson Serialization View Support for details.
JSONP is now supported with Jackson. See the section called Jackson JSONP
Support.
A new lifecycle option is available for intercepting @ResponseBody and
ResponseEntity methods just after the controller method returns and before the
response is written. To take advantage declare an @ControllerAdvice bean that

25/08/2016 12:10

Spring Framework Reference Documentation

61 de 1194

implements ResponseBodyAdvice . The built-in support for @JsonView and JSONP

take advantage of this. See Section 22.4.1, Intercepting requests with a
HandlerInterceptor.
There are three new HttpMessageConverter options:
Gsonlighter footprint than Jackson; has already been in use in Spring Android.
Google Protocol Buffersefficient and effective as an inter-service
communication data protocol within an enterprise but can also be exposed as
JSON and XML for browsers.
Jackson based XML serialization is now supported through the jacksondataformat-xml extension. When using @EnableWebMvc or
<mvc:annotation-driven/> , this is used by default instead of JAXB2 if
jackson-dataformat-xml is in the classpath.
Views such as JSPs can now build links to controllers by referring to controller
mappings by name. A default name is assigned to every @RequestMapping . For
example FooController with method handleFoo is named "FC#handleFoo". The
naming strategy is pluggable. It is also possible to name an @RequestMapping
explicitly through its name attribute. A new mvcUrl function in the Spring JSP tag
library makes this easy to use in JSP pages. See Section 22.7.2, Building URIs to
Controllers and methods from views.
ResponseEntity provides a builder-style API to guide controller methods towards
the preparation of server-side responses, e.g. ResponseEntity.ok() .
RequestEntity is a new type that provides a builder-style API to guide client-side
REST code towards the preparation of HTTP requests.
MVC Java config and XML namespace:
View resolvers can now be configured including support for content negotiation,
see Section 22.16.8, View Resolvers.
View controllers now have built-in support for redirects and for setting the
response status. An application can use this to configure redirect URLs, render
404 responses with a view, send "no content" responses, etc. Some use cases
are listed here.
Path matching customizations are frequently used and now built-in. See
Section 22.16.11, Path Matching.
Groovy markup template support (based on Groovy 2.3). See the
GroovyMarkupConfigurer and respecitve ViewResolver and `View'
implementations.

4.4 WebSocket Messaging Improvements

SockJS (Java) client-side support. See SockJsClient and classes in same

25/08/2016 12:10

Spring Framework Reference Documentation

62 de 1194

package.
New application context events SessionSubscribeEvent and
SessionUnsubscribeEvent published when STOMP clients subscribe and
unsubscribe.
New "websocket" scope. See Section 26.4.14, WebSocket Scope.
@SendToUser can target only a single session and does not require an authenticated
user.
@MessageMapping methods can use dot "." instead of slash "/" as path separator.
See SPR-11660.
STOMP/WebSocket monitoring info collected and logged. See Section 26.4.16,
Runtime Monitoring.
Significantly optimized and improved logging that should remain very readable and
compact even at DEBUG level.
Optimized message creation including support for temporary message mutability and
avoiding automatic message id and timestamp creation. See Javadoc of
MessageHeaderAccessor .
Close STOMP/WebSocket connections that have no activity within 60 seconds after
the WebSocket session is established. See SPR-11884.

4.5 Testing Improvements

Groovy scripts can now be used to configure the ApplicationContext loaded for
integration tests in the TestContext framework.
See the section called Context configuration with Groovy scripts for details.
Test-managed transactions can now be programmatically started and ended within
transactional test methods via the new TestTransaction API.
See the section called Programmatic transaction management for details.
SQL script execution can now be configured declaratively via the new @Sql and
@SqlConfig annotations on a per-class or per-method basis.
See Section 15.5.8, Executing SQL scripts for details.
Test property sources which automatically override system and application property
sources can be configured via the new @TestPropertySource annotation.
See the section called Context configuration with test property sources for
details.
Default TestExecutionListener s can now be automatically discovered.
See the section called Automatic discovery of default TestExecutionListeners
for details.
Custom TestExecutionListener s can now be automatically merged with the
default listeners.

25/08/2016 12:10

Spring Framework Reference Documentation

63 de 1194

See the section called Merging TestExecutionListeners for details.

The documentation for transactional testing support in the TestContext framework
has been improved with more thorough explanations and additional examples.
See Section 15.5.7, Transaction management for details.
Various improvements to MockServletContext , MockHttpServletRequest , and
other Servlet API mocks.
AssertThrows has been refactored to support Throwable instead of Exception .
In Spring MVC Test, JSON responses can be asserted with JSON Assert as an extra
option to using JSONPath much like it has been possible to do for XML with XMLUnit.
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 common setup for any 3rd party framework or
within a project.
MockRestServiceServer now supports the AsyncRestTemplate for client-side
testing.

5. New Features and Enhancements in Spring

Framework 4.2
5.1 Core Container Improvements
Annotations such as @Bean get detected and processed on Java 8 default methods
as well, allowing for composing a configuration class from interfaces with default
@Bean methods.
Configuration classes may declare @Import with regular component classes now,
allowing for a mix of imported configuration classes and component classes.
Configuration classes may declare an @Order value, getting processed in a
corresponding order (e.g. for overriding beans by name) even when detected through
classpath scanning.
@Resource injection points support an @Lazy declaration, analogous to
@Autowired , receiving a lazy-initializing proxy for the requested target bean.
The application event infrastructure now offers an annotation-based model as well as
the ability to publish any arbitrary event.
Any public method in a managed bean can be annotated with @EventListener
to consume events.
@TransactionalEventListener provides transaction-bound event support.
Spring Framework 4.2 introduces first-class support for declaring and looking up

25/08/2016 12:10

Spring Framework Reference Documentation

64 de 1194

aliases for annotation attributes. The new @AliasFor annotation can be used to
declare a pair of aliased attributes within a single annotation or to declare an alias
from one attribute in a custom composed annotation to an attribute in a
meta-annotation.
The following annotations have been retrofitted with @AliasFor support in order
to provide meaningful aliases for their value attributes: @Cacheable ,
@CacheEvict , @CachePut , @ComponentScan , @ComponentScan.Filter ,
@ImportResource , @Scope , @ManagedResource , @Header , @Payload ,
@SendToUser , @ActiveProfiles , @ContextConfiguration , @Sql ,
@TestExecutionListeners , @TestPropertySource , @Transactional ,
@ControllerAdvice , @CookieValue , @CrossOrigin , @MatrixVariable ,
@RequestHeader , @RequestMapping , @RequestParam , @RequestPart ,
@ResponseStatus , @SessionAttributes , @ActionMapping ,
@RenderMapping , @EventListener , @TransactionalEventListener .
For example, @ContextConfiguration from the spring-test module is now
declared as follows:
public @interface ContextConfiguration {
@AliasFor("locations")
String[] value() default {};
@AliasFor("value")
String[] locations() default {};
// ...
}

Similarly, composed annotations that override attributes from meta-annotations

can now use @AliasFor for fine-grained control over exactly which attributes
are overridden within an annotation hierarchy. In fact, it is now possible to
declare an alias for the value attribute of a meta-annotation.
For example, one can now develop a composed annotation with a custom
attribute override as follows.
@ContextConfiguration
public @interface MyTestConfig {
@AliasFor(annotation = ContextConfiguration.class, attribute = "value")
String[] xmlFiles();
// ...
}

25/08/2016 12:10

Spring Framework Reference Documentation

65 de 1194

See Spring Annotation Programming Model.

Numerous improvements to Springs search algorithms used for finding
meta-annotations. For example, locally declared composed annotations are now
favored over inherited annotations.
Composed annotations that override attributes from meta-annotations can now be
discovered on interfaces and on abstract, bridge, & interface methods as well as on
classes, standard methods, constructors, and fields.
Maps representing annotation attributes (and AnnotationAttributes instances)
can be synthesized (i.e., converted) into an annotation.
The features of field-based data binding ( DirectFieldAccessor ) have been
aligned with the current property-based data binding ( BeanWrapper ). In particular,
field-based binding now supports navigation for Collections, Arrays, and Maps.
DefaultConversionService now provides out-of-the-box converters for Stream ,
Charset , Currency , and TimeZone . Such converters can be added individually to
any arbitrary ConversionService as well.
DefaultFormattingConversionService comes with out-of-the-box support for the
value types in JSR-354 Money & Currency (if the 'javax.money' API is present on the
classpath): namely, MonetaryAmount and CurrencyUnit . This includes support for
applying @NumberFormat .
@NumberFormat can now be used as a meta-annotation.
JavaMailSenderImpl has a new testConnection() method for checking
connectivity to the server.
ScheduledTaskRegistrar exposes scheduled tasks.
Apache commons-pool2 is now supported for a pooling AOP
CommonsPool2TargetSource .
Introduced StandardScriptFactory as a JSR-223 based mechanism for scripted
beans, exposed through the lang:std element in XML. Supports e.g. JavaScript
and JRuby. (Note: JRubyScriptFactory and lang:jruby are deprecated now, in
favor of using JSR-223.)

5.2 Data Access Improvements

javax.transaction.Transactional is now supported via AspectJ.
SimpleJdbcCallOperations now supports named binding.
Full support for Hibernate ORM 5.0: as a JPA provider (automatically adapted) as
well as through its native API (covered by the new
org.springframework.orm.hibernate5 package).
Embedded databases can now be automatically assigned unique names, and
<jdbc:embedded-database> supports a new database-name attribute. See

25/08/2016 12:10

Spring Framework Reference Documentation

66 de 1194

"Testing Improvements" below for further details.

5.3 JMS Improvements

The autoStartup attribute can be controlled via JmsListenerContainerFactory .
The type of the reply Destination can now be configured per listener container.
The value of the @SendTo annotation can now use a SpEL expression.
The response destination can be computed at runtime using JmsResponse
@JmsListener is now a repeatable annotation to declare several JMS containers on
the same method (use the newly introduced @JmsListeners if youre not using
Java8 yet).

5.4 Web Improvements

HTTP Streaming and Server-Sent Events support, see the section called HTTP
Streaming.
Built-in support for CORS including global (MVC Java config and XML namespace)
and local (e.g. @CrossOrigin ) configuration. See Chapter 27, CORS Support for
details.
HTTP caching updates:
new CacheControl builder; plugged into ResponseEntity ,
WebContentGenerator , ResourceHttpRequestHandler .
improved ETag/Last-Modified support in WebRequest .
Custom mapping annotations, using @RequestMapping as a meta-annotation.
Public methods in AbstractHandlerMethodMapping to register and unregister
request mappings at runtime.
Protected createDispatcherServlet method in
AbstractDispatcherServletInitializer to further customize the
DispatcherServlet instance to use.
HandlerMethod as a method argument on @ExceptionHandler methods,
especially handy in @ControllerAdvice components.
java.util.concurrent.CompletableFuture as an @Controller method return
value type.
Byte-range request support in HttpHeaders and for serving static resources.
@ResponseStatus detected on nested exceptions.
UriTemplateHandler extension point in the RestTemplate .
DefaultUriTemplateHandler exposes baseUrl property and path segment
encoding options.

25/08/2016 12:10

Spring Framework Reference Documentation

67 de 1194

the extension point can also be used to plug in any URI template library.
OkHTTP integration with the RestTemplate .
Custom baseUrl alternative for methods in MvcUriComponentsBuilder .
Serialization/deserialization exception messages are now logged at WARN level.
Default JSON prefix has been changed from "{} && " to the safer ")]}', " one.
New RequestBodyAdvice extension point and built-in implementation to support
Jacksons @JsonView on @RequestBody method arguments.
When using GSON or Jackson 2.6+, the handler method return type is used to
improve serialization of parameterized types like List<Foo> .
Introduced ScriptTemplateView as a JSR-223 based mechanism for scripted web
views, with a focus on JavaScript view templating on Nashorn (JDK 8).

5.5 WebSocket Messaging Improvements

Expose presence information about connected users and subscriptions:
new SimpUserRegistry exposed as a bean named "userRegistry".
sharing of presence information across cluster of servers (see broker relay config
options).
Resolve user destinations across cluster of servers (see broker relay config options).
StompSubProtocolErrorHandler extension point to customize and control STOMP
ERROR frames to clients.
Global @MessageExceptionHandler methods via @ControllerAdvice
components.
Heart-beats and a SpEL expression 'selector' header for subscriptions with
SimpleBrokerMessageHandler .
STOMP client for use over TCP and WebSocket; see Section 26.4.13, STOMP
Client.
@SendTo and @SendToUser can contain destination variable placeholders.
Jacksons @JsonView supported for return values on @MessageMapping and
@SubscribeMapping methods.
ListenableFuture and CompletableFuture as return value types from
@MessageMapping and @SubscribeMapping methods.
MarshallingMessageConverter for XML payloads.

5.6 Testing Improvements

JUnit-based integration tests can now be executed with JUnit rules instead of the
SpringJUnit4ClassRunner . This allows Spring-based integration tests to be run

25/08/2016 12:10

Spring Framework Reference Documentation

68 de 1194

with alternative runners like JUnits Parameterized or third-party runners such as

the MockitoJUnitRunner .
See the section called Spring JUnit 4 Rules for details.
The Spring MVC Test framework now provides first-class support for HtmlUnit,
including integration with Seleniums WebDriver, allowing for page-based web
application testing without the need to deploy to a Servlet container.
See Section 15.6.2, HtmlUnit Integration for details.
AopTestUtils is a new testing utility that allows developers to obtain a reference to
the underlying target object hidden behind one or more Spring proxies.
See Section 14.2.1, General testing utilities for details.
ReflectionTestUtils now supports setting and getting static fields, including
constants.
The original ordering of bean definition profiles declared via @ActiveProfiles is
now retained in order to support use cases such as Spring Boots
ConfigFileApplicationListener which loads configuration files based on the
names of active profiles.
@DirtiesContext supports new BEFORE_METHOD , BEFORE_CLASS , and
BEFORE_EACH_TEST_METHOD modes for closing the ApplicationContext before a
testfor example, if some rogue (i.e., yet to be determined) test within a large test
suite has corrupted the original configuration for the ApplicationContext .
@Commit is a new annotation that may be used as a direct replacement for
@Rollback(false) .
@Rollback may now be used to configure class-level default rollback semantics.
Consequently, @TransactionConfiguration is now deprecated and will be
removed in a subsequent release.
@Sql now supports execution of inlined SQL statements via a new statements
attribute.
The ContextCache that is used for caching ApplicationContext s between tests
is now a public API with a default implementation that can be replaced for custom
caching needs.
DefaultTestContext , DefaultBootstrapContext , and
DefaultCacheAwareContextLoaderDelegate are now public classes in the
support subpackage, allowing for custom extensions.
TestContextBootstrapper s are now responsible for building the TestContext .
In the Spring MVC Test framework, MvcResult details can now be logged at DEBUG
level or written to a custom OutputStream or Writer . See the new log() ,
print(OutputStream) , and print(Writer) methods in
MockMvcResultHandlers for details.
The JDBC XML namespace supports a new database-name attribute in

25/08/2016 12:10

Spring Framework Reference Documentation

69 de 1194

embedded databases - for example, via a SpEL expression or a property

placeholder that is influenced by the current active bean definition profiles.
Embedded databases can now be automatically assigned a unique name, allowing
common test database configuration to be reused in different
ApplicationContext s within a test suite.
See Section 19.8.6, Generating unique names for embedded databases for
details.
MockHttpServletRequest and MockHttpServletResponse now provide better
support for date header formatting via the getDateHeader and setDateHeader
methods.

6. New Features and Enhancements in Spring

Framework 4.3
6.1 Core Container Improvements
Core container exceptions provide richer metadata to evaluate programmatically.
Java 8 default methods get detected as bean property getters/setters.
It is no longer necessary to specify the @Autowired annotation if the target bean
only defines one constructor.
@Configuration classes support constructor injection.
Any SpEL expression used to specify the condition of an @EventListener can
now refer to beans (e.g. @beanName.method() ).
Composed annotations can now override array attributes in meta-annotations with a
single element of the component type of the array. For example, the String[] path
attribute of @RequestMapping can be overridden with String path in a composed
annotation.
@Scheduled and @Schedules may now be used as meta-annotations to create
custom composed annotations with attribute overrides.
@Scheduled is properly supported on beans of any scope.

6.2 Data Access Improvements

jdbc:initialize-database and jdbc:embedded-database support a
configurable separator to be applied to each script.

25/08/2016 12:10

Spring Framework Reference Documentation

70 de 1194

6.3 Caching Improvements

Spring 4.3 allows concurrent calls on a given key to be synchronized so that the value is
only computed once. This is an opt-in feature that should be enabled via the new sync
attribute on @Cacheable . This features introduces a breaking change in the Cache
interface as a get(Object key, Callable<T> valueLoader) method has been
added.
Spring 4.3 also improves the caching abstraction as follows:
SpEL expressions in caches-related annotations can now refer to beans (i.e.
@beanName.method() ).
ConcurrentMapCacheManager and ConcurrentMapCache now support the
serialization of cache entries via a new storeByValue attribute.
@Cacheable , @CacheEvict , @CachePut , and @Caching may now be used as
meta-annotations to create custom composed annotations with attribute overrides.

6.4 JMS Improvements

@SendTo can now be specified at the class level to share a common reply
destination.
@JmsListener and @JmsListeners may now be used as meta-annotations to
create custom composed annotations with attribute overrides.

6.5 Web Improvements

Built-in support for HTTP HEAD and HTTP OPTIONS.
New @GetMapping , @PostMapping , @PutMapping , @DeleteMapping , and
@PatchMapping composed annotations for @RequestMapping .
See Composed @RequestMapping Variants for details.
New @RequestScope , @SessionScope , and @ApplicationScope composed
annotations for web scopes.
See Request scope, Session scope, and Application scope for details.
New @RestControllerAdvice annotation with combined @ControllerAdvice
with @ResponseBody semantics.
@ResponseStatus is now supported at the class level and inherited by all methods.
New @SessionAttribute annotation for access to session attributes (see
example).
New @RequestAttribute annotation for access to request attributes (see

25/08/2016 12:10

Spring Framework Reference Documentation

71 de 1194

example).
@ModelAttribute allows preventing data binding via binding=false attribute
(see reference).
Consistent exposure of Errors and custom Throwables to MVC exception handlers.
Consistent charset handling in HTTP message converters, including a UTF-8 default
for multipart text content.
Static resource handling uses the configured ContentNegotiationManager for
media type determination.
RestTemplate and AsyncRestTemplate support strict URI variable encoding via
DefaultUriTemplateHandler .
AsyncRestTemplate supports request interception.

6.6 WebSocket Messaging Improvements

@SendTo and @SendToUser can now be specified at class-level to share a common
destination.

6.7 Testing Improvements

The JUnit support in the Spring TestContext Framework now requires JUnit 4.12 or
higher.
New SpringRunner alias for the SpringJUnit4ClassRunner .
Test related annotations may now be declared on interfacesfor example, for use
with test interfaces that make use of Java 8 based interface default methods.
An empty declaration of @ContextConfiguration can now be completely omitted if
default XML files, Groovy scripts, or @Configuration classes are detected.
@Transactional test methods are no longer required to be public (e.g., in
TestNG and JUnit 5).
@BeforeTransaction and @AfterTransaction methods are no longer required to
be public and may now be declared on Java 8 based interface default methods.
The ApplicationContext cache in the Spring TestContext Framework is now
bounded with a default maximum size of 32 and a least recently used eviction policy.
The maximum size can be configured by setting a JVM system property or Spring
property called spring.test.context.cache.maxSize .
New ContextCustomizer API for customizing a test ApplicationContext after
bean definitions have been loaded into the context but before the context has been
refreshed. Customizers can be registered globally by third parties, foregoing the need
to implement a custom ContextLoader .

25/08/2016 12:10

Spring Framework Reference Documentation

72 de 1194

@Sql and @SqlGroup may now be used as meta-annotations to create custom

composed annotations with attribute overrides.
ReflectionTestUtils now automatically unwraps proxies when setting or getting a
field.
Server-side Spring MVC Test supports expectations on response headers with
multiple values.
Server-side Spring MVC Test parses form data request content and populates
request parameters.
Server-side Spring MVC Test supports mock-like assertions for invoked handler
methods.
Client-side REST test support allows indicating how many times a request is
expected and whether the order of declaration for expectations should be ignored
(see Section 15.6.3, Client-Side REST Tests).
Client-side REST Test supports expectations for form data in the request body.

6.8 Support for new library and server generations

Hibernate ORM 5.2 (still supporting 4.2/4.3 and 5.0/5.1 as well, with 3.6 deprecated
now)
Jackson 2.8 (minimum raised to Jackson 2.6+ as of Spring 4.3)
OkHttp 3.x (still supporting OkHttp 2.x side by side)
Netty 4.1
Undertow 1.4
Tomcat 8.5.2 as well as 9.0 M6
Furthermore, Spring Framework 4.3 embeds the updated ASM 5.1 and Objenesis 2.4 in
spring-core.jar .

Part III. Core Technologies

This part of the reference documentation covers all of those technologies that are
absolutely integral to the Spring Framework.
Foremost amongst these is the Spring Frameworks Inversion of Control (IoC) container.
A thorough treatment of the Spring Frameworks IoC container is closely followed by
comprehensive coverage of Springs Aspect-Oriented Programming (AOP) technologies.

25/08/2016 12:10

Spring Framework Reference Documentation

73 de 1194

The Spring Framework has its own AOP framework, which is conceptually easy to
understand, and which successfully addresses the 80% sweet spot of AOP requirements
in Java enterprise programming.
Coverage of Springs integration with AspectJ (currently the richest - in terms of features and certainly most mature AOP implementation in the Java enterprise space) is also
provided.
Chapter 7, The IoC container
Chapter 8, Resources
Chapter 9, Validation, Data Binding, and Type Conversion
Chapter 10, Spring Expression Language (SpEL)
Chapter 11, Aspect Oriented Programming with Spring
Chapter 12, Spring AOP APIs

7. The IoC container

7.1 Introduction to the Spring IoC container and beans
This chapter covers the Spring Framework implementation of the Inversion of Control
(IoC) [1] 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 instance after it is constructed or returned from a factory method. The container
then injects those dependencies when it creates the bean. This process is fundamentally
the inverse, hence the name Inversion of Control (IoC), of the bean itself controlling the
instantiation or location of its dependencies by using direct construction of classes, or a
mechanism such as the Service Locator pattern.
The org.springframework.beans and org.springframework.context packages
are the basis for Spring Frameworks IoC container. The BeanFactory interface provides
an advanced configuration mechanism capable of managing any type of object.
ApplicationContext is a sub-interface of BeanFactory . It adds easier integration with
Springs AOP features; message resource handling (for use in internationalization), event
publication; and application-layer specific contexts such as the
WebApplicationContext for use in web applications.
In short, the BeanFactory provides the configuration framework and basic functionality,
and the ApplicationContext adds more enterprise-specific functionality. The

25/08/2016 12:10

Spring Framework Reference Documentation

74 de 1194

exclusively in this chapter in descriptions of Springs IoC container. For more information
on using the BeanFactory instead of the ApplicationContext, refer to Section 7.16,
The BeanFactory.
In Spring, the objects that form the backbone of your application and that are managed by
the Spring IoC container are called beans. A bean is an object that is instantiated,
assembled, and otherwise managed by a Spring IoC container. Otherwise, a bean is
simply one of many objects in your application. Beans, and the dependencies among
them, are reflected in the configuration metadata used by a container.

7.2 Container overview

The interface org.springframework.context.ApplicationContext represents the
Spring IoC container and is responsible for instantiating, configuring, and assembling the
aforementioned beans. The container gets its instructions on what objects to instantiate,
configure, and assemble by reading configuration metadata. The configuration metadata
is represented in XML, Java annotations, or Java code. It allows you to express the
objects that compose your application and the rich interdependencies between such
objects.
Several implementations of the ApplicationContext interface are supplied out-ofthe-box with Spring. In standalone applications it is common to create an instance of
ClassPathXmlApplicationContext or FileSystemXmlApplicationContext . While
XML has been the traditional format for defining configuration metadata you can instruct
the container to use Java annotations or code as the metadata format by providing a
small amount of XML configuration to declaratively enable support for these additional
metadata formats.
In most application scenarios, explicit user code is not required to instantiate one or more
instances of a Spring IoC container. For example, in a web application scenario, a simple
eight (or so) lines of boilerplate web descriptor XML in the web.xml file of the application
will typically suffice (see Section 7.15.4, Convenient ApplicationContext instantiation for
web applications). If you are using the Spring Tool Suite Eclipse-powered development
environment this boilerplate configuration can be easily created with few mouse clicks or
keystrokes.
The following diagram is a high-level view of how Spring works. Your application classes
are combined with configuration metadata so that after the ApplicationContext is
created and initialized, you have a fully configured and executable system or application.
Figure 7.1. The Spring IoC container

25/08/2016 12:10

Spring Framework Reference Documentation

75 de 1194

7.2.1 Configuration metadata

As the preceding diagram shows, the Spring IoC container consumes a form of
configuration metadata; this configuration metadata represents how you as an application
developer tell the Spring container to instantiate, configure, and assemble the objects in
your application.
Configuration metadata is traditionally supplied in a simple and intuitive XML format,
which is what most of this chapter uses to convey key concepts and features of the
Spring IoC container.

XML-based metadata is not the only allowed form of configuration

metadata. The Spring IoC container itself is totally decoupled from the
format in which this configuration metadata is actually written. These days
many developers choose Java-based configuration for their Spring
applications.

For information about using other forms of metadata with the Spring container, see:
Annotation-based configuration: Spring 2.5 introduced support for annotation-based
configuration metadata.
Java-based configuration: Starting with Spring 3.0, many features provided by the
Spring JavaConfig project became part of the core Spring Framework. Thus you can
define beans external to your application classes by using Java rather than XML files.
To use these new features, see the @Configuration , @Bean , @Import and

25/08/2016 12:10

Spring Framework Reference Documentation

76 de 1194

Spring configuration consists of at least one and typically more than one bean definition
that the container must manage. XML-based configuration metadata shows these beans
configured as <bean/> elements inside a top-level <beans/> element. Java
configuration typically uses @Bean annotated methods within a @Configuration class.
These bean definitions correspond to the actual objects that make up your application.
Typically you define service layer objects, data access objects (DAOs), presentation
objects such as Struts Action instances, infrastructure objects such as Hibernate
SessionFactories , JMS Queues , and so forth. Typically one does not configure
fine-grained domain objects in the container, because it is usually the responsibility of
DAOs and business logic to create and load domain objects. However, you can use
Springs integration with AspectJ to configure objects that have been created outside the
control of an IoC container. See Using AspectJ to dependency-inject domain objects with
Spring.
The following example shows the basic structure of XML-based configuration metadata:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="..." class="...">

</bean>
<bean id="..." class="...">

</bean>

</beans>

The id attribute is a string that you use to identify the individual bean definition. The
class attribute defines the type of the bean and uses the fully qualified classname. The
value of the id attribute refers to collaborating objects. The XML for referring to
collaborating objects is not shown in this example; see Dependencies for more
information.

7.2.2 Instantiating a container

25/08/2016 12:10

Spring Framework Reference Documentation

77 de 1194

to an ApplicationContext constructor are actually resource strings that allow the

container to load configuration metadata from a variety of external resources such as the
local file system, from the Java CLASSPATH , and so on.
ApplicationContext context =
new ClassPathXmlApplicationContext(new String[] {"services.xml", "daos.xml"

After you learn about Springs IoC container, you may want to know more
about Springs Resource abstraction, as described in Chapter 8,
Resources, which provides a convenient mechanism for reading an
InputStream from locations defined in a URI syntax. In particular,
Resource paths are used to construct applications contexts as described
in Section 8.7, Application contexts and Resource paths.

The following example shows the service layer objects (services.xml) configuration
file:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">

<bean id="petStore" class="org.springframework.samples.jpetstore.services.PetStore

The following example shows the data access objects daos.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">

25/08/2016 12:10

Spring Framework Reference Documentation

78 de 1194

class="org.springframework.samples.jpetstore.dao.jpa.JpaAccountDao">

</bean>

<bean id="itemDao" class="org.springframework.samples.jpetstore.dao.jpa.JpaItemDao

</bean>

</beans>

In the preceding example, the service layer consists of the class

PetStoreServiceImpl , and two data access objects of the type JpaAccountDao and
JpaItemDao (based on the JPA Object/Relational mapping standard). The
property name element refers to the name of the JavaBean property, and the ref
element refers to the name of another bean definition. This linkage between id and ref
elements expresses the dependency between collaborating objects. For details of
configuring an objects dependencies, see Dependencies.

Composing XML-based configuration metadata

It can be useful to have bean definitions span multiple XML files. Often each individual
XML configuration file represents a logical layer or module in your architecture.
You can use the application context constructor to load bean definitions from all these
XML fragments. This constructor takes multiple Resource locations, as was shown in
the previous section. Alternatively, use one or more occurrences of the <import/>
element to load bean definitions from another file or files. For example:
<beans>
<import resource="services.xml"/>
<import resource="resources/messageSource.xml"/>
<import resource="/resources/themeSource.xml"/>
<bean id="bean1" class="..."/>
<bean id="bean2" class="..."/>
</beans>

In the preceding example, external bean definitions are loaded from three files:
services.xml , messageSource.xml , and themeSource.xml . All location paths are
relative to the definition file doing the importing, so services.xml must be in the same
directory or classpath location as the file doing the importing, while messageSource.xml
and themeSource.xml must be in a resources location below the location of the

25/08/2016 12:10

Spring Framework Reference Documentation

79 de 1194

importing file. As you can see, a leading slash is ignored, but given that these paths are
relative, it is better form not to use the slash at all. The contents of the files being
imported, including the top level <beans/> element, must be valid XML bean definitions
according to the Spring Schema.

It is possible, but not recommended, to reference files in parent directories

using a relative "../" path. Doing so creates a dependency on a file that is
outside the current application. In particular, this reference is not
recommended for "classpath:" URLs (for example,
"classpath:../services.xml"), where the runtime resolution process chooses
the "nearest" classpath root and then looks into its parent directory.
Classpath configuration changes may lead to the choice of a different,
incorrect directory.
You can always use fully qualified resource locations instead of relative
paths: for example, "file:C:/config/services.xml" or "classpath:/config
/services.xml". However, be aware that you are coupling your applications
configuration to specific absolute locations. It is generally preferable to keep
an indirection for such absolute locations, for example, through "${}"
placeholders that are resolved against JVM system properties at runtime.

7.2.3 Using the container

The ApplicationContext is the interface for an advanced factory capable of
maintaining a registry of different beans and their dependencies. Using the method
T getBean(String name, Class<T> requiredType) you can retrieve instances of
your beans.
The ApplicationContext enables you to read bean definitions and access them as
follows:
// create and configure beans
ApplicationContext context =
new ClassPathXmlApplicationContext(new String[] {"services.xml", "daos.xml"
// retrieve configured instance
PetStoreService service = context.getBean("petStore", PetStoreService.class);
// use configured instance
List<String> userList = service.getUsernameList();

25/08/2016 12:10

Spring Framework Reference Documentation

80 de 1194

interface has a few other methods for retrieving beans, but ideally your application code
should never use them. Indeed, your application code should have no calls to the
getBean() method at all, and thus no dependency on Spring APIs at all. For example,
Springs integration with web frameworks provides for dependency injection for various
web framework classes such as controllers and JSF-managed beans.

7.3 Bean overview

A Spring IoC container manages one or more beans. These beans are created with the
configuration metadata that you supply to the container, for example, in the form of XML
<bean/> definitions.
Within the container itself, these bean definitions are represented as BeanDefinition
objects, which contain (among other information) the following metadata:
A package-qualified class name: typically the actual implementation class of the bean
being defined.
Bean behavioral configuration elements, which state how the bean should behave in
the container (scope, lifecycle callbacks, and so forth).
References to other beans that are needed for the bean to do its work; these
references are also called collaborators or dependencies.
Other configuration settings to set in the newly created object, for example, the
number of connections to use in a bean that manages a connection pool, or the size
limit of the pool.
This metadata translates to a set of properties that make up each bean definition.

Table 7.1. The bean definition

Property

Explained in

class

Section 7.3.2, Instantiating beans

name

Section 7.3.1, Naming beans

scope

Section 7.5, Bean scopes

constructor arguments

Section 7.4.1, Dependency Injection

properties

Section 7.4.1, Dependency Injection

autowiring mode

Section 7.4.5, Autowiring collaborators

25/08/2016 12:10

Spring Framework Reference Documentation

81 de 1194

Property

Explained in

lazy-initialization mode

Section 7.4.4, Lazy-initialized beans

initialization method

the section called Initialization callbacks

destruction method

the section called Destruction callbacks

In addition to bean definitions that contain information on how to create a specific bean,
the ApplicationContext implementations also permit the registration of existing
objects that are created outside the container, by users. This is done by accessing the
ApplicationContexts BeanFactory via the method getBeanFactory() which returns the
BeanFactory implementation DefaultListableBeanFactory .
DefaultListableBeanFactory supports this registration through the methods
registerSingleton(..) and registerBeanDefinition(..) . However, typical
applications work solely with beans defined through metadata bean definitions.

Bean metadata and manually supplied singleton instances need to be

registered as early as possible, in order for the container to properly reason
about them during autowiring and other introspection steps. While
overriding of existing metadata and existing singleton instances is
supported to some degree, the registration of new beans at runtime
(concurrently with live access to factory) is not officially supported and may
lead to concurrent access exceptions and/or inconsistent state in the bean
container.

7.3.1 Naming beans

Every bean has one or more identifiers. These identifiers must be unique within the
container that hosts the bean. A bean usually has only one identifier, but if it requires
more than one, the extra ones can be considered aliases.
In XML-based configuration metadata, you use the id and/or name attributes to specify
the bean identifier(s). The id attribute allows you to specify exactly one id.
Conventionally these names are alphanumeric ('myBean', 'fooService', etc.), but may
contain special characters as well. If you want to introduce other aliases to the bean, you
can also specify them in the name attribute, separated by a comma ( , ), semicolon ( ; ),
or white space. As a historical note, in versions prior to Spring 3.1, the id attribute was

25/08/2016 12:10

Spring Framework Reference Documentation

82 de 1194

defined as an xsd:ID type, which constrained possible characters. As of 3.1, it is

defined as an xsd:string type. Note that bean id uniqueness is still enforced by the
container, though no longer by XML parsers.
You are not required to supply a name or id for a bean. If no name or id is supplied
explicitly, the container generates a unique name for that bean. However, if you want to
refer to that bean by name, through the use of the ref element or Service Locator style
lookup, you must provide a name. Motivations for not supplying a name are related to
using inner beans and autowiring collaborators.
Bean Naming Conventions
The convention is to use the standard Java convention for instance field names
when naming beans. That is, bean names start with a lowercase letter, and are
camel-cased from then on. Examples of such names would be (without quotes)
'accountManager' , 'accountService' , 'userDao' , 'loginController' ,
and so forth.
Naming beans consistently makes your configuration easier to read and
understand, and if you are using Spring AOP it helps a lot when applying advice to
a set of beans related by name.

With component scanning in the classpath, Spring generates bean names

for unnamed components, following the rules above: essentially, taking the
simple class name and turning its initial character to lower-case. However,
in the (unusual) special case when there is more than one character and
both the first and second characters are upper case, the original casing gets
preserved. These are the same rules as defined by
java.beans.Introspector.decapitalize (which Spring is using here).

Aliasing a bean outside the bean definition

In a bean definition itself, you can supply more than one name for the bean, by using a
combination of up to one name specified by the id attribute, and any number of other
names in the name attribute. These names can be equivalent aliases to the same bean,
and are useful for some situations, such as allowing each component in an application to
refer to a common dependency by using a bean name that is specific to that component
itself.
Specifying all aliases where the bean is actually defined is not always adequate, however.

25/08/2016 12:10

Spring Framework Reference Documentation

83 de 1194

is commonly the case in large systems where configuration is split amongst each
subsystem, each subsystem having its own set of object definitions. In XML-based
configuration metadata, you can use the <alias/> element to accomplish this.
<alias name="fromName" alias="toName"/>

In this case, a bean in the same container which is named fromName , may also, after the
use of this alias definition, be referred to as toName .
For example, the configuration metadata for subsystem A may refer to a DataSource via
the name subsystemA-dataSource . The configuration metadata for subsystem B may
refer to a DataSource via the name subsystemB-dataSource . When composing the
main application that uses both these subsystems the main application refers to the
DataSource via the name myApp-dataSource . To have all three names refer to the
same object you add to the MyApp configuration metadata the following aliases
definitions:
<alias name="subsystemA-dataSource" alias="subsystemB-dataSource"/>
<alias name="subsystemA-dataSource" alias="myApp-dataSource" />

Now each component and the main application can refer to the dataSource through a
name that is unique and guaranteed not to clash with any other definition (effectively
creating a namespace), yet they refer to the same bean.
Java-configuration
If you are using Java-configuration, the @Bean annotation can be used to provide
aliases see Section 7.12.3, Using the @Bean annotation for details.

7.3.2 Instantiating beans

A bean definition essentially is a recipe for creating one or more objects. The container
looks at the recipe for a named bean when asked, and uses the configuration metadata
encapsulated by that bean definition to create (or acquire) an actual object.
If you use XML-based configuration metadata, you specify the type (or class) of object
that is to be instantiated in the class attribute of the <bean/> element. This class
attribute, which internally is a Class property on a BeanDefinition instance, is usually
mandatory. (For exceptions, see the section called Instantiation using an instance factory
method and Section 7.7, Bean definition inheritance.) You use the Class property in
one of two ways:

25/08/2016 12:10

Spring Framework Reference Documentation

84 de 1194

Typically, to specify the bean class to be constructed in the case where the container
itself directly creates the bean by calling its constructor reflectively, somewhat
equivalent to Java code using the new operator.
To specify the actual class containing the static factory method that will be invoked
to create the object, in the less common case where the container invokes a static
factory method on a class to create the bean. The object type returned from the
invocation of the static factory method may be the same class or another class
entirely.
Inner class names. If you want to configure a bean definition for a static nested
class, you have to use the binary name of the nested class.
For example, if you have a class called Foo in the com.example package, and
this Foo class has a static nested class called Bar , the value of the 'class'
attribute on a bean definition would be
com.example.Foo$Bar
Notice the use of the $ character in the name to separate the nested class name
from the outer class name.

Instantiation with a constructor

When you create a bean by the constructor approach, all normal classes are usable by
and compatible with Spring. That is, the class being developed does not need to
implement any specific interfaces or to be coded in a specific fashion. Simply specifying
the bean class should suffice. However, depending on what type of IoC you use for that
specific bean, you may need a default (empty) constructor.
The Spring IoC container can manage virtually any class you want it to manage; it is not
limited to managing true JavaBeans. Most Spring users prefer actual JavaBeans with
only a default (no-argument) constructor and appropriate setters and getters modeled
after the properties in the container. You can also have more exotic non-bean-style
classes in your container. If, for example, you need to use a legacy connection pool that
absolutely does not adhere to the JavaBean specification, Spring can manage it as well.
With XML-based configuration metadata you can specify your bean class as follows:
<bean id="exampleBean" class="examples.ExampleBean"/>
<bean name="anotherExample" class="examples.ExampleBeanTwo"/>

For details about the mechanism for supplying arguments to the constructor (if required)

25/08/2016 12:10

Spring Framework Reference Documentation

85 de 1194

Dependencies.

Instantiation with a static factory method

When defining a bean that you create with a static factory method, you use the class
attribute to specify the class containing the static factory method and an attribute
named factory-method to specify the name of the factory method itself. You should be
able to call this method (with optional arguments as described later) and return a live
object, which subsequently is treated as if it had been created through a constructor. One
use for such a bean definition is to call static factories in legacy code.
The following bean definition specifies that the bean will be created by calling a factorymethod. The definition does not specify the type (class) of the returned object, only the
class containing the factory method. In this example, the createInstance() method
must be a static method.
<bean id="clientService"
class="examples.ClientService"
factory-method="createInstance"/>
public class ClientService {
private static ClientService clientService = new ClientService();
private ClientService() {}
public static ClientService createInstance() {
return clientService;
}
}

For details about the mechanism for supplying (optional) arguments to the factory method
and setting object instance properties after the object is returned from the factory, see
Dependencies and configuration in detail.

Instantiation using an instance factory method

Similar to instantiation through a static factory method, instantiation with an instance
factory method invokes a non-static method of an existing bean from the container to
create a new bean. To use this mechanism, leave the class attribute empty, and in the
factory-bean attribute, specify the name of a bean in the current (or parent/ancestor)
container that contains the instance method that is to be invoked to create the object. Set
the name of the factory method itself with the factory-method attribute.

25/08/2016 12:10

Spring Framework Reference Documentation

86 de 1194

<bean id="serviceLocator" class="examples.DefaultServiceLocator">

</bean>

<bean id="clientService"
factory-bean="serviceLocator"
factory-method="createClientServiceInstance"/>
public class DefaultServiceLocator {
private static ClientService clientService = new ClientServiceImpl();
private DefaultServiceLocator() {}
public ClientService createClientServiceInstance() {
return clientService;
}
}

One factory class can also hold more than one factory method as shown here:
<bean id="serviceLocator" class="examples.DefaultServiceLocator">

</bean>
<bean id="clientService"
factory-bean="serviceLocator"
factory-method="createClientServiceInstance"/>
<bean id="accountService"
factory-bean="serviceLocator"
factory-method="createAccountServiceInstance"/>
public class DefaultServiceLocator {
private static ClientService clientService = new ClientServiceImpl();
private static AccountService accountService = new AccountServiceImpl();
private DefaultServiceLocator() {}
public ClientService createClientServiceInstance() {
return clientService;
}
public AccountService createAccountServiceInstance() {
return accountService;
}

25/08/2016 12:10

Spring Framework Reference Documentation

87 de 1194

This approach shows that the factory bean itself can be managed and configured through
dependency injection (DI). See Dependencies and configuration in detail.

In Spring documentation, factory bean refers to a bean that is configured in

the Spring container that will create objects through an instance or static
factory method. By contrast, FactoryBean (notice the capitalization) refers
to a Spring-specific FactoryBean .

7.4 Dependencies
A typical enterprise application does not consist of a single object (or bean in the Spring
parlance). Even the simplest application has a few objects that work together to present
what the end-user sees as a coherent application. This next section explains how you go
from defining a number of bean definitions that stand alone to a fully realized application
where objects collaborate to achieve a goal.

7.4.1 Dependency Injection

Dependency injection (DI) 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 instance after it is constructed or
returned from a factory method. The container then injects those dependencies when it
creates the bean. This process is fundamentally the inverse, hence the name Inversion of
Control (IoC), of the bean itself controlling the instantiation or location of its dependencies
on its own by using direct construction of classes, or the Service Locator pattern.
Code is cleaner with the DI principle and decoupling is more effective when objects are
provided with their dependencies. The object does not look up its dependencies, and
does not know the location or class of the dependencies. As such, your classes become
easier to test, in particular when the dependencies are on interfaces or abstract base
classes, which allow for stub or mock implementations to be used in unit tests.
DI exists in two major variants, Constructor-based dependency injection and Setter-based
dependency injection.

Constructor-based dependency injection

25/08/2016 12:10

Spring Framework Reference Documentation

88 de 1194

Constructor-based DI is accomplished by the container invoking a constructor with a

number of arguments, each representing a dependency. Calling a static factory
method with specific arguments to construct the bean is nearly equivalent, and this
discussion treats arguments to a constructor and to a static factory method similarly.
The following example shows a class that can only be dependency-injected with
constructor injection. Notice that there is nothing special about this class, it is a POJO
that has no dependencies on container specific interfaces, base classes or annotations.
public class SimpleMovieLister {
// the SimpleMovieLister has a dependency on a MovieFinder
private MovieFinder movieFinder;
// a constructor so that the Spring container can inject a MovieFinder
public SimpleMovieLister(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
// business logic that actually uses the injected MovieFinder is omitted...
}

Constructor argument resolution

Constructor argument resolution matching occurs using the arguments type. If no
potential ambiguity exists in the constructor arguments of a bean definition, then the order
in which the constructor arguments are defined in a bean definition is the order in which
those arguments are supplied to the appropriate constructor when the bean is being
instantiated. Consider the following class:
package x.y;
public class Foo {
public Foo(Bar bar, Baz baz) {
// ...
}
}

No potential ambiguity exists, assuming that Bar and Baz classes are not related by
inheritance. Thus the following configuration works fine, and you do not need to specify
the constructor argument indexes and/or types explicitly in the <constructor-arg/>
element.

25/08/2016 12:10

Spring Framework Reference Documentation

89 de 1194

When another bean is referenced, the type is known, and matching can occur (as was the
case with the preceding example). When a simple type is used, such as
<value>true</value> , Spring cannot determine the type of the value, and so cannot
match by type without help. Consider the following class:
package examples;
public class ExampleBean {
// Number of years to calculate the Ultimate Answer
private int years;
// The Answer to Life, the Universe, and Everything
private String ultimateAnswer;
public ExampleBean(int years, String ultimateAnswer) {
this.years = years;
this.ultimateAnswer = ultimateAnswer;
}
}

In the preceding scenario, the container can use type matching with simple types if you
explicitly specify the type of the constructor argument using the type attribute. For
example:
<bean id="exampleBean" class="examples.ExampleBean">
<constructor-arg type="int" value="7500000"/>
<constructor-arg type="java.lang.String" value="42"/>
</bean>

Use the index attribute to specify explicitly the index of constructor arguments. For
example:

25/08/2016 12:10

Spring Framework Reference Documentation

90 de 1194

<constructor-arg index="0" value="7500000"/>

<constructor-arg index="1" value="42"/>
</bean>

In addition to resolving the ambiguity of multiple simple values, specifying an index

resolves ambiguity where a constructor has two arguments of the same type. Note that
the index is 0 based.
You can also use the constructor parameter name for value disambiguation:
<bean id="exampleBean" class="examples.ExampleBean">
<constructor-arg name="years" value="7500000"/>
<constructor-arg name="ultimateAnswer" value="42"/>
</bean>

Keep in mind that to make this work out of the box your code must be compiled with the
debug flag enabled so that Spring can look up the parameter name from the constructor.
If you cant compile your code with debug flag (or dont want to) you can use
@ConstructorProperties JDK annotation to explicitly name your constructor arguments.
The sample class would then have to look as follows:
package examples;
public class ExampleBean {
// Fields omitted
@ConstructorProperties({"years", "ultimateAnswer"})
public ExampleBean(int years, String ultimateAnswer) {
this.years = years;
this.ultimateAnswer = ultimateAnswer;
}
}

Setter-based dependency injection

Setter-based DI is accomplished by the container calling setter methods on your beans
after invoking a no-argument constructor or no-argument static factory method to
instantiate your bean.
The following example shows a class that can only be dependency-injected using pure
setter injection. This class is conventional Java. It is a POJO that has no dependencies
on container specific interfaces, base classes or annotations.

25/08/2016 12:10

Spring Framework Reference Documentation

91 de 1194

public class SimpleMovieLister {

// the SimpleMovieLister has a dependency on the MovieFinder
private MovieFinder movieFinder;
// a setter method so that the Spring container can inject a MovieFinder
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
// business logic that actually uses the injected MovieFinder is omitted...
}

The ApplicationContext supports constructor-based and setter-based DI for the

beans it manages. It also supports setter-based DI after some dependencies have
already been injected through the constructor approach. You configure the dependencies
in the form of a BeanDefinition , which you use in conjunction with PropertyEditor
instances to convert properties from one format to another. However, most Spring users
do not work with these classes directly (i.e., programmatically) but rather with XML bean
definitions, annotated components (i.e., classes annotated with @Component ,
@Controller , etc.), or @Bean methods in Java-based @Configuration classes.
These sources are then converted internally into instances of BeanDefinition and
used to load an entire Spring IoC container instance.
Constructor-based or setter-based DI?
Since you can mix constructor-based and setter-based DI, it is a good rule of thumb
to use constructors for mandatory dependencies and setter methods or
configuration methods for optional dependencies. Note that use of the @Required
annotation on a setter method can be used to make the property a required
dependency.
The Spring team generally advocates constructor injection as it enables one to
implement application components as immutable objects and to ensure that
required dependencies are not null . Furthermore constructor-injected
components are always returned to client (calling) code in a fully initialized state. As
a side note, a large number of constructor arguments is a bad code smell, implying
that the class likely has too many responsibilities and should be refactored to better
address proper separation of concerns.
Setter injection should primarily only be used for optional dependencies that can be
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

25/08/2016 12:10

Spring Framework Reference Documentation

92 de 1194

reconfiguration or re-injection later. Management through JMX MBeans is therefore

a compelling use case for setter injection.
Use the DI style that makes the most sense for a particular class. Sometimes, when
dealing with third-party classes for which you do not have the source, the choice is
made for you. For example, if a third-party class does not expose any setter
methods, then constructor injection may be the only available form of DI.

Dependency resolution process

The container performs bean dependency resolution as follows:
The ApplicationContext is created and initialized with configuration metadata that
describes all the beans. Configuration metadata can be specified via XML, Java
code, or annotations.
For each bean, its dependencies are expressed in the form of properties, constructor
arguments, or arguments to the static-factory method if you are using that instead of
a normal constructor. These dependencies are provided to the bean, when the bean
is actually created.
Each property or constructor argument is an actual definition of the value to set, or a
reference to another bean in the container.
Each property or constructor argument which is a value is converted from its
specified format to the actual type of that property or constructor argument. By default
Spring can convert a value supplied in string format to all built-in types, such as int ,
long , String , boolean , etc.
The Spring container validates the configuration of each bean as the container is created.
However, the bean properties themselves are not set until the bean is actually created.
Beans that are singleton-scoped and set to be pre-instantiated (the default) are created
when the container is created. Scopes are defined in Section 7.5, Bean scopes.
Otherwise, the bean is created only when it is requested. Creation of a bean potentially
causes a graph of beans to be created, as the beans dependencies and its
dependencies' dependencies (and so on) are created and assigned. Note that resolution
mismatches among those dependencies may show up late, i.e. on first creation of the
affected bean.
Circular dependencies
If you use predominantly constructor injection, it is possible to create an
unresolvable circular dependency scenario.
For example: Class A requires an instance of class B through constructor injection,

25/08/2016 12:10

Spring Framework Reference Documentation

93 de 1194

and class B requires an instance of class A through constructor injection. If you

configure beans for classes A and B to be injected into each other, the Spring IoC
container detects this circular reference at runtime, and throws a
BeanCurrentlyInCreationException .
One possible solution is to edit the source code of some classes to be configured
by setters rather than constructors. Alternatively, avoid constructor injection and use
setter injection only. In other words, although it is not recommended, you can
configure circular dependencies with setter injection.
Unlike the typical case (with no circular dependencies), a circular dependency
between bean A and bean B forces one of the beans to be injected into the other
prior to being fully initialized itself (a classic chicken/egg scenario).
You can generally trust Spring to do the right thing. It detects configuration problems,
such as references to non-existent beans and circular dependencies, at container
load-time. Spring sets properties and resolves dependencies as late as possible, when
the bean is actually created. This means that a Spring container which has loaded
correctly can later generate an exception when you request an object if there is a problem
creating that object or one of its dependencies. For example, the bean throws an
exception as a result of a missing or invalid property. This potentially delayed visibility of
some configuration issues is why ApplicationContext implementations by default
pre-instantiate singleton beans. At the cost of some upfront time and memory to create
these beans before they are actually needed, you discover configuration issues when the
ApplicationContext is created, not later. You can still override this default behavior so
that singleton beans will lazy-initialize, rather than be pre-instantiated.
If no circular dependencies exist, when one or more collaborating beans are being
injected into a dependent bean, each collaborating bean is totally configured prior to
being injected into the dependent bean. This means that if bean A has a dependency on
bean B, the Spring IoC container completely configures bean B prior to invoking the setter
method on bean A. In other words, the bean is instantiated (if not a pre-instantiated
singleton), its dependencies are set, and the relevant lifecycle methods (such as a
configured init method or the InitializingBean callback method) are invoked.

Examples of dependency injection

The following example uses XML-based configuration metadata for setter-based DI. A
small part of a Spring XML configuration file specifies some bean definitions:
<bean id="exampleBean" class="examples.ExampleBean">

<property name="beanOne">

25/08/2016 12:10

Spring Framework Reference Documentation

94 de 1194

<ref bean="anotherExampleBean"/>
</property>

<property name="beanTwo" ref="yetAnotherBean"/>
<property name="integerProperty" value="1"/>
</bean>
<bean id="anotherExampleBean" class="examples.AnotherBean"/>
<bean id="yetAnotherBean" class="examples.YetAnotherBean"/>
public class ExampleBean {
private AnotherBean beanOne;
private YetAnotherBean beanTwo;
private int i;
public void setBeanOne(AnotherBean beanOne) {
this.beanOne = beanOne;
}
public void setBeanTwo(YetAnotherBean beanTwo) {
this.beanTwo = beanTwo;
}
public void setIntegerProperty(int i) {
this.i = i;
}
}

In the preceding example, setters are declared to match against the properties specified
in the XML file. The following example uses constructor-based DI:
<bean id="exampleBean" class="examples.ExampleBean">

<constructor-arg>
<ref bean="anotherExampleBean"/>
</constructor-arg>

<constructor-arg ref="yetAnotherBean"/>
<constructor-arg type="int" value="1"/>
</bean>
<bean id="anotherExampleBean" class="examples.AnotherBean"/>

25/08/2016 12:10

Spring Framework Reference Documentation

95 de 1194

<bean id="yetAnotherBean" class="examples.YetAnotherBean"/>

public class ExampleBean {
private AnotherBean beanOne;
private YetAnotherBean beanTwo;
private int i;
public ExampleBean(
AnotherBean anotherBean, YetAnotherBean yetAnotherBean, int i) {
this.beanOne = anotherBean;
this.beanTwo = yetAnotherBean;
this.i = i;
}
}

The constructor arguments specified in the bean definition will be used as arguments to
the constructor of the ExampleBean .
Now consider a variant of this example, where instead of using a constructor, Spring is
told to call a static factory method to return an instance of the object:
<bean id="exampleBean" class="examples.ExampleBean" factory-method="createInstance"
<constructor-arg ref="anotherExampleBean"/>
<constructor-arg ref="yetAnotherBean"/>
<constructor-arg value="1"/>
</bean>
<bean id="anotherExampleBean" class="examples.AnotherBean"/>
<bean id="yetAnotherBean" class="examples.YetAnotherBean"/>
public class ExampleBean {
// a private constructor
private ExampleBean(...) {
...
}
// a static factory method; the arguments to this method can be
// considered the dependencies of the bean that is returned,
// regardless of how those arguments are actually used.
public static ExampleBean createInstance (
AnotherBean anotherBean, YetAnotherBean yetAnotherBean, int i) {
ExampleBean eb = new ExampleBean (...);

25/08/2016 12:10

Spring Framework Reference Documentation

96 de 1194

return eb;
}
}

Arguments to the static factory method are supplied via <constructor-arg/>

elements, exactly the same as if a constructor had actually been used. The type of the
class being returned by the factory method does not have to be of the same type as the
class that contains the static factory method, although in this example it is. An instance
(non-static) factory method would be used in an essentially identical fashion (aside from
the use of the factory-bean attribute instead of the class attribute), so details will not
be discussed here.

7.4.2 Dependencies and configuration in detail

As mentioned in the previous section, you can define bean properties and constructor
arguments as references to other managed beans (collaborators), or as values defined
inline. Springs XML-based configuration metadata supports sub-element types within its
<property/> and <constructor-arg/> elements for this purpose.

Straight values (primitives, Strings, and so on)

The value attribute of the <property/> element specifies a property or constructor
argument as a human-readable string representation. Springs conversion service is used
to convert these values from a String to the actual type of the property or argument.

<bean id="myDataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method

<property name="driverClassName" value="com.mysql.jdbc.Driver"/>
<property name="url" value="jdbc:mysql://localhost:3306/mydb"/>
<property name="username" value="root"/>
<property name="password" value="masterkaoli"/>
</bean>

The following example uses the p-namespace for even more succinct XML configuration.
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="myDataSource" class="org.apache.commons.dbcp.BasicDataSource"

25/08/2016 12:10

Spring Framework Reference Documentation

97 de 1194

destroy-method="close"
p:driverClassName="com.mysql.jdbc.Driver"
p:url="jdbc:mysql://localhost:3306/mydb"
p:username="root"
p:password="masterkaoli"/>
</beans>

The preceding XML is more succinct; however, typos are discovered at runtime rather
than design time, unless you use an IDE such as IntelliJ IDEA or the Spring Tool Suite
(STS) that support automatic property completion when you create bean definitions. Such
IDE assistance is highly recommended.
You can also configure a java.util.Properties instance as:
<bean id="mappings"
class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"

<property name="properties">
<value>
jdbc.driver.className=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/mydb
</value>
</property>
</bean>

The Spring container converts the text inside the <value/> element into a
java.util.Properties instance by using the JavaBeans PropertyEditor
mechanism. This is a nice shortcut, and is one of a few places where the Spring team do
favor the use of the nested <value/> element over the value attribute style.

The idref element

The idref element is simply an error-proof way to pass the id (string value - not a
reference) of another bean in the container to a <constructor-arg/> or <property/>
element.
<bean id="theTargetBean" class="..."/>
<bean id="theClientBean" class="...">
<property name="targetName">
<idref bean="theTargetBean" />
</property>
</bean>

25/08/2016 12:10

Spring Framework Reference Documentation

98 de 1194

The above bean definition snippet is exactly equivalent (at runtime) to the following
snippet:
<bean id="theTargetBean" class="..." />
<bean id="client" class="...">
<property name="targetName" value="theTargetBean" />
</bean>

The first form is preferable to the second, because using the idref tag allows the
container to validate at deployment time that the referenced, named bean actually exists.
In the second variation, no validation is performed on the value that is passed to the
targetName property of the client bean. Typos are only discovered (with most likely
fatal results) when the client bean is actually instantiated. If the client bean is a
prototype bean, this typo and the resulting exception may only be discovered long after
the container is deployed.

The local attribute on the idref element is no longer supported in the

4.0 beans xsd since it does not provide value over a regular bean
reference anymore. Simply change your existing idref local references
to idref bean when upgrading to the 4.0 schema.

A common place (at least in versions earlier than Spring 2.0) where the <idref/>
element brings value is in the configuration of AOP interceptors in a ProxyFactoryBean
bean definition. Using <idref/> elements when you specify the interceptor names
prevents you from misspelling an interceptor id.

References to other beans (collaborators)

The ref element is the final element inside a <constructor-arg/> or <property/>
definition element. Here you set the value of the specified property of a bean to be a
reference to another bean (a collaborator) managed by the container. The referenced
bean is a dependency of the bean whose property will be set, and it is initialized on
demand as needed before the property is set. (If the collaborator is a singleton bean, it
may be initialized already by the container.) All references are ultimately a reference to
another object. Scoping and validation depend on whether you specify the id/name of the
other object through the bean , local, or parent attributes.
Specifying the target bean through the bean attribute of the <ref/> tag is the most
general form, and allows creation of a reference to any bean in the same container or

25/08/2016 12:10

Spring Framework Reference Documentation

99 de 1194

attribute may be the same as the id attribute of the target bean, or as one of the values
in the name attribute of the target bean.
<ref bean="someBean"/>

Specifying the target bean through the parent attribute creates a reference to a bean
that is in a parent container of the current container. The value of the parent attribute
may be the same as either the id attribute of the target bean, or one of the values in the
name attribute of the target bean, and the target bean must be in a parent container of
the current one. You use this bean reference variant mainly when you have a hierarchy of
containers and you want to wrap an existing bean in a parent container with a proxy that
will have the same name as the parent bean.

<bean id="accountService" class="com.foo.SimpleAccountService">

</bean>

<bean id="accountService" 
class="org.springframework.aop.framework.ProxyFactoryBean">
<property name="target">
<ref parent="accountService"/> 
</property>

</bean>

The local attribute on the ref element is no longer supported in the 4.0
beans xsd since it does not provide value over a regular bean reference
anymore. Simply change your existing ref local references to
ref bean when upgrading to the 4.0 schema.

Inner beans
A <bean/> element inside the <property/> or <constructor-arg/> elements
defines a so-called inner bean.
<bean id="outer" class="...">

<property name="name" value="Fiona Apple"/>

25/08/2016 12:10

Spring Framework Reference Documentation

100 de 1194

<property name="age" value="25"/>

</bean>
</property>
</bean>

An inner bean definition does not require a defined id or name; if specified, the container
does not use such a value as an identifier. The container also ignores the scope flag on
creation: Inner beans are always anonymous and they are always created with the outer
bean. It is not possible to inject inner beans into collaborating beans other than into the
enclosing bean or to access them independently.
As a corner case, it is possible to receive destruction callbacks from a custom scope, e.g.
for a request-scoped inner bean contained within a singleton bean: The creation of the
inner bean instance will be tied to its containing bean, but destruction callbacks allow it to
participate in the request scopes lifecycle. This is not a common scenario; inner beans
typically simply share their containing beans scope.

Collections
In the <list/> , <set/> , <map/> , and <props/> elements, you set the properties and
arguments of the Java Collection types List , Set , Map , and Properties ,
respectively.
<bean id="moreComplexObject" class="example.ComplexObject">

<property name="adminEmails">
<props>
<prop key="administrator">[email protected]</prop>
<prop key="support">[email protected]</prop>
<prop key="development">[email protected]</prop>
</props>
</property>

<property name="someList">
<list>
<value>a list element followed by a reference</value>
<ref bean="myDataSource" />
</list>
</property>

<property name="someMap">
<map>
<entry key="an entry" value="just some string"/>
<entry key ="a ref" value-ref="myDataSource"/>
</map>

25/08/2016 12:10

Spring Framework Reference Documentation

101 de 1194

</property>

<property name="someSet">
<set>
<value>just some string</value>
<ref bean="myDataSource" />
</set>
</property>
</bean>

Collection merging
The Spring container also supports the merging of collections. An application developer
can define a parent-style <list/> , <map/> , <set/> or <props/> element, and have
child-style <list/> , <map/> , <set/> or <props/> elements inherit and override
values from the parent collection. That is, the child collections values are the result of
merging the elements of the parent and child collections, with the childs collection
elements overriding values specified in the parent collection.
This section on merging discusses the parent-child bean mechanism. Readers unfamiliar
with parent and child bean definitions may wish to read the relevant section before
continuing.
The following example demonstrates collection merging:
<beans>
<bean id="parent" abstract="true" class="example.ComplexObject">
<property name="adminEmails">
<props>
<prop key="administrator">[email protected]</prop>
<prop key="support">[email protected]</prop>
</props>
</property>
</bean>
<bean id="child" parent="parent">
<property name="adminEmails">

<props merge="true">
<prop key="sales">[email protected]</prop>
<prop key="support">[email protected]</prop>

25/08/2016 12:10

Spring Framework Reference Documentation

102 de 1194

</props>
</property>
</bean>
<beans>

Notice the use of the merge=true attribute on the <props/> element of the
adminEmails property of the child bean definition. When the child bean is resolved
and instantiated by the container, the resulting instance has an adminEmails
Properties collection that contains the result of the merging of the childs
adminEmails collection with the parents adminEmails collection.
[email protected]
[email protected]
[email protected]

The child Properties collections value set inherits all property elements from the
parent <props/> , and the childs value for the support value overrides the value in the
parent collection.
This merging behavior applies similarly to the <list/> , <map/> , and <set/> collection
types. In the specific case of the <list/> element, the semantics associated with the
List collection type, that is, the notion of an ordered collection of values, is
maintained; the parents values precede all of the child lists values. In the case of the
Map , Set , and Properties collection types, no ordering exists. Hence no ordering
semantics are in effect for the collection types that underlie the associated Map , Set ,
and Properties implementation types that the container uses internally.

Limitations of collection merging

You cannot merge different collection types (such as a Map and a List ), and if you do
attempt to do so an appropriate Exception is thrown. The merge attribute must be
specified on the lower, inherited, child definition; specifying the merge attribute on a
parent collection definition is redundant and will not result in the desired merging.

Strongly-typed collection
With the introduction of generic types in Java 5, you can use strongly typed collections.
That is, it is possible to declare a Collection type such that it can only contain String
elements (for example). If you are using Spring to dependency-inject a strongly-typed
Collection into a bean, you can take advantage of Springs type-conversion support
such that the elements of your strongly-typed Collection instances are converted to
the appropriate type prior to being added to the Collection .
public class Foo {

25/08/2016 12:10

Spring Framework Reference Documentation

103 de 1194

private Map<String, Float> accounts;

public void setAccounts(Map<String, Float> accounts) {
this.accounts = accounts;
}
}
<beans>
<bean id="foo" class="x.y.Foo">
<property name="accounts">
<map>
<entry key="one" value="9.99"/>
<entry key="two" value="2.75"/>
<entry key="six" value="3.99"/>
</map>
</property>
</bean>
</beans>

When the accounts property of the foo bean is prepared for injection, the generics
information about the element type of the strongly-typed Map<String, Float> is
available by reflection. Thus Springs type conversion infrastructure recognizes the
various value elements as being of type Float , and the string values 9.99, 2.75 , and
3.99 are converted into an actual Float type.

Null and empty string values

Spring treats empty arguments for properties and the like as empty Strings . The
following XML-based configuration metadata snippet sets the email property to the empty
String value ("").
<bean class="ExampleBean">
<property name="email" value=""/>
</bean>

The preceding example is equivalent to the following Java code:

exampleBean.setEmail("")

The <null/> element handles null values. For example:

25/08/2016 12:10

Spring Framework Reference Documentation

104 de 1194

</property>
</bean>

The above configuration is equivalent to the following Java code:

exampleBean.setEmail(null)

XML shortcut with the p-namespace

The p-namespace enables you to use the bean elements attributes, instead of nested
<property/> elements, to describe your property values and/or collaborating beans.
Spring supports extensible configuration formats with namespaces, which are based on
an XML Schema definition. The beans configuration format discussed in this chapter is
defined in an XML Schema document. However, the p-namespace is not defined in an
XSD file and exists only in the core of Spring.
The following example shows two XML snippets that resolve to the same result: The first
uses standard XML format and the second uses the p-namespace.
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean name="classic" class="com.example.ExampleBean">
<property name="email" value="[email protected]"/>
</bean>
<bean name="p-namespace" class="com.example.ExampleBean"
p:email="[email protected]"/>
</beans>

The example shows an attribute in the p-namespace called email in the bean definition.
This tells Spring to include a property declaration. As previously mentioned, the
p-namespace does not have a schema definition, so you can set the name of the attribute
to the property name.
This next example includes two more bean definitions that both have a reference to
another bean:
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"

25/08/2016 12:10

Spring Framework Reference Documentation

105 de 1194

xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean name="john-classic" class="com.example.Person">
<property name="name" value="John Doe"/>
<property name="spouse" ref="jane"/>
</bean>
<bean name="john-modern"
class="com.example.Person"
p:name="John Doe"
p:spouse-ref="jane"/>
<bean name="jane" class="com.example.Person">
<property name="name" value="Jane Doe"/>
</bean>
</beans>

As you can see, this example includes not only a property value using the p-namespace,
but also uses a special format to declare property references. Whereas the first bean
definition uses <property name="spouse" ref="jane"/> to create a reference from
bean john to bean jane , the second bean definition uses p:spouse-ref="jane" as
an attribute to do the exact same thing. In this case spouse is the property name,
whereas the -ref part indicates that this is not a straight value but rather a reference to
another bean.

The p-namespace is not as flexible as the standard XML format. For

example, the format for declaring property references clashes with
properties that end in Ref , whereas the standard XML format does not. We
recommend that you choose your approach carefully and communicate this
to your team members, to avoid producing XML documents that use all
three approaches at the same time.

XML shortcut with the c-namespace

Similar to the the section called XML shortcut with the p-namespace, the c-namespace,
newly introduced in Spring 3.1, allows usage of inlined attributes for configuring the
constructor arguments rather then nested constructor-arg elements.
Lets review the examples from the section called Constructor-based dependency
injection with the c: namespace:

25/08/2016 12:10

Spring Framework Reference Documentation

106 de 1194

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:c="http://www.springframework.org/schema/c"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="bar" class="x.y.Bar"/>
<bean id="baz" class="x.y.Baz"/>

<bean id="foo" class="x.y.Foo">
<constructor-arg ref="bar"/>
<constructor-arg ref="baz"/>
<constructor-arg value="[email protected]"/>
</bean>

<bean id="foo" class="x.y.Foo" c:bar-ref="bar" c:baz-ref="baz" c:email="
</beans>

The c: namespace uses the same conventions as the p: one (trailing -ref for bean
references) for setting the constructor arguments by their names. And just as well, it
needs to be declared even though it is not defined in an XSD schema (but it exists inside
the Spring core).
For the rare cases where the constructor argument names are not available (usually if the
bytecode was compiled without debugging information), one can use fallback to the
argument indexes:

<bean id="foo" class="x.y.Foo" c:_0-ref="bar" c:_1-ref="baz"/>

Due to the XML grammar, the index notation requires the presence of the
leading _ as XML attribute names cannot start with a number (even though
some IDE allow it).

In practice, the constructor resolution mechanism is quite efficient in matching arguments

so unless one really needs to, we recommend using the name notation through-out your
configuration.

Compound property names

You can use compound or nested property names when you set bean properties, as long

25/08/2016 12:10

Spring Framework Reference Documentation

107 de 1194

as all components of the path except the final property name are not null . Consider the
following bean definition.
<bean id="foo" class="foo.Bar">
<property name="fred.bob.sammy" value="123" />
</bean>

The foo bean has a fred property, which has a bob property, which has a sammy
property, and that final sammy property is being set to the value 123 . In order for this to
work, the fred property of foo , and the bob property of fred must not be null after
the bean is constructed, or a NullPointerException is thrown.

7.4.3 Using depends-on

If a bean is a dependency of another that usually means that one bean is set as a
property of another. Typically you accomplish this with the <ref/> element in
XML-based configuration metadata. However, sometimes dependencies between beans
are less direct; for example, a static initializer in a class needs to be triggered, such as
database driver registration. The depends-on attribute can explicitly force one or more
beans to be initialized before the bean using this element is initialized. The following
example uses the depends-on attribute to express a dependency on a single bean:
<bean id="beanOne" class="ExampleBean" depends-on="manager"/>
<bean id="manager" class="ManagerBean" />

To express a dependency on multiple beans, supply a list of bean names as the value of
the depends-on attribute, with commas, whitespace and semicolons, used as valid
delimiters:
<bean id="beanOne" class="ExampleBean" depends-on="manager,accountDao">
<property name="manager" ref="manager" />
</bean>
<bean id="manager" class="ManagerBean" />
<bean id="accountDao" class="x.y.jdbc.JdbcAccountDao" />

The depends-on attribute in the bean definition can specify both an

initialization time dependency and, in the case of singleton beans only, a
corresponding destroy time dependency. Dependent beans that define a
depends-on relationship with a given bean are destroyed first, prior to the
given bean itself being destroyed. Thus depends-on can also control

25/08/2016 12:10

Spring Framework Reference Documentation

108 de 1194

shutdown order.

7.4.4 Lazy-initialized beans

By default, ApplicationContext implementations eagerly create and configure all
singleton beans as part of the initialization process. Generally, this pre-instantiation is
desirable, because errors in the configuration or surrounding environment are discovered
immediately, as opposed to hours or even days later. When this behavior is not desirable,
you can prevent pre-instantiation of a singleton bean by marking the bean definition as
lazy-initialized. A lazy-initialized bean tells the IoC container to create a bean instance
when it is first requested, rather than at startup.
In XML, this behavior is controlled by the lazy-init attribute on the <bean/> element;
for example:
<bean id="lazy" class="com.foo.ExpensiveToCreateBean" lazy-init="true"/>
<bean name="not.lazy" class="com.foo.AnotherBean"/>

When the preceding configuration is consumed by an ApplicationContext , the bean

named lazy is not eagerly pre-instantiated when the ApplicationContext is starting
up, whereas the not.lazy bean is eagerly pre-instantiated.
However, when a lazy-initialized bean is a dependency of a singleton bean that is not
lazy-initialized, the ApplicationContext creates the lazy-initialized bean at startup,
because it must satisfy the singletons dependencies. The lazy-initialized bean is injected
into a singleton bean elsewhere that is not lazy-initialized.
You can also control lazy-initialization at the container level by using the
default-lazy-init attribute on the <beans/> element; for example:
<beans default-lazy-init="true">

</beans>

7.4.5 Autowiring collaborators

The Spring container can autowire relationships between collaborating beans. You can
allow Spring to resolve collaborators (other beans) automatically for your bean by
inspecting the contents of the ApplicationContext . Autowiring has the following
advantages:

25/08/2016 12:10

Spring Framework Reference Documentation

109 de 1194

Autowiring can significantly reduce the need to specify properties or constructor

arguments. (Other mechanisms such as a bean template discussed elsewhere in this
chapter are also valuable in this regard.)
Autowiring can update a configuration as your objects evolve. For example, if you
need to add a dependency to a class, that dependency can be satisfied automatically
without you needing to modify the configuration. Thus autowiring can be especially
useful during development, without negating the option of switching to explicit wiring
when the code base becomes more stable.
When using XML-based configuration metadata [2], you specify autowire mode for a bean
definition with the autowire attribute of the <bean/> element. The autowiring
functionality has four modes. You specify autowiring per bean and thus can choose which
ones to autowire.

Table 7.2. Autowiring modes

Mode
no

Explanation
(Default) No autowiring. Bean references must be defined via a
ref element. Changing the default setting is not recommended for
larger deployments, because specifying collaborators explicitly
gives greater control and clarity. To some extent, it documents the
structure of a system.

byName

Autowiring by property name. Spring looks for a bean with the

same name as the property that needs to be autowired. For
example, if a bean definition is set to autowire by name, and it
contains a master property (that is, it has a setMaster(..) method),
Spring looks for a bean definition named master , and uses it to
set the property.

byType

Allows a property to be autowired if exactly one bean of the

property type exists in the container. If more than one exists, a fatal
exception is thrown, which indicates that you may not use byType
autowiring for that bean. If there are no matching beans, nothing
happens; the property is not set.

constructor Analogous to byType, but applies to constructor arguments. If there

is not exactly one bean of the constructor argument type in the
container, a fatal error is raised.

25/08/2016 12:10

Spring Framework Reference Documentation

110 de 1194

With byType or constructor autowiring mode, you can wire arrays and typed-collections.
In such cases all autowire candidates within the container that match the expected type
are provided to satisfy the dependency. You can autowire strongly-typed Maps if the
expected key type is String . An autowired Maps values will consist of all bean
instances that match the expected type, and the Maps keys will contain the
corresponding bean names.
You can combine autowire behavior with dependency checking, which is performed after
autowiring completes.

Limitations and disadvantages of autowiring

Autowiring works best when it is used consistently across a project. If autowiring is not
used in general, it might be confusing to developers to use it to wire only one or two bean
definitions.
Consider the limitations and disadvantages of autowiring:
Explicit dependencies in property and constructor-arg settings always override
autowiring. You cannot autowire so-called simple properties such as primitives,
Strings , and Classes (and arrays of such simple properties). This limitation is
by-design.
Autowiring is less exact than explicit wiring. Although, as noted in the above table,
Spring is careful to avoid guessing in case of ambiguity that might have unexpected
results, the relationships between your Spring-managed objects are no longer
documented explicitly.
Wiring information may not be available to tools that may generate documentation
from a Spring container.
Multiple bean definitions within the container may match the type specified by the
setter method or constructor argument to be autowired. For arrays, collections, or
Maps, this is not necessarily a problem. However for dependencies that expect a
single value, this ambiguity is not arbitrarily resolved. If no unique bean definition is
available, an exception is thrown.
In the latter scenario, you have several options:
Abandon autowiring in favor of explicit wiring.
Avoid autowiring for a bean definition by setting its autowire-candidate attributes
to false as described in the next section.
Designate a single bean definition as the primary candidate by setting the primary

25/08/2016 12:10

Spring Framework Reference Documentation

111 de 1194

attribute of its <bean/> element to true .

Implement the more fine-grained control available with annotation-based
configuration, as described in Section 7.9, Annotation-based container
configuration.

Excluding a bean from autowiring

On a per-bean basis, you can exclude a bean from autowiring. In Springs XML format,
set the autowire-candidate attribute of the <bean/> element to false ; the container
makes that specific bean definition unavailable to the autowiring infrastructure (including
annotation style configurations such as @Autowired ).
You can also limit autowire candidates based on pattern-matching against bean names.
The top-level <beans/> element accepts one or more patterns within its
default-autowire-candidates attribute. For example, to limit autowire candidate
status to any bean whose name ends with Repository, provide a value of *Repository. To
provide multiple patterns, define them in a comma-separated list. An explicit value of
true or false for a bean definitions autowire-candidate attribute always takes
precedence, and for such beans, the pattern matching rules do not apply.
These techniques are useful for beans that you never want to be injected into other beans
by autowiring. It does not mean that an excluded bean cannot itself be configured using
autowiring. Rather, the bean itself is not a candidate for autowiring other beans.

7.4.6 Method injection

In most application scenarios, most beans in the container are singletons. When a
singleton bean needs to collaborate with another singleton bean, or a non-singleton bean
needs to collaborate with another non-singleton bean, you typically handle the
dependency by defining one bean as a property of the other. A problem arises when the
bean lifecycles are different. Suppose singleton bean A needs to use non-singleton
(prototype) bean B, perhaps on each method invocation on A. The container only creates
the singleton bean A once, and thus only gets one opportunity to set the properties. The
container cannot provide bean A with a new instance of bean B every time one is needed.
A solution is to forego some inversion of control. You can make bean A aware of the
container by implementing the ApplicationContextAware interface, and by making a
getBean("B") call to the container ask for (a typically new) bean B instance every time
bean A needs it. The following is an example of this approach:
// a class that uses a stateful Command-style class to perform some processing

25/08/2016 12:10

Spring Framework Reference Documentation

112 de 1194

package fiona.apple;
// Spring-API imports
import org.springframework.beans.BeansException;
import org.springframework.context.ApplicationContext;
import org.springframework.context.ApplicationContextAware;
public class CommandManager implements ApplicationContextAware {
private ApplicationContext applicationContext;
public Object process(Map commandState) {
// grab a new instance of the appropriate Command
Command command = createCommand();
// set the state on the (hopefully brand new) Command instance
command.setState(commandState);
return command.execute();
}
protected Command createCommand() {
// notice the Spring API dependency!
return this.applicationContext.getBean("command", Command.class);
}
public void setApplicationContext(
ApplicationContext applicationContext) throws BeansException {
this.applicationContext = applicationContext;
}
}

The preceding is not desirable, because the business code is aware of and coupled to the
Spring Framework. Method Injection, a somewhat advanced feature of the Spring IoC
container, allows this use case to be handled in a clean fashion.
You can read more about the motivation for Method Injection in this blog entry.

Lookup method injection

Lookup method injection is the ability of the container to override methods on container
managed beans, to return the lookup result for another named bean in the container. The
lookup typically involves a prototype bean as in the scenario described in the preceding
section. The Spring Framework implements this method injection by using bytecode
generation from the CGLIB library to generate dynamically a subclass that overrides the
method.

25/08/2016 12:10

Spring Framework Reference Documentation

113 de 1194

For this dynamic subclassing to work, the class that the Spring bean
container will subclass cannot be final , and the method to be
overridden cannot be final either.
Unit-testing a class that has an abstract method requires you to
subclass the class yourself and to supply a stub implementation of the
abstract method.
Concrete methods are also necessary for component scanning which
requires concrete classes to pick up.
A further key limitation is that lookup methods wont work with factory
methods and in particular not with @Bean methods in configuration
classes, since the container is not in charge of creating the instance in
that case and therefore cannot create a runtime-generated subclass on
the fly.
Finally, objects that have been the target of method injection cannot be
serialized.

Looking at the CommandManager class in the previous code snippet, you see that the
Spring container will dynamically override the implementation of the createCommand()
method. Your CommandManager class will not have any Spring dependencies, as can be
seen in the reworked example:
package fiona.apple;
// no more Spring imports!
public abstract class CommandManager {
public Object process(Object commandState) {
// grab a new instance of the appropriate Command interface
Command command = createCommand();
// set the state on the (hopefully brand new) Command instance
command.setState(commandState);
return command.execute();
}
// okay... but where is the implementation of this method?
protected abstract Command createCommand();
}

In the client class containing the method to be injected (the CommandManager in this
case), the method to be injected requires a signature of the following form:

25/08/2016 12:10

Spring Framework Reference Documentation

114 de 1194

<public|protected> [abstract] <return-type> theMethodName(no-arguments);

If the method is abstract , the dynamically-generated subclass implements the method.

Otherwise, the dynamically-generated subclass overrides the concrete method defined in
the original class. For example:

<bean id="command" class="fiona.apple.AsyncCommand" scope="prototype">

</bean>

<bean id="commandManager" class="fiona.apple.CommandManager">
<lookup-method name="createCommand" bean="command"/>
</bean>

The bean identified as commandManager calls its own method createCommand()

whenever it needs a new instance of the command bean. You must be careful to deploy
the command bean as a prototype, if that is actually what is needed. If it is deployed as a
singleton, the same instance of the command bean is returned each time.

The interested reader may also find the ServiceLocatorFactoryBean (in

the org.springframework.beans.factory.config package) to be of
use. The approach used in ServiceLocatorFactoryBean is similar to that of
another utility class, ObjectFactoryCreatingFactoryBean , but it allows
you to specify your own lookup interface as opposed to a Spring-specific
lookup interface. Consult the javadocs of these classes for additional
information.

Arbitrary method replacement

A less useful form of method injection than lookup method injection is the ability to
replace arbitrary methods in a managed bean with another method implementation.
Users may safely skip the rest of this section until the functionality is actually needed.
With XML-based configuration metadata, you can use the replaced-method element to
replace an existing method implementation with another, for a deployed bean. Consider
the following class, with a method computeValue, which we want to override:
public class MyValueCalculator {

25/08/2016 12:10

Spring Framework Reference Documentation

115 de 1194

// some real code...

}
// some other methods...
}

A class implementing the

org.springframework.beans.factory.support.MethodReplacer interface provides
the new method definition.
/**
* meant to be used to override the existing computeValue(String)
* implementation in MyValueCalculator
*/
public class ReplacementComputeValue implements MethodReplacer {
public Object reimplement(Object o, Method m, Object[] args) throws Throwable {
// get the input value, work with it, and return a computed result
String input = (String) args[0];
...
return ...;
}
}

The bean definition to deploy the original class and specify the method override would
look like this:
<bean id="myValueCalculator" class="x.y.z.MyValueCalculator">

<replaced-method name="computeValue" replacer="replacementComputeValue">
<arg-type>String</arg-type>
</replaced-method>
</bean>
<bean id="replacementComputeValue" class="a.b.c.ReplacementComputeValue"/>

You can use one or more contained <arg-type/> elements within the
<replaced-method/> element to indicate the method signature of the method being
overridden. The signature for the arguments is necessary only if the method is
overloaded and multiple variants exist within the class. For convenience, the type string
for an argument may be a substring of the fully qualified type name. For example, the
following all match java.lang.String :
java.lang.String

25/08/2016 12:10

Spring Framework Reference Documentation

116 de 1194

String
Str

Because the number of arguments is often enough to distinguish between each possible
choice, this shortcut can save a lot of typing, by allowing you to type only the shortest
string that will match an argument type.

7.5 Bean scopes

When you create a bean definition, you create a recipe for creating actual instances of
the class defined by that bean definition. The idea that a bean definition is a recipe is
important, because it means that, as with a class, you can create many object instances
from a single recipe.
You can control not only the various dependencies and configuration values that are to be
plugged into an object that is created from a particular bean definition, but also the scope
of the objects created from a particular bean definition. This approach is powerful and
flexible in that you can choose the scope of the objects you create through configuration
instead of having to bake in the scope of an object at the Java class level. Beans can be
defined to be deployed in one of a number of scopes: out of the box, the Spring
Framework supports seven scopes, five of which are available only if you use a
web-aware ApplicationContext .
The following scopes are supported out of the box. You can also create a custom scope.

Table 7.3. Bean scopes

Scope
singleton

Description
(Default) Scopes a single bean definition to a single object
instance per Spring IoC container.

prototype

Scopes a single bean definition to any number of object

instances.

request

Scopes a single bean definition to the lifecycle of a single HTTP

request; that is, each HTTP request has its own instance of a
bean created off the back of a single bean definition. Only valid
in the context of a web-aware Spring ApplicationContext .

session

Scopes a single bean definition to the lifecycle of an HTTP

Session . Only valid in the context of a web-aware Spring

25/08/2016 12:10

Spring Framework Reference Documentation

117 de 1194

Scope

Description
ApplicationContext .

globalSession Scopes a single bean definition to the lifecycle of a global HTTP

Session . Typically only valid when used in a Portlet context.
Only valid in the context of a web-aware Spring
ApplicationContext .
application

Scopes a single bean definition to the lifecycle of a

ServletContext . Only valid in the context of a web-aware
Spring ApplicationContext .

websocket

Scopes a single bean definition to the lifecycle of a WebSocket .

Only valid in the context of a web-aware Spring
ApplicationContext .

As of Spring 3.0, a thread scope is available, but is not registered by

default. For more information, see the documentation for
SimpleThreadScope . For instructions on how to register this or any other
custom scope, see the section called Using a custom scope.

7.5.1 The singleton scope

Only one shared instance of a singleton bean is managed, and all requests for beans with
an id or ids matching that bean definition result in that one specific bean instance being
returned by the Spring container.
To put it another way, when you define a bean definition and it is scoped as a singleton,
the Spring IoC container creates exactly one instance of the object defined by that bean
definition. This single instance is stored in a cache of such singleton beans, and all
subsequent requests and references for that named bean return the cached object.

25/08/2016 12:10

Spring Framework Reference Documentation

118 de 1194

Springs concept of a singleton bean differs from the Singleton pattern as defined in the
Gang of Four (GoF) patterns book. The GoF Singleton hard-codes the scope of an object
such that one and only one instance of a particular class is created per ClassLoader. The
scope of the Spring singleton is best described as per container and per bean. This
means that if you define one bean for a particular class in a single Spring container, then
the Spring container creates one and only one instance of the class defined by that bean
definition. The singleton scope is the default scope in Spring. To define a bean as a
singleton in XML, you would write, for example:
<bean id="accountService" class="com.foo.DefaultAccountService"/>

<!-- the following is equivalent, though redundant (singleton scope is the default) -<bean id="accountService" class="com.foo.DefaultAccountService" scope="singleton"

7.5.2 The prototype scope

The non-singleton, prototype scope of bean deployment results in the creation of a new
bean instance every time a request for that specific bean is made. That is, the bean is
injected into another bean or you request it through a getBean() method call on the
container. As a rule, use the prototype scope for all stateful beans and the singleton
scope for stateless beans.
The following diagram illustrates the Spring prototype scope. A data access object (DAO)
is not typically configured as a prototype, because a typical DAO does not hold any

25/08/2016 12:10

Spring Framework Reference Documentation

119 de 1194

conversational state; it was just easier for this author to reuse the core of the singleton
diagram.

The following example defines a bean as a prototype in XML:

<bean id="accountService" class="com.foo.DefaultAccountService" scope="prototype"

In contrast to the other scopes, Spring does not manage the complete lifecycle of a
prototype bean: the container instantiates, configures, and otherwise assembles a
prototype object, and hands it to the client, with no further record of that prototype
instance. Thus, although initialization lifecycle callback methods are called on all objects
regardless of scope, in the case of prototypes, configured destruction lifecycle callbacks
are not called. The client code must clean up prototype-scoped objects and release
expensive resources that the prototype bean(s) are holding. To get the Spring container
to release resources held by prototype-scoped beans, try using a custom bean
post-processor, which holds a reference to beans that need to be cleaned up.
In some respects, the Spring containers role in regard to a prototype-scoped bean is a
replacement for the Java new operator. All lifecycle management past that point must be
handled by the client. (For details on the lifecycle of a bean in the Spring container, see
Section 7.6.1, Lifecycle callbacks.)

7.5.3 Singleton beans with prototype-bean dependencies

25/08/2016 12:10

Spring Framework Reference Documentation

120 de 1194

that dependencies are resolved at instantiation time. Thus if you dependency-inject a

prototype-scoped bean into a singleton-scoped bean, a new prototype bean is
instantiated and then dependency-injected into the singleton bean. The prototype
instance is the sole instance that is ever supplied to the singleton-scoped bean.
However, suppose you want the singleton-scoped bean to acquire a new instance of the
prototype-scoped bean repeatedly at runtime. You cannot dependency-inject a prototypescoped bean into your singleton bean, because that injection occurs only once, when the
Spring container is instantiating the singleton bean and resolving and injecting its
dependencies. If you need a new instance of a prototype bean at runtime more than
once, see Section 7.4.6, Method injection

7.5.4 Request, session, global session, application, and

WebSocket scopes
The request , session , globalSession , application , and websocket scopes are
only available if you use a web-aware Spring ApplicationContext implementation
(such as XmlWebApplicationContext ). If you use these scopes with regular Spring IoC
containers such as the ClassPathXmlApplicationContext , an
IllegalStateException will be thrown complaining about an unknown bean scope.

Initial web configuration

To support the scoping of beans at the request , session , globalSession ,
application , and websocket levels (web-scoped beans), some minor initial
configuration is required before you define your beans. (This initial setup is not required
for the standard scopes, singleton and prototype .)
How you accomplish this initial setup depends on your particular Servlet environment.
If you access scoped beans within Spring Web MVC, in effect, within a request that is
processed by the Spring DispatcherServlet or DispatcherPortlet , then no special
setup is necessary: DispatcherServlet and DispatcherPortlet already expose all
relevant state.
If you use a Servlet 2.5 web container, with requests processed outside of Springs
DispatcherServlet (for example, when using JSF or Struts), you need to register the
org.springframework.web.context.request.RequestContextListener
ServletRequestListener . For Servlet 3.0+, this can be done programmatically via the
WebApplicationInitializer interface. Alternatively, or for older containers, add the
following declaration to your web applications web.xml file:

25/08/2016 12:10

Spring Framework Reference Documentation

121 de 1194

<web-app>
...
<listener>
<listener-class>
org.springframework.web.context.request.RequestContextListener
</listener-class>
</listener>
...
</web-app>

Alternatively, if there are issues with your listener setup, consider using Springs
RequestContextFilter . The filter mapping depends on the surrounding web
application configuration, so you have to change it as appropriate.

<web-app>
...
<filter>
<filter-name>requestContextFilter</filter-name>
<filter-class>org.springframework.web.filter.RequestContextFilter</filter-clas
</filter>
<filter-mapping>
<filter-name>requestContextFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
...
</web-app>

DispatcherServlet , RequestContextListener , and RequestContextFilter all do

exactly the same thing, namely bind the HTTP request object to the Thread that is
servicing that request. This makes beans that are request- and session-scoped available
further down the call chain.

Request scope
Consider the following XML configuration for a bean definition:
<bean id="loginAction" class="com.foo.LoginAction" scope="request"/>

The Spring container creates a new instance of the LoginAction bean by using the
loginAction bean definition for each and every HTTP request. That is, the
loginAction bean is scoped at the HTTP request level. You can change the internal
state of the instance that is created as much as you want, because other instances
created from the same loginAction bean definition will not see these changes in state;
they are particular to an individual request. When the request completes processing, the

25/08/2016 12:10

Spring Framework Reference Documentation

122 de 1194

bean that is scoped to the request is discarded.

When using annotation-driven components or Java Config, the @RequestScope
annotation can be used to assign a component to the request scope.
@RequestScope
@Component
public class LoginAction {
// ...
}

Session scope
Consider the following XML configuration for a bean definition:
<bean id="userPreferences" class="com.foo.UserPreferences" scope="session"/>

The Spring container creates a new instance of the UserPreferences bean by using the
userPreferences bean definition for the lifetime of a single HTTP Session . In other
words, the userPreferences bean is effectively scoped at the HTTP Session level. As
with request-scoped beans, you can change the internal state of the instance that is
created as much as you want, knowing that other HTTP Session instances that are also
using instances created from the same userPreferences bean definition do not see
these changes in state, because they are particular to an individual HTTP Session .
When the HTTP Session is eventually discarded, the bean that is scoped to that
particular HTTP Session is also discarded.
When using annotation-driven components or Java Config, the @SessionScope
annotation can be used to assign a component to the session scope.
@SessionScope
@Component
public class UserPreferences {
// ...
}

Global session scope

Consider the following bean definition:
<bean id="userPreferences" class="com.foo.UserPreferences" scope="globalSession"

The globalSession scope is similar to the standard HTTP Session scope (described

25/08/2016 12:10

Spring Framework Reference Documentation

123 de 1194

specification defines the notion of a global Session that is shared among all portlets that
make up a single portlet web application. Beans defined at the globalSession scope
are scoped (or bound) to the lifetime of the global portlet Session .
If you write a standard Servlet-based web application and you define one or more beans
as having globalSession scope, the standard HTTP Session scope is used, and no
error is raised.

Application scope
Consider the following XML configuration for a bean definition:
<bean id="appPreferences" class="com.foo.AppPreferences" scope="application"

The Spring container creates a new instance of the AppPreferences bean by using the
appPreferences bean definition once for the entire web application. That is, the
appPreferences bean is scoped at the ServletContext level, stored as a regular
ServletContext attribute. This is somewhat similar to a Spring singleton bean but
differs in two important ways: It is a singleton per ServletContext , not per Spring
'ApplicationContext' (for which there may be several in any given web application), and it
is actually exposed and therefore visible as a ServletContext attribute.
When using annotation-driven components or Java Config, the @ApplicationScope
annotation can be used to assign a component to the application scope.
@ApplicationScope
@Component
public class AppPreferences {
// ...
}

Scoped beans as dependencies

The Spring IoC container manages not only the instantiation of your objects (beans), but
also the wiring up of collaborators (or dependencies). If you want to inject (for example)
an HTTP request scoped bean into another bean of a longer-lived scope, you may
choose to inject an AOP proxy in place of the scoped bean. That is, you need to inject a
proxy object that exposes the same public interface as the scoped object but that can
also retrieve the real target object from the relevant scope (such as an HTTP request)
and delegate method calls onto the real object.

25/08/2016 12:10

Spring Framework Reference Documentation

124 de 1194

You may also use <aop:scoped-proxy/> between beans that are scoped
as singleton , with the reference then going through an intermediate
proxy that is serializable and therefore able to re-obtain the target singleton
bean on deserialization.
When declaring <aop:scoped-proxy/> against a bean of scope
prototype , every method call on the shared proxy will lead to the creation
of a new target instance which the call is then being forwarded to.
Also, scoped proxies are not the only way to access beans from shorter
scopes in a lifecycle-safe fashion. You may also simply declare your
injection point (i.e. the constructor/setter argument or autowired field) as
ObjectFactory<MyTargetBean> , allowing for a getObject() call to
retrieve the current instance on demand every time it is needed - without
holding on to the instance or storing it separately.
The JSR-330 variant of this is called Provider , used with a
Provider<MyTargetBean> declaration and a corresponding get() call
for every retrieval attempt. See here for more details on JSR-330 overall.

The configuration in the following example is only one line, but it is important to
understand the "why" as well as the "how" behind it.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:aop="http://www.springframework.org/schema/aop"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop.xsd">

<bean id="userPreferences" class="com.foo.UserPreferences" scope="session"

<aop:scoped-proxy/>
</bean>

<bean id="userService" class="com.foo.SimpleUserService">

<property name="userPreferences" ref="userPreferences"/>
</bean>
</beans>

25/08/2016 12:10

Spring Framework Reference Documentation

125 de 1194

bean definition (see the section called Choosing the type of proxy to create and
Chapter 41, XML Schema-based configuration). Why do definitions of beans scoped at
the request , session , globalSession and custom-scope levels require the
<aop:scoped-proxy/> element? Lets 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).
<bean id="userPreferences" class="com.foo.UserPreferences" scope="session"/>
<bean id="userManager" class="com.foo.UserManager">
<property name="userPreferences" ref="userPreferences"/>
</bean>

In the preceding example, the singleton bean userManager is injected with a reference
to the HTTP Session -scoped bean userPreferences . The salient point here is that
the userManager bean is a singleton: it will be instantiated exactly once per container,
and its dependencies (in this case only one, the userPreferences bean) are also
injected only once. This means that the userManager bean will only operate on the
exact same userPreferences object, that is, the one that it was originally injected with.
This is not the behavior you want when injecting a shorter-lived scoped bean into a
longer-lived scoped bean, for example injecting an HTTP Session -scoped collaborating
bean as a dependency into singleton bean. Rather, you need a single userManager
object, and for the lifetime of an HTTP Session , you need a userPreferences object
that is specific to said HTTP Session . Thus the container creates an object that exposes
the exact same public interface as the UserPreferences class (ideally an object that is
a UserPreferences instance) which can fetch the real UserPreferences object from
the scoping mechanism (HTTP request, Session , etc.). The container injects this proxy
object into the userManager bean, which is unaware that this UserPreferences
reference is a proxy. In this example, when a UserManager instance invokes a method
on the dependency-injected UserPreferences object, it actually is invoking a method on
the proxy. The proxy then fetches the real UserPreferences object from (in this case)
the HTTP Session , and delegates the method invocation onto the retrieved real
UserPreferences object.
Thus you need the following, correct and complete, configuration when injecting
request- , session- , and globalSession-scoped beans into collaborating objects:
<bean id="userPreferences" class="com.foo.UserPreferences" scope="session">
<aop:scoped-proxy/>
</bean>

25/08/2016 12:10

Spring Framework Reference Documentation

126 de 1194

<bean id="userManager" class="com.foo.UserManager">

Choosing the type of proxy to create

By default, when the Spring container creates a proxy for a bean that is marked up with
the <aop:scoped-proxy/> element, a CGLIB-based class proxy is created.

CGLIB proxies only intercept public method calls! Do not call non-public
methods on such a proxy; they will not be delegated to the actual scoped
target object.

Alternatively, you can configure the Spring container to create standard JDK
interface-based proxies for such scoped beans, by specifying false for the value of the
proxy-target-class attribute of the <aop:scoped-proxy/> element. Using JDK
interface-based proxies means that you do not need additional libraries in your
application classpath to effect such proxying. However, it also means that the class of the
scoped bean must implement at least one interface, and that all collaborators into which
the scoped bean is injected must reference the bean through one of its interfaces.

<bean id="userPreferences" class="com.foo.DefaultUserPreferences" scope="session"
<aop:scoped-proxy proxy-target-class="false"/>
</bean>
<bean id="userManager" class="com.foo.UserManager">
<property name="userPreferences" ref="userPreferences"/>
</bean>

For more detailed information about choosing class-based or interface-based proxying,

see Section 11.6, Proxying mechanisms.

7.5.5 Custom scopes

The bean scoping mechanism is extensible; You can define your own scopes, or even
redefine existing scopes, although the latter is considered bad practice and you cannot
override the built-in singleton and prototype scopes.

Creating a custom scope

25/08/2016 12:10

Spring Framework Reference Documentation

127 de 1194

To integrate your custom scope(s) into the Spring container, you need to implement the
org.springframework.beans.factory.config.Scope interface, which is described in
this section. For an idea of how to implement your own scopes, see the Scope
implementations that are supplied with the Spring Framework itself and the Scope
javadocs, which explains the methods you need to implement in more detail.
The Scope interface has four methods to get objects from the scope, remove them from
the scope, and allow them to be destroyed.
The following method returns the object from the underlying scope. The session scope
implementation, for example, returns the session-scoped bean (and if it does not exist,
the method returns a new instance of the bean, after having bound it to the session for
future reference).
Object get(String name, ObjectFactory objectFactory)

The following method removes the object from the underlying scope. The session scope
implementation for example, removes the session-scoped bean from the underlying
session. The object should be returned, but you can return null if the object with the
specified name is not found.
Object remove(String name)

The following method registers the callbacks the scope should execute when it is
destroyed or when the specified object in the scope is destroyed. Refer to the javadocs or
a Spring scope implementation for more information on destruction callbacks.
void registerDestructionCallback(String name, Runnable destructionCallback)

The following method obtains the conversation identifier for the underlying scope. This
identifier is different for each scope. For a session scoped implementation, this identifier
can be the session identifier.
String getConversationId()

Using a custom scope

After you write and test one or more custom Scope implementations, you need to make
the Spring container aware of your new scope(s). The following method is the central
method to register a new Scope with the Spring container:
void registerScope(String scopeName, Scope scope);

25/08/2016 12:10

Spring Framework Reference Documentation

128 de 1194

This method is declared on the ConfigurableBeanFactory interface, which is available

on most of the concrete ApplicationContext implementations that ship with Spring via
the BeanFactory property.
The first argument to the registerScope(..) method is the unique name associated
with a scope; examples of such names in the Spring container itself are singleton and
prototype . The second argument to the registerScope(..) method is an actual
instance of the custom Scope implementation that you wish to register and use.
Suppose that you write your custom Scope implementation, and then register it as below.

The example below uses SimpleThreadScope which is included with

Spring, but not registered by default. The instructions would be the same for
your own custom Scope implementations.

Scope threadScope = new SimpleThreadScope();

beanFactory.registerScope("thread", threadScope);

You then create bean definitions that adhere to the scoping rules of your custom Scope :
<bean id="..." class="..." scope="thread">

With a custom Scope implementation, you are not limited to programmatic registration of
the scope. You can also do the Scope registration declaratively, using the
CustomScopeConfigurer class:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:aop="http://www.springframework.org/schema/aop"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop.xsd">

25/08/2016 12:10

Spring Framework Reference Documentation

129 de 1194

</bean>
<bean id="bar" class="x.y.Bar" scope="thread">
<property name="name" value="Rick"/>
<aop:scoped-proxy/>
</bean>
<bean id="foo" class="x.y.Foo">
<property name="bar" ref="bar"/>
</bean>
</beans>

When you place <aop:scoped-proxy/> in a FactoryBean

implementation, it is the factory bean itself that is scoped, not the object
returned from getObject() .

7.6 Customizing the nature of a bean

7.6.1 Lifecycle callbacks
To interact with the containers management of the bean lifecycle, you can implement the
Spring InitializingBean and DisposableBean interfaces. The container calls
afterPropertiesSet() for the former and destroy() for the latter to allow the bean
to perform certain actions upon initialization and destruction of your beans.

The JSR-250 @PostConstruct and @PreDestroy annotations are

generally considered best practice for receiving lifecycle callbacks in a
modern Spring application. Using these annotations means that your beans
are not coupled to Spring specific interfaces. For details see Section 7.9.8,
@PostConstruct and @PreDestroy.
If you dont want to use the JSR-250 annotations but you are still looking to
remove coupling consider the use of init-method and destroy-method object
definition metadata.

Internally, the Spring Framework uses BeanPostProcessor implementations to process

any callback interfaces it can find and call the appropriate methods. If you need custom
features or other lifecycle behavior Spring does not offer out-of-the-box, you can

25/08/2016 12:10

Spring Framework Reference Documentation

130 de 1194

implement a BeanPostProcessor yourself. For more information, see Section 7.8,

Container Extension Points.
In addition to the initialization and destruction callbacks, Spring-managed objects may
also implement the Lifecycle interface so that those objects can participate in the
startup and shutdown process as driven by the containers own lifecycle.
The lifecycle callback interfaces are described in this section.

Initialization callbacks
The org.springframework.beans.factory.InitializingBean interface allows a
bean to perform initialization work after all necessary properties on the bean have been
set by the container. The InitializingBean interface specifies a single method:
void afterPropertiesSet() throws Exception;

It is recommended that you do not use the InitializingBean interface because it

unnecessarily couples the code to Spring. Alternatively, use the @PostConstruct
annotation or specify a POJO initialization method. In the case of XML-based
configuration metadata, you use the init-method attribute to specify the name of the
method that has a void no-argument signature. With Java config, you use the
initMethod attribute of @Bean , see the section called Receiving lifecycle callbacks.
For example, the following:
<bean id="exampleInitBean" class="examples.ExampleBean" init-method="init"/>
public class ExampleBean {
public void init() {
// do some initialization work
}
}

is exactly the same as

<bean id="exampleInitBean" class="examples.AnotherExampleBean"/>
public class AnotherExampleBean implements InitializingBean {
public void afterPropertiesSet() {
// do some initialization work

25/08/2016 12:10

Spring Framework Reference Documentation

131 de 1194

but does not couple the code to Spring.

Destruction callbacks
Implementing the org.springframework.beans.factory.DisposableBean interface
allows a bean to get a callback when the container containing it is destroyed. The
DisposableBean interface specifies a single method:
void destroy() throws Exception;

It is recommended that you do not use the DisposableBean callback interface because
it unnecessarily couples the code to Spring. Alternatively, use the @PreDestroy
annotation or specify a generic method that is supported by bean definitions. With
XML-based configuration metadata, you use the destroy-method attribute on the
<bean/> . With Java config, you use the destroyMethod attribute of @Bean , see the
section called Receiving lifecycle callbacks. For example, the following definition:
<bean id="exampleInitBean" class="examples.ExampleBean" destroy-method="cleanup"
public class ExampleBean {
public void cleanup() {
// do some destruction work (like releasing pooled connections)
}
}

is exactly the same as:

<bean id="exampleInitBean" class="examples.AnotherExampleBean"/>
public class AnotherExampleBean implements DisposableBean {
public void destroy() {
// do some destruction work (like releasing pooled connections)
}
}

but does not couple the code to Spring.

25/08/2016 12:10

Spring Framework Reference Documentation

132 de 1194

The destroy-method attribute of a <bean> element can be assigned a

special (inferred) value which instructs Spring to automatically detect a
public close or shutdown method on the specific bean class (any class
that implements java.lang.AutoCloseable or java.io.Closeable
would therefore match). This special (inferred) value can also be set on
the default-destroy-method attribute of a <beans> element to apply
this behavior to an entire set of beans (see the section called Default
initialization and destroy methods). Note that this is the default behavior
with Java config.

Default initialization and destroy methods

When you write initialization and destroy method callbacks that do not use the Springspecific InitializingBean and DisposableBean callback interfaces, you typically
write methods with names such as init() , initialize() , dispose() , and so on.
Ideally, the names of such lifecycle callback methods are standardized across a project
so that all developers use the same method names and ensure consistency.
You can configure the Spring container to look for named initialization and destroy
callback method names on every bean. This means that you, as an application developer,
can write your application classes and use an initialization callback called init() ,
without having to configure an init-method="init" attribute with each bean definition.
The Spring IoC container calls that method when the bean is created (and in accordance
with the standard lifecycle callback contract described previously). This feature also
enforces a consistent naming convention for initialization and destroy method callbacks.
Suppose that your initialization callback methods are named init() and destroy
callback methods are named destroy() . Your class will resemble the class in the
following example.
public class DefaultBlogService implements BlogService {
private BlogDao blogDao;
public void setBlogDao(BlogDao blogDao) {
this.blogDao = blogDao;
}
// this is (unsurprisingly) the initialization callback method
public void init() {
if (this.blogDao == null) {

25/08/2016 12:10

Spring Framework Reference Documentation

133 de 1194

throw new IllegalStateException("The [blogDao] property must be set."

}
}
}
<beans default-init-method="init">
<bean id="blogService" class="com.foo.DefaultBlogService">
<property name="blogDao" ref="blogDao" />
</bean>
</beans>

The presence of the default-init-method attribute on the top-level <beans/>

element attribute causes the Spring IoC container to recognize a method called init on
beans as the initialization method callback. When a bean is created and assembled, if the
bean class has such a method, it is invoked at the appropriate time.
You configure destroy method callbacks similarly (in XML, that is) by using the
default-destroy-method attribute on the top-level <beans/> element.
Where existing bean classes already have callback methods that are named at variance
with the convention, you can override the default by specifying (in XML, that is) the
method name using the init-method and destroy-method attributes of the <bean/>
itself.
The Spring container guarantees that a configured initialization callback is called
immediately after a bean is supplied with all dependencies. Thus the initialization callback
is called on the raw bean reference, which means that AOP interceptors and so forth are
not yet applied to the bean. A target bean is fully created first, then an AOP proxy (for
example) with its interceptor chain is applied. If the target bean and the proxy are defined
separately, your code can even interact with the raw target bean, bypassing the proxy.
Hence, it would be inconsistent to apply the interceptors to the init method, because
doing so would couple the lifecycle of the target bean with its proxy/interceptors and leave
strange semantics when your code interacts directly to the raw target bean.

Combining lifecycle mechanisms

As of Spring 2.5, you have three options for controlling bean lifecycle behavior: the
InitializingBean and DisposableBean callback interfaces; custom init() and
destroy() methods; and the @PostConstruct and @PreDestroy annotations. You
can combine these mechanisms to control a given bean.

25/08/2016 12:10

Spring Framework Reference Documentation

134 de 1194

If multiple lifecycle mechanisms are configured for a bean, and each

mechanism is configured with a different method name, then each
configured method is executed in the order listed below. However, if the
same method name is configured - for example, init() for an initialization
method - for more than one of these lifecycle mechanisms, that method is
executed once, as explained in the preceding section.

Multiple lifecycle mechanisms configured for the same bean, with different initialization
methods, are called as follows:
Methods annotated with @PostConstruct
afterPropertiesSet() as defined by the InitializingBean callback interface
A custom configured init() method
Destroy methods are called in the same order:
Methods annotated with @PreDestroy
destroy() as defined by the DisposableBean callback interface
A custom configured destroy() method

Startup and shutdown callbacks

The Lifecycle interface defines the essential methods for any object that has its own
lifecycle requirements (e.g. starts and stops some background process):
public interface Lifecycle {
void start();
void stop();
boolean isRunning();
}

Any Spring-managed object may implement that interface. Then, when the
ApplicationContext itself receives start and stop signals, e.g. for a stop/restart
scenario at runtime, it will cascade those calls to all Lifecycle implementations defined
within that context. It does this by delegating to a LifecycleProcessor :
public interface LifecycleProcessor extends Lifecycle {

25/08/2016 12:10

Spring Framework Reference Documentation

135 de 1194

void onRefresh();
void onClose();
}

Notice that the LifecycleProcessor is itself an extension of the Lifecycle interface.

It also adds two other methods for reacting to the context being refreshed and closed.

Note that the regular org.springframework.context.Lifecycle

interface is just a plain contract for explicit start/stop notifications and does
NOT imply auto-startup at context refresh time. Consider implementing
org.springframework.context.SmartLifecycle instead for
fine-grained control over auto-startup of a specific bean (including startup
phases). Also, please note that stop notifications are not guaranteed to
come before destruction: On regular shutdown, all Lifecycle beans will
first receive a stop notification before the general destruction callbacks are
being propagated; however, on hot refresh during a contexts lifetime or on
aborted refresh attempts, only destroy methods will be called.

The order of startup and shutdown invocations can be important. If a "depends-on"

relationship exists between any two objects, the dependent side will start after its
dependency, and it will stop before its dependency. However, at times the direct
dependencies are unknown. You may only know that objects of a certain type should start
prior to objects of another type. In those cases, the SmartLifecycle interface defines
another option, namely the getPhase() method as defined on its super-interface,
Phased .
public interface Phased {
int getPhase();
}
public interface SmartLifecycle extends Lifecycle, Phased {
boolean isAutoStartup();
void stop(Runnable callback);
}

25/08/2016 12:10

Spring Framework Reference Documentation

136 de 1194

When starting, the objects with the lowest phase start first, and when stopping, the
reverse order is followed. Therefore, an object that implements SmartLifecycle and
whose getPhase() method returns Integer.MIN_VALUE would be among the first to
start and the last to stop. At the other end of the spectrum, a phase value of
Integer.MAX_VALUE would indicate that the object should be started last and stopped
first (likely because it depends on other processes to be running). When considering the
phase value, its also important to know that the default phase for any "normal"
Lifecycle object that does not implement SmartLifecycle would be 0. Therefore,
any negative phase value would indicate that an object should start before those standard
components (and stop after them), and vice versa for any positive phase value.
As you can see the stop method defined by SmartLifecycle accepts a callback. Any
implementation must invoke that callbacks run() method after that implementations
shutdown process is complete. That enables asynchronous shutdown where necessary
since the default implementation of the LifecycleProcessor interface,
DefaultLifecycleProcessor , will wait up to its timeout value for the group of objects
within each phase to invoke that callback. The default per-phase timeout is 30 seconds.
You can override the default lifecycle processor instance by defining a bean named
"lifecycleProcessor" within the context. If you only want to modify the timeout, then
defining the following would be sufficient:

<bean id="lifecycleProcessor" class="org.springframework.context.support.DefaultLifecy

<property name="timeoutPerShutdownPhase" value="10000"/>
</bean>

As mentioned, the LifecycleProcessor interface defines callback methods for the

refreshing and closing of the context as well. The latter will simply drive the shutdown
process as if stop() had been called explicitly, but it will happen when the context is
closing. The 'refresh' callback on the other hand enables another feature of
SmartLifecycle beans. When the context is refreshed (after all objects have been
instantiated and initialized), that callback will be invoked, and at that point the default
lifecycle processor will check the boolean value returned by each SmartLifecycle
objects isAutoStartup() method. If "true", then that object will be started at that point
rather than waiting for an explicit invocation of the contexts or its own start() method
(unlike the context refresh, the context start does not happen automatically for a standard
context implementation). The "phase" value as well as any "depends-on" relationships will
determine the startup order in the same way as described above.

Shutting down the Spring IoC container gracefully in non-web

25/08/2016 12:10

Spring Framework Reference Documentation

137 de 1194

This section applies only to non-web applications. Springs web-based

ApplicationContext implementations already have code in place to shut
down the Spring IoC container gracefully when the relevant web application
is shut down.

If you are using Springs IoC container in a non-web application environment; for
example, in a rich client desktop environment; you register a shutdown hook with the
JVM. Doing so ensures a graceful shutdown and calls the relevant destroy methods on
your singleton beans so that all resources are released. Of course, you must still
configure and implement these destroy callbacks correctly.
To register a shutdown hook, you call the registerShutdownHook() method that is
declared on the ConfigurableApplicationContext interface:
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
public final class Boot {
public static void main(final String[] args) throws Exception {
ConfigurableApplicationContext ctx = new ClassPathXmlApplicationContext(
new String []{"beans.xml"});
// add a shutdown hook for the above context...
ctx.registerShutdownHook();
// app runs here...
// main method exits, hook is called prior to the app shutting down...
}
}

7.6.2 ApplicationContextAware and BeanNameAware

When an ApplicationContext creates an object instance that implements the
org.springframework.context.ApplicationContextAware interface, the instance is
provided with a reference to that ApplicationContext .
public interface ApplicationContextAware {

25/08/2016 12:10

Spring Framework Reference Documentation

138 de 1194

void setApplicationContext(ApplicationContext applicationContext) throws

}

Thus beans can manipulate programmatically the ApplicationContext that created

them, through the ApplicationContext interface, or by casting the reference to a
known subclass of this interface, such as ConfigurableApplicationContext , which
exposes additional functionality. One use would be the programmatic retrieval of other
beans. Sometimes this capability is useful; however, in general you should avoid it,
because it couples the code to Spring and does not follow the Inversion of Control style,
where collaborators are provided to beans as properties. Other methods of the
ApplicationContext provide access to file resources, publishing application events,
and accessing a MessageSource . These additional features are described in
Section 7.15, Additional Capabilities of the ApplicationContext
As of Spring 2.5, autowiring is another alternative to obtain reference to the
ApplicationContext . The "traditional" constructor and byType autowiring modes
(as described in Section 7.4.5, Autowiring collaborators) can provide a dependency of
type ApplicationContext for a constructor argument or setter method parameter,
respectively. For more flexibility, including the ability to autowire fields and multiple
parameter methods, use the new annotation-based autowiring features. If you do, the
ApplicationContext is autowired into a field, constructor argument, or method
parameter that is expecting the ApplicationContext type if the field, constructor, or
method in question carries the @Autowired annotation. For more information, see
Section 7.9.2, @Autowired.
When an ApplicationContext creates a class that implements the
org.springframework.beans.factory.BeanNameAware interface, the class is
provided with a reference to the name defined in its associated object definition.
public interface BeanNameAware {
void setBeanName(String name) throws BeansException;
}

The callback is invoked after population of normal bean properties but before an
initialization callback such as InitializingBean afterPropertiesSet or a custom
init-method.

7.6.3 Other Aware interfaces

25/08/2016 12:10

Spring Framework Reference Documentation

139 de 1194

Besides ApplicationContextAware and BeanNameAware discussed above, Spring

offers a range of Aware interfaces that allow beans to indicate to the container that they
require a certain infrastructure dependency. The most important Aware interfaces are
summarized below - as a general rule, the name is a good indication of the dependency
type:

Table 7.4. Aware interfaces

Name

Injected

Explained in

Dependency
ApplicationContextAware

Declaring

Section 7.6.2,

ApplicationContext

ApplicationContextAware
and BeanNameAware

ApplicationEventPublisherAware

BeanClassLoaderAware

BeanFactoryAware

Event publisher of the

Section 7.15, Additional

enclosing

Capabilities of the

ApplicationContext

Class loader used to

Section 7.3.2,

load the bean classes.

Instantiating beans

Declaring

Section 7.6.2,

BeanFactory

ApplicationContextAware
and BeanNameAware

BeanNameAware

Name of the declaring

Section 7.6.2,

bean

ApplicationContextAware
and BeanNameAware

BootstrapContextAware

Resource adapter

Chapter 32, JCA CCI

BootstrapContext
the container runs in.
Typically available only
in JCA aware
ApplicationContext s
LoadTimeWeaverAware

Defined weaver for

Section 11.8.4,

processing class

Load-time weaving with

definition at load time

AspectJ in the Spring

Framework

25/08/2016 12:10

Spring Framework Reference Documentation

140 de 1194

Name

Injected

Explained in

Dependency
MessageSourceAware

Configured strategy for

Section 7.15, Additional

resolving messages

Capabilities of the

(with support for

ApplicationContext

parametrization and
internationalization)
NotificationPublisherAware

PortletConfigAware

Spring JMX notification

Section 31.7,

publisher

Notifications

Current

Chapter 25, Portlet MVC

PortletConfig the

Framework

container runs in. Valid

only in a web-aware
Spring
ApplicationContext
PortletContextAware

Current

Chapter 25, Portlet MVC

PortletContext the

Framework

container runs in. Valid

only in a web-aware
Spring
ApplicationContext
ResourceLoaderAware

Configured loader for

Chapter 8, Resources

low-level access to
resources
ServletConfigAware

Current

Chapter 22, Web MVC

ServletConfig the

framework

container runs in. Valid

only in a web-aware
Spring
ApplicationContext
ServletContextAware

Current

Chapter 22, Web MVC

ServletContext the

framework

container runs in. Valid

only in a web-aware
Spring
ApplicationContext

25/08/2016 12:10

Spring Framework Reference Documentation

141 de 1194

Note again that usage of these interfaces ties your code to the Spring API and does not
follow the Inversion of Control style. As such, they are recommended for infrastructure
beans that require programmatic access to the container.

7.7 Bean definition inheritance

A bean definition can contain a lot of configuration information, including constructor
arguments, property values, and container-specific information such as initialization
method, static factory method name, and so on. A child bean definition inherits
configuration data from a parent definition. The child definition can override some values,
or add others, as needed. Using parent and child bean definitions can save a lot of typing.
Effectively, this is a form of templating.
If you work with an ApplicationContext interface programmatically, child bean
definitions are represented by the ChildBeanDefinition class. Most users do not work
with them on this level, instead configuring bean definitions declaratively in something like
the ClassPathXmlApplicationContext . When you use XML-based configuration
metadata, you indicate a child bean definition by using the parent attribute, specifying
the parent bean as the value of this attribute.
<bean id="inheritedTestBean" abstract="true"
class="org.springframework.beans.TestBean">
<property name="name" value="parent"/>
<property name="age" value="1"/>
</bean>
<bean id="inheritsWithDifferentClass"
class="org.springframework.beans.DerivedTestBean"
parent="inheritedTestBean" init-method="initialize">
<property name="name" value="override"/>

</bean>

A child bean definition uses the bean class from the parent definition if none is specified,
but can also override it. In the latter case, the child bean class must be compatible with
the parent, that is, it must accept the parents property values.
A child bean definition inherits scope, constructor argument values, property values, and
method overrides from the parent, with the option to add new values. Any scope,
initialization method, destroy method, and/or static factory method settings that you

25/08/2016 12:10

Spring Framework Reference Documentation

142 de 1194

The remaining settings are always taken from the child definition: depends on, autowire
mode, dependency check, singleton, lazy init.
The preceding example explicitly marks the parent bean definition as abstract by using
the abstract attribute. If the parent definition does not specify a class, explicitly marking
the parent bean definition as abstract is required, as follows:
<bean id="inheritedTestBeanWithoutClass" abstract="true">
<property name="name" value="parent"/>
<property name="age" value="1"/>
</bean>
<bean id="inheritsWithClass" class="org.springframework.beans.DerivedTestBean"
parent="inheritedTestBeanWithoutClass" init-method="initialize">
<property name="name" value="override"/>

</bean>

The parent bean cannot be instantiated on its own because it is incomplete, and it is also
explicitly marked as abstract . When a definition is abstract like this, it is usable only
as a pure template bean definition that serves as a parent definition for child definitions.
Trying to use such an abstract parent bean on its own, by referring to it as a ref
property of another bean or doing an explicit getBean() call with the parent bean id,
returns an error. Similarly, the containers internal preInstantiateSingletons()
method ignores bean definitions that are defined as abstract.

ApplicationContext pre-instantiates all singletons by default. Therefore,

it is important (at least for singleton beans) that if you have a (parent) bean
definition which you intend to use only as a template, and this definition
specifies a class, you must make sure to set the abstract attribute to true,
otherwise the application context will actually (attempt to) pre-instantiate the
abstract bean.

7.8 Container Extension Points

Typically, an application developer does not need to subclass ApplicationContext
implementation classes. Instead, the Spring IoC container can be extended by plugging in
implementations of special integration interfaces. The next few sections describe these
integration interfaces.

25/08/2016 12:10

Spring Framework Reference Documentation

143 de 1194

7.8.1 Customizing beans using a BeanPostProcessor

The BeanPostProcessor interface defines callback methods that you can implement to
provide your own (or override the containers default) instantiation logic, dependencyresolution logic, and so forth. If you want to implement some custom logic after the Spring
container finishes instantiating, configuring, and initializing a bean, you can plug in one or
more BeanPostProcessor implementations.
You can configure multiple BeanPostProcessor instances, and you can control the
order in which these BeanPostProcessor s execute by setting the order property. You
can set this property only if the BeanPostProcessor implements the Ordered interface;
if you write your own BeanPostProcessor you should consider implementing the
Ordered interface too. For further details, consult the javadocs of the
BeanPostProcessor and Ordered interfaces. See also the note below on
programmatic registration of BeanPostProcessor s.

BeanPostProcessor s operate on bean (or object) instances; that is to say,

the Spring IoC container instantiates a bean instance and then
BeanPostProcessor s do their work.
BeanPostProcessor s are scoped per-container. This is only relevant if
you are using container hierarchies. If you define a BeanPostProcessor in
one container, it will only post-process the beans in that container. In other
words, beans that are defined in one container are not post-processed by a
BeanPostProcessor defined in another container, even if both containers
are part of the same hierarchy.
To change the actual bean definition (i.e., the blueprint that defines the
bean), you instead need to use a BeanFactoryPostProcessor as
described in Section 7.8.2, Customizing configuration metadata with a
BeanFactoryPostProcessor.

The org.springframework.beans.factory.config.BeanPostProcessor interface

consists of exactly two callback methods. When such a class is registered as a
post-processor with the container, for each bean instance that is created by the container,
the post-processor gets a callback from the container both before container initialization
methods (such as InitializingBeans afterPropertiesSet() and any declared init method)
are called as well as after any bean initialization callbacks. The post-processor can take
any action with the bean instance, including ignoring the callback completely. A bean
post-processor typically checks for callback interfaces or may wrap a bean with a proxy.
Some Spring AOP infrastructure classes are implemented as bean post-processors in

25/08/2016 12:10

Spring Framework Reference Documentation

144 de 1194

An ApplicationContext automatically detects any beans that are defined in the

configuration metadata which implement the BeanPostProcessor interface. The
ApplicationContext registers these beans as post-processors so that they can be
called later upon bean creation. Bean post-processors can be deployed in the container
just like any other beans.
Note that when declaring a BeanPostProcessor using an @Bean factory method on a
configuration class, the return type of the factory method should be the implementation
class itself or at least the
org.springframework.beans.factory.config.BeanPostProcessor interface,
clearly indicating the post-processor nature of that bean. Otherwise, the
ApplicationContext wont be able to autodetect it by type before fully creating it. Since
a BeanPostProcessor needs to be instantiated early in order to apply to the initialization
of other beans in the context, this early type detection is critical.

While the recommended approach for BeanPostProcessor registration is

through ApplicationContext auto-detection (as described above), it is
also possible to register them programmatically against a
ConfigurableBeanFactory using the addBeanPostProcessor method.
This can be useful when needing to evaluate conditional logic before
registration, or even for copying bean post processors across contexts in a
hierarchy. Note however that BeanPostProcessor s added
programmatically do not respect the Ordered interface. Here it is the order
of registration that dictates the order of execution. Note also that
BeanPostProcessor s registered programmatically are always processed
before those registered through auto-detection, regardless of any explicit
ordering.

Classes that implement the BeanPostProcessor interface are special and

are treated differently by the container. All BeanPostProcessor s and
beans that they reference directly are instantiated on startup, as part of the
special startup phase of the ApplicationContext . Next, all
BeanPostProcessor s are registered in a sorted fashion and applied to all
further beans in the container. Because AOP auto-proxying is implemented
as a BeanPostProcessor itself, neither BeanPostProcessor s nor the
beans they reference directly are eligible for auto-proxying, and thus do not
have aspects woven into them.
For any such bean, you should see an informational log message: "Bean

25/08/2016 12:10

Spring Framework Reference Documentation

145 de 1194

foo is not eligible for getting processed by all BeanPostProcessor interfaces

(for example: not eligible for auto-proxying)".
Note that if you have beans wired into your BeanPostProcessor using
autowiring or @Resource (which may fall back to autowiring), Spring might
access unexpected beans when searching for type-matching dependency
candidates, and therefore make them ineligible for auto-proxying or other
kinds of bean post-processing. For example, if you have a dependency
annotated with @Resource where the field/setter name does not directly
correspond to the declared name of a bean and no name attribute is used,
then Spring will access other beans for matching them by type.

The following examples show how to write, register, and use BeanPostProcessor s in an
ApplicationContext .

Example: Hello World, BeanPostProcessor-style

This first example illustrates basic usage. The example shows a custom
BeanPostProcessor implementation that invokes the toString() method of each
bean as it is created by the container and prints the resulting string to the system console.
Find below the custom BeanPostProcessor implementation class definition:
package scripting;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.beans.BeansException;
public class InstantiationTracingBeanPostProcessor implements BeanPostProcessor {
// simply return the instantiated bean as-is
public Object postProcessBeforeInitialization(Object bean,
String beanName) throws BeansException {
return bean; // we could potentially return any object reference here...
}
public Object postProcessAfterInitialization(Object bean,
String beanName) throws BeansException {
System.out.println("Bean '" + beanName + "' created : " + bean.toString());
return bean;
}
}

25/08/2016 12:10

Spring Framework Reference Documentation

146 de 1194

<?xml version="1.0" encoding="UTF-8"?>

<lang:groovy id="messenger"
script-source="classpath:org/springframework/scripting/groovy/Messenger.gr
<lang:property name="message" value="Fiona Apple Is Just So Dreamy."
</lang:groovy>
<!-when the above bean (messenger) is instantiated, this custom
BeanPostProcessor implementation will output the fact to the system console
-->
<bean class="scripting.InstantiationTracingBeanPostProcessor"/>
</beans>

Notice how the InstantiationTracingBeanPostProcessor is simply defined. It does

not 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
Chapter 35, Dynamic language support.)
The following simple Java application executes the preceding code and configuration:
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.springframework.scripting.Messenger;
public final class Boot {

public static void main(final String[] args) throws Exception {

ApplicationContext ctx = new ClassPathXmlApplicationContext("scripting/beans.x
Messenger messenger = (Messenger) ctx.getBean("messenger");
System.out.println(messenger);
}
}

The output of the preceding application resembles the following:

Bean 'messenger' created : org.springframework.scripting.groovy.GroovyMessenger@272961

25/08/2016 12:10

Spring Framework Reference Documentation

147 de 1194

Example: The RequiredAnnotationBeanPostProcessor

Using callback interfaces or annotations in conjunction with a custom
BeanPostProcessor implementation is a common means of extending the Spring IoC
container. An example is Springs RequiredAnnotationBeanPostProcessor - a
BeanPostProcessor implementation that ships with the Spring distribution which
ensures that JavaBean properties on beans that are marked with an (arbitrary) annotation
are actually (configured to be) dependency-injected with a value.

7.8.2 Customizing configuration metadata with a

BeanFactoryPostProcessor
The next extension point that we will look at is the
org.springframework.beans.factory.config.BeanFactoryPostProcessor . The
semantics of this interface are similar to those of the BeanPostProcessor , with one
major difference: BeanFactoryPostProcessor operates on the bean configuration
metadata; that is, the Spring IoC container allows a BeanFactoryPostProcessor to
read the configuration metadata and potentially change it before the container instantiates
any beans other than BeanFactoryPostProcessor s.
You can configure multiple BeanFactoryPostProcessor s, and you can control the order
in which these BeanFactoryPostProcessor s execute by setting the order property.
However, you can only set this property if the BeanFactoryPostProcessor implements
the Ordered interface. If you write your own BeanFactoryPostProcessor , you should
consider implementing the Ordered interface too. Consult the javadocs of the
BeanFactoryPostProcessor and Ordered interfaces for more details.

If you want to change the actual bean instances (i.e., the objects that are
created from the configuration metadata), then you instead need to use a
BeanPostProcessor (described above in Section 7.8.1, Customizing
beans using a BeanPostProcessor). While it is technically possible to work
with bean instances within a BeanFactoryPostProcessor (e.g., using
BeanFactory.getBean() ), doing so causes premature bean instantiation,
violating the standard container lifecycle. This may cause negative side
effects such as bypassing bean post processing.
Also, BeanFactoryPostProcessor s are scoped per-container. This is only
relevant if you are using container hierarchies. If you define a
BeanFactoryPostProcessor in one container, it will only be applied to the
bean definitions in that container. Bean definitions in one container will not

25/08/2016 12:10

Spring Framework Reference Documentation

148 de 1194

be post-processed by BeanFactoryPostProcessor s in another container,

even if both containers are part of the same hierarchy.

A bean factory post-processor is executed automatically when it is declared inside an

ApplicationContext , in order to apply changes to the configuration metadata that
define the container. Spring includes a number of predefined bean factory
post-processors, such as PropertyOverrideConfigurer and
PropertyPlaceholderConfigurer . A custom BeanFactoryPostProcessor can also
be used, for example, to register custom property editors.
An ApplicationContext automatically detects any beans that are deployed into it that
implement the BeanFactoryPostProcessor interface. It uses these beans as bean
factory post-processors, at the appropriate time. You can deploy these post-processor
beans as you would any other bean.

As with BeanPostProcessor s , you typically do not want to configure

BeanFactoryPostProcessor s for lazy initialization. If no other bean
references a Bean(Factory)PostProcessor , that post-processor will not
get instantiated at all. Thus, marking it for lazy initialization will be ignored,
and the Bean(Factory)PostProcessor will be instantiated eagerly even if
you set the default-lazy-init attribute to true on the declaration of
your <beans /> element.

Example: the Class name substitution PropertyPlaceholderConfigurer

You use the PropertyPlaceholderConfigurer to externalize property values from a
bean definition in a separate file using the standard Java Properties format. Doing so
enables the person deploying an application to customize environment-specific properties
such as database URLs and passwords, without the complexity or risk of modifying the
main XML definition file or files for the container.
Consider the following XML-based configuration metadata fragment, where a
DataSource with placeholder values is defined. The example shows properties
configured from an external Properties file. At runtime, a
PropertyPlaceholderConfigurer is applied to the metadata that will replace some
properties of the DataSource. The values to replace are specified as placeholders of the
form ${property-name} which follows the Ant / log4j / JSP EL style.
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"

25/08/2016 12:10

Spring Framework Reference Documentation

149 de 1194

<property name="locations" value="classpath:com/foo/jdbc.properties"/>

</bean>
<bean id="dataSource" destroy-method="close"
class="org.apache.commons.dbcp.BasicDataSource">
<property name="driverClassName" value="${jdbc.driverClassName}"/>
<property name="url" value="${jdbc.url}"/>
<property name="username" value="${jdbc.username}"/>
<property name="password" value="${jdbc.password}"/>
</bean>

The actual values come from another file in the standard Java Properties format:
jdbc.driverClassName=org.hsqldb.jdbcDriver
jdbc.url=jdbc:hsqldb:hsql://production:9002
jdbc.username=sa
jdbc.password=root

Therefore, the string ${jdbc.username} is replaced at runtime with the value 'sa', and
the same applies for other placeholder values that match keys in the properties file. The
PropertyPlaceholderConfigurer checks for placeholders in most properties and
attributes of a bean definition. Furthermore, the placeholder prefix and suffix can be
customized.
With the context namespace introduced in Spring 2.5, it is possible to configure
property placeholders with a dedicated configuration element. One or more locations can
be provided as a comma-separated list in the location attribute.
<context:property-placeholder location="classpath:com/foo/jdbc.properties"/>

The PropertyPlaceholderConfigurer not only looks for properties in the

Properties file you specify. By default it also checks against the Java System
properties if it cannot find a property in the specified properties files. You can customize
this behavior by setting the systemPropertiesMode property of the configurer with one
of the following three supported integer values:
never (0): Never check system properties
fallback (1): Check system properties if not resolvable in the specified properties files.
This is the default.
override (2): Check system properties first, before trying the specified properties files.
This allows system properties to override any other property source.
Consult the PropertyPlaceholderConfigurer javadocs for more information.

You can use the PropertyPlaceholderConfigurer to substitute class names, which is so

25/08/2016 12:10

Spring Framework Reference Documentation

150 de 1194

useful when you have to pick a particular implementation class at runtime. For example:

<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfi
<property name="locations">
<value>classpath:com/foo/strategy.properties</value>
</property>
<property name="properties">
<value>custom.strategy.class=com.foo.DefaultStrategy</value>
</property>
</bean>
<bean id="serviceStrategy" class="${custom.strategy.class}"/>

If the class cannot be resolved at runtime to a valid class, resolution of the bean fails when it
to be created, which is during the preInstantiateSingletons() phase of an
ApplicationContext for a non-lazy-init bean.

Example: the PropertyOverrideConfigurer

The PropertyOverrideConfigurer , another bean factory post-processor, resembles
the PropertyPlaceholderConfigurer , but unlike the latter, the original definitions can
have default values or no values at all for bean properties. If an overriding Properties
file does not have an entry for a certain bean property, the default context definition is
used.
Note that the bean definition is not aware of being overridden, so it is not immediately
obvious from the XML definition file that the override configurer is being used. In case of
multiple PropertyOverrideConfigurer instances that define different values for the
same bean property, the last one wins, due to the overriding mechanism.
Properties file configuration lines take this format:
beanName.property=value

For example:
dataSource.driverClassName=com.mysql.jdbc.Driver
dataSource.url=jdbc:mysql:mydb

This example file can be used with a container definition that contains a bean called
dataSource, which has driver and url properties.
Compound property names are also supported, as long as every component of the path
except the final property being overridden is already non-null (presumably initialized by
the constructors). In this example
foo.fred.bob.sammy=123

25/08/2016 12:10

Spring Framework Reference Documentation

151 de 1194

i. the sammy property of the bob property of the fred property of the foo bean is
set to the scalar value 123 .

Specified override values are always literal values; they are not translated
into bean references. This convention also applies when the original value
in the XML bean definition specifies a bean reference.

With the context namespace introduced in Spring 2.5, it is possible to configure

property overriding with a dedicated configuration element:
<context:property-override location="classpath:override.properties"/>

7.8.3 Customizing instantiation logic with a FactoryBean

Implement the org.springframework.beans.factory.FactoryBean interface for
objects that are themselves factories.
The FactoryBean interface is a point of pluggability into the Spring IoC containers
instantiation logic. If you have complex initialization code that is better expressed in Java
as opposed to a (potentially) verbose amount of XML, you can create your own
FactoryBean , write the complex initialization inside that class, and then plug your
custom FactoryBean into the container.
The FactoryBean interface provides three methods:
Object getObject() : returns an instance of the object this factory creates. The
instance can possibly be shared, depending on whether this factory returns
singletons or prototypes.
boolean isSingleton() : returns true if this FactoryBean returns singletons,
false otherwise.
Class getObjectType() : returns the object type returned by the getObject()
method or null if the type is not known in advance.
The FactoryBean concept and interface is used in a number of places within the Spring
Framework; more than 50 implementations of the FactoryBean interface ship with
Spring itself.
When you need to ask a container for an actual FactoryBean instance itself instead of
the bean it produces, preface the beans id with the ampersand symbol ( & ) when calling
the getBean() method of the ApplicationContext . So for a given FactoryBean with

25/08/2016 12:10

Spring Framework Reference Documentation

152 de 1194

the FactoryBean ; whereas, invoking getBean("&myBean") returns the FactoryBean

instance itself.

7.9 Annotation-based container configuration

Are annotations better than XML for configuring Spring?
The introduction of annotation-based configurations raised the question of whether
this approach is 'better' than XML. The short answer is it depends. The long answer
is that each approach has its pros and cons, and usually it is up to the developer to
decide which strategy suits them better. Due to the way they are defined,
annotations provide a lot of context in their declaration, leading to shorter and more
concise configuration. However, XML excels at wiring up components without
touching their source code or recompiling them. Some developers prefer having the
wiring close to the source while others argue that annotated classes are no longer
POJOs and, furthermore, that the configuration becomes decentralized and harder
to control.
No matter the choice, Spring can accommodate both styles and even mix them
together. Its worth pointing out that through its JavaConfig option, Spring allows
annotations to be used in a non-invasive way, without touching the target
components source code and that in terms of tooling, all configuration styles are
supported by the Spring Tool Suite.
An alternative to XML setups is provided by annotation-based configuration which rely on
the bytecode metadata for wiring up components instead of angle-bracket declarations.
Instead of using XML to describe a bean wiring, the developer moves the configuration
into the component class itself by using annotations on the relevant class, method, or
field declaration. As mentioned in the section called Example: The
RequiredAnnotationBeanPostProcessor, using a BeanPostProcessor in conjunction
with annotations is a common means of extending the Spring IoC container. For example,
Spring 2.0 introduced the possibility of enforcing required properties with the @Required
annotation. Spring 2.5 made it possible to follow that same general approach to drive
Springs dependency injection. Essentially, the @Autowired annotation provides the
same capabilities as described in Section 7.4.5, Autowiring collaborators but with more
fine-grained control and wider applicability. Spring 2.5 also added support for JSR-250
annotations such as @PostConstruct , and @PreDestroy . Spring 3.0 added support for
JSR-330 (Dependency Injection for Java) annotations contained in the javax.inject
package such as @Inject and @Named . Details about those annotations can be found
in the relevant section.

25/08/2016 12:10

Spring Framework Reference Documentation

153 de 1194

Annotation injection is performed before XML injection, thus the latter

configuration will override the former for properties wired through both
approaches.

As always, you can register them as individual bean definitions, but they can also be
implicitly registered by including the following tag in an XML-based Spring configuration
(notice the inclusion of the context namespace):
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<context:annotation-config/>
</beans>

(The implicitly registered post-processors include

AutowiredAnnotationBeanPostProcessor , CommonAnnotationBeanPostProcessor ,
PersistenceAnnotationBeanPostProcessor , as well as the aforementioned
RequiredAnnotationBeanPostProcessor .)

<context:annotation-config/> only looks for annotations on beans in

the same application context in which it is defined. This means that, if you
put <context:annotation-config/> in a WebApplicationContext for
a DispatcherServlet , it only checks for @Autowired beans in your
controllers, and not your services. See Section 22.2, The
DispatcherServlet for more information.

7.9.1 @Required
The @Required annotation applies to bean property setter methods, as in the following
example:
public class SimpleMovieLister {

25/08/2016 12:10

Spring Framework Reference Documentation

154 de 1194

private MovieFinder movieFinder;

@Required
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
// ...
}

This annotation simply indicates that the affected bean property must be populated at
configuration time, through an explicit property value in a bean definition or through
autowiring. The container throws an exception if the affected bean property has not been
populated; this allows for eager and explicit failure, avoiding NullPointerException s
or the like later on. It is still recommended that you put assertions into the bean class
itself, for example, into an init method. Doing so enforces those required references and
values even when you use the class outside of a container.

7.9.2 @Autowired
JSR 330s @Inject annotation can be used in place of Springs
@Autowired annotation in the examples below. See here for more details.

You can apply the @Autowired annotation to constructors:

public class MovieRecommender {
private final CustomerPreferenceDao customerPreferenceDao;
@Autowired
public MovieRecommender(CustomerPreferenceDao customerPreferenceDao) {
this.customerPreferenceDao = customerPreferenceDao;
}
// ...
}

As of Spring Framework 4.3, the @Autowired constructor is no longer

necessary if the target bean only defines one constructor. If several

25/08/2016 12:10

Spring Framework Reference Documentation

155 de 1194

constructors are available, at least one must be annotated to teach the

container which one it has to use.

As expected, you can also apply the @Autowired annotation to "traditional" setter
methods:
public class SimpleMovieLister {
private MovieFinder movieFinder;
@Autowired
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
// ...
}

You can also apply the annotation to methods with arbitrary names and/or multiple
arguments:
public class MovieRecommender {
private MovieCatalog movieCatalog;
private CustomerPreferenceDao customerPreferenceDao;
@Autowired
public void prepare(MovieCatalog movieCatalog,
CustomerPreferenceDao customerPreferenceDao) {
this.movieCatalog = movieCatalog;
this.customerPreferenceDao = customerPreferenceDao;
}
// ...
}

You can apply @Autowired to fields as well and even mix it with constructors:
public class MovieRecommender {
private final CustomerPreferenceDao customerPreferenceDao;

25/08/2016 12:10

Spring Framework Reference Documentation

156 de 1194

@Autowired
private MovieCatalog movieCatalog;
@Autowired
public MovieRecommender(CustomerPreferenceDao customerPreferenceDao) {
this.customerPreferenceDao = customerPreferenceDao;
}
// ...
}

It is also possible to provide all beans of a particular type from the ApplicationContext
by adding the annotation to a field or method that expects an array of that type:
public class MovieRecommender {
@Autowired
private MovieCatalog[] movieCatalogs;
// ...
}

The same applies for typed collections:

public class MovieRecommender {
private Set<MovieCatalog> movieCatalogs;
@Autowired
public void setMovieCatalogs(Set<MovieCatalog> movieCatalogs) {
this.movieCatalogs = movieCatalogs;
}
// ...
}

Your beans can implement the org.springframework.core.Ordered

interface or either use the @Order or standard @Priority annotation if
you want items in the array or list to be sorted into a specific order.

Even typed Maps can be autowired as long as the expected key type is String . The

25/08/2016 12:10

Spring Framework Reference Documentation

157 de 1194

corresponding bean names:

public class MovieRecommender {
private Map<String, MovieCatalog> movieCatalogs;
@Autowired
public void setMovieCatalogs(Map<String, MovieCatalog> movieCatalogs) {
this.movieCatalogs = movieCatalogs;
}
// ...
}

By default, the autowiring fails whenever zero candidate beans are available; the default
behavior is to treat annotated methods, constructors, and fields as indicating required
dependencies. This behavior can be changed as demonstrated below.
public class SimpleMovieLister {
private MovieFinder movieFinder;
@Autowired(required=false)
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
// ...
}

Only one annotated constructor per-class can be marked as required, but multiple
non-required constructors can be annotated. In that case, each is considered
among the candidates and Spring uses the greediest constructor whose
dependencies can be satisfied, that is the constructor that has the largest number
of arguments.
@Autowireds required attribute is recommended over the `@Required
annotation. The required attribute indicates that the property is not required for
autowiring purposes, the property is ignored if it cannot be autowired. @Required ,
on the other hand, is stronger in that it enforces the property that was set by any
means supported by the container. If no value is injected, a corresponding
exception is raised.

25/08/2016 12:10

Spring Framework Reference Documentation

158 de 1194

You can also use @Autowired for interfaces that are well-known resolvable
dependencies: BeanFactory , ApplicationContext , Environment ,
ResourceLoader , ApplicationEventPublisher , and MessageSource . These
interfaces and their extended interfaces, such as ConfigurableApplicationContext
or ResourcePatternResolver , are automatically resolved, with no special setup
necessary.
public class MovieRecommender {
@Autowired
private ApplicationContext context;
public MovieRecommender() {
}
// ...
}

@Autowired , @Inject , @Resource , and @Value annotations are

handled by Spring BeanPostProcessor implementations which in turn
means that you cannot apply these annotations within your own
BeanPostProcessor or BeanFactoryPostProcessor types (if any).
These types must be 'wired up' explicitly via XML or using a Spring @Bean
method.

7.9.3 Fine-tuning annotation-based autowiring with @Primary

Because autowiring by type may lead to multiple candidates, it is often necessary to have
more control over the selection process. One way to accomplish this is with Springs
@Primary annotation. @Primary indicates that a particular bean should be given
preference when multiple beans are candidates to be autowired to a single-valued
dependency. If exactly one 'primary' bean exists among the candidates, it will be the
autowired value.
Lets assume we have the following configuration that defines firstMovieCatalog as
the primary MovieCatalog .
@Configuration
public class MovieConfiguration {

25/08/2016 12:10

Spring Framework Reference Documentation

159 de 1194

@Bean
@Primary
public MovieCatalog firstMovieCatalog() { ... }
@Bean
public MovieCatalog secondMovieCatalog() { ... }
// ...
}

With such configuration, the following MovieRecommender will be autowired with the
firstMovieCatalog .
public class MovieRecommender {
@Autowired
private MovieCatalog movieCatalog;
// ...
}

The corresponding bean definitions appear as follows.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<context:annotation-config/>
<bean class="example.SimpleMovieCatalog" primary="true">

</bean>
<bean class="example.SimpleMovieCatalog">

</bean>
<bean id="movieRecommender" class="example.MovieRecommender"/>
</beans>

25/08/2016 12:10

Spring Framework Reference Documentation

160 de 1194

7.9.4 Fine-tuning annotation-based autowiring with qualifiers

@Primary is an effective way to use autowiring by type with several instances when one
primary candidate can be determined. When more control over the selection process is
required, Springs @Qualifier annotation can be used. You can associate qualifier
values with specific arguments, narrowing the set of type matches so that a specific bean
is chosen for each argument. In the simplest case, this can be a plain descriptive value:
public class MovieRecommender {
@Autowired
@Qualifier("main")
private MovieCatalog movieCatalog;
// ...
}

The @Qualifier annotation can also be specified on individual constructor arguments

or method parameters:
public class MovieRecommender {
private MovieCatalog movieCatalog;
private CustomerPreferenceDao customerPreferenceDao;
@Autowired
public void prepare(@Qualifier("main")MovieCatalog movieCatalog,
CustomerPreferenceDao customerPreferenceDao) {
this.movieCatalog = movieCatalog;
this.customerPreferenceDao = customerPreferenceDao;
}
// ...
}

The corresponding bean definitions appear as follows. The bean with qualifier value
"main" is wired with the constructor argument that is qualified with the same value.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans

25/08/2016 12:10

Spring Framework Reference Documentation

161 de 1194

http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<context:annotation-config/>
<bean class="example.SimpleMovieCatalog">
<qualifier value="main"/>

</bean>
<bean class="example.SimpleMovieCatalog">
<qualifier value="action"/>

</bean>
<bean id="movieRecommender" class="example.MovieRecommender"/>
</beans>

For a fallback match, the bean name is considered a default qualifier value. Thus you can
define the bean with an id "main" instead of the nested qualifier element, leading to the
same matching result. However, although you can use this convention to refer to specific
beans by name, @Autowired is fundamentally about type-driven injection with optional
semantic qualifiers. This means that qualifier values, even with the bean name fallback,
always have narrowing semantics within the set of type matches; they do not semantically
express a reference to a unique bean id. Good qualifier values are "main" or "EMEA" or
"persistent", expressing characteristics of a specific component that are independent from
the bean id , which may be auto-generated in case of an anonymous bean definition like
the one in the preceding example.
Qualifiers also apply to typed collections, as discussed above, for example, to
Set<MovieCatalog> . In this case, all matching beans according to the declared
qualifiers are injected as a collection. This implies that qualifiers do not have to be unique;
they rather simply constitute filtering criteria. For example, you can define multiple
MovieCatalog beans with the same qualifier value "action", all of which would be
injected into a Set<MovieCatalog> annotated with @Qualifier("action") .

If you intend to express annotation-driven injection by name, do not

primarily use @Autowired , even if is technically capable of referring to a
bean name through @Qualifier values. Instead, use the JSR-250

25/08/2016 12:10

Spring Framework Reference Documentation

162 de 1194

@Resource annotation, which is semantically defined to identify a specific

target component by its unique name, with the declared type being
irrelevant for the matching process. @Autowired has rather different
semantics: After selecting candidate beans by type, the specified String
qualifier value will be considered within those type-selected candidates only,
e.g. matching an "account" qualifier against beans marked with the same
qualifier label.
For beans that are themselves defined as a collection/map or array type,
@Resource is a fine solution, referring to the specific collection or array
bean by unique name. That said, as of 4.3, collection/map and array types
can be matched through Springs @Autowired type matching algorithm as
well, as long as the element type information is preserved in @Bean return
type signatures or collection inheritance hierarchies. In this case, qualifier
values can be used to select among same-typed collections, as outlined in
the previous paragraph.
As of 4.3, @Autowired also considers self references for injection, i.e.
references back to the bean that is currently injected. Note that self injection
is a fallback; regular dependencies on other components always have
precedence. In that sense, self references do not participate in regular
candidate selection and are therefore in particular never primary; on the
contrary, they always end up as lowest precedence. In practice, use self
references as a last resort only, e.g. for calling other methods on the same
instance through the beans transactional proxy: Consider factoring out the
affected methods to a separate delegate bean in such a scenario.
Alternatively, use @Resource which may obtain a proxy back to the current
bean by its unique name.
@Autowired applies to fields, constructors, and multi-argument methods,
allowing for narrowing through qualifier annotations at the parameter level.
By contrast, @Resource is supported only for fields and bean property
setter methods with a single argument. As a consequence, stick with
qualifiers if your injection target is a constructor or a multi-argument
method.

You can create your own custom qualifier annotations. Simply define an annotation and
provide the @Qualifier annotation within your definition:
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier

25/08/2016 12:10

Spring Framework Reference Documentation

163 de 1194

String value();
}

Then you can provide the custom qualifier on autowired fields and parameters:
public class MovieRecommender {
@Autowired
@Genre("Action")
private MovieCatalog actionCatalog;
private MovieCatalog comedyCatalog;
@Autowired
public void setComedyCatalog(@Genre("Comedy") MovieCatalog comedyCatalog) {
this.comedyCatalog = comedyCatalog;
}
// ...
}

Next, provide the information for the candidate bean definitions. You can add
<qualifier/> tags as sub-elements of the <bean/> tag and then specify the type
and value to match your custom qualifier annotations. The type is matched against the
fully-qualified class name of the annotation. Or, as a convenience if no risk of conflicting
names exists, you can use the short class name. Both approaches are demonstrated in
the following example.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<context:annotation-config/>
<bean class="example.SimpleMovieCatalog">
<qualifier type="Genre" value="Action"/>

</bean>
<bean class="example.SimpleMovieCatalog">

25/08/2016 12:10

Spring Framework Reference Documentation

164 de 1194

<qualifier type="example.Genre" value="Comedy"/>

</bean>
<bean id="movieRecommender" class="example.MovieRecommender"/>
</beans>

In Section 7.10, Classpath scanning and managed components, you will see an
annotation-based alternative to providing the qualifier metadata in XML. Specifically, see
Section 7.10.8, Providing qualifier metadata with annotations.
In some cases, it may be sufficient to use an annotation without a value. This may be
useful when the annotation serves a more generic purpose and can be applied across
several different types of dependencies. For example, you may provide an offline catalog
that would be searched when no Internet connection is available. First define the simple
annotation:
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface Offline {
}

Then add the annotation to the field or property to be autowired:

public class MovieRecommender {
@Autowired
@Offline
private MovieCatalog offlineCatalog;
// ...
}

Now the bean definition only needs a qualifier type :

You can also define custom qualifier annotations that accept named attributes in addition

25/08/2016 12:10

Spring Framework Reference Documentation

165 de 1194

on a field or parameter to be autowired, a bean definition must match all such attribute
values to be considered an autowire candidate. As an example, consider the following
annotation definition:
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface MovieQualifier {
String genre();
Format format();
}

In this case Format is an enum:

public enum Format {
VHS, DVD, BLURAY
}

The fields to be autowired are annotated with the custom qualifier and include values for
both attributes: genre and format .
public class MovieRecommender {
@Autowired
@MovieQualifier(format=Format.VHS, genre="Action")
private MovieCatalog actionVhsCatalog;
@Autowired
@MovieQualifier(format=Format.VHS, genre="Comedy")
private MovieCatalog comedyVhsCatalog;
@Autowired
@MovieQualifier(format=Format.DVD, genre="Action")
private MovieCatalog actionDvdCatalog;
@Autowired
@MovieQualifier(format=Format.BLURAY, genre="Comedy")
private MovieCatalog comedyBluRayCatalog;
// ...
}

25/08/2016 12:10

Spring Framework Reference Documentation

166 de 1194

demonstrates that bean meta attributes may be used instead of the <qualifier/>
sub-elements. If available, the <qualifier/> and its attributes take precedence, but the
autowiring mechanism falls back on the values provided within the <meta/> tags if no
such qualifier is present, as in the last two bean definitions in the following example.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<context:annotation-config/>
<bean class="example.SimpleMovieCatalog">
<qualifier type="MovieQualifier">
<attribute key="format" value="VHS"/>
<attribute key="genre" value="Action"/>
</qualifier>

</bean>
<bean class="example.SimpleMovieCatalog">
<qualifier type="MovieQualifier">
<attribute key="format" value="VHS"/>
<attribute key="genre" value="Comedy"/>
</qualifier>

</bean>
<bean class="example.SimpleMovieCatalog">
<meta key="format" value="DVD"/>
<meta key="genre" value="Action"/>

</bean>
<bean class="example.SimpleMovieCatalog">
<meta key="format" value="BLURAY"/>
<meta key="genre" value="Comedy"/>

</bean>
</beans>

25/08/2016 12:10

Spring Framework Reference Documentation

167 de 1194

7.9.5 Using generics as autowiring qualifiers

In addition to the @Qualifier annotation, it is also possible to use Java generic types as
an implicit form of qualification. For example, suppose you have the following
configuration:
@Configuration
public class MyConfiguration {
@Bean
public StringStore stringStore() {
return new StringStore();
}
@Bean
public IntegerStore integerStore() {
return new IntegerStore();
}
}

Assuming that beans above implement a generic interface, i.e. Store<String> and
Store<Integer> , you can @Autowire the Store interface and the generic will be
used as a qualifier:
@Autowired
private Store<String> s1; // <String> qualifier, injects the stringStore bean
@Autowired
private Store<Integer> s2; // <Integer> qualifier, injects the integerStore bean

Generic qualifiers also apply when autowiring Lists, Maps and Arrays:
// Inject all Store beans as long as they have an <Integer> generic
// Store<String> beans will not appear in this list
@Autowired
private List<Store<Integer>> s;

7.9.6 CustomAutowireConfigurer
The CustomAutowireConfigurer is a BeanFactoryPostProcessor that enables you
to register your own custom qualifier annotation types even if they are not annotated with
Springs @Qualifier annotation.

25/08/2016 12:10

Spring Framework Reference Documentation

168 de 1194

class="org.springframework.beans.factory.annotation.CustomAutowireConfigurer"
<property name="customQualifierTypes">
<set>
<value>example.CustomQualifier</value>
</set>
</property>
</bean>

The AutowireCandidateResolver determines autowire candidates by:

the autowire-candidate value of each bean definition
any default-autowire-candidates pattern(s) available on the <beans/>
element
the presence of @Qualifier annotations and any custom annotations registered
with the CustomAutowireConfigurer
When multiple beans qualify as autowire candidates, the determination of a "primary" is
the following: if exactly one bean definition among the candidates has a primary
attribute set to true , it will be selected.

7.9.7 @Resource
Spring also supports injection using the JSR-250 @Resource annotation on fields or
bean property setter methods. This is a common pattern in Java EE 5 and 6, for example
in JSF 1.2 managed beans or JAX-WS 2.0 endpoints. Spring supports this pattern for
Spring-managed objects as well.
@Resource takes a name attribute, and by default Spring interprets that value as the
bean name to be injected. In other words, it follows by-name semantics, as demonstrated
in this example:
public class SimpleMovieLister {
private MovieFinder movieFinder;
@Resource(name="myMovieFinder")
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
}

If no name is specified explicitly, the default name is derived from the field name or setter
method. In case of a field, it takes the field name; in case of a setter method, it takes the

25/08/2016 12:10

Spring Framework Reference Documentation

169 de 1194

bean property name. So the following example is going to have the bean with name
"movieFinder" injected into its setter method:
public class SimpleMovieLister {
private MovieFinder movieFinder;
@Resource
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
}

The name provided with the annotation is resolved as a bean name by the
ApplicationContext of which the
CommonAnnotationBeanPostProcessor is aware. The names can be
resolved through JNDI if you configure Springs SimpleJndiBeanFactory
explicitly. However, it is recommended that you rely on the default behavior
and simply use Springs JNDI lookup capabilities to preserve the level of
indirection.

In the exclusive case of @Resource usage with no explicit name specified, and similar to
@Autowired , @Resource finds a primary type match instead of a specific named bean
and resolves well-known resolvable dependencies: the BeanFactory ,
ApplicationContext , ResourceLoader , ApplicationEventPublisher , and
MessageSource interfaces.
Thus in the following example, the customerPreferenceDao field first looks for a bean
named customerPreferenceDao, then falls back to a primary type match for the type
CustomerPreferenceDao . The "context" field is injected based on the known resolvable
dependency type ApplicationContext .
public class MovieRecommender {
@Resource
private CustomerPreferenceDao customerPreferenceDao;
@Resource
private ApplicationContext context;
public MovieRecommender() {

25/08/2016 12:10

Spring Framework Reference Documentation

170 de 1194

// ...
}

7.9.8 @PostConstruct and @PreDestroy

The CommonAnnotationBeanPostProcessor not only recognizes the @Resource
annotation but also the JSR-250 lifecycle annotations. Introduced in Spring 2.5, the
support for these annotations offers yet another alternative to those described in
initialization callbacks and destruction callbacks. Provided that the
CommonAnnotationBeanPostProcessor is registered within the Spring
ApplicationContext , a method carrying one of these annotations is invoked at the
same point in the lifecycle as the corresponding Spring lifecycle interface method or
explicitly declared callback method. In the example below, the cache will be
pre-populated upon initialization and cleared upon destruction.
public class CachingMovieLister {
@PostConstruct
public void populateMovieCache() {
// populates the movie cache upon initialization...
}
@PreDestroy
public void clearMovieCache() {
// clears the movie cache upon destruction...
}
}

For details about the effects of combining various lifecycle mechanisms,

see the section called Combining lifecycle mechanisms.

7.10 Classpath scanning and managed components

Most examples in this chapter use XML to specify the configuration metadata that
produces each BeanDefinition within the Spring container. The previous section
(Section 7.9, Annotation-based container configuration) demonstrates how to provide a
lot of the configuration metadata through source-level annotations. Even in those

25/08/2016 12:10

Spring Framework Reference Documentation

171 de 1194

the annotations only drive the dependency injection. This section describes an option for
implicitly detecting the candidate components by scanning the classpath. Candidate
components are classes that match against a filter criteria and have a corresponding
bean definition registered with the container. This removes the need to use XML to
perform bean registration; instead you can use annotations (for example @Component ),
AspectJ type expressions, or your own custom filter criteria to select which classes will
have bean definitions registered with the container.

Starting with Spring 3.0, many features provided by the Spring JavaConfig
project are part of the core Spring Framework. This allows you to define
beans using Java rather than using the traditional XML files. Take a look at
the @Configuration , @Bean , @Import , and @DependsOn annotations
for examples of how to use these new features.

7.10.1 @Component and further stereotype annotations

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 Section 20.2.2,
Exception translation.
Spring provides further stereotype annotations: @Component , @Service , and
@Controller . @Component is a generic stereotype for any Spring-managed
component. @Repository , @Service , and @Controller are specializations of
@Component for more specific use cases, for example, in the persistence, service, and
presentation layers, respectively. Therefore, you can annotate your component classes
with @Component , but by annotating them with @Repository , @Service , or
@Controller instead, your classes are more properly suited for processing by tools or
associating with aspects. For example, these stereotype annotations make ideal targets
for pointcuts. It is also possible that @Repository , @Service , and @Controller may
carry additional semantics in future releases of the Spring Framework. Thus, if you are
choosing between using @Component or @Service for your service layer, @Service is
clearly the better choice. Similarly, as stated above, @Repository is already supported
as a marker for automatic exception translation in your persistence layer.

7.10.2 Meta-annotations
Many of the annotations provided by Spring can be used as meta-annotations in your

25/08/2016 12:10

Spring Framework Reference Documentation

172 de 1194

annotation. For example, the @Service annotation mentioned above is meta-annotated

with @Component :
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component // Spring will see this and treat @Service in the same way as @Component
public @interface Service {
// ....
}

Meta-annotations can also be combined to create composed annotations. For example,

the @RestController annotation from Spring MVC is composed of @Controller and
@ResponseBody .
In addition, composed annotations may optionally redeclare attributes from
meta-annotations to allow user customization. This can be particularly useful when you
want to only expose a subset of the meta-annotations attributes. For example, Springs
@SessionScope annotation hardcodes the scope name to session but still allows
customization of the proxyMode .
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Scope(WebApplicationContext.SCOPE_SESSION)
public @interface SessionScope {
/**
* Alias for {@link Scope#proxyMode}.
* <p>Defaults to {@link ScopedProxyMode#TARGET_CLASS}.
*/
@AliasFor(annotation = Scope.class)
ScopedProxyMode proxyMode() default ScopedProxyMode.TARGET_CLASS;
}

@SessionScope can then be used without declaring the proxyMode as follows:

@Service
@SessionScope
public class SessionScopedService {
// ...
}

25/08/2016 12:10

Spring Framework Reference Documentation

173 de 1194

@Service
@SessionScope(proxyMode = ScopedProxyMode.INTERFACES)
public class SessionScopedUserService implements UserService {
// ...
}

For further details, consult the Spring Annotation Programming Model.

7.10.3 Automatically detecting classes and registering bean

definitions
Spring can automatically detect stereotyped classes and register corresponding
BeanDefinition s with the ApplicationContext . For example, the following two
classes are eligible for such autodetection:
@Service
public class SimpleMovieLister {
private MovieFinder movieFinder;
@Autowired
public SimpleMovieLister(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
}
@Repository
public class JpaMovieFinder implements MovieFinder {
// implementation elided for clarity
}

To autodetect these classes and register the corresponding beans, you need to add
@ComponentScan to your @Configuration class, where the basePackages attribute is
a common parent package for the two classes. (Alternatively, you can specify a
comma/semicolon/space-separated list that includes the parent package of each class.)
@Configuration
@ComponentScan(basePackages = "org.example")
public class AppConfig {
...
}

25/08/2016 12:10

Spring Framework Reference Documentation

174 de 1194

for concision, the above may have used the value attribute of the
annotation, i.e. ComponentScan("org.example")

The following is an alternative using XML

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<context:component-scan base-package="org.example"/>
</beans>

The use of <context:component-scan> implicitly enables the

functionality of <context:annotation-config> . There is usually no need
to include the <context:annotation-config> element when using
<context:component-scan> .

The scanning of classpath packages requires the presence of

corresponding directory entries in the classpath. When you build JARs with
Ant, make sure that you do not activate the files-only switch of the JAR task.
Also, classpath directories may not get exposed based on security policies
in some environments, e.g. standalone apps on JDK 1.7.0_45 and higher
(which requires 'Trusted-Library' setup in your manifests; see
http://stackoverflow.com/questions/19394570/java-jre-7u45-breaksclassloader-getresources).

Furthermore, the AutowiredAnnotationBeanPostProcessor and

CommonAnnotationBeanPostProcessor are both included implicitly when you use the
component-scan element. That means that the two components are autodetected and
wired together - all without any bean configuration metadata provided in XML.

25/08/2016 12:10

Spring Framework Reference Documentation

175 de 1194

You can disable the registration of

AutowiredAnnotationBeanPostProcessor and
CommonAnnotationBeanPostProcessor by including the annotationconfig attribute with a value of false.

7.10.4 Using filters to customize scanning

By default, classes annotated with @Component , @Repository , @Service ,
@Controller , or a custom annotation that itself is annotated with @Component are the
only detected candidate components. However, you can modify and extend this behavior
simply by applying custom filters. Add them as includeFilters or excludeFilters parameters
of the @ComponentScan annotation (or as include-filter or exclude-filter sub-elements of
the component-scan element). Each filter element requires the type and expression
attributes. The following table describes the filtering options.

Table 7.5. Filter Types

Filter

Example Expression

Description

Type
annotation

org.example.SomeAnnotation

(default)
assignable

An annotation to be present at the type level in

target components.

org.example.SomeClass

A class (or interface) that the target components

are assignable to (extend/implement).

aspectj

org.example..*Service+

An AspectJ type expression to be matched by the

target components.

regex

org\.example\.Default.*

A regex expression to be matched by the target

components class names.

custom

org.example.MyTypeFilter

A custom implementation of the

org.springframework.core.type .TypeFilt
interface.

The following example shows the configuration ignoring all @Repository annotations
and using "stub" repositories instead.

25/08/2016 12:10

Spring Framework Reference Documentation

176 de 1194

@Configuration
@ComponentScan(basePackages = "org.example",
includeFilters = @Filter(type = FilterType.REGEX, pattern = ".*Stub.*Repositor
excludeFilters = @Filter(Repository.class))
public class AppConfig {
...
}

and the equivalent using XML

You can also disable the default filters by setting

useDefaultFilters=false on the annotation or providing
use-default-filters="false" as an attribute of the
<component-scan/> element. This will in effect disable automatic
detection of classes annotated with @Component , @Repository ,
@Service , @Controller , or @Configuration .

7.10.5 Defining bean metadata within components

Spring components can also contribute bean definition metadata to the container. You do
this with the same @Bean annotation used to define bean metadata within
@Configuration annotated classes. Here is a simple example:
@Component
public class FactoryMethodComponent {
@Bean
@Qualifier("public")
public TestBean publicInstance() {
return new TestBean("publicInstance");
}
public void doWork() {

25/08/2016 12:10

Spring Framework Reference Documentation

177 de 1194

}
}

This class is a Spring component that has application-specific code contained in its
doWork() method. However, it also contributes a bean definition that has a factory
method referring to the method publicInstance() . The @Bean annotation identifies
the factory method and other bean definition properties, such as a qualifier value through
the @Qualifier annotation. Other method level annotations that can be specified are
@Scope , @Lazy , and custom qualifier annotations.

In addition to its role for component initialization, the @Lazy annotation may
also be placed on injection points marked with @Autowired or @Inject .
In this context, it leads to the injection of a lazy-resolution proxy.

Autowired fields and methods are supported as previously discussed, with additional
support for autowiring of @Bean methods:
@Component
public class FactoryMethodComponent {
private static int i;
@Bean
@Qualifier("public")
public TestBean publicInstance() {
return new TestBean("publicInstance");
}
// use of a custom qualifier and autowiring of method parameters
@Bean
protected TestBean protectedInstance(
@Qualifier("public") TestBean spouse,
@Value("#{privateInstance.age}") String country) {
TestBean tb = new TestBean("protectedInstance", 1);
tb.setSpouse(spouse);
tb.setCountry(country);
return tb;
}
@Bean
private TestBean privateInstance() {
return new TestBean("privateInstance", i++);

25/08/2016 12:10

Spring Framework Reference Documentation

178 de 1194

}
@Bean
@RequestScope
public TestBean requestScopedInstance() {
return new TestBean("requestScopedInstance", 3);
}
}

The example autowires the String method parameter country to the value of the Age
property on another bean named privateInstance . A Spring Expression Language
element defines the value of the property through the notation #{ <expression> } . For
@Value annotations, an expression resolver is preconfigured to look for bean names
when resolving expression text.
The @Bean methods in a Spring component are processed differently than their
counterparts inside a Spring @Configuration class. The difference is that @Component
classes are not enhanced with CGLIB to intercept the invocation of methods and fields.
CGLIB proxying is the means by which invoking methods or fields within @Bean methods
in @Configuration classes creates bean metadata references to collaborating objects;
such methods are not invoked with normal Java semantics but rather go through the
container in order to provide the usual lifecycle management and proxying of Spring
beans even when referring to other beans via programmatic calls to @Bean methods. In
contrast, invoking a method or field in an @Bean method within a plain @Component
class has standard Java semantics, with no special CGLIB processing or other
constraints applying.

You may declare @Bean methods as static , allowing for them to be

called without creating their containing configuration class as an instance.
This makes particular sense when defining post-processor beans, e.g. of
type BeanFactoryPostProcessor or BeanPostProcessor , since such
beans will get initialized early in the container lifecycle and should avoid
triggering other parts of the configuration at that point.
Note that calls to static @Bean methods will never get intercepted by the
container, not even within @Configuration classes (see above). This is
due to technical limitations: CGLIB subclassing can only override non-static
methods. As a consequence, a direct call to another @Bean method will
have standard Java semantics, resulting in an independent instance being
returned straight from the factory method itself.
The Java language visibility of @Bean methods does not have an

25/08/2016 12:10

Spring Framework Reference Documentation

179 de 1194

immediate impact on the resulting bean definition in Springs container. You

may freely declare your factory methods as you see fit in
non- @Configuration classes and also for static methods anywhere.
However, regular @Bean methods in @Configuration classes need to be
overridable, i.e. they must not be declared as private or final .
@Bean methods will also be discovered on base classes of a given
component or configuration class, as well as on Java 8 default methods
declared in interfaces implemented by the component or configuration
class. This allows for a lot of flexibility in composing complex configuration
arrangements, with even multiple inheritance being possible through Java 8
default methods as of Spring 4.2.
Finally, note that a single class may hold multiple @Bean methods for the
same bean, as an arrangement of multiple factory methods to use
depending on available dependencies at runtime. This is the same
algorithm as for choosing the "greediest" constructor or factory method in
other configuration scenarios: The variant with the largest number of
satisfiable dependencies will be picked at construction time, analogous to
how the container selects between multiple @Autowired constructors.

7.10.6 Naming autodetected components

When a component is autodetected as part of the scanning process, its bean name is
generated by the BeanNameGenerator strategy known to that scanner. By default, any
Spring stereotype annotation ( @Component , @Repository , @Service , and
@Controller ) that contains a name value will thereby provide that name to the
corresponding bean definition.
If such an annotation contains no name value or for any other detected component
(such as those discovered by custom filters), the default bean name generator returns the
uncapitalized non-qualified class name. For example, if the following two components
were detected, the names would be myMovieLister and movieFinderImpl :
@Service("myMovieLister")
public class SimpleMovieLister {
// ...
}
@Repository
public class MovieFinderImpl implements MovieFinder {
// ...

25/08/2016 12:10

Spring Framework Reference Documentation

180 de 1194

If you do not want to rely on the default bean-naming strategy, you can
provide a custom bean-naming strategy. First, implement the
BeanNameGenerator interface, and be sure to include a default no-arg
constructor. Then, provide the fully-qualified class name when configuring
the scanner:

@Configuration
@ComponentScan(basePackages = "org.example", nameGenerator = MyNameGenerator.class)
public class AppConfig {
...
}
<beans>
<context:component-scan base-package="org.example"
name-generator="org.example.MyNameGenerator" />
</beans>

As a general rule, consider specifying the name with the annotation whenever other
components may be making explicit references to it. On the other hand, the
auto-generated names are adequate whenever the container is responsible for wiring.

7.10.7 Providing a scope for autodetected components

As with Spring-managed components in general, the default and most common scope for
autodetected components is singleton . However, sometimes you need a different
scope which can be specified via the @Scope annotation. Simply provide the name of the
scope within the annotation:
@Scope("prototype")
@Repository
public class MovieFinderImpl implements MovieFinder {
// ...
}

For details on web-specific scopes, see Section 7.5.4, Request, session, global session,
application, and WebSocket scopes.

To provide a custom strategy for scope resolution rather than relying on the

25/08/2016 12:10

Spring Framework Reference Documentation

181 de 1194

annotation-based approach, implement the ScopeMetadataResolver

interface, and be sure to include a default no-arg constructor. Then, provide
the fully-qualified class name when configuring the scanner:

@Configuration
@ComponentScan(basePackages = "org.example", scopeResolver = MyScopeResolver.class)
public class AppConfig {
...
}
<beans>
<context:component-scan base-package="org.example"
scope-resolver="org.example.MyScopeResolver" />
</beans>

When using certain non-singleton scopes, it may be necessary to generate proxies for the
scoped objects. The reasoning is described in the section called Scoped beans as
dependencies. For this purpose, a scoped-proxy attribute is available on the
component-scan element. The three possible values are: no, interfaces, and targetClass.
For example, the following configuration will result in standard JDK dynamic proxies:

@Configuration
@ComponentScan(basePackages = "org.example", scopedProxy = ScopedProxyMode.INTERFACES)
public class AppConfig {
...
}
<beans>
<context:component-scan base-package="org.example"
scoped-proxy="interfaces" />
</beans>

7.10.8 Providing qualifier metadata with annotations

The @Qualifier annotation is discussed in Section 7.9.4, Fine-tuning annotation-based
autowiring with qualifiers. The examples in that section demonstrate the use of the
@Qualifier annotation and custom qualifier annotations to provide fine-grained control
when you resolve autowire candidates. Because those examples were based on XML
bean definitions, the qualifier metadata was provided on the candidate bean definitions
using the qualifier or meta sub-elements of the bean element in the XML. When
relying upon classpath scanning for autodetection of components, you provide the

25/08/2016 12:10

Spring Framework Reference Documentation

182 de 1194

examples demonstrate this technique:

@Component
@Qualifier("Action")
public class ActionMovieCatalog implements MovieCatalog {
// ...
}
@Component
@Genre("Action")
public class ActionMovieCatalog implements MovieCatalog {
// ...
}
@Component
@Offline
public class CachingMovieCatalog implements MovieCatalog {
// ...
}

As with most annotation-based alternatives, keep in mind that the

annotation metadata is bound to the class definition itself, while the use of
XML allows for multiple beans of the same type to provide variations in their
qualifier metadata, because that metadata is provided per-instance rather
than per-class.

7.11 Using JSR 330 Standard Annotations

Starting with Spring 3.0, Spring offers support for JSR-330 standard annotations
(Dependency Injection). Those annotations are scanned in the same way as the Spring
annotations. You just need to have the relevant jars in your classpath.

If you are using Maven, the javax.inject artifact is available in the

standard Maven repository ( http://repo1.maven.org/maven2/javax/inject
/javax.inject/1/). You can add the following dependency to your file pom.xml:
<dependency>
<groupId>javax.inject</groupId>
<artifactId>javax.inject</artifactId>
<version>1</version>
</dependency>

25/08/2016 12:10

Spring Framework Reference Documentation

183 de 1194

7.11.1 Dependency Injection with @Inject and @Named

Instead of @Autowired , @javax.inject.Inject may be used as follows:
import javax.inject.Inject;
public class SimpleMovieLister {
private MovieFinder movieFinder;
@Inject
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
public void listMovies() {
this.movieFinder.findMovies(...);
...
}
}

As with @Autowired , it is possible to use @Inject at the field level, method level and
constructor-argument level. Furthermore, you may declare your injection point as a
Provider , allowing for on-demand access to beans of shorter scopes or lazy access to
other beans through a Provider.get() call. As a variant of the example above:
import javax.inject.Inject;
import javax.inject.Provider;
public class SimpleMovieLister {
private Provider<MovieFinder> movieFinder;
public void listMovies() {
this.movieFinder.get().findMovies(...);
...
}
}

If you would like to use a qualified name for the dependency that should be injected, you
should use the @Named annotation as follows:
import javax.inject.Inject;
import javax.inject.Named;
public class SimpleMovieLister {

25/08/2016 12:10

Spring Framework Reference Documentation

184 de 1194

private MovieFinder movieFinder;

@Inject
public void setMovieFinder(@Named("main") MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
// ...
}

7.11.2 @Named: a standard equivalent to the @Component

annotation
Instead of @Component , @javax.inject.Named may be used as follows:
import javax.inject.Inject;
import javax.inject.Named;
@Named("movieListener")
public class SimpleMovieLister {
private MovieFinder movieFinder;
@Inject
public void setMovieFinder(MovieFinder movieFinder) {
this.movieFinder = movieFinder;
}
// ...
}

It is very common to use @Component without specifying a name for the component.
@Named can be used in a similar fashion:
import javax.inject.Inject;
import javax.inject.Named;
@Named
public class SimpleMovieLister {
private MovieFinder movieFinder;
@Inject
public void setMovieFinder(MovieFinder movieFinder) {

25/08/2016 12:10

Spring Framework Reference Documentation

185 de 1194

}
// ...
}

When using @Named , it is possible to use component scanning in the exact same way as
when using Spring annotations:
@Configuration
@ComponentScan(basePackages = "org.example")
public class AppConfig {
...
}

In contrast to @Component , the JSR-330 @Named annotation is not

composable. Please use Springs stereotype model for building custom
component annotations.

7.11.3 Limitations of JSR-330 standard annotations

When working with standard annotations, it is important to know that some significant
features are not available as shown in the table below:

Table 7.6. Spring component model elements vs. JSR-330 variants

Spring
@Autowired

javax.inject.*
@Inject

javax.inject restrictions / comments

@Inject has no 'required' attribute;
can be used with Java 8s Optional
instead.

@Component

@Named

JSR-330 does not provide a

composable model, just a way to
identify named components.

@Scope("singleton") @Singleton

The JSR-330 default scope is like

Springs prototype . However, in order
to keep it consistent with Springs
general defaults, a JSR-330 bean
declared in the Spring container is a
singleton by default. In order to use a

25/08/2016 12:10

Spring Framework Reference Documentation

186 de 1194

Spring

javax.inject.*

javax.inject restrictions / comments

scope other than singleton , you
should use Springs @Scope
annotation. javax.inject also
provides a @Scope annotation.
Nevertheless, this one is only intended
to be used for creating your own
annotations.

@Qualifier

@Qualifier /

javax.inject.Qualifier is just a

@Named

meta-annotation for building custom

qualifiers. Concrete String qualifiers (like
Springs @Qualifier with a value) can
be associated through
javax.inject.Named .

@Value

no equivalent

@Required

no equivalent

@Lazy

no equivalent

ObjectFactory

Provider

javax.inject.Provider is a direct
alternative to Springs ObjectFactory ,
just with a shorter get() method
name. It can also be used in
combination with Springs @Autowired
or with non-annotated constructors and
setter methods.

7.12 Java-based container configuration

7.12.1 Basic concepts: @Bean and @Configuration
The central artifacts in Springs new Java-configuration support are @Configuration annotated classes and @Bean -annotated methods.
The @Bean annotation is used to indicate that a method instantiates, configures and

25/08/2016 12:10

Spring Framework Reference Documentation

187 de 1194

initializes a new object to be managed by the Spring IoC container. For those familiar with
Springs <beans/> XML configuration the @Bean annotation plays the same role as the
<bean/> element. You can use @Bean annotated methods with any Spring
@Component , however, they are most often used with @Configuration beans.
Annotating a class with @Configuration indicates that its primary purpose is as a
source of bean definitions. Furthermore, @Configuration classes allow inter-bean
dependencies to be defined by simply calling other @Bean methods in the same class.
The simplest possible @Configuration class would read as follows:
@Configuration
public class AppConfig {
@Bean
public MyService myService() {
return new MyServiceImpl();
}
}

The AppConfig class above would be equivalent to the following Spring <beans/>
XML:
<beans>
<bean id="myService" class="com.acme.services.MyServiceImpl"/>
</beans>

Full @Configuration vs 'lite' @Beans mode?

When @Bean methods are declared within classes that are not annotated with
@Configuration they are referred to as being processed in a 'lite' mode. For
example, bean methods declared in a @Component or even in a plain old class will
be considered 'lite'.
Unlike full @Configuration , lite @Bean methods cannot easily declare inter-bean
dependencies. Usually one @Bean method should not invoke another @Bean
method when operating in 'lite' mode.
Only using @Bean methods within @Configuration classes is a recommended
approach of ensuring that 'full' mode is always used. This will prevent the same
@Bean method from accidentally being invoked multiple times and helps to reduce
subtle bugs that can be hard to track down when operating in 'lite' mode.
The @Bean and @Configuration annotations will be discussed in depth in the sections

25/08/2016 12:10

Spring Framework Reference Documentation

188 de 1194

Java-based configuration.

7.12.2 Instantiating the Spring container using

AnnotationConfigApplicationContext
The sections below document Springs AnnotationConfigApplicationContext , new
in Spring 3.0. This versatile ApplicationContext implementation is capable of
accepting not only @Configuration classes as input, but also plain @Component
classes and classes annotated with JSR-330 metadata.
When @Configuration classes are provided as input, the @Configuration class itself
is registered as a bean definition, and all declared @Bean methods within the class are
also registered as bean definitions.
When @Component and JSR-330 classes are provided, they are registered as bean
definitions, and it is assumed that DI metadata such as @Autowired or @Inject are
used within those classes where necessary.

Simple construction
In much the same way that Spring XML files are used as input when instantiating a
ClassPathXmlApplicationContext , @Configuration classes may be used as input
when instantiating an AnnotationConfigApplicationContext . This allows for
completely XML-free usage of the Spring container:
public static void main(String[] args) {
ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.
MyService myService = ctx.getBean(MyService.class);
myService.doStuff();
}

As mentioned above, AnnotationConfigApplicationContext is not limited to working

only with @Configuration classes. Any @Component or JSR-330 annotated class may
be supplied as input to the constructor. For example:
public static void main(String[] args) {
ApplicationContext ctx = new AnnotationConfigApplicationContext(MyServiceImpl.
MyService myService = ctx.getBean(MyService.class);
myService.doStuff();
}

The above assumes that MyServiceImpl , Dependency1 and Dependency2 use Spring

25/08/2016 12:10

Spring Framework Reference Documentation

189 de 1194

Building the container programmatically using register(Class<?>)

An AnnotationConfigApplicationContext may be instantiated using a no-arg
constructor and then configured using the register() method. This approach is
particularly useful when programmatically building an
AnnotationConfigApplicationContext .

public static void main(String[] args) {

AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
ctx.register(AppConfig.class, OtherConfig.class);
ctx.register(AdditionalConfig.class);
ctx.refresh();
MyService myService = ctx.getBean(MyService.class);
myService.doStuff();
}

Enabling component scanning with scan(String)

To enable component scanning, just annotate your @Configuration class as follows:
@Configuration
@ComponentScan(basePackages = "com.acme")
public class AppConfig {
...
}

Experienced Spring users will be familiar with the XML declaration

equivalent from Springs context: namespace
<beans>
<context:component-scan base-package="com.acme"/>
</beans>

In the example above, the com.acme package will be scanned, looking for any
@Component -annotated classes, and those classes will be registered as Spring bean
definitions within the container. AnnotationConfigApplicationContext exposes the
scan(String) method to allow for the same component-scanning functionality:

public static void main(String[] args) {

AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
ctx.scan("com.acme");
ctx.refresh();
MyService myService = ctx.getBean(MyService.class);

25/08/2016 12:10

Spring Framework Reference Documentation

190 de 1194

Remember that @Configuration classes are meta-annotated with

@Component , so they are candidates for component-scanning! In the
example above, assuming that AppConfig is declared within the
com.acme package (or any package underneath), it will be picked up
during the call to scan() , and upon refresh() all its @Bean methods will
be processed and registered as bean definitions within the container.

Support for web applications with

AnnotationConfigWebApplicationContext
A WebApplicationContext variant of AnnotationConfigApplicationContext is
available with AnnotationConfigWebApplicationContext . This implementation may
be used when configuring the Spring ContextLoaderListener servlet listener, Spring
MVC DispatcherServlet , etc. What follows is a web.xml snippet that configures a
typical Spring MVC web application. Note the use of the contextClass context-param
and init-param:

<web-app>

<context-param>
<param-name>contextClass</param-name>
<param-value>
org.springframework.web.context.support.AnnotationConfigWebApplicationCont
</param-value>
</context-param>

<!-- Configuration locations must consist of one or more comma- or space-delimited

fully-qualified @Configuration classes. Fully-qualified packages may also be
specified for component-scanning -->
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>com.acme.AppConfig</param-value>
</context-param>

<servlet>
<servlet-name>dispatcher</servlet-name>

25/08/2016 12:10

Spring Framework Reference Documentation

191 de 1194

<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-clas

<init-param>
<param-name>contextClass</param-name>
<param-value>
org.springframework.web.context.support.AnnotationConfigWebApplication
</param-value>
</init-param>

<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>com.acme.web.MvcConfig</param-value>
</init-param>
</servlet>

<servlet-mapping>
<servlet-name>dispatcher</servlet-name>
<url-pattern>/app/*</url-pattern>
</servlet-mapping>
</web-app>

7.12.3 Using the @Bean annotation

@Bean is a method-level annotation and a direct analog of the XML <bean/> element.
The annotation supports some of the attributes offered by <bean/> , such as:
init-method, destroy-method, autowiring and name .
You can use the @Bean annotation in a @Configuration -annotated or in a
@Component -annotated class.

Declaring a bean
To declare a bean, simply annotate a method with the @Bean annotation. You use this
method to register a bean definition within an ApplicationContext of the type specified
as the methods return value. By default, the bean name will be the same as the method
name. The following is a simple example of a @Bean method declaration:
@Configuration
public class AppConfig {
@Bean
public TransferService transferService() {

25/08/2016 12:10

Spring Framework Reference Documentation

192 de 1194

return new TransferServiceImpl();

}
}

The preceding configuration is exactly equivalent to the following Spring XML:

Both declarations make a bean named transferService available in the

ApplicationContext , bound to an object instance of type TransferServiceImpl :
transferService -> com.acme.TransferServiceImpl

Bean dependencies
A @Bean annotated method can have an arbitrary number of parameters describing the
dependencies required to build that bean. For instance if our TransferService requires
an AccountRepository we can materialize that dependency via a method parameter:
@Configuration
public class AppConfig {
@Bean
public TransferService transferService(AccountRepository accountRepository) {
return new TransferServiceImpl(accountRepository);
}
}

The resolution mechanism is pretty much identical to constructor-based dependency

injection, see the relevant section for more details.

Receiving lifecycle callbacks

Any classes defined with the @Bean annotation support the regular lifecycle callbacks
and can use the @PostConstruct and @PreDestroy annotations from JSR-250, see
JSR-250 annotations for further details.
The regular Spring lifecycle callbacks are fully supported as well. If a bean implements
InitializingBean , DisposableBean , or Lifecycle , their respective methods are
called by the container.

25/08/2016 12:10

Spring Framework Reference Documentation

193 de 1194

MessageSourceAware, ApplicationContextAware, and so on are also fully supported.

The @Bean annotation supports specifying arbitrary initialization and destruction callback
methods, much like Spring XMLs init-method and destroy-method attributes on the
bean element:
public class Foo {
public void init() {
// initialization logic
}
}
public class Bar {
public void cleanup() {
// destruction logic
}
}
@Configuration
public class AppConfig {
@Bean(initMethod = "init")
public Foo foo() {
return new Foo();
}
@Bean(destroyMethod = "cleanup")
public Bar bar() {
return new Bar();
}
}

By default, beans defined using Java config that have a public close or
shutdown method are automatically enlisted with a destruction callback. If
you have a public close or shutdown method and you do not wish for it
to be called when the container shuts down, simply add
@Bean(destroyMethod="") to your bean definition to disable the default
(inferred) mode.
You may want to do that by default for a resource that you acquire via JNDI
as its lifecycle is managed outside the application. In particular, make sure
to always do it for a DataSource as it is known to be problematic on Java
EE application servers.
@Bean(destroyMethod="")

25/08/2016 12:10

Spring Framework Reference Documentation

194 de 1194

public DataSource dataSource() throws NamingException {

return (DataSource) jndiTemplate.lookup("MyDS");
}

Also, with @Bean methods, you will typically choose to use programmatic
JNDI lookups: either using Springs
JndiTemplate / JndiLocatorDelegate helpers or straight JNDI
InitialContext usage, but not the JndiObjectFactoryBean variant
which would force you to declare the return type as the FactoryBean type
instead of the actual target type, making it harder to use for cross-reference
calls in other @Bean methods that intend to refer to the provided resource
here.

Of course, in the case of Foo above, it would be equally as valid to call the init()
method directly during construction:
@Configuration
public class AppConfig {
@Bean
public Foo foo() {
Foo foo = new Foo();
foo.init();
return foo;
}
// ...
}

When you work directly in Java, you can do anything you like with your
objects and do not always need to rely on the container lifecycle!

Specifying bean scope

Using the @Scope annotation
You can specify that your beans defined with the @Bean annotation should have a
specific scope. You can use any of the standard scopes specified in the Bean Scopes
section.
The default scope is singleton , but you can override this with the @Scope annotation:

25/08/2016 12:10

Spring Framework Reference Documentation

195 de 1194

@Configuration
public class MyConfiguration {
@Bean
@Scope("prototype")
public Encryptor encryptor() {
// ...
}
}

@Scope and scoped-proxy

Spring offers a convenient way of working with scoped dependencies through scoped
proxies. The easiest way to create such a proxy when using the XML configuration is the
<aop:scoped-proxy/> element. Configuring your beans in Java with a @Scope
annotation offers equivalent support with the proxyMode attribute. The default is no proxy
( ScopedProxyMode.NO ), but you can specify ScopedProxyMode.TARGET_CLASS or
ScopedProxyMode.INTERFACES .
If you port the scoped proxy example from the XML reference documentation (see
preceding link) to our @Bean using Java, it would look like the following:
// an HTTP Session-scoped bean exposed as a proxy
@Bean
@SessionScope
public UserPreferences userPreferences() {
return new UserPreferences();
}
@Bean
public Service userService() {
UserService service = new SimpleUserService();
// a reference to the proxied userPreferences bean
service.setUserPreferences(userPreferences());
return service;
}

Customizing bean naming

By default, configuration classes use a @Bean methods name as the name of the
resulting bean. This functionality can be overridden, however, with the name attribute.
@Configuration

25/08/2016 12:10

Spring Framework Reference Documentation

196 de 1194

@Bean(name = "myFoo")
public Foo foo() {
return new Foo();
}
}

Bean aliasing
As discussed in Section 7.3.1, Naming beans, it is sometimes desirable to give a single
bean multiple names, otherwise known as bean aliasing. The name attribute of the
@Bean annotation accepts a String array for this purpose.
@Configuration
public class AppConfig {
@Bean(name = { "dataSource", "subsystemA-dataSource", "subsystemB-dataSource" })
public DataSource dataSource() {
// instantiate, configure and return DataSource bean...
}
}

Bean description
Sometimes it is helpful to provide a more detailed textual description of a bean. This can
be particularly useful when beans are exposed (perhaps via JMX) for monitoring
purposes.
To add a description to a @Bean the @Description annotation can be used:
@Configuration
public class AppConfig {
@Bean
@Description("Provides a basic example of a bean")
public Foo foo() {
return new Foo();
}
}

7.12.4 Using the @Configuration annotation

25/08/2016 12:10

Spring Framework Reference Documentation

197 de 1194

@Configuration is a class-level annotation indicating that an object is a source of bean

definitions. @Configuration classes declare beans via public @Bean annotated
methods. Calls to @Bean methods on @Configuration classes can also be used to
define inter-bean dependencies. See Section 7.12.1, Basic concepts: @Bean and
@Configuration for a general introduction.

Injecting inter-bean dependencies

When @Bean s have dependencies on one another, expressing that dependency is as
simple as having one bean method call another:
@Configuration
public class AppConfig {
@Bean
public Foo foo() {
return new Foo(bar());
}
@Bean
public Bar bar() {
return new Bar();
}
}

In the example above, the foo bean receives a reference to bar via constructor
injection.

This method of declaring inter-bean dependencies only works when the

@Bean method is declared within a @Configuration class. You cannot
declare inter-bean dependencies using plain @Component classes.

Lookup method injection

As noted earlier, lookup method injection is an advanced feature that you should use
rarely. It is useful in cases where a singleton-scoped bean has a dependency on a
prototype-scoped bean. Using Java for this type of configuration provides a natural
means for implementing this pattern.
public abstract class CommandManager {
public Object process(Object commandState) {

25/08/2016 12:10

Spring Framework Reference Documentation

198 de 1194

// grab a new instance of the appropriate Command interface

Command command = createCommand();
// set the state on the (hopefully brand new) Command instance
command.setState(commandState);
return command.execute();
}
// okay... but where is the implementation of this method?
protected abstract Command createCommand();
}

Using Java-configuration support , you can create a subclass of CommandManager where

the abstract createCommand() method is overridden in such a way that it looks up a
new (prototype) command object:
@Bean
@Scope("prototype")
public AsyncCommand asyncCommand() {
AsyncCommand command = new AsyncCommand();
// inject dependencies here as required
return command;
}

@Bean
public CommandManager commandManager() {
// return new anonymous implementation of CommandManager with command() overridden
// to return a new prototype Command object
return new CommandManager() {
protected Command createCommand() {
return asyncCommand();
}
}
}

Further information about how Java-based configuration works internally

The following example shows a @Bean annotated method being called twice:
@Configuration
public class AppConfig {
@Bean
public ClientService clientService1() {
ClientServiceImpl clientService = new ClientServiceImpl();
clientService.setClientDao(clientDao());

25/08/2016 12:10

Spring Framework Reference Documentation

199 de 1194

return clientService;
}
@Bean
public ClientService clientService2() {
ClientServiceImpl clientService = new ClientServiceImpl();
clientService.setClientDao(clientDao());
return clientService;
}
@Bean
public ClientDao clientDao() {
return new ClientDaoImpl();
}
}

clientDao() has been called once in clientService1() and once in

clientService2() . Since this method creates a new instance of ClientDaoImpl and
returns it, you would normally expect having 2 instances (one for each service). That
definitely would be problematic: in Spring, instantiated beans have a singleton scope
by default. This is where the magic comes in: All @Configuration classes are
subclassed at startup-time with CGLIB . In the subclass, the child method checks the
container first for any cached (scoped) beans before it calls the parent method and
creates a new instance. Note that as of Spring 3.2, it is no longer necessary to add
CGLIB to your classpath because CGLIB classes have been repackaged under
org.springframework.cglib and included directly within the spring-core JAR.

The behavior could be different according to the scope of your bean. We

are talking about singletons here.

There are a few restrictions due to the fact that CGLIB dynamically adds
features at startup-time:
Configuration classes should not be final
They should have a constructor with no arguments

7.12.5 Composing Java-based configurations

Using the @Import annotation

25/08/2016 12:10

Spring Framework Reference Documentation

200 de 1194

Much as the <import/> element is used within Spring XML files to aid in modularizing
configurations, the @Import annotation allows for loading @Bean definitions from
another configuration class:
@Configuration
public class ConfigA {
@Bean
public A a() {
return new A();
}
}
@Configuration
@Import(ConfigA.class)
public class ConfigB {
@Bean
public B b() {
return new B();
}
}

Now, rather than needing to specify both ConfigA.class and ConfigB.class when
instantiating the context, only ConfigB needs to be supplied explicitly:
public static void main(String[] args) {
ApplicationContext ctx = new AnnotationConfigApplicationContext(ConfigB.
// now both beans A and B will be available...
A a = ctx.getBean(A.class);
B b = ctx.getBean(B.class);
}

This approach simplifies container instantiation, as only one class needs to be dealt with,
rather than requiring the developer to remember a potentially large number of
@Configuration classes during construction.

Injecting dependencies on imported @Bean definitions

The example above works, but is simplistic. In most practical scenarios, beans will have
dependencies on one another across configuration classes. When using XML, this is not
an issue, per se, because there is no compiler involved, and one can simply declare

25/08/2016 12:10

Spring Framework Reference Documentation

201 de 1194

ref="someBean" and trust that Spring will work it out during container initialization. Of
course, when using @Configuration classes, the Java compiler places constraints on
the configuration model, in that references to other beans must be valid Java syntax.
Fortunately, solving this problem is simple. As we already discussed, @Bean method can
have an arbitrary number of parameters describing the bean dependencies. Lets
consider a more real-world scenario with several @Configuration classes, each
depending on beans declared in the others:
@Configuration
public class ServiceConfig {
@Bean
public TransferService transferService(AccountRepository accountRepository) {
return new TransferServiceImpl(accountRepository);
}
}
@Configuration
public class RepositoryConfig {
@Bean
public AccountRepository accountRepository(DataSource dataSource) {
return new JdbcAccountRepository(dataSource);
}
}
@Configuration
@Import({ServiceConfig.class, RepositoryConfig.class})
public class SystemTestConfig {
@Bean
public DataSource dataSource() {
// return new DataSource
}
}
public static void main(String[] args) {
ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.
// everything wires up across configuration classes...
TransferService transferService = ctx.getBean(TransferService.class);
transferService.transfer(100.00, "A123", "C456");
}

25/08/2016 12:10

Spring Framework Reference Documentation

202 de 1194

There is another way to achieve the same result. Remember that @Configuration
classes are ultimately just another bean in the container: This means that they can take
advantage of @Autowired and @Value injection etc just like any other bean!

Make sure that the dependencies you inject that way are of the simplest
kind only. @Configuration classes are processed quite early during the
initialization of the context and forcing a dependency to be injected this way
may lead to unexpected early initialization. Whenever possible, resort to
parameter-based injection as in the example above.
Also, be particularly careful with BeanPostProcessor and
BeanFactoryPostProcessor definitions via @Bean . Those should usually
be declared as static @Bean methods, not triggering the instantiation of
their containing configuration class. Otherwise, @Autowired and @Value
wont work on the configuration class itself since it is being created as a
bean instance too early.

@Configuration
public class ServiceConfig {
@Autowired
private AccountRepository accountRepository;
@Bean
public TransferService transferService() {
return new TransferServiceImpl(accountRepository);
}
}
@Configuration
public class RepositoryConfig {
private final DataSource dataSource;
@Autowired
public RepositoryConfig(DataSource dataSource) {
this.dataSource = dataSource;
}
@Bean
public AccountRepository accountRepository() {
return new JdbcAccountRepository(dataSource);
}

25/08/2016 12:10

Spring Framework Reference Documentation

203 de 1194

}
@Configuration
@Import({ServiceConfig.class, RepositoryConfig.class})
public class SystemTestConfig {
@Bean
public DataSource dataSource() {
// return new DataSource
}
}
public static void main(String[] args) {
ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.
// everything wires up across configuration classes...
TransferService transferService = ctx.getBean(TransferService.class);
transferService.transfer(100.00, "A123", "C456");
}

Constructor injection in @Configuration classes is only supported as of

Spring Framework 4.3. Note also that there is no need to specify
@Autowired if the target bean defines only one constructor; in the example
above, @Autowired is not necessary on the RepositoryConfig
constructor.

In the scenario above, using @Autowired works well and provides the desired
modularity, but determining exactly where the autowired bean definitions are declared is
still somewhat ambiguous. For example, as a developer looking at ServiceConfig , how
do you know exactly where the @Autowired AccountRepository bean is declared? Its
not explicit in the code, and this may be just fine. Remember that the Spring Tool Suite
provides tooling that can render graphs showing how everything is wired up - that may be
all you need. Also, your Java IDE can easily find all declarations and uses of the
AccountRepository type, and will quickly show you the location of @Bean methods
that return that type.
In cases where this ambiguity is not acceptable and you wish to have direct navigation
from within your IDE from one @Configuration class to another, consider autowiring
the configuration classes themselves:
@Configuration
public class ServiceConfig {

25/08/2016 12:10

Spring Framework Reference Documentation

204 de 1194

@Autowired
private RepositoryConfig repositoryConfig;
@Bean
public TransferService transferService() {
// navigate 'through' the config class to the @Bean method!
return new TransferServiceImpl(repositoryConfig.accountRepository());
}
}

In the situation above, it is completely explicit where AccountRepository is defined.

However, ServiceConfig is now tightly coupled to RepositoryConfig ; thats the
tradeoff. This tight coupling can be somewhat mitigated by using interface-based or
abstract class-based @Configuration classes. Consider the following:
@Configuration
public class ServiceConfig {
@Autowired
private RepositoryConfig repositoryConfig;
@Bean
public TransferService transferService() {
return new TransferServiceImpl(repositoryConfig.accountRepository());
}
}
@Configuration
public interface RepositoryConfig {
@Bean
AccountRepository accountRepository();
}
@Configuration
public class DefaultRepositoryConfig implements RepositoryConfig {
@Bean
public AccountRepository accountRepository() {
return new JdbcAccountRepository(...);
}
}

25/08/2016 12:10

Spring Framework Reference Documentation

205 de 1194

@Configuration
@Import({ServiceConfig.class, DefaultRepositoryConfig.class}) // import the concrete c
public class SystemTestConfig {
@Bean
public DataSource dataSource() {
// return DataSource
}
}
public static void main(String[] args) {
ApplicationContext ctx = new AnnotationConfigApplicationContext(SystemTestConfig.
TransferService transferService = ctx.getBean(TransferService.class);
transferService.transfer(100.00, "A123", "C456");
}

Now ServiceConfig is loosely coupled with respect to the concrete

DefaultRepositoryConfig , and built-in IDE tooling is still useful: it will be easy for the
developer to get a type hierarchy of RepositoryConfig implementations. In this way,
navigating @Configuration classes and their dependencies becomes no different than
the usual process of navigating interface-based code.

Conditionally include @Configuration classes or @Bean methods

It is often useful to conditionally enable or disable a complete @Configuration class, or
even individual @Bean methods, based on some arbitrary system state. One common
example of this is to use the @Profile annotation to activate beans only when a specific
profile has been enabled in the Spring Environment (see Section 7.13.1, Bean
definition profiles for details).
The @Profile annotation is actually implemented using a much more flexible annotation
called @Conditional . The @Conditional annotation indicates specific
org.springframework.context.annotation.Condition implementations that should
be consulted before a @Bean is registered.
Implementations of the Condition interface simply provide a matches() method that
returns true or false . For example, here is the actual Condition implementation
used for @Profile :
@Override
public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
if (context.getEnvironment() != null) {
// Read the @Profile annotation attributes

25/08/2016 12:10

Spring Framework Reference Documentation

206 de 1194

if (attrs != null) {
for (Object value : attrs.get("value")) {
if (context.getEnvironment().acceptsProfiles(((String[]) value))) {
return true;
}
}
return false;
}
}
return true;
}

See the @Conditional javadocs for more detail.

Combining Java and XML configuration

Springs @Configuration class support does not aim to be a 100% complete
replacement for Spring XML. Some facilities such as Spring XML namespaces remain an
ideal way to configure the container. In cases where XML is convenient or necessary, you
have a choice: either instantiate the container in an "XML-centric" way using, for example,
ClassPathXmlApplicationContext , or in a "Java-centric" fashion using
AnnotationConfigApplicationContext and the @ImportResource annotation to
import XML as needed.

XML-centric use of @Configuration classes

It may be preferable to bootstrap the Spring container from XML and include
@Configuration classes in an ad-hoc fashion. For example, in a large existing
codebase that uses Spring XML, it will be easier to create @Configuration classes on
an as-needed basis and include them from the existing XML files. Below youll find the
options for using @Configuration classes in this kind of "XML-centric" situation.
Remember that @Configuration classes are ultimately just bean definitions in the
container. In this example, we create a @Configuration class named AppConfig and
include it within system-test-config.xml as a <bean/> definition. Because
<context:annotation-config/> is switched on, the container will recognize the
@Configuration annotation and process the @Bean methods declared in AppConfig
properly.
@Configuration
public class AppConfig {
@Autowired

25/08/2016 12:10

Spring Framework Reference Documentation

207 de 1194

@Bean
public AccountRepository accountRepository() {
return new JdbcAccountRepository(dataSource);
}
@Bean
public TransferService transferService() {
return new TransferService(accountRepository());
}
}

system-test-config.xml:
<beans>

<context:annotation-config/>
<context:property-placeholder location="classpath:/com/acme/jdbc.properties"
<bean class="com.acme.AppConfig"/>
<bean class="org.springframework.jdbc.datasource.DriverManagerDataSource"
<property name="url" value="${jdbc.url}"/>
<property name="username" value="${jdbc.username}"/>
<property name="password" value="${jdbc.password}"/>
</bean>
</beans>

jdbc.properties:
jdbc.url=jdbc:hsqldb:hsql://localhost/xdb
jdbc.username=sa
jdbc.password=

public static void main(String[] args) {

ApplicationContext ctx = new ClassPathXmlApplicationContext("classpath:/com/acme/s
TransferService transferService = ctx.getBean(TransferService.class);
// ...
}

25/08/2016 12:10

Spring Framework Reference Documentation

208 de 1194

In system-test-config.xml above, the AppConfig <bean/> does not

declare an id element. While it would be acceptable to do so, it is
unnecessary given that no other bean will ever refer to it, and it is unlikely
that it will be explicitly fetched from the container by name. Likewise with
the DataSource bean - it is only ever autowired by type, so an explicit
bean id is not strictly required.

Because @Configuration is meta-annotated with @Component , @Configuration annotated classes are automatically candidates for component scanning. Using the same
scenario as above, we can redefine system-test-config.xml to take advantage of
component-scanning. Note that in this case, we dont need to explicitly declare
<context:annotation-config/> , because <context:component-scan/> enables
the same functionality.
system-test-config.xml:
<beans>

<context:component-scan base-package="com.acme"/>
<context:property-placeholder location="classpath:/com/acme/jdbc.properties"
<bean class="org.springframework.jdbc.datasource.DriverManagerDataSource"
<property name="url" value="${jdbc.url}"/>
<property name="username" value="${jdbc.username}"/>
<property name="password" value="${jdbc.password}"/>
</bean>
</beans>

@Configuration class-centric use of XML with @ImportResource

In applications where @Configuration classes are the primary mechanism for
configuring the container, it will still likely be necessary to use at least some XML. In these
scenarios, simply use @ImportResource and define only as much XML as is needed.
Doing so achieves a "Java-centric" approach to configuring the container and keeps XML
to a bare minimum.
@Configuration
@ImportResource("classpath:/com/acme/properties-config.xml")
public class AppConfig {
@Value("${jdbc.url}")
private String url;

25/08/2016 12:10

Spring Framework Reference Documentation

209 de 1194

@Value("${jdbc.username}")
private String username;
@Value("${jdbc.password}")
private String password;
@Bean
public DataSource dataSource() {
return new DriverManagerDataSource(url, username, password);
}
}
properties-config.xml
<beans>
<context:property-placeholder location="classpath:/com/acme/jdbc.properties"
</beans>
jdbc.properties
jdbc.url=jdbc:hsqldb:hsql://localhost/xdb
jdbc.username=sa
jdbc.password=

public static void main(String[] args) {

ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.
TransferService transferService = ctx.getBean(TransferService.class);
// ...
}

7.13 Environment abstraction

The Environment is an abstraction integrated in the container that models two key
aspects of the application environment: profiles and properties.
A profile is a named, logical group of bean definitions to be registered with the container
only if the given profile is active. Beans may be assigned to a profile whether defined in
XML or via annotations. The role of the Environment object with relation to profiles is in
determining which profiles (if any) are currently active, and which profiles (if any) should
be active by default.
Properties play an important role in almost all applications, and may originate from a
variety of sources: properties files, JVM system properties, system environment variables,
JNDI, servlet context parameters, ad-hoc Properties objects, Maps, and so on. The role
of the Environment object with relation to properties is to provide the user with a

25/08/2016 12:10

Spring Framework Reference Documentation

210 de 1194

from them.

7.13.1 Bean definition profiles

Bean definition profiles is a mechanism in the core container that allows for registration of
different beans in different environments. The word environment can mean different
things to different users and this feature can help with many use cases, including:
working against an in-memory datasource in development vs looking up that same
datasource from JNDI when in QA or production
registering monitoring infrastructure only when deploying an application into a
performance environment
registering customized implementations of beans for customer A vs. customer B
deployments
Lets consider the first use case in a practical application that requires a DataSource . In
a test environment, the configuration may look like this:
@Bean
public DataSource dataSource() {
return new EmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("my-schema.sql")
.addScript("my-test-data.sql")
.build();
}

Lets now consider how this application will be deployed into a QA or production
environment, assuming that the datasource for the application will be registered with the
production application servers JNDI directory. Our dataSource bean now looks like this:
@Bean(destroyMethod="")
public DataSource dataSource() throws Exception {
Context ctx = new InitialContext();
return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource");
}

The problem is how to switch between using these two variations based on the current
environment. Over time, Spring users have devised a number of ways to get this done,
usually relying on a combination of system environment variables and XML <import/>
statements containing ${placeholder} tokens that resolve to the correct configuration
file path depending on the value of an environment variable. Bean definition profiles is a
core container feature that provides a solution to this problem.

25/08/2016 12:10

Spring Framework Reference Documentation

211 de 1194

If we generalize the example use case above of environment-specific bean definitions, we

end up with the need to register certain bean definitions in certain contexts, while not in
others. You could say that you want to register a certain profile of bean definitions in
situation A, and a different profile in situation B. Lets first see how we can update our
configuration to reflect this need.

@Profile
The @Profile annotation allows you to indicate that a component is eligible for
registration when one or more specified profiles are active. Using our example above, we
can rewrite the dataSource configuration as follows:
@Configuration
@Profile("dev")
public class StandaloneDataConfig {
@Bean
public DataSource dataSource() {
return new EmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("classpath:com/bank/config/sql/schema.sql")
.addScript("classpath:com/bank/config/sql/test-data.sql")
.build();
}
}
@Configuration
@Profile("production")
public class JndiDataConfig {
@Bean(destroyMethod="")
public DataSource dataSource() throws Exception {
Context ctx = new InitialContext();
return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource");
}
}

As mentioned before, with @Bean methods, you will typically choose to use
programmatic JNDI lookups: either using Springs
JndiTemplate / JndiLocatorDelegate helpers or the straight JNDI
InitialContext usage shown above, but not the
JndiObjectFactoryBean variant which would force you to declare the
return type as the FactoryBean type.

25/08/2016 12:10

Spring Framework Reference Documentation

212 de 1194

@Profile can be used as a meta-annotation for the purpose of creating a custom

composed annotation. The following example defines a custom @Production annotation
that can be used as a drop-in replacement for @Profile("production") :
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Profile("production")
public @interface Production {
}

@Profile can also be declared at the method level to include only one particular bean of
a configuration class:
@Configuration
public class AppConfig {
@Bean
@Profile("dev")
public DataSource devDataSource() {
return new EmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("classpath:com/bank/config/sql/schema.sql")
.addScript("classpath:com/bank/config/sql/test-data.sql")
.build();
}
@Bean
@Profile("production")
public DataSource productionDataSource() throws Exception {
Context ctx = new InitialContext();
return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource");
}
}

25/08/2016 12:10

Spring Framework Reference Documentation

213 de 1194

If a @Configuration class is marked with @Profile , all of the @Bean

methods and @Import annotations associated with that class will be
bypassed unless one or more of the specified profiles are active. If a
@Component or @Configuration class is marked with
@Profile({"p1", "p2"}) , that class will not be registered/processed
unless profiles 'p1' and/or 'p2' have been activated. If a given profile is
prefixed with the NOT operator ( ! ), the annotated element will be
registered if the profile is not active. For example, given
@Profile({"p1", "!p2"}) , registration will occur if profile 'p1' is active or
if profile 'p2' is not active.

7.13.2 XML bean definition profiles

The XML counterpart is the profile attribute of the <beans> element. Our sample
configuration above can be rewritten in two XML files as follows:
<beans profile="dev"
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jdbc="http://www.springframework.org/schema/jdbc"
xsi:schemaLocation="...">
<jdbc:embedded-database id="dataSource">
<jdbc:script location="classpath:com/bank/config/sql/schema.sql"/>
<jdbc:script location="classpath:com/bank/config/sql/test-data.sql"/>
</jdbc:embedded-database>
</beans>
<beans profile="production"
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jee="http://www.springframework.org/schema/jee"
xsi:schemaLocation="...">
<jee:jndi-lookup id="dataSource" jndi-name="java:comp/env/jdbc/datasource"
</beans>

It is also possible to avoid that split and nest <beans/> elements within the same file:
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jdbc="http://www.springframework.org/schema/jdbc"

25/08/2016 12:10

Spring Framework Reference Documentation

214 de 1194

xmlns:jee="http://www.springframework.org/schema/jee"
xsi:schemaLocation="...">

<beans profile="dev">
<jdbc:embedded-database id="dataSource">
<jdbc:script location="classpath:com/bank/config/sql/schema.sql"
<jdbc:script location="classpath:com/bank/config/sql/test-data.sql"
</jdbc:embedded-database>
</beans>
<beans profile="production">
<jee:jndi-lookup id="dataSource" jndi-name="java:comp/env/jdbc/datasource"
</beans>
</beans>

The spring-bean.xsd has been constrained to allow such elements only as the last
ones in the file. This should help provide flexibility without incurring clutter in the XML
files.

Activating a profile
Now that we have updated our configuration, we still need to instruct Spring which profile
is active. If we started our sample application right now, we would see a
NoSuchBeanDefinitionException thrown, because the container could not find the
Spring bean named dataSource .
Activating a profile can be done in several ways, but the most straightforward is to do it
programmatically against the Environment API which is available via an
ApplicationContext :
AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
ctx.getEnvironment().setActiveProfiles("dev");
ctx.register(SomeConfig.class, StandaloneDataConfig.class, JndiDataConfig.class
ctx.refresh();

In addition, profiles may also be activated declaratively through the

spring.profiles.active property which may be specified through system
environment variables, JVM system properties, servlet context parameters in web.xml ,
or even as an entry in JNDI (see Section 7.13.3, PropertySource abstraction). In
integration tests, active profiles can be declared via the @ActiveProfiles annotation in
the spring-test module (see the section called Context configuration with
environment profiles).

25/08/2016 12:10

Spring Framework Reference Documentation

215 de 1194

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
setActiveProfiles() method, which accepts String varargs:
ctx.getEnvironment().setActiveProfiles("profile1", "profile2");

Declaratively, spring.profiles.active may accept a comma-separated list of profile

names:
-Dspring.profiles.active="profile1,profile2"

Default profile
The default profile represents the profile that is enabled by default. Consider the
following:
@Configuration
@Profile("default")
public class DefaultDataConfig {
@Bean
public DataSource dataSource() {
return new EmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("classpath:com/bank/config/sql/schema.sql")
.build();
}
}

If no profile is active, the dataSource above will be created; this can be seen as a way
to provide a default definition for one or more beans. If any profile is enabled, the default
profile will not apply.
The name of the default profile can be changed using setDefaultProfiles() on the
Environment or declaratively using the spring.profiles.default property.

7.13.3 PropertySource abstraction

Springs Environment abstraction provides search operations over a configurable
hierarchy of property sources. To explain fully, consider the following:
ApplicationContext ctx = new GenericApplicationContext();
Environment env = ctx.getEnvironment();

25/08/2016 12:10

Spring Framework Reference Documentation

216 de 1194

System.out.println("Does my environment contain the 'foo' property? " + containsFoo);

In the snippet above, we see a high-level way of asking Spring whether the foo property
is defined for the current environment. To answer this question, the Environment object
performs a search over a set of PropertySource objects. A PropertySource is a
simple abstraction over any source of key-value pairs, and Springs
StandardEnvironment is configured with two PropertySource objectsone
representing the set of JVM system properties (a la System.getProperties() ) and one
representing the set of system environment variables (a la System.getenv() ).

These default property sources are present for StandardEnvironment , for

use in standalone applications. StandardServletEnvironment is
populated with additional default property sources including servlet config
and servlet context parameters. StandardPortletEnvironment similarly
has access to portlet config and portlet context parameters as property
sources. Both can optionally enable a JndiPropertySource . See the
javadocs for details.

Concretely, when using the StandardEnvironment , the call to

env.containsProperty("foo") will return true if a foo system property or foo
environment variable is present at runtime.

The search performed is hierarchical. By default, system properties have

precedence over environment variables, so if the foo property happens to
be set in both places during a call to env.getProperty("foo") , the
system property value will 'win' and be returned preferentially over the
environment variable. Note that property values will not get merged but
rather completely overridden by a preceding entry.
For a common StandardServletEnvironment , the full hierarchy looks as
follows, with the highest-precedence entries at the top: * ServletConfig
parameters (if applicable, e.g. in case of a DispatcherServlet context) *
ServletContext parameters (web.xml context-param entries) * JNDI
environment variables ("java:comp/env/" entries) * JVM system properties
("-D" command-line arguments) * JVM system environment (operating
system environment variables)

Most importantly, the entire mechanism is configurable. Perhaps you have a custom
source of properties that youd like to integrate into this search. No problemsimply

25/08/2016 12:10

Spring Framework Reference Documentation

217 de 1194

implement and instantiate your own PropertySource and add it to the set of
PropertySources for the current Environment :
ConfigurableApplicationContext ctx = new GenericApplicationContext();
MutablePropertySources sources = ctx.getEnvironment().getPropertySources();
sources.addFirst(new MyPropertySource());

In the code above, MyPropertySource has been added with highest precedence in the
search. If it contains a foo property, it will be detected and returned ahead of any foo
property in any other PropertySource . The MutablePropertySources API exposes a
number of methods that allow for precise manipulation of the set of property sources.

7.13.4 @PropertySource
The @PropertySource annotation provides a convenient and declarative mechanism for
adding a PropertySource to Springs Environment .
Given a file "app.properties" containing the key/value pair testbean.name=myTestBean ,
the following @Configuration class uses @PropertySource in such a way that a call
to testBean.getName() will return "myTestBean".
@Configuration
@PropertySource("classpath:/com/myco/app.properties")
public class AppConfig {
@Autowired
Environment env;
@Bean
public TestBean testBean() {
TestBean testBean = new TestBean();
testBean.setName(env.getProperty("testbean.name"));
return testBean;
}
}

Any ${} placeholders present in a @PropertySource resource location will be

resolved against the set of property sources already registered against the environment.
For example:
@Configuration
@PropertySource("classpath:/com/${my.placeholder:default/path}/app.properties")
public class AppConfig {
@Autowired
Environment env;

25/08/2016 12:10

Spring Framework Reference Documentation

218 de 1194

@Bean
public TestBean testBean() {
TestBean testBean = new TestBean();
testBean.setName(env.getProperty("testbean.name"));
return testBean;
}
}

Assuming that "my.placeholder" is present in one of the property sources already

registered, e.g. system properties or environment variables, the placeholder will be
resolved to the corresponding value. If not, then "default/path" will be used as a default. If
no default is specified and a property cannot be resolved, an
IllegalArgumentException will be thrown.

7.13.5 Placeholder resolution in statements

Historically, the value of placeholders in elements could be resolved only against JVM
system properties or environment variables. No longer is this the case. Because the
Environment abstraction is integrated throughout the container, its easy to route
resolution of placeholders through it. This means that you may configure the resolution
process in any way you like: change the precedence of searching through system
properties and environment variables, or remove them entirely; add your own property
sources to the mix as appropriate.
Concretely, the following statement works regardless of where the customer property is
defined, as long as it is available in the Environment :
<beans>
<import resource="com/bank/service/${customer}-config.xml"/>
</beans>

7.14 Registering a LoadTimeWeaver

The LoadTimeWeaver is used by Spring to dynamically transform classes as they are
loaded into the Java virtual machine (JVM).
To enable load-time weaving add the @EnableLoadTimeWeaving to one of your
@Configuration classes:
@Configuration
@EnableLoadTimeWeaving

25/08/2016 12:10

Spring Framework Reference Documentation

219 de 1194

public class AppConfig {

}

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
Springs JPA support where load-time weaving may be necessary for JPA class
transformation. Consult the LocalContainerEntityManagerFactoryBean javadocs for
more detail. For more on AspectJ load-time weaving, see Section 11.8.4, Load-time
weaving with AspectJ in the Spring Framework.

7.15 Additional Capabilities of the ApplicationContext

As was discussed in the chapter introduction, the
org.springframework.beans.factory package provides basic functionality for
managing and manipulating beans, including in a programmatic way. The
org.springframework.context package adds the ApplicationContext interface,
which extends the BeanFactory interface, in addition to extending other interfaces to
provide additional functionality in a more application framework-oriented style. Many
people use the ApplicationContext in a completely declarative fashion, not even
creating it programmatically, but instead relying on support classes such as
ContextLoader to automatically instantiate an ApplicationContext as part of the
normal startup process of a Java EE web application.
To enhance BeanFactory functionality in a more framework-oriented style the context
package also provides the following functionality:
Access to messages in i18n-style, through the MessageSource interface.
Access to resources, such as URLs and files, through the ResourceLoader
interface.
Event publication to namely beans implementing the ApplicationListener
interface, through the use of the ApplicationEventPublisher interface.
Loading of multiple (hierarchical) contexts, allowing each to be focused on one
particular layer, such as the web layer of an application, through the

25/08/2016 12:10

Spring Framework Reference Documentation

220 de 1194

HierarchicalBeanFactory interface.

7.15.1 Internationalization using MessageSource

The ApplicationContext interface extends an interface called MessageSource , and
therefore provides internationalization (i18n) functionality. Spring also provides the
interface HierarchicalMessageSource , which can resolve messages hierarchically.
Together these interfaces provide the foundation upon which Spring effects message
resolution. The methods defined on these interfaces include:
String getMessage(String code, Object[] args, String default, Locale loc)
The basic method used to retrieve a message from the MessageSource . When no
message is found for the specified locale, the default message is used. Any
arguments passed in become replacement values, using the MessageFormat
functionality provided by the standard library.
String getMessage(String code, Object[] args, Locale loc) : Essentially
the same as the previous method, but with one difference: no default message can
be specified; if the message cannot be found, a NoSuchMessageException is
thrown.
String getMessage(MessageSourceResolvable resolvable, Locale locale) :
All properties used in the preceding methods are also wrapped in a class named
MessageSourceResolvable , which you can use with this method.
When an ApplicationContext is loaded, it automatically searches for a
MessageSource bean defined in the context. The bean must have the name
messageSource . If such a bean is found, all calls to the preceding methods are
delegated to the message source. If no message source is found, the
ApplicationContext attempts to find a parent containing a bean with the same name.
If it does, it uses that bean as the MessageSource . If the ApplicationContext cannot
find any source for messages, an empty DelegatingMessageSource is instantiated in
order to be able to accept calls to the methods defined above.
Spring provides two MessageSource implementations,
ResourceBundleMessageSource and StaticMessageSource . Both implement
HierarchicalMessageSource in order to do nested messaging. The
StaticMessageSource is rarely used but provides programmatic ways to add messages
to the source. The ResourceBundleMessageSource is shown in the following example:
<beans>
<bean id="messageSource"
class="org.springframework.context.support.ResourceBundleMessageSource"

25/08/2016 12:10

Spring Framework Reference Documentation

221 de 1194

<property name="basenames">
<list>
<value>format</value>
<value>exceptions</value>
<value>windows</value>
</list>
</property>
</bean>
</beans>

In the example it is assumed you have three resource bundles defined in your classpath
called format , exceptions and windows . Any request to resolve a message will be
handled in the JDK standard way of resolving messages through ResourceBundles. For
the purposes of the example, assume the contents of two of the above resource bundle
files are
# in format.properties
message=Alligators rock!
# in exceptions.properties
argument.required=The {0} argument is required.

A program to execute the MessageSource functionality is shown in the next example.

Remember that all ApplicationContext implementations are also MessageSource
implementations and so can be cast to the MessageSource interface.
public static void main(String[] args) {
MessageSource resources = new ClassPathXmlApplicationContext("beans.xml"
String message = resources.getMessage("message", null, "Default", null);
System.out.println(message);
}

The resulting output from the above program will be

Alligators rock!

So to summarize, the MessageSource is defined in a file called beans.xml , which

exists at the root of your classpath. The messageSource bean definition refers to a
number of resource bundles through its basenames property. The three files that are
passed in the list to the basenames property exist as files at the root of your classpath
and are called format.properties , exceptions.properties , and
windows.properties respectively.
The next example shows arguments passed to the message lookup; these arguments will
be converted into Strings and inserted into placeholders in the lookup message.

25/08/2016 12:10

Spring Framework Reference Documentation

222 de 1194

<beans>

<bean id="messageSource" class="org.springframework.context.support.ResourceBundle
<property name="basename" value="exceptions"/>
</bean>

<bean id="example" class="com.foo.Example">
<property name="messages" ref="messageSource"/>
</bean>
</beans>
public class Example {
private MessageSource messages;
public void setMessages(MessageSource messages) {
this.messages = messages;
}
public void execute() {
String message = this.messages.getMessage("argument.required",
new Object [] {"userDao"}, "Required", null);
System.out.println(message);
}
}

The resulting output from the invocation of the execute() method will be
The userDao argument is required.

With regard to internationalization (i18n), Springs various MessageSource

implementations follow the same locale resolution and fallback rules as the standard JDK
ResourceBundle . In short, and continuing with the example messageSource defined
previously, if you want to resolve messages against the British ( en-GB ) locale, you would
create files called format_en_GB.properties , exceptions_en_GB.properties , and
windows_en_GB.properties respectively.
Typically, locale resolution is managed by the surrounding environment of the application.
In this example, the locale against which (British) messages will be resolved is specified
manually.
# in exceptions_en_GB.properties
argument.required=Ebagum lad, the {0} argument is required, I say, required.

25/08/2016 12:10

Spring Framework Reference Documentation

223 de 1194

public static void main(final String[] args) {

MessageSource resources = new ClassPathXmlApplicationContext("beans.xml"
String message = resources.getMessage("argument.required",
new Object [] {"userDao"}, "Required", Locale.UK);
System.out.println(message);
}

The resulting output from the running of the above program will be
Ebagum lad, the 'userDao' argument is required, I say, required.

You can also use the MessageSourceAware interface to acquire a reference to any
MessageSource that has been defined. Any bean that is defined in an
ApplicationContext that implements the MessageSourceAware interface is injected
with the application contexts MessageSource when the bean is created and configured.

As an alternative to ResourceBundleMessageSource , Spring provides a

ReloadableResourceBundleMessageSource class. This variant supports
the same bundle file format but is more flexible than the standard JDK
based ResourceBundleMessageSource implementation. In particular, it
allows for reading files from any Spring resource location (not just from the
classpath) and supports hot reloading of bundle property files (while
efficiently caching them in between). Check out the
ReloadableResourceBundleMessageSource javadocs for details.

7.15.2 Standard and Custom Events

Event handling in the ApplicationContext is provided through the
ApplicationEvent class and ApplicationListener interface. If a bean that
implements the ApplicationListener interface is deployed into the context, every time
an ApplicationEvent gets published to the ApplicationContext , that bean is
notified. Essentially, this is the standard Observer design pattern.

As of Spring 4.2, the event infrastructure has been significantly improved

and offer an annotation-based model as well as the ability to publish any
arbitrary event, that is an object that does not necessarily extend from
ApplicationEvent . When such an object is published we wrap it in a
PayloadApplicationEvent for you.

25/08/2016 12:10

Spring Framework Reference Documentation

224 de 1194

Table 7.7. Built-in Events

Event
ContextRefreshedEvent

Explanation
Published when the ApplicationContext is
initialized or refreshed, for example, using the
refresh() method on the
ConfigurableApplicationContext interface.
"Initialized" here means that all beans are loaded,
post-processor beans are detected and activated,
singletons are pre-instantiated, and the
ApplicationContext object is ready for use. As
long as the context has not been closed, a refresh
can be triggered multiple times, provided that the
chosen ApplicationContext actually supports
such "hot" refreshes. For example,
XmlWebApplicationContext supports hot
refreshes, but GenericApplicationContext
does not.

ContextStartedEvent

Published when the ApplicationContext is

started, using the start() method on the
ConfigurableApplicationContext interface.
"Started" here means that all Lifecycle beans
receive an explicit start signal. Typically this signal
is used to restart beans after an explicit stop, but it
may also be used to start components that have
not been configured for autostart , for example,
components that have not already started on
initialization.

ContextStoppedEvent

Published when the ApplicationContext is

stopped, using the stop() method on the
ConfigurableApplicationContext interface.
"Stopped" here means that all Lifecycle beans
receive an explicit stop signal. A stopped context
may be restarted through a start() call.

ContextClosedEvent

Published when the ApplicationContext is

closed, using the close() method on the
ConfigurableApplicationContext interface.

25/08/2016 12:10

Spring Framework Reference Documentation

225 de 1194

Event

Explanation
"Closed" here means that all singleton beans are
destroyed. A closed context reaches its end of life;
it cannot be refreshed or restarted.

RequestHandledEvent

A web-specific event telling all beans that an HTTP

request has been serviced. This event is published
after the request is complete. This event is only
applicable to web applications using Springs
DispatcherServlet .

You can also create and publish your own custom events. This example demonstrates a
simple class that extends Springs ApplicationEvent base class:
public class BlackListEvent extends ApplicationEvent {
private final String address;
private final String test;
public BlackListEvent(Object source, String address, String test) {
super(source);
this.address = address;
this.test = test;
}
// accessor and other methods...
}

To publish a custom ApplicationEvent , call the publishEvent() method on an

ApplicationEventPublisher . Typically this is done by creating a class that
implements ApplicationEventPublisherAware and registering it as a Spring bean.
The following example demonstrates such a class:
public class EmailService implements ApplicationEventPublisherAware {
private List<String> blackList;
private ApplicationEventPublisher publisher;
public void setBlackList(List<String> blackList) {
this.blackList = blackList;
}

25/08/2016 12:10

Spring Framework Reference Documentation

226 de 1194

public void setApplicationEventPublisher(ApplicationEventPublisher publisher) {

this.publisher = publisher;
}
public void sendEmail(String address, String text) {
if (blackList.contains(address)) {
BlackListEvent event = new BlackListEvent(this, address, text);
publisher.publishEvent(event);
return;
}
// send email...
}
}

At configuration time, the Spring container will detect that EmailService implements
ApplicationEventPublisherAware and will automatically call
setApplicationEventPublisher() . In reality, the parameter passed in will be the
Spring container itself; youre simply interacting with the application context via its
ApplicationEventPublisher interface.
To receive the custom ApplicationEvent , create a class that implements
ApplicationListener and register it as a Spring bean. The following example
demonstrates such a class:
public class BlackListNotifier implements ApplicationListener<BlackListEvent> {
private String notificationAddress;
public void setNotificationAddress(String notificationAddress) {
this.notificationAddress = notificationAddress;
}
public void onApplicationEvent(BlackListEvent event) {
// notify appropriate parties via notificationAddress...
}
}

Notice that ApplicationListener is generically parameterized with the type of your

custom event, BlackListEvent . This means that the onApplicationEvent() method
can remain type-safe, avoiding any need for downcasting. You may register as many
event listeners as you wish, but note that by default event listeners receive events
synchronously. This means the publishEvent() method blocks until all listeners have

25/08/2016 12:10

Spring Framework Reference Documentation

227 de 1194

finished processing the event. One advantage of this synchronous and single-threaded
approach is that when a listener receives an event, it operates inside the transaction
context of the publisher if a transaction context is available. If another strategy for event
publication becomes necessary, refer to the JavaDoc for Springs
ApplicationEventMulticaster interface.
The following example shows the bean definitions used to register and configure each of
the classes above:
<bean id="emailService" class="example.EmailService">
<property name="blackList">
<list>
<value>[email protected]</value>
<value>[email protected]</value>
<value>[email protected]</value>
</list>
</property>
</bean>
<bean id="blackListNotifier" class="example.BlackListNotifier">
<property name="notificationAddress" value="[email protected]"/>
</bean>

Putting it all together, when the sendEmail() method of the emailService bean is
called, if there are any emails that should be blacklisted, a custom event of type
BlackListEvent is published. The blackListNotifier bean is registered as an
ApplicationListener and thus receives the BlackListEvent , at which point it can
notify appropriate parties.

Springs eventing mechanism is designed for simple communication

between Spring beans within the same application context. However, for
more sophisticated enterprise integration needs, the separately-maintained
Spring Integration project provides complete support for building lightweight,
pattern-oriented, event-driven architectures that build upon the well-known
Spring programming model.

Annotation-based Event Listeners

As of Spring 4.2, an event listener can be registered on any public method of a managed
bean via the EventListener annotation. The BlackListNotifier can be rewritten as
follows:

25/08/2016 12:10

Spring Framework Reference Documentation

228 de 1194

public class BlackListNotifier {

private String notificationAddress;
public void setNotificationAddress(String notificationAddress) {
this.notificationAddress = notificationAddress;
}
@EventListener
public void processBlackListEvent(BlackListEvent event) {
// notify appropriate parties via notificationAddress...
}
}

As you can see above, the method signature actually infer which even type it listens to.
This also works for nested generics as long as the actual event resolves the generics
parameter you would filter on.
If your method should listen to several events or if you want to define it with no parameter
at all, the event type(s) can also be specified on the annotation itself:
@EventListener({ContextStartedEvent.class, ContextRefreshedEvent.class})
public void handleContextStart() {
}

It is also possible to add additional runtime filtering via the condition attribute of the
annotation that defines a SpEL expression that should match to actually invoke the
method for a particular event.
For instance, our notifier can be rewritten to be only invoked if the test attribute of the
event is equal to foo :
@EventListener(condition = "#event.test == 'foo'")
public void processBlackListEvent(BlackListEvent event) {
// notify appropriate parties via notificationAddress...
}

Each SpEL expression evaluates again a dedicated context. The next table lists the
items made available to the context so one can use them for conditional event
processing:

Table 7.8. Event SpEL available metadata

25/08/2016 12:10

Spring Framework Reference Documentation

229 de 1194

Name

Location

Description

Example

event

root object

The actual ApplicationEvent

#root.event

args

root object

The arguments (as array) used

#root.args[0]

for invoking the target

argument

evaluation

Name of any of the method

#iban or #a0 (one

name

context

arguments. If for some reason

can also use #p0

the names are not available (e.g. or #p<#arg>

no debug information), the

notation as an

argument names are also

alias).

available under the #a<#arg>

where #arg stands for the
argument index (starting from 0).

Note that #root.event allows you to access to the underlying event, even if your
method signature actually refers to an arbitrary object that was published.
If you need to publish an event as the result of processing another, just change the
method signature to return the event that should be published, something like:
@EventListener
public ListUpdateEvent handleBlackListEvent(BlackListEvent event) {
// notify appropriate parties via notificationAddress and
// then publish a ListUpdateEvent...
}

This feature is not supported for asynchronous listeners.

This new method will publish a new ListUpdateEvent for every BlackListEvent
handled by the method above. If you need to publish several events, just return a
Collection of events instead.

Asynchronous Listeners
If you want a particular listener to process events asynchronously, simply reuse the
regular @Async support:
@EventListener

25/08/2016 12:10

Spring Framework Reference Documentation

230 de 1194

@Async
public void processBlackListEvent(BlackListEvent event) {
// BlackListEvent is processed in a separate thread
}

Be aware of the following limitations when using asynchronous events:

1. If the event listener throws an Exception it will not be propagated to the caller,
check AsyncUncaughtExceptionHandler for more details.
2. Such event listener cannot send replies. If you need to send another event as the
result of the processing, inject ApplicationEventPublisher to send the event
manually.

Ordering Listeners
If you need the listener to be invoked before another one, just add the @Order
annotation to the method declaration:
@EventListener
@Order(42)
public void processBlackListEvent(BlackListEvent event) {
// notify appropriate parties via notificationAddress...
}

Generic Events
You may also use generics to further define the structure of your event. Consider an
EntityCreatedEvent<T> where T is the type of the actual entity that got created. You
can create the following listener definition to only receive EntityCreatedEvent for a
Person :
@EventListener
public void onPersonCreated(EntityCreatedEvent<Person> event) {
...
}

Due to type erasure, this will only work if the event that is fired resolves the generic
parameter(s) on which the event listener filters on (that is something like
class PersonCreatedEvent extends EntityCreatedEvent<Person> { } ).
In certain circumstances, this may become quite tedious if all events follow the same
structure (as it should be the case for the event above). In such a case, you can
implement ResolvableTypeProvider to guide the framework beyond what the runtime

25/08/2016 12:10

Spring Framework Reference Documentation

231 de 1194

public class EntityCreatedEvent<T>

extends ApplicationEvent implements ResolvableTypeProvider {
public EntityCreatedEvent(T entity) {
super(entity);
}
@Override
public ResolvableType getResolvableType() {
return ResolvableType.forClassWithGenerics(getClass(),
ResolvableType.forInstance(getSource()));
}
}

This works not only for ApplicationEvent but any arbitrary object that
youd send as an event.

7.15.3 Convenient access to low-level resources

For optimal usage and understanding of application contexts, users should generally
familiarize themselves with Springs Resource abstraction, as described in the chapter
Chapter 8, Resources.
An application context is a ResourceLoader , which can be used to load Resource s. A
Resource is essentially a more feature rich version of the JDK class java.net.URL , in
fact, the implementations of the Resource wrap an instance of java.net.URL where
appropriate. A Resource can obtain low-level resources from almost any location in a
transparent fashion, including from the classpath, a filesystem location, anywhere
describable with a standard URL, and some other variations. If the resource location
string is a simple path without any special prefixes, where those resources come from is
specific and appropriate to the actual application context type.
You can configure a bean deployed into the application context to implement the special
callback interface, ResourceLoaderAware , to be automatically called back at
initialization time with the application context itself passed in as the ResourceLoader .
You can also expose properties of type Resource , to be used to access static resources;
they will be injected into it like any other properties. You can specify those Resource
properties as simple String paths, and rely on a special JavaBean PropertyEditor that
is automatically registered by the context, to convert those text strings to actual
Resource objects when the bean is deployed.

25/08/2016 12:10

Spring Framework Reference Documentation

232 de 1194

The location path or paths supplied to an ApplicationContext constructor are actually

resource strings, and in simple form are treated appropriately to the specific context
implementation. ClassPathXmlApplicationContext treats a simple location path as a
classpath location. You can also use location paths (resource strings) with special
prefixes to force loading of definitions from the classpath or a URL, regardless of the
actual context type.

7.15.4 Convenient ApplicationContext instantiation for web

applications
You can create ApplicationContext instances declaratively by using, for example, a
ContextLoader . Of course you can also create ApplicationContext instances
programmatically by using one of the ApplicationContext implementations.
You can register an ApplicationContext using the ContextLoaderListener as
follows:

<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/daoContext.xml /WEB-INF/applicationContext.xml</param-value>
</context-param>

<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-cl
</listener>

The listener inspects the contextConfigLocation parameter. If the parameter does not
exist, the listener uses /WEB-INF/applicationContext.xml as a default. When the
parameter does exist, the listener separates the String by using predefined delimiters
(comma, semicolon and whitespace) and uses the values as locations where application
contexts will be searched. Ant-style path patterns are supported as well. Examples are
/WEB-INF/*Context.xml for all files with names ending with "Context.xml", residing in
the "WEB-INF" directory, and /WEB-INF/**/*Context.xml , for all such files in any
subdirectory of "WEB-INF".

7.15.5 Deploying a Spring ApplicationContext as a Java EE RAR

file
It is possible to deploy a Spring ApplicationContext as a RAR file, encapsulating the
context and all of its required bean classes and library JARs in a Java EE RAR

25/08/2016 12:10

Spring Framework Reference Documentation

233 de 1194

just hosted in Java EE environment, being able to access the Java EE servers facilities.
RAR deployment is more natural alternative to scenario of deploying a headless WAR file,
in effect, a WAR file without any HTTP entry points that is used only for bootstrapping a
Spring ApplicationContext in a Java EE environment.
RAR deployment is ideal for application contexts that do not need HTTP entry points but
rather consist only of message endpoints and scheduled jobs. Beans in such a context
can use application server resources such as the JTA transaction manager and
JNDI-bound JDBC DataSources and JMS ConnectionFactory instances, and may also
register with the platforms JMX server - all through Springs standard transaction
management and JNDI and JMX support facilities. Application components can also
interact with the application servers JCA WorkManager through Springs TaskExecutor
abstraction.
Check out the JavaDoc of the SpringContextResourceAdapter class for the
configuration details involved in RAR deployment.
For a simple deployment of a Spring ApplicationContext as a Java EE RAR file: package
all application classes into a RAR file, which is a standard JAR file with a different file
extension. Add all required library JARs into the root of the RAR archive. Add a "METAINF/ra.xml" deployment descriptor (as shown in SpringContextResourceAdapter s
JavaDoc) and the corresponding Spring XML bean definition file(s) (typically "METAINF/applicationContext.xml"), and drop the resulting RAR file into your application
servers deployment directory.

Such RAR deployment units are usually self-contained; they do not expose
components to the outside world, not even to other modules of the same
application. Interaction with a RAR-based ApplicationContext usually occurs
through JMS destinations that it shares with other modules. A RAR-based
ApplicationContext may also, for example, schedule some jobs, reacting to
new files in the file system (or the like). If it needs to allow synchronous
access from the outside, it could for example export RMI endpoints, which
of course may be used by other application modules on the same machine.

7.16 The BeanFactory

The BeanFactory provides the underlying basis for Springs IoC functionality but it is
only used directly in integration with other third-party frameworks and is now largely
historical in nature for most users of Spring. The BeanFactory and related interfaces,

25/08/2016 12:10

Spring Framework Reference Documentation

234 de 1194

such as BeanFactoryAware , InitializingBean , DisposableBean , are still present

in Spring for the purposes of backward compatibility with the large number of third-party
frameworks that integrate with Spring. Often third-party components that can not use
more modern equivalents such as @PostConstruct or @PreDestroy in order to remain
compatible with JDK 1.4 or to avoid a dependency on JSR-250.
This section provides additional background into the differences between the
BeanFactory and ApplicationContext and how one might access the IoC container
directly through a classic singleton lookup.

7.16.1 BeanFactory or ApplicationContext?

Use an ApplicationContext unless you have a good reason for not doing so.
Because the ApplicationContext includes all functionality of the BeanFactory , it is
generally recommended over the BeanFactory , except for a few situations such as in
embedded applications running on resource-constrained devices where memory
consumption might be critical and a few extra kilobytes might make a difference.
However, for most typical enterprise applications and systems, the
ApplicationContext is what you will want to use. Spring makes heavy use of the
BeanPostProcessor extension point (to effect proxying and so on). If you use only a
plain BeanFactory , a fair amount of support such as transactions and AOP will not take
effect, at least not without some extra steps on your part. This situation could be
confusing because nothing is actually wrong with the configuration.
The following table lists features provided by the BeanFactory and
ApplicationContext interfaces and implementations.

Table 7.9. Feature Matrix

Feature

BeanFactory

ApplicationContext

Bean instantiation/wiring

Yes

Automatic BeanPostProcessor

Yes

registration
Automatic
BeanFactoryPostProcessor
registration

25/08/2016 12:10

Spring Framework Reference Documentation

235 de 1194

Feature
Convenient MessageSource

BeanFactory

ApplicationContext

Yes

access (for i18n)

ApplicationEvent publication

To explicitly register a bean post-processor with a BeanFactory implementation, you

need to write code like this:
DefaultListableBeanFactory factory = new DefaultListableBeanFactory();
// populate the factory with bean definitions
// now register any needed BeanPostProcessor instances
MyBeanPostProcessor postProcessor = new MyBeanPostProcessor();
factory.addBeanPostProcessor(postProcessor);
// now start using the factory

To explicitly register a BeanFactoryPostProcessor when using a BeanFactory

implementation, you must write code like this:
DefaultListableBeanFactory factory = new DefaultListableBeanFactory();
XmlBeanDefinitionReader reader = new XmlBeanDefinitionReader(factory);
reader.loadBeanDefinitions(new FileSystemResource("beans.xml"));
// bring in some property values from a Properties file
PropertyPlaceholderConfigurer cfg = new PropertyPlaceholderConfigurer();
cfg.setLocation(new FileSystemResource("jdbc.properties"));
// now actually do the replacement
cfg.postProcessBeanFactory(factory);

In both cases, the explicit registration step is inconvenient, which is one reason why the
various ApplicationContext implementations are preferred above plain BeanFactory
implementations in the vast majority of Spring-backed applications, especially when using
BeanFactoryPostProcessor s and BeanPostProcessor s. These mechanisms
implement important functionality such as property placeholder replacement and AOP.

7.16.2 Glue code and the evil singleton

It is best to write most application code in a dependency-injection (DI) style, where that

25/08/2016 12:10

Spring Framework Reference Documentation

236 de 1194

code is served out of a Spring IoC container, has its own dependencies supplied by the
container when it is created, and is completely unaware of the container. However, for the
small glue layers of code that are sometimes needed to tie other code together, you
sometimes need a singleton (or quasi-singleton) style access to a Spring IoC container.
For example, third-party code may try to construct new objects directly (
Class.forName() style), without the ability to get these objects out of a Spring IoC
container.If the object constructed by the third-party code is a small stub or proxy, which
then uses a singleton style access to a Spring IoC container to get a real object to
delegate to, then inversion of control has still been achieved for the majority of the code
(the object coming out of the container). Thus most code is still unaware of the container
or how it is accessed, and remains decoupled from other code, with all ensuing benefits.
EJBs may also use this stub/proxy approach to delegate to a plain Java implementation
object, retrieved from a Spring IoC container. While the Spring IoC container itself ideally
does not have to be a singleton, it may be unrealistic in terms of memory usage or
initialization times (when using beans in the Spring IoC container such as a Hibernate
SessionFactory ) for each bean to use its own, non-singleton Spring IoC container.
Looking up the application context in a service locator style is sometimes the only option
for accessing shared Spring-managed components, such as in an EJB 2.1 environment,
or when you want to share a single ApplicationContext as a parent to
WebApplicationContexts across WAR files. In this case you should look into using the
utility class ContextSingletonBeanFactoryLocator locator that is described in this
Spring team blog entry.

[1]
[2]

See Background
See Section 7.4.1, Dependency Injection

8. Resources
8.1 Introduction
Javas standard java.net.URL class and standard handlers for various URL prefixes
unfortunately are not quite adequate enough for all access to low-level resources. For
example, there is no standardized URL implementation that may be used to access a
resource that needs to be obtained from the classpath, or relative to a ServletContext .
While it is possible to register new handlers for specialized URL prefixes (similar to
existing handlers for prefixes such as http: ), this is generally quite complicated, and the
URL

25/08/2016 12:10

Spring Framework Reference Documentation

237 de 1194

existence of the resource being pointed to.

8.2 The Resource interface

Springs Resource interface is meant to be a more capable interface for abstracting
access to low-level resources.
public interface Resource extends InputStreamSource {
boolean exists();
boolean isOpen();
URL getURL() throws IOException;
File getFile() throws IOException;
Resource createRelative(String relativePath) throws IOException;
String getFilename();
String getDescription();
}
public interface InputStreamSource {
InputStream getInputStream() throws IOException;
}

Some of the most important methods from the Resource interface are:
getInputStream() : locates and opens the resource, returning an InputStream
for reading from the resource. It is expected that each invocation returns a fresh
InputStream . It is the responsibility of the caller to close the stream.
exists() : returns a boolean indicating whether this resource actually exists in
physical form.
isOpen() : returns a boolean indicating whether this resource represents a handle
with an open stream. If true , the InputStream cannot be read multiple times, and
must be read once only and then closed to avoid resource leaks. Will be false for
all usual resource implementations, with the exception of InputStreamResource .
getDescription() : returns a description for this resource, to be used for error

25/08/2016 12:10

Spring Framework Reference Documentation

238 de 1194

the actual URL of the resource.

Other methods allow you to obtain an actual URL or File object representing the
resource (if the underlying implementation is compatible, and supports that functionality).
The Resource abstraction is used extensively in Spring itself, as an argument type in
many method signatures when a resource is needed. Other methods in some Spring
APIs (such as the constructors to various ApplicationContext implementations), take
a String which in unadorned or simple form is used to create a Resource appropriate
to that context implementation, or via special prefixes on the String path, allow the
caller to specify that a specific Resource implementation must be created and used.
While the Resource interface is used a lot with Spring and by Spring, its actually very
useful to use as a general utility class by itself in your own code, for access to resources,
even when your code doesnt know or care about any other parts of Spring. While this
couples your code to Spring, it really only couples it to this small set of utility classes,
which are serving as a more capable replacement for URL , and can be considered
equivalent to any other library you would use for this purpose.
It is important to note that the Resource abstraction does not replace functionality: it
wraps it where possible. For example, a UrlResource wraps a URL, and uses the
wrapped URL to do its work.

8.3 Built-in Resource implementations

There are a number of Resource implementations that come supplied straight out of the
box in Spring:

8.3.1 UrlResource
The UrlResource wraps a java.net.URL , and may be used to access any object that
is normally accessible via a URL, such as files, an HTTP target, an FTP target, etc. All
URLs have a standardized String representation, such that appropriate standardized
prefixes are used to indicate one URL type from another. This includes file: for
accessing filesystem paths, http: for accessing resources via the HTTP protocol, ftp:
for accessing resources via FTP, etc.
A UrlResource is created by Java code explicitly using the UrlResource constructor,
but will often be created implicitly when you call an API method which takes a String
argument which is meant to represent a path. For the latter case, a JavaBeans
PropertyEditor will ultimately decide which type of Resource to create. If the path

25/08/2016 12:10

Spring Framework Reference Documentation

239 de 1194

string contains a few well-known (to it, that is) prefixes such as classpath: , it will create
an appropriate specialized Resource for that prefix. However, if it doesnt recognize the
prefix, it will assume the this is just a standard URL string, and will create a
UrlResource .

8.3.2 ClassPathResource
This class represents a resource which should be obtained from the classpath. This uses
either the thread context class loader, a given class loader, or a given class for loading
resources.
This Resource implementation supports resolution as java.io.File if the class path
resource resides in the file system, but not for classpath resources which reside in a jar
and have not been expanded (by the servlet engine, or whatever the environment is) to
the filesystem. To address this the various Resource implementations always support
resolution as a java.net.URL .
A ClassPathResource is created by Java code explicitly using the
ClassPathResource constructor, but will often be created implicitly when you call an
API method which takes a String argument which is meant to represent a path. For the
latter case, a JavaBeans PropertyEditor will recognize the special prefix classpath:
on the string path, and create a ClassPathResource in that case.

8.3.3 FileSystemResource
This is a Resource implementation for java.io.File handles. It obviously supports
resolution as a File , and as a URL .

8.3.4 ServletContextResource
This is a Resource implementation for ServletContext resources, interpreting relative
paths within the relevant web applications root directory.
This always supports stream access and URL access, but only allows java.io.File
access when the web application archive is expanded and the resource is physically on
the filesystem. Whether or not its expanded and on the filesystem like this, or accessed
directly from the JAR or somewhere else like a DB (its conceivable) is actually dependent
on the Servlet container.

25/08/2016 12:10

Spring Framework Reference Documentation

240 de 1194

8.3.5 InputStreamResource
A Resource implementation for a given InputStream . This should only be used if no
specific Resource implementation is applicable. In particular, prefer
ByteArrayResource or any of the file-based Resource implementations where
possible.
In contrast to other Resource implementations, this is a descriptor for an already opened
resource - therefore returning true from isOpen() . Do not use it if you need to keep
the resource descriptor somewhere, or if you need to read a stream multiple times.

8.3.6 ByteArrayResource
This is a Resource implementation for a given byte array. It creates a
ByteArrayInputStream for the given byte array.
Its useful for loading content from any given byte array, without having to resort to a
single-use InputStreamResource .

8.4 The ResourceLoader

The ResourceLoader interface is meant to be implemented by objects that can return
(i.e. load) Resource instances.
public interface ResourceLoader {
Resource getResource(String location);
}

All application contexts implement the ResourceLoader interface, and therefore all
application contexts may be used to obtain Resource instances.
When you call getResource() on a specific application context, and the location path
specified doesnt have a specific prefix, you will get back a Resource type that is
appropriate to that particular application context. For example, assume the following
snippet of code was executed against a ClassPathXmlApplicationContext instance:
Resource template = ctx.getResource("some/resource/path/myTemplate.txt");

What would be returned would be a ClassPathResource ; if the same method was

executed against a FileSystemXmlApplicationContext instance, youd get back a

25/08/2016 12:10

Spring Framework Reference Documentation

241 de 1194

FileSystemResource . For a WebApplicationContext , youd get back a

ServletContextResource , and so on.
As such, you can load resources in a fashion appropriate to the particular application
context.
On the other hand, you may also force ClassPathResource to be used, regardless of
the application context type, by specifying the special classpath: prefix:
Resource template = ctx.getResource("classpath:some/resource/path/myTemplate.txt"

Similarly, one can force a UrlResource to be used by specifying any of the standard
java.net.URL prefixes:
Resource template = ctx.getResource("file:///some/resource/path/myTemplate.txt"
Resource template = ctx.getResource("http://myhost.com/resource/path/myTemplate.txt"

The following table summarizes the strategy for converting String s to Resource s:

Table 8.1. Resource strings

Prefix

Example

Explanation

classpath:

classpath:com/myapp/config.xml

Loaded from the classpath.

file:

file:///data/config.xml

Loaded as a URL , from the

filesystem. [1]

http:

http://myserver/logo.png

Loaded as a URL .

(none)

/data/config.xml

Depends on the underlying

ApplicationContext .

[1]

But see also Section 8.7.3, FileSystemResource caveats.

8.5 The ResourceLoaderAware interface

The ResourceLoaderAware interface is a special marker interface, identifying objects
that expect to be provided with a ResourceLoader reference.

25/08/2016 12:10

Spring Framework Reference Documentation

242 de 1194

void setResourceLoader(ResourceLoader resourceLoader);

}

When a class implements ResourceLoaderAware and is deployed into an application

context (as a Spring-managed bean), it is recognized as ResourceLoaderAware by the
application context. The application context will then invoke the
setResourceLoader(ResourceLoader) , supplying itself as the argument (remember,
all application contexts in Spring implement the ResourceLoader interface).
Of course, since an ApplicationContext is a ResourceLoader , the bean could also
implement the ApplicationContextAware interface and use the supplied application
context directly to load resources, but in general, its better to use the specialized
ResourceLoader interface if thats all thats needed. The code would just be coupled to
the resource loading interface, which can be considered a utility interface, and not the
whole Spring ApplicationContext interface.
As of Spring 2.5, you can rely upon autowiring of the ResourceLoader as an alternative
to implementing the ResourceLoaderAware interface. The "traditional" constructor
and byType autowiring modes (as described in Section 7.4.5, Autowiring collaborators)
are now capable of providing a dependency of type ResourceLoader for either a
constructor argument or setter method parameter respectively. For more flexibility
(including the ability to autowire fields and multiple parameter methods), consider using
the new annotation-based autowiring features. In that case, the ResourceLoader will be
autowired into a field, constructor argument, or method parameter that is expecting the
ResourceLoader type as long as the field, constructor, or method in question carries the
@Autowired annotation. For more information, see Section 7.9.2, @Autowired.

8.6 Resources as dependencies

If the bean itself is going to determine and supply the resource path through some sort of
dynamic process, it probably makes sense for the bean to use the ResourceLoader
interface to load resources. Consider as an example the loading of a template of some
sort, where the specific resource that is needed depends on the role of the user. If the
resources are static, it makes sense to eliminate the use of the ResourceLoader
interface completely, and just have the bean expose the Resource properties it needs,
and expect that they will be injected into it.
What makes it trivial to then inject these properties, is that all application contexts register
and use a special JavaBeans PropertyEditor which can convert String paths to
Resource objects. So if myBean has a template property of type Resource , it can be

25/08/2016 12:10

Spring Framework Reference Documentation

243 de 1194

configured with a simple string for that resource, as follows:

Note that the resource path has no prefix, so because the application context itself is
going to be used as the ResourceLoader , the resource itself will be loaded via a
ClassPathResource , FileSystemResource , or ServletContextResource (as
appropriate) depending on the exact type of the context.
If there is a need to force a specific Resource type to be used, then a prefix may be
used. The following two examples show how to force a ClassPathResource and a
UrlResource (the latter being used to access a filesystem file).
<property name="template" value="classpath:some/resource/path/myTemplate.txt"
<property name="template" value="file:///some/resource/path/myTemplate.txt"/>

8.7 Application contexts and Resource paths

8.7.1 Constructing application contexts
An application context constructor (for a specific application context type) generally takes
a string or array of strings as the location path(s) of the resource(s) such as XML files that
make up the definition of the context.
When such a location path doesnt have a prefix, the specific Resource type built from
that path and used to load the bean definitions, depends on and is appropriate to the
specific application context. For example, if you create a
ClassPathXmlApplicationContext as follows:
ApplicationContext ctx = new ClassPathXmlApplicationContext("conf/appContext.xml"

The bean definitions will be loaded from the classpath, as a ClassPathResource will be
used. But if you create a FileSystemXmlApplicationContext as follows:
ApplicationContext ctx =
new FileSystemXmlApplicationContext("conf/appContext.xml");

The bean definition will be loaded from a filesystem location, in this case relative to the

25/08/2016 12:10

Spring Framework Reference Documentation

244 de 1194

current working directory.

Note that the use of the special classpath prefix or a standard URL prefix on the location
path will override the default type of Resource created to load the definition. So this
FileSystemXmlApplicationContext
ApplicationContext ctx =
new FileSystemXmlApplicationContext("classpath:conf/appContext.xml");

i. will actually load its bean definitions from the classpath. However, it is still a
FileSystemXmlApplicationContext . If it is subsequently used as a
ResourceLoader , any unprefixed paths will still be treated as filesystem paths.

Constructing ClassPathXmlApplicationContext instances - shortcuts

The ClassPathXmlApplicationContext exposes a number of constructors to enable
convenient instantiation. The basic idea is that one supplies merely a string array
containing just the filenames of the XML files themselves (without the leading path
information), and one also supplies a Class ; the ClassPathXmlApplicationContext
will derive the path information from the supplied class.
An example will hopefully make this clear. Consider a directory layout that looks like this:
com/
foo/
services.xml
daos.xml
MessengerService.class

A ClassPathXmlApplicationContext instance composed of the beans defined in the

'services.xml' and 'daos.xml' could be instantiated like so
ApplicationContext ctx = new ClassPathXmlApplicationContext(
new String[] {"services.xml", "daos.xml"}, MessengerService.class);

Please do consult the ClassPathXmlApplicationContext javadocs for details on the

various constructors.

8.7.2 Wildcards in application context constructor resource paths

The resource paths in application context constructor values may be a simple path (as
shown above) which has a one-to-one mapping to a target Resource, or alternately may
contain the special "classpath*:" prefix and/or internal Ant-style regular expressions
(matched using Springs PathMatcher utility). Both of the latter are effectively wildcards

25/08/2016 12:10

Spring Framework Reference Documentation

245 de 1194

One use for this mechanism is when doing component-style application assembly. All
components can 'publish' context definition fragments to a well-known location path, and
when the final application context is created using the same path prefixed via
classpath*: , all component fragments will be picked up automatically.
Note that this wildcarding is specific to use of resource paths in application context
constructors (or when using the PathMatcher utility class hierarchy directly), and is
resolved at construction time. It has nothing to do with the Resource type itself. Its not
possible to use the classpath*: prefix to construct an actual Resource , as a resource
points to just one resource at a time.

Ant-style Patterns
When the path location contains an Ant-style pattern, for example:
/WEB-INF/*-context.xml
com/mycompany/**/applicationContext.xml
file:C:/some/path/*-context.xml
classpath:com/mycompany/**/applicationContext.xml

i. the resolver follows a more complex but defined procedure to try to resolve the
wildcard. It produces a Resource for the path up to the last non-wildcard segment
and obtains a URL from it. If this URL is not a "jar:" URL or container-specific variant
(e.g. "
zip:`" in WebLogic, " `wsjar`" in WebSphere, etc.), then a `java.io.File
is obtained from it and used to resolve the wildcard by traversing the filesystem. In
the case of a jar URL, the resolver either gets a java.net.JarURLConnection from
it or manually parses the jar URL and then traverses the contents of the jar file to
resolve the wildcards.

Implications on portability
If the specified path is already a file URL (either explicitly, or implicitly because the base
ResourceLoader is a filesystem one, then wildcarding is guaranteed to work in a
completely portable fashion.
If the specified path is a classpath location, then the resolver must obtain the last
non-wildcard path segment URL via a Classloader.getResource() call. Since this is
just a node of the path (not the file at the end) it is actually undefined (in the
ClassLoader javadocs) exactly what sort of a URL is returned in this case. In practice, it
is always a java.io.File representing the directory, where the classpath resource
resolves to a filesystem location, or a jar URL of some sort, where the classpath resource
resolves to a jar location. Still, there is a portability concern on this operation.

25/08/2016 12:10

Spring Framework Reference Documentation

246 de 1194

If a jar URL is obtained for the last non-wildcard segment, the resolver must be able to
get a java.net.JarURLConnection from it, or manually parse the jar URL, to be able to
walk the contents of the jar, and resolve the wildcard. This will work in most environments,
but will fail in others, and it is strongly recommended that the wildcard resolution of
resources coming from jars be thoroughly tested in your specific environment before you
rely on it.

The Classpath: portability classpath: prefix

When constructing an XML-based application context, a location string may use the
special classpath*: prefix:
ApplicationContext ctx =
new ClassPathXmlApplicationContext("classpath*:conf/appContext.xml");

This special prefix specifies that all classpath resources that match the given name must
be obtained (internally, this essentially happens via a ClassLoader.getResources()
call), and then merged to form the final application context definition.

The wildcard classpath relies on the getResources() method of the underlying

classloader. As most application servers nowadays supply their own classloader
implementation, the behavior might differ especially when dealing with jar files. A
simple test to check if classpath* works is to use the classloader to load a file
from within a jar on the classpath:
getClass().getClassLoader().getResources("<someFileInsideTheJar>") .
Try this test with files that have the same name but are placed inside two different
locations. In case an inappropriate result is returned, check the application server
documentation for settings that might affect the classloader behavior.

The " classpath*:`" prefix can also be combined with a `PathMatcher

pattern in the rest of the location path, for example " `classpath*:META-INF/*-beans.xml`".
In this case, the resolution strategy is fairly simple: a ClassLoader.getResources() call is
used on the last non-wildcard path segment to get all the matching resources in the class
loader hierarchy, and then off each resource the same PathMatcher resolution strategy
described above is used for the wildcard subpath.

Other notes relating to wildcards

Please note that classpath*: when combined with Ant-style patterns will only work
reliably with at least one root directory before the pattern starts, unless the actual target

25/08/2016 12:10

Spring Framework Reference Documentation

247 de 1194

files reside in the file system. This means that a pattern like "
classpath*:*.xml`" will not retrieve files from the root of jar files but rather
method which only returns file system locations for a passed-in empty string (indicating
potential roots to search).
Ant-style patterns with " `classpath:`" resources are not guaranteed to find matching
resources if the root package to search is available in multiple class path locations. This is
because a resource such as
com/mycompany/package1/service-context.xml

may be in only one location, but when a path such as

classpath:com/mycompany/**/service-context.xml

is used to try to resolve it, the resolver will work off the (first) URL returned by
getResource("com/mycompany") ;. If this base package node exists in multiple
classloader locations, the actual end resource may not be underneath. Therefore,
preferably, use " `classpath*:`" with the same Ant-style pattern in such a case, which will
search all class path locations that contain the root package.

8.7.3 FileSystemResource caveats

A FileSystemResource that is not attached to a FileSystemApplicationContext
(that is, a FileSystemApplicationContext is not the actual ResourceLoader ) will
treat absolute vs. relative paths as you would expect. Relative paths are relative to the
current working directory, while absolute paths are relative to the root of the filesystem.
For backwards compatibility (historical) reasons however, this changes when the
FileSystemApplicationContext is the ResourceLoader . The
FileSystemApplicationContext simply forces all attached FileSystemResource
instances to treat all location paths as relative, whether they start with a leading slash or
not. In practice, this means the following are equivalent:
ApplicationContext ctx =
new FileSystemXmlApplicationContext("conf/context.xml");
ApplicationContext ctx =
new FileSystemXmlApplicationContext("/conf/context.xml");

As are the following: (Even though it would make sense for them to be different, as one
case is relative and the other absolute.)
FileSystemXmlApplicationContext ctx = ...;

25/08/2016 12:10

Spring Framework Reference Documentation

248 de 1194

ctx.getResource("some/resource/path/myTemplate.txt");
FileSystemXmlApplicationContext ctx = ...;
ctx.getResource("/some/resource/path/myTemplate.txt");

In practice, if true absolute filesystem paths are needed, it is better to forgo the use of
absolute paths with FileSystemResource / FileSystemXmlApplicationContext ,
and just force the use of a UrlResource , by using the file: URL prefix.
// actual context type doesn't matter, the Resource will always be UrlResource
ctx.getResource("file:///some/resource/path/myTemplate.txt");

// force this FileSystemXmlApplicationContext to load its definition via a UrlResource

ApplicationContext ctx =
new FileSystemXmlApplicationContext("file:///conf/context.xml");

9. Validation, Data Binding, and Type Conversion

9.1 Introduction
JSR-303/JSR-349 Bean Validation
Spring Framework 4.0 supports Bean Validation 1.0 (JSR-303) and Bean Validation
1.1 (JSR-349) in terms of setup support, also adapting it to Springs Validator
interface.
An application can choose to enable Bean Validation once globally, as described in
Section 9.8, Spring Validation, and use it exclusively for all validation needs.
An application can also register additional Spring Validator instances per
DataBinder instance, as described in Section 9.8.3, Configuring a DataBinder.
This may be useful for plugging in validation logic without the use of annotations.
There are pros and cons for considering validation as business logic, and Spring offers a
design for validation (and data binding) that does not exclude either one of them.
Specifically validation should not be tied to the web tier, should be easy to localize and it
should be possible to plug in any validator available. Considering the above, Spring has
come up with a Validator interface that is both basic and eminently usable in every
layer of an application.
Data binding is useful for allowing user input to be dynamically bound to the domain

25/08/2016 12:10

Spring Framework Reference Documentation

249 de 1194

model of an application (or whatever objects you use to process user input). Spring
provides the so-called DataBinder to do exactly that. The Validator and the
DataBinder make up the validation package, which is primarily used in but not
limited to the MVC framework.
The BeanWrapper is a fundamental concept in the Spring Framework and is used in a lot
of places. However, you probably will not have the need to use the BeanWrapper
directly. Because this is reference documentation however, we felt that some explanation
might be in order. We will explain the BeanWrapper in this chapter since, if you were
going to use it at all, you would most likely do so when trying to bind data to objects.
Springs DataBinder and the lower-level BeanWrapper both use PropertyEditors to parse
and format property values. The PropertyEditor concept is part of the JavaBeans
specification, and is also explained in this chapter. Spring 3 introduces a "core.convert"
package that provides a general type conversion facility, as well as a higher-level "format"
package for formatting UI field values. These new packages may be used as simpler
alternatives to PropertyEditors, and will also be discussed in this chapter.

9.2 Validation using Springs Validator interface

Spring features a Validator interface that you can use to validate objects. The
Validator interface works using an Errors object so that while validating, validators
can report validation failures to the Errors object.
Lets consider a small data object:
public class Person {
private String name;
private int age;
// the usual getters and setters...
}

Were going to provide validation behavior for the Person class by implementing the
following two methods of the org.springframework.validation.Validator interface:
supports(Class) - Can this Validator validate instances of the supplied
Class ?
validate(Object, org.springframework.validation.Errors) - validates the
given object and in case of validation errors, registers those with the given Errors
object

25/08/2016 12:10

Spring Framework Reference Documentation

250 de 1194

Implementing a Validator is fairly straightforward, especially when you know of the

ValidationUtils helper class that the Spring Framework also provides.
public class PersonValidator implements Validator {
/**
* This Validator validates *just* Person instances
*/
public boolean supports(Class clazz) {
return Person.class.equals(clazz);
}
public void validate(Object obj, Errors e) {
ValidationUtils.rejectIfEmpty(e, "name", "name.empty");
Person p = (Person) obj;
if (p.getAge() < 0) {
e.rejectValue("age", "negativevalue");
} else if (p.getAge() > 110) {
e.rejectValue("age", "too.darn.old");
}
}
}

As you can see, the static rejectIfEmpty(..) method on the ValidationUtils

class is used to reject the 'name' property if it is null or the empty string. Have a look
at the ValidationUtils javadocs to see what functionality it provides besides the
example shown previously.
While it is certainly possible to implement a single Validator class to validate each of
the nested objects in a rich object, it may be better to encapsulate the validation logic for
each nested class of object in its own Validator implementation. A simple example of a
'rich' object would be a Customer that is composed of two String properties (a first and
second name) and a complex Address object. Address objects may be used
independently of Customer objects, and so a distinct AddressValidator has been
implemented. If you want your CustomerValidator to reuse the logic contained within
the AddressValidator class without resorting to copy-and-paste, you can dependencyinject or instantiate an AddressValidator within your CustomerValidator , and use it
like so:
public class CustomerValidator implements Validator {
private final Validator addressValidator;
public CustomerValidator(Validator addressValidator) {

25/08/2016 12:10

Spring Framework Reference Documentation

251 de 1194

throw new IllegalArgumentException("The supplied [Validator] is "

"required and must not be null.");
}
if (!addressValidator.supports(Address.class)) {
throw new IllegalArgumentException("The supplied [Validator] must "
support the validation of [Address] instances.");
}
this.addressValidator = addressValidator;
}

/**
* This Validator validates Customer instances, and any subclasses of Customer too
*/
public boolean supports(Class clazz) {
return Customer.class.isAssignableFrom(clazz);
}

public void validate(Object target, Errors errors) {

ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "field.required
ValidationUtils.rejectIfEmptyOrWhitespace(errors, "surname", "field.required"
Customer customer = (Customer) target;
try {
errors.pushNestedPath("address");
ValidationUtils.invokeValidator(this.addressValidator, customer.getAddress
} finally {
errors.popNestedPath();
}
}
}

Validation errors are reported to the Errors object passed to the validator. In case of
Spring Web MVC you can use <spring:bind/> tag to inspect the error messages, but
of course you can also inspect the errors object yourself. More information about the
methods it offers can be found in the javadocs.

9.3 Resolving codes to error messages

Weve talked about databinding and validation. Outputting messages corresponding to
validation errors is the last thing we need to discuss. In the example weve shown above,
we rejected the name and the age field. If were going to output the error messages by
using a MessageSource , we will do so using the error code weve given when rejecting
the field ('name' and 'age' in this case). When you call (either directly, or indirectly, using
for example the ValidationUtils class) rejectValue or one of the other reject
methods from the Errors interface, the underlying implementation will not only register

25/08/2016 12:10

Spring Framework Reference Documentation

252 de 1194

the code youve passed in, but also a number of additional error codes. What error codes
it registers is determined by the MessageCodesResolver that is used. By default, the
DefaultMessageCodesResolver is used, which for example not only registers a
message with the code you gave, but also messages that include the field name you
passed to the reject method. So in case you reject a field using
rejectValue("age", "too.darn.old") , apart from the too.darn.old code, Spring
will also register too.darn.old.age and too.darn.old.age.int (so the first will
include the field name and the second will include the type of the field); this is done as a
convenience to aid developers in targeting error messages and suchlike.
More information on the MessageCodesResolver and the default strategy can be found
online in the javadocs of MessageCodesResolver and
DefaultMessageCodesResolver , respectively.

9.4 Bean manipulation and the BeanWrapper

The org.springframework.beans package adheres to the JavaBeans standard
provided by Oracle. A JavaBean is simply a class with a default no-argument constructor,
which follows a naming convention where (by way of an example) a property named
bingoMadness would have a setter method setBingoMadness(..) and a getter
method getBingoMadness() . For more information about JavaBeans and the
specification, please refer to Oracles website ( javabeans).
One quite important class in the beans package is the BeanWrapper interface and its
corresponding implementation ( BeanWrapperImpl ). As quoted from the javadocs, the
BeanWrapper offers functionality to set and get property values (individually or in bulk),
get property descriptors, and to query properties to determine if they are readable or
writable. Also, the BeanWrapper offers support for nested properties, enabling the setting
of properties on sub-properties to an unlimited depth. Then, the BeanWrapper supports
the ability to add standard JavaBeans PropertyChangeListeners and
VetoableChangeListeners , without the need for supporting code in the target class.
Last but not least, the BeanWrapper provides support for the setting of indexed
properties. The BeanWrapper usually isnt used by application code directly, but by the
DataBinder and the BeanFactory .
The way the BeanWrapper works is partly indicated by its name: it wraps a bean to
perform actions on that bean, like setting and retrieving properties.

9.4.1 Setting and getting basic and nested properties

25/08/2016 12:10

Spring Framework Reference Documentation

253 de 1194

Setting and getting properties is done using the setPropertyValue(s) and

getPropertyValue(s) methods that both come with a couple of overloaded variants.
Theyre all described in more detail in the javadocs Spring comes with. Whats important
to know is that there are a couple of conventions for indicating properties of an object. A
couple of examples:

Table 9.1. Examples of properties

Expression
name

Explanation
Indicates the property name corresponding to the
methods getName() or isName() and
setName(..)

account.name

Indicates the nested property name of the property

account corresponding e.g. to the methods
getAccount().setName() or
getAccount().getName()

account[2]

Indicates the third element of the indexed property

account . Indexed properties can be of type
array , list or other naturally ordered collection

account[COMPANYNAME]

Indicates the value of the map entry indexed by the

key COMPANYNAME of the Map property account

Below youll find some examples of working with the BeanWrapper to get and set
properties.
(This next section is not vitally important to you if youre not planning to work with the
BeanWrapper directly. If youre just using the DataBinder and the BeanFactory and
their out-of-the-box implementation, you should skip ahead to the section about
PropertyEditors .)
Consider the following two classes:
public class Company {
private String name;
private Employee managingDirector;

25/08/2016 12:10

Spring Framework Reference Documentation

254 de 1194

public String getName() {

return this.name;
}
public void setName(String name) {
this.name = name;
}
public Employee getManagingDirector() {
return this.managingDirector;
}
public void setManagingDirector(Employee managingDirector) {
this.managingDirector = managingDirector;
}
}
public class Employee {
private String name;
private float salary;
public String getName() {
return this.name;
}
public void setName(String name) {
this.name = name;
}
public float getSalary() {
return salary;
}
public void setSalary(float salary) {
this.salary = salary;
}
}

The following code snippets show some examples of how to retrieve and manipulate
some of the properties of instantiated Companies and Employees :
BeanWrapper company = new BeanWrapperImpl(new Company());
// setting the company name..
company.setPropertyValue("name", "Some Company Inc.");
// ... can also be done like this:

25/08/2016 12:10

Spring Framework Reference Documentation

255 de 1194

PropertyValue value = new PropertyValue("name", "Some Company Inc.");

company.setPropertyValue(value);
// ok, let's create the director and tie it to the company:
BeanWrapper jim = new BeanWrapperImpl(new Employee());
jim.setPropertyValue("name", "Jim Stravinsky");
company.setPropertyValue("managingDirector", jim.getWrappedInstance());
// retrieving the salary of the managingDirector through the company
Float salary = (Float) company.getPropertyValue("managingDirector.salary");

9.4.2 Built-in PropertyEditor implementations

Spring uses the concept of PropertyEditors to effect the conversion between an
Object and a String . If you think about it, it sometimes might be handy to be able to
represent properties in a different way than the object itself. For example, a Date can be
represented in a human readable way (as the String '2007-14-09' ), while were still
able to convert the human readable form back to the original date (or even better: convert
any date entered in a human readable form, back to Date objects). This behavior can be
achieved by registering custom editors, of type java.beans.PropertyEditor .
Registering custom editors on a BeanWrapper or alternately in a specific IoC container
as mentioned in the previous chapter, gives it the knowledge of how to convert properties
to the desired type. Read more about PropertyEditors in the javadocs of the
java.beans package provided by Oracle.
A couple of examples where property editing is used in Spring:
setting properties on beans is done using PropertyEditors . When mentioning
java.lang.String as the value of a property of some bean youre declaring in
XML file, Spring will (if the setter of the corresponding property has a Class parameter) use the ClassEditor to try to resolve the parameter to a Class object.
parsing HTTP request parameters in Springs MVC framework is done using all kinds
of PropertyEditors that you can manually bind in all subclasses of the
CommandController .
Spring has a number of built-in PropertyEditors to make life easy. Each of those is
listed below and they are all located in the
org.springframework.beans.propertyeditors package. Most, but not all (as
indicated below), are registered by default by BeanWrapperImpl . Where the property
editor is configurable in some fashion, you can of course still register your own variant to
override the default one:

25/08/2016 12:10

Spring Framework Reference Documentation

256 de 1194

Table 9.2. Built-in PropertyEditors

Class
ByteArrayPropertyEditor

Explanation
Editor for byte arrays. Strings will simply be
converted to their corresponding byte
representations. Registered by default by
BeanWrapperImpl .

ClassEditor

Parses Strings representing classes to actual

classes and the other way around. When a class
is not found, an IllegalArgumentException is
thrown. Registered by default by
BeanWrapperImpl .

CustomBooleanEditor

Customizable property editor for Boolean

properties. Registered by default by
BeanWrapperImpl , but, can be overridden by
registering custom instance of it as custom
editor.

CustomCollectionEditor

Property editor for Collections, converting any

source Collection to a given target
Collection type.

CustomDateEditor

Customizable property editor for java.util.Date,

supporting a custom DateFormat. NOT
registered by default. Must be user registered as
needed with appropriate format.

CustomNumberEditor

Customizable property editor for any Number

subclass like Integer , Long , Float ,
Double . Registered by default by
BeanWrapperImpl , but can be overridden by
registering custom instance of it as a custom
editor.

FileEditor

Capable of resolving Strings to java.io.File

objects. Registered by default by
BeanWrapperImpl .

InputStreamEditor

One-way property editor, capable of taking a text

string and producing (via an intermediate

25/08/2016 12:10

Spring Framework Reference Documentation

257 de 1194

Class

Explanation
ResourceEditor and Resource ) an
InputStream , so InputStream properties may
be directly set as Strings. Note that the default
usage will not close the InputStream for you!
Registered by default by BeanWrapperImpl .

LocaleEditor

Capable of resolving Strings to Locale objects

and vice versa (the String format is [country]
[variant], which is the same thing the toString()
method of Locale provides). Registered by
default by BeanWrapperImpl .

PatternEditor

Capable of resolving Strings to

java.util.regex.Pattern objects and vice
versa.

PropertiesEditor

Capable of converting Strings (formatted using

the format as defined in the javadocs of the
java.util.Properties class) to Properties
objects. Registered by default by
BeanWrapperImpl .

StringTrimmerEditor

Property editor that trims Strings. Optionally

allows transforming an empty string into a null
value. NOT registered by default; must be user
registered as needed.

URLEditor

Capable of resolving a String representation of a

URL to an actual URL object. Registered by
default by BeanWrapperImpl .

Spring uses the java.beans.PropertyEditorManager to set the search path for

property editors that might be needed. The search path also includes
sun.bean.editors , which includes PropertyEditor implementations for types such
as Font , Color , and most of the primitive types. Note also that the standard JavaBeans
infrastructure will automatically discover PropertyEditor classes (without you having to
register them explicitly) if they are in the same package as the class they handle, and
have the same name as that class, with 'Editor' appended; for example, one could

25/08/2016 12:10

Spring Framework Reference Documentation

258 de 1194

FooEditor class to be recognized and used as the PropertyEditor for Foo -typed
properties.
com
chank
pop
Foo
FooEditor // the PropertyEditor for the Foo class

Note that you can also use the standard BeanInfo JavaBeans mechanism here as well
(described in not-amazing-detail here). Find below an example of using the BeanInfo
mechanism for explicitly registering one or more PropertyEditor instances with the
properties of an associated class.
com
chank
pop
Foo
FooBeanInfo // the BeanInfo for the Foo class

Here is the Java source code for the referenced FooBeanInfo class. This would
associate a CustomNumberEditor with the age property of the Foo class.
public class FooBeanInfo extends SimpleBeanInfo {
public PropertyDescriptor[] getPropertyDescriptors() {
try {
final PropertyEditor numberPE = new CustomNumberEditor(Integer.class
PropertyDescriptor ageDescriptor = new PropertyDescriptor("age", Foo.
public PropertyEditor createPropertyEditor(Object bean) {
return numberPE;
};
};
return new PropertyDescriptor[] { ageDescriptor };
}
catch (IntrospectionException ex) {
throw new Error(ex.toString());
}
}
}

Registering additional custom PropertyEditors

When setting bean properties as a string value, a Spring IoC container ultimately uses
standard JavaBeans PropertyEditors to convert these Strings to the complex type of
the property. Spring pre-registers a number of custom PropertyEditors (for example,
to convert a classname expressed as a string into a real Class object). Additionally,
Javas standard JavaBeans PropertyEditor lookup mechanism allows a
PropertyEditor for a class simply to be named appropriately and placed in the same

25/08/2016 12:10

Spring Framework Reference Documentation

259 de 1194

package as the class it provides support for, to be found automatically.

If there is a need to register other custom PropertyEditors , there are several
mechanisms available. The most manual approach, which is not normally convenient or
recommended, is to simply use the registerCustomEditor() method of the
ConfigurableBeanFactory interface, assuming you have a BeanFactory reference.
Another, slightly more convenient, mechanism is to use a special bean factory
post-processor called CustomEditorConfigurer . Although bean factory
post-processors can be used with BeanFactory implementations, the
CustomEditorConfigurer has a nested property setup, so it is strongly recommended
that it is used with the ApplicationContext , where it may be deployed in similar
fashion to any other bean, and automatically detected and applied.
Note that all bean factories and application contexts automatically use a number of
built-in property editors, through their use of something called a BeanWrapper to handle
property conversions. The standard property editors that the BeanWrapper registers are
listed in the previous section. Additionally, ApplicationContexts also override or add
an additional number of editors to handle resource lookups in a manner appropriate to the
specific application context type.
Standard JavaBeans PropertyEditor instances are used to convert property values
expressed as strings to the actual complex type of the property.
CustomEditorConfigurer , a bean factory post-processor, may be used to conveniently
add support for additional PropertyEditor instances to an ApplicationContext .
Consider a user class ExoticType , and another class DependsOnExoticType which
needs ExoticType set as a property:
package example;
public class ExoticType {
private String name;
public ExoticType(String name) {
this.name = name;
}
}
public class DependsOnExoticType {
private ExoticType type;
public void setType(ExoticType type) {

25/08/2016 12:10

Spring Framework Reference Documentation

260 de 1194

this.type = type;
}
}

When things are properly set up, we want to be able to assign the type property as a
string, which a PropertyEditor will behind the scenes convert into an actual
ExoticType instance:
<bean id="sample" class="example.DependsOnExoticType">
<property name="type" value="aNameForExoticType"/>
</bean>

The PropertyEditor implementation could look similar to this:

// converts string representation to ExoticType object
package example;
public class ExoticTypeEditor extends PropertyEditorSupport {
public void setAsText(String text) {
setValue(new ExoticType(text.toUpperCase()));
}
}

Finally, we use CustomEditorConfigurer to register the new PropertyEditor with

the ApplicationContext , which will then be able to use it as needed:
<bean class="org.springframework.beans.factory.config.CustomEditorConfigurer"
<property name="customEditors">
<map>
<entry key="example.ExoticType" value="example.ExoticTypeEditor"
</map>
</property>
</bean>

Using PropertyEditorRegistrars
Another mechanism for registering property editors with the Spring container is to create
and use a PropertyEditorRegistrar . This interface is particularly useful when you
need to use the same set of property editors in several different situations: write a
corresponding registrar and reuse that in each case. PropertyEditorRegistrars work
in conjunction with an interface called PropertyEditorRegistry , an interface that is
implemented by the Spring BeanWrapper (and DataBinder ).
PropertyEditorRegistrars are particularly convenient when used in conjunction with

25/08/2016 12:10

Spring Framework Reference Documentation

261 de 1194

the CustomEditorConfigurer (introduced here), which exposes a property called

setPropertyEditorRegistrars(..) : PropertyEditorRegistrars added to a
CustomEditorConfigurer in this fashion can easily be shared with DataBinder and
Spring MVC Controllers . Furthermore, it avoids the need for synchronization on
custom editors: a PropertyEditorRegistrar is expected to create fresh
PropertyEditor instances for each bean creation attempt.
Using a PropertyEditorRegistrar is perhaps best illustrated with an example. First
off, you need to create your own PropertyEditorRegistrar implementation:
package com.foo.editors.spring;
public final class CustomPropertyEditorRegistrar implements PropertyEditorRegistrar {
public void registerCustomEditors(PropertyEditorRegistry registry) {
// it is expected that new PropertyEditor instances are created
registry.registerCustomEditor(ExoticType.class, new ExoticTypeEditor());
// you could register as many custom property editors as are required here...
}
}

Spring Framework Reference Documentation

262 de 1194

Find below an example of using a PropertyEditorRegistrar in the implementation of

an initBinder(..) method:
public final class RegisterUserController extends SimpleFormController {
private final PropertyEditorRegistrar customPropertyEditorRegistrar;
public RegisterUserController(PropertyEditorRegistrar propertyEditorRegistrar) {
this.customPropertyEditorRegistrar = propertyEditorRegistrar;
}
protected void initBinder(HttpServletRequest request,
ServletRequestDataBinder binder) throws Exception {
this.customPropertyEditorRegistrar.registerCustomEditors(binder);
}
// other methods to do with registering a User
}

This style of PropertyEditor registration can lead to concise code (the implementation
of initBinder(..) is just one line long!), and allows common PropertyEditor
registration code to be encapsulated in a class and then shared amongst as many
Controllers as needed.

9.5 Spring Type Conversion

Spring 3 introduces a core.convert package that provides a general type conversion
system. The system defines an SPI to implement type conversion logic, as well as an API
to execute type conversions at runtime. Within a Spring container, this system can be
used as an alternative to PropertyEditors to convert externalized bean property value
strings to required property types. The public API may also be used anywhere in your
application where type conversion is needed.

9.5.1 Converter SPI

The SPI to implement type conversion logic is simple and strongly typed:
package org.springframework.core.convert.converter;
public interface Converter<S, T> {
T convert(S source);

25/08/2016 12:10

Spring Framework Reference Documentation

263 de 1194

To create your own converter, simply implement the interface above. Parameterize S as
the type you are converting from, and T as the type you are converting to. Such a
converter can also be applied transparently if a collection or array of S needs to be
converted to an array or collection of T , provided that a delegating array/collection
converter has been registered as well (which DefaultConversionService does by
default).
For each call to convert(S) , the source argument is guaranteed to be NOT null. Your
Converter may throw any unchecked exception if conversion fails; specifically, an
IllegalArgumentException should be thrown to report an invalid source value. Take
care to ensure that your Converter implementation is thread-safe.
Several converter implementations are provided in the core.convert.support
package as a convenience. These include converters from Strings to Numbers and other
common types. Consider StringToInteger as an example for a typical Converter
implementation:
package org.springframework.core.convert.support;
final class StringToInteger implements Converter<String, Integer> {
public Integer convert(String source) {
return Integer.valueOf(source);
}
}

9.5.2 ConverterFactory
When you need to centralize the conversion logic for an entire class hierarchy, for
example, when converting from String to java.lang.Enum objects, implement
ConverterFactory :
package org.springframework.core.convert.converter;
public interface ConverterFactory<S, R> {
<T extends R> Converter<S, T> getConverter(Class<T> targetType);
}

25/08/2016 12:10

Spring Framework Reference Documentation

264 de 1194

the range of classes you can convert to. Then implement getConverter(Class<T>), where
T is a subclass of R.
Consider the StringToEnum ConverterFactory as an example:
package org.springframework.core.convert.support;
final class StringToEnumConverterFactory implements ConverterFactory<String, Enum> {
public <T extends Enum> Converter<String, T> getConverter(Class<T> targetType) {
return new StringToEnumConverter(targetType);
}

private final class StringToEnumConverter<T extends Enum> implements Converter<Str

private Class<T> enumType;
public StringToEnumConverter(Class<T> enumType) {
this.enumType = enumType;
}
public T convert(String source) {
return (T) Enum.valueOf(this.enumType, source.trim());
}
}
}

9.5.3 GenericConverter
When you require a sophisticated Converter implementation, consider the
GenericConverter interface. With a more flexible but less strongly typed signature, a
GenericConverter supports converting between multiple source and target types. In
addition, a GenericConverter makes available source and target field context you can use
when implementing your conversion logic. Such context allows a type conversion to be
driven by a field annotation, or generic information declared on a field signature.
package org.springframework.core.convert.converter;
public interface GenericConverter {
public Set<ConvertiblePair> getConvertibleTypes();

Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType

}

25/08/2016 12:10

Spring Framework Reference Documentation

265 de 1194

To implement a GenericConverter, have getConvertibleTypes() return the supported

sourcetarget type pairs. Then implement convert(Object, TypeDescriptor,
TypeDescriptor) to implement your conversion logic. The source TypeDescriptor provides
access to the source field holding the value being converted. The target TypeDescriptor
provides access to the target field where the converted value will be set.
A good example of a GenericConverter is a converter that converts between a Java Array
and a Collection. Such an ArrayToCollectionConverter introspects the field that declares
the target Collection type to resolve the Collections element type. This allows each
element in the source array to be converted to the Collection element type before the
Collection is set on the target field.

Because GenericConverter is a more complex SPI interface, only use it

when you need it. Favor Converter or ConverterFactory for basic type
conversion needs.

ConditionalGenericConverter
Sometimes you only want a Converter to execute if a specific condition holds true. For
example, you might only want to execute a Converter if a specific annotation is present
on the target field. Or you might only want to execute a Converter if a specific method,
such as a static valueOf method, is defined on the target class.
ConditionalGenericConverter is the union of the GenericConverter and
ConditionalConverter interfaces that allows you to define such custom matching
criteria:
public interface ConditionalGenericConverter
extends GenericConverter, ConditionalConverter {
boolean matches(TypeDescriptor sourceType, TypeDescriptor targetType);
}

A good example of a ConditionalGenericConverter is an EntityConverter that

converts between an persistent entity identifier and an entity reference. Such a
EntityConverter might only match if the target entity type declares a static finder method
e.g. findAccount(Long) . You would perform such a finder method check in the
implementation of matches(TypeDescriptor, TypeDescriptor) .

9.5.4 ConversionService API

25/08/2016 12:10

Spring Framework Reference Documentation

266 de 1194

The ConversionService defines a unified API for executing type conversion logic at
runtime. Converters are often executed behind this facade interface:
package org.springframework.core.convert;
public interface ConversionService {
boolean canConvert(Class<?> sourceType, Class<?> targetType);
<T> T convert(Object source, Class<T> targetType);
boolean canConvert(TypeDescriptor sourceType, TypeDescriptor targetType);

Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType

}

Most ConversionService implementations also implement ConverterRegistry , which

provides an SPI for registering converters. Internally, a ConversionService
implementation delegates to its registered converters to carry out type conversion logic.
A robust ConversionService implementation is provided in the core.convert.support
package. GenericConversionService is the general-purpose implementation suitable
for use in most environments. ConversionServiceFactory provides a convenient
factory for creating common ConversionService configurations.

9.5.5 Configuring a ConversionService

A ConversionService is a stateless object designed to be instantiated at application
startup, then shared between multiple threads. In a Spring application, you typically
configure a ConversionService instance per Spring container (or ApplicationContext).
That ConversionService will be picked up by Spring and then used whenever a type
conversion needs to be performed by the framework. You may also inject this
ConversionService into any of your beans and invoke it directly.

If no ConversionService is registered with Spring, the original

PropertyEditor-based system is used.

To register a default ConversionService with Spring, add the following bean definition with
id conversionService :

25/08/2016 12:10

Spring Framework Reference Documentation

267 de 1194

class="org.springframework.context.support.ConversionServiceFactoryBean"

A default ConversionService can convert between strings, numbers, enums, collections,

maps, and other common types. To supplement or override the default converters with
your own custom converter(s), set the converters property. Property values may
implement either of the Converter, ConverterFactory, or GenericConverter interfaces.
<bean id="conversionService"
class="org.springframework.context.support.ConversionServiceFactoryBean"
<property name="converters">
<set>
<bean class="example.MyCustomConverter"/>
</set>
</property>
</bean>

It is also common to use a ConversionService within a Spring MVC application. See

Section 22.16.3, Conversion and Formatting in the Spring MVC chapter.
In certain situations you may wish to apply formatting during conversion. See
Section 9.6.3, FormatterRegistry SPI for details on using
FormattingConversionServiceFactoryBean .

9.5.6 Using a ConversionService programmatically

To work with a ConversionService instance programmatically, simply inject a reference to
it like you would for any other bean:
@Service
public class MyService {
@Autowired
public MyService(ConversionService conversionService) {
this.conversionService = conversionService;
}
public void doIt() {
this.conversionService.convert(...)
}
}

For most use cases, the convert method specifying the targetType can be used but it
will not work with more complex types such as a collection of a parameterized element. If
you want to convert a List of Integer to a List of String programmatically, for

25/08/2016 12:10

Spring Framework Reference Documentation

268 de 1194

instance, you need to provide a formal definition of the source and target types.
Fortunately, TypeDescriptor provides various options to make that straightforward:
DefaultConversionService cs = new DefaultConversionService();
List<Integer> input = ....
cs.convert(input,
TypeDescriptor.forObject(input), // List<Integer> type descriptor
TypeDescriptor.collection(List.class, TypeDescriptor.valueOf(String.class

Note that DefaultConversionService registers converters automatically which are

appropriate for most environments. This includes collection converters, scalar converters,
and also basic Object to String converters. The same converters can be registered
with any ConverterRegistry using the static addDefaultConverters method on the
DefaultConversionService class.
Converters for value types will be reused for arrays and collections, so there is no need to
create a specific converter to convert from a Collection of S to a Collection of T ,
assuming that standard collection handling is appropriate.

9.6 Spring Field Formatting

As discussed in the previous section, core.convert is a general-purpose type
conversion system. It provides a unified ConversionService API as well as a
strongly-typed Converter SPI for implementing conversion logic from one type to another.
A Spring Container uses this system to bind bean property values. In addition, both the
Spring Expression Language (SpEL) and DataBinder use this system to bind field values.
For example, when SpEL needs to coerce a Short to a Long to complete an
expression.setValue(Object bean, Object value) attempt, the core.convert
system performs the coercion.
Now consider the type conversion requirements of a typical client environment such as a
web or desktop application. In such environments, you typically convert from String to
support the client postback process, as well as back to String to support the view
rendering process. In addition, you often need to localize String values. The more general
core.convert Converter SPI does not address such formatting requirements directly. To
directly address them, Spring 3 introduces a convenient Formatter SPI that provides a
simple and robust alternative to PropertyEditors for client environments.
In general, use the Converter SPI when you need to implement general-purpose type
conversion logic; for example, for converting between a java.util.Date and and

25/08/2016 12:10

Spring Framework Reference Documentation

269 de 1194

java.lang.Long. Use the Formatter SPI when youre working in a client environment, such
as a web application, and need to parse and print localized field values. The
ConversionService provides a unified type conversion API for both SPIs.

9.6.1 Formatter SPI

The Formatter SPI to implement field formatting logic is simple and strongly typed:
package org.springframework.format;
public interface Formatter<T> extends Printer<T>, Parser<T> {
}

Where Formatter extends from the Printer and Parser building-block interfaces:
public interface Printer<T> {
String print(T fieldValue, Locale locale);
}
import java.text.ParseException;
public interface Parser<T> {
T parse(String clientValue, Locale locale) throws ParseException;
}

To create your own Formatter, simply implement the Formatter interface above.
Parameterize T to be the type of object you wish to format, for example,
java.util.Date . Implement the print() operation to print an instance of T for display
in the client locale. Implement the parse() operation to parse an instance of T from the
formatted representation returned from the client locale. Your Formatter should throw a
ParseException or IllegalArgumentException if a parse attempt fails. Take care to ensure
your Formatter implementation is thread-safe.
Several Formatter implementations are provided in format subpackages as a
convenience. The number package provides a NumberFormatter ,
CurrencyFormatter , and PercentFormatter to format java.lang.Number objects
using a java.text.NumberFormat . The datetime package provides a
DateFormatter to format java.util.Date objects with a java.text.DateFormat .
The datetime.joda package provides comprehensive datetime formatting support
based on the Joda Time library.
Consider DateFormatter as an example Formatter implementation:

25/08/2016 12:10

Spring Framework Reference Documentation

270 de 1194

package org.springframework.format.datetime;
public final class DateFormatter implements Formatter<Date> {
private String pattern;
public DateFormatter(String pattern) {
this.pattern = pattern;
}
public String print(Date date, Locale locale) {
if (date == null) {
return "";
}
return getDateFormat(locale).format(date);
}
public Date parse(String formatted, Locale locale) throws ParseException {
if (formatted.length() == 0) {
return null;
}
return getDateFormat(locale).parse(formatted);
}
protected DateFormat getDateFormat(Locale locale) {
DateFormat dateFormat = new SimpleDateFormat(this.pattern, locale);
dateFormat.setLenient(false);
return dateFormat;
}
}

The Spring team welcomes community-driven Formatter contributions; see

jira.spring.io to contribute.

9.6.2 Annotation-driven Formatting

As you will see, field formatting can be configured by field type or annotation. To bind an
Annotation to a formatter, implement AnnotationFormatterFactory:
package org.springframework.format;
public interface AnnotationFormatterFactory<A extends Annotation> {
Set<Class<?>> getFieldTypes();

25/08/2016 12:10

Spring Framework Reference Documentation

271 de 1194

Printer<?> getPrinter(A annotation, Class<?> fieldType);

Parser<?> getParser(A annotation, Class<?> fieldType);
}

Parameterize A to be the field annotationType you wish to associate formatting logic with,
for example org.springframework.format.annotation.DateTimeFormat . Have
getFieldTypes() return the types of fields the annotation may be used on. Have
getPrinter() return a Printer to print the value of an annotated field. Have
getParser() return a Parser to parse a clientValue for an annotated field.
The example AnnotationFormatterFactory implementation below binds the
@NumberFormat Annotation to a formatter. This annotation allows either a number style
or pattern to be specified:
public final class NumberFormatAnnotationFormatterFactory
implements AnnotationFormatterFactory<NumberFormat> {
public Set<Class<?>> getFieldTypes() {
return new HashSet<Class<?>>(asList(new Class<?>[] {
Short.class, Integer.class, Long.class, Float.class,
Double.class, BigDecimal.class, BigInteger.class }));
}
public Printer<Number> getPrinter(NumberFormat annotation, Class<?> fieldType) {
return configureFormatterFrom(annotation, fieldType);
}
public Parser<Number> getParser(NumberFormat annotation, Class<?> fieldType) {
return configureFormatterFrom(annotation, fieldType);
}
private Formatter<Number> configureFormatterFrom(NumberFormat annotation,
Class<?> fieldType) {
if (!annotation.pattern().isEmpty()) {
return new NumberFormatter(annotation.pattern());
} else {
Style style = annotation.style();
if (style == Style.PERCENT) {
return new PercentFormatter();
} else if (style == Style.CURRENCY) {
return new CurrencyFormatter();
} else {
return new NumberFormatter();
}

25/08/2016 12:10

Spring Framework Reference Documentation

272 de 1194

}
}
}

To trigger formatting, simply annotate fields with @NumberFormat:

public class MyModel {
@NumberFormat(style=Style.CURRENCY)
private BigDecimal decimal;
}

Format Annotation API

A portable format annotation API exists in the
org.springframework.format.annotation package. Use @NumberFormat to format
java.lang.Number fields. Use @DateTimeFormat to format java.util.Date,
java.util.Calendar, java.util.Long, or Joda Time fields.
The example below uses @DateTimeFormat to format a java.util.Date as a ISO Date
(yyyy-MM-dd):
public class MyModel {
@DateTimeFormat(iso=ISO.DATE)
private Date date;
}

9.6.3 FormatterRegistry SPI

The FormatterRegistry is an SPI for registering formatters and converters.
FormattingConversionService is an implementation of FormatterRegistry suitable for
most environments. This implementation may be configured programmatically or
declaratively as a Spring bean using FormattingConversionServiceFactoryBean .
Because this implementation also implements ConversionService , it can be directly
configured for use with Springs DataBinder and the Spring Expression Language (SpEL).
Review the FormatterRegistry SPI below:
package org.springframework.format;

25/08/2016 12:10

Spring Framework Reference Documentation

273 de 1194

void addFormatterForFieldType(Class<?> fieldType, Printer<?> printer, Parser<?> pa

void addFormatterForFieldType(Class<?> fieldType, Formatter<?> formatter);
void addFormatterForFieldType(Formatter<?> formatter);
void addFormatterForAnnotation(AnnotationFormatterFactory<?, ?> factory);
}

As shown above, Formatters can be registered by fieldType or annotation.

The FormatterRegistry SPI allows you to configure Formatting rules centrally, instead of
duplicating such configuration across your Controllers. For example, you might want to
enforce that all Date fields are formatted a certain way, or fields with a specific annotation
are formatted in a certain way. With a shared FormatterRegistry, you define these rules
once and they are applied whenever formatting is needed.

9.6.4 FormatterRegistrar SPI

The FormatterRegistrar is an SPI for registering formatters and converters through the
FormatterRegistry:
package org.springframework.format;
public interface FormatterRegistrar {
void registerFormatters(FormatterRegistry registry);
}

A FormatterRegistrar is useful when registering multiple related converters and formatters

for a given formatting category, such as Date formatting. It can also be useful where
declarative registration is insufficient. For example when a formatter needs to be indexed
under a specific field type different from its own <T> or when registering a Printer/Parser
pair. The next section provides more information on converter and formatter registration.

9.6.5 Configuring Formatting in Spring MVC

See Section 22.16.3, Conversion and Formatting in the Spring MVC chapter.

25/08/2016 12:10

Spring Framework Reference Documentation

274 de 1194

9.7 Configuring a global date & time format

By default, date and time fields that are not annotated with @DateTimeFormat are
converted from strings using the DateFormat.SHORT style. If you prefer, you can change
this by defining your own global format.
You will need to ensure that Spring does not register default formatters, and instead you
should register all formatters manually. Use the
org.springframework.format.datetime.joda.JodaTimeFormatterRegistrar or
org.springframework.format.datetime.DateFormatterRegistrar class
depending on whether you use the Joda Time library.
For example, the following Java configuration will register a global ' `yyyyMMdd format.
This example does not depend on the Joda Time library:
@Configuration
public class AppConfig {
@Bean
public FormattingConversionService conversionService() {

// Use the DefaultFormattingConversionService but do not register defaults

DefaultFormattingConversionService conversionService = new DefaultFormattingCo

// Ensure @NumberFormat is still supported

conversionService.addFormatterForFieldAnnotation(new NumberFormatAnnotationFor
// Register date conversion with a specific global format
DateFormatterRegistrar registrar = new DateFormatterRegistrar();
registrar.setFormatter(new DateFormatter("yyyyMMdd"));
registrar.registerFormatters(conversionService);
return conversionService;
}
}

If you prefer XML based configuration you can use a

FormattingConversionServiceFactoryBean . Here is the same example, this time
using Joda Time:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans

25/08/2016 12:10

Spring Framework Reference Documentation

275 de 1194

http://www.springframework.org/schema/beans/spring-beans.xsd>

<bean id="conversionService" class="org.springframework.format.support.FormattingC

Joda Time provides separate distinct types to represent date , time and
date-time values. The dateFormatter , timeFormatter and
dateTimeFormatter properties of the JodaTimeFormatterRegistrar
should be used to configure the different formats for each type. The
DateTimeFormatterFactoryBean provides a convenient way to create
formatters.

If you are using Spring MVC remember to explicitly configure the conversion service that
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 Section 22.16.3, Conversion and Formatting
for details.

9.8 Spring Validation

Spring 3 introduces several enhancements to its validation support. First, the JSR-303
Bean Validation API is now fully supported. Second, when used programmatically,
Springs DataBinder can now validate objects as well as bind to them. Third, Spring MVC

25/08/2016 12:10

Spring Framework Reference Documentation

276 de 1194

now has support for declaratively validating @Controller inputs.

9.8.1 Overview of the JSR-303 Bean Validation API

JSR-303 standardizes validation constraint declaration and metadata for the Java
platform. Using this API, you annotate domain model properties with declarative
validation constraints and the runtime enforces them. There are a number of built-in
constraints you can take advantage of. You may also define your own custom constraints.
To illustrate, consider a simple PersonForm model with two properties:
public class PersonForm {
private String name;
private int age;
}

JSR-303 allows you to define declarative validation constraints against such properties:
public class PersonForm {
@NotNull
@Size(max=64)
private String name;
@Min(0)
private int age;
}

When an instance of this class is validated by a JSR-303 Validator, these constraints will
be enforced.
For general information on JSR-303/JSR-349, see the Bean Validation website. For
information on the specific capabilities of the default reference implementation, see the
Hibernate Validator documentation. To learn how to setup a Bean Validation provider as a
Spring bean, keep reading.

9.8.2 Configuring a Bean Validation Provider

Spring provides full support for the Bean Validation API. This includes convenient support
for bootstrapping a JSR-303/JSR-349 Bean Validation provider as a Spring bean. This
allows for a javax.validation.ValidatorFactory or
javax.validation.Validator to be injected wherever validation is needed in your

25/08/2016 12:10

Spring Framework Reference Documentation

277 de 1194

application.
Use the LocalValidatorFactoryBean to configure a default Validator as a Spring
bean:
<bean id="validator"
class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean"

The basic configuration above will trigger Bean Validation to initialize using its default
bootstrap mechanism. A JSR-303/JSR-349 provider, such as Hibernate Validator, is
expected to be present in the classpath and will be detected automatically.

Injecting a Validator
LocalValidatorFactoryBean implements both
javax.validation.ValidatorFactory and javax.validation.Validator , as well
as Springs org.springframework.validation.Validator . You may inject a
reference to either of these interfaces into beans that need to invoke validation logic.
Inject a reference to javax.validation.Validator if you prefer to work with the Bean
Validation API directly:
import javax.validation.Validator;
@Service
public class MyService {
@Autowired
private Validator validator;

Inject a reference to org.springframework.validation.Validator if your bean

requires the Spring Validation API:
import org.springframework.validation.Validator;
@Service
public class MyService {
@Autowired
private Validator validator;
}

Configuring Custom Constraints

25/08/2016 12:10

Spring Framework Reference Documentation

278 de 1194

Each Bean Validation constraint consists of two parts. First, a @Constraint annotation
that declares the constraint and its configurable properties. Second, an implementation of
the javax.validation.ConstraintValidator interface that implements the
constraints behavior. To associate a declaration with an implementation, each
@Constraint annotation references a corresponding ValidationConstraint
implementation class. At runtime, a ConstraintValidatorFactory instantiates the
referenced implementation when the constraint annotation is encountered in your domain
model.
By default, the LocalValidatorFactoryBean configures a
SpringConstraintValidatorFactory that uses Spring to create ConstraintValidator
instances. This allows your custom ConstraintValidators to benefit from dependency
injection like any other Spring bean.
Shown below is an example of a custom @Constraint declaration, followed by an
associated ConstraintValidator implementation that uses Spring for dependency
injection:
@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy=MyConstraintValidator.class)
public @interface MyConstraint {
}
import javax.validation.ConstraintValidator;
public class MyConstraintValidator implements ConstraintValidator {
@Autowired;
private Foo aDependency;
...
}

As you can see, a ConstraintValidator implementation may have its dependencies

@Autowired like any other Spring bean.

Spring-driven Method Validation

The method validation feature supported by Bean Validation 1.1, and as a custom
extension also by Hibernate Validator 4.3, can be integrated into a Spring context through
a MethodValidationPostProcessor bean definition:

25/08/2016 12:10

Spring Framework Reference Documentation

279 de 1194

<bean class="org.springframework.validation.beanvalidation.MethodValidationPostProcess

In order to be eligible for Spring-driven method validation, all target classes need to be
annotated with Springs @Validated annotation, optionally declaring the validation
groups to use. Check out the MethodValidationPostProcessor javadocs for setup
details with Hibernate Validator and Bean Validation 1.1 providers.

Additional Configuration Options

The default LocalValidatorFactoryBean configuration should prove sufficient for most
cases. There are a number of configuration options for various Bean Validation
constructs, from message interpolation to traversal resolution. See the
LocalValidatorFactoryBean javadocs for more information on these options.

9.8.3 Configuring a DataBinder

Since Spring 3, a DataBinder instance can be configured with a Validator. Once
configured, the Validator may be invoked by calling binder.validate() . Any validation
Errors are automatically added to the binders BindingResult.
When working with the DataBinder programmatically, this can be used to invoke
validation logic after binding to a target object:
Foo target = new Foo();
DataBinder binder = new DataBinder(target);
binder.setValidator(new FooValidator());
// bind to the target object
binder.bind(propertyValues);
// validate the target object
binder.validate();
// get BindingResult that includes any validation errors
BindingResult results = binder.getBindingResult();

A DataBinder can also be configured with multiple Validator instances via

dataBinder.addValidators and dataBinder.replaceValidators . This is useful
when combining globally configured Bean Validation with a Spring Validator configured
locally on a DataBinder instance. See ???.

9.8.4 Spring MVC 3 Validation

25/08/2016 12:10

Spring Framework Reference Documentation

280 de 1194

See Section 22.16.4, Validation in the Spring MVC chapter.

10. Spring Expression Language (SpEL)

10.1 Introduction
The Spring Expression Language (SpEL for short) is a powerful expression language that
supports querying and manipulating an object graph at runtime. The language syntax is
similar to Unified EL but offers additional features, most notably method invocation and
basic string templating functionality.
While there are several other Java expression languages available, OGNL, MVEL, and
JBoss EL, to name a few, the Spring Expression Language was created to provide the
Spring community with a single well supported expression language that can be used
across all the products in the Spring portfolio. Its language features are driven by the
requirements of the projects in the Spring portfolio, including tooling requirements for
code completion support within the eclipse based Spring Tool Suite. That said, SpEL is
based on a technology agnostic API allowing other expression language implementations
to be integrated should the need arise.
While SpEL serves as the foundation for expression evaluation within the Spring portfolio,
it is not directly tied to Spring and can be used independently. In order to be self
contained, many of the examples in this chapter use SpEL as if it were an independent
expression language. This requires creating a few bootstrapping infrastructure classes
such as the parser. Most Spring users will not need to deal with this infrastructure and will
instead only author expression strings for evaluation. An example of this typical use is the
integration of SpEL into creating XML or annotated based bean definitions as shown in
the section Expression support for defining bean definitions.
This chapter covers the features of the expression language, its API, and its language
syntax. In several places an Inventor and Inventors Society class are used as the target
objects for expression evaluation. These class declarations and the data used to populate
them are listed at the end of the chapter.

10.2 Feature Overview

The expression language supports the following functionality
Literal expressions

25/08/2016 12:10

Spring Framework Reference Documentation

281 de 1194

Boolean and relational operators

Regular expressions
Class expressions
Accessing properties, arrays, lists, maps
Method invocation
Relational operators
Assignment
Calling constructors
Bean references
Array construction
Inline lists
Inline maps
Ternary operator
Variables
User defined functions
Collection projection
Collection selection
Templated expressions

10.3 Expression Evaluation using Springs Expression

Interface
This section introduces the simple use of SpEL interfaces and its expression language.
The complete language reference can be found in the section Language Reference.
The following code introduces the SpEL API to evaluate the literal string expression 'Hello
World'.
ExpressionParser parser = new SpelExpressionParser();
Expression exp = parser.parseExpression("'Hello World'");
String message = (String) exp.getValue();

The value of the message variable is simply 'Hello World'.

The SpEL classes and interfaces you are most likely to use are located in the packages
org.springframework.expression and its sub packages and spel.support .
The interface ExpressionParser is responsible for parsing an expression string. In this
example the expression string is a string literal denoted by the surrounding single quotes.
The interface Expression is responsible for evaluating the previously defined

25/08/2016 12:10

Spring Framework Reference Documentation

282 de 1194

EvaluationException when calling parser.parseExpression and exp.getValue

respectively.
SpEL supports a wide range of features, such as calling methods, accessing properties,
and calling constructors.
As an example of method invocation, we call the concat method on the string literal.
ExpressionParser parser = new SpelExpressionParser();
Expression exp = parser.parseExpression("'Hello World'.concat('!')");
String message = (String) exp.getValue();

The value of message is now 'Hello World!'.

As an example of calling a JavaBean property, the String property Bytes can be called
as shown below.
ExpressionParser parser = new SpelExpressionParser();
// invokes 'getBytes()'
Expression exp = parser.parseExpression("'Hello World'.bytes");
byte[] bytes = (byte[]) exp.getValue();

SpEL also supports nested properties using standard dot notation, i.e. prop1.prop2.prop3
and the setting of property values
Public fields may also be accessed.
ExpressionParser parser = new SpelExpressionParser();
// invokes 'getBytes().length'
Expression exp = parser.parseExpression("'Hello World'.bytes.length");
int length = (Integer) exp.getValue();

The Strings constructor can be called instead of using a string literal.

ExpressionParser parser = new SpelExpressionParser();
Expression exp = parser.parseExpression("new String('hello world').toUpperCase()
String message = exp.getValue(String.class);

Note the use of the generic method

public <T> T getValue(Class<T> desiredResultType) . Using this method
removes the need to cast the value of the expression to the desired result type. An
EvaluationException will be thrown if the value cannot be cast to the type T or
converted using the registered type converter.

25/08/2016 12:10

Spring Framework Reference Documentation

283 de 1194

The more common usage of SpEL is to provide an expression string that is evaluated
against a specific object instance (called the root object). There are two options here and
which to choose depends on whether the object against which the expression is being
evaluated will be changing with each call to evaluate the expression. In the following
example we retrieve the name property from an instance of the Inventor class.
// Create and set a calendar
GregorianCalendar c = new GregorianCalendar();
c.set(1856, 7, 9);
// The constructor arguments are name, birthday, and nationality.
Inventor tesla = new Inventor("Nikola Tesla", c.getTime(), "Serbian");
ExpressionParser parser = new SpelExpressionParser();
Expression exp = parser.parseExpression("name");
EvaluationContext context = new StandardEvaluationContext(tesla);
String name = (String) exp.getValue(context);

In the last line, the value of the string variable name will be set to "Nikola Tesla". The
class StandardEvaluationContext is where you can specify which object the "name"
property will be evaluated against. This is the mechanism to use if the root object is
unlikely to change, it can simply be set once in the evaluation context. If the root object is
likely to change repeatedly, it can be supplied on each call to getValue , as this next
example shows:
/ Create and set a calendar
GregorianCalendar c = new GregorianCalendar();
c.set(1856, 7, 9);
// The constructor arguments are name, birthday, and nationality.
Inventor tesla = new Inventor("Nikola Tesla", c.getTime(), "Serbian");
ExpressionParser parser = new SpelExpressionParser();
Expression exp = parser.parseExpression("name");
String name = (String) exp.getValue(tesla);

In this case the inventor tesla has been supplied directly to getValue and the
expression evaluation infrastructure creates and manages a default evaluation context
internally - it did not require one to be supplied.
The StandardEvaluationContext is relatively expensive to construct and during repeated
usage it builds up cached state that enables subsequent expression evaluations to be
performed more quickly. For this reason it is better to cache and reuse them where

25/08/2016 12:10

Spring Framework Reference Documentation

284 de 1194

In some cases it can be desirable to use a configured evaluation context and yet still
supply a different root object on each call to getValue . getValue allows both to be
specified on the same call. In these situations the root object passed on the call is
considered to override any (which maybe null) specified on the evaluation context.

In standalone usage of SpEL there is a need to create the parser, parse

expressions and perhaps provide evaluation contexts and a root context
object. However, more common usage is to provide only the SpEL
expression string as part of a configuration file, for example for Spring bean
or Spring Web Flow definitions. In this case, the parser, evaluation context,
root object and any predefined variables are all set up implicitly, requiring
the user to specify nothing other than the expressions.

As a final introductory example, the use of a boolean operator is shown using the Inventor
object in the previous example.
Expression exp = parser.parseExpression("name == 'Nikola Tesla'");
boolean result = exp.getValue(context, Boolean.class); // evaluates to true

10.3.1 The EvaluationContext interface

The interface EvaluationContext is used when evaluating an expression to resolve
properties, methods, fields, and to help perform type conversion. The out-of-the-box
implementation, StandardEvaluationContext , uses reflection to manipulate the object,
caching java.lang.reflect.Method , java.lang.reflect.Field , and
java.lang.reflect.Constructor instances for increased performance.
The StandardEvaluationContext is where you may specify the root object to evaluate
against via the method setRootObject() or passing the root object into the constructor.
You can also specify variables and functions that will be used in the expression using the
methods setVariable() and registerFunction() . The use of variables and
functions are described in the language reference sections Variables and Functions. The
StandardEvaluationContext is also where you can register custom
ConstructorResolver s, MethodResolver s, and PropertyAccessor s to extend how
SpEL evaluates expressions. Please refer to the JavaDoc of these classes for more
details.

Type Conversion

25/08/2016 12:10

Spring Framework Reference Documentation

285 de 1194

org.springframework.core.convert.ConversionService ). This conversion service

comes with many converters built in for common conversions but is also fully extensible
so custom conversions between types can be added. Additionally it has the key capability
that it is generics aware. This means that when working with generic types in
expressions, SpEL will attempt conversions to maintain type correctness for any objects it
encounters.
What does this mean in practice? Suppose assignment, using setValue() , is being
used to set a List property. The type of the property is actually List<Boolean> . SpEL
will recognize that the elements of the list need to be converted to Boolean before being
placed in it. A simple example:
class Simple {
public List<Boolean> booleanList = new ArrayList<Boolean>();
}
Simple simple = new Simple();
simple.booleanList.add(true);
StandardEvaluationContext simpleContext = new StandardEvaluationContext(simple);
// false is passed in here as a string. SpEL and the conversion service will
// correctly recognize that it needs to be a Boolean and convert it
parser.parseExpression("booleanList[0]").setValue(simpleContext, "false");
// b will be false
Boolean b = simple.booleanList.get(0);

10.3.2 Parser configuration

It is possible to configure the SpEL expression parser using a parser configuration object
( org.springframework.expression.spel.SpelParserConfiguration ). The
configuration object controls the behavior of some of the expression components. For
example, if indexing into an array or collection and the element at the specified index is
null it is possible to automatically create the element. This is useful when using
expressions made up of a chain of property references. If indexing into an array or list
and specifying an index that is beyond the end of the current size of the array or list it is
possible to automatically grow the array or list to accommodate that index.
class Demo {
public List<String> list;
}

25/08/2016 12:10

Spring Framework Reference Documentation

286 de 1194

// Turn on:
// - auto null reference initialization
// - auto collection growing
SpelParserConfiguration config = new SpelParserConfiguration(true,true);
ExpressionParser parser = new SpelExpressionParser(config);
Expression expression = parser.parseExpression("list[3]");
Demo demo = new Demo();
Object o = expression.getValue(demo);
// demo.list will now be a real collection of 4 entries
// Each entry is a new empty String

It is also possible to configure the behaviour of the SpEL expression compiler.

10.3.3 SpEL compilation

Spring Framework 4.1 includes a basic expression compiler. Expressions are usually
interpreted which provides a lot of dynamic flexibility during evaluation but does not
provide the optimum performance. For occasional expression usage this is fine, but when
used by other components like Spring Integration, performance can be very important
and there is no real need for the dynamism.
The new SpEL compiler is intended to address this need. The compiler will generate a
real Java class on the fly during evaluation that embodies the expression behavior and
use that to achieve much faster expression evaluation. Due to the lack of typing around
expressions the compiler uses information gathered during the interpreted evaluations of
an expression when performing compilation. For example, it does not know the type of a
property reference purely from the expression but during the first interpreted evaluation it
will find out what it is. Of course, basing the compilation on this information could cause
trouble later if the types of the various expression elements change over time. For this
reason compilation is best suited to expressions whose type information is not going to
change on repeated evaluations.
For a basic expression like this:
someArray[0].someProperty.someOtherProperty < 0.1
which involves array access, some property derefencing and numeric operations, the
performance gain can be very noticeable. In an example micro benchmark run of 50000

25/08/2016 12:10

Spring Framework Reference Documentation

287 de 1194

iterations, it was taking 75ms to evaluate using only the interpreter and just 3ms using the
compiled version of the expression.

Compiler configuration
The compiler is not turned on by default, but there are two ways to turn it on. It can be
turned on using the parser configuration process discussed earlier or via a system
property when SpEL usage is embedded inside another component. This section
discusses both of these options.
Is is important to understand that there are a few modes the compiler can operate in,
captured in an enum ( org.springframework.expression.spel.SpelCompilerMode ).
The modes are as follows:
OFF - The compiler is switched off; this is the default.
IMMEDIATE - In immediate mode the expressions are compiled as soon as possible.
This is typically after the first interpreted evaluation. If the compiled expression fails
(typically due to a type changing, as described above) then the caller of the
expression evaluation will receive an exception.
MIXED - In mixed mode the expressions silently switch between interpreted and
compiled mode over time. After some number of interpreted runs they will switch to
compiled form and if something goes wrong with the compiled form (like a type
changing, as described above) then the expression will automatically switch back to
interpreted form again. Sometime later it may generate another compiled form and
switch to it. Basically the exception that the user gets in IMMEDIATE mode is instead
handled internally.
IMMEDIATE mode exists because MIXED mode could cause issues for expressions that
have side effects. If a compiled expression blows up after partially succeeding it may
have already done something that has affected the state of the system. If this has
happened the caller may not want it to silently re-run in interpreted mode since part of the
expression may be running twice.
After selecting a mode, use the SpelParserConfiguration to configure the parser:

SpelParserConfiguration config = new SpelParserConfiguration(SpelCompilerMode.IMMEDIAT

this.getClass().getClassLoader());
SpelExpressionParser parser = new SpelExpressionParser(config);
Expression expr = parser.parseExpression("payload");
MyMessage message = new MyMessage();

25/08/2016 12:10

Spring Framework Reference Documentation

288 de 1194

Object payload = expr.getValue(message);

When specifying the compiler mode it is also possible to specify a classloader (passing
null is allowed). Compiled expressions will be defined in a child classloader created under
any that is supplied. It is important to ensure if a classloader is specified it can see all the
types involved in the expression evaluation process. If none is specified then a default
classloader will be used (typically the context classloader for the thread that is running
during expression evaluation).
The second way to configure the compiler is for use when SpEL is embedded inside
some other component and it may not be possible to configure via a configuration object.
In these cases it is possible to use a system property. The property
spring.expression.compiler.mode can be set to one of the SpelCompilerMode
enum values ( off , immediate , or mixed ).

Compiler limitations
With Spring Framework 4.1 the basic compilation framework is in place. However, the
framework does not yet support compiling every kind of expression. The initial focus has
been on the common expressions that are likely to be used in performance critical
contexts. These kinds of expression cannot be compiled at the moment:
expressions involving assignment
expressions relying on the conversion service
expressions using custom resolvers or accessors
expressions using selection or projection
More and more types of expression will be compilable in the future.

10.4 Expression support for defining bean definitions

SpEL expressions can be used with XML or annotation-based configuration metadata for
defining BeanDefinition s. In both cases the syntax to define the expression is of the
form #{ <expression string> } .

10.4.1 XML based configuration

A property or constructor-arg value can be set using expressions as shown below.
<bean id="numberGuess" class="org.spring.samples.NumberGuess">

25/08/2016 12:10

Spring Framework Reference Documentation

289 de 1194

<property name="randomNumber" value="#{ T(java.lang.Math).random() * 100.0 }"

</bean>

The variable systemProperties is predefined, so you can use it in your expressions as

shown below. Note that you do not have to prefix the predefined variable with the #
symbol in this context.
<bean id="taxCalculator" class="org.spring.samples.TaxCalculator">
<property name="defaultLocale" value="#{ systemProperties['user.region'] }"

</bean>

You can also refer to other bean properties by name, for example.
<bean id="numberGuess" class="org.spring.samples.NumberGuess">
<property name="randomNumber" value="#{ T(java.lang.Math).random() * 100.0 }"

</bean>
<bean id="shapeGuess" class="org.spring.samples.ShapeGuess">
<property name="initialShapeSeed" value="#{ numberGuess.randomNumber }"/>

</bean>

10.4.2 Annotation-based configuration

The @Value annotation can be placed on fields, methods and method/constructor
parameters to specify a default value.
Here is an example to set the default value of a field variable.
public static class FieldValueTestBean
@Value("#{ systemProperties['user.region'] }")
private String defaultLocale;
public void setDefaultLocale(String defaultLocale) {
this.defaultLocale = defaultLocale;
}

25/08/2016 12:10

Spring Framework Reference Documentation

290 de 1194

public String getDefaultLocale() {

return this.defaultLocale;
}
}

The equivalent but on a property setter method is shown below.

public static class PropertyValueTestBean
private String defaultLocale;
@Value("#{ systemProperties['user.region'] }")
public void setDefaultLocale(String defaultLocale) {
this.defaultLocale = defaultLocale;
}
public String getDefaultLocale() {
return this.defaultLocale;
}
}

Autowired methods and constructors can also use the @Value annotation.
public class SimpleMovieLister {
private MovieFinder movieFinder;
private String defaultLocale;
@Autowired
public void configure(MovieFinder movieFinder,
@Value("#{ systemProperties['user.region'] }") String defaultLocale) {
this.movieFinder = movieFinder;
this.defaultLocale = defaultLocale;
}
// ...
}
public class MovieRecommender {
private String defaultLocale;
private CustomerPreferenceDao customerPreferenceDao;
@Autowired

25/08/2016 12:10

Spring Framework Reference Documentation

291 de 1194

public MovieRecommender(CustomerPreferenceDao customerPreferenceDao,

@Value("#{systemProperties['user.country']}") String defaultLocale) {
this.customerPreferenceDao = customerPreferenceDao;
this.defaultLocale = defaultLocale;
}
// ...
}

10.5 Language Reference

10.5.1 Literal expressions
The types of literal expressions supported are strings, dates, numeric values (int, real,
and hex), boolean and null. Strings are delimited by single quotes. To put a single quote
itself in a string use two single quote characters. The following listing shows simple usage
of literals. Typically they would not be used in isolation like this, but as part of a more
complex expression, for example using a literal on one side of a logical comparison
operator.
ExpressionParser parser = new SpelExpressionParser();
// evals to "Hello World"
String helloWorld = (String) parser.parseExpression("'Hello World'").getValue();
double avogadrosNumber = (Double) parser.parseExpression("6.0221415E+23").getValue();
// evals to 2147483647
int maxValue = (Integer) parser.parseExpression("0x7FFFFFFF").getValue();
boolean trueValue = (Boolean) parser.parseExpression("true").getValue();
Object nullValue = parser.parseExpression("null").getValue();

Numbers support the use of the negative sign, exponential notation, and decimal points.
By default real numbers are parsed using Double.parseDouble().

10.5.2 Properties, Arrays, Lists, Maps, Indexers

Navigating with property references is easy: just use a period to indicate a nested
property value. The instances of the Inventor class, pupin, and tesla, were populated
with data listed in the section Classes used in the examples. To navigate "down" and get

25/08/2016 12:10

Spring Framework Reference Documentation

292 de 1194

Teslas year of birth and Pupins city of birth the following expressions are used.

// evals to 1856
int year = (Integer) parser.parseExpression("Birthdate.Year + 1900").getValue(context)
String city = (String) parser.parseExpression("placeOfBirth.City").getValue(context);

Case insensitivity is allowed for the first letter of property names. The contents of arrays
and lists are obtained using square bracket notation.
ExpressionParser parser = new SpelExpressionParser();
// Inventions Array
StandardEvaluationContext teslaContext = new StandardEvaluationContext(tesla);
// evaluates to "Induction motor"
String invention = parser.parseExpression("inventions[3]").getValue(
teslaContext, String.class);
// Members List
StandardEvaluationContext societyContext = new StandardEvaluationContext(ieee);
// evaluates to "Nikola Tesla"
String name = parser.parseExpression("Members[0].Name").getValue(
societyContext, String.class);
// List and Array navigation
// evaluates to "Wireless communication"
String invention = parser.parseExpression("Members[0].Inventions[6]").getValue(
societyContext, String.class);

The contents of maps are obtained by specifying the literal key value within the brackets.
In this case, because keys for the Officers map are strings, we can specify string literals.
// Officer's Dictionary
Inventor pupin = parser.parseExpression("Officers['president']").getValue(
societyContext, Inventor.class);
// evaluates to "Idvor"
String city = parser.parseExpression("Officers['president'].PlaceOfBirth.City"
societyContext, String.class);
// setting values
parser.parseExpression("Officers['advisors'][0].PlaceOfBirth.Country").setValue(
societyContext, "Croatia");

25/08/2016 12:10

Spring Framework Reference Documentation

293 de 1194

10.5.3 Inline lists

Lists can be expressed directly in an expression using {} notation.
// evaluates to a Java list containing the four numbers
List numbers = (List) parser.parseExpression("{1,2,3,4}").getValue(context);

List listOfLists = (List) parser.parseExpression("{{'a','b'},{'x','y'}}").getValue(con

{} by itself means an empty list. For performance reasons, if the list is itself entirely
composed of fixed literals then a constant list is created to represent the expression,
rather than building a new list on each evaluation.

10.5.4 Inline Maps

Maps can also be expressed directly in an expression using {key:value} notation.
// evaluates to a Java map containing the two entries
Map inventorInfo = (Map) parser.parseExpression("{name:'Nikola',dob:'10-July-1856'}"

Map mapOfMaps = (Map) parser.parseExpression("{name:{first:'Nikola',last:'Tesla'},dob:

{:} by itself means an empty map. For performance reasons, if the map is itself
composed of fixed literals or other nested constant structures (lists or maps) then a
constant map is created to represent the expression, rather than building a new map on
each evaluation. Quoting of the map keys is optional, the examples above are not using
quoted keys.

10.5.5 Array construction

Arrays can be built using the familiar Java syntax, optionally supplying an initializer to
have the array populated at construction time.
int[] numbers1 = (int[]) parser.parseExpression("new int[4]").getValue(context);

// Array with initializer

int[] numbers2 = (int[]) parser.parseExpression("new int[]{1,2,3}").getValue(context);

// Multi dimensional array

int[][] numbers3 = (int[][]) parser.parseExpression("new int[4][5]").getValue(context)

It is not currently allowed to supply an initializer when constructing a multi-dimensional

array.

25/08/2016 12:10

Spring Framework Reference Documentation

294 de 1194

10.5.6 Methods
Methods are invoked using typical Java programming syntax. You may also invoke
methods on literals. Varargs are also supported.
// string literal, evaluates to "bc"
String c = parser.parseExpression("'abc'.substring(2, 3)").getValue(String.class
// evaluates to true
boolean isMember = parser.parseExpression("isMember('Mihajlo Pupin')").getValue(
societyContext, Boolean.class);

10.5.7 Operators
Relational operators
The relational operators; equal, not equal, less than, less than or equal, greater than, and
greater than or equal are supported using standard operator notation.
// evaluates to true
boolean trueValue = parser.parseExpression("2 == 2").getValue(Boolean.class);
// evaluates to false
boolean falseValue = parser.parseExpression("2 < -5.0").getValue(Boolean.class
// evaluates to true
boolean trueValue = parser.parseExpression("'black' < 'block'").getValue(Boolean.

In addition to standard relational operators SpEL supports the instanceof and regular
expression based matches operator.
// evaluates to false
boolean falseValue = parser.parseExpression(
"'xyz' instanceof T(Integer.class)").getValue(Boolean.class);
// evaluates to true
boolean trueValue = parser.parseExpression(
"'5.00' matches '\^-?\\d+(\\.\\d{2})?$'").getValue(Boolean.class);
//evaluates to false
boolean falseValue = parser.parseExpression(
"'5.0067' matches '\^-?\\d+(\\.\\d{2})?$'").getValue(Boolean.class);

25/08/2016 12:10

Spring Framework Reference Documentation

295 de 1194

Be careful with primitive types as they are immediately boxed up to the

wrapper type, so 1 instanceof T(int) evaluates to false while
1 instanceof T(Integer.class) evaluates to true , as expected.

Each symbolic operator can also be specified as a purely alphabetic equivalent. This
avoids problems where the symbols used have special meaning for the document type in
which the expression is embedded (eg. an XML document). The textual equivalents are
shown here: lt ( < ), gt ( > ), le ( ), ge ( >= ), eq ( == ), ne ( != ), div ( / ), mod
( % ), not ( ! ). These are case insensitive.

Logical operators
The logical operators that are supported are and, or, and not. Their use is demonstrated
below.
// -- AND -// evaluates to false
boolean falseValue = parser.parseExpression("true and false").getValue(Boolean.

// evaluates to true
String expression = "isMember('Nikola Tesla') and isMember('Mihajlo Pupin')"
boolean trueValue = parser.parseExpression(expression).getValue(societyContext, Boolea
// -- OR -// evaluates to true
boolean trueValue = parser.parseExpression("true or false").getValue(Boolean.

// evaluates to true
String expression = "isMember('Nikola Tesla') or isMember('Albert Einstein')"
boolean trueValue = parser.parseExpression(expression).getValue(societyContext, Boolea
// -- NOT -// evaluates to false
boolean falseValue = parser.parseExpression("!true").getValue(Boolean.class);

// -- AND and NOT -String expression = "isMember('Nikola Tesla') and !isMember('Mihajlo Pupin')"
boolean falseValue = parser.parseExpression(expression).getValue(societyContext, Boole

Mathematical operators

25/08/2016 12:10

Spring Framework Reference Documentation

296 de 1194

The addition operator can be used on both numbers and strings. Subtraction,
multiplication and division can be used only on numbers. Other mathematical operators
supported are modulus (%) and exponential power (^). Standard operator precedence is
enforced. These operators are demonstrated below.
// Addition
int two = parser.parseExpression("1 + 1").getValue(Integer.class); // 2
String testString = parser.parseExpression(
"'test' + ' ' + 'string'").getValue(String.class); // 'test string'
// Subtraction
int four = parser.parseExpression("1 - -3").getValue(Integer.class); // 4
double d = parser.parseExpression("1000.00 - 1e4").getValue(Double.class); // -9000
// Multiplication
int six = parser.parseExpression("-2 * -3").getValue(Integer.class); // 6
double twentyFour = parser.parseExpression("2.0 * 3e0 * 4").getValue(Double.
// Division
int minusTwo = parser.parseExpression("6 / -3").getValue(Integer.class); // -2
double one = parser.parseExpression("8.0 / 4e0 / 2").getValue(Double.class);
// Modulus
int three = parser.parseExpression("7 % 4").getValue(Integer.class); // 3
int one = parser.parseExpression("8 / 5 % 2").getValue(Integer.class); // 1
// Operator precedence
int minusTwentyOne = parser.parseExpression("1+2-3*8").getValue(Integer.class

10.5.8 Assignment
Setting of a property is done by using the assignment operator. This would typically be
done within a call to setValue but can also be done inside a call to getValue .
Inventor inventor = new Inventor();
StandardEvaluationContext inventorContext = new StandardEvaluationContext(inventor);
parser.parseExpression("Name").setValue(inventorContext, "Alexander Seovic2"
// alternatively

25/08/2016 12:10

Spring Framework Reference Documentation

297 de 1194

String aleks = parser.parseExpression(

"Name = 'Alexandar Seovic'").getValue(inventorContext, String.class);

10.5.9 Types
The special T operator can be used to specify an instance of java.lang.Class (the type).
Static methods are invoked using this operator as well. The
StandardEvaluationContext uses a TypeLocator to find types and the
StandardTypeLocator (which can be replaced) is built with an understanding of the
java.lang package. This means T() references to types within java.lang do not need to be
fully qualified, but all other type references must be.
Class dateClass = parser.parseExpression("T(java.util.Date)").getValue(Class.
Class stringClass = parser.parseExpression("T(String)").getValue(Class.class
boolean trueValue = parser.parseExpression(
"T(java.math.RoundingMode).CEILING < T(java.math.RoundingMode).FLOOR"
.getValue(Boolean.class);

10.5.10 Constructors
Constructors can be invoked using the new operator. The fully qualified class name
should be used for all but the primitive type and String (where int, float, etc, can be used).
Inventor einstein = p.parseExpression(
"new org.spring.samples.spel.inventor.Inventor('Albert Einstein', 'German')"
.getValue(Inventor.class);
//create new inventor instance within add method of List
p.parseExpression(
"Members.add(new org.spring.samples.spel.inventor.Inventor(
'Albert Einstein', 'German'))").getValue(societyContext);

10.5.11 Variables
Variables can be referenced in the expression using the syntax #variableName .
Variables are set using the method setVariable on the StandardEvaluationContext .
Inventor tesla = new Inventor("Nikola Tesla", "Serbian");
StandardEvaluationContext context = new StandardEvaluationContext(tesla);

25/08/2016 12:10

Spring Framework Reference Documentation

298 de 1194

context.setVariable("newName", "Mike Tesla");

parser.parseExpression("Name = #newName").getValue(context);
System.out.println(tesla.getName()) // "Mike Tesla"

The #this and #root variables

The variable #this is always defined and refers to the current evaluation object (against
which unqualified references are resolved). The variable #root is always defined and
refers to the root context object. Although #this may vary as components of an expression
are evaluated, #root always refers to the root.
// create an array of integers
List<Integer> primes = new ArrayList<Integer>();
primes.addAll(Arrays.asList(2,3,5,7,11,13,17));
// create parser and set variable 'primes' as the array of integers
ExpressionParser parser = new SpelExpressionParser();
StandardEvaluationContext context = new StandardEvaluationContext();
context.setVariable("primes",primes);
// all prime numbers > 10 from the list (using selection ?{...})
// evaluates to [11, 13, 17]
List<Integer> primesGreaterThanTen = (List<Integer>) parser.parseExpression(
"#primes.?[#this>10]").getValue(context);

10.5.12 Functions
You can extend SpEL by registering user defined functions that can be called within the
expression string. The function is registered with the StandardEvaluationContext
using the method.
public void registerFunction(String name, Method m)

A reference to a Java Method provides the implementation of the function. For example, a
utility method to reverse a string is shown below.
public abstract class StringUtils {
public static String reverseString(String input) {
StringBuilder backwards = new StringBuilder();
for (int i = 0; i < input.length(); i++)
backwards.append(input.charAt(input.length() - 1 - i));

25/08/2016 12:10

Spring Framework Reference Documentation

299 de 1194

}
return backwards.toString();
}
}

This method is then registered with the evaluation context and can be used within an
expression string.
ExpressionParser parser = new SpelExpressionParser();
StandardEvaluationContext context = new StandardEvaluationContext();
context.registerFunction("reverseString",
StringUtils.class.getDeclaredMethod("reverseString", new Class[] { String.
String helloWorldReversed = parser.parseExpression(
"#reverseString('hello')").getValue(context, String.class);

10.5.13 Bean references

If the evaluation context has been configured with a bean resolver it is possible to lookup
beans from an expression using the (@) symbol.
ExpressionParser parser = new SpelExpressionParser();
StandardEvaluationContext context = new StandardEvaluationContext();
context.setBeanResolver(new MyBeanResolver());

// This will end up calling resolve(context,"foo") on MyBeanResolver during evaluation

Object bean = parser.parseExpression("@foo").getValue(context);

To access a factory bean itself, the bean name should instead be prefixed with a (&)
symbol.
ExpressionParser parser = new SpelExpressionParser();
StandardEvaluationContext context = new StandardEvaluationContext();
context.setBeanResolver(new MyBeanResolver());

// This will end up calling resolve(context,"&foo") on MyBeanResolver during evaluatio

Object bean = parser.parseExpression("&foo").getValue(context);

10.5.14 Ternary Operator (If-Then-Else)

You can use the ternary operator for performing if-then-else conditional logic inside the
expression. A minimal example is:

25/08/2016 12:10

Spring Framework Reference Documentation

300 de 1194

String falseString = parser.parseExpression(

"false ? 'trueExp' : 'falseExp'").getValue(String.class);

In this case, the boolean false results in returning the string value 'falseExp'. A more
realistic example is shown below.
parser.parseExpression("Name").setValue(societyContext, "IEEE");
societyContext.setVariable("queryName", "Nikola Tesla");

expression = "isMember(#queryName)? #queryName + ' is a member of the ' " +

"+ Name + ' Society' : #queryName + ' is not a member of the ' + Name + ' Soci
String queryResultString = parser.parseExpression(expression)
.getValue(societyContext, String.class);
// queryResultString = "Nikola Tesla is a member of the IEEE Society"

Also see the next section on the Elvis operator for an even shorter syntax for the ternary
operator.

10.5.15 The Elvis Operator

The Elvis operator is a shortening of the ternary operator syntax and is used in the
Groovy language. With the ternary operator syntax you usually have to repeat a variable
twice, for example:
String name = "Elvis Presley";
String displayName = name != null ? name : "Unknown";

Instead you can use the Elvis operator, named for the resemblance to Elvis' hair style.
ExpressionParser parser = new SpelExpressionParser();
String name = parser.parseExpression("name?:'Unknown'").getValue(String.class
System.out.println(name); // 'Unknown'

Here is a more complex example.

ExpressionParser parser = new SpelExpressionParser();
Inventor tesla = new Inventor("Nikola Tesla", "Serbian");
StandardEvaluationContext context = new StandardEvaluationContext(tesla);

String name = parser.parseExpression("Name?:'Elvis Presley'").getValue(context, String

25/08/2016 12:10

Spring Framework Reference Documentation

301 de 1194

System.out.println(name); // Nikola Tesla

tesla.setName(null);
name = parser.parseExpression("Name?:'Elvis Presley'").getValue(context, String.
System.out.println(name); // Elvis Presley

10.5.16 Safe Navigation operator

The Safe Navigation operator is used to avoid a NullPointerException and comes
from the Groovy language. Typically when you have a reference to an object you might
need to verify that it is not null before accessing methods or properties of the object. To
avoid this, the safe navigation operator will simply return null instead of throwing an
exception.
ExpressionParser parser = new SpelExpressionParser();
Inventor tesla = new Inventor("Nikola Tesla", "Serbian");
tesla.setPlaceOfBirth(new PlaceOfBirth("Smiljan"));
StandardEvaluationContext context = new StandardEvaluationContext(tesla);
String city = parser.parseExpression("PlaceOfBirth?.City").getValue(context, String.
System.out.println(city); // Smiljan
tesla.setPlaceOfBirth(null);
city = parser.parseExpression("PlaceOfBirth?.City").getValue(context, String.
System.out.println(city); // null - does not throw NullPointerException!!!

The Elvis operator can be used to apply default values in expressions, e.g.
in an @Value expression:
@Value("#{systemProperties['pop3.port'] ?: 25}")

This will inject a system property pop3.port if it is defined or 25 if not.

10.5.17 Collection Selection

Selection is a powerful expression language feature that allows you to transform some
source collection into another by selecting from its entries.

25/08/2016 12:10

Spring Framework Reference Documentation

302 de 1194

Selection uses the syntax ?[selectionExpression] . This will filter the collection and
return a new collection containing a subset of the original elements. For example,
selection would allow us to easily get a list of Serbian inventors:
List<Inventor> list = (List<Inventor>) parser.parseExpression(
"Members.?[Nationality == 'Serbian']").getValue(societyContext);

Selection is possible upon both lists and maps. In the former case the selection criteria is
evaluated against each individual list element whilst against a map the selection criteria is
evaluated against each map entry (objects of the Java type Map.Entry ). Map entries
have their key and value accessible as properties for use in the selection.
This expression will return a new map consisting of those elements of the original map
where the entry value is less than 27.
Map newMap = parser.parseExpression("map.?[value<27]").getValue();

In addition to returning all the selected elements, it is possible to retrieve just the first or
the last value. To obtain the first entry matching the selection the syntax is ^[] whilst to
obtain the last matching selection the syntax is $[] .

10.5.18 Collection Projection

Projection allows a collection to drive the evaluation of a sub-expression and the result is
a new collection. The syntax for projection is ![projectionExpression] . Most easily
understood by example, suppose we have a list of inventors but want the list of cities
where they were born. Effectively we want to evaluate 'placeOfBirth.city' for every entry in
the inventor list. Using projection:
// returns ['Smiljan', 'Idvor' ]
List placesOfBirth = (List)parser.parseExpression("Members.![placeOfBirth.city]"

A map can also be used to drive projection and in this case the projection expression is
evaluated against each entry in the map (represented as a Java Map.Entry ). The result
of a projection across a map is a list consisting of the evaluation of the projection
expression against each map entry.

10.5.19 Expression templating

Expression templates allow a mixing of literal text with one or more evaluation blocks.
Each evaluation block is delimited with prefix and suffix characters that you can define, a

25/08/2016 12:10

Spring Framework Reference Documentation

303 de 1194

common choice is to use #{ } as the delimiters. For example,

String randomPhrase = parser.parseExpression(
"random number is #{T(java.lang.Math).random()}",
new TemplateParserContext()).getValue(String.class);
// evaluates to "random number is 0.7038186818312008"

The string is evaluated by concatenating the literal text 'random number is ' with the result
of evaluating the expression inside the #{ } delimiter, in this case the result of calling that
random() method. The second argument to the method parseExpression() is of the
type ParserContext . The ParserContext interface is used to influence how the
expression is parsed in order to support the expression templating functionality. The
definition of TemplateParserContext is shown below.
public class TemplateParserContext implements ParserContext {
public String getExpressionPrefix() {
return "#{";
}
public String getExpressionSuffix() {
return "}";
}
public boolean isTemplate() {
return true;
}
}

10.6 Classes used in the examples

Inventor.java
package org.spring.samples.spel.inventor;
import java.util.Date;
import java.util.GregorianCalendar;
public class Inventor {
private String name;
private String nationality;
private String[] inventions;

25/08/2016 12:10

Spring Framework Reference Documentation

304 de 1194

private PlaceOfBirth placeOfBirth;

public Inventor(String name, String nationality) {
GregorianCalendar c= new GregorianCalendar();
this.name = name;
this.nationality = nationality;
this.birthdate = c.getTime();
}
public Inventor(String name, Date birthdate, String nationality) {
this.name = name;
this.nationality = nationality;
this.birthdate = birthdate;
}
public Inventor() {
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getNationality() {
return nationality;
}
public void setNationality(String nationality) {
this.nationality = nationality;
}
public Date getBirthdate() {
return birthdate;
}
public void setBirthdate(Date birthdate) {
this.birthdate = birthdate;
}
public PlaceOfBirth getPlaceOfBirth() {
return placeOfBirth;
}
public void setPlaceOfBirth(PlaceOfBirth placeOfBirth) {
this.placeOfBirth = placeOfBirth;

25/08/2016 12:10

Spring Framework Reference Documentation

305 de 1194

}
public void setInventions(String[] inventions) {
this.inventions = inventions;
}
public String[] getInventions() {
return inventions;
}
}

PlaceOfBirth.java
package org.spring.samples.spel.inventor;
public class PlaceOfBirth {
private String city;
private String country;
public PlaceOfBirth(String city) {
this.city=city;
}
public PlaceOfBirth(String city, String country) {
this(city);
this.country = country;
}
public String getCity() {
return city;
}
public void setCity(String s) {
this.city = s;
}
public String getCountry() {
return country;
}
public void setCountry(String country) {
this.country = country;
}
}

25/08/2016 12:10

Spring Framework Reference Documentation

306 de 1194

package org.spring.samples.spel.inventor;
import java.util.*;
public class Society {
private String name;
public static String Advisors = "advisors";
public static String President = "president";
private List<Inventor> members = new ArrayList<Inventor>();
private Map officers = new HashMap();
public List getMembers() {
return members;
}
public Map getOfficers() {
return officers;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public boolean isMember(String name) {
for (Inventor inventor : members) {
if (inventor.getName().equals(name)) {
return true;
}
}
return false;
}
}

11. Aspect Oriented Programming with Spring

11.1 Introduction
25/08/2016 12:10

Spring Framework Reference Documentation

307 de 1194

Aspect-Oriented Programming (AOP) complements Object-Oriented Programming (OOP)

by providing another way of thinking about program structure. The key unit of modularity
in OOP is the class, whereas in AOP the unit of modularity is the aspect. Aspects enable
the modularization of concerns such as transaction management that cut across multiple
types and objects. (Such concerns are often termed crosscutting concerns in AOP
literature.)
One of the key components of Spring is the AOP framework. While the Spring IoC
container does not depend on AOP, meaning you do not need to use AOP if you dont
want to, AOP complements Spring IoC to provide a very capable middleware solution.
Spring 2.0 AOP
Spring 2.0 introduces a simpler and more powerful way of writing custom aspects
using either a schema-based approach or the @AspectJ annotation style. Both of
these styles offer fully typed advice and use of the AspectJ pointcut language, while
still using Spring AOP for weaving.
The Spring 2.0 schema- and @AspectJ-based AOP support is discussed in this
chapter. Spring 2.0 AOP remains fully backwards compatible with Spring 1.2 AOP,
and the lower-level AOP support offered by the Spring 1.2 APIs is discussed in the
following chapter.
AOP is used in the Spring Framework to
provide declarative enterprise services, especially as a replacement for EJB
declarative services. The most important such service is declarative transaction
management.
allow users to implement custom aspects, complementing their use of OOP with
AOP.

If you are interested only in generic declarative services or other

pre-packaged declarative middleware services such as pooling, you do not
need to work directly with Spring AOP, and can skip most of this chapter.

11.1.1 AOP concepts

Let us begin by defining some central AOP concepts and terminology. These terms are
not Spring-specific unfortunately, AOP terminology is not particularly intuitive; however,
it would be even more confusing if Spring used its own terminology.

25/08/2016 12:10

Spring Framework Reference Documentation

308 de 1194

Aspect: a modularization of a concern that cuts across multiple classes. Transaction

management is a good example of a crosscutting concern in enterprise Java
applications. In Spring AOP, aspects are implemented using regular classes (the
schema-based approach) or regular classes annotated with the @Aspect annotation
(the @AspectJ style).
Join point: a point during the execution of a program, such as the execution of a
method or the handling of an exception. In Spring AOP, a join point always represents
a method execution.
Advice: action taken by an aspect at a particular join point. Different types of advice
include "around," "before" and "after" advice. (Advice types are discussed below.)
Many AOP frameworks, including Spring, model an advice as an interceptor,
maintaining a chain of interceptors around the join point.
Pointcut: a predicate that matches join points. Advice is associated with a pointcut
expression and runs at any join point matched by the pointcut (for example, the
execution of a method with a certain name). The concept of join points as matched by
pointcut expressions is central to AOP, and Spring uses the AspectJ pointcut
expression language by default.
Introduction: declaring additional methods or fields on behalf of a type. Spring AOP
allows you to introduce new interfaces (and a corresponding implementation) to any
advised object. For example, you could use an introduction to make a bean
implement an IsModified interface, to simplify caching. (An introduction is known
as an inter-type declaration in the AspectJ community.)
Target object: object being advised by one or more aspects. Also referred to as the
advised object. Since Spring AOP is implemented using runtime proxies, this object
will always be a proxied object.
AOP proxy: an object created by the AOP framework in order to implement the
aspect contracts (advise method executions and so on). In the Spring Framework, an
AOP proxy will be a JDK dynamic proxy or a CGLIB proxy.
Weaving: linking aspects with other application types or objects to create an advised
object. This can be done at compile time (using the AspectJ compiler, for example),
load time, or at runtime. Spring AOP, like other pure Java AOP frameworks, performs
weaving at runtime.
Types of advice:
Before advice: Advice that executes before a join point, but which does not have the
ability to prevent execution flow proceeding to the join point (unless it throws an
exception).
After returning advice: Advice to be executed after a join point completes normally:
for example, if a method returns without throwing an exception.

25/08/2016 12:10

Spring Framework Reference Documentation

309 de 1194

After throwing advice: Advice to be executed if a method exits by throwing an

exception.
After (finally) advice: Advice to be executed regardless of the means by which a join
point exits (normal or exceptional return).
Around advice: Advice that surrounds a join point such as a method invocation. This
is the most powerful kind of advice. Around advice can perform custom behavior
before and after the method invocation. It is also responsible for choosing whether to
proceed to the join point or to shortcut the advised method execution by returning its
own return value or throwing an exception.
Around advice is the most general kind of advice. Since Spring AOP, like AspectJ,
provides a full range of advice types, we recommend that you use the least powerful
advice type that can implement the required behavior. For example, if you need only to
update a cache with the return value of a method, you are better off implementing an after
returning advice than an around advice, although an around advice can accomplish the
same thing. Using the most specific advice type provides a simpler programming model
with less potential for errors. For example, you do not need to invoke the proceed()
method on the JoinPoint used for around advice, and hence cannot fail to invoke it.
In Spring 2.0, all advice parameters are statically typed, so that you work with advice
parameters of the appropriate type (the type of the return value from a method execution
for example) rather than Object arrays.
The concept of join points, matched by pointcuts, is the key to AOP which distinguishes it
from older technologies offering only interception. Pointcuts enable advice to be targeted
independently of the Object-Oriented hierarchy. For example, an around advice providing
declarative transaction management can be applied to a set of methods spanning
multiple objects (such as all business operations in the service layer).

11.1.2 Spring AOP capabilities and goals

Spring AOP is implemented in pure Java. There is no need for a special compilation
process. Spring AOP does not need to control the class loader hierarchy, and is thus
suitable for use in a Servlet container or application server.
Spring AOP currently supports only method execution join points (advising the execution
of methods on Spring beans). Field interception is not implemented, although support for
field interception could be added without breaking the core Spring AOP APIs. If you need
to advise field access and update join points, consider a language such as AspectJ.
Spring AOPs approach to AOP differs from that of most other AOP frameworks. The aim

25/08/2016 12:10

Spring Framework Reference Documentation

310 de 1194

is not to provide the most complete AOP implementation (although Spring AOP is quite
capable); it is rather to provide a close integration between AOP implementation and
Spring IoC to help solve common problems in enterprise applications.
Thus, for example, the Spring Frameworks AOP functionality is normally used in
conjunction with the Spring IoC container. Aspects are configured using normal bean
definition syntax (although this allows powerful "autoproxying" capabilities): this is a
crucial difference from other AOP implementations. There are some things you cannot do
easily or efficiently with Spring AOP, such as advise very fine-grained objects (such as
domain objects typically): AspectJ is the best choice in such cases. However, our
experience is that Spring AOP provides an excellent solution to most problems in
enterprise Java applications that are amenable to AOP.
Spring AOP will never strive to compete with AspectJ to provide a comprehensive AOP
solution. We believe that both proxy-based frameworks like Spring AOP and full-blown
frameworks such as AspectJ are valuable, and that they are complementary, rather than
in competition. Spring seamlessly integrates Spring AOP and IoC with AspectJ, to enable
all uses of AOP to be catered for within a consistent Spring-based application
architecture. This integration does not affect the Spring AOP API or the AOP Alliance API:
Spring AOP remains backward-compatible. See the following chapter for a discussion of
the Spring AOP APIs.

One of the central tenets of the Spring Framework is that of

non-invasiveness; this is the idea that you should not be forced to introduce
framework-specific classes and interfaces into your business/domain
model. However, in some places the Spring Framework does give you the
option to introduce Spring Framework-specific dependencies into your
codebase: the rationale in giving you such options is because in certain
scenarios it might be just plain easier to read or code some specific piece of
functionality in such a way. The Spring Framework (almost) always offers
you the choice though: you have the freedom to make an informed decision
as to which option best suits your particular use case or scenario.
One such choice that is relevant to this chapter is that of which AOP
framework (and which AOP style) to choose. You have the choice of
AspectJ and/or Spring AOP, and you also have the choice of either the
@AspectJ annotation-style approach or the Spring XML configuration-style
approach. The fact that this chapter chooses to introduce the
@AspectJ-style approach first should not be taken as an indication that the
Spring team favors the @AspectJ annotation-style approach over the
Spring XML configuration-style.

25/08/2016 12:10

Spring Framework Reference Documentation

311 de 1194

See Section 11.4, Choosing which AOP declaration style to use for a more
complete discussion of the whys and wherefores of each style.

11.1.3 AOP Proxies

Spring AOP defaults to using standard JDK dynamic proxies for AOP proxies. This
enables any interface (or set of interfaces) to be proxied.
Spring AOP can also use CGLIB proxies. This is necessary to proxy classes rather than
interfaces. CGLIB is used by default if a business object does not implement an interface.
As it is good practice to program to interfaces rather than classes; business classes
normally will implement one or more business interfaces. It is possible to force the use of
CGLIB, in those (hopefully rare) cases where you need to advise a method that is not
declared on an interface, or where you need to pass a proxied object to a method as a
concrete type.
It is important to grasp the fact that Spring AOP is proxy-based. See Section 11.6.1,
Understanding AOP proxies for a thorough examination of exactly what this
implementation detail actually means.

11.2 @AspectJ support

@AspectJ refers to a style of declaring aspects as regular Java classes annotated with
annotations. The @AspectJ style was introduced by the AspectJ project as part of the
AspectJ 5 release. Spring interprets the same annotations as AspectJ 5, using a library
supplied by AspectJ for pointcut parsing and matching. The AOP runtime is still pure
Spring AOP though, and there is no dependency on the AspectJ compiler or weaver.

Using the AspectJ compiler and weaver enables use of the full AspectJ
language, and is discussed in Section 11.8, Using AspectJ with Spring
applications.

11.2.1 Enabling @AspectJ Support

To use @AspectJ aspects in a Spring configuration you need to enable Spring support for
configuring Spring AOP based on @AspectJ aspects, and autoproxying beans based on
whether or not they are advised by those aspects. By autoproxying we mean that if

25/08/2016 12:10

Spring Framework Reference Documentation

312 de 1194

generate a proxy for that bean to intercept method invocations and ensure that advice is
executed as needed.
The @AspectJ support can be enabled with XML or Java style configuration. In either
case you will also need to ensure that AspectJs aspectjweaver.jar library is on the
classpath of your application (version 1.6.8 or later). This library is available in the 'lib'
directory of an AspectJ distribution or via the Maven Central repository.

Enabling @AspectJ Support with Java configuration

To enable @AspectJ support with Java @Configuration add the
@EnableAspectJAutoProxy annotation:
@Configuration
@EnableAspectJAutoProxy
public class AppConfig {
}

Enabling @AspectJ Support with XML configuration

To enable @AspectJ support with XML based configuration use the
aop:aspectj-autoproxy element:
<aop:aspectj-autoproxy/>

This assumes that you are using schema support as described in Chapter 41, XML
Schema-based configuration. See Section 41.2.7, the aop schema for how to import the
tags in the aop namespace.

11.2.2 Declaring an aspect

With the @AspectJ support enabled, any bean defined in your application context with a
class that is an @AspectJ aspect (has the @Aspect annotation) will be automatically
detected by Spring and used to configure Spring AOP. The following example shows the
minimal definition required for a not-very-useful aspect:
A regular bean definition in the application context, pointing to a bean class that has the
@Aspect annotation:
<bean id="myAspect" class="org.xyz.NotVeryUsefulAspect">

25/08/2016 12:10

Spring Framework Reference Documentation

313 de 1194

And the NotVeryUsefulAspect class definition, annotated with

org.aspectj.lang.annotation.Aspect annotation;
package org.xyz;
import org.aspectj.lang.annotation.Aspect;
@Aspect
public class NotVeryUsefulAspect {
}

Aspects (classes annotated with @Aspect ) may have methods and fields just like any
other class. They may also contain pointcut, advice, and introduction (inter-type)
declarations.

You may register aspect classes as regular beans in your Spring XML
configuration, or autodetect them through classpath scanning - just like any
other Spring-managed bean. However, note that the @Aspect annotation is
not sufficient for autodetection in the classpath: For that purpose, you need
to add a separate @Component annotation (or alternatively a custom
stereotype annotation that qualifies, as per the rules of Springs component
scanner).

In Spring AOP, it is not possible to have aspects themselves be the target of

advice from other aspects. The @Aspect annotation on a class marks it as
an aspect, and hence excludes it from auto-proxying.

11.2.3 Declaring a pointcut

Recall that pointcuts determine join points of interest, and thus enable us to control when
advice executes. Spring AOP only supports method execution join points for Spring
beans, so you can think of a pointcut as matching the execution of methods on Spring
beans. A pointcut declaration has two parts: a signature comprising a name and any
parameters, and a pointcut expression that determines exactly which method executions
we are interested in. In the @AspectJ annotation-style of AOP, a pointcut signature is
provided by a regular method definition, and the pointcut expression is indicated using the
@Pointcut annotation (the method serving as the pointcut signature must have a void
return type).

25/08/2016 12:10

Spring Framework Reference Documentation

314 de 1194

An example will help make this distinction between a pointcut signature and a pointcut
expression clear. The following example defines a pointcut named 'anyOldTransfer'
that will match the execution of any method named 'transfer' :
@Pointcut("execution(* transfer(..))")// the pointcut expression
private void anyOldTransfer() {}// the pointcut signature

The pointcut expression that forms the value of the @Pointcut annotation is a regular
AspectJ 5 pointcut expression. For a full discussion of AspectJs pointcut language, see
the AspectJ Programming Guide (and for extensions, the AspectJ 5 Developers
Notebook) or one of the books on AspectJ such as "Eclipse AspectJ" by Colyer et. al. or
"AspectJ in Action" by Ramnivas Laddad.

Supported Pointcut Designators

Spring AOP supports the following AspectJ pointcut designators (PCD) for use in pointcut
expressions:
Other pointcut types

The full AspectJ pointcut language supports additional pointcut designators that are
not supported in Spring. These are:
call, get, set, preinitialization, staticinitialization, initialization, handle
and @withincode . Use of these pointcut designators in pointcut expressions
interpreted by Spring AOP will result in an IllegalArgumentException being
thrown.
The set of pointcut designators supported by Spring AOP may be extended in future
releases to support more of the AspectJ pointcut designators.

execution - for matching method execution join points, this is the primary pointcut
designator you will use when working with Spring AOP
within - limits matching to join points within certain types (simply the execution of a
method declared within a matching type when using Spring AOP)
this - limits matching to join points (the execution of methods when using Spring
AOP) where the bean reference (Spring AOP proxy) is an instance of the given type
target - limits matching to join points (the execution of methods when using Spring
AOP) where the target object (application object being proxied) is an instance of the
given type
args - limits matching to join points (the execution of methods when using Spring
AOP) where the arguments are instances of the given types
@target - limits matching to join points (the execution of methods when using Spring

25/08/2016 12:10

Spring Framework Reference Documentation

315 de 1194

AOP) where the class of the executing object has an annotation of the given type
@args - limits matching to join points (the execution of methods when using Spring
AOP) where the runtime type of the actual arguments passed have annotations of the
given type(s)
@within - limits matching to join points within types that have the given annotation
(the execution of methods declared in types with the given annotation when using
Spring AOP)
@annotation - limits matching to join points where the subject of the join point
(method being executed in Spring AOP) has the given annotation
Because Spring AOP limits matching to only method execution join points, the discussion
of the pointcut designators above gives a narrower definition than you will find in the
AspectJ programming guide. In addition, AspectJ itself has type-based semantics and at
an execution join point both this and target refer to the same object - the object
executing the method. Spring AOP is a proxy-based system and differentiates between
the proxy object itself (bound to this ) and the target object behind the proxy (bound to
target ).

Due to the proxy-based nature of Springs AOP framework, protected

methods are by definition not intercepted, neither for JDK proxies (where
this isnt applicable) nor for CGLIB proxies (where this is technically
possible but not recommendable for AOP purposes). As a consequence,
any given pointcut will be matched against public methods only!
If your interception needs include protected/private methods or even
constructors, consider the use of Spring-driven native AspectJ weaving
instead of Springs proxy-based AOP framework. This constitutes a different
mode of AOP usage with different characteristics, so be sure to make
yourself familiar with weaving first before making a decision.

Spring AOP also supports an additional PCD named bean . This PCD allows you to limit
the matching of join points to a particular named Spring bean, or to a set of named Spring
beans (when using wildcards). The bean PCD has the following form:
bean(idOrNameOfBean)

The idOrNameOfBean token can be the name of any Spring bean: limited wildcard
support using the * character is provided, so if you establish some naming conventions
for your Spring beans you can quite easily write a bean PCD expression to pick them
out. As is the case with other pointcut designators, the bean PCD can be &&'ed, ||'ed,

25/08/2016 12:10

Spring Framework Reference Documentation

316 de 1194

Please note that the bean PCD is only supported in Spring AOP - and not
in native AspectJ weaving. It is a Spring-specific extension to the standard
PCDs that AspectJ defines and therefore not available for aspects declared
in the @Aspect model.
The bean PCD operates at the instance level (building on the Spring bean
name concept) rather than at the type level only (which is what
weaving-based AOP is limited to). Instance-based pointcut designators are
a special capability of Springs proxy-based AOP framework and its close
integration with the Spring bean factory, where it is natural and
straightforward to identify specific beans by name.

Combining pointcut expressions

Pointcut expressions can be combined using '&&', '||' and '!'. It is also possible to refer to
pointcut expressions by name. The following example shows three pointcut expressions:
anyPublicOperation (which matches if a method execution join point represents the
execution of any public method); inTrading (which matches if a method execution is in
the trading module), and tradingOperation (which matches if a method execution
represents any public method in the trading module).
@Pointcut("execution(public * *(..))")
private void anyPublicOperation() {}
@Pointcut("within(com.xyz.someapp.trading..*)")
private void inTrading() {}
@Pointcut("anyPublicOperation() && inTrading()")
private void tradingOperation() {}

It is a best practice to build more complex pointcut expressions out of smaller named
components as shown above. When referring to pointcuts by name, normal Java visibility
rules apply (you can see private pointcuts in the same type, protected pointcuts in the
hierarchy, public pointcuts anywhere and so on). Visibility does not affect pointcut
matching.

Sharing common pointcut definitions

When working with enterprise applications, you often want to refer to modules of the
application and particular sets of operations from within several aspects. We recommend
defining a "SystemArchitecture" aspect that captures common pointcut expressions for

25/08/2016 12:10

Spring Framework Reference Documentation

317 de 1194

package com.xyz.someapp;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
@Aspect
public class SystemArchitecture {
/**
* A join point is in the web layer if the method is defined
* in a type in the com.xyz.someapp.web package or any sub-package
* under that.
*/
@Pointcut("within(com.xyz.someapp.web..*)")
public void inWebLayer() {}
/**
* A join point is in the service layer if the method is defined
* in a type in the com.xyz.someapp.service package or any sub-package
* under that.
*/
@Pointcut("within(com.xyz.someapp.service..*)")
public void inServiceLayer() {}
/**
* A join point is in the data access layer if the method is defined
* in a type in the com.xyz.someapp.dao package or any sub-package
* under that.
*/
@Pointcut("within(com.xyz.someapp.dao..*)")
public void inDataAccessLayer() {}
/**
* A business service is the execution of any method defined on a service
* interface. This definition assumes that interfaces are placed in the
* "service" package, and that implementation types are in sub-packages.
*
* If you group service interfaces by functional area (for example,
* in packages com.xyz.someapp.abc.service and com.xyz.someapp.def.service) then
* the pointcut expression "execution(* com.xyz.someapp..service.*.*(..))"
* could be used instead.
*
* Alternatively, you can write the expression using the 'bean'
* PCD, like so "bean(*Service)". (This assumes that you have
* named your Spring service beans in a consistent fashion.)
*/
@Pointcut("execution(* com.xyz.someapp..service.*.*(..))")

25/08/2016 12:10

Spring Framework Reference Documentation

318 de 1194

/**
* A data access operation is the execution of any method defined on a
* dao interface. This definition assumes that interfaces are placed in the
* "dao" package, and that implementation types are in sub-packages.
*/
@Pointcut("execution(* com.xyz.someapp.dao.*.*(..))")
public void dataAccessOperation() {}
}

The pointcuts defined in such an aspect can be referred to anywhere that you need a
pointcut expression. For example, to make the service layer transactional, you could
write:
<aop:config>
<aop:advisor
pointcut="com.xyz.someapp.SystemArchitecture.businessService()"
advice-ref="tx-advice"/>
</aop:config>
<tx:advice id="tx-advice">
<tx:attributes>
<tx:method name="*" propagation="REQUIRED"/>
</tx:attributes>
</tx:advice>

The <aop:config> and <aop:advisor> elements are discussed in Section 11.3,

Schema-based AOP support. The transaction elements are discussed in Chapter 17,
Transaction Management.

Examples
Spring AOP users are likely to use the execution pointcut designator the most often.
The format of an execution expression is:

execution(modifiers-pattern? ret-type-pattern declaring-type-pattern?name-pattern(para

throws-pattern?)

All parts except the returning type pattern (ret-type-pattern in the snippet above), name
pattern, and parameters pattern are optional. The returning type pattern determines what
the return type of the method must be in order for a join point to be matched. Most
frequently you will use * as the returning type pattern, which matches any return type. A
fully-qualified type name will match only when the method returns the given type. The

25/08/2016 12:10

Spring Framework Reference Documentation

319 de 1194

name pattern. If specifying a declaring type pattern then include a trailing . to join it to
the name pattern component. The parameters pattern is slightly more complex: ()
matches a method that takes no parameters, whereas (..) matches any number of
parameters (zero or more). The pattern (*) matches a method taking one parameter of
any type, (*,String) matches a method taking two parameters, the first can be of any
type, the second must be a String. Consult the Language Semantics section of the
AspectJ Programming Guide for more information.
Some examples of common pointcut expressions are given below.
the execution of any public method:
execution(public * *(..))

the execution of any method with a name beginning with "set":

execution(* set*(..))

the execution of any method defined by the AccountService interface:

execution(* com.xyz.service.AccountService.*(..))

the execution of any method defined in the service package:

execution(* com.xyz.service.*.*(..))

the execution of any method defined in the service package or a sub-package:

execution(* com.xyz.service..*.*(..))

any join point (method execution only in Spring AOP) within the service package:
within(com.xyz.service.*)

any join point (method execution only in Spring AOP) within the service package or a
sub-package:
within(com.xyz.service..*)

any join point (method execution only in Spring AOP) where the proxy implements
the AccountService interface:
this(com.xyz.service.AccountService)

25/08/2016 12:10

Spring Framework Reference Documentation

320 de 1194

'this' is more commonly used in a binding form :- see the following section
on advice for how to make the proxy object available in the advice body.

any join point (method execution only in Spring AOP) where the target object
implements the AccountService interface:
target(com.xyz.service.AccountService)

'target' is more commonly used in a binding form :- see the following section
on advice for how to make the target object available in the advice body.

any join point (method execution only in Spring AOP) which takes a single parameter,
and where the argument passed at runtime is Serializable :
args(java.io.Serializable)

'args' is more commonly used in a binding form :- see the following section
on advice for how to make the method arguments available in the advice
body.

Note that the pointcut given in this example is different to

execution(* *(java.io.Serializable)) : the args version matches if the argument
passed at runtime is Serializable, the execution version matches if the method signature
declares a single parameter of type Serializable .
any join point (method execution only in Spring AOP) where the target object has an
@Transactional annotation:
@target(org.springframework.transaction.annotation.Transactional)

'@target' can also be used in a binding form :- see the following section on
advice for how to make the annotation object available in the advice body.

any join point (method execution only in Spring AOP) where the declared type of the
target object has an @Transactional annotation:

25/08/2016 12:10

Spring Framework Reference Documentation

321 de 1194

'@within' can also be used in a binding form :- see the following section on
advice for how to make the annotation object available in the advice body.

any join point (method execution only in Spring AOP) where the executing method
has an @Transactional annotation:
@annotation(org.springframework.transaction.annotation.Transactional)

'@annotation' can also be used in a binding form :- see the following

section on advice for how to make the annotation object available in the
advice body.

any join point (method execution only in Spring AOP) which takes a single parameter,
and where the runtime type of the argument passed has the @Classified
annotation:
@args(com.xyz.security.Classified)

'@args' can also be used in a binding form :- see the following section on
advice for how to make the annotation object(s) available in the advice
body.

any join point (method execution only in Spring AOP) on a Spring bean named
tradeService :
bean(tradeService)

any join point (method execution only in Spring AOP) on Spring beans having names
that match the wildcard expression *Service :
bean(*Service)

Writing good pointcuts

During compilation, AspectJ processes pointcuts in order to try and optimize matching
performance. Examining code and determining if each join point matches (statically or
dynamically) a given pointcut is a costly process. (A dynamic match means the match

25/08/2016 12:10

Spring Framework Reference Documentation

322 de 1194

determine if there is an actual match when the code is running). On first encountering a
pointcut declaration, AspectJ will rewrite it into an optimal form for the matching process.
What does this mean? Basically pointcuts are rewritten in DNF (Disjunctive Normal Form)
and the components of the pointcut are sorted such that those components that are
cheaper to evaluate are checked first. This means you do not have to worry about
understanding the performance of various pointcut designators and may supply them in
any order in a pointcut declaration.
However, AspectJ can only work with what it is told, and for optimal performance of
matching you should think about what they are trying to achieve and narrow the search
space for matches as much as possible in the definition. The existing designators
naturally fall into one of three groups: kinded, scoping and context:
Kinded designators are those which select a particular kind of join point. For example:
execution, get, set, call, handler
Scoping designators are those which select a group of join points of interest (of
probably many kinds). For example: within, withincode
Contextual designators are those that match (and optionally bind) based on context.
For example: this, target, @annotation
A well written pointcut should try and include at least the first two types (kinded and
scoping), whilst the contextual designators may be included if wishing to match based on
join point context, or bind that context for use in the advice. Supplying either just a kinded
designator or just a contextual designator will work but could affect weaving performance
(time and memory used) due to all the extra processing and analysis. Scoping
designators are very fast to match and their usage means AspectJ can very quickly
dismiss groups of join points that should not be further processed - that is why a good
pointcut should always include one if possible.

11.2.4 Declaring advice

Advice is associated with a pointcut expression, and runs before, after, or around method
executions matched by the pointcut. The pointcut expression may be either a simple
reference to a named pointcut, or a pointcut expression declared in place.

Before advice
Before advice is declared in an aspect using the @Before annotation:
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;

25/08/2016 12:10

Spring Framework Reference Documentation

323 de 1194

@Aspect
public class BeforeExample {
@Before("com.xyz.myapp.SystemArchitecture.dataAccessOperation()")
public void doAccessCheck() {
// ...
}
}

If using an in-place pointcut expression we could rewrite the above example as:
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
@Aspect
public class BeforeExample {
@Before("execution(* com.xyz.myapp.dao.*.*(..))")
public void doAccessCheck() {
// ...
}
}

After returning advice

After returning advice runs when a matched method execution returns normally. It is
declared using the @AfterReturning annotation:
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.AfterReturning;
@Aspect
public class AfterReturningExample {
@AfterReturning("com.xyz.myapp.SystemArchitecture.dataAccessOperation()")
public void doAccessCheck() {
// ...
}
}

Note: it is of course possible to have multiple advice declarations, and other

25/08/2016 12:10

Spring Framework Reference Documentation

324 de 1194

members as well, all inside the same aspect. Were just showing a single
advice declaration in these examples to focus on the issue under discussion
at the time.

Sometimes you need access in the advice body to the actual value that was returned.
You can use the form of @AfterReturning that binds the return value for this:
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.AfterReturning;
@Aspect
public class AfterReturningExample {
@AfterReturning(
pointcut="com.xyz.myapp.SystemArchitecture.dataAccessOperation()",
returning="retVal")
public void doAccessCheck(Object retVal) {
// ...
}
}

The name used in the returning attribute must correspond to the name of a parameter
in the advice method. When a method execution returns, the return value will be passed
to the advice method as the corresponding argument value. A returning clause also
restricts matching to only those method executions that return a value of the specified
type ( Object in this case, which will match any return value).
Please note that it is not possible to return a totally different reference when using afterreturning advice.

After throwing advice

After throwing advice runs when a matched method execution exits by throwing an
exception. It is declared using the @AfterThrowing annotation:
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.AfterThrowing;
@Aspect
public class AfterThrowingExample {
@AfterThrowing("com.xyz.myapp.SystemArchitecture.dataAccessOperation()")
public void doRecoveryActions() {

25/08/2016 12:10

Spring Framework Reference Documentation

325 de 1194

// ...
}
}

Often you want the advice to run only when exceptions of a given type are thrown, and
you also often need access to the thrown exception in the advice body. Use the
throwing attribute to both restrict matching (if desired, use Throwable as the
exception type otherwise) and bind the thrown exception to an advice parameter.
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.AfterThrowing;
@Aspect
public class AfterThrowingExample {
@AfterThrowing(
pointcut="com.xyz.myapp.SystemArchitecture.dataAccessOperation()",
throwing="ex")
public void doRecoveryActions(DataAccessException ex) {
// ...
}
}

The name used in the throwing attribute must correspond to the name of a parameter
in the advice method. When a method execution exits by throwing an exception, the
exception will be passed to the advice method as the corresponding argument value. A
throwing clause also restricts matching to only those method executions that throw an
exception of the specified type ( DataAccessException in this case).

After (finally) advice

After (finally) advice runs however a matched method execution exits. It is declared using
the @After annotation. After advice must be prepared to handle both normal and
exception return conditions. It is typically used for releasing resources, etc.
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.After;
@Aspect
public class AfterFinallyExample {
@After("com.xyz.myapp.SystemArchitecture.dataAccessOperation()")
public void doReleaseLock() {

25/08/2016 12:10

Spring Framework Reference Documentation

326 de 1194

// ...
}
}

Around advice
The final kind of advice is around advice. Around advice runs "around" a matched method
execution. It has the opportunity to do work both before and after the method executes,
and to determine when, how, and even if, the method actually gets to execute at all.
Around advice is often used if you need to share state before and after a method
execution in a thread-safe manner (starting and stopping a timer for example). Always
use the least powerful form of advice that meets your requirements (i.e. dont use around
advice if simple before advice would do).
Around advice is declared using the @Around annotation. The first parameter of the
advice method must be of type ProceedingJoinPoint . Within the body of the advice,
calling proceed() on the ProceedingJoinPoint causes the underlying method to
execute. The proceed method may also be called passing in an Object[] - the values
in the array will be used as the arguments to the method execution when it proceeds.

The behavior of proceed when called with an Object[] is a little different than
the behavior of proceed for around advice compiled by the AspectJ
compiler. For around advice written using the traditional AspectJ language,
the number of arguments passed to proceed must match the number of
arguments passed to the around advice (not the number of arguments
taken by the underlying join point), and the value passed to proceed in a
given argument position supplants the original value at the join point for the
entity the value was bound to (Dont worry if this doesnt make sense right
now!). The approach taken by Spring is simpler and a better match to its
proxy-based, execution only semantics. You only need to be aware of this
difference if you are compiling @AspectJ aspects written for Spring and
using proceed with arguments with the AspectJ compiler and weaver. There
is a way to write such aspects that is 100% compatible across both Spring
AOP and AspectJ, and this is discussed in the following section on advice
parameters.

import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.ProceedingJoinPoint;

25/08/2016 12:10

Spring Framework Reference Documentation

327 de 1194

@Aspect
public class AroundExample {
@Around("com.xyz.myapp.SystemArchitecture.businessService()")
public Object doBasicProfiling(ProceedingJoinPoint pjp) throws Throwable {
// start stopwatch
Object retVal = pjp.proceed();
// stop stopwatch
return retVal;
}
}

The value returned by the around advice will be the return value seen by the caller of the
method. A simple caching aspect for example could return a value from a cache if it has
one, and invoke proceed() if it does not. Note that proceed may be invoked once, many
times, or not at all within the body of the around advice, all of these are quite legal.

Advice parameters
Spring offers fully typed advice - meaning that you declare the parameters you need in
the advice signature (as we saw for the returning and throwing examples above) rather
than work with Object[] arrays all the time. Well see how to make argument and other
contextual values available to the advice body in a moment. First lets take a look at how
to write generic advice that can find out about the method the advice is currently advising.

Access to the current JoinPoint

Any advice method may declare as its first parameter, a parameter of type
org.aspectj.lang.JoinPoint (please note that around advice is required to declare a
first parameter of type ProceedingJoinPoint , which is a subclass of JoinPoint . The
JoinPoint interface provides a number of useful methods such as getArgs() (returns
the method arguments), getThis() (returns the proxy object), getTarget() (returns
the target object), getSignature() (returns a description of the method that is being
advised) and toString() (prints a useful description of the method being advised).
Please do consult the javadocs for full details.

Passing parameters to advice

Weve already seen how to bind the returned value or exception value (using after
returning and after throwing advice). To make argument values available to the advice
body, you can use the binding form of args . If a parameter name is used in place of a

25/08/2016 12:10

Spring Framework Reference Documentation

328 de 1194

type name in an args expression, then the value of the corresponding argument will be
passed as the parameter value when the advice is invoked. An example should make this
clearer. Suppose you want to advise the execution of dao operations that take an Account
object as the first parameter, and you need access to the account in the advice body. You
could write the following:
@Before("com.xyz.myapp.SystemArchitecture.dataAccessOperation() && args(account,..)")
public void validateAccount(Account account) {
// ...
}

The args(account,..) part of the pointcut expression serves two purposes: firstly, it
restricts matching to only those method executions where the method takes at least one
parameter, and the argument passed to that parameter is an instance of Account ;
secondly, it makes the actual Account object available to the advice via the account
parameter.
Another way of writing this is to declare a pointcut that "provides" the Account object
value when it matches a join point, and then just refer to the named pointcut from the
advice. This would look as follows:

@Pointcut("com.xyz.myapp.SystemArchitecture.dataAccessOperation() && args(account,..)"

private void accountDataAccessOperation(Account account) {}
@Before("accountDataAccessOperation(account)")
public void validateAccount(Account account) {
// ...
}

The interested reader is once more referred to the AspectJ programming guide for more
details.
The proxy object ( this ), target object ( target ), and annotations (
@within, @target, @annotation, @args ) can all be bound in a similar fashion. The
following example shows how you could match the execution of methods annotated with
an @Auditable annotation, and extract the audit code.
First the definition of the @Auditable annotation:
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Auditable {
AuditCode value();
}

25/08/2016 12:10

Spring Framework Reference Documentation

329 de 1194

And then the advice that matches the execution of @Auditable methods:
@Before("com.xyz.lib.Pointcuts.anyPublicMethod() && @annotation(auditable)")
public void audit(Auditable auditable) {
AuditCode code = auditable.value();
// ...
}

Advice parameters and generics

Spring AOP can handle generics used in class declarations and method parameters.
Suppose you have a generic type like this:
public interface Sample<T> {
void sampleGenericMethod(T param);
void sampleGenericCollectionMethod(Collection<T> param);
}

You can restrict interception of method types to certain parameter types by simply typing
the advice parameter to the parameter type you want to intercept the method for:
@Before("execution(* ..Sample+.sampleGenericMethod(*)) && args(param)")
public void beforeSampleMethod(MyType param) {
// Advice implementation
}

That this works is pretty obvious as we already discussed above. However, its worth
pointing out that this wont work for generic collections. So you cannot define a pointcut
like this:
@Before("execution(* ..Sample+.sampleGenericCollectionMethod(*)) && args(param)")
public void beforeSampleMethod(Collection<MyType> param) {
// Advice implementation
}

To make this work we would have to inspect every element of the collection, which is not
reasonable as we also cannot decide how to treat null values in general. To achieve
something similar to this you have to type the parameter to Collection<?> and
manually check the type of the elements.

Determining argument names

The parameter binding in advice invocations relies on matching names used in pointcut
expressions to declared parameter names in (advice and pointcut) method signatures.

25/08/2016 12:10

Spring Framework Reference Documentation

330 de 1194

Parameter names are not available through Java reflection, so Spring AOP uses the
following strategies to determine parameter names:
If the parameter names have been specified by the user explicitly, then the specified
parameter names are used: both the advice and the pointcut annotations have an
optional "argNames" attribute which can be used to specify the argument names of
the annotated method - these argument names are available at runtime. For
example:

@Before(value="com.xyz.lib.Pointcuts.anyPublicMethod() && target(bean) && @annotation(

argNames="bean,auditable")
public void audit(Object bean, Auditable auditable) {
AuditCode code = auditable.value();
// ... use code and bean
}

If the first parameter is of the JoinPoint , ProceedingJoinPoint , or

JoinPoint.StaticPart type, you may leave out the name of the parameter from the
value of the "argNames" attribute. For example, if you modify the preceding advice to
receive the join point object, the "argNames" attribute need not include it:

@Before(value="com.xyz.lib.Pointcuts.anyPublicMethod() && target(bean) && @annotation(

argNames="bean,auditable")
public void audit(JoinPoint jp, Object bean, Auditable auditable) {
AuditCode code = auditable.value();
// ... use code, bean, and jp
}

The special treatment given to the first parameter of the JoinPoint ,

ProceedingJoinPoint , and JoinPoint.StaticPart types is particularly convenient
for advice that do not collect any other join point context. In such situations, you may
simply omit the "argNames" attribute. For example, the following advice need not declare
the "argNames" attribute:
@Before("com.xyz.lib.Pointcuts.anyPublicMethod()")
public void audit(JoinPoint jp) {
// ... use jp
}

Using the 'argNames' attribute is a little clumsy, so if the 'argNames' attribute has
not been specified, then Spring AOP will look at the debug information for the class
and try to determine the parameter names from the local variable table. This
information will be present as long as the classes have been compiled with debug

25/08/2016 12:10

Spring Framework Reference Documentation

331 de 1194

flag on are: (1) your code will be slightly easier to understand (reverse engineer), (2)
the class file sizes will be very slightly bigger (typically inconsequential), (3) the
optimization to remove unused local variables will not be applied by your compiler. In
other words, you should encounter no difficulties building with this flag on.

If an @AspectJ aspect has been compiled by the AspectJ compiler (ajc)

even without the debug information then there is no need to add the
argNames attribute as the compiler will retain the needed information.

If the code has been compiled without the necessary debug information, then Spring
AOP will attempt to deduce the pairing of binding variables to parameters (for
example, if only one variable is bound in the pointcut expression, and the advice
method only takes one parameter, the pairing is obvious!). If the binding of variables
is ambiguous given the available information, then an
AmbiguousBindingException will be thrown.
If all of the above strategies fail then an IllegalArgumentException will be
thrown.

Proceeding with arguments

We remarked earlier that we would describe how to write a proceed call with arguments
that works consistently across Spring AOP and AspectJ. The solution is simply to ensure
that the advice signature binds each of the method parameters in order. For example:
@Around("execution(List<Account> find*(..)) && " +
"com.xyz.myapp.SystemArchitecture.inDataAccessLayer() && " +
"args(accountHolderNamePattern)")
public Object preProcessQueryPattern(ProceedingJoinPoint pjp,
String accountHolderNamePattern) throws Throwable {
String newPattern = preProcess(accountHolderNamePattern);
return pjp.proceed(new Object[] {newPattern});
}

In many cases you will be doing this binding anyway (as in the example above).

Advice ordering
What happens when multiple pieces of advice all want to run at the same join point?
Spring AOP follows the same precedence rules as AspectJ to determine the order of
advice execution. The highest precedence advice runs first "on the way in" (so given two
pieces of before advice, the one with highest precedence runs first). "On the way out"

25/08/2016 12:10

Spring Framework Reference Documentation

332 de 1194

from a join point, the highest precedence advice runs last (so given two pieces of after
advice, the one with the highest precedence will run second).
When two pieces of advice defined in different aspects both need to run at the same join
point, unless you specify otherwise the order of execution is undefined. You can control
the order of execution by specifying precedence. This is done in the normal Spring way
by either implementing the org.springframework.core.Ordered interface in the
aspect class or annotating it with the Order annotation. Given two aspects, the aspect
returning the lower value from Ordered.getValue() (or the annotation value) has the
higher precedence.
When two pieces of advice defined in the same aspect both need to run at the same join
point, the ordering is undefined (since there is no way to retrieve the declaration order via
reflection for javac-compiled classes). Consider collapsing such advice methods into one
advice method per join point in each aspect class, or refactor the pieces of advice into
separate aspect classes - which can be ordered at the aspect level.

11.2.5 Introductions
Introductions (known as inter-type declarations in AspectJ) enable an aspect to declare
that advised objects implement a given interface, and to provide an implementation of
that interface on behalf of those objects.
An introduction is made using the @DeclareParents annotation. This annotation is used
to declare that matching types have a new parent (hence the name). For example, given
an interface UsageTracked , and an implementation of that interface
DefaultUsageTracked , the following aspect declares that all implementors of service
interfaces also implement the UsageTracked interface. (In order to expose statistics via
JMX for example.)
@Aspect
public class UsageTracking {

@DeclareParents(value="com.xzy.myapp.service.*+", defaultImpl=DefaultUsageTracked.
public static UsageTracked mixin;

@Before("com.xyz.myapp.SystemArchitecture.businessService() && this(usageTracked)"

public void recordUsage(UsageTracked usageTracked) {
usageTracked.incrementUseCount();
}
}

25/08/2016 12:10

Spring Framework Reference Documentation

333 de 1194

The interface to be implemented is determined by the type of the annotated field. The
value attribute of the @DeclareParents annotation is an AspectJ type pattern :- any
bean of a matching type will implement the UsageTracked interface. Note that in the
before advice of the above example, service beans can be directly used as
implementations of the UsageTracked interface. If accessing a bean programmatically
you would write the following:
UsageTracked usageTracked = (UsageTracked) context.getBean("myService");

11.2.6 Aspect instantiation models

(This is an advanced topic, so if you are just starting out with AOP you can
safely skip it until later.)

By default there will be a single instance of each aspect within the application context.
AspectJ calls this the singleton instantiation model. It is possible to define aspects with
alternate lifecycles :- Spring supports AspectJs perthis and pertarget instantiation
models ( percflow, percflowbelow, and pertypewithin are not currently
supported).
A "perthis" aspect is declared by specifying a perthis clause in the @Aspect
annotation. Lets look at an example, and then well explain how it works.
@Aspect("perthis(com.xyz.myapp.SystemArchitecture.businessService())")
public class MyAspect {
private int someState;
@Before(com.xyz.myapp.SystemArchitecture.businessService())
public void recordServiceUsage() {
// ...
}
}

The effect of the 'perthis' clause is that one aspect instance will be created for each
unique service object executing a business service (each unique object bound to 'this' at
join points matched by the pointcut expression). The aspect instance is created the first
time that a method is invoked on the service object. The aspect goes out of scope when
the service object goes out of scope. Before the aspect instance is created, none of the

25/08/2016 12:10

Spring Framework Reference Documentation

334 de 1194

declared within it will execute at matched join points, but only when the service object is
the one this aspect is associated with. See the AspectJ programming guide for more
information on per-clauses.
The 'pertarget' instantiation model works in exactly the same way as perthis, but
creates one aspect instance for each unique target object at matched join points.

11.2.7 Example
Now that you have seen how all the constituent parts work, lets put them together to do
something useful!
The execution of business services can sometimes fail due to concurrency issues (for
example, deadlock loser). If the operation is retried, it is quite likely to succeed next time
round. For business services where it is appropriate to retry in such conditions
(idempotent operations that dont need to go back to the user for conflict resolution), wed
like to transparently retry the operation to avoid the client seeing a
PessimisticLockingFailureException . This is a requirement that clearly cuts across
multiple services in the service layer, and hence is ideal for implementing via an aspect.
Because we want to retry the operation, we will need to use around advice so that we can
call proceed multiple times. Heres how the basic aspect implementation looks:
@Aspect
public class ConcurrentOperationExecutor implements Ordered {
private static final int DEFAULT_MAX_RETRIES = 2;
private int maxRetries = DEFAULT_MAX_RETRIES;
private int order = 1;
public void setMaxRetries(int maxRetries) {
this.maxRetries = maxRetries;
}
public int getOrder() {
return this.order;
}
public void setOrder(int order) {
this.order = order;
}
@Around("com.xyz.myapp.SystemArchitecture.businessService()")

25/08/2016 12:10

Spring Framework Reference Documentation

335 de 1194

public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable {

int numAttempts = 0;
PessimisticLockingFailureException lockFailureException;
do {
numAttempts++;
try {
return pjp.proceed();
}
catch(PessimisticLockingFailureException ex) {
lockFailureException = ex;
}
} while(numAttempts <= this.maxRetries);
throw lockFailureException;
}
}

Note that the aspect implements the Ordered interface so we can set the precedence of
the aspect higher than the transaction advice (we want a fresh transaction each time we
retry). The maxRetries and order properties will both be configured by Spring. The
main action happens in the doConcurrentOperation around advice. Notice that for the
moment were applying the retry logic to all businessService()s . We try to proceed,
and if we fail with an PessimisticLockingFailureException we simply try again
unless we have exhausted all of our retry attempts.
The corresponding Spring configuration is:
<aop:aspectj-autoproxy/>

<bean id="concurrentOperationExecutor" class="com.xyz.myapp.service.impl.ConcurrentOpe

To refine the aspect so that it only retries idempotent operations, we might define an
Idempotent annotation:
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {
// marker annotation
}

and use the annotation to annotate the implementation of service operations. The change
to the aspect to only retry idempotent operations simply involves refining the pointcut
expression so that only @Idempotent operations match:

25/08/2016 12:10

Spring Framework Reference Documentation

336 de 1194

@Around("com.xyz.myapp.SystemArchitecture.businessService() && " +

"@annotation(com.xyz.myapp.service.Idempotent)")
public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable {
...
}

11.3 Schema-based AOP support

If you prefer an XML-based format, then Spring also offers support for defining aspects
using the new "aop" namespace tags. The exact same pointcut expressions and advice
kinds are supported as when using the @AspectJ style, hence in this section we will
focus on the new syntax and refer the reader to the discussion in the previous section
(Section 11.2, @AspectJ support) for an understanding of writing pointcut expressions
and the binding of advice parameters.
To use the aop namespace tags described in this section, you need to import the
spring-aop schema as described in Chapter 41, XML Schema-based configuration.
See Section 41.2.7, the aop schema for how to import the tags in the aop namespace.
Within your Spring configurations, all aspect and advisor elements must be placed within
an <aop:config> element (you can have more than one <aop:config> element in an
application context configuration). An <aop:config> element can contain pointcut,
advisor, and aspect elements (note these must be declared in that order).

The <aop:config> style of configuration makes heavy use of Springs

auto-proxying mechanism. This can cause issues (such as advice not being
woven) if you are already using explicit auto-proxying via the use of
BeanNameAutoProxyCreator or suchlike. The recommended usage
pattern is to use either just the <aop:config> style, or just the
AutoProxyCreator style.

11.3.1 Declaring an aspect

Using the schema support, an aspect is simply a regular Java object defined as a bean in
your Spring application context. The state and behavior is captured in the fields and
methods of the object, and the pointcut and advice information is captured in the XML.
An aspect is declared using the <aop:aspect> element, and the backing bean is
referenced using the ref attribute:

25/08/2016 12:10

Spring Framework Reference Documentation

337 de 1194

<aop:config>
<aop:aspect id="myAspect" ref="aBean">
...
</aop:aspect>
</aop:config>
<bean id="aBean" class="...">
...
</bean>

The bean backing the aspect (" `aBean`" in this case) can of course be configured and
dependency injected just like any other Spring bean.

11.3.2 Declaring a pointcut

A named pointcut can be declared inside an <aop:config> element, enabling the pointcut
definition to be shared across several aspects and advisors.
A pointcut representing the execution of any business service in the service layer could
be defined as follows:
<aop:config>
<aop:pointcut id="businessService"
expression="execution(* com.xyz.myapp.service.*.*(..))"/>
</aop:config>

Note that the pointcut expression itself is using the same AspectJ pointcut expression
language as described in Section 11.2, @AspectJ support. If you are using the schema
based declaration style, you can refer to named pointcuts defined in types (@Aspects)
within the pointcut expression. Another way of defining the above pointcut would be:
<aop:config>
<aop:pointcut id="businessService"
expression="com.xyz.myapp.SystemArchitecture.businessService()"/>
</aop:config>

Assuming you have a SystemArchitecture aspect as described in the section called

Sharing common pointcut definitions.
Declaring a pointcut inside an aspect is very similar to declaring a top-level pointcut:

25/08/2016 12:10

Spring Framework Reference Documentation

338 de 1194

<aop:config>
<aop:aspect id="myAspect" ref="aBean">
<aop:pointcut id="businessService"
expression="execution(* com.xyz.myapp.service.*.*(..))"/>
...
</aop:aspect>
</aop:config>

Much the same way in an @AspectJ aspect, pointcuts declared using the schema based
definition style may collect join point context. For example, the following pointcut collects
the 'this' object as the join point context and passes it to advice:
<aop:config>
<aop:aspect id="myAspect" ref="aBean">

<aop:pointcut id="businessService"
expression="execution(* com.xyz.myapp.service.*.*(..)) && this(ser
<aop:before pointcut-ref="businessService" method="monitor"/>
...
</aop:aspect>
</aop:config>

The advice must be declared to receive the collected join point context by including
parameters of the matching names:
public void monitor(Object service) {
...
}

When combining pointcut sub-expressions, '&&' is awkward within an XML document, and
so the keywords 'and', 'or' and 'not' can be used in place of '&&', '||' and '!' respectively.
For example, the previous pointcut may be better written as:
<aop:config>
<aop:aspect id="myAspect" ref="aBean">

25/08/2016 12:10

Spring Framework Reference Documentation

339 de 1194

<aop:pointcut id="businessService"
expression="execution(* com.xyz.myapp.service.*.*(..)) **and** this(servic
<aop:before pointcut-ref="businessService" method="monitor"/>
...
</aop:aspect>
</aop:config>

Note that pointcuts defined in this way are referred to by their XML id and cannot be used
as named pointcuts to form composite pointcuts. The named pointcut support in the
schema based definition style is thus more limited than that offered by the @AspectJ
style.

11.3.3 Declaring advice

The same five advice kinds are supported as for the @AspectJ style, and they have
exactly the same semantics.

Before advice
Before advice runs before a matched method execution. It is declared inside an
<aop:aspect> using the <aop:before> element.
<aop:aspect id="beforeExample" ref="aBean">
<aop:before
pointcut-ref="dataAccessOperation"
method="doAccessCheck"/>
...
</aop:aspect>

Here dataAccessOperation is the id of a pointcut defined at the top ( <aop:config> )

level. To define the pointcut inline instead, replace the pointcut-ref attribute with a
pointcut attribute:
<aop:aspect id="beforeExample" ref="aBean">
<aop:before
pointcut="execution(* com.xyz.myapp.dao.*.*(..))"
method="doAccessCheck"/>

25/08/2016 12:10

Spring Framework Reference Documentation

340 de 1194

...
</aop:aspect>

As we noted in the discussion of the @AspectJ style, using named pointcuts can
significantly improve the readability of your code.
The method attribute identifies a method ( doAccessCheck ) that provides the body of the
advice. This method must be defined for the bean referenced by the aspect element
containing the advice. Before a data access operation is executed (a method execution
join point matched by the pointcut expression), the "doAccessCheck" method on the
aspect bean will be invoked.

After returning advice

After returning advice runs when a matched method execution completes normally. It is
declared inside an <aop:aspect> in the same way as before advice. For example:
<aop:aspect id="afterReturningExample" ref="aBean">
<aop:after-returning
pointcut-ref="dataAccessOperation"
method="doAccessCheck"/>
...
</aop:aspect>

Just as in the @AspectJ style, it is possible to get hold of the return value within the
advice body. Use the returning attribute to specify the name of the parameter to which the
return value should be passed:
<aop:aspect id="afterReturningExample" ref="aBean">
<aop:after-returning
pointcut-ref="dataAccessOperation"
returning="retVal"
method="doAccessCheck"/>
...
</aop:aspect>

The doAccessCheck method must declare a parameter named retVal . The type of this

25/08/2016 12:10

Spring Framework Reference Documentation

341 de 1194

parameter constrains matching in the same way as described for @AfterReturning. For
example, the method signature may be declared as:
public void doAccessCheck(Object retVal) {...

After throwing advice

After throwing advice executes when a matched method execution exits by throwing an
exception. It is declared inside an <aop:aspect> using the after-throwing element:
<aop:aspect id="afterThrowingExample" ref="aBean">
<aop:after-throwing
pointcut-ref="dataAccessOperation"
method="doRecoveryActions"/>
...
</aop:aspect>

Just as in the @AspectJ style, it is possible to get hold of the thrown exception within the
advice body. Use the throwing attribute to specify the name of the parameter to which the
exception should be passed:
<aop:aspect id="afterThrowingExample" ref="aBean">
<aop:after-throwing
pointcut-ref="dataAccessOperation"
throwing="dataAccessEx"
method="doRecoveryActions"/>
...
</aop:aspect>

The doRecoveryActions method must declare a parameter named dataAccessEx . The

type of this parameter constrains matching in the same way as described for
@AfterThrowing. For example, the method signature may be declared as:
public void doRecoveryActions(DataAccessException dataAccessEx) {...

After (finally) advice

After (finally) advice runs however a matched method execution exits. It is declared using

25/08/2016 12:10

Spring Framework Reference Documentation

342 de 1194

the after element:

<aop:aspect id="afterFinallyExample" ref="aBean">
<aop:after
pointcut-ref="dataAccessOperation"
method="doReleaseLock"/>
...
</aop:aspect>

Around advice
The final kind of advice is around advice. Around advice runs "around" a matched method
execution. It has the opportunity to do work both before and after the method executes,
and to determine when, how, and even if, the method actually gets to execute at all.
Around advice is often used if you need to share state before and after a method
execution in a thread-safe manner (starting and stopping a timer for example). Always
use the least powerful form of advice that meets your requirements; dont use around
advice if simple before advice would do.
Around advice is declared using the aop:around element. The first parameter of the
advice method must be of type ProceedingJoinPoint . Within the body of the advice,
calling proceed() on the ProceedingJoinPoint causes the underlying method to
execute. The proceed method may also be calling passing in an Object[] - the values
in the array will be used as the arguments to the method execution when it proceeds. See
the section called Around advice for notes on calling proceed with an Object[] .
<aop:aspect id="aroundExample" ref="aBean">
<aop:around
pointcut-ref="businessService"
method="doBasicProfiling"/>
...
</aop:aspect>

The implementation of the doBasicProfiling advice would be exactly the same as in

the @AspectJ example (minus the annotation of course):
public Object doBasicProfiling(ProceedingJoinPoint pjp) throws Throwable {
// start stopwatch

25/08/2016 12:10

Spring Framework Reference Documentation

343 de 1194

Object retVal = pjp.proceed();

// stop stopwatch
return retVal;
}

Advice parameters
The schema based declaration style supports fully typed advice in the same way as
described for the @AspectJ support - by matching pointcut parameters by name against
advice method parameters. See the section called Advice parameters for details. If you
wish to explicitly specify argument names for the advice methods (not relying on the
detection strategies previously described) then this is done using the arg-names
attribute of the advice element, which is treated in the same manner to the "argNames"
attribute in an advice annotation as described in the section called Determining argument
names. For example:
<aop:before
pointcut="com.xyz.lib.Pointcuts.anyPublicMethod() and @annotation(auditable)"
method="audit"
arg-names="auditable"/>

The arg-names attribute accepts a comma-delimited list of parameter names.

Find below a slightly more involved example of the XSD-based approach that illustrates
some around advice used in conjunction with a number of strongly typed parameters.
package x.y.service;
public interface FooService {
Foo getFoo(String fooName, int age);
}
public class DefaultFooService implements FooService {
public Foo getFoo(String name, int age) {
return new Foo(name, age);
}
}

Next up is the aspect. Notice the fact that the profile(..) method accepts a number of
strongly-typed parameters, the first of which happens to be the join point used to proceed
with the method call: the presence of this parameter is an indication that the
profile(..) is to be used as around advice:

25/08/2016 12:10

Spring Framework Reference Documentation

344 de 1194

package x.y;
import org.aspectj.lang.ProceedingJoinPoint;
import org.springframework.util.StopWatch;
public class SimpleProfiler {
public Object profile(ProceedingJoinPoint call, String name, int age) throws
StopWatch clock = new StopWatch("Profiling for '" + name + "' and '"
try {
clock.start(call.toShortString());
return call.proceed();
} finally {
clock.stop();
System.out.println(clock.prettyPrint());
}
}
}

Finally, here is the XML configuration that is required to effect the execution of the above
advice for a particular join point:

25/08/2016 12:10

Spring Framework Reference Documentation

345 de 1194

</beans>

If we had the following driver script, we would get output something like this on standard
output:
import org.springframework.beans.factory.BeanFactory;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import x.y.service.FooService;
public final class Boot {
public static void main(final String[] args) throws Exception {
BeanFactory ctx = new ClassPathXmlApplicationContext("x/y/plain.xml"
FooService foo = (FooService) ctx.getBean("fooService");
foo.getFoo("Pengo", 12);
}
}
StopWatch 'Profiling for 'Pengo' and '12'': running time (millis) = 0
----------------------------------------ms
%
Task name
----------------------------------------00000 ? execution(getFoo)

Advice ordering
When multiple advice needs to execute at the same join point (executing method) the
ordering rules are as described in the section called Advice ordering. The precedence
between aspects is determined by either adding the Order annotation to the bean
backing the aspect or by having the bean implement the Ordered interface.

11.3.4 Introductions
Introductions (known as inter-type declarations in AspectJ) enable an aspect to declare
that advised objects implement a given interface, and to provide an implementation of
that interface on behalf of those objects.
An introduction is made using the aop:declare-parents element inside an
aop:aspect This element is used to declare that matching types have a new parent
(hence the name). For example, given an interface UsageTracked , and an
implementation of that interface DefaultUsageTracked , the following aspect declares
that all implementors of service interfaces also implement the UsageTracked interface.
(In order to expose statistics via JMX for example.)

25/08/2016 12:10

Spring Framework Reference Documentation

346 de 1194

<aop:declare-parents
types-matching="com.xzy.myapp.service.*+"
implement-interface="com.xyz.myapp.service.tracking.UsageTracked"
default-impl="com.xyz.myapp.service.tracking.DefaultUsageTracked"/>
<aop:before
pointcut="com.xyz.myapp.SystemArchitecture.businessService()
and this(usageTracked)"
method="recordUsage"/>
</aop:aspect>

The class backing the usageTracking bean would contain the method:
public void recordUsage(UsageTracked usageTracked) {
usageTracked.incrementUseCount();
}

The interface to be implemented is determined by implement-interface attribute. The

value of the types-matching attribute is an AspectJ type pattern :- any bean of a
matching type will implement the UsageTracked interface. Note that in the before advice
of the above example, service beans can be directly used as implementations of the
UsageTracked interface. If accessing a bean programmatically you would write the
following:
UsageTracked usageTracked = (UsageTracked) context.getBean("myService");

11.3.5 Aspect instantiation models

The only supported instantiation model for schema-defined aspects is the singleton
model. Other instantiation models may be supported in future releases.

11.3.6 Advisors
The concept of "advisors" is brought forward from the AOP support defined in Spring 1.2
and does not have a direct equivalent in AspectJ. An advisor is like a small self-contained
aspect that has a single piece of advice. The advice itself is represented by a bean, and
must implement one of the advice interfaces described in Section 12.3.2, Advice types in
Spring. Advisors can take advantage of AspectJ pointcut expressions though.
Spring supports the advisor concept with the <aop:advisor> element. You will most

25/08/2016 12:10

Spring Framework Reference Documentation

347 de 1194

namespace support in Spring. Heres how it looks:

<aop:config>
<aop:pointcut id="businessService"
expression="execution(* com.xyz.myapp.service.*.*(..))"/>
<aop:advisor
pointcut-ref="businessService"
advice-ref="tx-advice"/>
</aop:config>
<tx:advice id="tx-advice">
<tx:attributes>
<tx:method name="*" propagation="REQUIRED"/>
</tx:attributes>
</tx:advice>

As well as the pointcut-ref attribute used in the above example, you can also use the
pointcut attribute to define a pointcut expression inline.
To define the precedence of an advisor so that the advice can participate in ordering, use
the order attribute to define the Ordered value of the advisor.

11.3.7 Example
Lets see how the concurrent locking failure retry example from Section 11.2.7, Example
looks when rewritten using the schema support.
The execution of business services can sometimes fail due to concurrency issues (for
example, deadlock loser). If the operation is retried, it is quite likely it will succeed next
time round. For business services where it is appropriate to retry in such conditions
(idempotent operations that dont need to go back to the user for conflict resolution), wed
like to transparently retry the operation to avoid the client seeing a
PessimisticLockingFailureException . This is a requirement that clearly cuts across
multiple services in the service layer, and hence is ideal for implementing via an aspect.
Because we want to retry the operation, well need to use around advice so that we can
call proceed multiple times. Heres how the basic aspect implementation looks (its just a
regular Java class using the schema support):
public class ConcurrentOperationExecutor implements Ordered {

25/08/2016 12:10

Spring Framework Reference Documentation

348 de 1194

private static final int DEFAULT_MAX_RETRIES = 2;

private int maxRetries = DEFAULT_MAX_RETRIES;
private int order = 1;
public void setMaxRetries(int maxRetries) {
this.maxRetries = maxRetries;
}
public int getOrder() {
return this.order;
}
public void setOrder(int order) {
this.order = order;
}
public Object doConcurrentOperation(ProceedingJoinPoint pjp) throws Throwable {
int numAttempts = 0;
PessimisticLockingFailureException lockFailureException;
do {
numAttempts++;
try {
return pjp.proceed();
}
catch(PessimisticLockingFailureException ex) {
lockFailureException = ex;
}
} while(numAttempts <= this.maxRetries);
throw lockFailureException;
}
}

Note that the aspect implements the Ordered interface so we can set the precedence of
the aspect higher than the transaction advice (we want a fresh transaction each time we
retry). The maxRetries and order properties will both be configured by Spring. The
main action happens in the doConcurrentOperation around advice method. We try to
proceed, and if we fail with a PessimisticLockingFailureException we simply try
again unless we have exhausted all of our retry attempts.

This class is identical to the one used in the @AspectJ example, but with
the annotations removed.

25/08/2016 12:10

Spring Framework Reference Documentation

349 de 1194

<aop:config>
<aop:aspect id="concurrentOperationRetry" ref="concurrentOperationExecutor"
<aop:pointcut id="idempotentOperation"
expression="execution(* com.xyz.myapp.service.*.*(..))"/>
<aop:around
pointcut-ref="idempotentOperation"
method="doConcurrentOperation"/>
</aop:aspect>
</aop:config>
<bean id="concurrentOperationExecutor"
class="com.xyz.myapp.service.impl.ConcurrentOperationExecutor">
<property name="maxRetries" value="3"/>
<property name="order" value="100"/>
</bean>

Notice that for the time being we assume that all business services are idempotent. If this
is not the case we can refine the aspect so that it only retries genuinely idempotent
operations, by introducing an Idempotent annotation:
@Retention(RetentionPolicy.RUNTIME)
public @interface Idempotent {
// marker annotation
}

and using the annotation to annotate the implementation of service operations. The
change to the aspect to retry only idempotent operations simply involves refining the
pointcut expression so that only @Idempotent operations match:
<aop:pointcut id="idempotentOperation"
expression="execution(* com.xyz.myapp.service.*.*(..)) and
@annotation(com.xyz.myapp.service.Idempotent)"/>

11.4 Choosing which AOP declaration style to use

Once you have decided that an aspect is the best approach for implementing a given
requirement, how do you decide between using Spring AOP or AspectJ, and between the
Aspect language (code) style, @AspectJ annotation style, or the Spring XML style?
These decisions are influenced by a number of factors including application requirements,

25/08/2016 12:10

Spring Framework Reference Documentation

350 de 1194

development tools, and team familiarity with AOP.

11.4.1 Spring AOP or full AspectJ?

Use the simplest thing that can work. Spring AOP is simpler than using full AspectJ as
there is no requirement to introduce the AspectJ compiler / weaver into your development
and build processes. If you only need to advise the execution of operations on Spring
beans, then Spring AOP is the right choice. If you need to advise objects not managed by
the Spring container (such as domain objects typically), then you will need to use
AspectJ. You will also need to use AspectJ if you wish to advise join points other than
simple method executions (for example, field get or set join points, and so on).
When using AspectJ, you have the choice of the AspectJ language syntax (also known as
the "code style") or the @AspectJ annotation style. Clearly, if you are not using Java 5+
then the choice has been made for you use the code style. If aspects play a large role
in your design, and you are able to use the AspectJ Development Tools (AJDT) plugin for
Eclipse, then the AspectJ language syntax is the preferred option: it is cleaner and
simpler because the language was purposefully designed for writing aspects. If you are
not using Eclipse, or have only a few aspects that do not play a major role in your
application, then you may want to consider using the @AspectJ style and sticking with a
regular Java compilation in your IDE, and adding an aspect weaving phase to your build
script.

11.4.2 @AspectJ or XML for Spring AOP?

If you have chosen to use Spring AOP, then you have a choice of @AspectJ or XML
style. There are various tradeoffs to consider.
The XML style will be most familiar to existing Spring users and it is backed by genuine
POJOs. When using AOP as a tool to configure enterprise services then XML can be a
good choice (a good test is whether you consider the pointcut expression to be a part of
your configuration you might want to change independently). With the XML style arguably
it is clearer from your configuration what aspects are present in the system.
The XML style has two disadvantages. Firstly it does not fully encapsulate the
implementation of the requirement it addresses in a single place. The DRY principle says
that there should be a single, unambiguous, authoritative representation of any piece of
knowledge within a system. When using the XML style, the knowledge of how a
requirement is implemented is split across the declaration of the backing bean class, and
the XML in the configuration file. When using the @AspectJ style there is a single module

25/08/2016 12:10

Spring Framework Reference Documentation

351 de 1194

- the aspect - in which this information is encapsulated. Secondly, the XML style is slightly
more limited in what it can express than the @AspectJ style: only the "singleton" aspect
instantiation model is supported, and it is not possible to combine named pointcuts
declared in XML. For example, in the @AspectJ style you can write something like:
@Pointcut(execution(* get*()))
public void propertyAccess() {}
@Pointcut(execution(org.xyz.Account+ *(..))
public void operationReturningAnAccount() {}
@Pointcut(propertyAccess() && operationReturningAnAccount())
public void accountPropertyAccess() {}

In the XML style I can declare the first two pointcuts:

<aop:pointcut id="propertyAccess"
expression="execution(* get*())"/>
<aop:pointcut id="operationReturningAnAccount"
expression="execution(org.xyz.Account+ *(..))"/>

The downside of the XML approach is that you cannot define the
accountPropertyAccess pointcut by combining these definitions.
The @AspectJ style supports additional instantiation models, and richer pointcut
composition. It has the advantage of keeping the aspect as a modular unit. It also has the
advantage the @AspectJ aspects can be understood (and thus consumed) both by
Spring AOP and by AspectJ - so if you later decide you need the capabilities of AspectJ
to implement additional requirements then it is very easy to migrate to an AspectJ-based
approach. On balance the Spring team prefer the @AspectJ style whenever you have
aspects that do more than simple "configuration" of enterprise services.

11.5 Mixing aspect types

It is perfectly possible to mix @AspectJ style aspects using the autoproxying support,
schema-defined <aop:aspect> aspects, <aop:advisor> declared advisors and even
proxies and interceptors defined using the Spring 1.2 style in the same configuration. All
of these are implemented using the same underlying support mechanism and will co-exist
without any difficulty.

25/08/2016 12:10

Spring Framework Reference Documentation

352 de 1194

11.6 Proxying mechanisms

Spring AOP uses either JDK dynamic proxies or CGLIB to create the proxy for a given
target object. (JDK dynamic proxies are preferred whenever you have a choice).
If the target object to be proxied implements at least one interface then a JDK dynamic
proxy will be used. All of the interfaces implemented by the target type will be proxied. If
the target object does not implement any interfaces then a CGLIB proxy will be created.
If you want to force the use of CGLIB proxying (for example, to proxy every method
defined for the target object, not just those implemented by its interfaces) you can do so.
However, there are some issues to consider:
final methods cannot be advised, as they cannot be overridden.
As of Spring 3.2, it is no longer necessary to add CGLIB to your project classpath, as
CGLIB classes are repackaged under org.springframework and included directly in
the spring-core JAR. This means that CGLIB-based proxy support 'just works' in the
same way that JDK dynamic proxies always have.
As of Spring 4.0, the constructor of your proxied object will NOT be called twice
anymore since the CGLIB proxy instance will be created via Objenesis. Only if your
JVM does not allow for constructor bypassing, you might see double invocations and
corresponding debug log entries from Springs AOP support.
To force the use of CGLIB proxies set the value of the proxy-target-class attribute of
the <aop:config> element to true:
<aop:config proxy-target-class="true">

</aop:config>

To force CGLIB proxying when using the @AspectJ autoproxy support, set the
'proxy-target-class' attribute of the <aop:aspectj-autoproxy> element to true :
<aop:aspectj-autoproxy proxy-target-class="true"/>

Multiple <aop:config/> sections are collapsed into a single unified

auto-proxy creator at runtime, which applies the strongest proxy settings
that any of the <aop:config/> sections (typically from different XML bean
definition files) specified. This also applies to the
<tx:annotation-driven/> and <aop:aspectj-autoproxy/> elements.
To be clear: using proxy-target-class="true" on

25/08/2016 12:10

Spring Framework Reference Documentation

353 de 1194

<aop:config/> elements will force the use of CGLIB proxies for all three
of them.

11.6.1 Understanding AOP proxies

Spring AOP is proxy-based. It is vitally important that you grasp the semantics of what
that last statement actually means before you write your own aspects or use any of the
Spring AOP-based aspects supplied with the Spring Framework.
Consider first the scenario where you have a plain-vanilla, un-proxied, nothing-specialabout-it, straight object reference, as illustrated by the following code snippet.
public class SimplePojo implements Pojo {
public void foo() {
// this next method invocation is a direct call on the 'this' reference
this.bar();
}
public void bar() {
// some logic...
}
}

If you invoke a method on an object reference, the method is invoked directly on that
object reference, as can be seen below.

public class Main {

public static void main(String[] args) {
Pojo pojo = new SimplePojo();
// this is a direct method call on the 'pojo' reference

25/08/2016 12:10

Spring Framework Reference Documentation

354 de 1194

}
}

Things change slightly when the reference that client code has is a proxy. Consider the
following diagram and code snippet.

public class Main {

public static void main(String[] args) {
ProxyFactory factory = new ProxyFactory(new SimplePojo());
factory.addInterface(Pojo.class);
factory.addAdvice(new RetryAdvice());
Pojo pojo = (Pojo) factory.getProxy();
// this is a method call on the proxy!
pojo.foo();
}
}

The key thing to understand here is that the client code inside the main(..) of the
Main class has a reference to the proxy. This means that method calls on that object
reference will be calls on the proxy, and as such the proxy will be able to delegate to all of
the interceptors (advice) that are relevant to that particular method call. However, once
the call has finally reached the target object, the SimplePojo reference in this case, any
method calls that it may make on itself, such as this.bar() or this.foo() , are going
to be invoked against the this reference, and not the proxy. This has important
implications. It means that self-invocation is not going to result in the advice associated
with a method invocation getting a chance to execute.
Okay, so what is to be done about this? The best approach (the term best is used loosely
here) is to refactor your code such that the self-invocation does not happen. For sure, this
does entail some work on your part, but it is the best, least-invasive approach. The next
approach is absolutely horrendous, and I am almost reticent to point it out precisely

25/08/2016 12:10

Spring Framework Reference Documentation

355 de 1194

because it is so horrendous. You can (choke!) totally tie the logic within your class to
Spring AOP by doing this:
public class SimplePojo implements Pojo {
public void foo() {
// this works, but... gah!
((Pojo) AopContext.currentProxy()).bar();
}
public void bar() {
// some logic...
}
}

This totally couples your code to Spring AOP, and it makes the class itself aware of the
fact that it is being used in an AOP context, which flies in the face of AOP. It also requires
some additional configuration when the proxy is being created:
public class Main {
public static void main(String[] args) {
ProxyFactory factory = new ProxyFactory(new SimplePojo());
factory.adddInterface(Pojo.class);
factory.addAdvice(new RetryAdvice());
factory.setExposeProxy(true);
Pojo pojo = (Pojo) factory.getProxy();
// this is a method call on the proxy!
pojo.foo();
}
}

Finally, it must be noted that AspectJ does not have this self-invocation issue because it
is not a proxy-based AOP framework.

11.7 Programmatic creation of @AspectJ Proxies

In addition to declaring aspects in your configuration using either <aop:config> or
<aop:aspectj-autoproxy> , it is also possible programmatically to create proxies that
advise target objects. For the full details of Springs AOP API, see the next chapter. Here
we want to focus on the ability to automatically create proxies using @AspectJ aspects.

25/08/2016 12:10

Spring Framework Reference Documentation

356 de 1194

The class org.springframework.aop.aspectj.annotation.AspectJProxyFactory

can be used to create a proxy for a target object that is advised by one or more
@AspectJ aspects. Basic usage for this class is very simple, as illustrated below. See the
javadocs for full information.
// create a factory that can generate a proxy for the given target object
AspectJProxyFactory factory = new AspectJProxyFactory(targetObject);
// add an aspect, the class must be an @AspectJ aspect
// you can call this as many times as you need with different aspects
factory.addAspect(SecurityManager.class);

// you can also add existing aspect instances, the type of the object supplied must be
factory.addAspect(usageTracker);
// now get the proxy object...
MyInterfaceType proxy = factory.getProxy();

11.8 Using AspectJ with Spring applications

Everything weve covered so far in this chapter is pure Spring AOP. In this section, were
going to look at how you can use the AspectJ compiler/weaver instead of, or in addition
to, Spring AOP if your needs go beyond the facilities offered by Spring AOP alone.
Spring ships with a small AspectJ aspect library, which is available standalone in your
distribution as spring-aspects.jar ; youll need to add this to your classpath in order to
use the aspects in it. Section 11.8.1, Using AspectJ to dependency inject domain objects
with Spring and Section 11.8.2, Other Spring aspects for AspectJ discuss the content of
this library and how you can use it. Section 11.8.3, Configuring AspectJ aspects using
Spring IoC discusses how to dependency inject AspectJ aspects that are woven using
the AspectJ compiler. Finally, Section 11.8.4, Load-time weaving with AspectJ in the
Spring Framework provides an introduction to load-time weaving for Spring applications
using AspectJ.

11.8.1 Using AspectJ to dependency inject domain objects with

Spring
The Spring container instantiates and configures beans defined in your application
context. It is also possible to ask a bean factory to configure a pre-existing object given
the name of a bean definition containing the configuration to be applied. The
spring-aspects.jar contains an annotation-driven aspect that exploits this capability

25/08/2016 12:10

Spring Framework Reference Documentation

357 de 1194

to allow dependency injection of any object. The support is intended to be used for
objects created outside of the control of any container. Domain objects often fall into this
category because they are often created programmatically using the new operator, or by
an ORM tool as a result of a database query.
The @Configurable annotation marks a class as eligible for Spring-driven configuration.
In the simplest case it can be used just as a marker annotation:
package com.xyz.myapp.domain;
import org.springframework.beans.factory.annotation.Configurable;
@Configurable
public class Account {
// ...
}

When used as a marker interface in this way, Spring will configure new instances of the
annotated type ( Account in this case) using a bean definition (typically prototypescoped) with the same name as the fully-qualified type name (
com.xyz.myapp.domain.Account ). Since the default name for a bean is the fullyqualified name of its type, a convenient way to declare the prototype definition is simply to
omit the id attribute:
<bean class="com.xyz.myapp.domain.Account" scope="prototype">
<property name="fundsTransferService" ref="fundsTransferService"/>
</bean>

If you want to explicitly specify the name of the prototype bean definition to use, you can
do so directly in the annotation:
package com.xyz.myapp.domain;
import org.springframework.beans.factory.annotation.Configurable;
@Configurable("account")
public class Account {
// ...
}

Spring will now look for a bean definition named "account" and use that as the definition
to configure new Account instances.
You can also use autowiring to avoid having to specify a dedicated bean definition at all.

25/08/2016 12:10

Spring Framework Reference Documentation

358 de 1194

annotation: specify either @Configurable(autowire=Autowire.BY_TYPE) or

@Configurable(autowire=Autowire.BY_NAME for autowiring by type or by name
respectively. As an alternative, as of Spring 2.5 it is preferable to specify explicit,
annotation-driven dependency injection for your @Configurable beans by using
@Autowired or @Inject at the field or method level (see Section 7.9,
Annotation-based container configuration for further details).
Finally you can enable Spring dependency checking for the object references in the newly
created and configured object by using the dependencyCheck attribute (for example:
@Configurable(autowire=Autowire.BY_NAME,dependencyCheck=true) ). If this
attribute is set to true, then Spring will validate after configuration that all properties
(which are not primitives or collections) have been set.
Using the annotation on its own does nothing of course. It is the
AnnotationBeanConfigurerAspect in spring-aspects.jar that acts on the
presence of the annotation. In essence the aspect says "after returning from the
initialization of a new object of a type annotated with @Configurable , configure the
newly created object using Spring in accordance with the properties of the annotation". In
this context, initialization refers to newly instantiated objects (e.g., objects instantiated
with the new operator) as well as to Serializable objects that are undergoing
deserialization (e.g., via readResolve()).

One of the key phrases in the above paragraph is 'in essence'. For most
cases, the exact semantics of 'after returning from the initialization of a new
object' will be fine in this context, 'after initialization' means that the
dependencies will be injected after the object has been constructed - this
means that the dependencies will not be available for use in the constructor
bodies of the class. If you want the dependencies to be injected before the
constructor bodies execute, and thus be available for use in the body of the
constructors, then you need to define this on the @Configurable
declaration like so:
@Configurable(preConstruction=true)

You can find out more information about the language semantics of the
various pointcut types in AspectJ in this appendix of the AspectJ
Programming Guide.

For this to work the annotated types must be woven with the AspectJ weaver - you can
either use a build-time Ant or Maven task to do this (see for example the AspectJ
Development Environment Guide) or load-time weaving (see Section 11.8.4, Load-time

25/08/2016 12:10

Spring Framework Reference Documentation

359 de 1194

weaving with AspectJ in the Spring Framework). The

AnnotationBeanConfigurerAspect itself needs configuring by Spring (in order to
obtain a reference to the bean factory that is to be used to configure new objects). If you
are using Java based configuration simply add @EnableSpringConfigured to any
@Configuration class.
@Configuration
@EnableSpringConfigured
public class AppConfig {
}

If you prefer XML based configuration, the Spring context namespace defines a
convenient context:spring-configured element:
<context:spring-configured/>

Instances of @Configurable objects created before the aspect has been configured will
result in a message being issued to the debug log and no configuration of the object
taking place. An example might be a bean in the Spring configuration that creates domain
objects when it is initialized by Spring. In this case you can use the "depends-on" bean
attribute to manually specify that the bean depends on the configuration aspect.

Do not activate @Configurable processing through the bean configurer

aspect unless you really mean to rely on its semantics at runtime. In
particular, make sure that you do not use @Configurable on bean classes
which are registered as regular Spring beans with the container: You would
get double initialization otherwise, once through the container and once
through the aspect.

Unit testing @Configurable objects

One of the goals of the @Configurable support is to enable independent unit testing of

25/08/2016 12:10

Spring Framework Reference Documentation

360 de 1194

@Configurable types have not been woven by AspectJ then the annotation has no
affect during unit testing, and you can simply set mock or stub property references in the
object under test and proceed as normal. If @Configurable types have been woven by
AspectJ then you can still unit test outside of the container as normal, but you will see a
warning message each time that you construct an @Configurable object indicating that
it has not been configured by Spring.

Working with multiple application contexts

The AnnotationBeanConfigurerAspect used to implement the @Configurable
support is an AspectJ singleton aspect. The scope of a singleton aspect is the same as
the scope of static members, that is to say there is one aspect instance per
classloader that defines the type. This means that if you define multiple application
contexts within the same classloader hierarchy you need to consider where to define the
@EnableSpringConfigured bean and where to place spring-aspects.jar on the
classpath.
Consider a typical Spring web-app configuration with a shared parent application context
defining common business services and everything needed to support them, and one
child application context per servlet containing definitions particular to that servlet. All of
these contexts will co-exist within the same classloader hierarchy, and so the
AnnotationBeanConfigurerAspect can only hold a reference to one of them. In this
case we recommend defining the @EnableSpringConfigured bean in the shared
(parent) application context: this defines the services that you are likely to want to inject
into domain objects. A consequence is that you cannot configure domain objects with
references to beans defined in the child (servlet-specific) contexts using the
@Configurable mechanism (probably not something you want to do anyway!).
When deploying multiple web-apps within the same container, ensure that each
web-application loads the types in spring-aspects.jar using its own classloader (for
example, by placing spring-aspects.jar in 'WEB-INF/lib' ). If
spring-aspects.jar is only added to the container wide classpath (and hence loaded
by the shared parent classloader), all web applications will share the same aspect
instance which is probably not what you want.

11.8.2 Other Spring aspects for AspectJ

In addition to the @Configurable aspect, spring-aspects.jar contains an AspectJ
aspect that can be used to drive Springs transaction management for types and methods
annotated with the @Transactional annotation. This is primarily intended for users who

25/08/2016 12:10

Spring Framework Reference Documentation

361 de 1194

want to use the Spring Frameworks transaction support outside of the Spring container.
The aspect that interprets @Transactional annotations is the
AnnotationTransactionAspect . When using this aspect, you must annotate the
implementation class (and/or methods within that class), not the interface (if any) that the
class implements. AspectJ follows Javas rule that annotations on interfaces are not
inherited.
A @Transactional annotation on a class specifies the default transaction semantics for
the execution of any public operation in the class.
A @Transactional annotation on a method within the class overrides the default
transaction semantics given by the class annotation (if present). Methods of any visibility
may be annotated, including private methods. Annotating non-public methods directly is
the only way to get transaction demarcation for the execution of such methods.

Since Spring Framework 4.2, spring-aspects provides a similar aspect

that offers the exact same features for the standard
javax.transaction.Transactional annotation. Check
JtaAnnotationTransactionAspect for more details.

For AspectJ programmers that want to use the Spring configuration and transaction
management support but dont want to (or cannot) use annotations,
spring-aspects.jar also contains abstract aspects you can extend to provide your
own pointcut definitions. See the sources for the AbstractBeanConfigurerAspect and
AbstractTransactionAspect aspects for more information. As an example, the
following excerpt shows how you could write an aspect to configure all instances of
objects defined in the domain model using prototype bean definitions that match the fullyqualified class names:
public aspect DomainObjectConfiguration extends AbstractBeanConfigurerAspect {
public DomainObjectConfiguration() {
setBeanWiringInfoResolver(new ClassNameBeanWiringInfoResolver());
}
// the creation of a new bean (any object in the domain model)
protected pointcut beanCreation(Object beanInstance) :
initialization(new(..)) &&
SystemArchitecture.inDomainModel() &&
this(beanInstance);

25/08/2016 12:10

Spring Framework Reference Documentation

362 de 1194

11.8.3 Configuring AspectJ aspects using Spring IoC

When using AspectJ aspects with Spring applications, it is natural to both want and
expect to be able to configure such aspects using Spring. The AspectJ runtime itself is
responsible for aspect creation, and the means of configuring the AspectJ created
aspects via Spring depends on the AspectJ instantiation model (the per-xxx clause)
used by the aspect.
The majority of AspectJ aspects are singleton aspects. Configuration of these aspects is
very easy: simply create a bean definition referencing the aspect type as normal, and
include the bean attribute 'factory-method="aspectOf"' . This ensures that Spring
obtains the aspect instance by asking AspectJ for it rather than trying to create an
instance itself. For example:
<bean id="profiler" class="com.xyz.profiler.Profiler"
factory-method="aspectOf">
<property name="profilingStrategy" ref="jamonProfilingStrategy"/>
</bean>

Non-singleton aspects are harder to configure: however it is possible to do so by creating

prototype bean definitions and using the @Configurable support from
spring-aspects.jar to configure the aspect instances once they have bean created
by the AspectJ runtime.
If you have some @AspectJ aspects that you want to weave with AspectJ (for example,
using load-time weaving for domain model types) and other @AspectJ aspects that you
want to use with Spring AOP, and these aspects are all configured using Spring, then you
will need to tell the Spring AOP @AspectJ autoproxying support which exact subset of
the @AspectJ aspects defined in the configuration should be used for autoproxying. You
can do this by using one or more <include/> elements inside the
<aop:aspectj-autoproxy/> declaration. Each <include/> element specifies a name
pattern, and only beans with names matched by at least one of the patterns will be used
for Spring AOP autoproxy configuration:
<aop:aspectj-autoproxy>
<aop:include name="thisBean"/>
<aop:include name="thatBean"/>
</aop:aspectj-autoproxy>

25/08/2016 12:10

Spring Framework Reference Documentation

363 de 1194

Do not be misled by the name of the <aop:aspectj-autoproxy/>

element: using it will result in the creation of Spring AOP proxies. The
@AspectJ style of aspect declaration is just being used here, but the
AspectJ runtime is not involved.

11.8.4 Load-time weaving with AspectJ in the Spring Framework

Load-time weaving (LTW) refers to the process of weaving AspectJ aspects into an
applications class files as they are being loaded into the Java virtual machine (JVM). The
focus of this section is on configuring and using LTW in the specific context of the Spring
Framework: this section is not an introduction to LTW though. For full details on the
specifics of LTW and configuring LTW with just AspectJ (with Spring not being involved at
all), see the LTW section of the AspectJ Development Environment Guide.
The value-add that the Spring Framework brings to AspectJ LTW is in enabling much
finer-grained control over the weaving process. 'Vanilla' AspectJ LTW is effected using a
Java (5+) agent, which is switched on by specifying a VM argument when starting up a
JVM. It is thus a JVM-wide setting, which may be fine in some situations, but often is a
little too coarse. Spring-enabled LTW enables you to switch on LTW on a
per-ClassLoader basis, which obviously is more fine-grained and which can make more
sense in a 'single-JVM-multiple-application' environment (such as is found in a typical
application server environment).
Further, in certain environments, this support enables load-time weaving without making
any modifications to the application servers launch script that will be needed to add
-javaagent:path/to/aspectjweaver.jar or (as we describe later in this section)
-javaagent:path/to/org.springframework.instrument-{version}.jar
(previously named spring-agent.jar ). Developers simply modify one or more files that
form the application context to enable load-time weaving instead of relying on
administrators who typically are in charge of the deployment configuration such as the
launch script.
Now that the sales pitch is over, let us first walk through a quick example of AspectJ LTW
using Spring, followed by detailed specifics about elements introduced in the following
example. For a complete example, please see the Petclinic sample application.

A first example
Let us assume that you are an application developer who has been tasked with

25/08/2016 12:10

Spring Framework Reference Documentation

364 de 1194

a profiling tool, what we are going to do is switch on a simple profiling aspect that will
enable us to very quickly get some performance metrics, so that we can then apply a
finer-grained profiling tool to that specific area immediately afterwards.

The example presented here uses XML style configuration, it is also

possible to configure and use @AspectJ with Java Configuration.
Specifically the @EnableLoadTimeWeaving annotation can be used as an
alternative to <context:load-time-weaver/> (see below for details).

Here is the profiling aspect. Nothing too fancy, just a quick-and-dirty time-based profiler,
using the @AspectJ-style of aspect declaration.
package foo;
import
import
import
import
import
import

org.aspectj.lang.ProceedingJoinPoint;
org.aspectj.lang.annotation.Aspect;
org.aspectj.lang.annotation.Around;
org.aspectj.lang.annotation.Pointcut;
org.springframework.util.StopWatch;
org.springframework.core.annotation.Order;

@Aspect
public class ProfilingAspect {
@Around("methodsToBeProfiled()")
public Object profile(ProceedingJoinPoint pjp) throws Throwable {
StopWatch sw = new StopWatch(getClass().getSimpleName());
try {
sw.start(pjp.getSignature().getName());
return pjp.proceed();
} finally {
sw.stop();
System.out.println(sw.prettyPrint());
}
}
@Pointcut("execution(public * foo..*.*(..))")
public void methodsToBeProfiled(){}
}

We will also need to create an META-INF/aop.xml file, to inform the AspectJ weaver
that we want to weave our ProfilingAspect into our classes. This file convention,
namely the presence of a file (or files) on the Java classpath called META-INF/aop.xml
is standard AspectJ.

25/08/2016 12:10

Spring Framework Reference Documentation

365 de 1194

<!DOCTYPE aspectj PUBLIC "-//AspectJ//DTD//EN" "http://www.eclipse.org/aspectj/dtd/asp

Now to the Spring-specific portion of the configuration. We need to configure a

LoadTimeWeaver (all explained later, just take it on trust for now). This load-time weaver
is the essential component responsible for weaving the aspect configuration in one or
more META-INF/aop.xml files into the classes in your application. The good thing is that
it does not require a lot of configuration, as can be seen below (there are some more
options that you can specify, but these are detailed later).
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">

<bean id="entitlementCalculationService"
class="foo.StubEntitlementCalculationService"/>

<context:load-time-weaver/>
</beans>

Now that all the required artifacts are in place - the aspect, the META-INF/aop.xml file,
and the Spring configuration -, let us create a simple driver class with a main(..)
method to demonstrate the LTW in action.
package foo;

25/08/2016 12:10

Spring Framework Reference Documentation

366 de 1194

import org.springframework.context.support.ClassPathXmlApplicationContext;
public final class Main {
public static void main(String[] args) {
ApplicationContext ctx = new ClassPathXmlApplicationContext("beans.xml"

EntitlementCalculationService entitlementCalculationService
= (EntitlementCalculationService) ctx.getBean("entitlementCalculationServi
// the profiling aspect is 'woven' around this method execution
entitlementCalculationService.calculateEntitlement();
}
}

There is one last thing to do. The introduction to this section did say that one could switch
on LTW selectively on a per- ClassLoader basis with Spring, and this is true. However,
just for this example, we are going to use a Java agent (supplied with Spring) to switch on
the LTW. This is the command line we will use to run the above Main class:
java -javaagent:C:/projects/foo/lib/global/spring-instrument.jar foo.Main

The -javaagent is a flag for specifying and enabling agents to instrument programs
running on the JVM. The Spring Framework ships with such an agent, the
InstrumentationSavingAgent , which is packaged in the spring-instrument.jar
that was supplied as the value of the -javaagent argument in the above example.
The output from the execution of the Main program will look something like that below. (I
have introduced a Thread.sleep(..) statement into the calculateEntitlement()
implementation so that the profiler actually captures something other than 0 milliseconds the 01234 milliseconds is not an overhead introduced by the AOP :) )
Calculating entitlement
StopWatch 'ProfilingAspect': running time (millis) = 1234
------ ----- ---------------------------ms
%
Task name
------ ----- ---------------------------01234 100% calculateEntitlement

Since this LTW is effected using full-blown AspectJ, we are not just limited to advising
Spring beans; the following slight variation on the Main program will yield the same
result.
package foo;
import org.springframework.context.support.ClassPathXmlApplicationContext;

25/08/2016 12:10

Spring Framework Reference Documentation

367 de 1194

public final class Main {

public static void main(String[] args) {
new ClassPathXmlApplicationContext("beans.xml", Main.class);
EntitlementCalculationService entitlementCalculationService =
new StubEntitlementCalculationService();
// the profiling aspect will be 'woven' around this method execution
entitlementCalculationService.calculateEntitlement();
}
}

Notice how in the above program we are simply bootstrapping the Spring container, and
then creating a new instance of the StubEntitlementCalculationService totally
outside the context of Spring the profiling advice still gets woven in.
The example admittedly is simplistic however the basics of the LTW support in Spring
have all been introduced in the above example, and the rest of this section will explain the
'why' behind each bit of configuration and usage in detail.

The ProfilingAspect used in this example may be basic, but it is quite

useful. It is a nice example of a development-time aspect that developers
can use during development (of course), and then quite easily exclude from
builds of the application being deployed into UAT or production.

Aspects
The aspects that you use in LTW have to be AspectJ aspects. They can be written in
either the AspectJ language itself or you can write your aspects in the @AspectJ-style. It
means that your aspects are then both valid AspectJ and Spring AOP aspects.
Furthermore, the compiled aspect classes need to be available on the classpath.

'META-INF/aop.xml'
The AspectJ LTW infrastructure is configured using one or more META-INF/aop.xml
files, that are on the Java classpath (either directly, or more typically in jar files).
The structure and contents of this file is detailed in the main AspectJ reference
documentation, and the interested reader is referred to that resource. (I appreciate that
this section is brief, but the aop.xml file is 100% AspectJ - there is no Spring-specific

25/08/2016 12:10

Spring Framework Reference Documentation

368 de 1194

information or semantics that apply to it, and so there is no extra value that I can
contribute either as a result), so rather than rehash the quite satisfactory section that the
AspectJ developers wrote, I am just directing you there.)

Required libraries (JARS)

At a minimum you will need the following libraries to use the Spring Frameworks support
for AspectJ LTW:
spring-aop.jar (version 2.5 or later, plus all mandatory dependencies)
aspectjweaver.jar (version 1.6.8 or later)
If you are using the Spring-provided agent to enable instrumentation, you will also need:
spring-instrument.jar

Spring configuration
The key component in Springs LTW support is the LoadTimeWeaver interface (in the
org.springframework.instrument.classloading package), and the numerous
implementations of it that ship with the Spring distribution. A LoadTimeWeaver is
responsible for adding one or more java.lang.instrument.ClassFileTransformers
to a ClassLoader at runtime, which opens the door to all manner of interesting
applications, one of which happens to be the LTW of aspects.

If you are unfamiliar with the idea of runtime class file transformation, you
are encouraged to read the javadoc API documentation for the
java.lang.instrument package before continuing. This is not a huge
chore because there is - rather annoyingly - precious little documentation
there the key interfaces and classes will at least be laid out in front of you
for reference as you read through this section.

Configuring a LoadTimeWeaver for a particular ApplicationContext can be as easy

as adding one line. (Please note that you almost certainly will need to be using an
ApplicationContext as your Spring container - typically a BeanFactory will not be
enough because the LTW support makes use of BeanFactoryPostProcessors .)
To enable the Spring Frameworks LTW support, you need to configure a
LoadTimeWeaver , which typically is done using the @EnableLoadTimeWeaving
annotation.

25/08/2016 12:10

Spring Framework Reference Documentation

369 de 1194

@Configuration
@EnableLoadTimeWeaving
public class AppConfig {
}

Alternatively, if you prefer XML based configuration, use the

<context:load-time-weaver/> element. Note that the element is defined in the
context namespace.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<context:load-time-weaver/>
</beans>

The above configuration will define and register a number of LTW-specific infrastructure
beans for you automatically, such as a LoadTimeWeaver and an
AspectJWeavingEnabler . The default LoadTimeWeaver is the
DefaultContextLoadTimeWeaver class, which attempts to decorate an automatically
detected LoadTimeWeaver : the exact type of LoadTimeWeaver that will be
'automatically detected' is dependent upon your runtime environment (summarized in the
following table).

Table 11.1. DefaultContextLoadTimeWeaver LoadTimeWeavers

Runtime Environment

LoadTimeWeaver
implementation

Running in Oracles WebLogic

WebLogicLoadTimeWeaver

Running in Oracles GlassFish

GlassFishLoadTimeWeaver

Running in Apache Tomcat

TomcatLoadTimeWeaver

Running in Red Hats JBoss AS or

JBossLoadTimeWeaver

25/08/2016 12:10

Spring Framework Reference Documentation

370 de 1194

Runtime Environment

LoadTimeWeaver
implementation

WildFly
Running in IBMs WebSphere

WebSphereLoadTimeWeaver

JVM started with Spring

InstrumentationLoadTimeWeaver

InstrumentationSavingAgent (java
-javaagent:path/to/spring-instrument.jar)
Fallback, expecting the underlying

ReflectiveLoadTimeWeaver

ClassLoader to follow common

conventions (e.g. applicable to
TomcatInstrumentableClassLoader
and Resin)

Note that these are just the LoadTimeWeavers that are autodetected when using the
DefaultContextLoadTimeWeaver : it is of course possible to specify exactly which
LoadTimeWeaver implementation that you wish to use.
To specify a specific LoadTimeWeaver with Java configuration implement the
LoadTimeWeavingConfigurer interface and override the getLoadTimeWeaver()
method:
@Configuration
@EnableLoadTimeWeaving
public class AppConfig implements LoadTimeWeavingConfigurer {
@Override
public LoadTimeWeaver getLoadTimeWeaver() {
return new ReflectiveLoadTimeWeaver();
}
}

If you are using XML based configuration you can specify the fully-qualified classname as
the value of the weaver-class attribute on the <context:load-time-weaver/>
element:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

25/08/2016 12:10

Spring Framework Reference Documentation

371 de 1194

xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">

<context:load-time-weaver
weaver-class="org.springframework.instrument.classloading.ReflectiveLoadTi
</beans>

The LoadTimeWeaver that is defined and registered by the configuration can be later
retrieved from the Spring container using the well-known name loadTimeWeaver .
Remember that the LoadTimeWeaver exists just as a mechanism for Springs LTW
infrastructure to add one or more ClassFileTransformers . The actual
ClassFileTransformer that does the LTW is the ClassPreProcessorAgentAdapter
(from the org.aspectj.weaver.loadtime package) class. See the class-level javadocs
of the ClassPreProcessorAgentAdapter class for further details, because the specifics
of how the weaving is actually effected is beyond the scope of this section.
There is one final attribute of the configuration left to discuss: the aspectjWeaving
attribute (or aspectj-weaving if you are using XML). This is a simple attribute that
controls whether LTW is enabled or not; it is as simple as that. It accepts one of three
possible values, summarized below, with the default value being autodetect if the
attribute is not present.

Table 11.2. AspectJ weaving attribute values

Annotation

XML Value

Explanation

Value
ENABLED

AspectJ weaving is on, and aspects will be

woven at load-time as appropriate.

DISABLED

off

LTW is off no aspect will be woven at

load-time.

AUTODETECT

autodetect

If the Spring LTW infrastructure can find at least

one META-INF/aop.xml file, then AspectJ
weaving is on, else it is off. This is the default
value.

25/08/2016 12:10

Spring Framework Reference Documentation

372 de 1194

Environment-specific configuration
This last section contains any additional settings and configuration that you will need
when using Springs LTW support in environments such as application servers and web
containers.

Tomcat
Historically, Apache Tomcat's default class loader did not support class transformation
which is why Spring provides an enhanced implementation that addresses this need.
Named TomcatInstrumentableClassLoader , the loader works on Tomcat 6.0 and
above.

Do not define TomcatInstrumentableClassLoader anymore on Tomcat

8.0 and higher. Instead, let Spring automatically use Tomcats new native
InstrumentableClassLoader facility through the
TomcatLoadTimeWeaver strategy.

If you still need to use TomcatInstrumentableClassLoader , it can be registered

individually for each web application as follows:
Copy org.springframework.instrument.tomcat.jar into
$CATALINA_HOME/lib, where $CATALINA_HOME represents the root of the Tomcat
installation)
Instruct Tomcat to use the custom class loader (instead of the default) by editing the
web application context file:

<Context path="/myWebApp" docBase="/my/webApp/location">

Apache Tomcat (6.0+) supports several context locations:

server configuration file - $CATALINA_HOME/conf/server.xml
default context configuration - $CATALINA_HOME/conf/context.xml - that affects all
deployed web applications
per-web application configuration which can be deployed either on the server-side at
$CATALINA_HOME/conf/[enginename]/[hostname]/[webapp]-context.xml or
embedded inside the web-app archive at META-INF/context.xml

25/08/2016 12:10

Spring Framework Reference Documentation

373 de 1194

will impact only applications that use the custom class loader and does not require any
changes to the server configuration. See the Tomcat 6.0.x documentation for more details
about available context locations.
Alternatively, consider the use of the Spring-provided generic VM agent, to be specified in
Tomcats launch script (see above). This will make instrumentation available to all
deployed web applications, no matter what ClassLoader they happen to run on.

WebLogic, WebSphere, Resin, GlassFish, JBoss

Recent versions of WebLogic Server (version 10 and above), IBM WebSphere
Application Server (version 7 and above), Resin (3.1 and above) and JBoss (6.x or
above) provide a ClassLoader that is capable of local instrumentation. Springs native
LTW leverages such ClassLoaders to enable AspectJ weaving. You can enable LTW by
simply activating load-time weaving as described earlier. Specifically, you do not need to
modify the launch script to add -javaagent:path/to/spring-instrument.jar .
Note that GlassFish instrumentation-capable ClassLoader is available only in its EAR
environment. For GlassFish web applications, follow the Tomcat setup instructions as
outlined above.
Note that on JBoss 6.x, the app server scanning needs to be disabled to prevent it from
loading the classes before the application actually starts. A quick workaround is to add to
your artifact a file named WEB-INF/jboss-scanning.xml with the following content:
<scanning xmlns="urn:jboss:scanning:1.0"/>

Generic Java applications

When class instrumentation is required in environments that do not support or are not
supported by the existing LoadTimeWeaver implementations, a JDK agent can be the
only solution. For such cases, Spring provides InstrumentationLoadTimeWeaver ,
which requires a Spring-specific (but very general) VM agent,
org.springframework.instrument-{version}.jar (previously named
spring-agent.jar ).
To use it, you must start the virtual machine with the Spring agent, by supplying the
following JVM options:
-javaagent:/path/to/org.springframework.instrument-{version}.jar

Note that this requires modification of the VM launch script which may prevent you from
using this in application server environments (depending on your operation policies).

25/08/2016 12:10

Spring Framework Reference Documentation

374 de 1194

Additionally, the JDK agent will instrument the entire VM which can prove expensive.
For performance reasons, it is recommended to use this configuration only if your target
environment (such as Jetty) does not have (or does not support) a dedicated LTW.

11.9 Further Resources

More information on AspectJ can be found on the AspectJ website.
The book Eclipse AspectJ by Adrian Colyer et. al. (Addison-Wesley, 2005) provides a
comprehensive introduction and reference for the AspectJ language.
The book AspectJ in Action, Second Edition by Ramnivas Laddad (Manning, 2009)
comes highly recommended; the focus of the book is on AspectJ, but a lot of general
AOP themes are explored (in some depth).

12. Spring AOP APIs

12.1 Introduction
The previous chapter described the Springs support for AOP using @AspectJ and
schema-based aspect definitions. In this chapter 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 and later AOP support described in the previous
chapter, but when working with existing applications, or when reading books and articles,
you may come across Spring 1.2 style examples. Spring 4.0 is backwards compatible
with Spring 1.2 and everything described in this chapter is fully supported in Spring 4.0.

12.2 Pointcut API in Spring

Lets look at how Spring handles the crucial pointcut concept.

12.2.1 Concepts
Springs pointcut model enables pointcut reuse independent of advice types. Its possible
to target different advice using the same pointcut.
The org.springframework.aop.Pointcut interface is the central interface, used to

25/08/2016 12:10

Spring Framework Reference Documentation

375 de 1194

public interface Pointcut {

ClassFilter getClassFilter();
MethodMatcher getMethodMatcher();
}

Splitting the Pointcut interface into two parts allows reuse of class and method
matching parts, and fine-grained composition operations (such as performing a "union"
with another method matcher).
The ClassFilter interface is used to restrict the pointcut to a given set of target
classes. If the matches() method always returns true, all target classes will be matched:
public interface ClassFilter {
boolean matches(Class clazz);
}

The MethodMatcher interface is normally more important. The complete interface is

shown below:
public interface MethodMatcher {
boolean matches(Method m, Class targetClass);
boolean isRuntime();
boolean matches(Method m, Class targetClass, Object[] args);
}

The matches(Method, Class) method is used to test whether this pointcut will ever
match a given method on a target class. This evaluation can be performed when an AOP
proxy is created, to avoid the need for a test on every method invocation. If the
2-argument matches method returns true for a given method, and the isRuntime()
method for the MethodMatcher returns true, the 3-argument matches method will be
invoked on every method invocation. This enables a pointcut to look at the arguments
passed to the method invocation immediately before the target advice is to execute.
Most MethodMatchers are static, meaning that their isRuntime() method returns false.
In this case, the 3-argument matches method will never be invoked.

25/08/2016 12:10

Spring Framework Reference Documentation

376 de 1194

If possible, try to make pointcuts static, allowing the AOP framework to

cache the results of pointcut evaluation when an AOP proxy is created.

12.2.2 Operations on pointcuts

Spring supports operations on pointcuts: notably, union and intersection.
Union means the methods that either pointcut matches.
Intersection means the methods that both pointcuts match.
Union is usually more useful.
Pointcuts can be composed using the static methods in the
org.springframework.aop.support.Pointcuts class, or using the ComposablePointcut
class in the same package. However, using AspectJ pointcut expressions is usually a
simpler approach.

12.2.3 AspectJ expression pointcuts

Since 2.0, the most important type of pointcut used by Spring is
org.springframework.aop.aspectj.AspectJExpressionPointcut . This is a
pointcut that uses an AspectJ supplied library to parse an AspectJ pointcut expression
string.
See the previous chapter for a discussion of supported AspectJ pointcut primitives.

12.2.4 Convenience pointcut implementations

Spring provides several convenient pointcut implementations. Some can be used out of
the box; others are intended to be subclassed in application-specific pointcuts.

Static pointcuts
Static pointcuts are based on method and target class, and cannot take into account the
methods arguments. Static pointcuts are sufficient - and best - for most usages. Its
possible for Spring to evaluate a static pointcut only once, when a method is first invoked:
after that, there is no need to evaluate the pointcut again with each method invocation.
Lets consider some static pointcut implementations included with Spring.

Regular expression pointcuts

25/08/2016 12:10

Spring Framework Reference Documentation

377 de 1194

One obvious way to specify static pointcuts is regular expressions. Several AOP
frameworks besides Spring make this possible.
org.springframework.aop.support.JdkRegexpMethodPointcut is a generic regular
expression pointcut, using the regular expression support in JDK 1.4+.
Using the JdkRegexpMethodPointcut class, you can provide a list of pattern Strings. If
any of these is a match, the pointcut will evaluate to true. (So the result is effectively the
union of these pointcuts.)
The usage is shown below:
<bean id="settersAndAbsquatulatePointcut"
class="org.springframework.aop.support.JdkRegexpMethodPointcut">
<property name="patterns">
<list>
<value>.*set.*</value>
<value>.*absquatulate</value>
</list>
</property>
</bean>

Spring provides a convenience class, RegexpMethodPointcutAdvisor , that allows us

to also reference an Advice (remember that an Advice can be an interceptor, before
advice, throws advice etc.). Behind the scenes, Spring will use a
JdkRegexpMethodPointcut . Using RegexpMethodPointcutAdvisor simplifies wiring,
as the one bean encapsulates both pointcut and advice, as shown below:
<bean id="settersAndAbsquatulateAdvisor"
class="org.springframework.aop.support.RegexpMethodPointcutAdvisor">
<property name="advice">
<ref bean="beanNameOfAopAllianceInterceptor"/>
</property>
<property name="patterns">
<list>
<value>.*set.*</value>
<value>.*absquatulate</value>
</list>
</property>
</bean>

RegexpMethodPointcutAdvisor can be used with any Advice type.

Attribute-driven pointcuts
An important type of static pointcut is a metadata-driven pointcut. This uses the values of

25/08/2016 12:10

Spring Framework Reference Documentation

378 de 1194

metadata attributes: typically, source-level metadata.

Dynamic pointcuts
Dynamic pointcuts are costlier to evaluate than static pointcuts. They take into account
method arguments, as well as static information. This means that they must be evaluated
with every method invocation; the result cannot be cached, as arguments will vary.
The main example is the control flow pointcut.

Control flow pointcuts

Spring control flow pointcuts are conceptually similar to AspectJ cflow pointcuts, although
less powerful. (There is currently no way to specify that a pointcut executes below a join
point matched by another pointcut.) A control flow pointcut matches the current call stack.
For example, it might fire if the join point was invoked by a method in the
com.mycompany.web package, or by the SomeCaller class. Control flow pointcuts are
specified using the org.springframework.aop.support.ControlFlowPointcut
class.

Control flow pointcuts are significantly more expensive to evaluate at

runtime than even other dynamic pointcuts. In Java 1.4, the cost is about 5
times that of other dynamic pointcuts.

12.2.5 Pointcut superclasses

Spring provides useful pointcut superclasses to help you to implement your own
pointcuts.
Because static pointcuts are most useful, youll probably subclass
StaticMethodMatcherPointcut, as shown below. This requires implementing just one
abstract method (although its possible to override other methods to customize behavior):
class TestStaticPointcut extends StaticMethodMatcherPointcut {
public boolean matches(Method m, Class targetClass) {
// return true if custom criteria match
}
}

There are also superclasses for dynamic pointcuts.

25/08/2016 12:10

Spring Framework Reference Documentation

379 de 1194

You can use custom pointcuts with any advice type in Spring 1.0 RC2 and above.

12.2.6 Custom pointcuts

Because pointcuts in Spring AOP are Java classes, rather than language features (as in
AspectJ) its possible to declare custom pointcuts, whether static or dynamic. Custom
pointcuts in Spring can be arbitrarily complex. However, using the AspectJ pointcut
expression language is recommended if possible.

Later versions of Spring may offer support for "semantic pointcuts" as

offered by JAC: for example, "all methods that change instance variables in
the target object."

12.3 Advice API in Spring

Lets now look at how Spring AOP handles advice.

12.3.1 Advice lifecycles

Each advice is a Spring bean. An advice instance can be shared across all advised
objects, or unique to each advised object. This corresponds to per-class or per-instance
advice.
Per-class advice is used most often. It is appropriate for generic advice such as
transaction advisors. These do not depend on the state of the proxied object or add new
state; they merely act on the method and arguments.
Per-instance advice is appropriate for introductions, to support mixins. In this case, the
advice adds state to the proxied object.
Its possible to use a mix of shared and per-instance advice in the same AOP proxy.

12.3.2 Advice types in Spring

Spring provides several advice types out of the box, and is extensible to support arbitrary
advice types. Let us look at the basic concepts and standard advice types.

Interception around advice

25/08/2016 12:10

Spring Framework Reference Documentation

380 de 1194

The most fundamental advice type in Spring is interception around advice.

Spring is compliant with the AOP Alliance interface for around advice using method
interception. MethodInterceptors implementing around advice should implement the
following interface:
public interface MethodInterceptor extends Interceptor {
Object invoke(MethodInvocation invocation) throws Throwable;
}

The MethodInvocation argument to the invoke() method exposes the method being
invoked; the target join point; the AOP proxy; and the arguments to the method. The
invoke() method should return the invocations result: the return value of the join point.
A simple MethodInterceptor implementation looks as follows:
public class DebugInterceptor implements MethodInterceptor {
public Object invoke(MethodInvocation invocation) throws Throwable {
System.out.println("Before: invocation=[" + invocation + "]");
Object rval = invocation.proceed();
System.out.println("Invocation returned");
return rval;
}
}

Note the call to the MethodInvocations proceed() method. This proceeds down the
interceptor chain towards the join point. Most interceptors will invoke this method, and
return its return value. However, a MethodInterceptor, like any around advice, can return
a different value or throw an exception rather than invoke the proceed method. However,
you dont want to do this without good reason!

MethodInterceptors offer interoperability with other AOP Alliance-compliant

AOP implementations. The other advice types discussed in the remainder
of this section implement common AOP concepts, but in a Spring-specific
way. While there is an advantage in using the most specific advice type,
stick with MethodInterceptor around advice if you are likely to want to run
the aspect in another AOP framework. Note that pointcuts are not currently
interoperable between frameworks, and the AOP Alliance does not currently
define pointcut interfaces.

25/08/2016 12:10

Spring Framework Reference Documentation

381 de 1194

Before advice
A simpler advice type is a before advice. This does not need a MethodInvocation
object, since it will only be called before entering the method.
The main advantage of a before advice is that there is no need to invoke the proceed()
method, and therefore no possibility of inadvertently failing to proceed down the
interceptor chain.
The MethodBeforeAdvice interface is shown below. (Springs API design would allow
for field before advice, although the usual objects apply to field interception and its
unlikely that Spring will ever implement it).
public interface MethodBeforeAdvice extends BeforeAdvice {
void before(Method m, Object[] args, Object target) throws Throwable;
}

Note the return type is void . Before advice can insert custom behavior before the join
point executes, but cannot change the return value. If a before advice throws an
exception, this will abort further execution of the interceptor chain. The exception will
propagate back up the interceptor chain. If it is unchecked, or on the signature of the
invoked method, it will be passed directly to the client; otherwise it will be wrapped in an
unchecked exception by the AOP proxy.
An example of a before advice in Spring, which counts all method invocations:
public class CountingBeforeAdvice implements MethodBeforeAdvice {
private int count;
public void before(Method m, Object[] args, Object target) throws Throwable {
++count;
}
public int getCount() {
return count;
}
}

Before advice can be used with any pointcut.

Throws advice

25/08/2016 12:10

Spring Framework Reference Documentation

382 de 1194

Throws advice is invoked after the return of the join point if the join point threw an
exception. Spring offers typed throws advice. Note that this means that the
org.springframework.aop.ThrowsAdvice interface does not contain any methods: It
is a tag interface identifying that the given object implements one or more typed throws
advice methods. These should be in the form of:
afterThrowing([Method, args, target], subclassOfThrowable)

Only the last argument is required. The method signatures may have either one or four
arguments, depending on whether the advice method is interested in the method and
arguments. The following classes are examples of throws advice.
The advice below is invoked if a RemoteException is thrown (including subclasses):
public class RemoteThrowsAdvice implements ThrowsAdvice {
public void afterThrowing(RemoteException ex) throws Throwable {
// Do something with remote exception
}
}

The following advice is invoked if a ServletException is thrown. Unlike the above

advice, it declares 4 arguments, so that it has access to the invoked method, method
arguments and target object:
public class ServletThrowsAdviceWithArguments implements ThrowsAdvice {

public void afterThrowing(Method m, Object[] args, Object target, ServletException

// Do something with all arguments
}
}

The final example illustrates how these two methods could be used in a single class,
which handles both RemoteException and ServletException . Any number of throws
advice methods can be combined in a single class.
public static class CombinedThrowsAdvice implements ThrowsAdvice {
public void afterThrowing(RemoteException ex) throws Throwable {
// Do something with remote exception
}

public void afterThrowing(Method m, Object[] args, Object target, ServletException

// Do something with all arguments
}

25/08/2016 12:10

Spring Framework Reference Documentation

383 de 1194

If a throws-advice method throws an exception itself, it will override the

original exception (i.e. change the exception thrown to the user). The
overriding exception will typically be a RuntimeException; this is compatible
with any method signature. However, if a throws-advice method throws a
checked exception, it will have to match the declared exceptions of the
target method and is hence to some degree coupled to specific target
method signatures. Do not throw an undeclared checked exception that is
incompatible with the target methods signature!

Throws advice can be used with any pointcut.

After Returning advice

An after returning advice in Spring must implement the
org.springframework.aop.AfterReturningAdvice interface, shown below:
public interface AfterReturningAdvice extends Advice {
void afterReturning(Object returnValue, Method m, Object[] args, Object target)
throws Throwable;
}

An after returning advice has access to the return value (which it cannot modify), invoked
method, methods arguments and target.
The following after returning advice counts all successful method invocations that have
not thrown exceptions:
public class CountingAfterReturningAdvice implements AfterReturningAdvice {
private int count;

public void afterReturning(Object returnValue, Method m, Object[] args, Object tar

throws Throwable {
++count;
}
public int getCount() {
return count;

25/08/2016 12:10

Spring Framework Reference Documentation

384 de 1194

}
}

This advice doesnt change the execution path. If it throws an exception, this will be
thrown up the interceptor chain instead of the return value.

After returning advice can be used with any pointcut.

Introduction advice
Spring treats introduction advice as a special kind of interception advice.
Introduction requires an IntroductionAdvisor , and an IntroductionInterceptor ,
implementing the following interface:
public interface IntroductionInterceptor extends MethodInterceptor {
boolean implementsInterface(Class intf);
}

The invoke() method inherited from the AOP Alliance MethodInterceptor interface
must implement the introduction: that is, if the invoked method is on an introduced
interface, the introduction interceptor is responsible for handling the method call - it
cannot invoke proceed() .
Introduction advice cannot be used with any pointcut, as it applies only at class, rather
than method, level. You can only use introduction advice with the
IntroductionAdvisor , which has the following methods:
public interface IntroductionAdvisor extends Advisor, IntroductionInfo {
ClassFilter getClassFilter();
void validateInterfaces() throws IllegalArgumentException;
}
public interface IntroductionInfo {
Class[] getInterfaces();
}

There is no MethodMatcher , and hence no Pointcut , associated with introduction

advice. Only class filtering is logical.

25/08/2016 12:10

Spring Framework Reference Documentation

385 de 1194

The getInterfaces() method returns the interfaces introduced by this advisor.

The validateInterfaces() method is used internally to see whether or not the
introduced interfaces can be implemented by the configured
IntroductionInterceptor .
Lets look at a simple example from the Spring test suite. Lets suppose we want to
introduce the following interface to one or more objects:
public interface Lockable {
void lock();
void unlock();
boolean locked();
}

This illustrates a mixin. We want to be able to cast advised objects to Lockable, whatever
their type, and call lock and unlock methods. If we call the lock() method, we want all
setter methods to throw a LockedException . Thus we can add an aspect that provides
the ability to make objects immutable, without them having any knowledge of it: a good
example of AOP.
Firstly, well need an IntroductionInterceptor that does the heavy lifting. In this
case, we extend the
org.springframework.aop.support.DelegatingIntroductionInterceptor
convenience class. We could implement IntroductionInterceptor directly, but using
DelegatingIntroductionInterceptor is best for most cases.
The DelegatingIntroductionInterceptor is designed to delegate an introduction to
an actual implementation of the introduced interface(s), concealing the use of interception
to do so. The delegate can be set to any object using a constructor argument; the default
delegate (when the no-arg constructor is used) is this. Thus in the example below, the
delegate is the LockMixin subclass of DelegatingIntroductionInterceptor . Given
a delegate (by default itself), a DelegatingIntroductionInterceptor instance looks
for all interfaces implemented by the delegate (other than IntroductionInterceptor), and
will support introductions against any of them. Its possible for subclasses such as
LockMixin to call the suppressInterface(Class intf) method to suppress
interfaces that should not be exposed. However, no matter how many interfaces an
IntroductionInterceptor is prepared to support, the IntroductionAdvisor used
will control which interfaces are actually exposed. An introduced interface will conceal any
implementation of the same interface by the target.
Thus LockMixin extends DelegatingIntroductionInterceptor and implements

25/08/2016 12:10

Spring Framework Reference Documentation

386 de 1194

for introduction, so we dont need to specify that. We could introduce any number of
interfaces in this way.
Note the use of the locked instance variable. This effectively adds additional state to
that held in the target object.

public class LockMixin extends DelegatingIntroductionInterceptor implements Lockable {

private boolean locked;
public void lock() {
this.locked = true;
}
public void unlock() {
this.locked = false;
}
public boolean locked() {
return this.locked;
}
public Object invoke(MethodInvocation invocation) throws Throwable {
if (locked() && invocation.getMethod().getName().indexOf("set") == 0
throw new LockedException();
}
return super.invoke(invocation);
}
}

Often it isnt necessary to override the invoke() method: the

DelegatingIntroductionInterceptor implementation - which calls the delegate
method if the method is introduced, otherwise proceeds towards the join point - is usually
sufficient. In the present case, we need to add a check: no setter method can be invoked
if in locked mode.
The introduction advisor required is simple. All it needs to do is hold a distinct
LockMixin instance, and specify the introduced interfaces - in this case, just Lockable .
A more complex example might take a reference to the introduction interceptor (which
would be defined as a prototype): in this case, theres no configuration relevant for a
LockMixin , so we simply create it using new .
public class LockMixinAdvisor extends DefaultIntroductionAdvisor {

25/08/2016 12:10

Spring Framework Reference Documentation

387 de 1194

public LockMixinAdvisor() {
super(new LockMixin(), Lockable.class);
}
}

We can apply this advisor very simply: it requires no configuration. (However, it is

necessary: Its impossible to use an IntroductionInterceptor without an
IntroductionAdvisor.) As usual with introductions, the advisor must be per-instance, as it is
stateful. We need a different instance of LockMixinAdvisor , and hence LockMixin ,
for each advised object. The advisor comprises part of the advised objects state.
We can apply this advisor programmatically, using the Advised.addAdvisor() method,
or (the recommended way) in XML configuration, like any other advisor. All proxy creation
choices discussed below, including "auto proxy creators," correctly handle introductions
and stateful mixins.

12.4 Advisor API in Spring

In Spring, an Advisor is an aspect that contains just a single advice object associated with
a pointcut expression.
Apart from the special case of introductions, any advisor can be used with any advice.
org.springframework.aop.support.DefaultPointcutAdvisor is the most
commonly used advisor class. For example, it can be used with a MethodInterceptor ,
BeforeAdvice or ThrowsAdvice .
It is possible to mix advisor and advice types in Spring in the same AOP proxy. For
example, you could use a interception around advice, throws advice and before advice in
one proxy configuration: Spring will automatically create the necessary interceptor chain.

12.5 Using the ProxyFactoryBean to create AOP

proxies
If youre using the Spring IoC container (an ApplicationContext or BeanFactory) for your
business objects - and you should be! - you will want to use one of Springs AOP
FactoryBeans. (Remember that a factory bean introduces a layer of indirection, enabling
it to create objects of a different type.)

The Spring AOP support also uses factory beans under the covers.

25/08/2016 12:10

Spring Framework Reference Documentation

388 de 1194

The basic way to create an AOP proxy in Spring is to use the

org.springframework.aop.framework.ProxyFactoryBean. This gives complete control over
the pointcuts and advice that will apply, and their ordering. However, there are simpler
options that are preferable if you dont need such control.

12.5.1 Basics
The ProxyFactoryBean , like other Spring FactoryBean implementations, introduces a
level of indirection. If you define a ProxyFactoryBean with name foo , what objects
referencing foo see is not the ProxyFactoryBean instance itself, but an object created
by the ProxyFactoryBeans implementation of the `getObject() method. This
method will create an AOP proxy wrapping a target object.
One of the most important benefits of using a ProxyFactoryBean or another IoC-aware
class to create AOP proxies, is that it means that advices and pointcuts can also be
managed by IoC. This is a powerful feature, enabling certain approaches that are hard to
achieve with other AOP frameworks. For example, an advice may itself reference
application objects (besides the target, which should be available in any AOP framework),
benefiting from all the pluggability provided by Dependency Injection.

12.5.2 JavaBean properties

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 Section 12.5.3, JDK- and
CGLIB-based proxies).
Some key properties are inherited from
org.springframework.aop.framework.ProxyConfig (the superclass for all AOP
proxy factories in Spring). These key properties include:
proxyTargetClass : true if the target class is to be proxied, rather than the target
class' interfaces. If this property value is set to true , then CGLIB proxies will be
created (but see also Section 12.5.3, JDK- and CGLIB-based proxies).
optimize : controls whether or not aggressive optimizations are applied to proxies
created via CGLIB. One should not blithely use this setting unless one fully
understands how the relevant AOP proxy handles optimization. This is currently used
only for CGLIB proxies; it has no effect with JDK dynamic proxies.

25/08/2016 12:10

Spring Framework Reference Documentation

389 de 1194

no longer allowed. This is useful both as a slight optimization and for those cases
when you dont want callers to be able to manipulate the proxy (via the Advised
interface) after the proxy has been created. The default value of this property is
false , so changes such as adding additional advice are allowed.
exposeProxy : determines whether or not the current proxy should be exposed in a
ThreadLocal so that it can be accessed by the target. If a target needs to obtain the
proxy and the exposeProxy property is set to true , the target can use the
AopContext.currentProxy() method.
Other properties specific to ProxyFactoryBean include:
proxyInterfaces : array of String interface names. If this isnt supplied, a CGLIB
proxy for the target class will be used (but see also Section 12.5.3, JDK- and
CGLIB-based proxies).
interceptorNames : String array of Advisor , interceptor or other advice names to
apply. Ordering is significant, on a first come-first served basis. That is to say that the
first interceptor in the list will be the first to be able to intercept the invocation.
The names are bean names in the current factory, including bean names from ancestor
factories. You cant mention bean references here since doing so would result in the
ProxyFactoryBean ignoring the singleton setting of the advice.
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 Section 12.5.6, Using 'global'
advisors.
singleton: whether or not the factory should return a single object, no matter how
often the getObject() method is called. Several FactoryBean implementations
offer such a method. The default value is true . If you want to use stateful advice for example, for stateful mixins - use prototype advices along with a singleton value of
false .

12.5.3 JDK- and CGLIB-based proxies

This section serves as the definitive documentation on how the ProxyFactoryBean
chooses to create one of either a JDK- and CGLIB-based proxy for a particular target
object (that is to be proxied).

The behavior of the ProxyFactoryBean with regard to creating JDK- or

25/08/2016 12:10

Spring Framework Reference Documentation

390 de 1194

The ProxyFactoryBean now exhibits similar semantics with regard to

auto-detecting interfaces as those of the TransactionProxyFactoryBean
class.

If the class of a target object that is to be proxied (hereafter simply referred to as the
target class) doesnt implement any interfaces, then a CGLIB-based proxy will be created.
This is the easiest scenario, because JDK proxies are interface based, and no interfaces
means JDK proxying isnt even possible. One simply plugs in the target bean, and
specifies the list of interceptors via the interceptorNames property. Note that a
CGLIB-based proxy will be created even if the proxyTargetClass property of the
ProxyFactoryBean has been set to false . (Obviously this makes no sense, and is
best removed from the bean definition because it is at best redundant, and at worst
confusing.)
If the target class implements one (or more) interfaces, then the type of proxy that is
created depends on the configuration of the ProxyFactoryBean .
If the proxyTargetClass property of the ProxyFactoryBean has been set to true ,
then a CGLIB-based proxy will be created. This makes sense, and is in keeping with the
principle of least surprise. Even if the proxyInterfaces property of the
ProxyFactoryBean has been set to one or more fully qualified interface names, the fact
that the proxyTargetClass property is set to true will cause CGLIB-based proxying to
be in effect.
If the proxyInterfaces property of the ProxyFactoryBean has been set to one or
more fully qualified interface names, then a JDK-based proxy will be created. The created
proxy will implement all of the interfaces that were specified in the proxyInterfaces
property; if the target class happens to implement a whole lot more interfaces than those
specified in the proxyInterfaces property, that is all well and good but those additional
interfaces will not be implemented by the returned proxy.
If the proxyInterfaces property of the ProxyFactoryBean has not been set, but the
target class does implement one (or more) interfaces, then the ProxyFactoryBean will
auto-detect the fact that the target class does actually implement at least one interface,
and a JDK-based proxy will be created. The interfaces that are actually proxied will be all
of the interfaces that the target class implements; in effect, this is the same as simply
supplying a list of each and every interface that the target class implements to the
proxyInterfaces property. However, it is significantly less work, and less prone to
typos.

25/08/2016 12:10

Spring Framework Reference Documentation

391 de 1194

12.5.4 Proxying interfaces

Lets look at a simple example of ProxyFactoryBean in action. This example involves:
A target bean that will be proxied. This is the "personTarget" bean definition in the
example below.
An Advisor and an Interceptor used to provide advice.
An AOP proxy bean definition specifying the target object (the personTarget bean)
and the interfaces to proxy, along with the advices to apply.
<bean id="personTarget" class="com.mycompany.PersonImpl">
<property name="name" value="Tony"/>
<property name="age" value="51"/>
</bean>
<bean id="myAdvisor" class="com.mycompany.MyAdvisor">
<property name="someProperty" value="Custom string property value"/>
</bean>

<bean id="debugInterceptor" class="org.springframework.aop.interceptor.DebugIntercepto

</bean>
<bean id="person"
class="org.springframework.aop.framework.ProxyFactoryBean">
<property name="proxyInterfaces" value="com.mycompany.Person"/>
<property name="target" ref="personTarget"/>
<property name="interceptorNames">
<list>
<value>myAdvisor</value>
<value>debugInterceptor</value>
</list>
</property>
</bean>

Note that the interceptorNames property takes a list of String: the bean names of the
interceptor or advisors in the current factory. Advisors, interceptors, before, after returning
and throws advice objects can be used. The ordering of advisors is significant.

You might be wondering why the list doesnt hold bean references. The
reason for this is that if the ProxyFactoryBeans singleton property is set to
false, it must be able to return independent proxy instances. If any of the
advisors is itself a prototype, an independent instance would need to be
returned, so its necessary to be able to obtain an instance of the prototype

25/08/2016 12:10

Spring Framework Reference Documentation

392 de 1194

from the factory; holding a reference isnt sufficient.

The "person" bean definition above can be used in place of a Person implementation, as
follows:
Person person = (Person) factory.getBean("person");

Other beans in the same IoC context can express a strongly typed dependency on it, as
with an ordinary Java object:
<bean id="personUser" class="com.mycompany.PersonUser">
<property name="person"><ref bean="person"/></property>
</bean>

The PersonUser class in this example would expose a property of type Person. As far
as its concerned, the AOP proxy can be used transparently in place of a "real" person
implementation. However, its class would be a dynamic proxy class. It would be possible
to cast it to the Advised interface (discussed below).
Its possible to conceal the distinction between target and proxy using an anonymous
inner bean, as follows. Only the ProxyFactoryBean definition is different; the advice is
included only for completeness:
<bean id="myAdvisor" class="com.mycompany.MyAdvisor">
<property name="someProperty" value="Custom string property value"/>
</bean>

<bean id="debugInterceptor" class="org.springframework.aop.interceptor.DebugIntercepto

<bean id="person" class="org.springframework.aop.framework.ProxyFactoryBean"
<property name="proxyInterfaces" value="com.mycompany.Person"/>

<property name="target">
<bean class="com.mycompany.PersonImpl">
<property name="name" value="Tony"/>
<property name="age" value="51"/>
</bean>
</property>
<property name="interceptorNames">
<list>
<value>myAdvisor</value>
<value>debugInterceptor</value>
</list>
</property>

25/08/2016 12:10

Spring Framework Reference Documentation

393 de 1194

This has the advantage that theres only one object of type Person : useful if we want to
prevent users of the application context from obtaining a reference to the un-advised
object, or need to avoid any ambiguity with Spring IoC autowiring. Theres also arguably
an advantage in that the ProxyFactoryBean definition is self-contained. However, there
are times when being able to obtain the un-advised target from the factory might actually
be an advantage: for example, in certain test scenarios.

12.5.5 Proxying classes

What if you need to proxy a class, rather than one or more interfaces?
Imagine that in our example above, there was no Person interface: we needed to advise
a class called Person that didnt implement any business interface. In this case, you can
configure Spring to use CGLIB proxying, rather than dynamic proxies. Simply set the
proxyTargetClass property on the ProxyFactoryBean above to true. While its best to
program to interfaces, rather than classes, the ability to advise classes that dont
implement interfaces can be useful when working with legacy code. (In general, Spring
isnt prescriptive. While it makes it easy to apply good practices, it avoids forcing a
particular approach.)
If you want to, you can force the use of CGLIB in any case, even if you do have
interfaces.
CGLIB proxying works by generating a subclass of the target class at runtime. Spring
configures this generated subclass to delegate method calls to the original target: the
subclass is used to implement the Decorator pattern, weaving in the advice.
CGLIB proxying should generally be transparent to users. However, there are some
issues to consider:
Final methods cant be advised, as they cant be overridden.
There is no need to add CGLIB to your classpath. As of Spring 3.2, CGLIB is
repackaged and included in the spring-core JAR. In other words, CGLIB-based AOP
will work "out of the box" just as do JDK dynamic proxies.
Theres little performance difference between CGLIB proxying and dynamic proxies. As of
Spring 1.0, dynamic proxies are slightly faster. However, this may change in the future.
Performance should not be a decisive consideration in this case.

12.5.6 Using 'global' advisors

25/08/2016 12:10

Spring Framework Reference Documentation

394 de 1194

the part before the asterisk, will be added to the advisor chain. This can come in handy if
you need to add a standard set of 'global' advisors:
<bean id="proxy" class="org.springframework.aop.framework.ProxyFactoryBean">
<property name="target" ref="service"/>
<property name="interceptorNames">
<list>
<value>global*</value>
</list>
</property>
</bean>

<bean id="global_debug" class="org.springframework.aop.interceptor.DebugInterceptor"

<bean id="global_performance" class="org.springframework.aop.interceptor.PerformanceMo

12.6 Concise proxy definitions

Especially when defining transactional proxies, you may end up with many similar proxy
definitions. The use of parent and child bean definitions, along with inner bean definitions,
can result in much cleaner and more concise proxy definitions.
First a parent, template, bean definition is created for the proxy:

<bean id="txProxyTemplate" abstract="true"

class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean
<property name="transactionManager" ref="transactionManager"/>
<property name="transactionAttributes">
<props>
<prop key="*">PROPAGATION_REQUIRED</prop>
</props>
</property>
</bean>

This will never be instantiated itself, so may actually be incomplete. Then each proxy
which needs to be created is just a child bean definition, which wraps the target of the
proxy as an inner bean definition, since the target will never be used on its own anyway.
<bean id="myService" parent="txProxyTemplate">
<property name="target">
<bean class="org.springframework.samples.MyServiceImpl">
</bean>
</property>
</bean>

25/08/2016 12:10

Spring Framework Reference Documentation

395 de 1194

case, the transaction propagation settings:

<bean id="mySpecialService" parent="txProxyTemplate">
<property name="target">
<bean class="org.springframework.samples.MySpecialServiceImpl">
</bean>
</property>
<property name="transactionAttributes">
<props>
<prop key="get*">PROPAGATION_REQUIRED,readOnly</prop>
<prop key="find*">PROPAGATION_REQUIRED,readOnly</prop>
<prop key="load*">PROPAGATION_REQUIRED,readOnly</prop>
<prop key="store*">PROPAGATION_REQUIRED</prop>
</props>
</property>
</bean>

Note that in the example above, we have explicitly marked the parent bean definition as
abstract by using the abstract attribute, as described previously, so that it may not actually
ever be instantiated. Application contexts (but not simple bean factories) will by default
pre-instantiate all singletons. It is therefore important (at least for singleton beans) that if
you have a (parent) bean definition which you intend to use only as a template, and this
definition specifies a class, you must make sure to set the abstract attribute to true,
otherwise the application context will actually try to pre-instantiate it.

12.7 Creating AOP proxies programmatically with the

ProxyFactory
Its easy to create AOP proxies programmatically using Spring. This enables you to use
Spring AOP without dependency on Spring IoC.
The following listing shows creation of a proxy for a target object, with one interceptor and
one advisor. The interfaces implemented by the target object will automatically be
proxied:
ProxyFactory factory = new ProxyFactory(myBusinessInterfaceImpl);
factory.addAdvice(myMethodInterceptor);
factory.addAdvisor(myAdvisor);
MyBusinessInterface tb = (MyBusinessInterface) factory.getProxy();

The first step is to construct an object of type

org.springframework.aop.framework.ProxyFactory . You can create this with a
target object, as in the above example, or specify the interfaces to be proxied in an

25/08/2016 12:10

Spring Framework Reference Documentation

396 de 1194

alternate constructor.
You can add advices (with interceptors as a specialized kind of advice) and/or advisors,
and manipulate them for the life of the ProxyFactory. If you add an
IntroductionInterceptionAroundAdvisor, you can cause the proxy to implement additional
interfaces.
There are also convenience methods on ProxyFactory (inherited from AdvisedSupport )
which allow you to add other advice types such as before and throws advice.
AdvisedSupport is the superclass of both ProxyFactory and ProxyFactoryBean.

Integrating AOP proxy creation with the IoC framework is best practice in
most applications. We recommend that you externalize configuration from
Java code with AOP, as in general.

12.8 Manipulating advised objects

However you create AOP proxies, you can manipulate them using the
org.springframework.aop.framework.Advised interface. Any AOP proxy can be
cast to this interface, whichever other interfaces it implements. This interface includes the
following methods:
Advisor[] getAdvisors();
void addAdvice(Advice advice) throws AopConfigException;
void addAdvice(int pos, Advice advice) throws AopConfigException;
void addAdvisor(Advisor advisor) throws AopConfigException;
void addAdvisor(int pos, Advisor advisor) throws AopConfigException;
int indexOf(Advisor advisor);
boolean removeAdvisor(Advisor advisor) throws AopConfigException;
void removeAdvisor(int index) throws AopConfigException;
boolean replaceAdvisor(Advisor a, Advisor b) throws AopConfigException;
boolean isFrozen();

25/08/2016 12:10

Spring Framework Reference Documentation

397 de 1194

advice type that has been added to the factory. If you added an Advisor, the returned
advisor at this index will be the object that you added. If you added an interceptor or other
advice type, Spring will have wrapped this in an advisor with a pointcut that always
returns true. Thus if you added a MethodInterceptor , the advisor returned for this
index will be an DefaultPointcutAdvisor returning your MethodInterceptor and a
pointcut that matches all classes and methods.
The addAdvisor() methods can be used to add any Advisor. Usually the advisor
holding pointcut and advice will be the generic DefaultPointcutAdvisor , which can be
used with any advice or pointcut (but not for introductions).
By default, its possible to add or remove advisors or interceptors even once a proxy has
been created. The only restriction is that its impossible to add or remove an introduction
advisor, as existing proxies from the factory will not show the interface change. (You can
obtain a new proxy from the factory to avoid this problem.)
A simple example of casting an AOP proxy to the Advised interface and examining and
manipulating its advice:
Advised advised = (Advised) myObject;
Advisor[] advisors = advised.getAdvisors();
int oldAdvisorCount = advisors.length;
System.out.println(oldAdvisorCount + " advisors");
// Add an advice like an interceptor without a pointcut
// Will match all proxied methods
// Can use for interceptors, before, after returning or throws advice
advised.addAdvice(new DebugInterceptor());
// Add selective advice using a pointcut
advised.addAdvisor(new DefaultPointcutAdvisor(mySpecialPointcut, myAdvice));

assertEquals("Added two advisors", oldAdvisorCount + 2, advised.getAdvisors().length);

25/08/2016 12:10

Spring Framework Reference Documentation

398 de 1194

Its questionable whether its advisable (no pun intended) to modify advice
on a business object in production, although there are no doubt legitimate
usage cases. However, it can be very useful in development: for example,
in tests. I have sometimes found it very useful to be able to add test code in
the form of an interceptor or other advice, getting inside a method
invocation I want to test. (For example, the advice can get inside a
transaction created for that method: for example, to run SQL to check that a
database was correctly updated, before marking the transaction for roll
back.)

Depending on how you created the proxy, you can usually set a frozen flag, in which
case the Advised isFrozen() method will return true, and any attempts to modify
advice through addition or removal will result in an AopConfigException . The ability to
freeze the state of an advised object is useful in some cases, for example, to prevent
calling code removing a security interceptor. It may also be used in Spring 1.1 to allow
aggressive optimization if runtime advice modification is known not to be required.

12.9 Using the "auto-proxy" facility

So far weve considered explicit creation of AOP proxies using a ProxyFactoryBean or
similar factory bean.
Spring also allows us to use "auto-proxy" bean definitions, which can automatically proxy
selected bean definitions. This is built on Spring "bean post processor" infrastructure,
which enables modification of any bean definition as the container loads.
In this model, you set up some special bean definitions in your XML bean definition file to
configure the auto proxy infrastructure. This allows you just to declare the targets eligible
for auto-proxying: you dont need to use ProxyFactoryBean .
There are two ways to do this:
Using an auto-proxy creator that refers to specific beans in the current context.
A special case of auto-proxy creation that deserves to be considered separately;
auto-proxy creation driven by source-level metadata attributes.

12.9.1 Autoproxy bean definitions

The org.springframework.aop.framework.autoproxy package provides the

25/08/2016 12:10

Spring Framework Reference Documentation

399 de 1194

following standard auto-proxy creators.

BeanNameAutoProxyCreator
The BeanNameAutoProxyCreator class is a BeanPostProcessor that automatically
creates AOP proxies for beans with names matching literal values or wildcards.
<bean class="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator"
<property name="beanNames" value="jdk*,onlyJdk"/>
<property name="interceptorNames">
<list>
<value>myInterceptor</value>
</list>
</property>
</bean>

As with ProxyFactoryBean , there is an interceptorNames property rather than a list

of interceptors, to allow correct behavior for prototype advisors. Named "interceptors" can
be advisors or any advice type.
As with auto proxying in general, the main point of using BeanNameAutoProxyCreator is
to apply the same configuration consistently to multiple objects, with minimal volume of
configuration. It is a popular choice for applying declarative transactions to multiple
objects.
Bean definitions whose names match, such as "jdkMyBean" and "onlyJdk" in the above
example, are plain old bean definitions with the target class. An AOP proxy will be
created automatically by the BeanNameAutoProxyCreator . The same advice will be
applied to all matching beans. Note that if advisors are used (rather than the interceptor in
the above example), the pointcuts may apply differently to different beans.

DefaultAdvisorAutoProxyCreator
A more general and extremely powerful auto proxy creator is
DefaultAdvisorAutoProxyCreator . This will automagically apply eligible advisors in
the current context, without the need to include specific bean names in the auto-proxy
advisors bean definition. It offers the same merit of consistent configuration and
avoidance of duplication as BeanNameAutoProxyCreator .
Using this mechanism involves:
Specifying a DefaultAdvisorAutoProxyCreator bean definition.
Specifying any number of Advisors in the same or related contexts. Note that these

25/08/2016 12:10

Spring Framework Reference Documentation

400 de 1194

there must be a pointcut to evaluate, to check the eligibility of each advice to

candidate bean definitions.
The DefaultAdvisorAutoProxyCreator will automatically evaluate the pointcut
contained in each advisor, to see what (if any) advice it should apply to each business
object (such as "businessObject1" and "businessObject2" in the example).
This means that any number of advisors can be applied automatically to each business
object. If no pointcut in any of the advisors matches any method in a business object, the
object will not be proxied. As bean definitions are added for new business objects, they
will automatically be proxied if necessary.
Autoproxying in general has the advantage of making it impossible for callers or
dependencies to obtain an un-advised object. Calling getBean("businessObject1") on this
ApplicationContext will return an AOP proxy, not the target business object. (The "inner
bean" idiom shown earlier also offers this benefit.)

<bean class="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreato

The DefaultAdvisorAutoProxyCreator is very useful if you want to apply the same

advice consistently to many business objects. Once the infrastructure definitions are in
place, you can simply add new business objects without including specific proxy
configuration. You can also drop in additional aspects very easily - for example, tracing or
performance monitoring aspects - with minimal change to configuration.
The DefaultAdvisorAutoProxyCreator offers support for filtering (using a naming
convention so that only certain advisors are evaluated, allowing use of multiple, differently
configured, AdvisorAutoProxyCreators in the same factory) and ordering. Advisors can
implement the org.springframework.core.Ordered interface to ensure correct
ordering if this is an issue. The TransactionAttributeSourceAdvisor used in the above
example has a configurable order value; the default setting is unordered.

25/08/2016 12:10

Spring Framework Reference Documentation

401 de 1194

AbstractAdvisorAutoProxyCreator
This is the superclass of DefaultAdvisorAutoProxyCreator. You can create your own
auto-proxy creators by subclassing this class, in the unlikely event that advisor definitions
offer insufficient customization to the behavior of the framework
DefaultAdvisorAutoProxyCreator .

12.9.2 Using metadata-driven auto-proxying

A particularly important type of auto-proxying is driven by metadata. This produces a
similar programming model to .NET ServicedComponents . Instead of defining metadata
in XML descriptors, configuration for transaction management and other enterprise
services is held in source-level attributes.
In this case, you use the DefaultAdvisorAutoProxyCreator , in combination with
Advisors that understand metadata attributes. The metadata specifics are held in the
pointcut part of the candidate advisors, rather than in the auto-proxy creation class itself.
This is really a special case of the DefaultAdvisorAutoProxyCreator , but deserves
consideration on its own. (The metadata-aware code is in the pointcuts contained in the
advisors, not the AOP framework itself.)
The /attributes directory of the JPetStore sample application shows the use of
attribute-driven auto-proxying. In this case, theres no need to use the
TransactionProxyFactoryBean . Simply defining transactional attributes on business
objects is sufficient, because of the use of metadata-aware pointcuts. The bean
definitions include the following code, in /WEB-INF/declarativeServices.xml . Note
that this is generic, and can be used outside the JPetStore:

<bean class="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreato

25/08/2016 12:10

Spring Framework Reference Documentation

402 de 1194

<bean id="attributes" class="org.springframework.metadata.commons.CommonsAttributes"

The DefaultAdvisorAutoProxyCreator bean definition (the name is not significant,

hence it can even be omitted) will pick up all eligible pointcuts in the current application
context. In this case, the "transactionAdvisor" bean definition, of type
TransactionAttributeSourceAdvisor , will apply to classes or methods carrying a
transaction attribute. The TransactionAttributeSourceAdvisor depends on a
TransactionInterceptor, via constructor dependency. The example resolves this via
autowiring. The AttributesTransactionAttributeSource depends on an
implementation of the org.springframework.metadata.Attributes interface. In this
fragment, the "attributes" bean satisfies this, using the Jakarta Commons Attributes API to
obtain attribute information. (The application code must have been compiled using the
Commons Attributes compilation task.)
The /annotation directory of the JPetStore sample application contains an analogous
example for auto-proxying driven by JDK 1.5+ annotations. The following configuration
enables automatic detection of Springs Transactional annotation, leading to implicit
proxies for beans containing that annotation:

<bean class="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreato

The TransactionInterceptor defined here depends on a

PlatformTransactionManager definition, which is not included in this generic file
(although it could be) because it will be specific to the applications transaction
requirements (typically JTA, as in this example, or Hibernate, JDO or JDBC):
<bean id="transactionManager"
class="org.springframework.transaction.jta.JtaTransactionManager"/>

25/08/2016 12:10

Spring Framework Reference Documentation

403 de 1194

If you require only declarative transaction management, using these generic

XML definitions will result in Spring automatically proxying all classes or
methods with transaction attributes. You wont need to work directly with
AOP, and the programming model is similar to that of .NET
ServicedComponents.

This mechanism is extensible. Its possible to do auto-proxying based on custom

attributes. You need to:
Define your custom attribute.
Specify an Advisor with the necessary advice, including a pointcut that is triggered by
the presence of the custom attribute on a class or method. You may be able to use
an existing advice, merely implementing a static pointcut that picks up the custom
attribute.
Its possible for such advisors to be unique to each advised class (for example, mixins):
they simply need to be defined as prototype, rather than singleton, bean definitions. For
example, the LockMixin introduction interceptor from the Spring test suite, shown
above, could be used in conjunction with a generic DefaultIntroductionAdvisor :
<bean id="lockMixin" class="test.mixin.LockMixin" scope="prototype"/>

<bean id="lockableAdvisor" class="org.springframework.aop.support.DefaultIntroductionA

scope="prototype">
<constructor-arg ref="lockMixin"/>
</bean>

Note that both lockMixin and lockableAdvisor are defined as prototypes.

12.10 Using TargetSources

Spring offers the concept of a TargetSource, expressed in the
org.springframework.aop.TargetSource interface. This interface is responsible for
returning the "target object" implementing the join point. The TargetSource
implementation is asked for a target instance each time the AOP proxy handles a method
invocation.
Developers using Spring AOP dont normally need to work directly with TargetSources,
but this provides a powerful means of supporting pooling, hot swappable and other
sophisticated targets. For example, a pooling TargetSource can return a different target

25/08/2016 12:10

Spring Framework Reference Documentation

404 de 1194

If you do not specify a TargetSource, a default implementation is used that wraps a local
object. The same target is returned for each invocation (as you would expect).
Lets look at the standard target sources provided with Spring, and how you can use
them.

When using a custom target source, your target will usually need to be a
prototype rather than a singleton bean definition. This allows Spring to
create a new target instance when required.

12.10.1 Hot swappable target sources

The org.springframework.aop.target.HotSwappableTargetSource exists to allow
the target of an AOP proxy to be switched while allowing callers to keep their references
to it.
Changing the target sources target takes effect immediately. The
HotSwappableTargetSource is threadsafe.
You can change the target via the swap() method on HotSwappableTargetSource as
follows:
HotSwappableTargetSource swapper = (HotSwappableTargetSource) beanFactory.getBean(
Object oldTarget = swapper.swap(newTarget);

The XML definitions required look as follows:

The above swap() call changes the target of the swappable bean. Clients who hold a
reference to that bean will be unaware of the change, but will immediately start hitting the
new target.
Although this example doesnt add any advice - and its not necessary to add advice to

25/08/2016 12:10

Spring Framework Reference Documentation

405 de 1194

arbitrary advice.

12.10.2 Pooling target sources

Using a pooling target source provides a similar programming model to stateless session
EJBs, in which a pool of identical instances is maintained, with method invocations going
to free objects in the pool.
A crucial difference between Spring pooling and SLSB pooling is that Spring pooling can
be applied to any POJO. As with Spring in general, this service can be applied in a
non-invasive way.
Spring provides out-of-the-box support for Commons Pool 2.2, which provides a fairly
efficient pooling implementation. Youll need the commons-pool Jar on your applications
classpath to use this feature. Its also possible to subclass
org.springframework.aop.target.AbstractPoolingTargetSource to support any
other pooling API.

Commons Pool 1.5+ is also supported but deprecated as of Spring

Framework 4.2.

Sample configuration is shown below:

<bean id="businessObjectTarget" class="com.mycompany.MyBusinessObject"
scope="prototype">
... properties omitted
</bean>

<bean id="poolTargetSource" class="org.springframework.aop.target.CommonsPool2TargetSo

Note that the target object - "businessObjectTarget" in the example - must be a prototype.
This allows the PoolingTargetSource implementation to create new instances of the
target to grow the pool as necessary. See the javadocs of
AbstractPoolingTargetSource and the concrete subclass you wish to use for

25/08/2016 12:10

Spring Framework Reference Documentation

406 de 1194

information about its properties: "maxSize" is the most basic, and always guaranteed to
be present.
In this case, "myInterceptor" is the name of an interceptor that would need to be defined
in the same IoC context. However, it isnt necessary to specify interceptors to use pooling.
If you want only pooling, and no other advice, dont set the interceptorNames property at
all.
Its possible to configure Spring so as to be able to cast any pooled object to the
org.springframework.aop.target.PoolingConfig interface, which exposes
information about the configuration and current size of the pool through an introduction.
Youll need to define an advisor like this:

<bean id="poolConfigAdvisor" class="org.springframework.beans.factory.config.MethodInv

This advisor is obtained by calling a convenience method on the

AbstractPoolingTargetSource class, hence the use of MethodInvokingFactoryBean.
This advisors name ("poolConfigAdvisor" here) must be in the list of interceptors names
in the ProxyFactoryBean exposing the pooled object.
The cast will look as follows:
PoolingConfig conf = (PoolingConfig) beanFactory.getBean("businessObject");
System.out.println("Max pool size is " + conf.getMaxSize());

Pooling stateless service objects is not usually necessary. We dont believe

it should be the default choice, as most stateless objects are naturally
thread safe, and instance pooling is problematic if resources are cached.

Simpler pooling is available using auto-proxying. Its possible to set the TargetSources
used by any auto-proxy creator.

12.10.3 Prototype target sources

Setting up a "prototype" target source is similar to a pooling TargetSource. In this case, a
new instance of the target will be created on every method invocation. Although the cost
of creating a new object isnt high in a modern JVM, the cost of wiring up the new object
(satisfying its IoC dependencies) may be more expensive. Thus you shouldnt use this

25/08/2016 12:10

Spring Framework Reference Documentation

407 de 1194

approach without very good reason.

To do this, you could modify the poolTargetSource definition shown above as follows.
(Ive also changed the name, for clarity.)

<bean id="prototypeTargetSource" class="org.springframework.aop.target.PrototypeTarget

Theres only one property: the name of the target bean. Inheritance is used in the
TargetSource implementations to ensure consistent naming. As with the pooling target
source, the target bean must be a prototype bean definition.

12.10.4 ThreadLocal target sources

ThreadLocal target sources are useful if you need an object to be created for each
incoming request (per thread that is). The concept of a ThreadLocal provide a
JDK-wide facility to transparently store resource alongside a thread. Setting up a
ThreadLocalTargetSource is pretty much the same as was explained for the other
types of target source:

<bean id="threadlocalTargetSource" class="org.springframework.aop.target.ThreadLocalTa

ThreadLocals come with serious issues (potentially resulting in memory

leaks) when incorrectly using them in a multi-threaded and multi-classloader
environments. One should always consider wrapping a threadlocal in some
other class and never directly use the ThreadLocal itself (except of course
in the wrapper class). Also, one should always remember to correctly set
and unset (where the latter simply involved a call to
ThreadLocal.set(null) ) the resource local to the thread. Unsetting
should be done in any case since not unsetting it might result in problematic
behavior. Springs ThreadLocal support does this for you and should always
be considered in favor of using ThreadLocals without other proper handling
code.

12.11 Defining new Advice types

25/08/2016 12:10

Spring Framework Reference Documentation

408 de 1194

is presently used internally, it is possible to support arbitrary advice types in addition to

the out-of-the-box interception around advice, before, throws advice and after returning
advice.
The org.springframework.aop.framework.adapter package is an SPI package
allowing support for new custom advice types to be added without changing the core
framework. The only constraint on a custom Advice type is that it must implement the
org.aopalliance.aop.Advice marker interface.
Please refer to the org.springframework.aop.framework.adapter javadocs for
further information.

12.12 Further resources

Please refer to the Spring sample applications for further examples of Spring AOP:
The JPetStores default configuration illustrates the use of the
TransactionProxyFactoryBean for declarative transaction management.
The /attributes directory of the JPetStore illustrates the use of attribute-driven
declarative transaction management.

Part IV. Testing

The adoption of the test-driven-development (TDD) approach to software development is
certainly advocated by the Spring team, and so coverage of Springs support for
integration testing is covered (alongside best practices for unit testing). The Spring team
has found that the correct use of IoC certainly does make both unit and integration testing
easier (in that the presence of setter methods and appropriate 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.

13. Introduction to Spring Testing

Testing is an integral part of enterprise software development. This chapter focuses on
the value-add of the IoC principle to unit testing and on the benefits of the Spring

25/08/2016 12:10

Spring Framework Reference Documentation

409 de 1194

Frameworks support for integration testing. (A thorough treatment of testing in the

enterprise is beyond the scope of this reference manual.)

14. Unit Testing

Dependency Injection should make your code less dependent on the container than it
would be with traditional Java EE development. The POJOs that make up your
application should be testable in JUnit or TestNG tests, with objects simply instantiated
using the new operator, without Spring or any other container. You can use mock objects
(in conjunction with other valuable testing techniques) to test your code in isolation. If you
follow the architecture recommendations for Spring, the resulting clean layering and
componentization of your codebase will facilitate easier unit testing. For example, you can
test service layer objects by stubbing or mocking DAO or Repository interfaces, without
needing to access persistent data while running unit tests.
True unit tests typically run extremely quickly, as there is no runtime infrastructure to set
up. Emphasizing true unit tests as part of your development methodology will boost your
productivity. You may not need this section of the testing chapter to help you write
effective unit tests for your IoC-based applications. For certain unit testing scenarios,
however, the Spring Framework provides the following mock objects and testing support
classes.

14.1 Mock Objects

14.1.1 Environment
The org.springframework.mock.env package contains mock implementations of the
Environment and PropertySource abstractions (see Section 7.13.1, Bean definition
profiles and Section 7.13.3, PropertySource abstraction). MockEnvironment and
MockPropertySource are useful for developing out-of-container tests for code that
depends on environment-specific properties.

14.1.2 JNDI
The org.springframework.mock.jndi package contains an implementation of the
JNDI SPI, which you can use to set up a simple JNDI environment for test suites or
stand-alone applications. If, for example, JDBC DataSource s get bound to the same
JNDI names in test code as within a Java EE container, you can reuse both application

25/08/2016 12:10

Spring Framework Reference Documentation

410 de 1194

code and configuration in testing scenarios without modification.

14.1.3 Servlet API

The org.springframework.mock.web package contains a comprehensive set of
Servlet API mock objects, which are useful for testing web contexts, controllers, and
filters. These mock objects are targeted at usage with Springs Web MVC framework and
are generally more convenient to use than dynamic mock objects such as EasyMock or
alternative Servlet API mock objects such as MockObjects. Since Spring Framework 4.0,
the set of mocks in the org.springframework.mock.web package is based on the
Servlet 3.0 API.
For thorough integration testing of your Spring MVC and REST Controller s in
conjunction with your WebApplicationContext configuration for Spring MVC, see the
Spring MVC Test Framework.

14.1.4 Portlet API

The org.springframework.mock.web.portlet package contains a set of Portlet API
mock objects, targeted at usage with Springs Portlet MVC framework.

14.2 Unit Testing support Classes

14.2.1 General testing utilities
The org.springframework.test.util package contains several general purpose
utilities for use in unit and integration testing.
ReflectionTestUtils is a collection of reflection-based utility methods. Developers
use these methods in testing scenarios where they need to change the value of a
constant, set a non- public field, invoke a non- public setter method, or invoke a
non- public configuration or lifecycle callback method when testing application code
involving use cases such as the following.
ORM frameworks such as JPA and Hibernate that condone private or protected
field access as opposed to public setter methods for properties in a domain entity.
Springs support for annotations such as @Autowired , @Inject , and @Resource ,
which provides dependency injection for private or protected fields, setter
methods, and configuration methods.

25/08/2016 12:10

Spring Framework Reference Documentation

411 de 1194

Use of annotations such as @PostConstruct and @PreDestroy for lifecycle

callback methods.
AopTestUtils is a collection of AOP-related utility methods. These methods can be
used to obtain a reference to the underlying target object hidden behind one or more
Spring proxies. For example, if you have configured a bean as a dynamic mock using a
library like EasyMock or Mockito and the mock is wrapped in a Spring proxy, you may
need direct access to the underlying mock in order to configure expectations on it and
perform verifications. For Springs core AOP utilities, see AopUtils and
AopProxyUtils .

14.2.2 Spring MVC

The org.springframework.test.web package contains ModelAndViewAssert , which
you can use in combination with JUnit, TestNG, or any other testing framework for unit
tests dealing with Spring MVC ModelAndView objects.

To unit test your Spring MVC Controller s as POJOs, use

ModelAndViewAssert combined with MockHttpServletRequest ,
MockHttpSession , and so on from Springs Servlet API mocks. For
thorough integration testing of your Spring MVC and REST Controller s
in conjunction with your WebApplicationContext configuration for Spring
MVC, use the Spring MVC Test Framework instead.

15. Integration Testing

15.1 Overview
It is important to be able to perform some integration testing without requiring deployment
to your application server or connecting to other enterprise infrastructure. This will enable
you to test things such as:
The correct wiring of your Spring IoC container contexts.
Data access using JDBC or an ORM tool. This would include such things as the
correctness of SQL statements, Hibernate queries, JPA entity mappings, etc.
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

25/08/2016 12:10

Spring Framework Reference Documentation

412 de 1194

and might also be in the long org.springframework.test form, depending on where

you get it from (see the section on Dependency Management for an explanation). This
library includes the org.springframework.test package, which contains valuable
classes for integration testing with a Spring container. This testing does not rely on an
application server or other deployment environment. Such tests are slower to run than
unit tests but much faster than the equivalent Selenium tests or remote tests that rely on
deployment to an application server.
In Spring 2.5 and later, unit and integration testing support is provided in the form of the
annotation-driven Spring TestContext Framework. The TestContext framework is agnostic
of the actual testing framework in use, thus allowing instrumentation of tests in various
environments including JUnit, TestNG, and so on.

15.2 Goals of Integration Testing

Springs integration testing support has the following primary goals:
To manage Spring IoC container caching between test execution.
To provide Dependency Injection of test fixture instances.
To provide transaction management appropriate to integration testing.
To supply Spring-specific base classes that assist developers in writing integration
tests.
The next few sections describe each goal and provide links to implementation and
configuration details.

15.2.1 Context management and caching

The Spring TestContext Framework provides consistent loading of Spring
ApplicationContext s and WebApplicationContext s as well as caching of those
contexts. Support for the caching of loaded contexts is important, because startup time
can become an issuenot because of the overhead of Spring itself, but because the
objects instantiated by the Spring container take time to instantiate. For example, a
project with 50 to 100 Hibernate mapping files might take 10 to 20 seconds to load the
mapping files, and incurring that cost before running every test in every test fixture leads
to slower overall test runs that reduce developer productivity.
Test classes typically declare either an array of resource locations for XML or Groovy
configuration metadataoften in the classpathor an array of annotated classes that is
used to configure the application. These locations or classes are the same as or similar to

25/08/2016 12:10

Spring Framework Reference Documentation

413 de 1194

those specified in web.xml or other configuration files for production deployments.

By default, once loaded, the configured ApplicationContext is reused for each test.
Thus the setup cost is incurred only once per test suite, and subsequent test execution is
much faster. In this context, the term test suite means all tests run in the same JVMfor
example, all tests run from an Ant, Maven, or Gradle build for a given project or module.
In the unlikely case that a test corrupts the application context and requires reloading
for example, by modifying a bean definition or the state of an application objectthe
TestContext framework can be configured to reload the configuration and rebuild the
application context before executing the next test.
See Section 15.5.4, Context management and the section called Context caching with
the TestContext framework.

15.2.2 Dependency Injection of test fixtures

When the TestContext framework loads your application context, it can optionally
configure instances of your test classes via Dependency Injection. This provides a
convenient mechanism for setting up test fixtures using preconfigured beans from your
application context. A strong benefit here is that you can reuse application contexts
across various testing scenarios (e.g., for configuring Spring-managed object graphs,
transactional proxies, DataSource s, etc.), thus avoiding the need to duplicate complex
test fixture setup for individual test cases.
As an example, consider the scenario where we have a class,
HibernateTitleRepository , that implements data access logic for a Title domain
entity. We want to write integration tests that test the following areas:
The Spring configuration: basically, is everything related to the configuration of the
HibernateTitleRepository bean correct and present?
The Hibernate mapping file configuration: is everything mapped correctly, and are the
correct lazy-loading settings in place?
The logic of the HibernateTitleRepository : does the configured instance of this
class perform as anticipated?
See dependency injection of test fixtures with the TestContext framework.

15.2.3 Transaction management

One common issue in tests that access a real database is their effect on the state of the
persistence store. Even when youre using a development database, changes to the state

25/08/2016 12:10

Spring Framework Reference Documentation

414 de 1194

may affect future tests. Also, many operationssuch as inserting or modifying persistent
datacannot be performed (or verified) outside a transaction.
The TestContext framework addresses this issue. By default, the framework will create
and roll back a transaction for each test. You simply write code that can assume the
existence of a transaction. If you call transactionally proxied objects in your tests, they will
behave correctly, according to their configured transactional semantics. In addition, if a
test method deletes the contents of selected tables while running within the transaction
managed for the test, the transaction will roll back by default, and the database will return
to its state prior to execution of the test. Transactional support is provided to a test via a
PlatformTransactionManager bean defined in the tests application context.
If you want a transaction to commitunusual, but occasionally useful when you want a
particular test to populate or modify the databasethe TestContext framework can be
instructed to cause the transaction to commit instead of roll back via the @Commit
annotation.
See transaction management with the TestContext framework.

15.2.4 Support classes for integration testing

The Spring TestContext Framework provides several abstract support classes that
simplify the writing of integration tests. These base test classes provide well-defined
hooks into the testing framework as well as convenient instance variables and methods,
which enable you to access:
The ApplicationContext , for performing explicit bean lookups or testing the state
of the context as a whole.
A JdbcTemplate , for executing SQL statements to query the database. Such
queries can be used to confirm database state both prior to and after execution of
database-related application code, and Spring ensures that such queries run in the
scope of the same transaction as the application code. When used in conjunction
with an ORM tool, be sure to avoid false positives.
In addition, you may want to create your own custom, application-wide superclass with
instance variables and methods specific to your project.
See support classes for the TestContext framework.

15.3 JDBC Testing Support

25/08/2016 12:10

Spring Framework Reference Documentation

415 de 1194

The org.springframework.test.jdbc package contains JdbcTestUtils , which is a

collection of JDBC related utility functions intended to simplify standard database testing
scenarios. Specifically, JdbcTestUtils provides the following static utility methods.
countRowsInTable(..) : counts the number of rows in the given table
countRowsInTableWhere(..) : counts the number of rows in the given table, using
the provided WHERE clause
deleteFromTables(..) : deletes all rows from the specified tables
deleteFromTableWhere(..) : deletes rows from the given table, using the provided
WHERE clause
dropTables(..) : drops the specified tables
Note that AbstractTransactionalJUnit4SpringContextTests and
AbstractTransactionalTestNGSpringContextTests provide convenience methods
which delegate to the aforementioned methods in JdbcTestUtils .
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 Section 19.8, Embedded database support and Section 19.8.5, Testing data
access logic with an embedded database.

15.4 Annotations
15.4.1 Spring Testing Annotations
The Spring Framework provides the following set of Spring-specific annotations that you
can use in your unit and integration tests in conjunction with the TestContext framework.
Refer to the corresponding javadocs for further information, including default attribute
values, attribute aliases, and so on.

@BootstrapWith
@BootstrapWith is a class-level annotation that is used to configure how the Spring
TestContext Framework is bootstrapped. Specifically, @BootstrapWith is used to
specify a custom TestContextBootstrapper . Consult the Bootstrapping the
TestContext framework section for further details.

@ContextConfiguration
@ContextConfiguration defines class-level metadata that is used to determine how to

25/08/2016 12:10

Spring Framework Reference Documentation

416 de 1194

load and configure an ApplicationContext for integration tests. Specifically,

@ContextConfiguration declares the application context resource locations or the
annotated classes that will be used to load the context.
Resource locations are typically XML configuration files or Groovy scripts located in the
classpath; whereas, annotated classes are typically @Configuration classes. However,
resource locations can also refer to files and scripts in the file system, and annotated
classes can be component classes, etc.
@ContextConfiguration("/test-config.xml")
public class XmlApplicationContextTests {
// class body...
}
@ContextConfiguration(classes = TestConfig.class)
public class ConfigClassApplicationContextTests {
// class body...
}

As an alternative or in addition to declaring resource locations or annotated classes,

@ContextConfiguration may be used to declare ApplicationContextInitializer
classes.
@ContextConfiguration(initializers = CustomContextIntializer.class)
public class ContextInitializerTests {
// class body...
}

@ContextConfiguration may optionally be used to declare the ContextLoader

strategy as well. Note, however, that you typically do not need to explicitly configure the
loader since the default loader supports either resource locations or annotated
classes as well as initializers .
@ContextConfiguration(locations = "/test-context.xml", loader = CustomContextLoader.
public class CustomLoaderXmlApplicationContextTests {
// class body...
}

@ContextConfiguration provides support for inheriting resource

locations or configuration classes as well as context initializers declared by
superclasses by default.

25/08/2016 12:10

Spring Framework Reference Documentation

417 de 1194

See Section 15.5.4, Context management and the @ContextConfiguration javadocs

for further details.

@WebAppConfiguration
@WebAppConfiguration is a class-level annotation that is used to declare that the
ApplicationContext loaded for an integration test should be a
WebApplicationContext . The mere presence of @WebAppConfiguration on a test
class ensures that a WebApplicationContext will be loaded for the test, using the
default value of "file:src/main/webapp" for the path to the root of the web application
(i.e., the resource base path). The resource base path is used behind the scenes to
create a MockServletContext which serves as the ServletContext for the tests
WebApplicationContext .
@ContextConfiguration
@WebAppConfiguration
public class WebAppTests {
// class body...
}

To override the default, specify a different base resource path via the implicit value
attribute. Both classpath: and file: resource prefixes are supported. If no resource
prefix is supplied the path is assumed to be a file system resource.
@ContextConfiguration
@WebAppConfiguration("classpath:test-web-resources")
public class WebAppTests {
// class body...
}

Note that @WebAppConfiguration must be used in conjunction with

@ContextConfiguration , either within a single test class or within a test class
hierarchy. See the @WebAppConfiguration javadocs for further details.

@ContextHierarchy
@ContextHierarchy is a class-level annotation that is used to define a hierarchy of
ApplicationContext s for integration tests. @ContextHierarchy should be declared
with a list of one or more @ContextConfiguration instances, each of which defines a
level in the context hierarchy. The following examples demonstrate the use of
@ContextHierarchy within a single test class; however, @ContextHierarchy can also
be used within a test class hierarchy.

25/08/2016 12:10

Spring Framework Reference Documentation

418 de 1194

@ContextHierarchy({
@ContextConfiguration("/parent-config.xml"),
@ContextConfiguration("/child-config.xml")
})
public class ContextHierarchyTests {
// class body...
}
@WebAppConfiguration
@ContextHierarchy({
@ContextConfiguration(classes = AppConfig.class),
@ContextConfiguration(classes = WebConfig.class)
})
public class WebIntegrationTests {
// class body...
}

If you need to merge or override the configuration for a given level of the context
hierarchy within a test class hierarchy, you must explicitly name that level by supplying
the same value to the name attribute in @ContextConfiguration at each
corresponding level in the class hierarchy. See the section called Context hierarchies
and the @ContextHierarchy javadocs for further examples.

@ActiveProfiles
@ActiveProfiles is a class-level annotation that is used to declare which bean
definition profiles should be active when loading an ApplicationContext for an
integration test.
@ContextConfiguration
@ActiveProfiles("dev")
public class DeveloperTests {
// class body...
}
@ContextConfiguration
@ActiveProfiles({"dev", "integration"})
public class DeveloperIntegrationTests {
// class body...
}

@ActiveProfiles provides support for inheriting active bean definition

profiles declared by superclasses by default. It is also possible to resolve

25/08/2016 12:10

Spring Framework Reference Documentation

419 de 1194

active bean definition profiles programmatically by implementing a custom

ActiveProfilesResolver and registering it via the resolver attribute of
@ActiveProfiles .

See the section called Context configuration with environment profiles and the
@ActiveProfiles javadocs for examples and further details.

@TestPropertySource
@TestPropertySource is a class-level annotation that is used to configure the locations
of properties files and inlined properties to be added to the set of PropertySources in
the Environment for an ApplicationContext loaded for an integration test.
Test property sources have higher precedence than those loaded from the operating
systems environment or Java system properties as well as property sources added by
the application declaratively via @PropertySource or programmatically. Thus, test
property sources can be used to selectively override properties defined in system and
application property sources. Furthermore, inlined properties have higher precedence
than properties loaded from resource locations.
The following example demonstrates how to declare a properties file from the classpath.
@ContextConfiguration
@TestPropertySource("/test.properties")
public class MyIntegrationTests {
// class body...
}

The following example demonstrates how to declare inlined properties.

@ContextConfiguration
@TestPropertySource(properties = { "timezone = GMT", "port: 4242" })
public class MyIntegrationTests {
// class body...
}

@DirtiesContext
@DirtiesContext indicates that the underlying Spring ApplicationContext has been
dirtied during the execution of a test (i.e., modified or corrupted in some mannerfor
example, by changing the state of a singleton bean) and should be closed. When an
application context is marked dirty, it is removed from the testing frameworks cache and

25/08/2016 12:10

Spring Framework Reference Documentation

420 de 1194

closed. As a consequence, the underlying Spring container will be rebuilt for any
subsequent test that requires a context with the same configuration metadata.
@DirtiesContext can be used as both a class-level and method-level annotation within
the same class or class hierarchy. In such scenarios, the ApplicationContext is
marked as dirty before or after any such annotated method as well as before or after the
current test class, depending on the configured methodMode and classMode .
The following examples explain when the context would be dirtied for various
configuration scenarios:
Before the current test class, when declared on a class with class mode set to
BEFORE_CLASS .
@DirtiesContext(classMode = BEFORE_CLASS)
public class FreshContextTests {
// some tests that require a new Spring container
}

After the current test class, when declared on a class with class mode set to
AFTER_CLASS (i.e., the default class mode).
@DirtiesContext
public class ContextDirtyingTests {
// some tests that result in the Spring container being dirtied
}

Before each test method in the current test class, when declared on a class with
class mode set to BEFORE_EACH_TEST_METHOD.
@DirtiesContext(classMode = BEFORE_EACH_TEST_METHOD)
public class FreshContextTests {
// some tests that require a new Spring container
}

After each test method in the current test class, when declared on a class with class
mode set to AFTER_EACH_TEST_METHOD.
@DirtiesContext(classMode = AFTER_EACH_TEST_METHOD)
public class ContextDirtyingTests {
// some tests that result in the Spring container being dirtied
}

Before the current test, when declared on a method with the method mode set to
BEFORE_METHOD

25/08/2016 12:10

Spring Framework Reference Documentation

421 de 1194

@DirtiesContext(methodMode = BEFORE_METHOD)
@Test
public void testProcessWhichRequiresFreshAppCtx() {
// some logic that requires a new Spring container
}

After the current test, when declared on a method with the method mode set to
AFTER_METHOD (i.e., the default method mode).
@DirtiesContext
@Test
public void testProcessWhichDirtiesAppCtx() {
// some logic that results in the Spring container being dirtied
}

If @DirtiesContext is used in a test whose context is configured as part of a context

hierarchy via @ContextHierarchy , the hierarchyMode flag can be used to control how
the context cache is cleared. By default an exhaustive algorithm will be used that clears
the context cache including not only the current level but also all other context hierarchies
that share an ancestor context common to the current test; all ApplicationContext s
that reside in a sub-hierarchy of the common ancestor context will be removed from the
context cache and closed. If the exhaustive algorithm is overkill for a particular use case,
the simpler current level algorithm can be specified instead, as seen below.
@ContextHierarchy({
@ContextConfiguration("/parent-config.xml"),
@ContextConfiguration("/child-config.xml")
})
public class BaseTests {
// class body...
}
public class ExtendedTests extends BaseTests {
@Test
@DirtiesContext(hierarchyMode = CURRENT_LEVEL)
public void test() {
// some logic that results in the child context being dirtied
}
}

For further details regarding the EXHAUSTIVE and CURRENT_LEVEL algorithms see the
DirtiesContext.HierarchyMode javadocs.

25/08/2016 12:10

Spring Framework Reference Documentation

422 de 1194

@TestExecutionListeners
@TestExecutionListeners defines class-level metadata for configuring the
TestExecutionListener implementations that should be registered with the
TestContextManager . Typically, @TestExecutionListeners is used in conjunction
with @ContextConfiguration .

@ContextConfiguration
@TestExecutionListeners({CustomTestExecutionListener.class, AnotherTestExecutionListen
public class CustomTestExecutionListenerTests {
// class body...
}

@TestExecutionListeners supports inherited listeners by default. See the javadocs for

an example and further details.

@Commit
@Commit indicates that the transaction for a transactional test method should be
committed after the test method has completed. @Commit can be used as a direct
replacement for @Rollback(false) in order to more explicitly convey the intent of the
code. Analogous to @Rollback , @Commit may also be declared as a class-level or
method-level annotation.
@Commit
@Test
public void testProcessWithoutRollback() {
// ...
}

@Rollback
@Rollback indicates whether the transaction for a transactional test method should be
rolled back after the test method has completed. If true , the transaction is rolled back;
otherwise, the transaction is committed (see also @Commit ). Rollback semantics for
integration tests in the Spring TestContext Framework default to true even if
@Rollback is not explicitly declared.
When declared as a class-level annotation, @Rollback defines the default rollback
semantics for all test methods within the test class hierarchy. When declared as a
method-level annotation, @Rollback defines rollback semantics for the specific test
method, potentially overriding class-level @Rollback or @Commit semantics.

25/08/2016 12:10

Spring Framework Reference Documentation

423 de 1194

@Rollback(false)
@Test
public void testProcessWithoutRollback() {
// ...
}

@BeforeTransaction
@BeforeTransaction indicates that the annotated void method should be executed
before a transaction is started for test methods configured to run within a transaction via
Springs @Transactional annotation. As of Spring Framework 4.3,
@BeforeTransaction methods are not required to be public and may be declared on
Java 8 based interface default methods.
@BeforeTransaction
void beforeTransaction() {
// logic to be executed before a transaction is started
}

@AfterTransaction
@AfterTransaction indicates that the annotated void method should be executed
after a transaction is ended for test methods configured to run within a transaction via
Springs @Transactional annotation. As of Spring Framework 4.3,
@AfterTransaction methods are not required to be public and may be declared on
Java 8 based interface default methods.
@AfterTransaction
void afterTransaction() {
// logic to be executed after a transaction has ended
}

@Sql
@Sql is used to annotate a test class or test method to configure SQL scripts to be
executed against a given database during integration tests.
@Test
@Sql({"/test-schema.sql", "/test-user-data.sql"})
public void userTest {
// execute code that relies on the test schema and test data
}

25/08/2016 12:10

Spring Framework Reference Documentation

424 de 1194

See the section called Executing SQL scripts declaratively with @Sql for further details.

@SqlConfig
@SqlConfig defines metadata that is used to determine how to parse and execute SQL
scripts configured via the @Sql annotation.
@Test
@Sql(
scripts = "/test-user-data.sql",
config = @SqlConfig(commentPrefix = "`", separator = "@@")
)
public void userTest {
// execute code that relies on the test data
}

@SqlGroup
@SqlGroup is a container annotation that aggregates several @Sql annotations.
@SqlGroup can be used natively, declaring several nested @Sql annotations, or it can
be used in conjunction with Java 8s support for repeatable annotations, where @Sql can
simply be declared several times on the same class or method, implicitly generating this
container annotation.
@Test
@SqlGroup({
@Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")),
@Sql("/test-user-data.sql")
)}
public void userTest {
// execute code that uses the test schema and test data
}

15.4.2 Standard Annotation Support

The following annotations are supported with standard semantics for all configurations of
the Spring TestContext Framework. Note that these annotations are not specific to tests
and can be used anywhere in the Spring Framework.
@Autowired
@Qualifier
@Resource (javax.annotation) if JSR-250 is present
@Inject (javax.inject) if JSR-330 is present

25/08/2016 12:10

Spring Framework Reference Documentation

425 de 1194

@Named (javax.inject) if JSR-330 is present

@PersistenceContext (javax.persistence) if JPA is present
@PersistenceUnit (javax.persistence) if JPA is present
@Required
@Transactional

In the Spring TestContext Framework @PostConstruct and

@PreDestroy may be used with standard semantics on any application
components configured in the ApplicationContext ; however, these
lifecycle annotations have limited usage within an actual test class.
If a method within a test class is annotated with @PostConstruct , that
method will be executed before any before methods of the underlying test
framework (e.g., methods annotated with JUnit 4s @Before ), and that will
apply for every test method in the test class. On the other hand, if a method
within a test class is annotated with @PreDestroy , that method will never
be executed. Within a test class it is therefore recommended to use test
lifecycle callbacks from the underlying test framework instead of
@PostConstruct and @PreDestroy .

15.4.3 Spring JUnit 4 Testing Annotations

The following annotations are only supported when used in conjunction with the
SpringRunner, Springs JUnit rules, or Springs JUnit 4 support classes.

@IfProfileValue
@IfProfileValue indicates that the annotated test is enabled for a specific testing
environment. If the configured ProfileValueSource returns a matching value for the
provided name , the test is enabled. Otherwise, the test will be disabled and effectively
ignored.
@IfProfileValue can be applied at the class level, the method level, or both.
Class-level usage of @IfProfileValue takes precedence over method-level usage for
any methods within that class or its subclasses. Specifically, a test is enabled if it is
enabled both at the class level and at the method level; the absence of
@IfProfileValue means the test is implicitly enabled. This is analogous to the
semantics of JUnit 4s @Ignore annotation, except that the presence of @Ignore
always disables a test.

25/08/2016 12:10

Spring Framework Reference Documentation

426 de 1194

@IfProfileValue(name="java.vendor", value="Oracle Corporation")

@Test
public void testProcessWhichRunsOnlyOnOracleJvm() {
// some logic that should run only on Java VMs from Oracle Corporation
}

Alternatively, you can configure @IfProfileValue with a list of values (with OR

semantics) to achieve TestNG-like support for test groups in a JUnit 4 environment.
Consider the following example:
@IfProfileValue(name="test-groups", values={"unit-tests", "integration-tests"
@Test
public void testProcessWhichRunsForUnitOrIntegrationTestGroups() {
// some logic that should run only for unit and integration test groups
}

@ProfileValueSourceConfiguration
@ProfileValueSourceConfiguration is a class-level annotation that specifies what
type of ProfileValueSource to use when retrieving profile values configured through
the @IfProfileValue annotation. If @ProfileValueSourceConfiguration is not
declared for a test, SystemProfileValueSource is used by default.
@ProfileValueSourceConfiguration(CustomProfileValueSource.class)
public class CustomProfileValueSourceTests {
// class body...
}

@Timed
@Timed indicates that the annotated test method must finish execution in a specified time
period (in milliseconds). If the text execution time exceeds the specified time period, the
test fails.
The time period includes execution of the test method itself, any repetitions of the test
(see @Repeat ), as well as any set up or tear down of the test fixture.
@Timed(millis=1000)
public void testProcessWithOneSecondTimeout() {
// some logic that should not take longer than 1 second to execute
}

Springs @Timed annotation has different semantics than JUnit 4s @Test(timeout=)

25/08/2016 12:10

Spring Framework Reference Documentation

427 de 1194

(that is, by executing the test method in a separate Thread ), @Test(timeout=)

preemptively fails the test if the test takes too long. Springs @Timed , on the other hand,
does not preemptively fail the test but rather waits for the test to complete before failing.

@Repeat
@Repeat indicates that the annotated test method must be executed repeatedly. The
number of times that the test method is to be executed is specified in the annotation.
The scope of execution to be repeated includes execution of the test method itself as well
as any set up or tear down of the test fixture.
@Repeat(10)
@Test
public void testProcessRepeatedly() {
// ...
}

15.4.4 Meta-Annotation Support for Testing

It is possible to use most test-related annotations as meta-annotations in order to create
custom composed annotations and reduce configuration duplication across a test suite.
Each of the following may be used as meta-annotations in conjunction with the
TestContext framework.
@BootstrapWith
@ContextConfiguration
@ContextHierarchy
@ActiveProfiles
@TestPropertySource
@DirtiesContext
@WebAppConfiguration
@TestExecutionListeners
@Transactional
@BeforeTransaction
@AfterTransaction
@Commit
@Rollback
@Sql
@SqlConfig

25/08/2016 12:10

Spring Framework Reference Documentation

428 de 1194

@Repeat
@Timed
@IfProfileValue
@ProfileValueSourceConfiguration
For example, if we discover that we are repeating the following configuration across our
JUnit 4 based test suite
@RunWith(SpringRunner.class)
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
@ActiveProfiles("dev")
@Transactional
public class OrderRepositoryTests { }
@RunWith(SpringRunner.class)
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
@ActiveProfiles("dev")
@Transactional
public class UserRepositoryTests { }

We can reduce the above duplication by introducing a custom composed annotation that
centralizes the common test configuration like this:
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@ContextConfiguration({"/app-config.xml", "/test-data-access-config.xml"})
@ActiveProfiles("dev")
@Transactional
public @interface TransactionalDevTest { }

Then we can use our custom @TransactionalDevTest annotation to simplify the

configuration of individual test classes as follows:
@RunWith(SpringRunner.class)
@TransactionalDevTest
public class OrderRepositoryTests { }
@RunWith(SpringRunner.class)
@TransactionalDevTest
public class UserRepositoryTests { }

For further details, consult the Spring Annotation Programming Model.

15.5 Spring TestContext Framework

25/08/2016 12:10

Spring Framework Reference Documentation

429 de 1194

The Spring TestContext Framework (located in the

org.springframework.test.context package) provides generic, annotation-driven
unit and integration testing support that is agnostic of the testing framework in use. The
TestContext framework also places a great deal of importance on convention over
configuration with reasonable defaults that can be overridden through annotation-based
configuration.
In addition to generic testing infrastructure, the TestContext framework provides explicit
support for JUnit 4 and TestNG in the form of abstract support classes. For JUnit 4,
Spring also provides a custom JUnit Runner and custom JUnit Rules that allow one to
write so-called POJO test classes. POJO test classes are not required to extend a
particular class hierarchy.
The following section provides an overview of the internals of the TestContext framework.
If you are only interested in using the framework and not necessarily interested in
extending it with your own custom listeners or custom loaders, feel free to go directly to
the configuration (context management, dependency injection, transaction management),
support classes, and annotation support sections.

15.5.1 Key abstractions

The core of the framework consists of the TestContextManager class and the
TestContext , TestExecutionListener , and SmartContextLoader interfaces. A
TestContextManager is created per test class (e.g., for the execution of all test
methods within a single test class in JUnit 4). The TestContextManager in turn
manages a TestContext that holds the context of the current test. The
TestContextManager also updates the state of the TestContext as the test
progresses and delegates to TestExecutionListener implementations, which
instrument the actual test execution by providing dependency injection, managing
transactions, and so on. A SmartContextLoader is responsible for loading an
ApplicationContext for a given test class. Consult the javadocs and the Spring test
suite for further information and examples of various implementations.

TestContext
TestContext encapsulates the context in which a test is executed, agnostic of the
actual testing framework in use, and provides context management and caching support
for the test instance for which it is responsible. The TestContext also delegates to a
SmartContextLoader to load an ApplicationContext if requested.

25/08/2016 12:10

Spring Framework Reference Documentation

430 de 1194

TestContextManager
TestContextManager is the main entry point into the Spring TestContext Framework,
which manages a single TestContext and signals events to each registered
TestExecutionListener at well-defined test execution points:
prior to any before class or before all methods of a particular testing framework
test instance post-processing
prior to any before or before each methods of a particular testing framework
after any after or after each methods of a particular testing framework
after any after class or after all methods of a particular testing framework

TestExecutionListener
TestExecutionListener defines the API for reacting to test execution events published
by the TestContextManager with which the listener is registered. See Section 15.5.3,
TestExecutionListener configuration.

Context Loaders
ContextLoader is a strategy interface that was introduced in Spring 2.5 for loading an
ApplicationContext for an integration test managed by the Spring TestContext
Framework. Implement SmartContextLoader instead of this interface in order to
provide support for annotated classes, active bean definition profiles, test property
sources, context hierarchies, and WebApplicationContext support.
SmartContextLoader is an extension of the ContextLoader interface introduced in
Spring 3.1. The SmartContextLoader SPI supersedes the ContextLoader SPI that
was introduced in Spring 2.5. Specifically, a SmartContextLoader can choose to
process resource locations , annotated classes , or context initializers .
Furthermore, a SmartContextLoader can set active bean definition profiles and test
property sources in the context that it loads.
Spring provides the following implementations:
DelegatingSmartContextLoader : one of two default loaders which delegates
internally to an AnnotationConfigContextLoader , a
GenericXmlContextLoader , or a GenericGroovyXmlContextLoader depending
either on the configuration declared for the test class or on the presence of default
locations or default configuration classes. Groovy support is only enabled if Groovy is
on the classpath.
WebDelegatingSmartContextLoader : one of two default loaders which delegates

25/08/2016 12:10

Spring Framework Reference Documentation

431 de 1194

internally to an AnnotationConfigWebContextLoader , a
GenericXmlWebContextLoader , or a GenericGroovyXmlWebContextLoader
depending either on the configuration declared for the test class or on the presence
of default locations or default configuration classes. A web ContextLoader will only
be used if @WebAppConfiguration is present on the test class. Groovy support is
only enabled if Groovy is on the classpath.
AnnotationConfigContextLoader : loads a standard ApplicationContext from
annotated classes.
AnnotationConfigWebContextLoader : loads a WebApplicationContext from
annotated classes.
GenericGroovyXmlContextLoader : loads a standard ApplicationContext from
resource locations that are either Groovy scripts or XML configuration files.
GenericGroovyXmlWebContextLoader : loads a WebApplicationContext from
resource locations that are either Groovy scripts or XML configuration files.
GenericXmlContextLoader : loads a standard ApplicationContext from XML
resource locations.
GenericXmlWebContextLoader : loads a WebApplicationContext from XML
resource locations.
GenericPropertiesContextLoader : loads a standard ApplicationContext from
Java Properties files.

15.5.2 Bootstrapping the TestContext framework

The default configuration for the internals of the Spring TestContext Framework is
sufficient for all common use cases. However, there are times when a development team
or third party framework would like to change the default ContextLoader , implement a
custom TestContext or ContextCache , augment the default sets of
ContextCustomizerFactory and TestExecutionListener implementations, etc. For
such low level control over how the TestContext framework operates, Spring provides a
bootstrapping strategy.
TestContextBootstrapper defines the SPI for bootstrapping the TestContext
framework. A TestContextBootstrapper is used by the TestContextManager to load
the TestExecutionListener implementations for the current test and to build the
TestContext that it manages. A custom bootstrapping strategy can be configured for a
test class (or test class hierarchy) via @BootstrapWith , either directly or as a
meta-annotation. If a bootstrapper is not explicitly configured via @BootstrapWith ,
either the DefaultTestContextBootstrapper or the WebTestContextBootstrapper
will be used, depending on the presence of @WebAppConfiguration .

25/08/2016 12:10

Spring Framework Reference Documentation

432 de 1194

Since the TestContextBootstrapper SPI is likely to change in the future in order to

accommodate new requirements, implementers are strongly encouraged not to
implement this interface directly but rather to extend
AbstractTestContextBootstrapper or one of its concrete subclasses instead.

15.5.3 TestExecutionListener configuration

Spring provides the following TestExecutionListener implementations that are
registered by default, exactly in this order.
ServletTestExecutionListener : configures Servlet API mocks for a
WebApplicationContext
DirtiesContextBeforeModesTestExecutionListener : handles the
@DirtiesContext annotation for before modes
DependencyInjectionTestExecutionListener : provides dependency injection
for the test instance
DirtiesContextTestExecutionListener : handles the @DirtiesContext
annotation for after modes
TransactionalTestExecutionListener : provides transactional test execution
with default rollback semantics
SqlScriptsTestExecutionListener : executes SQL scripts configured via the
@Sql annotation

Registering custom TestExecutionListeners

Custom TestExecutionListener s can be registered for a test class and its subclasses
via the @TestExecutionListeners annotation. See annotation support and the
javadocs for @TestExecutionListeners for details and examples.

Automatic discovery of default TestExecutionListeners

Registering custom TestExecutionListener s via @TestExecutionListeners is
suitable for custom listeners that are used in limited testing scenarios; however, it can
become cumbersome if a custom listener needs to be used across a test suite. Since
Spring Framework 4.1, this issue is addressed via support for automatic discovery of
default TestExecutionListener implementations via the SpringFactoriesLoader
mechanism.
Specifically, the spring-test module declares all core default
TestExecutionListener s under the

25/08/2016 12:10

Spring Framework Reference Documentation

433 de 1194

META-INF/spring.factories properties file. Third-party frameworks and developers

can contribute their own TestExecutionListener s to the list of default listeners in the
same manner via their own META-INF/spring.factories properties file.

Ordering TestExecutionListeners
When the TestContext framework discovers default TestExecutionListener s via the
aforementioned SpringFactoriesLoader mechanism, the instantiated listeners are
sorted using Springs AnnotationAwareOrderComparator which honors Springs
Ordered interface and @Order annotation for ordering.
AbstractTestExecutionListener and all default TestExecutionListener s
provided by Spring implement Ordered with appropriate values. Third-party frameworks
and developers should therefore make sure that their default TestExecutionListener s
are registered in the proper order by implementing Ordered or declaring @Order .
Consult the javadocs for the getOrder() methods of the core default
TestExecutionListener s for details on what values are assigned to each core listener.

Merging TestExecutionListeners
If a custom TestExecutionListener is registered via @TestExecutionListeners ,
the default listeners will not be registered. In most common testing scenarios, this
effectively forces the developer to manually declare all default listeners in addition to any
custom listeners. The following listing demonstrates this style of configuration.
@ContextConfiguration
@TestExecutionListeners({
MyCustomTestExecutionListener.class,
ServletTestExecutionListener.class,
DirtiesContextBeforeModesTestExecutionListener.class,
DependencyInjectionTestExecutionListener.class,
DirtiesContextTestExecutionListener.class,
TransactionalTestExecutionListener.class,
SqlScriptsTestExecutionListener.class
})
public class MyTest {
// class body...
}

The challenge with this approach is that it requires that the developer know exactly which
listeners are registered by default. Moreover, the set of default listeners can change from
release to releasefor example, SqlScriptsTestExecutionListener was introduced
in Spring Framework 4.1, and DirtiesContextBeforeModesTestExecutionListener

25/08/2016 12:10

Spring Framework Reference Documentation

434 de 1194

Security register their own default TestExecutionListener s via the aforementioned

automatic discovery mechanism.
To avoid having to be aware of and re-declare all default listeners, the mergeMode
attribute of @TestExecutionListeners can be set to
MergeMode.MERGE_WITH_DEFAULTS . MERGE_WITH_DEFAULTS indicates that locally
declared listeners should be merged with the default listeners. The merging algorithm
ensures that duplicates are removed from the list and that the resulting set of merged
listeners is sorted according to the semantics of AnnotationAwareOrderComparator as
described in the section called Ordering TestExecutionListeners. If a listener implements
Ordered or is annotated with @Order it can influence the position in which it is merged
with the defaults; otherwise, locally declared listeners will simply be appended to the list
of default listeners when merged.
For example, if the MyCustomTestExecutionListener class in the previous example
configures its order value (for example, 500 ) to be less than the order of the
ServletTestExecutionListener (which happens to be 1000 ), the
MyCustomTestExecutionListener can then be automatically merged with the list of
defaults in front of the ServletTestExecutionListener , and the previous example
could be replaced with the following.
@ContextConfiguration
@TestExecutionListeners(
listeners = MyCustomTestExecutionListener.class,
mergeMode = MERGE_WITH_DEFAULTS
)
public class MyTest {
// class body...
}

15.5.4 Context management

Each TestContext provides context management and caching support for the test
instance it is responsible for. Test instances do not automatically receive access to the
configured ApplicationContext . However, if a test class implements the
ApplicationContextAware interface, a reference to the ApplicationContext is
supplied to the test instance. Note that AbstractJUnit4SpringContextTests and
AbstractTestNGSpringContextTests implement ApplicationContextAware and
therefore provide access to the ApplicationContext automatically.

25/08/2016 12:10

Spring Framework Reference Documentation

435 de 1194

As an alternative to implementing the ApplicationContextAware

interface, you can inject the application context for your test class through
the @Autowired annotation on either a field or setter method. For
example:
@RunWith(SpringRunner.class)
@ContextConfiguration
public class MyTest {
@Autowired
private ApplicationContext applicationContext;
// class body...
}

Similarly, if your test is configured to load a WebApplicationContext , you

can inject the web application context into your test as follows:
@RunWith(SpringRunner.class)
@WebAppConfiguration
@ContextConfiguration
public class MyWebAppTest {
@Autowired
private WebApplicationContext wac;
// class body...
}

Dependency injection via @Autowired is provided by the

DependencyInjectionTestExecutionListener which is configured by
default (see Section 15.5.5, Dependency injection of test fixtures).

Test classes that use the TestContext framework do not need to extend any particular
class or implement a specific interface to configure their application context. Instead,
configuration is achieved simply by declaring the @ContextConfiguration annotation
at the class level. If your test class does not explicitly declare application context resource
locations or annotated classes , the configured ContextLoader determines how to
load a context from a default location or default configuration classes. In addition to
context resource locations and annotated classes , an application context can also
be configured via application context initializers .
The following sections explain how to configure an ApplicationContext via XML
configuration files, Groovy scripts, annotated classes (typically @Configuration
classes), or context initializers using Springs @ContextConfiguration annotation.
Alternatively, you can implement and configure your own custom SmartContextLoader

25/08/2016 12:10

Spring Framework Reference Documentation

436 de 1194

for advanced use cases.

Context configuration with XML resources

To load an ApplicationContext for your tests using XML configuration files, annotate
your test class with @ContextConfiguration and configure the locations attribute
with an array that contains the resource locations of XML configuration metadata. A plain
or relative pathfor example "context.xml" will be treated as a classpath resource
that is relative to the package in which the test class is defined. A path starting with a
slash is treated as an absolute classpath location, for example
"/org/example/config.xml" . A path which represents a resource URL (i.e., a path
prefixed with classpath: , file: , http: , etc.) will be used as is.
@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from "/app-config.xml" and
// "/test-config.xml" in the root of the classpath
@ContextConfiguration(locations={"/app-config.xml", "/test-config.xml"})
public class MyTest {
// class body...
}

@ContextConfiguration supports an alias for the locations attribute through the

standard Java value attribute. Thus, if you do not need to declare additional attributes in
@ContextConfiguration , you can omit the declaration of the locations attribute
name and declare the resource locations by using the shorthand format demonstrated in
the following example.
@RunWith(SpringRunner.class)
@ContextConfiguration({"/app-config.xml", "/test-config.xml"})
public class MyTest {
// class body...
}

If you omit both the locations and value attributes from the
@ContextConfiguration annotation, the TestContext framework will attempt to detect a
default XML resource location. Specifically, GenericXmlContextLoader and
GenericXmlWebContextLoader detect a default location based on the name of the test
class. If your class is named com.example.MyTest , GenericXmlContextLoader loads
your application context from "classpath:com/example/MyTest-context.xml" .
package com.example;
@RunWith(SpringRunner.class)

25/08/2016 12:10

Spring Framework Reference Documentation

437 de 1194

// ApplicationContext will be loaded from

// "classpath:com/example/MyTest-context.xml"
@ContextConfiguration
public class MyTest {
// class body...
}

Context configuration with Groovy scripts

To load an ApplicationContext for your tests using Groovy scripts that utilize the
Groovy Bean Definition DSL, annotate your test class with @ContextConfiguration
and configure the locations or value attribute with an array that contains the
resource locations of Groovy scripts. Resource lookup semantics for Groovy scripts are
the same as those described for XML configuration files.

Support for using Groovy scripts to load an ApplicationContext in the

Spring TestContext Framework is enabled automatically if Groovy is on the
classpath.

@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from "/AppConfig.groovy" and
// "/TestConfig.groovy" in the root of the classpath
@ContextConfiguration({"/AppConfig.groovy", "/TestConfig.Groovy"})
public class MyTest {
// class body...
}

If you omit both the locations and value attributes from the
@ContextConfiguration annotation, the TestContext framework will attempt to detect a
default Groovy script. Specifically, GenericGroovyXmlContextLoader and
GenericGroovyXmlWebContextLoader detect a default location based on the name of
the test class. If your class is named com.example.MyTest , the Groovy context loader
will load your application context from
"classpath:com/example/MyTestContext.groovy" .
package com.example;
@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from
// "classpath:com/example/MyTestContext.groovy"
@ContextConfiguration
public class MyTest {

25/08/2016 12:10

Spring Framework Reference Documentation

438 de 1194

// class body...
}

Both XML configuration files and Groovy scripts can be declared

simultaneously via the locations or value attribute of
@ContextConfiguration . If the path to a configured resource location ends
with .xml it will be loaded using an XmlBeanDefinitionReader ; otherwise it
will be loaded using a GroovyBeanDefinitionReader .
The following listing demonstrates how to combine both in an integration test.
@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from
// "/app-config.xml" and "/TestConfig.groovy"
@ContextConfiguration({ "/app-config.xml", "/TestConfig.groovy" })
public class MyTest {
// class body...
}

Context configuration with annotated classes

To load an ApplicationContext for your tests using annotated classes (see
Section 7.12, Java-based container configuration), annotate your test class with
@ContextConfiguration and configure the classes attribute with an array that
contains references to annotated classes.
@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from AppConfig and TestConfig
@ContextConfiguration(classes = {AppConfig.class, TestConfig.class})
public class MyTest {
// class body...
}

The term annotated class can refer to any of the following.

A class annotated with @Configuration
A component (i.e., a class annotated with @Component , @Service ,
@Repository , etc.)
A JSR-330 compliant class that is annotated with javax.inject
annotations
Any other class that contains @Bean -methods
Consult the javadocs of @Configuration and @Bean for further
information regarding the configuration and semantics of annotated classes,

25/08/2016 12:10

Spring Framework Reference Documentation

439 de 1194

paying special attention to the discussion of `@Bean` Lite Mode.

If you omit the classes attribute from the @ContextConfiguration annotation, the
TestContext framework will attempt to detect the presence of default configuration
classes. Specifically, AnnotationConfigContextLoader and
AnnotationConfigWebContextLoader will detect all static nested classes of the test
class that meet the requirements for configuration class implementations as specified in
the @Configuration javadocs. In the following example, the OrderServiceTest class
declares a static nested configuration class named Config that will be automatically
used to load the ApplicationContext for the test class. Note that the name of the
configuration class is arbitrary. In addition, a test class can contain more than one
static nested configuration class if desired.
@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from the
// static nested Config class
@ContextConfiguration
public class OrderServiceTest {
@Configuration
static class Config {
// this bean will be injected into the OrderServiceTest class
@Bean
public OrderService orderService() {
OrderService orderService = new OrderServiceImpl();
// set properties, etc.
return orderService;
}
}
@Autowired
private OrderService orderService;
@Test
public void testOrderService() {
// test the orderService
}
}

Mixing XML, Groovy scripts, and annotated classes

It may sometimes be desirable to mix XML configuration files, Groovy scripts, and

25/08/2016 12:10

Spring Framework Reference Documentation

440 de 1194

annotated classes (i.e., typically @Configuration classes) to configure an

ApplicationContext for your tests. For example, if you use XML configuration in
production, you may decide that you want to use @Configuration classes to configure
specific Spring-managed components for your tests, or vice versa.
Furthermore, some third-party frameworks (like Spring Boot) provide first-class support
for loading an ApplicationContext from different types of resources simultaneously
(e.g., XML configuration files, Groovy scripts, and @Configuration classes). The Spring
Framework historically has not supported this for standard deployments. Consequently,
most of the SmartContextLoader implementations that the Spring Framework delivers
in the spring-test module support only one resource type per test context; however,
this does not mean that you cannot use both. One exception to the general rule is that the
GenericGroovyXmlContextLoader and GenericGroovyXmlWebContextLoader
support both XML configuration files and Groovy scripts simultaneously. Furthermore,
third-party frameworks may choose to support the declaration of both locations and
classes via @ContextConfiguration , and with the standard testing support in the
TestContext framework, you have the following options.
If you want to use resource locations (e.g., XML or Groovy) and @Configuration
classes to configure your tests, you will have to pick one as the entry point, and that one
will have to include or import the other. For example, in XML or Groovy scripts you can
include @Configuration classes via component scanning or define them as normal
Spring beans; whereas, in a @Configuration class you can use @ImportResource to
import XML configuration files or Groovy scripts. Note that this behavior is semantically
equivalent to how you configure your application in production: in production configuration
you will define either a set of XML or Groovy resource locations or a set of
@Configuration classes that your production ApplicationContext will be loaded
from, but you still have the freedom to include or import the other type of configuration.

Context configuration with context initializers

To configure an ApplicationContext for your tests using context initializers, annotate
your test class with @ContextConfiguration and configure the initializers
attribute with an array that contains references to classes that implement
ApplicationContextInitializer . The declared context initializers will then be used
to initialize the ConfigurableApplicationContext that is loaded for your tests. Note
that the concrete ConfigurableApplicationContext type supported by each declared
initializer must be compatible with the type of ApplicationContext created by the
SmartContextLoader in use (i.e., typically a GenericApplicationContext ).
Furthermore, the order in which the initializers are invoked depends on whether they

25/08/2016 12:10

Spring Framework Reference Documentation

441 de 1194

or the standard @Priority annotation.

@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from TestConfig
// and initialized by TestAppCtxInitializer
@ContextConfiguration(
classes = TestConfig.class,
initializers = TestAppCtxInitializer.class)
public class MyTest {
// class body...
}

It is also possible to omit the declaration of XML configuration files, Groovy scripts, or
annotated classes in @ContextConfiguration entirely and instead declare only
ApplicationContextInitializer classes which are then responsible for registering
beans in the contextfor example, by programmatically loading bean definitions from
XML files or configuration classes.
@RunWith(SpringRunner.class)
// ApplicationContext will be initialized by EntireAppInitializer
// which presumably registers beans in the context
@ContextConfiguration(initializers = EntireAppInitializer.class)
public class MyTest {
// class body...
}

Context configuration inheritance

@ContextConfiguration supports boolean inheritLocations and
inheritInitializers attributes that denote whether resource locations or annotated
classes and context initializers declared by superclasses should be inherited. The default
value for both flags is true . This means that a test class inherits the resource locations
or annotated classes as well as the context initializers declared by any superclasses.
Specifically, the resource locations or annotated classes for a test class are appended to
the list of resource locations or annotated classes declared by superclasses. Similarly, the
initializers for a given test class will be added to the set of initializers defined by test
superclasses. Thus, subclasses have the option of extending the resource locations,
annotated classes, or context initializers.
If the inheritLocations or inheritInitializers attribute in
@ContextConfiguration is set to false , the resource locations or annotated classes
and the context initializers, respectively, for the test class shadow and effectively replace
the configuration defined by superclasses.

25/08/2016 12:10

Spring Framework Reference Documentation

442 de 1194

In the following example that uses XML resource locations, the ApplicationContext
for ExtendedTest will be loaded from "base-config.xml" and "extended-config.xml", in
that order. Beans defined in "extended-config.xml" may therefore override (i.e., replace)
those defined in "base-config.xml".
@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from "/base-config.xml"
// in the root of the classpath
@ContextConfiguration("/base-config.xml")
public class BaseTest {
// class body...
}
// ApplicationContext will be loaded from "/base-config.xml" and
// "/extended-config.xml" in the root of the classpath
@ContextConfiguration("/extended-config.xml")
public class ExtendedTest extends BaseTest {
// class body...
}

Similarly, in the following example that uses annotated classes, the

ApplicationContext for ExtendedTest will be loaded from the BaseConfig and
ExtendedConfig classes, in that order. Beans defined in ExtendedConfig may
therefore override (i.e., replace) those defined in BaseConfig .
@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from BaseConfig
@ContextConfiguration(classes = BaseConfig.class)
public class BaseTest {
// class body...
}
// ApplicationContext will be loaded from BaseConfig and ExtendedConfig
@ContextConfiguration(classes = ExtendedConfig.class)
public class ExtendedTest extends BaseTest {
// class body...
}

In the following example that uses context initializers, the ApplicationContext for
ExtendedTest will be initialized using BaseInitializer and ExtendedInitializer .
Note, however, that the order in which the initializers are invoked depends on whether
they implement Springs Ordered interface or are annotated with Springs @Order
annotation or the standard @Priority annotation.
@RunWith(SpringRunner.class)

25/08/2016 12:10

Spring Framework Reference Documentation

443 de 1194

// ApplicationContext will be initialized by BaseInitializer

@ContextConfiguration(initializers = BaseInitializer.class)
public class BaseTest {
// class body...
}
// ApplicationContext will be initialized by BaseInitializer
// and ExtendedInitializer
@ContextConfiguration(initializers = ExtendedInitializer.class)
public class ExtendedTest extends BaseTest {
// class body...
}

Context configuration with environment profiles

Spring 3.1 introduced first-class support in the framework for the notion of environments
and profiles (a.k.a., bean definition profiles), and integration tests can be configured to
activate particular bean definition profiles for various testing scenarios. This is achieved
by annotating a test class with the @ActiveProfiles annotation and supplying a list of
profiles that should be activated when loading the ApplicationContext for the test.

@ActiveProfiles may be used with any implementation of the new

SmartContextLoader SPI, but @ActiveProfiles is not supported with
implementations of the older ContextLoader SPI.

Lets take a look at some examples with XML configuration and @Configuration
classes.

<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jdbc="http://www.springframework.org/schema/jdbc"
xmlns:jee="http://www.springframework.org/schema/jee"
xsi:schemaLocation="...">
<bean id="transferService"
class="com.bank.service.internal.DefaultTransferService">
<constructor-arg ref="accountRepository"/>
<constructor-arg ref="feePolicy"/>
</bean>
<bean id="accountRepository"
class="com.bank.repository.internal.JdbcAccountRepository">
<constructor-arg ref="dataSource"/>

25/08/2016 12:10

Spring Framework Reference Documentation

444 de 1194

</bean>
<bean id="feePolicy"
class="com.bank.service.internal.ZeroFeePolicy"/>
<beans profile="dev">
<jdbc:embedded-database id="dataSource">
<jdbc:script
location="classpath:com/bank/config/sql/schema.sql"/>
<jdbc:script
location="classpath:com/bank/config/sql/test-data.sql"/>
</jdbc:embedded-database>
</beans>
<beans profile="production">
<jee:jndi-lookup id="dataSource" jndi-name="java:comp/env/jdbc/datasource"
</beans>
<beans profile="default">
<jdbc:embedded-database id="dataSource">
<jdbc:script
location="classpath:com/bank/config/sql/schema.sql"/>
</jdbc:embedded-database>
</beans>
</beans>
package com.bank.service;
@RunWith(SpringRunner.class)
// ApplicationContext will be loaded from "classpath:/app-config.xml"
@ContextConfiguration("/app-config.xml")
@ActiveProfiles("dev")
public class TransferServiceTest {
@Autowired
private TransferService transferService;
@Test
public void testTransferService() {
// test the transferService
}
}

When TransferServiceTest is run, its ApplicationContext will be loaded from the

app-config.xml configuration file in the root of the classpath. If you inspect
app-config.xml youll notice that the accountRepository bean has a dependency on

25/08/2016 12:10

Spring Framework Reference Documentation

445 de 1194

a dataSource bean; however, dataSource is not defined as a top-level bean. Instead,

dataSource is defined three times: in the production profile, the dev profile, and the
default profile.
By annotating TransferServiceTest with @ActiveProfiles("dev") we instruct the
Spring TestContext Framework to load the ApplicationContext with the active profiles
set to {"dev"} . As a result, an embedded database will be created and populated with
test data, and the accountRepository bean will be wired with a reference to the
development DataSource . And thats likely what we want in an integration test.
It is sometimes useful to assign beans to a default profile. Beans within the default
profile are only included when no other profile is specifically activated. This can be used
to define fallback beans to be used in the applications default state. For example, you
may explicitly provide a data source for dev and production profiles, but define an
in-memory data source as a default when neither of these is active.
The following code listings demonstrate how to implement the same configuration and
integration test but using @Configuration classes instead of XML.
@Configuration
@Profile("dev")
public class StandaloneDataConfig {
@Bean
public DataSource dataSource() {
return new EmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("classpath:com/bank/config/sql/schema.sql")
.addScript("classpath:com/bank/config/sql/test-data.sql")
.build();
}
}
@Configuration
@Profile("production")
public class JndiDataConfig {
@Bean(destroyMethod="")
public DataSource dataSource() throws Exception {
Context ctx = new InitialContext();
return (DataSource) ctx.lookup("java:comp/env/jdbc/datasource");
}
}
@Configuration

25/08/2016 12:10

Spring Framework Reference Documentation

446 de 1194

@Profile("default")
public class DefaultDataConfig {
@Bean
public DataSource dataSource() {
return new EmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("classpath:com/bank/config/sql/schema.sql")
.build();
}
}
@Configuration
public class TransferServiceConfig {
@Autowired DataSource dataSource;
@Bean
public TransferService transferService() {
return new DefaultTransferService(accountRepository(), feePolicy());
}
@Bean
public AccountRepository accountRepository() {
return new JdbcAccountRepository(dataSource);
}
@Bean
public FeePolicy feePolicy() {
return new ZeroFeePolicy();
}
}
package com.bank.service;
@RunWith(SpringRunner.class)
@ContextConfiguration(classes = {
TransferServiceConfig.class,
StandaloneDataConfig.class,
JndiDataConfig.class,
DefaultDataConfig.class})
@ActiveProfiles("dev")
public class TransferServiceTest {
@Autowired
private TransferService transferService;

25/08/2016 12:10

Spring Framework Reference Documentation

447 de 1194

@Test
public void testTransferService() {
// test the transferService
}
}

In this variation, we have split the XML configuration into four independent
@Configuration classes:
TransferServiceConfig : acquires a dataSource via dependency injection using
@Autowired
StandaloneDataConfig : defines a dataSource for an embedded database
suitable for developer tests
JndiDataConfig : defines a dataSource that is retrieved from JNDI in a production
environment
DefaultDataConfig : defines a dataSource for a default embedded database in
case no profile is active
As with the XML-based configuration example, we still annotate TransferServiceTest
with @ActiveProfiles("dev") , but this time we specify all four configuration classes
via the @ContextConfiguration annotation. The body of the test class itself remains
completely unchanged.
It is often the case that a single set of profiles is used across multiple test classes within a
given project. Thus, to avoid duplicate declarations of the @ActiveProfiles annotation
it is possible to declare @ActiveProfiles once on a base class, and subclasses will
automatically inherit the @ActiveProfiles configuration from the base class. In the
following example, the declaration of @ActiveProfiles (as well as other annotations)
has been moved to an abstract superclass, AbstractIntegrationTest .
package com.bank.service;
@RunWith(SpringRunner.class)
@ContextConfiguration(classes = {
TransferServiceConfig.class,
StandaloneDataConfig.class,
JndiDataConfig.class,
DefaultDataConfig.class})
@ActiveProfiles("dev")
public abstract class AbstractIntegrationTest {
}
package com.bank.service;

25/08/2016 12:10

Spring Framework Reference Documentation

448 de 1194

// "dev" profile inherited from superclass

public class TransferServiceTest extends AbstractIntegrationTest {
@Autowired
private TransferService transferService;
@Test
public void testTransferService() {
// test the transferService
}
}

@ActiveProfiles also supports an inheritProfiles attribute that can be used to

disable the inheritance of active profiles.
package com.bank.service;
// "dev" profile overridden with "production"
@ActiveProfiles(profiles = "production", inheritProfiles = false)
public class ProductionTransferServiceTest extends AbstractIntegrationTest {
// test body
}

Furthermore, it is sometimes necessary to resolve active profiles for tests

programmatically instead of declarativelyfor example, based on:
the current operating system
whether tests are being executed on a continuous integration build server
the presence of certain environment variables
the presence of custom class-level annotations
etc.
To resolve active bean definition profiles programmatically, simply implement a custom
ActiveProfilesResolver and register it via the resolver attribute of
@ActiveProfiles . The following example demonstrates how to implement and register
a custom OperatingSystemActiveProfilesResolver . For further information, refer to
the corresponding javadocs.
package com.bank.service;
// "dev" profile overridden programmatically via a custom resolver
@ActiveProfiles(
resolver = OperatingSystemActiveProfilesResolver.class,
inheritProfiles = false)

25/08/2016 12:10

Spring Framework Reference Documentation

449 de 1194

public class TransferServiceTest extends AbstractIntegrationTest {

// test body
}
package com.bank.service.test;

public class OperatingSystemActiveProfilesResolver implements ActiveProfilesResolver {

@Override
String[] resolve(Class<?> testClass) {
String profile = ...;
// determine the value of profile based on the operating system
return new String[] {profile};
}
}

Context configuration with test property sources

Spring 3.1 introduced first-class support in the framework for the notion of an environment
with a hierarchy of property sources, and since Spring 4.1 integration tests can be
configured with test-specific property sources. In contrast to the @PropertySource
annotation used on @Configuration classes, the @TestPropertySource annotation
can be declared on a test class to declare resource locations for test properties files or
inlined properties. These test property sources will be added to the set of
PropertySources in the Environment for the ApplicationContext loaded for the
annotated integration test.

@TestPropertySource may be used with any implementation of the

SmartContextLoader SPI, but @TestPropertySource is not supported
with implementations of the older ContextLoader SPI.
Implementations of SmartContextLoader gain access to merged test
property source values via the getPropertySourceLocations() and
getPropertySourceProperties() methods in
MergedContextConfiguration .

Declaring test property sources

Test properties files can be configured via the locations or value attribute of
@TestPropertySource as shown in the following example.
Both traditional and XML-based properties file formats are supportedfor example,
"classpath:/com/example/test.properties" or "file:///path/to/file.xml" .

25/08/2016 12:10

Spring Framework Reference Documentation

450 de 1194

Each path will be interpreted as a Spring Resource . A plain pathfor example,

"test.properties" will be treated as a classpath resource that is relative to the
package in which the test class is defined. A path starting with a slash will be treated as
an absolute classpath resource, for example: "/org/example/test.xml" . A path which
references a URL (e.g., a path prefixed with classpath: , file: , http: , etc.) will be
loaded using the specified resource protocol. Resource location wildcards (e.g.
*/.properties ) are not permitted: each location must evaluate to exactly one
.properties or .xml resource.
@ContextConfiguration
@TestPropertySource("/test.properties")
public class MyIntegrationTests {
// class body...
}

Inlined properties in the form of key-value pairs can be configured via the properties
attribute of @TestPropertySource as shown in the following example. All key-value
pairs will be added to the enclosing Environment as a single test PropertySource
with the highest precedence.
The supported syntax for key-value pairs is the same as the syntax defined for entries in
a Java properties file:
"key=value"
"key:value"
"key value"
@ContextConfiguration
@TestPropertySource(properties = {"timezone = GMT", "port: 4242"})
public class MyIntegrationTests {
// class body...
}

Default properties file detection

If @TestPropertySource is declared as an empty annotation (i.e., without explicit values
for the locations or properties attributes), an attempt will be made to detect a
default properties file relative to the class that declared the annotation. For example, if the
annotated test class is com.example.MyTest , the corresponding default properties file is
"classpath:com/example/MyTest.properties" . If the default cannot be detected, an
IllegalStateException will be thrown.
Precedence

25/08/2016 12:10

Spring Framework Reference Documentation

451 de 1194

Test property sources have higher precedence than those loaded from the operating
systems environment or Java system properties as well as property sources added by
the application declaratively via @PropertySource or programmatically. Thus, test
property sources can be used to selectively override properties defined in system and
application property sources. Furthermore, inlined properties have higher precedence
than properties loaded from resource locations.
In the following example, the timezone and port properties as well as any properties
defined in "/test.properties" will override any properties of the same name that are
defined in system and application property sources. Furthermore, if the
"/test.properties" file defines entries for the timezone and port properties those
will be overridden by the inlined properties declared via the properties attribute.
@ContextConfiguration
@TestPropertySource(
locations = "/test.properties",
properties = {"timezone = GMT", "port: 4242"}
)
public class MyIntegrationTests {
// class body...
}

Inheriting and overriding test property sources

@TestPropertySource supports boolean inheritLocations and
inheritProperties attributes that denote whether resource locations for properties
files and inlined properties declared by superclasses should be inherited. The default
value for both flags is true . This means that a test class inherits the locations and
inlined properties declared by any superclasses. Specifically, the locations and inlined
properties for a test class are appended to the locations and inlined properties declared
by superclasses. Thus, subclasses have the option of extending the locations and inlined
properties. Note that properties that appear later will shadow (i.e.., override) properties of
the same name that appear earlier. In addition, the aforementioned precedence rules
apply for inherited test property sources as well.
If the inheritLocations or inheritProperties attribute in @TestPropertySource
is set to false , the locations or inlined properties, respectively, for the test class shadow
and effectively replace the configuration defined by superclasses.
In the following example, the ApplicationContext for BaseTest will be loaded using
only the "base.properties" file as a test property source. In contrast, the
ApplicationContext for ExtendedTest will be loaded using the
"base.properties" and "extended.properties" files as test property source

25/08/2016 12:10

Spring Framework Reference Documentation

452 de 1194

locations.
@TestPropertySource("base.properties")
@ContextConfiguration
public class BaseTest {
// ...
}
@TestPropertySource("extended.properties")
@ContextConfiguration
public class ExtendedTest extends BaseTest {
// ...
}

In the following example, the ApplicationContext for BaseTest will be loaded using
only the inlined key1 property. In contrast, the ApplicationContext for
ExtendedTest will be loaded using the inlined key1 and key2 properties.
@TestPropertySource(properties = "key1 = value1")
@ContextConfiguration
public class BaseTest {
// ...
}
@TestPropertySource(properties = "key2 = value2")
@ContextConfiguration
public class ExtendedTest extends BaseTest {
// ...
}

Loading a WebApplicationContext
Spring 3.2 introduced support for loading a WebApplicationContext in integration
tests. To instruct the TestContext framework to load a WebApplicationContext instead
of a standard ApplicationContext , simply annotate the respective test class with
@WebAppConfiguration .
The presence of @WebAppConfiguration on your test class instructs the TestContext
framework (TCF) that a WebApplicationContext (WAC) should be loaded for your
integration tests. In the background the TCF makes sure that a MockServletContext is
created and supplied to your tests WAC. By default the base resource path for your
MockServletContext will be set to "src/main/webapp". This is interpreted as a path
relative to the root of your JVM (i.e., normally the path to your project). If youre familiar
with the directory structure of a web application in a Maven project, youll know that

25/08/2016 12:10

Spring Framework Reference Documentation

453 de 1194

"src/main/webapp" is the default location for the root of your WAR. If you need to override
this default, simply provide an alternate path to the @WebAppConfiguration annotation
(e.g., @WebAppConfiguration("src/test/webapp") ). If you wish to reference a base
resource path from the classpath instead of the file system, just use Springs classpath:
prefix.
Please note that Springs testing support for WebApplicationContexts is on par with its
support for standard ApplicationContexts . When testing with a
WebApplicationContext you are free to declare XML configuration files, Groovy
scripts, or @Configuration classes via @ContextConfiguration . You are of course
also free to use any other test annotations such as @ActiveProfiles ,
@TestExecutionListeners , @Sql , @Rollback , etc.
The following examples demonstrate some of the various configuration options for
loading a WebApplicationContext .
Conventions.
@RunWith(SpringRunner.class)
// defaults to "file:src/main/webapp"
@WebAppConfiguration
// detects "WacTests-context.xml" in same package
// or static nested @Configuration class
@ContextConfiguration
public class WacTests {
//...
}

The above example demonstrates the TestContext frameworks support for convention
over configuration. If you annotate a test class with @WebAppConfiguration without
specifying a resource base path, the resource path will effectively default to "file:src/main
/webapp". Similarly, if you declare @ContextConfiguration without specifying resource
locations , annotated classes , or context initializers , Spring will attempt to
detect the presence of your configuration using conventions (i.e., "WacTests-context.xml"
in the same package as the WacTests class or static nested @Configuration classes).
Default resource semantics.
@RunWith(SpringRunner.class)
// file system resource

25/08/2016 12:10

Spring Framework Reference Documentation

454 de 1194

@WebAppConfiguration("webapp")
// classpath resource
@ContextConfiguration("/spring/test-servlet-config.xml")
public class WacTests {
//...
}

This example demonstrates how to explicitly declare a resource base path with
@WebAppConfiguration and an XML resource location with @ContextConfiguration .
The important thing to note here is the different semantics for paths with these two
annotations. By default, @WebAppConfiguration resource paths are file system based;
whereas, @ContextConfiguration resource locations are classpath based.
Explicit resource semantics.
@RunWith(SpringRunner.class)
// classpath resource
@WebAppConfiguration("classpath:test-web-resources")
// file system resource
@ContextConfiguration("file:src/main/webapp/WEB-INF/servlet-config.xml")
public class WacTests {
//...
}

In this third example, we see that we can override the default resource semantics for both
annotations by specifying a Spring resource prefix. Contrast the comments in this
example with the previous example.
To provide comprehensive web testing support, Spring 3.2 introduced a
ServletTestExecutionListener that is enabled by default. When testing against a
WebApplicationContext this TestExecutionListener sets up default thread-local state
via Spring Webs RequestContextHolder before each test method and creates a
MockHttpServletRequest , MockHttpServletResponse , and ServletWebRequest
based on the base resource path configured via @WebAppConfiguration .
ServletTestExecutionListener also ensures that the MockHttpServletResponse
and ServletWebRequest can be injected into the test instance, and once the test is
complete it cleans up thread-local state.
Once you have a WebApplicationContext loaded for your test you might find that you

25/08/2016 12:10

Spring Framework Reference Documentation

455 de 1194

perform assertions after invoking your web component. The following example
demonstrates which mocks can be autowired into your test instance. Note that the
WebApplicationContext and MockServletContext are both cached across the test
suite; whereas, the other mocks are managed per test method by the
ServletTestExecutionListener .
Injecting mocks.
@WebAppConfiguration
@ContextConfiguration
public class WacTests {
@Autowired
WebApplicationContext wac; // cached
@Autowired
MockServletContext servletContext; // cached
@Autowired
MockHttpSession session;
@Autowired
MockHttpServletRequest request;
@Autowired
MockHttpServletResponse response;
@Autowired
ServletWebRequest webRequest;
//...
}

Context caching
Once the TestContext framework loads an ApplicationContext (or
WebApplicationContext ) for a test, that context will be cached and reused for all
subsequent tests that declare the same unique context configuration within the same test
suite. To understand how caching works, it is important to understand what is meant by
unique and test suite.
An ApplicationContext can be uniquely identified by the combination of configuration
parameters that are used to load it. Consequently, the unique combination of
configuration parameters are used to generate a key under which the context is cached.
The TestContext framework uses the following configuration parameters to build the

25/08/2016 12:10

Spring Framework Reference Documentation

456 de 1194

context cache key:

locations (from @ContextConfiguration)
classes (from @ContextConfiguration)
contextInitializerClasses (from @ContextConfiguration)
contextCustomizers (from ContextCustomizerFactory)
contextLoader (from @ContextConfiguration)
parent (from @ContextHierarchy)
activeProfiles (from @ActiveProfiles)
propertySourceLocations (from @TestPropertySource)
propertySourceProperties (from @TestPropertySource)
resourceBasePath (from @WebAppConfiguration)
For example, if TestClassA specifies {"app-config.xml", "test-config.xml"} for
the locations (or value ) attribute of @ContextConfiguration , the TestContext
framework will load the corresponding ApplicationContext and store it in a static
context cache under a key that is based solely on those locations. So if TestClassB also
defines {"app-config.xml", "test-config.xml"} for its locations (either explicitly or
implicitly through inheritance) but does not define @WebAppConfiguration , a different
ContextLoader , different active profiles, different context initializers, different test
property sources, or a different parent context, then the same ApplicationContext will
be shared by both test classes. This means that the setup cost for loading an application
context is incurred only once (per test suite), and subsequent test execution is much
faster.

The Spring TestContext framework stores application contexts in a static

cache. This means that the context is literally stored in a static variable.
In other words, if tests execute in separate processes the static cache will
be cleared between each test execution, and this will effectively disable the
caching mechanism.
To benefit from the caching mechanism, all tests must run within the same
process or test suite. This can be achieved by executing all tests as a group
within an IDE. Similarly, when executing tests with a build framework such
as Ant, Maven, or Gradle it is important to make sure that the build
framework does not fork between tests. For example, if the forkMode for the
Maven Surefire plug-in is set to always or pertest , the TestContext
framework will not be able to cache application contexts between test
classes and the build process will run significantly slower as a result.

25/08/2016 12:10

Spring Framework Reference Documentation

457 de 1194

Since Spring Framework 4.3, the size of the context cache is bounded with a default
maximum size of 32. Whenever the maximum size is reached, a least recently used
(LRU) eviction policy is used to evict and close stale contexts. The maximum size can be
configured from the command line or a build script by setting a JVM system property
named spring.test.context.cache.maxSize . As an alternative, the same property
can be set programmatically via the SpringProperties API.
Since having a large number of application contexts loaded within a given test suite can
cause the suite to take an unnecessarily long time to execute, it is often beneficial to
know exactly how many contexts have been loaded and cached. To view the statistics for
the underlying context cache, simply set the log level for the
org.springframework.test.context.cache logging category to DEBUG .
In the unlikely case that a test corrupts the application context and requires reloading
for example, by modifying a bean definition or the state of an application objectyou can
annotate your test class or test method with @DirtiesContext (see the discussion of
@DirtiesContext in Section 15.4.1, Spring Testing Annotations). This instructs Spring
to remove the context from the cache and rebuild the application context before executing
the next test. Note that support for the @DirtiesContext annotation is provided by the
DirtiesContextBeforeModesTestExecutionListener and the
DirtiesContextTestExecutionListener which are enabled by default.

Context hierarchies
When writing integration tests that rely on a loaded Spring ApplicationContext , it is
often sufficient to test against a single context; however, there are times when it is
beneficial or even necessary to test against a hierarchy of ApplicationContext s. For
example, if you are developing a Spring MVC web application you will typically have a
root WebApplicationContext loaded via Springs ContextLoaderListener and a
child WebApplicationContext loaded via Springs DispatcherServlet . This results
in a parent-child context hierarchy where shared components and infrastructure
configuration are declared in the root context and consumed in the child context by
web-specific components. Another use case can be found in Spring Batch applications
where you often have a parent context that provides configuration for shared batch
infrastructure and a child context for the configuration of a specific batch job.
Since Spring Framework 3.2.2, it is possible to write integration tests that use context
hierarchies by declaring context configuration via the @ContextHierarchy annotation,
either on an individual test class or within a test class hierarchy. If a context hierarchy is
declared on multiple classes within a test class hierarchy it is also possible to merge or
override the context configuration for a specific, named level in the context hierarchy.

25/08/2016 12:10

Spring Framework Reference Documentation

458 de 1194

When merging configuration for a given level in the hierarchy the configuration resource
type (i.e., XML configuration files or annotated classes) must be consistent; otherwise, it
is perfectly acceptable to have different levels in a context hierarchy configured using
different resource types.
The following JUnit 4 based examples demonstrate common configuration scenarios for
integration tests that require the use of context hierarchies.
ControllerIntegrationTests represents a typical integration testing scenario for a
Spring MVC web application by declaring a context hierarchy consisting of two levels, one
for the root WebApplicationContext (loaded using the TestAppConfig
@Configuration class) and one for the dispatcher servlet WebApplicationContext
(loaded using the WebConfig @Configuration class). The WebApplicationContext
that is autowired into the test instance is the one for the child context (i.e., the lowest
context in the hierarchy).
@RunWith(SpringRunner.class)
@WebAppConfiguration
@ContextHierarchy({
@ContextConfiguration(classes = TestAppConfig.class),
@ContextConfiguration(classes = WebConfig.class)
})
public class ControllerIntegrationTests {
@Autowired
private WebApplicationContext wac;
// ...
}

The following test classes define a context hierarchy within a test class hierarchy.
AbstractWebTests declares the configuration for a root WebApplicationContext in a
Spring-powered web application. Note, however, that AbstractWebTests does not
declare @ContextHierarchy ; consequently, subclasses of AbstractWebTests can
optionally participate in a context hierarchy or simply follow the standard semantics for
@ContextConfiguration . SoapWebServiceTests and RestWebServiceTests both
extend AbstractWebTests and define a context hierarchy via @ContextHierarchy .
The result is that three application contexts will be loaded (one for each declaration of
@ContextConfiguration ), and the application context loaded based on the
configuration in AbstractWebTests will be set as the parent context for each of the
contexts loaded for the concrete subclasses.
@RunWith(SpringRunner.class)

25/08/2016 12:10

Spring Framework Reference Documentation

459 de 1194

@WebAppConfiguration
@ContextConfiguration("file:src/main/webapp/WEB-INF/applicationContext.xml")
public abstract class AbstractWebTests {}
@ContextHierarchy(@ContextConfiguration("/spring/soap-ws-config.xml")
public class SoapWebServiceTests extends AbstractWebTests {}
@ContextHierarchy(@ContextConfiguration("/spring/rest-ws-config.xml")
public class RestWebServiceTests extends AbstractWebTests {}

The following classes demonstrate the use of named hierarchy levels in order to merge
the configuration for specific levels in a context hierarchy. BaseTests defines two levels
in the hierarchy, parent and child . ExtendedTests extends BaseTests and
instructs the Spring TestContext Framework to merge the context configuration for the
child hierarchy level, simply by ensuring that the names declared via the name
attribute in @ContextConfiguration are both "child" . The result is that three
application contexts will be loaded: one for "/app-config.xml" , one for
"/user-config.xml" , and one for {"/user-config.xml", "/order-config.xml"} .
As with the previous example, the application context loaded from "/app-config.xml"
will be set as the parent context for the contexts loaded from "/user-config.xml" and
{"/user-config.xml", "/order-config.xml"} .
@RunWith(SpringRunner.class)
@ContextHierarchy({
@ContextConfiguration(name = "parent", locations = "/app-config.xml"),
@ContextConfiguration(name = "child", locations = "/user-config.xml")
})
public class BaseTests {}
@ContextHierarchy(
@ContextConfiguration(name = "child", locations = "/order-config.xml")
)
public class ExtendedTests extends BaseTests {}

In contrast to the previous example, this example demonstrates how to override the
configuration for a given named level in a context hierarchy by setting the
inheritLocations flag in @ContextConfiguration to false . Consequently, the
application context for ExtendedTests will be loaded only from
"/test-user-config.xml" and will have its parent set to the context loaded from
"/app-config.xml" .
@RunWith(SpringRunner.class)
@ContextHierarchy({
@ContextConfiguration(name = "parent", locations = "/app-config.xml"),

25/08/2016 12:10

Spring Framework Reference Documentation

460 de 1194

@ContextConfiguration(name = "child", locations = "/user-config.xml")

})
public class BaseTests {}
@ContextHierarchy(
@ContextConfiguration(
name = "child",
locations = "/test-user-config.xml",
inheritLocations = false
))
public class ExtendedTests extends BaseTests {}

If @DirtiesContext is used in a test whose context is configured as part

of a context hierarchy, the hierarchyMode flag can be used to control how
the context cache is cleared. For further details consult the discussion of
@DirtiesContext in Spring Testing Annotations and the
@DirtiesContext javadocs.

15.5.5 Dependency injection of test fixtures

When you use the DependencyInjectionTestExecutionListener which is
configured by defaultthe dependencies of your test instances are injected from beans
in the application context that you configured with @ContextConfiguration . You may
use setter injection, field injection, or both, depending on which annotations you choose
and whether you place them on setter methods or fields. For consistency with the
annotation support introduced in Spring 2.5 and 3.0, you can use Springs @Autowired
annotation or the @Inject annotation from JSR 330.

The TestContext framework does not instrument the manner in which a test
instance is instantiated. Thus the use of @Autowired or @Inject for
constructors has no effect for test classes.

Because @Autowired is used to perform autowiring by type, if you have multiple bean
definitions of the same type, you cannot rely on this approach for those particular beans.
In that case, you can use @Autowired in conjunction with @Qualifier . As of Spring 3.0
you may also choose to use @Inject in conjunction with @Named . Alternatively, if your
test class has access to its ApplicationContext , you can perform an explicit lookup by
using (for example) a call to applicationContext.getBean("titleRepository") .

25/08/2016 12:10

Spring Framework Reference Documentation

461 de 1194

annotate fields or setter methods with @Autowired or @Inject . Alternatively, you can
disable dependency injection altogether by explicitly configuring your class with
@TestExecutionListeners and omitting
DependencyInjectionTestExecutionListener.class from the list of listeners.
Consider the scenario of testing a HibernateTitleRepository class, as outlined in the
Goals section. The next two code listings demonstrate the use of @Autowired on fields
and setter methods. The application context configuration is presented after all sample
code listings.

The dependency injection behavior in the following code listings is not

specific to JUnit 4. The same DI techniques can be used in conjunction with
any testing framework.
The following examples make calls to static assertion methods such as
assertNotNull() but without prepending the call with Assert . In such
cases, assume that the method was properly imported through an
import static declaration that is not shown in the example.

The first code listing shows a JUnit 4 based implementation of the test class that uses
@Autowired for field injection.
@RunWith(SpringRunner.class)
// specifies the Spring configuration to load for this test fixture
@ContextConfiguration("repository-config.xml")
public class HibernateTitleRepositoryTests {
// this instance will be dependency injected by type
@Autowired
private HibernateTitleRepository titleRepository;
@Test
public void findById() {
Title title = titleRepository.findById(new Long(10));
assertNotNull(title);
}
}

Alternatively, you can configure the class to use @Autowired for setter injection as seen
below.
@RunWith(SpringRunner.class)
// specifies the Spring configuration to load for this test fixture

25/08/2016 12:10

Spring Framework Reference Documentation

462 de 1194

public class HibernateTitleRepositoryTests {

// this instance will be dependency injected by type
private HibernateTitleRepository titleRepository;
@Autowired
public void setTitleRepository(HibernateTitleRepository titleRepository) {
this.titleRepository = titleRepository;
}
@Test
public void findById() {
Title title = titleRepository.findById(new Long(10));
assertNotNull(title);
}
}

The preceding code listings use the same XML context file referenced by the
@ContextConfiguration annotation (that is, repository-config.xml ), which looks
like this:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">

<bean id="titleRepository" class="com.foo.repository.hibernate.HibernateTitleRepos
<property name="sessionFactory" ref="sessionFactory"/>
</bean>

<bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFa

</bean>
</beans>

If you are extending from a Spring-provided test base class that happens to use @Autowired
one of its setter methods, you might have multiple beans of the affected type defined in your

application context: for example, multiple DataSource beans. In such a case, you can overr
the setter method and use the @Qualifier annotation to indicate a specific target bean as
follows, but make sure to delegate to the overridden method in the superclass as well.
// ...

25/08/2016 12:10

Spring Framework Reference Documentation

463 de 1194

@Autowired
@Override
public void setDataSource(@Qualifier("myDataSource") DataSource dataSource
super.setDataSource(dataSource);
}
// ...

The specified qualifier value indicates the specific DataSource bean to inject, narrowing the
of type matches to a specific bean. Its value is matched against <qualifier> declarations
within the corresponding <bean> definitions. The bean name is used as a fallback qualifier
value, so you may effectively also point to a specific bean by name there (as shown above,
assuming that "myDataSource" is the bean id).

15.5.6 Testing request and session scoped beans

Request and session scoped beans have been supported by Spring since the early
years, and since Spring 3.2 its a breeze to test your request-scoped and session-scoped
beans by following these steps.
Ensure that a WebApplicationContext is loaded for your test by annotating your
test class with @WebAppConfiguration .
Inject the mock request or session into your test instance and prepare your test
fixture as appropriate.
Invoke your web component that you retrieved from the configured
WebApplicationContext (i.e., via dependency injection).
Perform assertions against the mocks.
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 SpEL expressions that retrieve the
username and password from the current HTTP request. In our test, we will want to
configure these request parameters via the mock managed by the TestContext
framework.
Request-scoped bean configuration.
<beans>
<bean id="userService"
class="com.example.SimpleUserService"
c:loginAction-ref="loginAction" />

25/08/2016 12:10

Spring Framework Reference Documentation

464 de 1194

<bean id="loginAction" class="com.example.LoginAction"

c:username="{request.getParameter('user')}"
c:password="{request.getParameter('pswd')}"
scope="request">
<aop:scoped-proxy />
</bean>
</beans>

In RequestScopedBeanTests we inject both the UserService (i.e., the subject under

test) and the MockHttpServletRequest into our test instance. Within our
requestScope() test method we set up our test fixture by setting request parameters in
the provided MockHttpServletRequest . When the loginUser() method is invoked on
our userService we are assured that the user service has access to the requestscoped loginAction for the current MockHttpServletRequest (i.e., the one we just
set parameters in). We can then perform assertions against the results based on the
known inputs for the username and password.
Request-scoped bean test.
@RunWith(SpringRunner.class)
@ContextConfiguration
@WebAppConfiguration
public class RequestScopedBeanTests {
@Autowired UserService userService;
@Autowired MockHttpServletRequest request;
@Test
public void requestScope() {
request.setParameter("user", "enigma");
request.setParameter("pswd", "$pr!ng");
LoginResults results = userService.loginUser();
// assert results
}
}

The following code snippet is similar to the one we saw above for a request-scoped bean;
however, this time the userService bean has a dependency on a session-scoped
userPreferences bean. Note that the UserPreferences bean is instantiated using a
SpEL expression that retrieves the theme from the current HTTP session. In our test, we
will need to configure a theme in the mock session managed by the TestContext

25/08/2016 12:10

Spring Framework Reference Documentation

465 de 1194

framework.
Session-scoped bean configuration.
<beans>
<bean id="userService"
class="com.example.SimpleUserService"
c:userPreferences-ref="userPreferences" />
<bean id="userPreferences"
class="com.example.UserPreferences"
c:theme="#{session.getAttribute('theme')}"
scope="session">
<aop:scoped-proxy />
</bean>
</beans>

In SessionScopedBeanTests we inject the UserService and the MockHttpSession

into our test instance. Within our sessionScope() test method we set up our test fixture
by setting the expected "theme" attribute in the provided MockHttpSession . When the
processUserPreferences() method is invoked on our userService we are assured
that the user service has access to the session-scoped userPreferences for the
current MockHttpSession , and we can perform assertions against the results based on
the configured theme.
Session-scoped bean test.
@RunWith(SpringRunner.class)
@ContextConfiguration
@WebAppConfiguration
public class SessionScopedBeanTests {
@Autowired UserService userService;
@Autowired MockHttpSession session;
@Test
public void sessionScope() throws Exception {
session.setAttribute("theme", "blue");
Results results = userService.processUserPreferences();
// assert results
}

25/08/2016 12:10

Spring Framework Reference Documentation

466 de 1194

15.5.7 Transaction management

In the TestContext framework, transactions are managed by the
TransactionalTestExecutionListener which is configured by default, even if you do
not explicitly declare @TestExecutionListeners on your test class. To enable support
for transactions, however, you must configure a PlatformTransactionManager bean in
the ApplicationContext that is loaded via @ContextConfiguration semantics
(further details are provided below). In addition, you must declare Springs
@Transactional annotation either at the class or method level for your tests.

Test-managed transactions
Test-managed transactions are transactions that are managed declaratively via the
TransactionalTestExecutionListener or programmatically via TestTransaction
(see below). Such transactions should not be confused with Spring-managed transactions
(i.e., those managed directly by Spring within the ApplicationContext loaded for tests)
or application-managed transactions (i.e., those managed programmatically within
application code that is invoked via tests). Spring-managed and application-managed
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
transaction propagation for details).

Enabling and disabling transactions

Annotating a test method with @Transactional causes the test to be run within a
transaction that will, by default, be automatically rolled back after completion of the test. If
a test class is annotated with @Transactional , each test method within that class
hierarchy will be run within a transaction. Test methods that are not annotated with
@Transactional (at the class or method level) will not be run within a transaction.
Furthermore, tests that are annotated with @Transactional but have the propagation
type set to NOT_SUPPORTED will not be run within a transaction.
Note that AbstractTransactionalJUnit4SpringContextTests and
AbstractTransactionalTestNGSpringContextTests are preconfigured for
transactional support at the class level.
The following example demonstrates a common scenario for writing an integration test for

25/08/2016 12:10

Spring Framework Reference Documentation

467 de 1194

rollback and commit behavior, there is no need to clean up the database after the
createUser() method is executed since any changes made to the database will be
automatically rolled back by the TransactionalTestExecutionListener . See
Section 15.7, PetClinic Example for an additional example.
@RunWith(SpringRunner.class)
@ContextConfiguration(classes = TestConfig.class)
@Transactional
public class HibernateUserRepositoryTests {
@Autowired
HibernateUserRepository repository;
@Autowired
SessionFactory sessionFactory;
JdbcTemplate jdbcTemplate;
@Autowired
public void setDataSource(DataSource dataSource) {
this.jdbcTemplate = new JdbcTemplate(dataSource);
}
@Test
public void createUser() {
// track initial state in test database:
final int count = countRowsInTable("user");
User user = new User(...);
repository.save(user);
// Manual flush is required to avoid false positive in test
sessionFactory.getCurrentSession().flush();
assertNumUsers(count + 1);
}
protected int countRowsInTable(String tableName) {
return JdbcTestUtils.countRowsInTable(this.jdbcTemplate, tableName);
}

protected void assertNumUsers(int expected) {

assertEquals("Number of rows in the [user] table.", expected, countRowsInTable
}
}

Transaction rollback and commit behavior

25/08/2016 12:10

Spring Framework Reference Documentation

468 de 1194

By default, test transactions will be automatically rolled back after completion of the test;
however, transactional commit and rollback behavior can be configured declaratively via
the @Commit and @Rollback annotations. See the corresponding entries in the
annotation support section for further details.

Programmatic transaction management

Since Spring Framework 4.1, it is possible to interact with test-managed transactions
programmatically via the static methods in TestTransaction . For example,
TestTransaction may be used within test methods, before methods, and after methods
to start or end the current test-managed transaction or to configure the current
test-managed transaction for rollback or commit. Support for TestTransaction is
automatically available whenever the TransactionalTestExecutionListener is
enabled.
The following example demonstrates some of the features of TestTransaction . Consult
the javadocs for TestTransaction for further details.
@ContextConfiguration(classes = TestConfig.class)
public class ProgrammaticTransactionManagementTests extends
AbstractTransactionalJUnit4SpringContextTests {
@Test
public void transactionalTest() {
// assert initial state in test database:
assertNumUsers(2);
deleteFromTables("user");
// changes to the database will be committed!
TestTransaction.flagForCommit();
TestTransaction.end();
assertFalse(TestTransaction.isActive());
assertNumUsers(0);
TestTransaction.start();
// perform other actions against the database that will
// be automatically rolled back after the test completes...
}

protected void assertNumUsers(int expected) {

assertEquals("Number of rows in the [user] table.", expected, countRowsInTable
}
}

25/08/2016 12:10

Spring Framework Reference Documentation

469 de 1194

Executing code outside of a transaction

Occasionally you need to execute certain code before or after a transactional test method
but outside the transactional contextfor example, to verify the initial database state
prior to execution of your test or to verify expected transactional commit behavior after
test execution (if the test was configured to commit the transaction).
TransactionalTestExecutionListener supports the @BeforeTransaction and
@AfterTransaction annotations exactly for such scenarios. Simply annotate any void
method in a test class or any void default method in a test interface with one of these
annotations, and the TransactionalTestExecutionListener ensures that your before
transaction method or after transaction method is executed at the appropriate time.

Any before methods (such as methods annotated with JUnit 4s @Before )

and any after methods (such as methods annotated with JUnit 4s @After )
are executed within a transaction. In addition, methods annotated with
@BeforeTransaction or @AfterTransaction are naturally not executed
for test methods that are not configured to run within a transaction.

Configuring a transaction manager

TransactionalTestExecutionListener expects a PlatformTransactionManager
bean to be defined in the Spring ApplicationContext for the test. In case there are
multiple instances of PlatformTransactionManager within the tests
ApplicationContext , a qualifier may be declared via @Transactional("myTxMgr")
or @Transactional(transactionManager = "myTxMgr") , or
TransactionManagementConfigurer can be implemented by an @Configuration
class. Consult the javadocs for
TestContextTransactionUtils.retrieveTransactionManager() for details on the
algorithm used to look up a transaction manager in the tests ApplicationContext .

Demonstration of all transaction-related annotations

The following JUnit 4 based example displays a fictitious integration testing scenario
highlighting all transaction-related annotations. The example is not intended to
demonstrate best practices but rather to demonstrate how these annotations can be
used. Consult the annotation support section for further information and configuration
examples. Transaction management for @Sql contains an additional example using
@Sql for declarative SQL script execution with default transaction rollback semantics.
@RunWith(SpringRunner.class)

25/08/2016 12:10

Spring Framework Reference Documentation

470 de 1194

@ContextConfiguration
@Transactional(transactionManager = "txMgr")
@Commit
public class FictitiousTransactionalTest {
@BeforeTransaction
void verifyInitialDatabaseState() {
// logic to verify the initial state before a transaction is started
}
@Before
public void setUpTestDataWithinTransaction() {
// set up test data within the transaction
}
@Test
// overrides the class-level @Commit setting
@Rollback
public void modifyDatabaseWithinTransaction() {
// logic which uses the test data and modifies database state
}
@After
public void tearDownWithinTransaction() {
// execute "tear down" logic within the transaction
}
@AfterTransaction
void verifyFinalDatabaseState() {
// logic to verify the final state after transaction has rolled back
}
}

When you test application code that manipulates the state of a Hibernate session
or JPA persistence context, make sure to flush the underlying unit of work within
test methods that execute that code. Failing to flush the underlying unit of work can
produce false positives: your test may pass, but the same code throws an
exception in a live, production environment. In the following Hibernate-based
example test case, one method demonstrates a false positive, and the other
method correctly exposes the results of flushing the session. Note that this applies
to any ORM frameworks that maintain an in-memory unit of work.
// ...
@Autowired

25/08/2016 12:10

Spring Framework Reference Documentation

471 de 1194

SessionFactory sessionFactory;
@Transactional
@Test // no expected exception!
public void falsePositive() {
updateEntityInHibernateSession();
// False positive: an exception will be thrown once the Hibernate
// Session is finally flushed (i.e., in production code)
}
@Transactional
@Test(expected = ...)
public void updateWithSessionFlush() {
updateEntityInHibernateSession();
// Manual flush is required to avoid false positive in test
sessionFactory.getCurrentSession().flush();
}
// ...

Or for JPA:
// ...
@PersistenceContext
EntityManager entityManager;
@Transactional
@Test // no expected exception!
public void falsePositive() {
updateEntityInJpaPersistenceContext();
// False positive: an exception will be thrown once the JPA
// EntityManager is finally flushed (i.e., in production code)
}
@Transactional
@Test(expected = ...)
public void updateWithEntityManagerFlush() {
updateEntityInJpaPersistenceContext();
// Manual flush is required to avoid false positive in test
entityManager.flush();
}
// ...

15.5.8 Executing SQL scripts

25/08/2016 12:10

Spring Framework Reference Documentation

472 de 1194

When writing integration tests against a relational database, it is often beneficial 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
Section 19.8, Embedded database support and Section 19.8.5, Testing data access
logic with an embedded database for details.
Although it is very useful to initialize a database for testing once when the
ApplicationContext is loaded, sometimes it is essential to be able to modify the
database during integration tests. The following sections explain how to execute SQL
scripts programmatically and declaratively during integration tests.

Executing SQL scripts programmatically

Spring provides the following options for executing SQL scripts programmatically within
integration test methods.
org.springframework.jdbc.datasource.init.ScriptUtils
org.springframework.jdbc.datasource.init.ResourceDatabasePopulator

org.springframework.test.context.junit4.AbstractTransactionalJUnit4SpringConte

org.springframework.test.context.testng.AbstractTransactionalTestNGSpringConte
ScriptUtils provides a collection of static utility methods for working with SQL scripts
and is mainly intended for internal use within the framework. However, if you require full
control over how SQL scripts are parsed and executed, ScriptUtils may suit your
needs better than some of the other alternatives described below. Consult the javadocs
for individual methods in ScriptUtils for further details.
ResourceDatabasePopulator provides a simple object-based API for programmatically
populating, initializing, or cleaning up a database using SQL scripts defined in external
resources. ResourceDatabasePopulator provides options for configuring the character
encoding, statement separator, comment delimiters, and error handling flags used when
parsing and executing the scripts, and each of the configuration options has a reasonable
default value. Consult the javadocs for details on default values. To execute the scripts
configured in a ResourceDatabasePopulator , you can invoke either the
populate(Connection) method to execute the populator against a
java.sql.Connection or the execute(DataSource) method to execute the populator
against a javax.sql.DataSource . The following example specifies SQL scripts for a
test schema and test data, sets the statement separator to "@@" , and then executes the
scripts against a DataSource .

25/08/2016 12:10

Spring Framework Reference Documentation

473 de 1194

public void databaseTest {

ResourceDatabasePopulator populator = new ResourceDatabasePopulator();
populator.addScripts(
new ClassPathResource("test-schema.sql"),
new ClassPathResource("test-data.sql"));
populator.setSeparator("@@");
populator.execute(this.dataSource);
// execute code that uses the test schema and data
}

Note that ResourceDatabasePopulator internally delegates to ScriptUtils for

parsing and executing SQL scripts. Similarly, the executeSqlScript(..) methods in
AbstractTransactionalJUnit4SpringContextTests and
AbstractTransactionalTestNGSpringContextTests internally use a
ResourceDatabasePopulator for executing SQL scripts. Consult the javadocs for the
various executeSqlScript(..) methods for further details.

Executing SQL scripts declaratively with @Sql

In addition to the aforementioned mechanisms for executing SQL scripts
programmatically, SQL scripts can also be configured declaratively in the Spring
TestContext Framework. Specifically, the @Sql annotation can be declared on a test
class or test method to configure the resource paths to SQL scripts that should be
executed against a given database either before or after an integration test method. Note
that method-level declarations override class-level declarations and that support for @Sql
is provided by the SqlScriptsTestExecutionListener which is enabled by default.
Path resource semantics
Each path will be interpreted as a Spring Resource . A plain pathfor example,
"schema.sql" will be treated as a classpath resource that is relative to the package
in which the test class is defined. A path starting with a slash will be treated as an
absolute classpath resource, for example: "/org/example/schema.sql" . A path which
references a URL (e.g., a path prefixed with classpath: , file: , http: , etc.) will be
loaded using the specified resource protocol.
The following example demonstrates how to use @Sql at the class level and at the
method level within a JUnit 4 based integration test class.
@RunWith(SpringRunner.class)
@ContextConfiguration
@Sql("/test-schema.sql")
public class DatabaseTests {

25/08/2016 12:10

Spring Framework Reference Documentation

474 de 1194

@Test
public void emptySchemaTest {
// execute code that uses the test schema without any test data
}
@Test
@Sql({"/test-schema.sql", "/test-user-data.sql"})
public void userTest {
// execute code that uses the test schema and test data
}
}

Default script detection

If no SQL scripts are specified, an attempt will be made to detect a default script
depending on where @Sql is declared. If a default cannot be detected, an
IllegalStateException will be thrown.
class-level declaration: if the annotated test class is com.example.MyTest , the
corresponding default script is "classpath:com/example/MyTest.sql" .
method-level declaration: if the annotated test method is named testMethod() and
is defined in the class com.example.MyTest , the corresponding default script is
"classpath:com/example/MyTest.testMethod.sql" .
Declaring multiple @Sql sets
If multiple sets of SQL scripts need to be configured for a given test class or test method
but with different syntax configuration, different error handling rules, or different execution
phases per set, it is possible to declare multiple instances of @Sql . With Java 8, @Sql
can be used as a repeatable annotation. Otherwise, the @SqlGroup annotation can be
used as an explicit container for declaring multiple instances of @Sql .
The following example demonstrates the use of @Sql as a repeatable annotation using
Java 8. In this scenario the test-schema.sql script uses a different syntax for
single-line comments.
@Test
@Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`"))
@Sql("/test-user-data.sql")
public void userTest {
// execute code that uses the test schema and test data
}

The following example is identical to the above except that the @Sql declarations are
grouped together within @SqlGroup for compatibility with Java 6 and Java 7.

25/08/2016 12:10

Spring Framework Reference Documentation

475 de 1194

@Test
@SqlGroup({
@Sql(scripts = "/test-schema.sql", config = @SqlConfig(commentPrefix = "`")),
@Sql("/test-user-data.sql")
)}
public void userTest {
// execute code that uses the test schema and test data
}

Script execution phases

By default, SQL scripts will be executed before the corresponding test method. However,
if a particular set of scripts needs to be executed after the test methodfor example, to
clean up database statethe executionPhase attribute in @Sql can be used as seen
in the following example. Note that ISOLATED and AFTER_TEST_METHOD are statically
imported from Sql.TransactionMode and Sql.ExecutionPhase respectively.
@Test
@Sql(
scripts = "create-test-data.sql",
config = @SqlConfig(transactionMode = ISOLATED)
)
@Sql(
scripts = "delete-test-data.sql",
config = @SqlConfig(transactionMode = ISOLATED),
executionPhase = AFTER_TEST_METHOD
)
public void userTest {
// execute code that needs the test data to be committed
// to the database outside of the test's transaction
}

Script configuration with @SqlConfig

Configuration for script parsing and error handling can be configured via the @SqlConfig
annotation. When declared as a class-level annotation on an integration test class,
@SqlConfig serves as global configuration for all SQL scripts within the test class
hierarchy. When declared directly via the config attribute of the @Sql annotation,
@SqlConfig serves as local configuration for the SQL scripts declared within the
enclosing @Sql annotation. Every attribute in @SqlConfig has an implicit default value
which is documented in the javadocs of the corresponding attribute. Due to the rules
defined for annotation attributes in the Java Language Specification, it is unfortunately not
possible to assign a value of null to an annotation attribute. Thus, in order to support
overrides of inherited global configuration, @SqlConfig attributes have an explicit default

25/08/2016 12:10

Spring Framework Reference Documentation

476 de 1194

declarations of @SqlConfig to selectively override individual attributes from global

declarations of @SqlConfig by providing a value other than "" or DEFAULT . Global
@SqlConfig attributes are inherited whenever local @SqlConfig attributes do not
supply an explicit value other than "" or DEFAULT . Explicit local configuration therefore
overrides global configuration.
The configuration options provided by @Sql and @SqlConfig are equivalent to those
supported by ScriptUtils and ResourceDatabasePopulator but are a superset of
those provided by the <jdbc:initialize-database/> XML namespace element.
Consult the javadocs of individual attributes in @Sql and @SqlConfig for details.
Transaction management for @Sql
By default, the SqlScriptsTestExecutionListener will infer the desired transaction
semantics for scripts configured via @Sql . Specifically, SQL scripts will be executed
without a transaction, within an existing Spring-managed transactionfor example, a
transaction managed by the TransactionalTestExecutionListener for a test
annotated with @Transactional or within an isolated transaction, depending on the
configured value of the transactionMode attribute in @SqlConfig and the presence of
a PlatformTransactionManager in the tests ApplicationContext . As a bare
minimum however, a javax.sql.DataSource must be present in the tests
ApplicationContext .
If the algorithms used by SqlScriptsTestExecutionListener to detect a
DataSource and PlatformTransactionManager and infer the transaction semantics
do not suit your needs, you may specify explicit names via the dataSource and
transactionManager attributes of @SqlConfig . Furthermore, the transaction
propagation behavior can be controlled via the transactionMode attribute of
@SqlConfig for example, if scripts should be executed in an isolated transaction.
Although a thorough discussion of all supported options for transaction management with
@Sql is beyond the scope of this reference manual, the javadocs for @SqlConfig and
SqlScriptsTestExecutionListener provide detailed information, and the following
example demonstrates a typical testing scenario using JUnit 4 and transactional tests
with @Sql . Note that there is no need to clean up the database after the usersTest()
method is executed since any changes made to the database (either within the test
method or within the /test-data.sql script) will be automatically rolled back by the
TransactionalTestExecutionListener (see transaction management for details).
@RunWith(SpringRunner.class)
@ContextConfiguration(classes = TestDatabaseConfig.class)
@Transactional
public class TransactionalSqlScriptsTests {

25/08/2016 12:10

Spring Framework Reference Documentation

477 de 1194

protected JdbcTemplate jdbcTemplate;

@Autowired
public void setDataSource(DataSource dataSource) {
this.jdbcTemplate = new JdbcTemplate(dataSource);
}
@Test
@Sql("/test-data.sql")
public void usersTest() {
// verify state in test database:
assertNumUsers(2);
// execute code that uses the test data...
}
protected int countRowsInTable(String tableName) {
return JdbcTestUtils.countRowsInTable(this.jdbcTemplate, tableName);
}

protected void assertNumUsers(int expected) {

assertEquals("Number of rows in the [user] table.", expected, countRowsInTable
}
}

15.5.9 TestContext Framework support classes

Spring JUnit 4 Runner
The Spring TestContext Framework offers full integration with JUnit 4 through a custom
runner (supported on JUnit 4.12 or higher). By annotating test classes with
@RunWith(SpringJUnit4ClassRunner.class) or the shorter
@RunWith(SpringRunner.class) variant, developers can implement standard JUnit 4
based unit and integration tests and simultaneously reap the benefits of the TestContext
framework such as support for loading application contexts, dependency injection of test
instances, transactional test method execution, and so on. If you would like to use the
Spring TestContext Framework with an alternative runner such as JUnit 4s
Parameterized or third-party runners such as the MockitoJUnitRunner , you may
optionally use Springs support for JUnit rules instead.
The following code listing displays the minimal requirements for configuring a test class to
run with the custom Spring Runner . @TestExecutionListeners is configured with an
empty list in order to disable the default listeners, which otherwise would require an

25/08/2016 12:10

Spring Framework Reference Documentation

478 de 1194

@RunWith(SpringRunner.class)
@TestExecutionListeners({})
public class SimpleTest {
@Test
public void testMethod() {
// execute test logic...
}
}

Spring JUnit 4 Rules

The org.springframework.test.context.junit4.rules package provides the
following JUnit 4 rules (supported on JUnit 4.12 or higher).
SpringClassRule
SpringMethodRule
SpringClassRule is a JUnit TestRule that supports class-level features of the Spring
TestContext Framework; whereas, SpringMethodRule is a JUnit MethodRule that
supports instance-level and method-level features of the Spring TestContext Framework.
In contrast to the SpringRunner , Springs rule-based JUnit support has the advantage
that it is independent of any org.junit.runner.Runner implementation and can
therefore be combined with existing alternative runners like JUnit 4s Parameterized or
third-party runners such as the MockitoJUnitRunner .
In order to support the full functionality of the TestContext framework, a
SpringClassRule must be combined with a SpringMethodRule . The following
example demonstrates the proper way to declare these rules in an integration test.
// Optionally specify a non-Spring Runner via @RunWith(...)
@ContextConfiguration
public class IntegrationTest {
@ClassRule
public static final SpringClassRule SPRING_CLASS_RULE = new SpringClassRule();
@Rule
public final SpringMethodRule springMethodRule = new SpringMethodRule();
@Test
public void testMethod() {
// execute test logic...
}

25/08/2016 12:10

Spring Framework Reference Documentation

479 de 1194

JUnit 4 support classes

The org.springframework.test.context.junit4 package provides the following
support classes for JUnit 4 based test cases (supported on JUnit 4.12 or higher).
AbstractJUnit4SpringContextTests
AbstractTransactionalJUnit4SpringContextTests
AbstractJUnit4SpringContextTests is an abstract base test class that integrates the
Spring TestContext Framework with explicit ApplicationContext testing support in a
JUnit 4 environment. When you extend AbstractJUnit4SpringContextTests , you can
access a protected applicationContext instance variable that can be used to
perform explicit bean lookups or to test the state of the context as a whole.
AbstractTransactionalJUnit4SpringContextTests is an abstract transactional
extension of AbstractJUnit4SpringContextTests that adds some convenience
functionality for JDBC access. This class expects a javax.sql.DataSource bean and a
PlatformTransactionManager bean to be defined in the ApplicationContext .
When you extend AbstractTransactionalJUnit4SpringContextTests you can
access a protected jdbcTemplate instance variable that can be used to execute SQL
statements to query the database. Such queries can be used to confirm database state
both prior to and after execution of database-related application code, and Spring
ensures that such queries run in the scope of the same transaction as the application
code. When used in conjunction with an ORM tool, be sure to avoid false positives. As
mentioned in Section 15.3, JDBC Testing Support,
AbstractTransactionalJUnit4SpringContextTests also provides convenience
methods which delegate to methods in JdbcTestUtils using the aforementioned
jdbcTemplate . Furthermore, AbstractTransactionalJUnit4SpringContextTests
provides an executeSqlScript(..) method for executing SQL scripts against the
configured DataSource .

TestNG support classes

25/08/2016 12:10

Spring Framework Reference Documentation

480 de 1194

The org.springframework.test.context.testng package provides the following

support classes for TestNG based test cases.
AbstractTestNGSpringContextTests
AbstractTransactionalTestNGSpringContextTests
AbstractTestNGSpringContextTests is an abstract base test class that integrates the
Spring TestContext Framework with explicit ApplicationContext testing support in a
TestNG environment. When you extend AbstractTestNGSpringContextTests , you
can access a protected applicationContext instance variable that can be used to
perform explicit bean lookups or to test the state of the context as a whole.
AbstractTransactionalTestNGSpringContextTests is an abstract transactional
extension of AbstractTestNGSpringContextTests that adds some convenience
functionality for JDBC access. This class expects a javax.sql.DataSource bean and a
PlatformTransactionManager bean to be defined in the ApplicationContext .
When you extend AbstractTransactionalTestNGSpringContextTests you can
access a protected jdbcTemplate instance variable that can be used to execute SQL
statements to query the database. Such queries can be used to confirm database state
both prior to and after execution of database-related application code, and Spring
ensures that such queries run in the scope of the same transaction as the application
code. When used in conjunction with an ORM tool, be sure to avoid false positives. As
mentioned in Section 15.3, JDBC Testing Support,
AbstractTransactionalTestNGSpringContextTests also provides convenience
methods which delegate to methods in JdbcTestUtils using the aforementioned
jdbcTemplate . Furthermore, AbstractTransactionalTestNGSpringContextTests
provides an executeSqlScript(..) method for executing SQL scripts against the
configured DataSource .

These classes are a convenience for extension. If you do not want your test
classes to be tied to a Spring-specific class hierarchy, you can configure
your own custom test classes by using @ContextConfiguration ,
@TestExecutionListeners , and so on, and by manually instrumenting
your test class with a TestContextManager . See the source code of
AbstractTestNGSpringContextTests for an example of how to
instrument your test class.

15.6 Spring MVC Test Framework

25/08/2016 12:10

Spring Framework Reference Documentation

481 de 1194

The Spring MVC Test framework provides first class support for testing Spring MVC code
using a fluent API that can be used with JUnit, TestNG, or any other testing framework.
Its built on the Servlet API mock objects from the spring-test module and hence does
not use a running Servlet container. It uses the DispatcherServlet to provide full
Spring MVC runtime behavior and provides support for loading actual Spring
configuration with the TestContext framework in addition to a standalone mode in which
controllers may be instantiated manually and tested one at a time.
Spring MVC Test also provides client-side support for testing code that uses the
RestTemplate . Client-side tests mock the server responses and also do not use a
running server.

Spring Boot provides an option to write full, end-to-end integration tests that
include a running server. If this is your goal please have a look at the Spring
Boot reference page. For more information on the differences between
out-of-container and end-to-end integration tests, see the section called
Differences between Out-of-Container and End-to-End Integration Tests.

15.6.1 Server-Side Tests

Its easy to write a plain unit test for a Spring MVC controller using JUnit or TestNG:
simply instantiate the controller, inject it with mocked or stubbed dependencies, and call
its methods passing MockHttpServletRequest , MockHttpServletResponse , etc., as
necessary. However, when writing such a unit test, much remains untested: for example,
request mappings, data binding, type conversion, validation, and much more.
Furthermore, other controller methods such as @InitBinder , @ModelAttribute , and
@ExceptionHandler may also be invoked as part of the request processing lifecycle.
The goal of Spring MVC Test is to provide an effective way for testing controllers by
performing requests and generating responses through the actual DispatcherServlet .
Spring MVC Test builds on the familiar "mock" implementations of the Servlet API
available in the spring-test module. This allows performing requests and generating
responses without the need for running in a Servlet container. For the most part
everything should work as it does at runtime with a few notable exceptions as explained
in the section called Differences between Out-of-Container and End-to-End Integration
Tests. Here is a JUnit 4 based example of using Spring MVC Test:
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

25/08/2016 12:10

Spring Framework Reference Documentation

482 de 1194

@RunWith(SpringRunner.class)
@WebAppConfiguration
@ContextConfiguration("test-servlet-context.xml")
public class ExampleTests {
@Autowired
private WebApplicationContext wac;
private MockMvc mockMvc;
@Before
public void setup() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
}
@Test
public void getAccount() throws Exception {
this.mockMvc.perform(get("/accounts/1").accept(MediaType.parseMediaType(
.andExpect(status().isOk())
.andExpect(content().contentType("application/json"))
.andExpect(jsonPath("$.name").value("Lee"));
}
}

The above test relies on the WebApplicationContext support of the TestContext

framework for loading Spring configuration from an XML configuration file located in the
same package as the test class, but Java-based and Groovy-based configuration are also
supported. See these sample tests.
The MockMvc instance is used to perform a GET request to "/accounts/1" and verify
that the resulting response has status 200, the content type is "application/json" ,
and the response body has a JSON property called "name" with the value "Lee". The
jsonPath syntax is supported through the Jayway JsonPath project. There are lots of
other options for verifying the result of the performed request that will be discussed below.

Static Imports
The fluent API in the example above requires a few static imports such as
MockMvcRequestBuilders.* , MockMvcResultMatchers.* , and
MockMvcBuilders.* . An easy way to find these classes is to search for types matching
"MockMvc*". If using Eclipse, be sure to add them as "favorite static members" in the
Eclipse preferences under Java Editor Content Assist Favorites. That will allow
use of content assist after typing the first character of the static method name. Other IDEs

25/08/2016 12:10

Spring Framework Reference Documentation

483 de 1194

(e.g. IntelliJ) may not require any additional configuration. Just check the support for code
completion on static members.

Setup Options
There are two main options for creating an instance of MockMvc . The first is to load
Spring MVC configuration through the TestContext framework, which loads the Spring
configuration and injects a WebApplicationContext into the test to use to build a
MockMvc instance:
@RunWith(SpringRunner.class)
@WebAppConfiguration
@ContextConfiguration("my-servlet-context.xml")
public class MyWebTests {
@Autowired
private WebApplicationContext wac;
private MockMvc mockMvc;
@Before
public void setup() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
}
// ...
}

The second is to simply create a controller instance manually without loading Spring
configuration. Instead basic default configuration, roughly comparable to that of the MVC
JavaConfig or the MVC namespace, is automatically created and can be customized to a
degree:
public class MyWebTests {
private MockMvc mockMvc;

@Before
public void setup() {
this.mockMvc = MockMvcBuilders.standaloneSetup(new AccountController()).build(
}
// ...

25/08/2016 12:10

Spring Framework Reference Documentation

484 de 1194

Which setup option should you use?

The "webAppContextSetup" loads your actual Spring MVC configuration resulting in a
more complete integration test. Since the TestContext framework caches the loaded
Spring configuration, it helps keep tests running fast, even as you introduce more tests in
your test suite. Furthermore, you can inject mock services into controllers through Spring
configuration in order to remain focused on testing the web layer. Here is an example of
declaring a mock service with Mockito:
<bean id="accountService" class="org.mockito.Mockito" factory-method="mock">
<constructor-arg value="org.example.AccountService"/>
</bean>

You can then inject the mock service into the test in order set up and verify expectations:
@RunWith(SpringRunner.class)
@WebAppConfiguration
@ContextConfiguration("test-servlet-context.xml")
public class AccountTests {
@Autowired
private WebApplicationContext wac;
private MockMvc mockMvc;
@Autowired
private AccountService accountService;
// ...
}

The "standaloneSetup" on the other hand is a little closer to a unit test. It tests one
controller at a time: the controller can be injected with mock dependencies manually, and
it doesnt involve loading Spring configuration. Such tests are more focused on style and
make it easier to see which controller is being tested, whether any specific Spring MVC
configuration is required to work, and so on. The "standaloneSetup" is also a very
convenient way to write ad-hoc tests to verify specific behavior or to debug an issue.
Just like with any "integration vs. unit testing" debate, there is no right or wrong answer.
However, using the "standaloneSetup" does imply the need for additional
"webAppContextSetup" tests in order to verify your Spring MVC configuration.

25/08/2016 12:10

Spring Framework Reference Documentation

485 de 1194

always test against your actual Spring MVC configuration.

Performing Requests
Its easy to perform requests using any HTTP method:
mockMvc.perform(post("/hotels/{id}", 42).accept(MediaType.APPLICATION_JSON));

You can also perform file upload requests that internally use
MockMultipartHttpServletRequest so that there is no actual parsing of a multipart
request but rather you have to set it up:
mockMvc.perform(fileUpload("/doc").file("a1", "ABC".getBytes("UTF-8")));

You can specify query parameters in URI template style:

mockMvc.perform(get("/hotels?foo={foo}", "bar"));

Or you can add Servlet request parameters representing either query of form parameters:
mockMvc.perform(get("/hotels").param("foo", "bar"));

If application code relies on Servlet request parameters and doesnt check the query
string explicitly (as is most often the case) then it doesnt matter which option you use.
Keep in mind however that query params provided with the URI template will be decoded
while request parameters provided through the param() method are expected to
already be decoded.
In most cases its preferable to leave out the context path and the Servlet path from the
request URI. If you must test with the full request URI, be sure to set the contextPath
and servletPath accordingly so that request mappings will work:
mockMvc.perform(get("/app/main/hotels/{id}").contextPath("/app").servletPath(

Looking at the above example, it would be cumbersome to set the contextPath and
servletPath with every performed request. Instead you can set up default request
properties:
public class MyWebTests {
private MockMvc mockMvc;
@Before

25/08/2016 12:10

Spring Framework Reference Documentation

486 de 1194

mockMvc = standaloneSetup(new AccountController())

.defaultRequest(get("/")
.contextPath("/app").servletPath("/main")
.accept(MediaType.APPLICATION_JSON).build();
}

The above properties will affect every request performed through the MockMvc instance.
If the same property is also specified on a given request, it overrides the default value.
That is why the HTTP method and URI in the default request dont matter since they must
be specified on every request.

Defining Expectations
Expectations can be defined by appending one or more .andExpect(..) calls after
performing a request:
mockMvc.perform(get("/accounts/1")).andExpect(status().isOk());

MockMvcResultMatchers.* provides a number of expectations, some of which are

further nested with more detailed expectations.
Expectations fall in two general categories. The first category of assertions verifies
properties of the response: for example, the response status, headers, and content.
These are the most important results to assert.
The second category of assertions goes beyond the response. These assertions allow
one to inspect Spring MVC specific aspects such as which controller method processed
the request, whether an exception was raised and handled, what the content of the model
is, what view was selected, what flash attributes were added, and so on. They also allow
one to inspect Servlet specific aspects such as request and session attributes.
The following test asserts that binding or validation failed:
mockMvc.perform(post("/persons"))
.andExpect(status().isOk())
.andExpect(model().attributeHasErrors("person"));

Many times when writing tests, its useful to dump the results of the performed request.
This can be done as follows, where print() is a static import from
MockMvcResultHandlers :
mockMvc.perform(post("/persons"))
.andDo(print())
.andExpect(status().isOk())

25/08/2016 12:10

Spring Framework Reference Documentation

487 de 1194

.andExpect(model().attributeHasErrors("person"));

As long as request processing does not cause an unhandled exception, the print()
method will print all the available result data to System.out . Spring Framework 4.2
introduced a log() method and two additional variants of the print() method, one
that accepts an OutputStream and one that accepts a Writer . For example, invoking
print(System.err) will print the result data to System.err ; while invoking
print(myWriter) will print the result data to a custom writer. If you would like to have
the result data logged instead of printed, simply invoke the log() method which will log
the result data as a single DEBUG message under the
org.springframework.test.web.servlet.result logging category.
In some cases, you may want to get direct access to the result and verify something that
cannot be verified otherwise. This can be achieved by appending .andReturn() after all
other expectations:

MvcResult mvcResult = mockMvc.perform(post("/persons")).andExpect(status().isOk()).and

// ...

If all tests repeat the same expectations you can set up common expectations once when
building the MockMvc instance:
standaloneSetup(new SimpleController())
.alwaysExpect(status().isOk())
.alwaysExpect(content().contentType("application/json;charset=UTF-8"))
.build()

Note that common expectations are always applied and cannot be overridden without
creating a separate MockMvc instance.
When JSON response content contains hypermedia links created with Spring HATEOAS,
the resulting links can be verified using JsonPath expressions:

mockMvc.perform(get("/people").accept(MediaType.APPLICATION_JSON))
.andExpect(jsonPath("$.links[?(@.rel == 'self')].href").value("http://localhost:80

When XML response content contains hypermedia links created with Spring HATEOAS,
the resulting links can be verified using XPath expressions:

Map<String, String> ns = Collections.singletonMap("ns", "http://www.w3.org/2005/Atom"

mockMvc.perform(get("/handle").accept(MediaType.APPLICATION_XML))
.andExpect(xpath("/person/ns:link[@rel='self']/@href", ns).string("http://localhos

25/08/2016 12:10

Spring Framework Reference Documentation

488 de 1194

Filter Registrations
When setting up a MockMvc instance, you can register one or more Servlet Filter
instances:

mockMvc = standaloneSetup(new PersonController()).addFilters(new CharacterEncodingFilt

Registered filters will be invoked through via the MockFilterChain from spring-test ,
and the last filter will delegate to the DispatcherServlet .

Differences between Out-of-Container and End-to-End Integration Tests

As mentioned earlier Spring MVC Test is built on the Servlet API mock objects from the
spring-test module and does not use a running Servlet container. Therefore there are
some important differences compared to full end-to-end integration tests with an actual
client and server running.
The easiest way to think about this is starting with a blank MockHttpServletRequest .
Whatever you add to it is what the request will be. Things that may catch you by surprise
are that there is no context path by default, no jsessionid cookie, no forwarding, error,
or async dispatches, and therefore no actual JSP rendering. Instead, "forwarded" and
"redirected" URLs are saved in the MockHttpServletResponse and can be asserted
with expectations.
This means if you are using JSPs you can verify the JSP page to which the request was
forwarded, but there wont be any HTML rendered. In other words, the JSP will not be
invoked. Note however that all other rendering technologies which dont rely on
forwarding such as Thymeleaf, Freemarker, and Velocity will render HTML to the
response body as expected. The same is true for rendering JSON, XML, and other
formats via @ResponseBody methods.
Alternatively you may consider the full end-to-end integration testing support from Spring
Boot via @WebIntegrationTest . See the Spring Boot reference.
There are pros and cons for each approach. The options provided in Spring MVC Test are
different stops on the scale from classic unit testing to full integration testing. To be
certain, none of the options in Spring MVC Test fall under the category of classic unit
testing, but they are a little closer to it. For example, you can isolate the web layer by
injecting mocked services into controllers, in which case youre testing the web layer only
through the DispatcherServlet but with actual Spring configuration, just like you might
test the data access layer in isolation from the layers above. Or you can use the
standalone setup focusing on one controller at a time and manually providing the

25/08/2016 12:10

Spring Framework Reference Documentation

489 de 1194

configuration required to make it work.

Another important distinction when using Spring MVC Test is that conceptually such tests
are on the inside of the server-side so you can check what handler was used, if an
exception was handled with a HandlerExceptionResolver, what the content of the model
is, what binding errors there were, etc. That means its easier to write expectations since
the server is not a black box as it is when testing it through an actual HTTP client. This is
generally an advantage of classic unit testing, that its easier to write, reason about, and
debug but does not replace the need for full integration tests. At the same time its
important not to lose sight of the fact that the response is the most important thing to
check. In short, there is room here for multiple styles and strategies of testing even within
the same project.

Further Server-Side Test Examples

The frameworks own tests include many sample tests intended to demonstrate how to
use Spring MVC Test. Browse these examples for further ideas. Also the springmvc-showcase has full test coverage based on Spring MVC Test.

15.6.2 HtmlUnit Integration

Spring provides integration between MockMvc and HtmlUnit. This simplifies performing
end-to-end testing when using HTML based views. This integration enables developers
to:
Easily test HTML pages using tools such as HtmlUnit, WebDriver, & Geb without the
need to deploy to a Servlet container
Test JavaScript within pages
Optionally test using mock services to speed up testing
Share logic between in-container end-to-end tests and out-of-container integration
tests

MockMvc works with templating technologies that do not rely on a Servlet

Container (e.g., Thymeleaf, Freemarker, Velocity, etc.), but it does not work
with JSPs since they rely on the Servlet Container.

Why HtmlUnit Integration?

The most obvious question that comes to mind is, "Why do I need this?". The answer is

25/08/2016 12:10

Spring Framework Reference Documentation

490 de 1194

web application that supports CRUD operations on a Message object. The application
also supports paging through all messages. How would you go about testing it?
With Spring MVC Test, we can easily test if we are able to create a Message .
MockHttpServletRequestBuilder createMessage = post("/messages/")
.param("summary", "Spring Rocks")
.param("text", "In case you didn't know, Spring Rocks!");
mockMvc.perform(createMessage)
.andExpect(status().is3xxRedirection())
.andExpect(redirectedUrl("/messages/123"));

What if we want to test our form view that allows us to create the message? For example,
assume our form looks like the following snippet:
<form id="messageForm" action="/messages/" method="post">
<div class="pull-right"><a href="/messages/">Messages</a></div>
<label for="summary">Summary</label>
<input type="text" class="required" id="summary" name="summary" value="" />
<label for="text">Message</label>
<textarea id="text" name="text"></textarea>
<div class="form-actions">
<input type="submit" value="Create" />
</div>
</form>

How do we ensure that our form will produce the correct request to create a new
message? A naive attempt would look like this:
mockMvc.perform(get("/messages/form"))
.andExpect(xpath("//input[@name='summary']").exists())
.andExpect(xpath("//textarea[@name='text']").exists());

This test has some obvious drawbacks. If we update our controller to use the parameter
message instead of text , our form test would continue to pass even though the HTML
form is out of synch with the controller. To resolve this we can combine our two tests.
String summaryParamName = "summary";
String textParamName = "text";
mockMvc.perform(get("/messages/form"))
.andExpect(xpath("//input[@name='" + summaryParamName + "']"
.andExpect(xpath("//textarea[@name='" + textParamName + "']"

25/08/2016 12:10

Spring Framework Reference Documentation

491 de 1194

MockHttpServletRequestBuilder createMessage = post("/messages/")

.param(summaryParamName, "Spring Rocks")
.param(textParamName, "In case you didn't know, Spring Rocks!"
mockMvc.perform(createMessage)
.andExpect(status().is3xxRedirection())
.andExpect(redirectedUrl("/messages/123"));

This would reduce the risk of our test incorrectly passing, but there are still some
problems.
What if we have multiple forms on our page? Admittedly we could update our xpath
expressions, but they get more complicated the more factors we take into account
(Are the fields the correct type? Are the fields enabled? etc.).
Another issue is that we are doing double the work we would expect. We must first
verify the view, and then we submit the view with the same parameters we just
verified. Ideally this could be done all at once.
Finally, there are some things that we still cannot account for. For example, what if
the form has JavaScript validation that we wish to test as well?
The overall problem is that testing a web page does not involve a single interaction.
Instead, it is a combination of how the user interacts with a web page and how that web
page interacts with other resources. For example, the result of a form view is used as the
input to a user for creating a message. In addition, our form view may potentially utilize
additional resources which impact the behavior of the page, such as JavaScript
validation.

Integration testing to the rescue?

To resolve the issues above we could perform end-to-end integration testing, but this has
some obvious drawbacks. Consider testing the view that allows us to page through the
messages. We might need the following tests.
Does our page display a notification to the user indicating that no results are available
when the messages are empty?
Does our page properly display a single message?
Does our page properly support paging?
To set up these tests, we would need to ensure our database contained the proper
messages in it. This leads to a number of additional challenges.
Ensuring the proper messages are in the database can be tedious; consider foreign

25/08/2016 12:10

Spring Framework Reference Documentation

492 de 1194

key constraints.
Testing can become slow since each test would need to ensure that the database is
in the correct state.
Since our database needs to be in a specific state, we cannot run tests in parallel.
Performing assertions on things like auto-generated ids, timestamps, etc. can be
difficult.
These challenges do not mean that we should abandon end-to-end integration testing
altogether. Instead, we can reduce the number of end-to-end integration tests by
refactoring our detailed tests to use mock services which will execute much faster, more
reliably, and without side effects. We can then implement a small number of true
end-to-end integration tests that validate simple workflows to ensure that everything
works together properly.

Enter HtmlUnit Integration

So how can we achieve a balance between testing the interactions of our pages and still
retain good performance within our test suite? The answer is: "By integrating MockMvc
with HtmlUnit."

HtmlUnit Integration Options

There are a number of ways to integrate MockMvc with HtmlUnit.
MockMvc and HtmlUnit: Use this option if you want to use the raw HtmlUnit libraries.
MockMvc and WebDriver: Use this option to ease development and reuse code
between integration and end-to-end testing.
MockMvc and Geb: Use this option if you would like to use Groovy for testing, ease
development, and reuse code between integration and end-to-end testing.

MockMvc and HtmlUnit

This section describes how to integrate MockMvc and HtmlUnit. Use this option if you
want to use the raw HtmlUnit libraries.

MockMvc and HtmlUnit Setup

First, make sure that you have included a test dependency on
net.sourceforge.htmlunit:htmlunit . In order to use HtmlUnit with Apache
HttpComponents 4.5+, you will need to use HtmlUnit 2.18 or higher.
We can easily create an HtmlUnit WebClient that integrates with MockMvc using the

25/08/2016 12:10

Spring Framework Reference Documentation

493 de 1194

MockMvcWebClientBuilder as follows.
@Autowired
WebApplicationContext context;
WebClient webClient;
@Before
public void setup() {
webClient = MockMvcWebClientBuilder
.webAppContextSetup(context)
.build();
}

This is a simple example of using MockMvcWebClientBuilder . For

advanced usage see the section called Advanced
MockMvcWebClientBuilder

This will ensure that any URL referencing localhost as the server will be directed to
our MockMvc instance without the need for a real HTTP connection. Any other URL will
be requested using a network connection as normal. This allows us to easily test the use
of CDNs.

MockMvc and HtmlUnit Usage

Now we can use HtmlUnit as we normally would, but without the need to deploy our
application to a Servlet container. For example, we can request the view to create a
message with the following.
HtmlPage createMsgFormPage = webClient.getPage("http://localhost/messages/form"

The default context path is "" . Alternatively, we can specify the context
path as illustrated in the section called Advanced
MockMvcWebClientBuilder.

Once we have a reference to the HtmlPage , we can then fill out the form and submit it to
create a message.
HtmlForm form = createMsgFormPage.getHtmlElementById("messageForm");
HtmlTextInput summaryInput = createMsgFormPage.getHtmlElementById("summary");

25/08/2016 12:10

Spring Framework Reference Documentation

494 de 1194

HtmlTextArea textInput = createMsgFormPage.getHtmlElementById("text");

textInput.setText("In case you didn't know, Spring Rocks!");
HtmlSubmitInput submit = form.getOneHtmlElementByAttribute("input", "type",
HtmlPage newMessagePage = submit.click();

Finally, we can verify that a new message was created successfully. The following
assertions use the AssertJ library.
assertThat(newMessagePage.getUrl().toString()).endsWith("/messages/123");
String id = newMessagePage.getHtmlElementById("id").getTextContent();
assertThat(id).isEqualTo("123");
String summary = newMessagePage.getHtmlElementById("summary").getTextContent();
assertThat(summary).isEqualTo("Spring Rocks");
String text = newMessagePage.getHtmlElementById("text").getTextContent();
assertThat(text).isEqualTo("In case you didn't know, Spring Rocks!");

This improves on our MockMvc test in a number of ways. First we no longer have to
explicitly verify our form and then create a request that looks like the form. Instead, we
request the form, fill it out, and submit it, thereby significantly reducing the overhead.
Another important factor is that HtmlUnit uses the Mozilla Rhino engine to evaluate
JavaScript. This means that we can test the behavior of JavaScript within our pages as
well!
Refer to the HtmlUnit documentation for additional information about using HtmlUnit.

Advanced MockMvcWebClientBuilder
In the examples so far, we have used MockMvcWebClientBuilder in the simplest way
possible, by building a WebClient based on the WebApplicationContext loaded for
us by the Spring TestContext Framework. This approach is repeated here.
@Autowired
WebApplicationContext context;
WebClient webClient;
@Before
public void setup() {
webClient = MockMvcWebClientBuilder
.webAppContextSetup(context)
.build();
}

We can also specify additional configuration options.

25/08/2016 12:10

Spring Framework Reference Documentation

495 de 1194

WebClient webClient;

@Before
public void setup() {
webClient = MockMvcWebClientBuilder
// demonstrates applying a MockMvcConfigurer (Spring Security)
.webAppContextSetup(context, springSecurity())
// for illustration only - defaults to ""
.contextPath("")
// By default MockMvc is used for localhost only;
// the following will use MockMvc for example.com and example.org as w
.useMockMvcForHosts("example.com","example.org")
.build();
}

As an alternative, we can perform the exact same setup by configuring the MockMvc
instance separately and supplying it to the MockMvcWebClientBuilder as follows.
MockMvc mockMvc = MockMvcBuilders
.webAppContextSetup(context)
.apply(springSecurity())
.build();

webClient = MockMvcWebClientBuilder
.mockMvcSetup(mockMvc)
// for illustration only - defaults to ""
.contextPath("")
// By default MockMvc is used for localhost only;
// the following will use MockMvc for example.com and example.org as w
.useMockMvcForHosts("example.com","example.org")
.build();

This is more verbose, but by building the WebClient with a MockMvc instance we have
the full power of MockMvc at our fingertips.

For additional information on creating a MockMvc instance refer to the

section called Setup Options.

MockMvc and WebDriver

In the previous sections, we have seen how to use MockMvc in conjunction with the raw
HtmlUnit APIs. In this section, we will leverage additional abstractions within the Selenium
WebDriver to make things even easier.

25/08/2016 12:10

Spring Framework Reference Documentation

496 de 1194

Why WebDriver and MockMvc?

We can already use HtmlUnit and MockMvc , so why would we want to use WebDriver ?
The Selenium WebDriver provides a very elegant API that allows us to easily organize
our code. To better understand, lets explore an example.

Despite being a part of Selenium, WebDriver does not require a Selenium

Server to run your tests.

Suppose we need to ensure that a message is created properly. The tests involve finding
the HTML form input elements, filling them out, and making various assertions.
This approach results in numerous, separate tests because we want to test error
conditions as well. For example, we want to ensure that we get an error if we fill out only
part of the form. If we fill out the entire form, the newly created message should be
displayed afterwards.
If one of the fields were named "summary", then we might have something like the
following repeated in multiple places within our tests.
HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary");
summaryInput.setValueAttribute(summary);

So what happens if we change the id to "smmry"? Doing so would force us to update all
of our tests to incorporate this change! Of course, this violates the DRY Principle; so we
should ideally extract this code into its own method as follows.
public HtmlPage createMessage(HtmlPage currentPage, String summary, String text) {
setSummary(currentPage, summary);
// ...
}
public void setSummary(HtmlPage currentPage, String summary) {
HtmlTextInput summaryInput = currentPage.getHtmlElementById("summary"
summaryInput.setValueAttribute(summary);
}

This ensures that we do not have to update all of our tests if we change the UI.
We might even take this a step further and place this logic within an Object that
represents the HtmlPage we are currently on.
public class CreateMessagePage {

25/08/2016 12:10

Spring Framework Reference Documentation

497 de 1194

final HtmlPage currentPage;

final HtmlTextInput summaryInput;
final HtmlSubmitInput submit;
public CreateMessagePage(HtmlPage currentPage) {
this.currentPage = currentPage;
this.summaryInput = currentPage.getHtmlElementById("summary"
this.submit = currentPage.getHtmlElementById("submit");
}
public <T> T createMessage(String summary, String text) throws Exception {
setSummary(summary);
HtmlPage result = submit.click();
boolean error = CreateMessagePage.at(result);

return (T) (error ? new CreateMessagePage(result) : new ViewMessagePag

}
public void setSummary(String summary) throws Exception {
summaryInput.setValueAttribute(summary);
}
public static boolean at(HtmlPage page) {
return "Create Message".equals(page.getTitleText());
}
}

Formerly, this pattern is known as the Page Object Pattern. While we can certainly do this
with HtmlUnit, WebDriver provides some tools that we will explore in the following
sections to make this pattern much easier to implement.

MockMvc and WebDriver Setup

To use Selenium WebDriver with the Spring MVC Test framework, make sure that your
project includes a test dependency on
org.seleniumhq.selenium:selenium-htmlunit-driver .
We can easily create a Selenium WebDriver that integrates with MockMvc using the
MockMvcHtmlUnitDriverBuilder as follows.
@Autowired
WebApplicationContext context;

25/08/2016 12:10

Spring Framework Reference Documentation

498 de 1194

WebDriver driver;
@Before
public void setup() {
driver = MockMvcHtmlUnitDriverBuilder
.webAppContextSetup(context)
.build();
}

This is a simple example of using MockMvcHtmlUnitDriverBuilder . For

more advanced usage, refer to the section called Advanced
MockMvcHtmlUnitDriverBuilder

MockMvc and WebDriver Usage

Now we can use WebDriver as we normally would, but without the need to deploy our
application to a Servlet container. For example, we can request the view to create a
message with the following.
CreateMessagePage page = CreateMessagePage.to(driver);

We can then fill out the form and submit it to create a message.
ViewMessagePage viewMessagePage =
page.createMessage(ViewMessagePage.class, expectedSummary, expectedText);

This improves on the design of our HtmlUnit test by leveraging the Page Object Pattern.
As we mentioned in the section called Why WebDriver and MockMvc?, we can use the
Page Object Pattern with HtmlUnit, but it is much easier with WebDriver. Lets take a look
at our new CreateMessagePage implementation.
public class CreateMessagePage
extends AbstractPage {

private WebElement summary;

25/08/2016 12:10

Spring Framework Reference Documentation

499 de 1194

@FindBy(css = "input[type=submit]")
private WebElement submit;
public CreateMessagePage(WebDriver driver) {
super(driver);
}

public <T> T createMessage(Class<T> resultPage, String summary, String details

this.summary.sendKeys(summary);
this.text.sendKeys(details);
this.submit.click();
return PageFactory.initElements(driver, resultPage);
}
public static CreateMessagePage to(WebDriver driver) {
driver.get("http://localhost:9990/mail/messages/form");
return PageFactory.initElements(driver, CreateMessagePage.class
}
}

The first thing you will notice is that CreateMessagePage extends the
AbstractPage . We wont go over the details of AbstractPage , but in summary it
contains common functionality for all of our pages. For example, if our application
has a navigational bar, global error messages, etc., this logic can be placed in a
shared location.
The next thing you will notice is that we have a member variable for each of the
parts of the HTML page that we are interested in. These are of type WebElement .
WebDriver 's PageFactory allows us to remove a lot of code from the HtmlUnit
version of CreateMessagePage by automatically resolving each WebElement . The
PageFactory#initElements(WebDriver,Class<T>) method will automatically resolve
each WebElement by using the field name and looking it up by the id or name of
the element within the HTML page.
We can use the @FindBy annotation to override the default lookup behavior. Our
example demonstrates how to use the @FindBy annotation to look up our submit
button using a css selector, input[type=submit].
Finally, we can verify that a new message was created successfully. The following
assertions use the FEST assertion library.

assertThat(viewMessagePage.getMessage()).isEqualTo(expectedMessage);
assertThat(viewMessagePage.getSuccess()).isEqualTo("Successfully created a new message

25/08/2016 12:10

Spring Framework Reference Documentation

500 de 1194

model. For example, it exposes a method that returns a Message object.

public Message getMessage() throws ParseException {
Message message = new Message();
message.setId(getId());
message.setCreated(getCreated());
message.setSummary(getSummary());
message.setText(getText());
return message;
}

We can then leverage the rich domain objects in our assertions.

Lastly, dont forget to close the WebDriver instance when the test is complete.
@After
public void destroy() {
if (driver != null) {
driver.close();
}
}

For additional information on using WebDriver, refer to the Selenium WebDriver

documentation.

Advanced MockMvcHtmlUnitDriverBuilder
In the examples so far, we have used MockMvcHtmlUnitDriverBuilder in the simplest
way possible, by building a WebDriver based on the WebApplicationContext loaded
for us by the Spring TestContext Framework. This approach is repeated here.
@Autowired
WebApplicationContext context;
WebDriver driver;
@Before
public void setup() {
driver = MockMvcHtmlUnitDriverBuilder
.webAppContextSetup(context)
.build();
}

We can also specify additional configuration options.

WebDriver driver;

25/08/2016 12:10

Spring Framework Reference Documentation

501 de 1194

@Before
public void setup() {
driver = MockMvcHtmlUnitDriverBuilder
// demonstrates applying a MockMvcConfigurer (Spring Security)
.webAppContextSetup(context, springSecurity())
// for illustration only - defaults to ""
.contextPath("")
// By default MockMvc is used for localhost only;
// the following will use MockMvc for example.com and example.org as w
.useMockMvcForHosts("example.com","example.org")
.build();
}

As an alternative, we can perform the exact same setup by configuring the MockMvc
instance separately and supplying it to the MockMvcHtmlUnitDriverBuilder as follows.
MockMvc mockMvc = MockMvcBuilders
.webAppContextSetup(context)
.apply(springSecurity())
.build();

driver = MockMvcHtmlUnitDriverBuilder
.mockMvcSetup(mockMvc)
// for illustration only - defaults to ""
.contextPath("")
// By default MockMvc is used for localhost only;
// the following will use MockMvc for example.com and example.org as w
.useMockMvcForHosts("example.com","example.org")
.build();

This is more verbose, but by building the WebDriver with a MockMvc instance we have
the full power of MockMvc at our fingertips.

For additional information on creating a MockMvc instance refer to the

section called Setup Options.

MockMvc and Geb

In the previous section, we saw how to use MockMvc with WebDriver . In this section,
we will use Geb to make our tests even Groovy-er.

Why Geb and MockMvc?

25/08/2016 12:10

Spring Framework Reference Documentation

502 de 1194

Geb is backed by WebDriver, so it offers many of the same benefits that we get from
WebDriver. However, Geb makes things even easier by taking care of some of the
boilerplate code for us.

MockMvc and Geb Setup

We can easily initialize a Geb Browser with a Selenium WebDriver that uses MockMvc
as follows.
def setup() {
browser.driver = MockMvcHtmlUnitDriverBuilder
.webAppContextSetup(context)
.build()
}

This is a simple example of using MockMvcHtmlUnitDriverBuilder . For

more advanced usage, refer to the section called Advanced
MockMvcHtmlUnitDriverBuilder

MockMvc and Geb Usage

Now we can use Geb as we normally would, but without the need to deploy our
application to a Servlet container. For example, we can request the view to create a
message with the following:
to CreateMessagePage

We can then fill out the form and submit it to create a message.
when:
form.summary = expectedSummary
form.text = expectedMessage
submit.click(ViewMessagePage)

Any unrecognized method calls or property accesses/references that are not found will be
forwarded to the current page object. This removes a lot of the boilerplate code we

25/08/2016 12:10

Spring Framework Reference Documentation

503 de 1194

As with direct WebDriver usage, this improves on the design of our HtmlUnit test by
leveraging the Page Object Pattern. As mentioned previously, we can use the Page
Object Pattern with HtmlUnit and WebDriver, but it is even easier with Geb. Lets take a
look at our new Groovy-based CreateMessagePage implementation.
class CreateMessagePage extends Page {
static url = 'messages/form'
static at = { assert title == 'Messages : Create'; true }
static content = {
submit { $('input[type=submit]') }
form { $('form') }
errors(required:false) { $('label.error, .alert-error')?.text() }
}
}

The first thing you will notice is that our CreateMessagePage extends Page . We wont
go over the details of Page , but in summary it contains common functionality for all of our
pages. The next thing you will notice is that we define a URL in which this page can be
found. This allows us to navigate to the page as follows.
to CreateMessagePage

We also have an at closure that determines if we are at the specified page. It should
return true if we are on the correct page. This is why we can assert that we are on the
correct page as follows.
then:
at CreateMessagePage
errors.contains('This field is required.')

We use an assertion in the closure, so that we can determine where things

went wrong if we were at the wrong page.

Next we create a content closure that specifies all the areas of interest within the page.
We can use a jQuery-ish Navigator API to select the content we are interested in.
Finally, we can verify that a new message was created successfully.
then:
at ViewMessagePage
success == 'Successfully created a new message'
id
date

25/08/2016 12:10

Spring Framework Reference Documentation

504 de 1194

summary == expectedSummary
message == expectedMessage

For further details on how to get the most out of Geb, consult The Book of Geb users
manual.

15.6.3 Client-Side REST Tests

Client-side tests can be used to test code that internally uses the RestTemplate . The
idea is to declare expected requests and to provide "stub" responses so that you can
focus on testing the code in isolation, i.e. without running a server. Here is an example:
RestTemplate restTemplate = new RestTemplate();

MockRestServiceServer mockServer = MockRestServiceServer.bindTo(restTemplate).build();

mockServer.expect(requestTo("/greeting")).andRespond(withSuccess());
// Test code that uses the above RestTemplate ...
mockServer.verify();

In the above example, MockRestServiceServer , the central class for client-side REST
tests, configures the RestTemplate with a custom ClientHttpRequestFactory that
asserts actual requests against expectations and returns "stub" responses. In this case
we expect a request to "/greeting" and want to return a 200 response with "text/plain"
content. We could define as additional expected requests and stub responses as needed.
When expected requests and stub responses are defined, the RestTemplate can be
used in client-side code as usual. At the end of testing mockServer.verify() can be
used to verify that all expectations have been satisfied.
By default requests are expected in the order in which expectations were declared. You
can set the ignoreExpectOrder option when building the server in which case all
expectations are checked (in order) to find a match for a given request. That means
requests are allowed to come in any order. Here is an example:
server = MockRestServiceServer.bindTo(restTemplate).ignoreExpectOrder(true).build();

Even with unordered requests by default each request is allowed to execute once only.
The expect method provides an overloaded variant that accepts an ExpectedCount
argument that specifies a count range, e.g. once , manyTimes , max , min , between ,
and so on. Here is an example:

25/08/2016 12:10

Spring Framework Reference Documentation

505 de 1194

MockRestServiceServer mockServer = MockRestServiceServer.bindTo(restTemplate).build();

mockServer.expect(times(2), requestTo("/foo")).andRespond(withSuccess());
mockServer.expect(times(3), requestTo("/bar")).andRespond(withSuccess());
// ...
mockServer.verify();

Note that when ignoreExpectOrder is not set (the default), and therefore requests are
expected in order of declaration, then that order only applies to the first of any expected
request. For example if "/foo" is expected 2 times followed by "/bar" 3 times, then there
should be a request to "/foo" before there is a request to "/bar" but aside from that
subsequent "/foo" and "/bar" requests can come at any time.
As an alternative to all of the above the client-side test support also provides a
ClientHttpRequestFactory implementation that can be configured into a
RestTemplate to bind it to a MockMvc instance. That allows processing requests using
actual server-side logic but without running a server. Here is an example:
MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
this.restTemplate = new RestTemplate(new MockMvcClientHttpRequestFactory(mockMvc));
// Test code that uses the above RestTemplate ...
mockServer.verify();

Static Imports
Just like with server-side tests, the fluent API for client-side tests requires a few static
imports. Those are easy to find by searching "MockRest*". Eclipse users should add
"MockRestRequestMatchers.*" and "MockRestResponseCreators.*" as "favorite
static members" in the Eclipse preferences under Java Editor Content Assist
Favorites. That allows using content assist after typing the first character of the static
method name. Other IDEs (e.g. IntelliJ) may not require any additional configuration. Just
check the support for code completion on static members.

Further Examples of Client-side REST Tests

Spring MVC Tests own tests include example tests of client-side REST tests.

15.7 PetClinic Example

25/08/2016 12:10

Spring Framework Reference Documentation

506 de 1194

The PetClinic application, available on GitHub, illustrates several features of the Spring
TestContext Framework in a JUnit 4 environment. Most test functionality is included in the
AbstractClinicTests , for which a partial listing is shown below:
import static org.junit.Assert.assertEquals;
// import ...

@ContextConfiguration
public abstract class AbstractClinicTests extends AbstractTransactionalJUnit4SpringCon
@Autowired
protected Clinic clinic;
@Test
public void getVets() {
Collection<Vet> vets = this.clinic.getVets();
assertEquals("JDBC query must show the same number of vets",
super.countRowsInTable("VETS"), vets.size());
Vet v1 = EntityUtils.getById(vets, Vet.class, 2);
assertEquals("Leary", v1.getLastName());
assertEquals(1, v1.getNrOfSpecialties());
assertEquals("radiology", (v1.getSpecialties().get(0)).getName());
// ...
}
// ...
}

Notes:
This test case extends the AbstractTransactionalJUnit4SpringContextTests
class, from which it inherits configuration for Dependency Injection (through the
DependencyInjectionTestExecutionListener ) and transactional behavior
(through the TransactionalTestExecutionListener ).
The clinic instance variablethe application object being testedis set by
Dependency Injection through @Autowired semantics.
The getVets() method illustrates how you can use the inherited
countRowsInTable() method to easily verify the number of rows in a given table,
thus verifying correct behavior of the application code being tested. This allows for
stronger tests and lessens dependency on the exact test data. For example, you can
add additional rows in the database without breaking tests.
Like many integration tests that use a database, most of the tests in
AbstractClinicTests depend on a minimum amount of data already in the
database before the test cases run. Alternatively, you might choose to populate the

25/08/2016 12:10

Spring Framework Reference Documentation

507 de 1194

database within the test fixture set up of your test casesagain, within the same
transaction as the tests.
The PetClinic application supports three data access technologies: JDBC, Hibernate, and
JPA. By declaring @ContextConfiguration without any specific resource locations, the
AbstractClinicTests class will have its application context loaded from the default
location, AbstractClinicTests-context.xml , which declares a common
DataSource . Subclasses specify additional context locations that must declare a
PlatformTransactionManager and a concrete implementation of Clinic .
For example, the Hibernate implementation of the PetClinic tests contains the following
implementation. For this example, HibernateClinicTests does not contain a single
line of code: we only need to declare @ContextConfiguration , and the tests are
inherited from AbstractClinicTests . Because @ContextConfiguration is declared
without any specific resource locations, the Spring TestContext Framework loads an
application context from all the beans defined in AbstractClinicTests-context.xml
(i.e., the inherited locations) and HibernateClinicTests-context.xml , with
HibernateClinicTests-context.xml possibly overriding beans defined in
AbstractClinicTests-context.xml .
@ContextConfiguration
public class HibernateClinicTests extends AbstractClinicTests { }

In a large-scale application, the Spring configuration is often split across multiple files.
Consequently, configuration locations are typically specified in a common base class for
all application-specific integration tests. Such a base class may also add useful instance
variablespopulated by Dependency Injection, naturallysuch as a SessionFactory
in the case of an application using Hibernate.
As far as possible, you should have exactly the same Spring configuration files in your
integration tests as in the deployed environment. One likely point of difference concerns
database connection pooling and transaction infrastructure. If you are deploying to a
full-blown application server, you will probably use its connection pool (available through
JNDI) and JTA implementation. Thus in production you will use a
JndiObjectFactoryBean or <jee:jndi-lookup> for the DataSource and
JtaTransactionManager . JNDI and JTA will not be available in out-of-container
integration tests, so you should use a combination like the Commons DBCP
BasicDataSource and DataSourceTransactionManager or
HibernateTransactionManager for them. You can factor out this variant behavior into
a single XML file, having the choice between application server and a 'local' configuration
separated from all other configuration, which will not vary between the test and production

25/08/2016 12:10

Spring Framework Reference Documentation

508 de 1194

environments. In addition, it is advisable to use properties files for connection settings.

See the PetClinic application for an example.

16. Further Resources

Consult the following resources for more information about testing:
JUnit: "A programmer-oriented testing framework for Java". Used by the Spring
Framework in its test suite.
TestNG: A testing framework inspired by JUnit with added support for annotations,
test groups, data-driven testing, distributed testing, etc.
AssertJ: "Fluent assertions for Java" including support for Java 8 lambdas, streams,
etc.
Mock Objects: Article in Wikipedia.
MockObjects.com: Web site dedicated to mock objects, a technique for improving the
design of code within test-driven development.
Mockito: Java mock library based on the test spy pattern.
EasyMock: Java library "that provides Mock Objects for interfaces (and objects
through the class extension) by generating them on the fly using Javas proxy
mechanism." Used by the Spring Framework in its test suite.
JMock: Library that supports test-driven development of Java code with mock
objects.
DbUnit: JUnit extension (also usable with Ant and Maven) targeted for databasedriven projects that, among other things, puts your database into a known state
between test runs.
The Grinder: Java load testing framework.

Part V. Data Access

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.
Springs 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.

25/08/2016 12:10

Spring Framework Reference Documentation

509 de 1194

Chapter 18, DAO support

Chapter 19, Data access with JDBC
Chapter 20, Object Relational Mapping (ORM) Data Access
Chapter 21, Marshalling XML using O/X Mappers

17. Transaction Management

17.1 Introduction to Spring Framework transaction
management
Comprehensive transaction support is among the most compelling reasons to use the
Spring Framework. The Spring Framework provides a consistent abstraction for
transaction management that delivers the following benefits:
Consistent programming model across different transaction APIs such as Java
Transaction API (JTA), JDBC, Hibernate, Java Persistence API (JPA), and Java Data
Objects (JDO).
Support for declarative transaction management.
Simpler API for programmatic transaction management than complex transaction
APIs such as JTA.
Excellent integration with Springs data access abstractions.
The following sections describe the Spring Frameworks transaction value-adds and
technologies. (The chapter also includes discussions of best practices, application server
integration, and solutions to common problems.)
Advantages of the Spring Frameworks transaction support model describes why you
would use the Spring Frameworks transaction abstraction instead of EJB ContainerManaged Transactions (CMT) or choosing to drive local transactions through a
proprietary API such as Hibernate.
Understanding the Spring Framework transaction abstraction outlines the core
classes and describes how to configure and obtain DataSource instances from a
variety of sources.
Synchronizing resources with transactionsdescribes how the application code
ensures that resources are created, reused, and cleaned up properly.
Declarative transaction management describes support for declarative transaction
management.
Programmatic transaction management covers support for programmatic (that is,

25/08/2016 12:10

Spring Framework Reference Documentation

510 de 1194

Transaction bound event describes how you could use application events within a
transaction.

17.2 Advantages of the Spring Frameworks transaction

support model
Traditionally, Java EE developers have had two choices for transaction management:
global or local transactions, both of which have profound limitations. Global and local
transaction management is reviewed in the next two sections, followed by a discussion of
how the Spring Frameworks transaction management support addresses the limitations
of the global and local transaction models.

17.2.1 Global transactions

Global transactions enable you to work with multiple transactional resources, typically
relational databases and message queues. The application server manages global
transactions through the JTA, which is a cumbersome API to use (partly due to its
exception model). Furthermore, a JTA UserTransaction normally needs to be sourced
from JNDI, meaning that you also need to use JNDI in order to use JTA. Obviously the
use of global transactions would limit any potential reuse of application code, as JTA is
normally only available in an application server environment.
Previously, the preferred way to use global transactions was via EJB CMT (Container
Managed Transaction): CMT is a form of declarative transaction management (as
distinguished from programmatic transaction management). EJB CMT removes the need
for transaction-related JNDI lookups, although of course the use of EJB itself necessitates
the use of JNDI. It removes most but not all of the need to write Java code to control
transactions. The significant downside is that CMT is tied to JTA and an application server
environment. Also, it is only available if one chooses to implement business logic in EJBs,
or at least behind a transactional EJB facade. The negatives of EJB in general are so
great that this is not an attractive proposition, especially in the face of compelling
alternatives for declarative transaction management.

17.2.2 Local transactions

Local transactions are resource-specific, such as a transaction associated with a JDBC
connection. Local transactions may be easier to use, but have significant disadvantages:
they cannot work across multiple transactional resources. For example, code that

25/08/2016 12:10

Spring Framework Reference Documentation

511 de 1194

transaction. Because the application server is not involved in transaction management, it

cannot help ensure correctness across multiple resources. (It is worth noting that most
applications use a single transaction resource.) Another downside is that local
transactions are invasive to the programming model.

17.2.3 Spring Frameworks consistent programming model

Spring resolves the disadvantages of global and local transactions. It enables application
developers to use a consistent programming model in any environment. You write your
code once, and it can benefit from different transaction management strategies in
different environments. The Spring Framework provides both declarative and
programmatic transaction management. Most users prefer declarative transaction
management, which is recommended in most cases.
With programmatic transaction management, developers work with the Spring Framework
transaction abstraction, which can run over any underlying transaction infrastructure. With
the preferred declarative model, developers typically write little or no code related to
transaction management, and hence do not depend on the Spring Framework transaction
API, or any other transaction API.

25/08/2016 12:10

Spring Framework Reference Documentation

512 de 1194

Do you need an application server for transaction management?

The Spring Frameworks transaction management support changes traditional rules
as to when an enterprise Java application requires an application server.
In particular, you do not need an application server simply for declarative
transactions through EJBs. In fact, even if your application server has powerful JTA
capabilities, you may decide that the Spring Frameworks declarative transactions
offer more power and a more productive programming model than EJB CMT.
Typically you need an application servers JTA capability only if your application
needs to handle transactions across multiple resources, which is not a requirement
for many applications. Many high-end applications use a single, highly scalable
database (such as Oracle RAC) instead. Standalone transaction managers such as
Atomikos Transactions and JOTM are other options. Of course, you may need other
application server capabilities such as Java Message Service (JMS) and Java EE
Connector Architecture (JCA).
The Spring Framework gives you the choice of when to scale your application to a
fully loaded application server. Gone are the days when the only alternative to using
EJB CMT or JTA was to write code with local transactions such as those on JDBC
connections, and face a hefty rework if you need that code to run within global,
container-managed transactions. With the Spring Framework, only some of the
bean definitions in your configuration file, rather than your code, need to change.

17.3 Understanding the Spring Framework transaction

abstraction
The key to the Spring transaction abstraction is the notion of a transaction strategy. A
transaction strategy is defined by the
org.springframework.transaction.PlatformTransactionManager interface:
public interface PlatformTransactionManager {
TransactionStatus getTransaction(
TransactionDefinition definition) throws TransactionException;
void commit(TransactionStatus status) throws TransactionException;
void rollback(TransactionStatus status) throws TransactionException;
}

This is primarily a service provider interface (SPI), although it can be used

25/08/2016 12:10

Spring Framework Reference Documentation

513 de 1194

programmatically from your application code. Because PlatformTransactionManager

is an interface, it can be easily mocked or stubbed as necessary. It is not tied to a lookup
strategy such as JNDI. PlatformTransactionManager implementations are defined like
any other object (or bean) in the Spring Framework IoC container. This benefit alone
makes Spring Framework transactions a worthwhile abstraction even when you work with
JTA. Transactional code can be tested much more easily than if it used JTA directly.
Again in keeping with Springs philosophy, the TransactionException that can be
thrown by any of the PlatformTransactionManager interfaces methods is unchecked
(that is, it extends the java.lang.RuntimeException class). Transaction infrastructure
failures are almost invariably fatal. In rare cases where application code can actually
recover from a transaction failure, the application developer can still choose to catch and
handle TransactionException . The salient point is that developers are not forced to do
so.
The getTransaction(..) method returns a TransactionStatus object, depending
on a TransactionDefinition parameter. The returned TransactionStatus might
represent a new transaction, or can represent an existing transaction if a matching
transaction exists in the current call stack. The implication in this latter case is that, as
with Java EE transaction contexts, a TransactionStatus is associated with a thread of
execution.
The TransactionDefinition interface specifies:
Isolation: The degree to which this transaction is isolated from the work of other
transactions. For example, can this transaction see uncommitted writes from other
transactions?
Propagation: Typically, all code executed within a transaction scope will run in that
transaction. However, you have the option of specifying the behavior in the event that
a transactional method is executed when a transaction context already exists. For
example, code can continue running in the existing transaction (the common case);
or the existing transaction can be suspended and a new transaction created. Spring
offers all of the transaction propagation options familiar from EJB CMT. To read about
the semantics of transaction propagation in Spring, see Section 17.5.7, Transaction
propagation.
Timeout: How long this transaction runs before timing out and being rolled back
automatically by the underlying transaction infrastructure.
Read-only status: A read-only transaction can be used when your code reads but
does not modify data. Read-only transactions can be a useful optimization in some
cases, such as when you are using Hibernate.

25/08/2016 12:10

Spring Framework Reference Documentation

514 de 1194

that discuss transaction isolation levels and other core transaction concepts.
Understanding these concepts is essential to using the Spring Framework or any
transaction management solution.
The TransactionStatus interface provides a simple way for transactional code to
control transaction execution and query transaction status. The concepts should be
familiar, as they are common to all transaction APIs:
public interface TransactionStatus extends SavepointManager {
boolean isNewTransaction();
boolean hasSavepoint();
void setRollbackOnly();
boolean isRollbackOnly();
void flush();
boolean isCompleted();
}

Regardless of whether you opt for declarative or programmatic transaction management

in Spring, defining the correct PlatformTransactionManager implementation is
absolutely essential. You typically define this implementation through dependency
injection.
PlatformTransactionManager implementations normally require knowledge of the
environment in which they work: JDBC, JTA, Hibernate, and so on. The following
examples show how you can define a local PlatformTransactionManager
implementation. (This example works with plain JDBC.)
You define a JDBC DataSource
<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method
<property name="driverClassName" value="${jdbc.driverClassName}" />
<property name="url" value="${jdbc.url}" />
<property name="username" value="${jdbc.username}" />
<property name="password" value="${jdbc.password}" />
</bean>

The related PlatformTransactionManager bean definition will then have a reference to

the DataSource definition. It will look like this:

25/08/2016 12:10

Spring Framework Reference Documentation

515 de 1194

<bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionM

If you use JTA in a Java EE container then you use a container DataSource , obtained
through JNDI, in conjunction with Springs JtaTransactionManager . This is what the
JTA and JNDI lookup version would look like:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jee="http://www.springframework.org/schema/jee"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/jee
http://www.springframework.org/schema/jee/spring-jee.xsd">
<jee:jndi-lookup id="dataSource" jndi-name="jdbc/jpetstore"/>

<bean id="txManager" class="org.springframework.transaction.jta.JtaTransactionMana

</beans>

The JtaTransactionManager does not need to know about the DataSource , or any
other specific resources, because it uses the containers global transaction management
infrastructure.

The above definition of the dataSource bean uses the <jndi-lookup/>

tag from the jee namespace. For more information on schema-based
configuration, see Chapter 41, XML Schema-based configuration, and for
more information on the <jee/> tags see the section entitled
Section 41.2.3, the jee schema.

You can also use Hibernate local transactions easily, as shown in the following examples.
In this case, you need to define a Hibernate LocalSessionFactoryBean , which your
application code will use to obtain Hibernate Session instances.
The DataSource bean definition will be similar to the local JDBC example shown
previously and thus is not shown in the following example.

25/08/2016 12:10

Spring Framework Reference Documentation

516 de 1194

If the DataSource , used by any non-JTA transaction manager, is looked up

via JNDI and managed by a Java EE container, then it should be
non-transactional because the Spring Framework, rather than the Java EE
container, will manage the transactions.

The txManager bean in this case is of the HibernateTransactionManager type. In

the same way as the DataSourceTransactionManager needs a reference to the
DataSource , the HibernateTransactionManager needs a reference to the
SessionFactory .

<bean id="sessionFactory" class="org.springframework.orm.hibernate5.LocalSessionFactor

<property name="dataSource" ref="dataSource"/>
<property name="mappingResources">
<list>
<value>org/springframework/samples/petclinic/hibernate/petclinic.hbm.xml
</list>
</property>
<property name="hibernateProperties">
<value>
hibernate.dialect=${hibernate.dialect}
</value>
</property>
</bean>

<bean id="txManager" class="org.springframework.orm.hibernate5.HibernateTransactionMan

If you are using Hibernate and Java EE container-managed JTA transactions, then you
should simply use the same JtaTransactionManager as in the previous JTA example
for JDBC.

<bean id="txManager" class="org.springframework.transaction.jta.JtaTransactionManager"

If you use JTA , then your transaction manager definition will look the same
regardless of what data access technology you use, be it JDBC, Hibernate
JPA or any other supported technology. This is due to the fact that JTA
transactions are global transactions, which can enlist any transactional
resource.

In all these cases, application code does not need to change. You can change how

25/08/2016 12:10

Spring Framework Reference Documentation

517 de 1194

transactions are managed merely by changing configuration, even if that change means
moving from local to global transactions or vice versa.

17.4 Synchronizing resources with transactions

It should now be clear how you create different transaction managers, and how they are
linked to related resources that need to be synchronized to transactions (for example
DataSourceTransactionManager to a JDBC DataSource ,
HibernateTransactionManager to a Hibernate SessionFactory , and so forth). This
section describes how the application code, directly or indirectly using a persistence API
such as JDBC, Hibernate, or JDO, ensures that these resources are created, reused, and
cleaned up properly. The section also discusses how transaction synchronization is
triggered (optionally) through the relevant PlatformTransactionManager .

17.4.1 High-level synchronization approach

The preferred approach is to use Springs highest level template based persistence
integration APIs or to use native ORM APIs with transaction- aware factory beans or
proxies for managing the native resource factories. These transaction-aware solutions
internally handle resource creation and reuse, cleanup, optional transaction
synchronization of the resources, and exception mapping. Thus user data access code
does not have to address these tasks, but can be focused purely on non-boilerplate
persistence logic. Generally, you use the native ORM API or take a template approach for
JDBC access by using the JdbcTemplate . These solutions are detailed in subsequent
chapters of this reference documentation.

17.4.2 Low-level synchronization approach

Classes such as DataSourceUtils (for JDBC), EntityManagerFactoryUtils (for
JPA), SessionFactoryUtils (for Hibernate), PersistenceManagerFactoryUtils (for
JDO), and so on exist at a lower level. When you want the application code to deal
directly with the resource types of the native persistence APIs, you use these classes to
ensure that proper Spring Framework-managed instances are obtained, transactions are
(optionally) synchronized, and exceptions that occur in the process are properly mapped
to a consistent API.
For example, in the case of JDBC, instead of the traditional JDBC approach of calling the
getConnection() method on the DataSource , you instead use Springs
org.springframework.jdbc.datasource.DataSourceUtils class as follows:

25/08/2016 12:10

Spring Framework Reference Documentation

518 de 1194

Connection conn = DataSourceUtils.getConnection(dataSource);

If an existing transaction already has a connection synchronized (linked) to it, that

instance is returned. Otherwise, the method call triggers the creation of a new connection,
which is (optionally) synchronized to any existing transaction, and made available for
subsequent reuse in that same transaction. As mentioned, any SQLException is
wrapped in a Spring Framework CannotGetJdbcConnectionException , one of the
Spring Frameworks hierarchy of unchecked DataAccessExceptions. This approach gives
you more information than can be obtained easily from the SQLException , and ensures
portability across databases, even across different persistence technologies.
This approach also works without Spring transaction management (transaction
synchronization is optional), so you can use it whether or not you are using Spring for
transaction management.
Of course, once you have used Springs JDBC support, JPA support or Hibernate
support, you will generally prefer not to use DataSourceUtils or the other helper
classes, because you will be much happier working through the Spring abstraction than
directly with the relevant APIs. For example, if you use the Spring JdbcTemplate or
jdbc.object package to simplify your use of JDBC, correct connection retrieval occurs
behind the scenes and you wont need to write any special code.

17.4.3 TransactionAwareDataSourceProxy
At the very lowest level exists the TransactionAwareDataSourceProxy class. This is a
proxy for a target DataSource , which wraps the target DataSource to add awareness
of Spring-managed transactions. In this respect, it is similar to a transactional JNDI
DataSource as provided by a Java EE server.
It should almost never be necessary or desirable to use this class, except when existing
code must be called and passed a standard JDBC DataSource interface
implementation. In that case, it is possible that this code is usable, but participating in
Spring managed transactions. It is preferable to write your new code by using the higher
level abstractions mentioned above.

17.5 Declarative transaction management

Most Spring Framework users choose declarative transaction management.
This option has the least impact on application code, and hence is most

25/08/2016 12:10

Spring Framework Reference Documentation

519 de 1194

consistent with the ideals of a non-invasive lightweight container.

The Spring Frameworks declarative transaction management is made possible with

Spring aspect-oriented programming (AOP), although, as the transactional aspects code
comes with the Spring Framework distribution and may be used in a boilerplate fashion,
AOP concepts do not generally have to be understood to make effective use of this code.
The Spring Frameworks declarative transaction management is similar to EJB CMT in
that you can specify transaction behavior (or lack of it) down to individual method level. It
is possible to make a setRollbackOnly() call within a transaction context if necessary.
The differences between the two types of transaction management are:
Unlike EJB CMT, which is tied to JTA, the Spring Frameworks declarative transaction
management works in any environment. It can work with JTA transactions or local
transactions using JDBC, JPA, Hibernate or JDO by simply adjusting the
configuration files.
You can apply the Spring Framework declarative transaction management to any
class, not merely special classes such as EJBs.
The Spring Framework offers declarative rollback rules,a feature with no EJB
equivalent. Both programmatic and declarative support for rollback rules is provided.
The Spring Framework enables you to customize transactional behavior, by using
AOP. For example, you can insert custom behavior in the case of transaction
rollback. You can also add arbitrary advice, along with the transactional advice. With
EJB CMT, you cannot influence the containers transaction management except with
setRollbackOnly() .
The Spring Framework does not support propagation of transaction contexts across
remote calls, as do high-end application servers. If you need this feature, we
recommend that you use EJB. However, consider carefully before using such a
feature, because normally, one does not want transactions to span remote calls.

Where is TransactionProxyFactoryBean?
Declarative transaction configuration in versions of Spring 2.0 and above differs
considerably from previous versions of Spring. The main difference is that there is
no longer any need to configure TransactionProxyFactoryBean beans.
The pre-Spring 2.0 configuration style is still 100% valid configuration; think of the
new <tx:tags/> as simply defining TransactionProxyFactoryBean beans on
your behalf.
The concept of rollback rules is important: they enable you to specify which exceptions

25/08/2016 12:10

Spring Framework Reference Documentation

520 de 1194

(and throwables) should cause automatic rollback. You specify this declaratively, in
configuration, not in Java code. So, although you can still call setRollbackOnly() on
the TransactionStatus object to roll back the current transaction back, most often you
can specify a rule that MyApplicationException must always result in rollback. The
significant advantage to this option is that business objects do not depend on the
transaction infrastructure. For example, they typically do not need to import Spring
transaction APIs or other Spring APIs.
Although EJB container default behavior automatically rolls back the transaction on a
system exception (usually a runtime exception), EJB CMT does not roll back the
transaction automatically on anapplication exception (that is, a checked exception other
than java.rmi.RemoteException ). While the Spring default behavior for declarative
transaction management follows EJB convention (roll back is automatic only on
unchecked exceptions), it is often useful to customize this behavior.

17.5.1 Understanding the Spring Frameworks declarative

transaction implementation
It is not sufficient to tell you simply to annotate your classes with the @Transactional
annotation, add @EnableTransactionManagement to your configuration, and then
expect you to understand how it all works. This section explains the inner workings of the
Spring Frameworks declarative transaction infrastructure in the event of transactionrelated issues.
The most important concepts to grasp with regard to the Spring Frameworks declarative
transaction support are that this support is enabled via AOP proxies, and that the
transactional advice is driven by metadata (currently XML- or annotation-based). The
combination of AOP with transactional metadata yields an AOP proxy that uses a
TransactionInterceptor in conjunction with an appropriate
PlatformTransactionManager implementation to drive transactions around method
invocations.

Spring AOP is covered in Chapter 11, Aspect Oriented Programming with

Spring.

Conceptually, calling a method on a transactional proxy looks like this

25/08/2016 12:10

Spring Framework Reference Documentation

521 de 1194

17.5.2 Example of declarative transaction implementation

Consider the following interface, and its attendant implementation. This example uses
Foo and Bar classes as placeholders so that you can concentrate on the transaction
usage without focusing on a particular domain model. For the purposes of this example,
the fact that the DefaultFooService class throws UnsupportedOperationException
instances in the body of each implemented method is good; it allows you to see
transactions created and then rolled back in response to the
UnsupportedOperationException instance.
// the service interface that we want to make transactional
package x.y.service;
public interface FooService {
Foo getFoo(String fooName);
Foo getFoo(String fooName, String barName);
void insertFoo(Foo foo);
void updateFoo(Foo foo);
}
// an implementation of the above interface

25/08/2016 12:10

Spring Framework Reference Documentation

522 de 1194

package x.y.service;
public class DefaultFooService implements FooService {
public Foo getFoo(String fooName) {
throw new UnsupportedOperationException();
}
public Foo getFoo(String fooName, String barName) {
throw new UnsupportedOperationException();
}
public void insertFoo(Foo foo) {
throw new UnsupportedOperationException();
}
public void updateFoo(Foo foo) {
throw new UnsupportedOperationException();
}
}

Assume that the first two methods of the FooService interface, getFoo(String) and
getFoo(String, String) , must execute in the context of a transaction with read-only
semantics, and that the other methods, insertFoo(Foo) and updateFoo(Foo) , must
execute in the context of a transaction with read-write semantics. The following
configuration is explained in detail in the next few paragraphs.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:aop="http://www.springframework.org/schema/aop"
xmlns:tx="http://www.springframework.org/schema/tx"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop.xsd">

<bean id="fooService" class="x.y.service.DefaultFooService"/>
<!-- the transactional advice (what 'happens'; see the <aop:advisor/> bean below)

25/08/2016 12:10

Spring Framework Reference Documentation

523 de 1194

<tx:advice id="txAdvice" transaction-manager="txManager">

<tx:attributes>
<!-- all methods starting with