0% found this document useful (0 votes)

3K views616 pages

Spring Documentation

Spring

Uploaded by

Naveen Yellapu

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 views616 pages

Spring Documentation

Spring

Uploaded by

Naveen Yellapu

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/ 616

2/20/2017 Spring Framework Reference Documentation

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

5.0.0.M4

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
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. Core Technologies

3. The IoC container
3.1. Introduction to the Spring IoC container and beans
3.2. Container overview
3.2.1. Conguration metadata
3.2.2. Instantiating a container
Composing XML-based conguration metadata
3.2.3. Using the container

3.3. Bean overview

3.3.1. Naming beans
Aliasing a bean outside the bean denition
3.3.2. Instantiating beans
Instantiation with a constructor
Instantiation with a static factory method
Instantiation using an instance factory method

3.4. Dependencies
3.4.1. Dependency Injection
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 1/616
2/20/2017 Spring Framework Reference Documentation
Constructor-based dependency injection
Setter-based dependency injection
Dependency resolution process
Examples of dependency injection
3.4.2. Dependencies and conguration 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
3.4.3. Using depends-on
3.4.4. Lazy-initialized beans
3.4.5. Autowiring collaborators
Limitations and disadvantages of autowiring
Excluding a bean from autowiring
3.4.6. Method injection
Lookup method injection
Arbitrary method replacement

3.5. Bean scopes

3.5.1. The singleton scope
3.5.2. The prototype scope
3.5.3. Singleton beans with prototype-bean dependencies
3.5.4. Request, session, application, and WebSocket scopes
Initial web conguration
Request scope
Session scope
Application scope
Scoped beans as dependencies
3.5.5. Custom scopes
Creating a custom scope
Using a custom scope

3.6. Customizing the nature of a bean

3.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
3.6.2. ApplicationContextAware and BeanNameAware
3.6.3. Other Aware interfaces

3.7. Bean denition inheritance

3.8. Container Extension Points
3.8.1. Customizing beans using a BeanPostProcessor
Example: Hello World, BeanPostProcessor-style
Example: The RequiredAnnotationBeanPostProcessor
3.8.2. Customizing conguration metadata with a BeanFactoryPostProcessor
Example: the Class name substitution PropertyPlaceholderCongurer
Example: the PropertyOverrideCongurer
3.8.3. Customizing instantiation logic with a FactoryBean

3.9. Annotation-based container conguration

3.9.1. @Required
3.9.2. @Autowired
3.9.3. Fine-tuning annotation-based autowiring with @Primary
3.9.4. Fine-tuning annotation-based autowiring with qualiers
3.9.5. Using generics as autowiring qualiers
3.9.6. CustomAutowireCongurer
3.9.7. @Resource
3.9.8. @PostConstruct and @PreDestroy

3.10. Classpath scanning and managed components

3.10.1. @Component and further stereotype annotations
3.10.2. Meta-annotations
3.10.3. Automatically detecting classes and registering bean denitions
3.10.4. Using lters to customize scanning
3.10.5. Dening bean metadata within components
3.10.6. Naming autodetected components
3.10.7. Providing a scope for autodetected components
3.10.8. Providing qualier metadata with annotations

3.11. Using JSR 330 Standard Annotations

3.11.1. Dependency Injection with @Inject and @Named

3.12. Java-based container conguration

3.12.1. Basic concepts: @Bean and @Conguration
3.12.2. Instantiating the Spring container using AnnotationCongApplicationContext
Simple construction
Building the container programmatically using register(Class<?>)
Enabling component scanning with scan(String)
Support for web applications with AnnotationCongWebApplicationContext
3.12.3. Using the @Bean annotation
Declaring a bean
Bean dependencies
Receiving lifecycle callbacks
Specifying bean scope
Customizing bean naming
Bean aliasing
Bean description
3.12.4. Using the @Conguration annotation
Injecting inter-bean dependencies
Lookup method injection
Further information about how Java-based conguration works internally
3.12.5. Composing Java-based congurations
Using the @Import annotation
Conditionally include @Conguration classes or @Bean methods
Combining Java and XML conguration

3.13. Environment abstraction

3.13.1. Bean denition proles
@Prole
3.13.2. XML bean denition proles
Activating a prole
Default prole
3.13.3. PropertySource abstraction
3.13.4. @PropertySource
3.13.5. Placeholder resolution in statements

3.14. Registering a LoadTimeWeaver

3.15. Additional Capabilities of the ApplicationContext
3.15.1. Internationalization using MessageSource
3.15.2. Standard and Custom Events
Annotation-based Event Listeners
Asynchronous Listeners
Ordering Listeners
Generic Events
3.15.3. Convenient access to low-level resources
3.15.4. Convenient ApplicationContext instantiation for web applications
3.15.5. Deploying a Spring ApplicationContext as a Java EE RAR le

3.16. The BeanFactory

3.16.1. BeanFactory or ApplicationContext?
3.16.2. Glue code and the evil singleton

4. Resources
4.1. Introduction
4.2. The Resource interface
4.3. Built-in Resource implementations
4.3.1. UrlResource
4.3.2. ClassPathResource
4.3.3. FileSystemResource
4.3.4. ServletContextResource
4.3.5. InputStreamResource
4.3.6. ByteArrayResource

4.4. The ResourceLoader

4.5. The ResourceLoaderAware interface
4.6. Resources as dependencies
4.7. Application contexts and Resource paths
4.7.1. Constructing application contexts
Constructing ClassPathXmlApplicationContext instances - shortcuts
4.7.2. Wildcards in application context constructor resource paths
Ant-style Patterns
The Classpath*: portability classpath*: prex
Other notes relating to wildcards

5. Validation, Data Binding, and Type Conversion

5.1. Introduction
5.2. Validation using Springs Validator interface
5.3. Resolving codes to error messages
5.4. Bean manipulation and the BeanWrapper
5.4.1. Setting and getting basic and nested properties
5.4.2. Built-in PropertyEditor implementations
Registering additional custom PropertyEditors

5.5. Spring Type Conversion

5.5.1. Converter SPI
5.5.2. ConverterFactory
5.5.3. GenericConverter
ConditionalGenericConverter
5.5.4. ConversionService API
5.5.5. Conguring a ConversionService
5.5.6. Using a ConversionService programmatically

5.6. Spring Field Formatting

5.6.1. Formatter SPI
5.6.2. Annotation-driven Formatting
Format Annotation API
5.6.3. FormatterRegistry SPI
5.6.4. FormatterRegistrar SPI
5.6.5. Conguring Formatting in Spring MVC

5.7. Conguring a global date & time format

5.8. Spring Validation
5.8.1. Overview of the JSR-303 Bean Validation API
5.8.2. Conguring a Bean Validation Provider
Injecting a Validator
Conguring Custom Constraints
Spring-driven Method Validation
Additional Conguration Options
5.8.3. Conguring a DataBinder
5.8.4. Spring MVC 3 Validation

6. Spring Expression Language (SpEL)

6.1. Introduction
6.2. Feature Overview
6.3. Expression Evaluation using Springs Expression Interface
6.3.1. The EvaluationContext interface
Type Conversion
6.3.2. Parser conguration
6.3.3. SpEL compilation
Compiler conguration
Compiler limitations

6.4. Expression support for dening bean denitions

6.4.1. XML based conguration
6.4.2. Annotation-based conguration

6.5. Language Reference

6.5.1. Literal expressions
6.5.2. Properties, Arrays, Lists, Maps, Indexers
6.5.3. Inline lists
6.5.4. Inline Maps
6.5.5. Array construction
6.5.6. Methods
6.5.7. Operators
Relational operators
Logical operators
Mathematical operators
6.5.8. Assignment
6.5.9. Types
6.5.10. Constructors
6.5.11. Variables
The #this and #root variables
6.5.12. Functions
6.5.13. Bean references
6.5.14. Ternary Operator (If-Then-Else)

6.6. Classes used in the examples

7. Aspect Oriented Programming with Spring

7.1. Introduction
7.1.1. AOP concepts
7.1.2. Spring AOP capabilities and goals
7.1.3. AOP Proxies

7.2. @AspectJ support

7.2.1. Enabling @AspectJ Support
Enabling @AspectJ Support with Java conguration
Enabling @AspectJ Support with XML conguration
7.2.2. Declaring an aspect
7.2.3. Declaring a pointcut
Supported Pointcut Designators
Combining pointcut expressions
Sharing common pointcut denitions
Examples
Writing good pointcuts
7.2.4. Declaring advice
Before advice
After returning advice
After throwing advice
After (nally) advice
Around advice
Advice parameters
Advice ordering
7.2.5. Introductions
7.2.6. Aspect instantiation models
7.2.7. Example

7.3. Schema-based AOP support

7.3.1. Declaring an aspect
7.3.2. Declaring a pointcut
7.3.3. Declaring advice
Before advice
After returning advice
After throwing advice
After (nally) advice
Around advice
Advice parameters
Advice ordering
7.3.4. Introductions
7.3.5. Aspect instantiation models
7.3.6. Advisors
7.3.7. Example

7.4. Choosing which AOP declaration style to use

7.4.1. Spring AOP or full AspectJ?
7.4.2. @AspectJ or XML for Spring AOP?

7.5. Mixing aspect types

7.6. Proxying mechanisms
7.6.1. Understanding AOP proxies

7.7. Programmatic creation of @AspectJ Proxies

7.8. Using AspectJ with Spring applications
7.8.1. Using AspectJ to dependency inject domain objects with Spring
Unit testing @Congurable objects
Working with multiple application contexts
7.8.2. Other Spring aspects for AspectJ
7.8.3. Conguring AspectJ aspects using Spring IoC
7.8.4. Load-time weaving with AspectJ in the Spring Framework
A rst example
Aspects
'META-INF/aop.xml'
Required libraries (JARS)
Spring conguration
Environment-specic conguration

7.9. Further Resources

8. Spring AOP APIs

8.1. Introduction
8.2. Pointcut API in Spring
8.2.1. Concepts
8.2.2. Operations on pointcuts
8.2.3. AspectJ expression pointcuts
8.2.4. Convenience pointcut implementations
Static pointcuts
Dynamic pointcuts
8.2.5. Pointcut superclasses
8.2.6. Custom pointcuts

8.3. Advice API in Spring

8.3.1. Advice lifecycles
8.3.2. Advice types in Spring
Interception around advice
Before advice
Throws advice
After Returning advice
Introduction advice

8.4. Advisor API in Spring

8.5. Using the ProxyFactoryBean to create AOP proxies
8.5.1. Basics
8.5.2. JavaBean properties
8.5.3. JDK- and CGLIB-based proxies
8.5.4. Proxying interfaces
8.5.5. Proxying classes
8.5.6. Using 'global' advisors

8.6. Concise proxy denitions

8.7. Creating AOP proxies programmatically with the ProxyFactory
8.8. Manipulating advised objects
8.9. Using the "auto-proxy" facility
8.9.1. Autoproxy bean denitions
BeanNameAutoProxyCreator
DefaultAdvisorAutoProxyCreator
AbstractAdvisorAutoProxyCreator
8.9.2. Using metadata-driven auto-proxying

8.10. Using TargetSources

8.10.1. Hot swappable target sources
8.10.2. Pooling target sources
8.10.3. Prototype target sources
8.10.4. ThreadLocal target sources

8.11. Dening new Advice types

8.12. Further resources

III. Testing
9. Introduction to Spring Testing
10. Unit Testing
10.1. Mock Objects
10.1.1. Environment
10.1.2. JNDI
10.1.3. Servlet API

10.2. Unit Testing support Classes

10.2.1. General testing utilities
10.2.2. Spring MVC

11. Integration Testing

11.1. Overview
11.2. Goals of Integration Testing
11.2.1. Context management and caching
11.2.2. Dependency Injection of test xtures
11.2.3. Transaction management
11.2.4. Support classes for integration testing
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 6/616
2/20/2017 Spring Framework Reference Documentation
11.3. JDBC Testing Support
11.4. Annotations
11.4.1. Spring Testing Annotations
@BootstrapWith
@ContextConguration
@WebAppConguration
@ContextHierarchy
@ActiveProles
@TestPropertySource
@DirtiesContext
@TestExecutionListeners
@Commit
@Rollback
@BeforeTransaction
@AfterTransaction
@Sql
@SqlCong
@SqlGroup
11.4.2. Standard Annotation Support
11.4.3. Spring JUnit 4 Testing Annotations
@IfProleValue
@ProleValueSourceConguration
@Timed
@Repeat
11.4.4. Meta-Annotation Support for Testing

11.5. Spring TestContext Framework

11.5.1. Key abstractions
TestContext
TestContextManager
TestExecutionListener
Context Loaders
11.5.2. Bootstrapping the TestContext framework
11.5.3. TestExecutionListener conguration
Registering custom TestExecutionListeners
Automatic discovery of default TestExecutionListeners
Ordering TestExecutionListeners
Merging TestExecutionListeners
11.5.4. Context management
Context conguration with XML resources
Context conguration with Groovy scripts
Context conguration with annotated classes
Mixing XML, Groovy scripts, and annotated classes
Context conguration with context initializers
Context conguration inheritance
Context conguration with environment proles
Context conguration with test property sources
Loading a WebApplicationContext
Context caching
Context hierarchies
11.5.5. Dependency injection of test xtures
11.5.6. Testing request and session scoped beans
11.5.7. Transaction management
Test-managed transactions
Enabling and disabling transactions
Transaction rollback and commit behavior
Programmatic transaction management
Executing code outside of a transaction
Conguring a transaction manager
Demonstration of all transaction-related annotations
11.5.8. Executing SQL scripts
Executing SQL scripts programmatically
Executing SQL scripts declaratively with @Sql
11.5.9. Parallel test execution
11.5.10. TestContext Framework support classes
Spring JUnit 4 Runner
Spring JUnit 4 Rules
JUnit 4 support classes
TestNG support classes

11.6. Spring MVC Test Framework

11.6.1. Server-Side Tests
Static Imports
Setup Options
Performing Requests
Dening Expectations
Filter Registrations
Differences between Out-of-Container and End-to-End Integration Tests
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 7/616
2/20/2017 Spring Framework Reference Documentation
Further Server-Side Test Examples
11.6.2. HtmlUnit Integration
Why HtmlUnit Integration?
MockMvc and HtmlUnit
MockMvc and WebDriver
MockMvc and Geb
11.6.3. Client-Side REST Tests
Static Imports
Further Examples of Client-side REST Tests

11.7. PetClinic Example

12. Further Resources

IV. Data Access

13. Transaction Management
13.1. Introduction to Spring Framework transaction management
13.2. Advantages of the Spring Frameworks transaction support model
13.2.1. Global transactions
13.2.2. Local transactions
13.2.3. Spring Frameworks consistent programming model

13.3. Understanding the Spring Framework transaction abstraction

13.4. Synchronizing resources with transactions
13.4.1. High-level synchronization approach
13.4.2. Low-level synchronization approach
13.4.3. TransactionAwareDataSourceProxy

13.5. Declarative transaction management

13.5.1. Understanding the Spring Frameworks declarative transaction implementation
13.5.2. Example of declarative transaction implementation
13.5.3. Rolling back a declarative transaction
13.5.4. Conguring different transactional semantics for different beans
13.5.5. <tx:advice/> settings
13.5.6. Using @Transactional
@Transactional settings
Multiple Transaction Managers with @Transactional
Custom shortcut annotations
13.5.7. Transaction propagation
Required
RequiresNew
Nested
13.5.8. Advising transactional operations
13.5.9. Using @Transactional with AspectJ

13.6. Programmatic transaction management

13.6.1. Using the TransactionTemplate
Specifying transaction settings
13.6.2. Using the PlatformTransactionManager

13.7. Choosing between programmatic and declarative transaction management

13.8. Transaction bound event
13.9. Application server-specic integration
13.9.1. IBM WebSphere
13.9.2. Oracle WebLogic Server

13.10. Solutions to common problems

13.10.1. Use of the wrong transaction manager for a specic DataSource

13.11. Further Resources

14. DAO support

14.1. Introduction
14.2. Consistent exception hierarchy
14.3. Annotations used for conguring DAO or Repository classes

15. Data access with JDBC

15.1. Introduction to Spring Framework JDBC
15.1.1. Choosing an approach for JDBC database access
15.1.2. Package hierarchy
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 8/616
2/20/2017 Spring Framework Reference Documentation
15.2. Using the JDBC core classes to control basic JDBC processing and error handling
15.2.1. JdbcTemplate
Examples of JdbcTemplate class usage
JdbcTemplate best practices
15.2.2. NamedParameterJdbcTemplate
15.2.3. SQLExceptionTranslator
15.2.4. Executing statements
15.2.5. Running queries
15.2.6. Updating the database
15.2.7. Retrieving auto-generated keys

15.3. Controlling database connections

15.3.1. DataSource
15.3.2. DataSourceUtils
15.3.3. SmartDataSource
15.3.4. AbstractDataSource
15.3.5. SingleConnectionDataSource
15.3.6. DriverManagerDataSource
15.3.7. TransactionAwareDataSourceProxy
15.3.8. DataSourceTransactionManager
15.3.9. NativeJdbcExtractor

15.4. JDBC batch operations

15.4.1. Basic batch operations with the JdbcTemplate
15.4.2. Batch operations with a List of objects
15.4.3. Batch operations with multiple batches

15.5. Simplifying JDBC operations with the SimpleJdbc classes

15.5.1. Inserting data using SimpleJdbcInsert
15.5.2. Retrieving auto-generated keys using SimpleJdbcInsert
15.5.3. Specifying columns for a SimpleJdbcInsert
15.5.4. Using SqlParameterSource to provide parameter values
15.5.5. Calling a stored procedure with SimpleJdbcCall
15.5.6. Explicitly declaring parameters to use for a SimpleJdbcCall
15.5.7. How to dene SqlParameters
15.5.8. Calling a stored function using SimpleJdbcCall
15.5.9. Returning ResultSet/REF Cursor from a SimpleJdbcCall

15.6. Modeling JDBC operations as Java objects

15.6.1. SqlQuery
15.6.2. MappingSqlQuery
15.6.3. SqlUpdate
15.6.4. StoredProcedure

15.7. Common problems with parameter and data value handling

15.7.1. Providing SQL type information for parameters
15.7.2. Handling BLOB and CLOB objects
15.7.3. Passing in lists of values for IN clause
15.7.4. Handling complex types for stored procedure calls

15.8. Embedded database support

15.8.1. Why use an embedded database?
15.8.2. Creating an embedded database using Spring XML
15.8.3. Creating an embedded database programmatically
15.8.4. Selecting the embedded database type
Using HSQL
Using H2
Using Derby
15.8.5. Testing data access logic with an embedded database
15.8.6. Generating unique names for embedded databases
15.8.7. Extending the embedded database support

15.9. Initializing a DataSource

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

16. Object Relational Mapping (ORM) Data Access

16.1. Introduction to ORM with Spring
16.2. General ORM integration considerations
16.2.1. Resource and transaction management
16.2.2. Exception translation

16.3. Hibernate
16.3.1. SessionFactory setup in a Spring container
16.3.2. Implementing DAOs based on plain Hibernate API
16.3.3. Declarative transaction demarcation
16.3.4. Programmatic transaction demarcation
16.3.5. Transaction management strategies

16.4. JPA
16.4.1. Three options for JPA setup in a Spring environment
LocalEntityManagerFactoryBean
Obtaining an EntityManagerFactory from JNDI
LocalContainerEntityManagerFactoryBean
Dealing with multiple persistence units
16.4.2. Implementing DAOs based on JPA: EntityManagerFactory and EntityManager
16.4.3. Spring-driven JPA transactions
16.4.4. JpaDialect and JpaVendorAdapter
16.4.5. Setting up JPA with JTA transaction management

17. Marshalling XML using O/X Mappers

17.1. Introduction
17.1.1. Ease of conguration
17.1.2. Consistent Interfaces
17.1.3. Consistent Exception Hierarchy

17.2. Marshaller and Unmarshaller

17.2.1. Marshaller
17.2.2. Unmarshaller
17.2.3. XmlMappingException

17.3. Using Marshaller and Unmarshaller

17.4. XML Schema-based Conguration
17.5. JAXB
17.5.1. Jaxb2Marshaller
XML Schema-based Conguration

17.6. Castor
17.6.1. CastorMarshaller
17.6.2. Mapping
XML Schema-based Conguration

17.7. JiBX
17.7.1. JibxMarshaller
XML Schema-based Conguration

17.8. XStream
17.8.1. XStreamMarshaller

V. The Web
18. Web MVC framework
18.1. Introduction to Spring Web MVC framework
18.1.1. Features of Spring Web MVC
18.1.2. Pluggability of other MVC implementations

18.2. The DispatcherServlet

18.2.1. Special Bean Types In the WebApplicationContext
18.2.2. Default DispatcherServlet Conguration
18.2.3. DispatcherServlet Processing Sequence

18.3. Implementing Controllers

18.3.1. Dening a controller with @Controller
18.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
Sufx Pattern Matching
Sufx Pattern Matching and RFD
Matrix Variables
Consumable Media Types
Producible Media Types
Request Parameters and Header Values
HTTP HEAD and HTTP OPTIONS
18.3.3. Dening @RequestMapping handler methods
Supported method argument types

http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 10/616
2/20/2017 Spring Framework Reference Documentation
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
Jackson Serialization View Support
Jackson JSONP Support
18.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
Conguring Asynchronous Request Processing
18.3.5. Testing Controllers

18.4. Handler mappings

18.4.1. Intercepting requests with a HandlerInterceptor

18.5. Resolving views

18.5.1. Resolving views with the ViewResolver interface
18.5.2. Chaining ViewResolvers
18.5.3. Redirecting to Views
RedirectView
The redirect: prex
The forward: prex
18.5.4. ContentNegotiatingViewResolver

18.6. Using ash attributes

18.7. Building URIs
18.7.1. Building URIs to Controllers and methods
18.7.2. Building URIs to Controllers and methods from views

18.8. Using locales

18.8.1. Obtaining Time Zone Information
18.8.2. AcceptHeaderLocaleResolver
18.8.3. CookieLocaleResolver
18.8.4. SessionLocaleResolver
18.8.5. LocaleChangeInterceptor

18.9. Using themes

18.9.1. Overview of themes
18.9.2. Dening themes
18.9.3. Theme resolvers

18.10. Springs multipart (le upload) support

18.10.1. Introduction
18.10.2. Using a MultipartResolver with Commons FileUpload
18.10.3. Using a MultipartResolver with Servlet 3.0
18.10.4. Handling a le upload in a form
18.10.5. Handling a le upload request from programmatic clients

18.11. Handling exceptions

18.11.1. HandlerExceptionResolver
18.11.2. @ExceptionHandler
18.11.3. Handling Standard Spring MVC Exceptions
18.11.4. REST Controller Exception Handling
18.11.5. Annotating Business Exceptions With @ResponseStatus
18.11.6. Customizing the Default Servlet Container Error Page

18.12. Web Security

18.13. Convention over conguration support
18.13.1. The Controller ControllerClassNameHandlerMapping
18.13.2. The Model ModelMap (ModelAndView)
18.13.3. The View - RequestToViewNameTranslator

18.14. HTTP caching support

18.15. Code-based Servlet container initialization

18.16. Conguring Spring MVC
18.16.1. Enabling the MVC Java Cong or the MVC XML Namespace
18.16.2. Customizing the Provided Conguration
18.16.3. Conversion and Formatting
18.16.4. Validation
18.16.5. Interceptors
18.16.6. Content Negotiation
18.16.7. View Controllers
18.16.8. View Resolvers
18.16.9. Serving of Resources
18.16.10. Falling Back On the "Default" Servlet To Serve Resources
18.16.11. Path Matching
18.16.12. Message Converters
18.16.13. Advanced Customizations with MVC Java Cong
18.16.14. Advanced Customizations with the MVC Namespace

19. View technologies

19.1. Introduction
19.2. Thymeleaf
19.3. Groovy Markup Templates
19.3.1. Conguration
19.3.2. Example

19.4. FreeMarker
19.4.1. Dependencies
19.4.2. Context conguration
19.4.3. Creating templates
19.4.4. Advanced FreeMarker conguration
19.4.5. Bind support and form handling
The bind macros
Simple binding
Form input generation macros
HTML escaping and XHTML compliance

19.5. JSP & JSTL

19.5.1. View resolvers
19.5.2. 'Plain-old' JSPs versus JSTL
19.5.3. Additional tags facilitating development
19.5.4. Using Springs form tag library
Conguration
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

19.6. Script templates

19.6.1. Dependencies
19.6.2. How to integrate script based templating

19.7. XML Marshalling View

19.8. Tiles
19.8.1. Dependencies
19.8.2. How to integrate Tiles
UrlBasedViewResolver
ResourceBundleViewResolver
SimpleSpringPreparerFactory and SpringBeanPreparerFactory

19.9. XSLT
19.9.1. My First Words

19.10. Document views (PDF/Excel)

19.10.1. Introduction
19.10.2. Conguration and setup
Document view denitions
Controller code
Subclassing for Excel views
Subclassing for PDF views

19.11. Feed Views

19.12. JSON Mapping View
19.13. XML Mapping View

20. CORS Support

20.1. Introduction
20.2. Controller method CORS conguration
20.3. Global CORS conguration
20.3.1. JavaCong
20.3.2. XML namespace

20.4. Advanced Customization

20.5. Filter based CORS support

21. Integrating with other web frameworks

21.1. Introduction
21.2. Common conguration
21.3. JavaServer Faces 1.2
21.3.1. SpringBeanFacesELResolver (JSF 1.2+)
21.3.2. FacesContextUtils

21.4. Apache Struts 2.x

21.5. Tapestry 5.x
21.6. Further Resources

22. WebSocket Support

22.1. Introduction
22.1.1. WebSocket Fallback Options
22.1.2. A Messaging Architecture
22.1.3. Sub-Protocol Support in WebSocket
22.1.4. Should I Use WebSocket?

22.2. WebSocket API

22.2.1. Create and Congure a WebSocketHandler
22.2.2. Customizing the WebSocket Handshake
22.2.3. WebSocketHandler Decoration
22.2.4. Deployment Considerations
22.2.5. Conguring the WebSocket Engine
22.2.6. Conguring allowed origins

22.3. SockJS Fallback Options

22.3.1. Overview of SockJS
22.3.2. Enable SockJS
22.3.3. HTTP Streaming in IE 8, 9: Ajax/XHR vs IFrame
22.3.4. Heartbeat Messages
22.3.5. Servlet 3 Async Requests
22.3.6. CORS Headers for SockJS
22.3.7. SockJS Client

22.4. STOMP Over WebSocket Messaging Architecture

22.4.1. Overview of STOMP
22.4.2. Enable STOMP over WebSocket
22.4.3. Flow of Messages
22.4.4. Annotation Message Handling
22.4.5. Sending Messages
22.4.6. Simple Broker
22.4.7. Full-Featured Broker
22.4.8. Connections To Full-Featured Broker
22.4.9. Using Dot as Separator in @MessageMapping Destinations
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 13/616
2/20/2017 Spring Framework Reference Documentation
22.4.10. Authentication
22.4.11. Token-based Authentication
22.4.12. User Destinations
22.4.13. Listening To ApplicationContext Events and Intercepting Messages
22.4.14. STOMP Client
22.4.15. WebSocket Scope
22.4.16. Conguration and Performance
22.4.17. Runtime Monitoring
22.4.18. Testing Annotated Controller Methods

23. Reactive Web Applications

23.1. Introduction
23.1.1. What is Reactive Programming?
23.1.2. Reactive API and Building Blocks

23.2. Spring Web Reactive Module

23.2.1. Server Side
Annotation-based Programming Model
Functional Programming Model
23.2.2. Client Side
23.2.3. Request and Response Body Conversion
23.2.4. Reactive WebSocket Support

23.3. Getting Started

23.3.1. Spring Boot Starter
23.3.2. Manual Bootstrapping
23.3.3. Examples

VI. Integration
24. Remoting and web services using Spring
24.1. Introduction
24.2. Exposing services using RMI
24.2.1. Exporting the service using the RmiServiceExporter
24.2.2. Linking in the service at the client

24.3. Using Hessian to remotely call services via HTTP

24.3.1. Wiring up the DispatcherServlet for Hessian and co.
24.3.2. Exposing your beans by using the HessianServiceExporter
24.3.3. Linking in the service on the client
24.3.4. Applying HTTP basic authentication to a service exposed through Hessian

24.4. Exposing services using HTTP invokers

24.4.1. Exposing the service object
24.4.2. Linking in the service at the client

24.5. Web services

24.5.1. Exposing servlet-based web services using JAX-WS
24.5.2. Exporting standalone web services using JAX-WS
24.5.3. Exporting web services using the JAX-WS RIs Spring support
24.5.4. Accessing web services using JAX-WS

24.6. JMS
24.6.1. Server-side conguration
24.6.2. Client-side conguration

24.7. AMQP
24.8. Auto-detection is not implemented for remote interfaces
24.9. Considerations when choosing a technology
24.10. Accessing RESTful services on the Client
24.10.1. RestTemplate
Working with the URI
Dealing with request and response headers
Jackson JSON Views support
24.10.2. HTTP Message Conversion
StringHttpMessageConverter
FormHttpMessageConverter
ByteArrayHttpMessageConverter
MarshallingHttpMessageConverter
MappingJackson2HttpMessageConverter
MappingJackson2XmlHttpMessageConverter
SourceHttpMessageConverter
BufferedImageHttpMessageConverter
24.10.3. Async RestTemplate
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 14/616
2/20/2017 Spring Framework Reference Documentation

25. Enterprise JavaBeans (EJB) integration

25.1. Introduction
25.2. Accessing EJBs
25.2.1. Concepts
25.2.2. Accessing local SLSBs
25.2.3. Accessing remote SLSBs
25.2.4. Accessing EJB 2.x SLSBs versus EJB 3 SLSBs

25.3. Using Springs EJB implementation support classes

25.3.1. EJB 3 injection interceptor

26. JMS (Java Message Service)

26.1. Introduction
26.2. Using Spring JMS
26.2.1. JmsTemplate
26.2.2. Connections
Caching Messaging Resources
SingleConnectionFactory
CachingConnectionFactory
26.2.3. Destination Management
26.2.4. Message Listener Containers
SimpleMessageListenerContainer
DefaultMessageListenerContainer
26.2.5. Transaction management

26.3. Sending a Message

26.3.1. Using Message Converters
26.3.2. SessionCallback and ProducerCallback

26.4. Receiving a message

26.4.1. Synchronous Reception
26.4.2. Asynchronous Reception - Message-Driven POJOs
26.4.3. the SessionAwareMessageListener interface
26.4.4. the MessageListenerAdapter
26.4.5. Processing messages within transactions

26.5. Support for JCA Message Endpoints

26.6. Annotation-driven listener endpoints
26.6.1. Enable listener endpoint annotations
26.6.2. Programmatic endpoints registration
26.6.3. Annotated endpoint method signature
26.6.4. Response management

26.7. JMS namespace support

27. JMX
27.1. Introduction
27.2. Exporting your beans to JMX
27.2.1. Creating an MBeanServer
27.2.2. Reusing an existing MBeanServer
27.2.3. Lazy-initialized MBeans
27.2.4. Automatic registration of MBeans
27.2.5. Controlling the registration behavior

27.3. Controlling the management interface of your beans

27.3.1. the MBeanInfoAssembler Interface
27.3.2. Using Source-Level Metadata (Java annotations)
27.3.3. Source-Level Metadata Types
27.3.4. the AutodetectCapableMBeanInfoAssembler interface
27.3.5. Dening management interfaces using Java interfaces
27.3.6. Using MethodNameBasedMBeanInfoAssembler

27.4. Controlling the ObjectNames for your beans

27.4.1. Reading ObjectNames from Properties
27.4.2. Using the MetadataNamingStrategy
27.4.3. Conguring annotation based MBean export

27.5. JSR-160 Connectors

27.5.1. Server-side Connectors
27.5.2. Client-side Connectors
27.5.3. JMX over Hessian or SOAP

27.6. Accessing MBeans via Proxies

27.7. Notications
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 15/616
2/20/2017 Spring Framework Reference Documentation
27.7.1. Registering Listeners for Notications
27.7.2. Publishing Notications

27.8. Further Resources

28. JCA CCI

28.1. Introduction
28.2. Conguring CCI
28.2.1. Connector conguration
28.2.2. ConnectionFactory conguration in Spring
28.2.3. Conguring CCI connections
28.2.4. Using a single CCI connection

28.3. Using Springs CCI access support

28.3.1. Record conversion
28.3.2. the CciTemplate
28.3.3. DAO support
28.3.4. Automatic output record generation
28.3.5. Summary
28.3.6. Using a CCI Connection and Interaction directly
28.3.7. Example for CciTemplate usage

28.4. Modeling CCI access as operation objects

28.4.1. MappingRecordOperation
28.4.2. MappingCommAreaOperation
28.4.3. Automatic output record generation
28.4.4. Summary
28.4.5. Example for MappingRecordOperation usage
28.4.6. Example for MappingCommAreaOperation usage

28.5. Transactions

29. Email
29.1. Introduction
29.2. Usage
29.2.1. Basic MailSender and SimpleMailMessage usage
29.2.2. Using the JavaMailSender and the MimeMessagePreparator

29.3. Using the JavaMail MimeMessageHelper

29.3.1. Sending attachments and inline resources
Attachments
Inline resources
29.3.2. Creating email content using a templating library

30. Task Execution and Scheduling

30.1. Introduction
30.2. The Spring TaskExecutor abstraction
30.2.1. TaskExecutor types
30.2.2. Using a TaskExecutor

30.3. The Spring TaskScheduler abstraction

30.3.1. the Trigger interface
30.3.2. Trigger implementations
30.3.3. TaskScheduler implementations

30.4. Annotation Support for Scheduling and Asynchronous Execution

30.4.1. Enable scheduling annotations
30.4.2. The @Scheduled annotation
30.4.3. The @Async annotation
30.4.4. Executor qualication with @Async
30.4.5. Exception management with @Async

30.5. The task namespace

30.5.1. The 'scheduler' element
30.5.2. The 'executor' element
30.5.3. The 'scheduled-tasks' element

30.6. Using the Quartz Scheduler

30.6.1. Using the JobDetailFactoryBean
30.6.2. Using the MethodInvokingJobDetailFactoryBean
30.6.3. Wiring up jobs using triggers and the SchedulerFactoryBean

31. Dynamic language support

31.1. Introduction

31.4. Scenarios
31.4.1. Scripted Spring MVC Controllers
31.4.2. Scripted Validators

31.5. Bits and bobs

31.5.1. AOP - advising scripted beans
31.5.2. Scoping

31.6. Further Resources

32. Cache Abstraction

32.1. Introduction
32.2. Understanding the cache abstraction
32.3. Declarative annotation-based caching
32.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
32.3.2. @CachePut annotation
32.3.3. @CacheEvict annotation
32.3.4. @Caching annotation
32.3.5. @CacheCong annotation
32.3.6. Enable caching annotations
32.3.7. Using custom annotations

32.4. JCache (JSR-107) annotations

32.4.1. Features summary
32.4.2. Enabling JSR-107 support

32.5. Declarative XML-based caching

32.6. Conguring the cache storage
32.6.1. JDK ConcurrentMap-based Cache
32.6.2. Ehcache-based Cache
32.6.3. Caffeine Cache
32.6.4. GemFire-based Cache
32.6.5. JSR-107 Cache
32.6.6. Dealing with caches without a backing store

32.7. Plugging-in different back-end caches

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

VII. Appendices
33. Whats New in the Spring Framework

34. Migrating to Spring Framework 4.x

35. Spring Annotation Programming Model

36. Classic Spring Usage

36.1. Classic ORM usage
36.1.1. Hibernate
The HibernateTemplate
Implementing Spring-based DAOs without callbacks

36.2. JMS Usage

37. Classic Spring AOP Usage

37.1. Pointcut API in Spring
37.1.1. Concepts
37.1.2. Operations on pointcuts
37.1.3. AspectJ expression pointcuts
37.1.4. Convenience pointcut implementations
Static pointcuts
Dynamic pointcuts
37.1.5. Pointcut superclasses
37.1.6. Custom pointcuts

37.2. Advice API in Spring

37.2.1. Advice lifecycles
37.2.2. Advice types in Spring
Interception around advice
Before advice
Throws advice
After Returning advice
Introduction advice

37.3. Advisor API in Spring

37.4. Using the ProxyFactoryBean to create AOP proxies
37.4.1. Basics
37.4.2. JavaBean properties
37.4.3. JDK- and CGLIB-based proxies
37.4.4. Proxying interfaces
37.4.5. Proxying classes
37.4.6. Using 'global' advisors

37.5. Concise proxy denitions

37.6. Creating AOP proxies programmatically with the ProxyFactory
37.7. Manipulating advised objects
37.8. Using the "autoproxy" facility
37.8.1. Autoproxy bean denitions
BeanNameAutoProxyCreator
DefaultAdvisorAutoProxyCreator
AbstractAdvisorAutoProxyCreator
37.8.2. Using metadata-driven auto-proxying

37.9. Using TargetSources

37.9.1. Hot swappable target sources
37.9.2. Pooling target sources
37.9.3. Prototype target sources
37.9.4. ThreadLocal target sources

37.10. Dening new Advice types

37.11. Further resources

38. XML Schema-based conguration

38.1. Introduction
38.2. XML Schema-based conguration
38.2.1. Referencing the schemas
38.2.2. the util schema
<util:constant/>
<util:property-path/>
<util:properties/>
<util:list/>
<util:map/>
<util:set/>
38.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)
<jee:remote-slsb/>
38.2.4. the lang schema

39. Extensible XML authoring

39.1. Introduction
39.2. Authoring the schema
39.3. Coding a NamespaceHandler
39.4. BeanDenitionParser
39.5. Registering the handler and the schema
39.5.1. 'META-INF/spring.handlers'
39.5.2. 'META-INF/spring.schemas'

39.6. Using a custom extension in your Spring XML conguration

39.7. Meatier examples
39.7.1. Nesting custom tags within custom tags
39.7.2. Custom attributes on 'normal' elements

39.8. Further Resources

PartI.Overview of Spring Framework

The Spring Framework is a lightweight solution and a potential one-stop-shop for building your enterprise-ready applications. However, Spring
is modular, allowing you to use only those parts that you need, without having to bring in the rest. You can use the IoC container, with any web
framework on top, but you can also use only the 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 StackOverow (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 conguration, 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

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 benet 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.1Dependency Injection and Inversion of Control

A Java applicationa loose term that runs the gamut from constrained, embedded applications to n-tier, server-side enterprise applications
typically 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

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 codies formalized design patterns as rst-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.

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.2Modules
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.

Figure2.1.Overview of the Spring Framework

The following sections list the available modules for each feature along with their artifact names and the topics they cover. Artifact names
correlate to artifact IDs used in Dependency Management tools.

2.2.1Core Container
The Core Container consists of the springcore , springbeans , springcontext , springcontextsupport , and
springexpression (Spring Expression Language) modules.

The springcore and springbeans 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 conguration and specication of dependencies from your actual program logic.

The Context ( springcontext ) 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. springcontextsupport provides support for integrating common
third-party libraries into a Spring application context, in particular for caching (EhCache, JCache) and scheduling (CommonJ, Quartz).

2.2.2AOP and Instrumentation

The springaop module provides an AOP Alliance-compliant aspect-oriented programming implementation allowing you to dene, for
example, method interceptors and pointcuts to cleanly decouple code that implements functionality that should be separated. Using source-
level metadata functionality, you can also incorporate behavioral information into your code, in a manner similar to that of .NET attributes.

The separate springaspects module provides integration with AspectJ.

The springinstrument module provides class instrumentation support and classloader implementations to be used in certain application
servers. The springinstrumenttomcat module contains Springs instrumentation agent for Tomcat.

2.2.3Messaging
Spring Framework 4 includes a springmessaging 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.4Data Access/Integration
The Data Access/Integration layer consists of the JDBC, ORM, OXM, JMS, and Transaction modules.

The springjdbc module provides a JDBC-abstraction layer that removes the need to do tedious JDBC coding and parsing of database-
vendor specic error codes.

The springtx module supports programmatic and declarative transaction management for classes that implement special interfaces and for
all your POJOs (Plain Old Java Objects).

The springorm module provides integration layers for popular object-relational mapping APIs, including JPA and Hibernate. Using the
springorm module you can use these O/R-mapping frameworks in combination with all of the other features Spring offers, such as the
simple declarative transaction management feature mentioned previously.

The springoxm module provides an abstraction layer that supports Object/XML mapping implementations such as JAXB, Castor, JiBX and
XStream.

The springjms module (Java Messaging Service) contains features for producing and consuming messages. Since Spring Framework 4.1, it
provides integration with the springmessaging module.

2.2.5Web
The Web layer consists of the springweb , springwebmvc and springwebsocket modules.

The springweb module provides basic web-oriented integration features such as multipart le 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 springwebmvc 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.

2.2.6Test
The springtest 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.3Usage scenarios

Figure2.2.Typical full-edged Spring web application

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 and Hibernate; for example, when using Hibernate, you can
continue to use your existing mapping les and standard Hibernate SessionFactory conguration. 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.

Figure2.3.Spring middle-tier using a third-party web framework

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-or-nothing 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.
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 23/616
2/20/2017 Spring Framework Reference Documentation
Figure2.4.Remoting usage scenario

When you need to access existing code through web services, you can use Springs Hessian , Rmi or HttpInvokerProxyFactoryBean
classes. Enabling remote access to existing applications is not difcult.

Figure2.5.EJBs - Wrapping existing POJOs

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.1Dependency 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 les) 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 le 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 commonsdbcp which depends on commonspool ).
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 spring*.jar, where * represents the short name for the module (e.g. springcore , springwebmvc , springjms , etc.).
The actual jar le name that you use is normally the module name concatenated with the version number (e.g. spring-core-5.0.0.M4.jar).

Maven Central, which is the default repository that Maven queries, and does not require any special conguration 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 specically for Spring. In addition to the nal GA releases, this repository also hosts development
snapshots and milestones. The jar le 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 le that contains all
Spring jars bundled together for easy download.

So the rst 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 nd bellow the list of Spring artifacts. For a more complete description of each modules, see Section2.2, Modules.

Table2.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-context-support Support classes for integrating common third-party libraries into a Spring application
context

org.springframework spring-core Core utilities, used by many other Spring modules

org.springframework spring-expression Spring Expression Language (SpEL)

org.springframework spring-instrument Instrumentation agent for JVM bootstrapping

org.springframework spring-instrument- Instrumentation agent for Tomcat

tomcat

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 spring-messaging Support for messaging architectures and protocols

org.springframework spring-orm 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 model-view-controller implementation for web applications

org.springframework spring-websocket 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 congure an application that depends on Spring, rst with Maven and then with Gradle and nally
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 congure an application, your Maven dependencies will look like this:

<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>springcontext</artifactId>
<version>5.0.0.M4</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.

The example above works with the Maven Central repository. To use the Spring Maven repository (e.g. for milestones or developer snapshots),
you need to specify the repository location in your Maven conguration. 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 nd 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
springframeworkbom in your dependencyManagement section to ensure that all spring dependencies (both direct and transitive) are at the
same version.

<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>springframeworkbom</artifactId>
<version>5.0.0.M4</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>springcontext</artifactId>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>springweb</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()
//andoptionally...
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
congured, you can declare dependencies in the usual Gradle way:

dependencies{
compile("org.springframework:springcontext:5.0.0.M4")
testCompile("org.springframework:springtest:5.0.0.M4")
}

Ivy Dependency Management

If you prefer to use Ivy to manage dependencies then there are similar conguration options.

To congure Ivy to point to the Spring repository add the following resolver to your ivysettings.xml :

You can change the root URL from /release/ to /milestone/ or /snapshot/ as appropriate.

Once congured, you can add dependencies in the usual way. For example (in ivy.xml ):

<dependencyorg="org.springframework"
name="springcore"rev="5.0.0.M4"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 le.

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 les end dist.zip , for example spring-framework-{spring-version}-RELEASE-dist.zip.
Distributions are also published for milestones and snapshots.

2.3.2Logging
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

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 commonslogging (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
commonslogging , then it is from Spring and specically from the central module called springcore .

The nice thing about commonslogging 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 nd 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 commonslogging , 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 rst 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 commonslogging :

1. Exclude the dependency from the springcore module (as it is the only module that explicitly depends on commonslogging )
2. Depend on a special commonslogging 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>
<groupId>org.springframework</groupId>
<artifactId>springcore</artifactId>
<version>5.0.0.M4</version>
<exclusions>
<exclusion>
<groupId>commonslogging</groupId>
<artifactId>commonslogging</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 x 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 efcient at runtime than commonslogging 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 congure 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 conguration 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 commonslogging 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 congure 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 commonslogging ): 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>springcore</artifactId>
<version>5.0.0.M4</version>
<exclusions>
<exclusion>

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
commonslogging with respect to classloader issues, notably if you are in a strict container like an OSGi platform. Allegedly there is also a
performance benet 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 (
jcloverslf4j 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 conguration and management purposes. Its efcient and well-established, and in fact its
what we use at runtime when we build and test Spring. Spring also provides some utilities for conguring and initializing Log4j, so it has an
optional compile-time dependency on Log4j in some modules.

To make Log4j work with the default JCL dependency ( commonslogging ) all you need to do is put Log4j on the classpath, and provide it with
a conguration le ( 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>springcore</artifactId>
<version>5.0.0.M4</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 commonslogging
from your application is not enough in most situations.

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 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.

PartII.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. 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.

Chapter3, The IoC container

Chapter4, Resources
Chapter5, Validation, Data Binding, and Type Conversion
Chapter6, Spring Expression Language (SpEL)
Chapter7, Aspect Oriented Programming with Spring
Chapter8, Spring AOP APIs

3.The IoC container

3.1Introduction 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 dene 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 conguration 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 specic contexts such as the WebApplicationContext for use in web
applications.

In short, the BeanFactory provides the conguration framework and basic functionality, and the ApplicationContext adds more enterprise-
specic functionality. The ApplicationContext is a complete superset of the BeanFactory , and is used exclusively in this chapter in
descriptions of Springs IoC container. For more information on using the BeanFactory instead of the ApplicationContext, refer to
Section3.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 reected in the conguration metadata used by a container.

3.2Container overview

Several implementations of the ApplicationContext interface are supplied out-of-the-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 dening conguration metadata you can instruct the container to use Java annotations or code as the metadata format by
providing a small amount of XML conguration 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 le of the application will typically
sufce (see Section3.15.4, Convenient ApplicationContext instantiation for web applications). If you are using the Spring Tool Suite Eclipse-
powered development environment this boilerplate conguration 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 conguration metadata so that after
the ApplicationContext is created and initialized, you have a fully congured and executable system or application.

Figure3.1.The Spring IoC container

3.2.1Conguration metadata
As the preceding diagram shows, the Spring IoC container consumes a form of conguration metadata; this conguration metadata represents
how you as an application developer tell the Spring container to instantiate, congure, and assemble the objects in your application.

Conguration 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 conguration metadata. The Spring IoC container itself is totally decoupled
from the format in which this conguration metadata is actually written. These days many developers choose Java-based
conguration for their Spring applications.

For information about using other forms of metadata with the Spring container, see:

Annotation-based conguration: Spring 2.5 introduced support for annotation-based conguration metadata.
Java-based conguration: Starting with Spring 3.0, many features provided by the Spring JavaCong project became part of the core
Spring Framework. Thus you can dene beans external to your application classes by using Java rather than XML les. To use these new
features, see the @Configuration , @Bean , @Import and @DependsOn annotations.

Spring conguration consists of at least one and typically more than one bean denition that the container must manage. XML-based
conguration metadata shows these beans congured as <bean/> elements inside a top-level <beans/> element. Java conguration typically
uses @Bean annotated methods within a @Configuration class.

These bean denitions correspond to the actual objects that make up your application. Typically you dene 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 congure ne-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 congure 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 conguration metadata:

<beanid="..."class="...">
<!collaboratorsandconfigurationforthisbeangohere>
</bean>

<!morebeandefinitionsgohere>

</beans>

The id attribute is a string that you use to identify the individual bean denition. The class attribute denes the type of the bean and uses the
fully qualied 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.

3.2.2Instantiating a container
Instantiating a Spring IoC container is straightforward. The location path or paths supplied to an ApplicationContext constructor are actually
resource strings that allow the container to load conguration metadata from a variety of external resources such as the local le system, from
the Java CLASSPATH , and so on.

ApplicationContextcontext=
newClassPathXmlApplicationContext(newString[]{"services.xml","daos.xml"});

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

The following example shows the service layer objects (services.xml) conguration le:

<!services>

<beanid="petStore"class="org.springframework.samples.jpetstore.services.PetStoreServiceImpl">
<propertyname="accountDao"ref="accountDao"/>
<propertyname="itemDao"ref="itemDao"/>
<!additionalcollaboratorsandconfigurationforthisbeangohere>
</bean>

<!morebeandefinitionsforservicesgohere>

</beans>

The following example shows the data access objects daos.xml le:

<beanid="accountDao"
class="org.springframework.samples.jpetstore.dao.jpa.JpaAccountDao">
<!additionalcollaboratorsandconfigurationforthisbeangohere>
</bean>

<beanid="itemDao"class="org.springframework.samples.jpetstore.dao.jpa.JpaItemDao">
<!additionalcollaboratorsandconfigurationforthisbeangohere>
</bean>

<!morebeandefinitionsfordataaccessobjectsgohere>

</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 propertyname element refers to the name
of the JavaBean property, and the ref element refers to the name of another bean denition. This linkage between id and ref elements
expresses the dependency between collaborating objects. For details of conguring an objects dependencies, see Dependencies.

Composing XML-based conguration metadata

It can be useful to have bean denitions span multiple XML les. Often each individual XML conguration le represents a logical layer or
module in your architecture.

You can use the application context constructor to load bean denitions 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 denitions from another le or les. For example:

<beanid="bean1"class="..."/>
<beanid="bean2"class="..."/>
</beans>

In the preceding example, external bean denitions are loaded from three les: services.xml , messageSource.xml , and
themeSource.xml . All location paths are relative to the denition le doing the importing, so services.xml must be in the same directory or
classpath location as the le doing the importing, while messageSource.xml and themeSource.xml must be in a resources location below
the location of the importing le. 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 les being imported, including the top level <beans/> element, must be valid XML bean denitions
according to the Spring Schema.

It is possible, but not recommended, to reference les in parent directories using a relative "../" path. Doing so creates a
dependency on a le 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 conguration changes may lead to the choice of a different, incorrect directory.
You can always use fully qualied resource locations instead of relative paths: for example, "le:C:/cong/services.xml" or
"classpath:/cong/services.xml". However, be aware that you are coupling your applications conguration to specic 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.

3.2.3Using 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 TgetBean(Stringname,Class<T>requiredType) you can retrieve instances of your beans.

The ApplicationContext enables you to read bean denitions and access them as follows:

//createandconfigurebeans
ApplicationContextcontext=
newClassPathXmlApplicationContext(newString[]{"services.xml","daos.xml"});

//retrieveconfiguredinstance
PetStoreServiceservice=context.getBean("petStore",PetStoreService.class);

//useconfiguredinstance
List<String>userList=service.getUsernameList();

3.3Bean overview
A Spring IoC container manages one or more beans. These beans are created with the conguration metadata that you supply to the container,
for example, in the form of XML <bean/> denitions.

Within the container itself, these bean denitions are represented as BeanDefinition objects, which contain (among other information) the
following metadata:

A package-qualied class name: typically the actual implementation class of the bean being dened.
Bean behavioral conguration 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 conguration 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 denition.

Table3.1.The bean denition

Property Explained in

class Section3.3.2, Instantiating beans

name Section3.3.1, Naming beans

scope Section3.5, Bean scopes

constructor arguments Section3.4.1, Dependency Injection

properties Section3.4.1, Dependency Injection

autowiring mode Section3.4.5, Autowiring collaborators

lazy-initialization mode Section3.4.4, Lazy-initialized beans

initialization method the section called Initialization callbacks

destruction method the section called Destruction callbacks

In addition to bean denitions that contain information on how to create a specic 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 dened through metadata bean denitions.

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 ofcially supported and may lead to concurrent access exceptions and/or inconsistent state in the bean container.

3.3.1Naming beans
Every bean has one or more identiers. These identiers must be unique within the container that hosts the bean. A bean usually has only one
identier, but if it requires more than one, the extra ones can be considered aliases.

In XML-based conguration metadata, you use the id and/or name attributes to specify the bean identier(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 dened as an xsd:ID type, which constrained

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 eld 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 conguration 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 rst and second characters are upper case, the original casing gets
preserved. These are the same rules as dened by java.beans.Introspector.decapitalize (which Spring is using here).

Aliasing a bean outside the bean denition

In a bean denition itself, you can supply more than one name for the bean, by using a combination of up to one name specied 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 specic to
that component itself.

Specifying all aliases where the bean is actually dened is not always adequate, however. It is sometimes desirable to introduce an alias for a
bean that is dened elsewhere. This is commonly the case in large systems where conguration is split amongst each subsystem, each
subsystem having its own set of object denitions. In XML-based conguration metadata, you can use the <alias/> element to accomplish
this.

<aliasname="fromName"alias="toName"/>

In this case, a bean in the same container which is named fromName , may also, after the use of this alias denition, be referred to as toName .

For example, the conguration metadata for subsystem A may refer to a DataSource via the name subsystemAdataSource . The
conguration metadata for subsystem B may refer to a DataSource via the name subsystemBdataSource . When composing the main
application that uses both these subsystems the main application refers to the DataSource via the name myAppdataSource . To have all three
names refer to the same object you add to the MyApp conguration metadata the following aliases denitions:

<aliasname="subsystemAdataSource"alias="subsystemBdataSource"/>
<aliasname="subsystemAdataSource"alias="myAppdataSource"/>

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 denition (effectively creating a namespace), yet they refer to the same bean.

Java-conguration

If you are using Java-conguration, the @Bean annotation can be used to provide aliases see Section3.12.3, Using the @Bean
annotation for details.

3.3.2Instantiating beans
A bean denition 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 conguration metadata encapsulated by that bean denition to create (or acquire) an actual object.

If you use XML-based conguration 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 Section3.7, Bean denition inheritance.) You use the
Class property in one of two ways:

Inner class names. If you want to congure a bean denition 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 denition 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 specic interfaces or to be coded in a specic fashion. Simply specifying the bean class should
sufce. However, depending on what type of IoC you use for that specic 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 specication, Spring can manage it as well.

With XML-based conguration metadata you can specify your bean class as follows:

<beanid="exampleBean"class="examples.ExampleBean"/>

<beanname="anotherExample"class="examples.ExampleBeanTwo"/>

For details about the mechanism for supplying arguments to the constructor (if required) and setting object instance properties after the object is
constructed, see Injecting Dependencies.

Instantiation with a static factory method

When dening 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 factorymethod 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 denition is to call static factories in legacy code.

The following bean denition species that the bean will be created by calling a factory-method. The denition 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.

<beanid="clientService"
class="examples.ClientService"
factorymethod="createInstance"/>

publicclassClientService{
privatestaticClientServiceclientService=newClientService();
privateClientService(){}

publicstaticClientServicecreateInstance(){
returnclientService;
}
}

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 conguration 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 factorybean 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 factorymethod attribute.

<!thefactorybean,whichcontainsamethodcalledcreateInstance()>
<beanid="serviceLocator"class="examples.DefaultServiceLocator">
<!injectanydependenciesrequiredbythislocatorbean>
</bean>

<!thebeantobecreatedviathefactorybean>
<beanid="clientService"
factorybean="serviceLocator"
factorymethod="createClientServiceInstance"/>

publicclassDefaultServiceLocator{

privatestaticClientServiceclientService=newClientServiceImpl();
privateDefaultServiceLocator(){}

publicClientServicecreateClientServiceInstance(){
returnclientService;
}
}

One factory class can also hold more than one factory method as shown here:

<beanid="serviceLocator"class="examples.DefaultServiceLocator">
<!injectanydependenciesrequiredbythislocatorbean>
</bean>

<beanid="clientService"
factorybean="serviceLocator"
factorymethod="createClientServiceInstance"/>

<beanid="accountService"
factorybean="serviceLocator"
factorymethod="createAccountServiceInstance"/>

publicclassDefaultServiceLocator{

privatestaticClientServiceclientService=newClientServiceImpl();
privatestaticAccountServiceaccountService=newAccountServiceImpl();

privateDefaultServiceLocator(){}

publicClientServicecreateClientServiceInstance(){
returnclientService;
}

publicAccountServicecreateAccountServiceInstance(){
returnaccountService;
}

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

In Spring documentation, factory bean refers to a bean that is congured 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-specic
FactoryBean .

3.4Dependencies
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 dening a
number of bean denitions that stand alone to a fully realized application where objects collaborate to achieve a goal.

3.4.1Dependency Injection

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

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 specic 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 specic
interfaces, base classes or annotations.

publicclassSimpleMovieLister{

//theSimpleMovieListerhasadependencyonaMovieFinder
privateMovieFindermovieFinder;

//aconstructorsothattheSpringcontainercaninjectaMovieFinder
publicSimpleMovieLister(MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

//businesslogicthatactuallyusestheinjectedMovieFinderisomitted...

Constructor argument resolution

Constructor argument resolution matching occurs using the arguments type. If no potential ambiguity exists in the constructor arguments of a
bean denition, then the order in which the constructor arguments are dened in a bean denition is the order in which those arguments are
supplied to the appropriate constructor when the bean is being instantiated. Consider the following class:

packagex.y;

publicclassFoo{

publicFoo(Barbar,Bazbaz){
//...
}

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

<beanid="bar"class="x.y.Bar"/>

<beanid="baz"class="x.y.Baz"/>
</beans>

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:

packageexamples;

publicclassExampleBean{

//NumberofyearstocalculatetheUltimateAnswer
privateintyears;

//TheAnswertoLife,theUniverse,andEverything
privateStringultimateAnswer;

publicExampleBean(intyears,StringultimateAnswer){
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:

<beanid="exampleBean"class="examples.ExampleBean">
<constructorargtype="int"value="7500000"/>
<constructorargtype="java.lang.String"value="42"/>
</bean>

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

<beanid="exampleBean"class="examples.ExampleBean">
<constructorargindex="0"value="7500000"/>
<constructorargindex="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:

<beanid="exampleBean"class="examples.ExampleBean">
<constructorargname="years"value="7500000"/>
<constructorargname="ultimateAnswer"value="42"/>
</bean>

Keep in mind that to make this work out of the box your code must be compiled with the debug ag enabled so that Spring can look up the
parameter name from the constructor. If you cant compile your code with debug ag (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:

packageexamples;

publicclassExampleBean{

//Fieldsomitted

@ConstructorProperties({"years","ultimateAnswer"})
publicExampleBean(intyears,StringultimateAnswer){
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 specic interfaces, base classes or annotations.

publicclassSimpleMovieLister{

//theSimpleMovieListerhasadependencyontheMovieFinder

//asettermethodsothattheSpringcontainercaninjectaMovieFinder
publicvoidsetMovieFinder(MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

//businesslogicthatactuallyusestheinjectedMovieFinderisomitted...

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 congure 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 denitions, 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 conguration 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 benet of setter injection is that setter
methods make objects of that class amenable to reconguration 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 conguration metadata that describes all the beans. Conguration metadata can
be specied 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 denition 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 specied 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 conguration 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 dened in Section3.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 rst 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, and class B requires an instance of class A through
constructor injection. If you congure 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 congured by setters rather than constructors. Alternatively, avoid
constructor injection and use setter injection only. In other words, although it is not recommended, you can congure circular
dependencies with setter injection.

You can generally trust Spring to do the right thing. It detects conguration 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 conguration 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 conguration 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 congured 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 congures 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 congured init method or the InitializingBean
callback method) are invoked.

Examples of dependency injection

The following example uses XML-based conguration metadata for setter-based DI. A small part of a Spring XML conguration le species
some bean denitions:

<beanid="exampleBean"class="examples.ExampleBean">
<!setterinjectionusingthenestedrefelement>
<propertyname="beanOne">
<refbean="anotherExampleBean"/>
</property>

<!setterinjectionusingtheneaterrefattribute>
<propertyname="beanTwo"ref="yetAnotherBean"/>
<propertyname="integerProperty"value="1"/>
</bean>

<beanid="anotherExampleBean"class="examples.AnotherBean"/>
<beanid="yetAnotherBean"class="examples.YetAnotherBean"/>

publicclassExampleBean{

privateAnotherBeanbeanOne;
privateYetAnotherBeanbeanTwo;
privateinti;

publicvoidsetBeanOne(AnotherBeanbeanOne){
this.beanOne=beanOne;
}

publicvoidsetBeanTwo(YetAnotherBeanbeanTwo){
this.beanTwo=beanTwo;
}

publicvoidsetIntegerProperty(inti){
this.i=i;
}

In the preceding example, setters are declared to match against the properties specied in the XML le. The following example uses
constructor-based DI:

<beanid="exampleBean"class="examples.ExampleBean">
<!constructorinjectionusingthenestedrefelement>
<constructorarg>
<refbean="anotherExampleBean"/>
</constructorarg>

<!constructorinjectionusingtheneaterrefattribute>
<constructorargref="yetAnotherBean"/>

<constructorargtype="int"value="1"/>

<beanid="anotherExampleBean"class="examples.AnotherBean"/>
<beanid="yetAnotherBean"class="examples.YetAnotherBean"/>

publicclassExampleBean{

privateAnotherBeanbeanOne;
privateYetAnotherBeanbeanTwo;
privateinti;

publicExampleBean(
AnotherBeananotherBean,YetAnotherBeanyetAnotherBean,inti){
this.beanOne=anotherBean;
this.beanTwo=yetAnotherBean;
this.i=i;
}

The constructor arguments specied in the bean denition 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:

<beanid="exampleBean"class="examples.ExampleBean"factorymethod="createInstance">
<constructorargref="anotherExampleBean"/>
<constructorargref="yetAnotherBean"/>
<constructorargvalue="1"/>
</bean>

<beanid="anotherExampleBean"class="examples.AnotherBean"/>
<beanid="yetAnotherBean"class="examples.YetAnotherBean"/>

publicclassExampleBean{

//aprivateconstructor
privateExampleBean(...){
...
}

//astaticfactorymethod;theargumentstothismethodcanbe
//consideredthedependenciesofthebeanthatisreturned,
//regardlessofhowthoseargumentsareactuallyused.
publicstaticExampleBeancreateInstance(
AnotherBeananotherBean,YetAnotherBeanyetAnotherBean,inti){

ExampleBeaneb=newExampleBean(...);
//someotheroperations...
returneb;
}

Arguments to the static factory method are supplied via <constructorarg/> 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 factorybean attribute instead of the class attribute), so details will not be discussed here.

3.4.2Dependencies and conguration in detail

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

Straight values (primitives, Strings, and so on)

The value attribute of the <property/> element species 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.

<beanid="myDataSource"class="org.apache.commons.dbcp.BasicDataSource"destroymethod="close">
<!resultsinasetDriverClassName(String)call>
<propertyname="driverClassName"value="com.mysql.jdbc.Driver"/>
<propertyname="url"value="jdbc:mysql://localhost:3306/mydb"/>
<propertyname="username"value="root"/>
<propertyname="password"value="masterkaoli"/>
</bean>

The following example uses the p-namespace for even more succinct XML conguration.

<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd">

<beanid="myDataSource"class="org.apache.commons.dbcp.BasicDataSource"
destroymethod="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 denitions. Such IDE assistance is
highly recommended.

You can also congure a java.util.Properties instance as:

<beanid="mappings"
class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">

<!typedasajava.util.Properties>
<propertyname="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
<constructorarg/> or <property/> element.

<beanid="theTargetBean"class="..."/>

<beanid="theClientBean"class="...">
<propertyname="targetName">
<idrefbean="theTargetBean"/>
</property>
</bean>

The above bean denition snippet is exactly equivalent (at runtime) to the following snippet:

<beanid="theTargetBean"class="..."/>

<beanid="client"class="...">
<propertyname="targetName"value="theTargetBean"/>
</bean>

The rst 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

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 idreflocal references to idrefbean 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 conguration of AOP
interceptors in a ProxyFactoryBean bean denition. 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 nal element inside a <constructorarg/> or <property/> denition element. Here you set the value of the
specied 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 parent container, regardless of whether it is in the same XML le. The value of the bean 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.

<refbean="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.

<!intheparentcontext>
<beanid="accountService"class="com.foo.SimpleAccountService">
<!insertdependenciesasrequiredashere>
</bean>

<!inthechild(descendant)context>
<beanid="accountService"<!beannameisthesameastheparentbean>
class="org.springframework.aop.framework.ProxyFactoryBean">
<propertyname="target">
<refparent="accountService"/><!noticehowwerefertotheparentbean>
</property>
<!insertotherconfigurationanddependenciesasrequiredhere>
</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 reflocal references to refbean when upgrading to the 4.0
schema.

Inner beans
A <bean/> element inside the <property/> or <constructorarg/> elements denes a so-called inner bean.

<beanid="outer"class="...">
<!insteadofusingareferencetoatargetbean,simplydefinethetargetbeaninline>
<propertyname="target">
<beanclass="com.example.Person"><!thisistheinnerbean>
<propertyname="name"value="FionaApple"/>
<propertyname="age"value="25"/>
</bean>
</property>
</bean>

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.

<beanid="moreComplexObject"class="example.ComplexObject">
<!resultsinasetAdminEmails(java.util.Properties)call>
<propertyname="adminEmails">
<props>
<propkey="administrator">[email protected]</prop>
<propkey="support">[email protected]</prop>
<propkey="development">[email protected]</prop>
</props>
</property>
<!resultsinasetSomeList(java.util.List)call>
<propertyname="someList">
<list>
<value>alistelementfollowedbyareference</value>
<refbean="myDataSource"/>
</list>
</property>
<!resultsinasetSomeMap(java.util.Map)call>
<propertyname="someMap">
<map>
<entrykey="anentry"value="justsomestring"/>
<entrykey="aref"valueref="myDataSource"/>
</map>
</property>
<!resultsinasetSomeSet(java.util.Set)call>
<propertyname="someSet">
<set>
<value>justsomestring</value>
<refbean="myDataSource"/>
</set>
</property>
</bean>

The value of a map key or value, or a set value, can also again be any of the following elements:

Collection merging
The Spring container also supports the merging of collections. An application developer can dene 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 specied in the parent collection.

This section on merging discusses the parent-child bean mechanism. Readers unfamiliar with parent and child bean denitions may wish to
read the relevant section before continuing.

The following example demonstrates collection merging:

<beans>
<beanid="parent"abstract="true"class="example.ComplexObject">
<propertyname="adminEmails">
<props>
<propkey="administrator">[email protected]</prop>
<propkey="support">[email protected]</prop>
</props>
</property>
</bean>
<beanid="child"parent="parent">

Notice the use of the merge=true attribute on the <props/> element of the adminEmails property of the child bean denition. 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 specic 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 specied on the lower, inherited, child denition; specifying the merge attribute on a parent collection denition 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 .

publicclassFoo{

privateMap<String,Float>accounts;

publicvoidsetAccounts(Map<String,Float>accounts){
this.accounts=accounts;
}
}

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 reection. 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 conguration metadata snippet sets
the email property to the empty String value ("").

<beanclass="ExampleBean">
<propertyname="email"value=""/>
</bean>

The preceding example is equivalent to the following Java code:

exampleBean.setEmail("")

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

<beanclass="ExampleBean">
<propertyname="email">
<null/>
</property>
</bean>

The above conguration 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 conguration formats with namespaces, which are based on an XML Schema denition. The beans conguration
format discussed in this chapter is dened in an XML Schema document. However, the p-namespace is not dened in an XSD le and exists
only in the core of Spring.

The following example shows two XML snippets that resolve to the same result: The rst uses standard XML format and the second uses the p-
namespace.

<beanname="classic"class="com.example.ExampleBean">
<propertyname="email"value="[email protected]"/>
</bean>

<beanname="pnamespace"class="com.example.ExampleBean"
p:email="[email protected]"/>
</beans>

The example shows an attribute in the p-namespace called email in the bean denition. This tells Spring to include a property declaration. As
previously mentioned, the p-namespace does not have a schema denition, so you can set the name of the attribute to the property name.

This next example includes two more bean denitions that both have a reference to another bean:

<beanname="johnclassic"class="com.example.Person">
<propertyname="name"value="JohnDoe"/>
<propertyname="spouse"ref="jane"/>
</bean>

<beanname="johnmodern"
class="com.example.Person"
p:name="JohnDoe"
p:spouseref="jane"/>

<beanname="jane"class="com.example.Person">
<propertyname="name"value="JaneDoe"/>
</bean>
</beans>

The p-namespace is not as exible 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 conguring the constructor arguments rather then nested constructorarg elements.

Lets review the examples from the section called Constructor-based dependency injection with the c: namespace:

<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:c="http://www.springframework.org/schema/c"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd">

<beanid="bar"class="x.y.Bar"/>
<beanid="baz"class="x.y.Baz"/>

<!traditionaldeclaration>
<beanid="foo"class="x.y.Foo">
<constructorargref="bar"/>
<constructorargref="baz"/>
<constructorargvalue="[email protected]"/>
</bean>

<!cnamespacedeclaration>
<beanid="foo"class="x.y.Foo"c:barref="bar"c:bazref="baz"c:email="[email protected]"/>

</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 dened 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:

<!cnamespaceindexdeclaration>
<beanid="foo"class="x.y.Foo"c:_0ref="bar"c:_1ref="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 efcient in matching arguments so unless one really needs to, we recommend using
the name notation through-out your conguration.

Compound property names

You can use compound or nested property names when you set bean properties, as long as all components of the path except the nal property
name are not null . Consider the following bean denition.

<beanid="foo"class="foo.Bar">
<propertyname="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 nal 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.

3.4.3Using 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 conguration 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 dependson attribute can explicitly force one or
more beans to be initialized before the bean using this element is initialized. The following example uses the dependson attribute to express
a dependency on a single bean:

<beanid="beanOne"class="ExampleBean"dependson="manager"/>
<beanid="manager"class="ManagerBean"/>

To express a dependency on multiple beans, supply a list of bean names as the value of the dependson attribute, with commas, whitespace
and semicolons, used as valid delimiters:

<beanid="beanOne"class="ExampleBean"dependson="manager,accountDao">
<propertyname="manager"ref="manager"/>
</bean>

<beanid="manager"class="ManagerBean"/>
<beanid="accountDao"class="x.y.jdbc.JdbcAccountDao"/>

The dependson attribute in the bean denition can specify both an initialization time dependency and, in the case of singleton
beans only, a corresponding destroy time dependency. Dependent beans that dene a dependson relationship with a given
bean are destroyed rst, prior to the given bean itself being destroyed. Thus dependson can also control shutdown order.

3.4.4Lazy-initialized beans
By default, ApplicationContext implementations eagerly create and congure all singleton beans as part of the initialization process.
Generally, this pre-instantiation is desirable, because errors in the conguration 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 denition as lazy-initialized. A lazy-initialized bean tells the IoC container to create a bean instance when it is rst requested, rather than at
startup.

In XML, this behavior is controlled by the lazyinit attribute on the <bean/> element; for example:

<beanid="lazy"class="com.foo.ExpensiveToCreateBean"lazyinit="true"/>
<beanname="not.lazy"class="com.foo.AnotherBean"/>

When the preceding conguration 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 defaultlazyinit attribute on the <beans/> element; for
example:

<beansdefaultlazyinit="true">
<!nobeanswillbepreinstantiated...>
</beans>

3.4.5Autowiring 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:

Autowiring can signicantly 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 conguration as your objects evolve. For example, if you need to add a dependency to a class, that dependency
can be satised automatically without you needing to modify the conguration. 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 conguration metadata [2], you specify autowire mode for a bean denition 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.

Table3.2.Autowiring modes

Mode Explanation

no (Default) No autowiring. Bean references must be dened 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 denition is set to autowire by name, and it contains a master property (that is, it has a
setMaster(..) method), Spring looks for a bean denition 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.

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 denitions.

Consider the limitations and disadvantages of autowiring:

Explicit dependencies in property and constructorarg 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 denitions within the container may match the type specied 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 denition 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 denition by setting its autowirecandidate attributes to false as described in the next section.
Designate a single bean denition as the primary candidate by setting the primary attribute of its <bean/> element to true .
Implement the more ne-grained control available with annotation-based conguration, as described in Section3.9, Annotation-based
container conguration.

Excluding a bean from autowiring

On a per-bean basis, you can exclude a bean from autowiring. In Springs XML format, set the autowirecandidate attribute of the <bean/>
element to false ; the container makes that specic bean denition unavailable to the autowiring infrastructure (including annotation style
congurations such as @Autowired ).

The autowirecandidate attribute is designed to only affect type-based autowiring. It does not affect explicit references by
name, which will get resolved even if the specied bean is not marked as an autowire candidate. As a consequence, autowiring
by name will nevertheless inject a bean if the name matches.

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 congured using autowiring. Rather, the bean itself is not a candidate for autowiring other beans.

3.4.6Method 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 dening 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:

//aclassthatusesastatefulCommandstyleclasstoperformsomeprocessing
packagefiona.apple;

//SpringAPIimports
importorg.springframework.beans.BeansException;
importorg.springframework.context.ApplicationContext;
importorg.springframework.context.ApplicationContextAware;

publicclassCommandManagerimplementsApplicationContextAware{

privateApplicationContextapplicationContext;

publicObjectprocess(MapcommandState){
//grabanewinstanceoftheappropriateCommand
Commandcommand=createCommand();
//setthestateonthe(hopefullybrandnew)Commandinstance
command.setState(commandState);
returncommand.execute();
}

protectedCommandcreateCommand(){
//noticetheSpringAPIdependency!
returnthis.applicationContext.getBean("command",Command.class);
}

publicvoidsetApplicationContext(
ApplicationContextapplicationContext)throwsBeansException{
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.

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.

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:

packagefiona.apple;

//nomoreSpringimports!

publicabstractclassCommandManager{

publicObjectprocess(ObjectcommandState){
//grabanewinstanceoftheappropriateCommandinterface
Commandcommand=createCommand();
//setthestateonthe(hopefullybrandnew)Commandinstance
command.setState(commandState);
returncommand.execute();
}

//okay...butwhereistheimplementationofthismethod?
protectedabstractCommandcreateCommand();
}

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:

<public|protected>[abstract]<returntype>theMethodName(noarguments);

If the method is abstract , the dynamically-generated subclass implements the method. Otherwise, the dynamically-generated subclass
overrides the concrete method dened in the original class. For example:

<!astatefulbeandeployedasaprototype(nonsingleton)>
<beanid="myCommand"class="fiona.apple.AsyncCommand"scope="prototype">
<!injectdependencieshereasrequired>
</bean>

<!commandProcessorusesstatefulCommandHelper>
<beanid="commandManager"class="fiona.apple.CommandManager">
<lookupmethodname="createCommand"bean="myCommand"/>
</bean>

The bean identied as commandManager calls its own method createCommand() whenever it needs a new instance of the myCommand
bean. You must be careful to deploy the myCommand bean as a prototype, if that is actually what is needed. If it is as a singleton, the same
instance of the myCommand bean is returned each time.

Alternatively, within the annotation-based component model, you may declare a lookup method through the @Lookup annotation:

publicabstractclassCommandManager{

publicObjectprocess(ObjectcommandState){
Commandcommand=createCommand();
command.setState(commandState);
returncommand.execute();
}

@Lookup("myCommand")
protectedabstractCommandcreateCommand();
}

Or, more idiomatically, you may rely on the target bean getting resolved against the declared return type of the lookup method:

publicabstractclassCommandManager{

@Lookup
protectedabstractMyCommandcreateCommand();
}

Note that you will typically declare such annotated lookup methods with a concrete stub implementation, in order for them to be compatible with
Springs component scanning rules where abstract classes get ignored by default. This limitation does not apply in case of explicitly registered
or explicitly imported bean classes.

Another way of accessing differently scoped target beans is an ObjectFactory / Provider injection point. Check out the
section called Scoped beans as dependencies.
The interested reader may also nd the ServiceLocatorFactoryBean (in the
org.springframework.beans.factory.config package) to be of use.

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 conguration metadata, you can use the replacedmethod 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:

publicclassMyValueCalculator{

publicStringcomputeValue(Stringinput){
//somerealcode...
}

//someothermethods...

A class implementing the org.springframework.beans.factory.support.MethodReplacer interface provides the new method denition.

/**
*meanttobeusedtooverridetheexistingcomputeValue(String)
*implementationinMyValueCalculator
*/
publicclassReplacementComputeValueimplementsMethodReplacer{

publicObjectreimplement(Objecto,Methodm,Object[]args)throwsThrowable{
//gettheinputvalue,workwithit,andreturnacomputedresult
Stringinput=(String)args[0];
...
return...;
}
}

The bean denition to deploy the original class and specify the method override would look like this:

<beanid="myValueCalculator"class="x.y.z.MyValueCalculator">
<!arbitrarymethodreplacement>
<replacedmethodname="computeValue"replacer="replacementComputeValue">
<argtype>String</argtype>
</replacedmethod>
</bean>

<beanid="replacementComputeValue"class="a.b.c.ReplacementComputeValue"/>

You can use one or more contained <argtype/> elements within the <replacedmethod/> 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 qualied type name. For example, the following all match
java.lang.String :

java.lang.String
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.

3.5Bean scopes
When you create a bean denition, you create a recipe for creating actual instances of the class dened by that bean denition. The idea that a
bean denition 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 conguration values that are to be plugged into an object that is created from a
particular bean denition, but also the scope of the objects created from a particular bean denition. This approach is powerful and exible in
that you can choose the scope of the objects you create through conguration instead of having to bake in the scope of an object at the Java
class level. Beans can be dened to be deployed in one of a number of scopes: out of the box, the Spring Framework supports six scopes, ve
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.

Table3.3.Bean scopes

Scope Description

singleton (Default) Scopes a single bean denition to a single object instance per Spring IoC container.

prototype Scopes a single bean denition to any number of object instances.

request Scopes a single bean denition 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 denition. Only valid in the context of a web-aware Spring
ApplicationContext .

session Scopes a single bean denition to the lifecycle of an HTTP Session . Only valid in the context of a web-aware Spring
ApplicationContext .

application Scopes a single bean denition to the lifecycle of a ServletContext . Only valid in the context of a web-aware Spring
ApplicationContext .

websocket Scopes a single bean denition 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.

3.5.1The 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 denition result in that
one specic bean instance being returned by the Spring container.

To put it another way, when you dene a bean denition and it is scoped as a singleton, the Spring IoC container creates exactly one instance
of the object dened by that bean denition. 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.

Springs concept of a singleton bean differs from the Singleton pattern as dened 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 dene one bean for a particular class in a single Spring
container, then the Spring container creates one and only one instance of the class dened by that bean denition. The singleton scope is the
default scope in Spring. To dene a bean as a singleton in XML, you would write, for example:

<beanid="accountService"class="com.foo.DefaultAccountService"/>

<!thefollowingisequivalent,thoughredundant(singletonscopeisthedefault)>
<beanid="accountService"class="com.foo.DefaultAccountService"scope="singleton"/>

3.5.2The 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 specic
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 congured as a prototype, because a
typical DAO does not hold any conversational state; it was just easier for this author to reuse the core of the singleton diagram.

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

<beanid="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, congures, 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, congured 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.

3.5.3Singleton beans with prototype-bean dependencies

When you use singleton-scoped beans with dependencies on prototype beans, be aware 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 prototype-scoped 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 Section3.4.6, Method injection

3.5.4Request, session, application, and WebSocket scopes

The request , session , 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 conguration

To support the scoping of beans at the request , session , application , and websocket levels (web-scoped beans), some minor initial
conguration is required before you dene 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 , then no
special setup is necessary: DispatcherServlet already exposes 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 le:

<webapp>
...
<listener>
<listenerclass>
org.springframework.web.context.request.RequestContextListener
</listenerclass>
</listener>
...
</webapp>

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

<webapp>
...
<filter>
<filtername>requestContextFilter</filtername>
<filterclass>org.springframework.web.filter.RequestContextFilter</filterclass>
</filter>
<filtermapping>
<filtername>requestContextFilter</filtername>
<urlpattern>/*</urlpattern>
</filtermapping>
...
</webapp>

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
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 56/616
2/20/2017 Spring Framework Reference Documentation

Consider the following XML conguration for a bean denition:

<beanid="loginAction"class="com.foo.LoginAction"scope="request"/>

The Spring container creates a new instance of the LoginAction bean by using the loginAction bean denition 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 denition will not see these changes in state; they
are particular to an individual request. When the request completes processing, the bean that is scoped to the request is discarded.

When using annotation-driven components or Java Cong, the @RequestScope annotation can be used to assign a component to the
request scope.

@RequestScope
@Component
publicclassLoginAction{
//...
}

Session scope
Consider the following XML conguration for a bean denition:

<beanid="userPreferences"class="com.foo.UserPreferences"scope="session"/>

The Spring container creates a new instance of the UserPreferences bean by using the userPreferences bean denition for the lifetime of
a single HTTP Session . In other words, the userPreferences bean is effectively scoped at the HTTP Session level. As with
requestscoped 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 denition 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 Cong, the @SessionScope annotation can be used to assign a component to the
session scope.

@SessionScope
@Component
publicclassUserPreferences{
//...
}

Application scope
Consider the following XML conguration for a bean denition:

<beanid="appPreferences"class="com.foo.AppPreferences"scope="application"/>

The Spring container creates a new instance of the AppPreferences bean by using the appPreferences bean denition 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 Cong, the @ApplicationScope annotation can be used to assign a component to the
application scope.

@ApplicationScope
@Component
publicclassAppPreferences{
//...
}

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

You may also use <aop:scopedproxy/> 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:scopedproxy/> 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 eld) 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.
As an extended variant, you may declare ObjectProvider<MyTargetBean> which delivers several additional access variants,
including getIfAvailable and getIfUnique .
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 conguration in the following example is only one line, but it is important to understand the "why" as well as the "how" behind it.

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:aop="http://www.springframework.org/schema/aop"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/springaop.xsd">

<!anHTTPSessionscopedbeanexposedasaproxy>
<beanid="userPreferences"class="com.foo.UserPreferences"scope="session">
<!instructsthecontainertoproxythesurroundingbean>
<aop:scopedproxy/>
</bean>

<!asingletonscopedbeaninjectedwithaproxytotheabovebean>
<beanid="userService"class="com.foo.SimpleUserService">
<!areferencetotheproxieduserPreferencesbean>
<propertyname="userPreferences"ref="userPreferences"/>
</bean>
</beans>

To create such a proxy, you insert a child <aop:scopedproxy/> element into a scoped bean denition (see the section called Choosing the
type of proxy to create and Chapter38, XML Schema-based conguration). Why do denitions of beans scoped at the request , session
and custom-scope levels require the <aop:scopedproxy/> element? Lets examine the following singleton bean denition and contrast it with
what you need to dene for the aforementioned scopes (note that the following userPreferences bean denition as it stands is incomplete).

<beanid="userPreferences"class="com.foo.UserPreferences"scope="session"/>

<beanid="userManager"class="com.foo.UserManager">
<propertyname="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 specic 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.

<beanid="userPreferences"class="com.foo.UserPreferences"scope="session">
<aop:scopedproxy/>
</bean>

<beanid="userManager"class="com.foo.UserManager">
<propertyname="userPreferences"ref="userPreferences"/>
</bean>

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:scopedproxy/> 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 congure the Spring container to create standard JDK interface-based proxies for such scoped beans, by specifying
false for the value of the proxytargetclass attribute of the <aop:scopedproxy/> 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.

<!DefaultUserPreferencesimplementstheUserPreferencesinterface>
<beanid="userPreferences"class="com.foo.DefaultUserPreferences"scope="session">
<aop:scopedproxyproxytargetclass="false"/>
</bean>

<beanid="userManager"class="com.foo.UserManager">
<propertyname="userPreferences"ref="userPreferences"/>
</bean>

For more detailed information about choosing class-based or interface-based proxying, see Section7.6, Proxying mechanisms.

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

Creating a custom scope

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).

Objectget(Stringname,ObjectFactoryobjectFactory)

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 specied name is not
found.

Objectremove(Stringname)

The following method registers the callbacks the scope should execute when it is destroyed or when the specied object in the scope is
destroyed. Refer to the javadocs or a Spring scope implementation for more information on destruction callbacks.

voidregisterDestructionCallback(Stringname,RunnabledestructionCallback)

StringgetConversationId()

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:

voidregisterScope(StringscopeName,Scopescope);

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 rst 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.

ScopethreadScope=newSimpleThreadScope();
beanFactory.registerScope("thread",threadScope);

You then create bean denitions that adhere to the scoping rules of your custom Scope :

<beanid="..."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:

<beanclass="org.springframework.beans.factory.config.CustomScopeConfigurer">
<propertyname="scopes">
<map>
<entrykey="thread">
<beanclass="org.springframework.context.support.SimpleThreadScope"/>
</entry>
</map>
</property>
</bean>

<beanid="bar"class="x.y.Bar"scope="thread">
<propertyname="name"value="Rick"/>
<aop:scopedproxy/>
</bean>

<beanid="foo"class="x.y.Foo">
<propertyname="bar"ref="bar"/>
</bean>

</beans>

When you place <aop:scopedproxy/> in a FactoryBean implementation, it is the factory bean itself that is scoped, not the
object returned from getObject() .

3.6Customizing the nature of a bean

3.6.1Lifecycle 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 specic
interfaces. For details see Section3.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 denition metadata.

Internally, the Spring Framework uses BeanPostProcessor implementations to process any callback interfaces it can nd and call the
appropriate methods. If you need custom features or other lifecycle behavior Spring does not offer out-of-the-box, you can implement a
BeanPostProcessor yourself. For more information, see Section3.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 species a single method:

voidafterPropertiesSet()throwsException;

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 conguration metadata, you use the
initmethod attribute to specify the name of the method that has a void no-argument signature. With Java cong, you use the initMethod
attribute of @Bean , see the section called Receiving lifecycle callbacks. For example, the following:

<beanid="exampleInitBean"class="examples.ExampleBean"initmethod="init"/>

publicclassExampleBean{

publicvoidinit(){
//dosomeinitializationwork
}

is exactly the same as

<beanid="exampleInitBean"class="examples.AnotherExampleBean"/>

publicclassAnotherExampleBeanimplementsInitializingBean{

publicvoidafterPropertiesSet(){
//dosomeinitializationwork
}

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 species a single method:

voiddestroy()throwsException;

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 denitions. With XML-based
conguration metadata, you use the destroymethod attribute on the <bean/> . With Java cong, you use the destroyMethod attribute of
@Bean , see the section called Receiving lifecycle callbacks. For example, the following denition:

<beanid="exampleInitBean"class="examples.ExampleBean"destroymethod="cleanup"/>

publicclassExampleBean{

publicvoidcleanup(){
//dosomedestructionwork(likereleasingpooledconnections)
}

is exactly the same as:

<beanid="exampleInitBean"class="examples.AnotherExampleBean"/>

publicclassAnotherExampleBeanimplementsDisposableBean{

publicvoiddestroy(){
//dosomedestructionwork(likereleasingpooledconnections)
}

but does not couple the code to Spring.

The destroymethod 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 specic 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 defaultdestroymethod 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 cong.

Default initialization and destroy methods

When you write initialization and destroy method callbacks that do not use the Spring-specic 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 congure 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
congure an initmethod="init" attribute with each bean denition. 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.

publicclassDefaultBlogServiceimplementsBlogService{

privateBlogDaoblogDao;

publicvoidsetBlogDao(BlogDaoblogDao){
this.blogDao=blogDao;
}

//thisis(unsurprisingly)theinitializationcallbackmethod
publicvoidinit(){
if(this.blogDao==null){
thrownewIllegalStateException("The[blogDao]propertymustbeset.");
}
}

<beansdefaultinitmethod="init">

<beanid="blogService"class="com.foo.DefaultBlogService">
<propertyname="blogDao"ref="blogDao"/>
</bean>

</beans>

The presence of the defaultinitmethod 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 congure destroy method callbacks similarly (in XML, that is) by using the defaultdestroymethod 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 initmethod and destroymethod attributes of the <bean/> itself.

The Spring container guarantees that a congured 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 rst, then an AOP proxy (for example) with its interceptor chain is applied. If the target bean and the proxy
are dened 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.

If multiple lifecycle mechanisms are congured for a bean, and each mechanism is congured with a different method name, then
each congured method is executed in the order listed below. However, if the same method name is congured - 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 congured for the same bean, with different initialization methods, are called as follows:

Methods annotated with @PostConstruct

afterPropertiesSet() as dened by the InitializingBean callback interface
A custom congured init() method

Destroy methods are called in the same order:

Methods annotated with @PreDestroy

destroy() as dened by the DisposableBean callback interface
A custom congured destroy() method

Startup and shutdown callbacks

The Lifecycle interface denes the essential methods for any object that has its own lifecycle requirements (e.g. starts and stops some
background process):

publicinterfaceLifecycle{

voidstart();

voidstop();

booleanisRunning();

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 dened within that context. It does this by
delegating to a LifecycleProcessor :

publicinterfaceLifecycleProcessorextendsLifecycle{

voidonRefresh();

voidonClose();

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
notications and does NOT imply auto-startup at context refresh time. Consider implementing
org.springframework.context.SmartLifecycle instead for ne-grained control over auto-startup of a specic bean
(including startup phases). Also, please note that stop notications are not guaranteed to come before destruction: On regular
shutdown, all Lifecycle beans will rst receive a stop notication 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 denes
another option, namely the getPhase() method as dened on its super-interface, Phased .

publicinterfacePhased{

intgetPhase();

publicinterfaceSmartLifecycleextendsLifecycle,Phased{

booleanisAutoStartup();

voidstop(Runnablecallback);

When starting, the objects with the lowest phase start rst, 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 rst 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
rst (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 dened 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 dening a bean named "lifecycleProcessor" within the context. If you only want to modify the timeout, then dening the following
would be sufcient:

<beanid="lifecycleProcessor"class="org.springframework.context.support.DefaultLifecycleProcessor">
<!timeoutvalueinmilliseconds>
<propertyname="timeoutPerShutdownPhase"value="10000"/>
</bean>

As mentioned, the LifecycleProcessor interface denes 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 applications

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 congure and implement these destroy callbacks correctly.

To register a shutdown hook, you call the registerShutdownHook() method that is declared on the ConfigurableApplicationContext
interface:

importorg.springframework.context.ConfigurableApplicationContext;
importorg.springframework.context.support.ClassPathXmlApplicationContext;

publicfinalclassBoot{

publicstaticvoidmain(finalString[]args)throwsException{

ConfigurableApplicationContextctx=newClassPathXmlApplicationContext(
newString[]{"beans.xml"});

//addashutdownhookfortheabovecontext...
ctx.registerShutdownHook();

//apprunshere...

//mainmethodexits,hookiscalledpriortotheappshuttingdown...

}
}

3.6.2ApplicationContextAware 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 .

publicinterfaceApplicationContextAware{

voidsetApplicationContext(ApplicationContextapplicationContext)throwsBeansException;

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 le resources, publishing application events, and accessing a
MessageSource . These additional features are described in Section3.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 Section3.4.5, Autowiring collaborators) can provide a dependency of type ApplicationContext
for a constructor argument or setter method parameter, respectively. For more exibility, including the ability to autowire elds and multiple
parameter methods, use the new annotation-based autowiring features. If you do, the ApplicationContext is autowired into a eld,
constructor argument, or method parameter that is expecting the ApplicationContext type if the eld, constructor, or method in question
carries the @Autowired annotation. For more information, see Section3.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 dened in its associated object denition.

publicinterfaceBeanNameAware{

voidsetBeanName(Stringname)throwsBeansException;

3.6.3Other Aware interfaces

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:

Table3.4.Aware interfaces

Name Injected Dependency Explained in

ApplicationContextAware Declaring ApplicationContext Section3.6.2,

ApplicationContextAware and
BeanNameAware

ApplicationEventPublisherAware Event publisher of the enclosing ApplicationContext Section3.15, Additional

Capabilities of the
ApplicationContext

BeanClassLoaderAware Class loader used to load the bean classes. Section3.3.2, Instantiating
beans

BeanFactoryAware Declaring BeanFactory Section3.6.2,

ApplicationContextAware and
BeanNameAware

BeanNameAware Name of the declaring bean Section3.6.2,

ApplicationContextAware and
BeanNameAware

BootstrapContextAware Resource adapter BootstrapContext the container Chapter28, JCA CCI

runs in. Typically available only in JCA aware
ApplicationContext s

LoadTimeWeaverAware Dened weaver for processing class denition at load Section7.8.4, Load-time weaving
time with AspectJ in the Spring
Framework

MessageSourceAware Congured strategy for resolving messages (with support Section3.15, Additional
for parametrization and internationalization) Capabilities of the
ApplicationContext

NotificationPublisherAware Spring JMX notication publisher Section27.7, Notications

ResourceLoaderAware Congured loader for low-level access to resources Chapter4, Resources

ServletConfigAware Current ServletConfig the container runs in. Valid only Chapter18, Web MVC framework
in a web-aware Spring ApplicationContext

ServletContextAware Current ServletContext the container runs in. Valid Chapter18, Web MVC framework
only in a web-aware Spring ApplicationContext

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.

3.7Bean denition inheritance

A bean denition can contain a lot of conguration information, including constructor arguments, property values, and container-specic
information such as initialization method, static factory method name, and so on. A child bean denition inherits conguration data from a parent
denition. The child denition can override some values, or add others, as needed. Using parent and child bean denitions can save a lot of
typing. Effectively, this is a form of templating.

<beanid="inheritedTestBean"abstract="true"
class="org.springframework.beans.TestBean">
<propertyname="name"value="parent"/>
<propertyname="age"value="1"/>
</bean>

<beanid="inheritsWithDifferentClass"
class="org.springframework.beans.DerivedTestBean"
parent="inheritedTestBean"initmethod="initialize">
<propertyname="name"value="override"/>
<!theagepropertyvalueof1willbeinheritedfromparent>
</bean>

A child bean denition uses the bean class from the parent denition if none is specied, 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 denition 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 specify will override the
corresponding parent settings.

The remaining settings are always taken from the child denition: depends on, autowire mode, dependency check, singleton, lazy init.

The preceding example explicitly marks the parent bean denition as abstract by using the abstract attribute. If the parent denition does not
specify a class, explicitly marking the parent bean denition as abstract is required, as follows:

<beanid="inheritedTestBeanWithoutClass"abstract="true">
<propertyname="name"value="parent"/>
<propertyname="age"value="1"/>
</bean>

<beanid="inheritsWithClass"class="org.springframework.beans.DerivedTestBean"
parent="inheritedTestBeanWithoutClass"initmethod="initialize">
<propertyname="name"value="override"/>
<!agewillinheritthevalueof1fromtheparentbeandefinition>
</bean>

The parent bean cannot be instantiated on its own because it is incomplete, and it is also explicitly marked as abstract . When a denition is
abstract like this, it is usable only as a pure template bean denition that serves as a parent denition for child denitions. 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 denitions that are dened
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 denition which you intend to use only as a template, and this denition species 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.

3.8Container 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.

3.8.1Customizing beans using a BeanPostProcessor

The BeanPostProcessor interface denes callback methods that you can implement to provide your own (or override the containers default)
instantiation logic, dependency-resolution logic, and so forth. If you want to implement some custom logic after the Spring container nishes
instantiating, conguring, and initializing a bean, you can plug in one or more BeanPostProcessor implementations.

You can congure 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

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 dene a
BeanPostProcessor in one container, it will only post-process the beans in that container. In other words, beans that are dened
in one container are not post-processed by a BeanPostProcessor dened in another container, even if both containers are part
of the same hierarchy.
To change the actual bean denition (i.e., the blueprint that denes the bean), you instead need to use a
BeanFactoryPostProcessor as described in Section3.8.2, Customizing conguration 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 order to provide proxy-wrapping logic.

An ApplicationContext automatically detects any beans that are dened in the conguration 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 conguration 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 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 eld/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 rst 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 denition:

packagescripting;

importorg.springframework.beans.factory.config.BeanPostProcessor;
importorg.springframework.beans.BeansException;

publicclassInstantiationTracingBeanPostProcessorimplementsBeanPostProcessor{

//simplyreturntheinstantiatedbeanasis
publicObjectpostProcessBeforeInitialization(Objectbean,
StringbeanName)throwsBeansException{
returnbean;//wecouldpotentiallyreturnanyobjectreferencehere...
}

publicObjectpostProcessAfterInitialization(Objectbean,
StringbeanName)throwsBeansException{
System.out.println("Bean'"+beanName+"'created:"+bean.toString());
returnbean;
}

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:lang="http://www.springframework.org/schema/lang"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/lang
http://www.springframework.org/schema/lang/springlang.xsd">

<lang:groovyid="messenger"
scriptsource="classpath:org/springframework/scripting/groovy/Messenger.groovy">
<lang:propertyname="message"value="FionaAppleIsJustSoDreamy."/>
</lang:groovy>

<!
whentheabovebean(messenger)isinstantiated,thiscustom
BeanPostProcessorimplementationwilloutputthefacttothesystemconsole
>
<beanclass="scripting.InstantiationTracingBeanPostProcessor"/>

</beans>

Notice how the InstantiationTracingBeanPostProcessor is simply dened. 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 conguration also denes a bean that is backed by a Groovy script. The
Spring dynamic language support is detailed in the chapter entitled Chapter31, Dynamic language support.)

The following simple Java application executes the preceding code and conguration:

importorg.springframework.context.ApplicationContext;
importorg.springframework.context.support.ClassPathXmlApplicationContext;
importorg.springframework.scripting.Messenger;

publicfinalclassBoot{

publicstaticvoidmain(finalString[]args)throwsException{
ApplicationContextctx=newClassPathXmlApplicationContext("scripting/beans.xml");
Messengermessenger=(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

org.springframework.scripting.groovy.GroovyMessenger@272961

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

3.8.2Customizing conguration 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 conguration metadata; that is, the Spring IoC container allows a BeanFactoryPostProcessor to read the conguration
metadata and potentially change it before the container instantiates any beans other than BeanFactoryPostProcessor s.

You can congure 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 conguration metadata), then you
instead need to use a BeanPostProcessor (described above in Section3.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
dene a BeanFactoryPostProcessor in one container, it will only be applied to the bean denitions in that container. Bean
denitions in one container will not 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
conguration metadata that dene the container. Spring includes a number of predened 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 congure 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
defaultlazyinit attribute to true on the declaration of your <beans/> element.

Example: the Class name substitution PropertyPlaceholderCongurer

You use the PropertyPlaceholderConfigurer to externalize property values from a bean denition in a separate le using the standard
Java Properties format. Doing so enables the person deploying an application to customize environment-specic properties such as
database URLs and passwords, without the complexity or risk of modifying the main XML denition le or les for the container.

Consider the following XML-based conguration metadata fragment, where a DataSource with placeholder values is dened. The example
shows properties congured from an external Properties le. At runtime, a PropertyPlaceholderConfigurer is applied to the metadata
that will replace some properties of the DataSource. The values to replace are specied as placeholders of the form ${propertyname} which
follows the Ant / log4j / JSP EL style.

<beanclass="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<propertyname="locations"value="classpath:com/foo/jdbc.properties"/>
</bean>

<beanid="dataSource"destroymethod="close"
class="org.apache.commons.dbcp.BasicDataSource">
<propertyname="driverClassName"value="${jdbc.driverClassName}"/>
<propertyname="url"value="${jdbc.url}"/>
<propertyname="username"value="${jdbc.username}"/>
<propertyname="password"value="${jdbc.password}"/>
</bean>

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 le. The PropertyPlaceholderConfigurer checks for placeholders in most properties and attributes of a bean
denition. Furthermore, the placeholder prex and sufx can be customized.

With the context namespace introduced in Spring 2.5, it is possible to congure property placeholders with a dedicated conguration element.
One or more locations can be provided as a comma-separated list in the location attribute.

<context:propertyplaceholderlocation="classpath:com/foo/jdbc.properties"/>

The PropertyPlaceholderConfigurer not only looks for properties in the Properties le you specify. By default it also checks against the
Java System properties if it cannot nd a property in the specied properties les. You can customize this behavior by setting the
systemPropertiesMode property of the congurer 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 specied properties les. This is the default.
override (2): Check system properties rst, before trying the specied properties les. 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 sometimes useful when you have to
pick a particular implementation class at runtime. For example:
<beanclass="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<propertyname="locations">
<value>classpath:com/foo/strategy.properties</value>
</property>
<propertyname="properties">
<value>custom.strategy.class=com.foo.DefaultStrategy</value>
</property>
</bean>

<beanid="serviceStrategy"class="${custom.strategy.class}"/>

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

Example: the PropertyOverrideCongurer

The PropertyOverrideConfigurer , another bean factory post-processor, resembles the PropertyPlaceholderConfigurer , but unlike the
latter, the original denitions can have default values or no values at all for bean properties. If an overriding Properties le does not have an
entry for a certain bean property, the default context denition is used.

Note that the bean denition is not aware of being overridden, so it is not immediately obvious from the XML denition le that the override
congurer is being used. In case of multiple PropertyOverrideConfigurer instances that dene different values for the same bean property,
the last one wins, due to the overriding mechanism.

Properties le conguration lines take this format:

beanName.property=value

For example:

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

This example le can be used with a container denition 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 nal property being overridden is already
non-null (presumably initialized by the constructors). In this example

foo.fred.bob.sammy=123

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

Specied override values are always literal values; they are not translated into bean references. This convention also applies

With the context namespace introduced in Spring 2.5, it is possible to congure property overriding with a dedicated conguration element:

<context:propertyoverridelocation="classpath:override.properties"/>

3.8.3Customizing 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:

ObjectgetObject() : returns an instance of the object this factory creates. The instance can possibly be shared, depending on whether
this factory returns singletons or prototypes.
booleanisSingleton() : returns true if this FactoryBean returns singletons, false otherwise.
ClassgetObjectType() : 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 an id of
myBean , invoking getBean("myBean") on the container returns the product of the FactoryBean ; whereas, invoking getBean("&myBean")
returns the FactoryBean instance itself.

3.9Annotation-based container conguration

Are annotations better than XML for conguring Spring?

The introduction of annotation-based congurations 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 dened, annotations provide a lot of context in their declaration, leading to shorter and more
concise conguration. 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 conguration 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 JavaCong
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 conguration styles are supported by the Spring Tool Suite.

An alternative to XML setups is provided by annotation-based conguration 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 conguration into the
component class itself by using annotations on the relevant class, method, or eld 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 Section3.4.5, Autowiring collaborators but with more ne-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.

Annotation injection is performed before XML injection, thus the latter conguration will override the former for properties wired
through both approaches.

As always, you can register them as individual bean denitions, but they can also be implicitly registered by including the following tag in an
XML-based Spring conguration (notice the inclusion of the context namespace):

http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 72/616
2/20/2017 Spring Framework Reference Documentation
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/springcontext.xsd">

<context:annotationconfig/>

</beans>

(The implicitly registered post-processors include AutowiredAnnotationBeanPostProcessor , CommonAnnotationBeanPostProcessor ,

PersistenceAnnotationBeanPostProcessor , as well as the aforementioned RequiredAnnotationBeanPostProcessor .)

<context:annotationconfig/> only looks for annotations on beans in the same application context in which it is dened.
This means that, if you put <context:annotationconfig/> in a WebApplicationContext for a DispatcherServlet , it
only checks for @Autowired beans in your controllers, and not your services. See Section18.2, The DispatcherServlet for more
information.

3.9.1@Required
The @Required annotation applies to bean property setter methods, as in the following example:

publicclassSimpleMovieLister{

privateMovieFindermovieFinder;

@Required
publicvoidsetMovieFinder(MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

//...

This annotation simply indicates that the affected bean property must be populated at conguration time, through an explicit property value in a
bean denition 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.

3.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:

publicclassMovieRecommender{

privatefinalCustomerPreferenceDaocustomerPreferenceDao;

@Autowired
publicMovieRecommender(CustomerPreferenceDaocustomerPreferenceDao){
this.customerPreferenceDao=customerPreferenceDao;
}

//...

As of Spring Framework 4.3, the @Autowired constructor is no longer necessary if the target bean only denes one constructor.
If several 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:

publicclassSimpleMovieLister{

privateMovieFindermovieFinder;

@Autowired
publicvoidsetMovieFinder(MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

//...

You can also apply the annotation to methods with arbitrary names and/or multiple arguments:

publicclassMovieRecommender{

privateMovieCatalogmovieCatalog;

privateCustomerPreferenceDaocustomerPreferenceDao;

@Autowired
publicvoidprepare(MovieCatalogmovieCatalog,
CustomerPreferenceDaocustomerPreferenceDao){
this.movieCatalog=movieCatalog;
this.customerPreferenceDao=customerPreferenceDao;
}

//...

You can apply @Autowired to elds as well and even mix it with constructors:

publicclassMovieRecommender{

privatefinalCustomerPreferenceDaocustomerPreferenceDao;

@Autowired
privateMovieCatalogmovieCatalog;

@Autowired
publicMovieRecommender(CustomerPreferenceDaocustomerPreferenceDao){
this.customerPreferenceDao=customerPreferenceDao;
}

//...

It is also possible to provide all beans of a particular type from the ApplicationContext by adding the annotation to a eld or method that
expects an array of that type:

publicclassMovieRecommender{

@Autowired
privateMovieCatalog[]movieCatalogs;

//...

The same applies for typed collections:

publicclassMovieRecommender{

privateSet<MovieCatalog>movieCatalogs;

@Autowired

//...

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 specic order.

Even typed Maps can be autowired as long as the expected key type is String . The Map values will contain all beans of the expected type,
and the keys will contain the corresponding bean names:

publicclassMovieRecommender{

privateMap<String,MovieCatalog>movieCatalogs;

@Autowired
publicvoidsetMovieCatalogs(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 elds as indicating required dependencies. This behavior can be changed as demonstrated below.

publicclassSimpleMovieLister{

privateMovieFindermovieFinder;

@Autowired(required=false)
publicvoidsetMovieFinder(MovieFindermovieFinder){
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
satised, that is the constructor that has the largest number of arguments.
@Autowiredsrequiredattributeisrecommendedoverthe`@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.

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.

publicclassMovieRecommender{

@Autowired
privateApplicationContextcontext;

publicMovieRecommender(){
}

//...

@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.

3.9.3Fine-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 conguration that denes firstMovieCatalog as the primary MovieCatalog .

@Configuration
publicclassMovieConfiguration{

@Bean
@Primary
publicMovieCatalogfirstMovieCatalog(){...}

@Bean
publicMovieCatalogsecondMovieCatalog(){...}

//...

With such conguration, the following MovieRecommender will be autowired with the firstMovieCatalog .

publicclassMovieRecommender{

@Autowired
privateMovieCatalogmovieCatalog;

//...

The corresponding bean denitions appear as follows.

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/springcontext.xsd">

<context:annotationconfig/>

<beanclass="example.SimpleMovieCatalog"primary="true">
<!injectanydependenciesrequiredbythisbean>
</bean>

<beanclass="example.SimpleMovieCatalog">
<!injectanydependenciesrequiredbythisbean>
</bean>

<beanid="movieRecommender"class="example.MovieRecommender"/>

</beans>

3.9.4Fine-tuning annotation-based autowiring with qualiers

@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 qualier values with specic

publicclassMovieRecommender{

@Autowired
@Qualifier("main")
privateMovieCatalogmovieCatalog;

//...

The @Qualifier annotation can also be specied on individual constructor arguments or method parameters:

publicclassMovieRecommender{

privateMovieCatalogmovieCatalog;

privateCustomerPreferenceDaocustomerPreferenceDao;

@Autowired
publicvoidprepare(@Qualifier("main")MovieCatalogmovieCatalog,
CustomerPreferenceDaocustomerPreferenceDao){
this.movieCatalog=movieCatalog;
this.customerPreferenceDao=customerPreferenceDao;
}

//...

The corresponding bean denitions appear as follows. The bean with qualier value "main" is wired with the constructor argument that is
qualied with the same value.

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/springcontext.xsd">

<context:annotationconfig/>

<beanclass="example.SimpleMovieCatalog">
<qualifiervalue="main"/>

<!injectanydependenciesrequiredbythisbean>
</bean>

<beanclass="example.SimpleMovieCatalog">
<qualifiervalue="action"/>

<!injectanydependenciesrequiredbythisbean>
</bean>

<beanid="movieRecommender"class="example.MovieRecommender"/>

</beans>

For a fallback match, the bean name is considered a default qualier value. Thus you can dene the bean with an id "main" instead of the
nested qualier element, leading to the same matching result. However, although you can use this convention to refer to specic beans by
name, @Autowired is fundamentally about type-driven injection with optional semantic qualiers. This means that qualier 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 qualier values are "main" or "EMEA" or "persistent", expressing characteristics of a specic component that are
independent from the bean id , which may be auto-generated in case of an anonymous bean denition like the one in the preceding example.

Qualiers also apply to typed collections, as discussed above, for example, to Set<MovieCatalog> . In this case, all matching beans according
to the declared qualiers are injected as a collection. This implies that qualiers do not have to be unique; they rather simply constitute ltering

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 @Resource annotation, which is semantically
dened to identify a specic 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 specied String qualier value
will be considered within those type-selected candidates only, e.g. matching an "account" qualier against beans marked with the
same qualier label.
For beans that are themselves dened as a collection/map or array type, @Resource is a ne solution, referring to the specic
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, qualier 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 elds, constructors, and multi-argument methods, allowing for narrowing through qualier annotations at
the parameter level. By contrast, @Resource is supported only for elds and bean property setter methods with a single
argument. As a consequence, stick with qualiers if your injection target is a constructor or a multi-argument method.

You can create your own custom qualier annotations. Simply dene an annotation and provide the @Qualifier annotation within your
denition:

@Target({ElementType.FIELD,ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public@interfaceGenre{

Stringvalue();
}

Then you can provide the custom qualier on autowired elds and parameters:

publicclassMovieRecommender{

@Autowired
@Genre("Action")
privateMovieCatalogactionCatalog;
privateMovieCatalogcomedyCatalog;

@Autowired
publicvoidsetComedyCatalog(@Genre("Comedy")MovieCatalogcomedyCatalog){
this.comedyCatalog=comedyCatalog;
}

//...

Next, provide the information for the candidate bean denitions. You can add <qualifier/> tags as sub-elements of the <bean/> tag and
then specify the type and value to match your custom qualier annotations. The type is matched against the fully-qualied class name of the
annotation. Or, as a convenience if no risk of conicting names exists, you can use the short class name. Both approaches are demonstrated in
the following example.

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/springcontext.xsd">

<context:annotationconfig/>

<beanclass="example.SimpleMovieCatalog">
<qualifiertype="Genre"value="Action"/>
<!injectanydependenciesrequiredbythisbean>
</bean>

<beanclass="example.SimpleMovieCatalog">
<qualifiertype="example.Genre"value="Comedy"/>
<!injectanydependenciesrequiredbythisbean>
</bean>

<beanid="movieRecommender"class="example.MovieRecommender"/>

</beans>

In Section3.10, Classpath scanning and managed components, you will see an annotation-based alternative to providing the qualier
metadata in XML. Specically, see Section3.10.8, Providing qualier metadata with annotations.

In some cases, it may be sufcient 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 ofine catalog that would be
searched when no Internet connection is available. First dene the simple annotation:

@Target({ElementType.FIELD,ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public@interfaceOffline{

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

publicclassMovieRecommender{

@Autowired
@Offline
privateMovieCatalogofflineCatalog;

//...

Now the bean denition only needs a qualier type :

<beanclass="example.SimpleMovieCatalog">
<qualifiertype="Offline"/>
<!injectanydependenciesrequiredbythisbean>
</bean>

You can also dene custom qualier annotations that accept named attributes in addition to or instead of the simple value attribute. If multiple
attribute values are then specied on a eld or parameter to be autowired, a bean denition must match all such attribute values to be
considered an autowire candidate. As an example, consider the following annotation denition:

@Target({ElementType.FIELD,ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public@interfaceMovieQualifier{

Stringgenre();

Formatformat();

In this case Format is an enum:

publicenumFormat{
VHS,DVD,BLURAY
}

The elds to be autowired are annotated with the custom qualier and include values for both attributes: genre and format .
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 79/616
2/20/2017 Spring Framework Reference Documentation

publicclassMovieRecommender{

@Autowired
@MovieQualifier(format=Format.VHS,genre="Action")
privateMovieCatalogactionVhsCatalog;

@Autowired
@MovieQualifier(format=Format.VHS,genre="Comedy")
privateMovieCatalogcomedyVhsCatalog;

@Autowired
@MovieQualifier(format=Format.DVD,genre="Action")
privateMovieCatalogactionDvdCatalog;

@Autowired
@MovieQualifier(format=Format.BLURAY,genre="Comedy")
privateMovieCatalogcomedyBluRayCatalog;

//...

Finally, the bean denitions should contain matching qualier values. This example also 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 qualier is present, as in the last two bean denitions in the following
example.

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/springcontext.xsd">

<context:annotationconfig/>

<beanclass="example.SimpleMovieCatalog">
<qualifiertype="MovieQualifier">
<attributekey="format"value="VHS"/>
<attributekey="genre"value="Action"/>
</qualifier>
<!injectanydependenciesrequiredbythisbean>
</bean>

<beanclass="example.SimpleMovieCatalog">
<qualifiertype="MovieQualifier">
<attributekey="format"value="VHS"/>
<attributekey="genre"value="Comedy"/>
</qualifier>
<!injectanydependenciesrequiredbythisbean>
</bean>

<beanclass="example.SimpleMovieCatalog">
<metakey="format"value="DVD"/>
<metakey="genre"value="Action"/>
<!injectanydependenciesrequiredbythisbean>
</bean>

<beanclass="example.SimpleMovieCatalog">
<metakey="format"value="BLURAY"/>
<metakey="genre"value="Comedy"/>
<!injectanydependenciesrequiredbythisbean>
</bean>

</beans>

3.9.5Using generics as autowiring qualiers

@Configuration
publicclassMyConfiguration{

@Bean
publicStringStorestringStore(){
returnnewStringStore();
}

@Bean
publicIntegerStoreintegerStore(){
returnnewIntegerStore();
}

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 qualier:

@Autowired
privateStore<String>s1;//<String>qualifier,injectsthestringStorebean

@Autowired
privateStore<Integer>s2;//<Integer>qualifier,injectstheintegerStorebean

Generic qualiers also apply when autowiring Lists, Maps and Arrays:

//InjectallStorebeansaslongastheyhavean<Integer>generic
//Store<String>beanswillnotappearinthislist
@Autowired
privateList<Store<Integer>>s;

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

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

The AutowireCandidateResolver determines autowire candidates by:

the autowirecandidate value of each bean denition

any defaultautowirecandidates 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 denition among the
candidates has a primary attribute set to true , it will be selected.

3.9.7@Resource
Spring also supports injection using the JSR-250 @Resource annotation on elds 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:

publicclassSimpleMovieLister{

privateMovieFindermovieFinder;
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 81/616
2/20/2017 Spring Framework Reference Documentation

@Resource(name="myMovieFinder")
publicvoidsetMovieFinder(MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

If no name is specied explicitly, the default name is derived from the eld name or setter method. In case of a eld, it takes the eld name; in
case of a setter method, it takes the bean property name. So the following example is going to have the bean with name "movieFinder" injected
into its setter method:

publicclassSimpleMovieLister{

privateMovieFindermovieFinder;

@Resource
publicvoidsetMovieFinder(MovieFindermovieFinder){
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 congure 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 specied, and similar to @Autowired , @Resource nds a primary type
match instead of a specic named bean and resolves well-known resolvable dependencies: the BeanFactory , ApplicationContext ,
ResourceLoader , ApplicationEventPublisher , and MessageSource interfaces.

Thus in the following example, the customerPreferenceDao eld rst looks for a bean named customerPreferenceDao, then falls back to a
primary type match for the type CustomerPreferenceDao . The "context" eld is injected based on the known resolvable dependency type
ApplicationContext .

publicclassMovieRecommender{

@Resource
privateCustomerPreferenceDaocustomerPreferenceDao;

@Resource
privateApplicationContextcontext;

publicMovieRecommender(){
}

//...

3.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.

publicclassCachingMovieLister{

@PostConstruct
publicvoidpopulateMovieCache(){
//populatesthemoviecacheuponinitialization...
}

@PreDestroy

For details about the effects of combining various lifecycle mechanisms, see the section called Combining lifecycle mechanisms.

3.10Classpath scanning and managed components

Most examples in this chapter use XML to specify the conguration metadata that produces each BeanDefinition within the Spring container.
The previous section (Section3.9, Annotation-based container conguration) demonstrates how to provide a lot of the conguration metadata
through source-level annotations. Even in those examples, however, the "base" bean denitions are explicitly dened in the XML le, while 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 lter criteria and have a corresponding bean denition 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 lter criteria to select which classes will have bean denitions registered with the container.

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

3.10.1@Component and further stereotype annotations

The @Repository annotation is a marker for any class that fullls 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 Section16.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 specic 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.

3.10.2Meta-annotations
Many of the annotations provided by Spring can be used as meta-annotations in your own code. A meta-annotation is simply an annotation that
can be applied to another annotation. For example, the @Service annotation mentioned above is meta-annotated with @Component :

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component//Springwillseethisandtreat@Serviceinthesamewayas@Component
public@interfaceService{

//....
}

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@interfaceSessionScope{

/**
*Aliasfor{@linkScope#proxyMode}.
*<p>Defaultsto{@linkScopedProxyMode#TARGET_CLASS}.
*/
@AliasFor(annotation=Scope.class)
ScopedProxyModeproxyMode()defaultScopedProxyMode.TARGET_CLASS;

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

@Service
@SessionScope
publicclassSessionScopedService{
//...
}

Or with an overridden value for the proxyMode as follows:

@Service
@SessionScope(proxyMode=ScopedProxyMode.INTERFACES)
publicclassSessionScopedUserServiceimplementsUserService{
//...
}

For further details, consult the Spring Annotation Programming Model.

3.10.3Automatically detecting classes and registering bean denitions

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
publicclassSimpleMovieLister{

privateMovieFindermovieFinder;

@Autowired
publicSimpleMovieLister(MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

@Repository
publicclassJpaMovieFinderimplementsMovieFinder{
//implementationelidedforclarity
}

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")
publicclassAppConfig{
...
}

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

<context:componentscanbasepackage="org.example"/>

</beans>

The use of <context:componentscan> implicitly enables the functionality of <context:annotationconfig> . There is

usually no need to include the <context:annotationconfig> element when using <context:componentscan> .

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 les-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://stackoverow.com/questions/19394570/java-jre-7u45-breaks-classloader-
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
conguration metadata provided in XML.

You can disable the registration of AutowiredAnnotationBeanPostProcessor and CommonAnnotationBeanPostProcessor

by including the annotation-cong attribute with a value of false.

3.10.4Using lters 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
lters. Add them as includeFilters or excludeFilters parameters of the @ComponentScan annotation (or as include-lter or exclude-lter sub-
elements of the componentscan element). Each lter element requires the type and expression attributes. The following table describes
the ltering options.

Table3.5.Filter Types

Filter Type Example Expression Description

annotation org.example.SomeAnnotation An annotation to be present at the type level in target components.

(default)

assignable 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.TypeFilter interface.

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

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

and the equivalent using XML

You can also disable the default lters by setting useDefaultFilters=false on the annotation or providing
usedefaultfilters="false" as an attribute of the <componentscan/> element. This will in effect disable automatic
detection of classes annotated with @Component , @Repository , @Service , @Controller , or @Configuration .

3.10.5Dening bean metadata within components

Spring components can also contribute bean denition metadata to the container. You do this with the same @Bean annotation used to dene
bean metadata within @Configuration annotated classes. Here is a simple example:

@Component
publicclassFactoryMethodComponent{

@Bean
@Qualifier("public")
publicTestBeanpublicInstance(){
returnnewTestBean("publicInstance");
}

publicvoiddoWork(){
//Componentmethodimplementationomitted
}

This class is a Spring component that has application-specic code contained in its doWork() method. However, it also contributes a bean
denition that has a factory method referring to the method publicInstance() . The @Bean annotation identies the factory method and other
bean denition properties, such as a qualier value through the @Qualifier annotation. Other method level annotations that can be specied
are @Scope , @Lazy , and custom qualier 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 elds and methods are supported as previously discussed, with additional support for autowiring of @Bean methods:

@Component
publicclassFactoryMethodComponent{

privatestaticinti;

@Bean
@Qualifier("public")
publicTestBeanpublicInstance(){
returnnewTestBean("publicInstance");
}

//useofacustomqualifierandautowiringofmethodparameters
@Bean
protectedTestBeanprotectedInstance(
@Qualifier("public")TestBeanspouse,
@Value("#{privateInstance.age}")Stringcountry){
TestBeantb=newTestBean("protectedInstance",1);
tb.setSpouse(spouse);
tb.setCountry(country);
returntb;
}

@Bean
privateTestBeanprivateInstance(){

@Bean
@RequestScope
publicTestBeanrequestScopedInstance(){
returnnewTestBean("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 denes the value of the property through the notation #{<expression>} . For
@Value annotations, an expression resolver is precongured to look for bean names when resolving expression text.

As of Spring Framework 4.3, you may also declare a factory method parameter of type InjectionPoint (or its more specic subclass
DependencyDescriptor ) in order to access the requesting injection point that triggers the creation of the current bean. Note that this will only
apply to the actual creation of bean instances, not to the injection of existing instances. As a consequence, this feature makes most sense for
beans of prototype scope. For other scopes, the factory method will only ever see the injection point which triggered the creation of a new bean
instance in the given scope: for example, the dependency that triggered the creation of a lazy singleton bean. Use the provided injection point
metadata with semantic care in such scenarios.

@Component
publicclassFactoryMethodComponent{

@Bean@Scope("prototype")
publicTestBeanprototypeInstance(InjectionPointinjectionPoint){
returnnewTestBean("prototypeInstancefor"+injectionPoint.getMember());
}
}

The @Bean methods in a regular 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 elds. CGLIB proxying is
the means by which invoking methods or elds 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 eld 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 conguration class
as an instance. This makes particular sense when dening 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 conguration 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 immediate impact on the resulting bean denition in Springs
container. You may freely declare your factory methods as you see t 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 conguration class, as well as on Java 8 default
methods declared in interfaces implemented by the component or conguration class. This allows for a lot of exibility in
composing complex conguration 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 conguration scenarios: The variant with the largest number of satisable dependencies will
be picked at construction time, analogous to how the container selects between multiple @Autowired constructors.

3.10.6Naming 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
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 87/616
2/20/2017 Spring Framework Reference Documentation
name value will thereby provide that name to the corresponding bean denition.

If such an annotation contains no name value or for any other detected component (such as those discovered by custom lters), the default
bean name generator returns the uncapitalized non-qualied class name. For example, if the following two components were detected, the
names would be myMovieLister and movieFinderImpl :

@Service("myMovieLister")
publicclassSimpleMovieLister{
//...
}

@Repository
publicclassMovieFinderImplimplementsMovieFinder{
//...
}

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-qualied class
name when conguring the scanner:

@Configuration
@ComponentScan(basePackages="org.example",nameGenerator=MyNameGenerator.class)
publicclassAppConfig{
...
}

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.

3.10.7Providing 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 specied via the @Scope annotation. Simply provide the name of the scope within the
annotation:

@Scope("prototype")
@Repository
publicclassMovieFinderImplimplementsMovieFinder{
//...
}

For details on web-specic scopes, see Section3.5.4, Request, session, application, and WebSocket scopes.

To provide a custom strategy for scope resolution rather than relying on the annotation-based approach, implement the
ScopeMetadataResolver interface, and be sure to include a default no-arg constructor. Then, provide the fully-qualied class
name when conguring the scanner:

@Configuration
@ComponentScan(basePackages="org.example",scopeResolver=MyScopeResolver.class)
publicclassAppConfig{
...
}

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
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 88/616
2/20/2017 Spring Framework Reference Documentation
three possible values are: no, interfaces, and targetClass. For example, the following conguration will result in standard JDK dynamic proxies:

@Configuration
@ComponentScan(basePackages="org.example",scopedProxy=ScopedProxyMode.INTERFACES)
publicclassAppConfig{
...
}

3.10.8Providing qualier metadata with annotations

The @Qualifier annotation is discussed in Section3.9.4, Fine-tuning annotation-based autowiring with qualiers. The examples in that
section demonstrate the use of the @Qualifier annotation and custom qualier annotations to provide ne-grained control when you resolve
autowire candidates. Because those examples were based on XML bean denitions, the qualier metadata was provided on the candidate bean
denitions 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 qualier metadata with type-level annotations on the candidate class. The following three
examples demonstrate this technique:

@Component
@Qualifier("Action")
publicclassActionMovieCatalogimplementsMovieCatalog{
//...
}

@Component
@Genre("Action")
publicclassActionMovieCatalogimplementsMovieCatalog{
//...
}

@Component
@Offline
publicclassCachingMovieCatalogimplementsMovieCatalog{
//...
}

As with most annotation-based alternatives, keep in mind that the annotation metadata is bound to the class denition itself, while
the use of XML allows for multiple beans of the same type to provide variations in their qualier metadata, because that metadata
is provided per-instance rather than per-class.

3.11Using 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 le pom.xml:
<dependency>
<groupId>javax.inject</groupId>
<artifactId>javax.inject</artifactId>
<version>1</version>
</dependency>

3.11.1Dependency Injection with @Inject and @Named

Instead of @Autowired , @javax.inject.Inject may be used as follows:

importjavax.inject.Inject;

privateMovieFindermovieFinder;

@Inject
publicvoidsetMovieFinder(MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

publicvoidlistMovies(){
this.movieFinder.findMovies(...);
...
}
}

As with @Autowired , it is possible to use @Inject at the eld 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:

importjavax.inject.Inject;
importjavax.inject.Provider;

publicclassSimpleMovieLister{

privateProvider<MovieFinder>movieFinder;

@Inject
publicvoidsetMovieFinder(Provider<MovieFinder>movieFinder){
this.movieFinder=movieFinder;
}

publicvoidlistMovies(){
this.movieFinder.get().findMovies(...);
...
}
}

If you would like to use a qualied name for the dependency that should be injected, you should use the @Named annotation as follows:

importjavax.inject.Inject;
importjavax.inject.Named;

publicclassSimpleMovieLister{

privateMovieFindermovieFinder;

@Inject
publicvoidsetMovieFinder(@Named("main")MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

//...
}

3.11.2@Named and @ManagedBean: standard equivalents to the @Component annotation

Instead of @Component , @javax.inject.Named or javax.annotation.ManagedBean may be used as follows:

importjavax.inject.Inject;
importjavax.inject.Named;

@Named("movieListener")//@ManagedBean("movieListener")couldbeusedaswell
publicclassSimpleMovieLister{

privateMovieFindermovieFinder;

@Inject
publicvoidsetMovieFinder(MovieFindermovieFinder){
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:

importjavax.inject.Inject;
importjavax.inject.Named;

@Named
publicclassSimpleMovieLister{

privateMovieFindermovieFinder;

@Inject
publicvoidsetMovieFinder(MovieFindermovieFinder){
this.movieFinder=movieFinder;
}

//...
}

When using @Named or @ManagedBean , it is possible to use component scanning in the exact same way as when using Spring annotations:

@Configuration
@ComponentScan(basePackages="org.example")
publicclassAppConfig{
...
}

In contrast to @Component , the JSR-330 @Named and the JSR-250 ManagedBean annotations are not composable. Please use
Springs stereotype model for building custom component annotations.

3.11.3Limitations of JSR-330 standard annotations

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

Table3.6.Spring component model elements vs. JSR-330 variants

Spring javax.inject.* javax.inject restrictions / comments

@Autowired @Inject @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.
@ManagedBean

@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 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.

@Qualier @Qualier / javax.inject.Qualifier is just a meta-annotation for building custom qualiers.

@Named Concrete String qualiers (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.

3.12Java-based container conguration

3.12.1Basic concepts: @Bean and @Conguration

The central artifacts in Springs new Java-conguration support are @Configuration -annotated classes and @Bean -annotated methods.

The @Bean annotation is used to indicate that a method instantiates, congures and initializes a new object to be managed by the Spring IoC
container. For those familiar with Springs <beans/> XML conguration 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 denitions. Furthermore, @Configuration
classes allow inter-bean dependencies to be dened by simply calling other @Bean methods in the same class. The simplest possible
@Configuration class would read as follows:

@Configuration
publicclassAppConfig{

@Bean
publicMyServicemyService(){
returnnewMyServiceImpl();
}

The AppConfig class above would be equivalent to the following Spring <beans/> XML:

Full @Conguration 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 below. First, however, well cover the various ways of
creating a spring container using Java-based conguration.

3.12.2Instantiating the Spring container using AnnotationCongApplicationContext

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 denition, and all declared
@Bean methods within the class are also registered as bean denitions.

When @Component and JSR-330 classes are provided, they are registered as bean denitions, 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 les 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:

publicstaticvoidmain(String[]args){
ApplicationContextctx=newAnnotationConfigApplicationContext(AppConfig.class);
MyServicemyService=ctx.getBean(MyService.class);

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:

publicstaticvoidmain(String[]args){
ApplicationContextctx=newAnnotationConfigApplicationContext(MyServiceImpl.class,Dependency1.class,Dependency2.
MyServicemyService=ctx.getBean(MyService.class);
myService.doStuff();
}

The above assumes that MyServiceImpl , Dependency1 and Dependency2 use Spring dependency injection annotations such as
@Autowired .

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

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

publicstaticvoidmain(String[]args){
AnnotationConfigApplicationContextctx=newAnnotationConfigApplicationContext();
ctx.register(AppConfig.class,OtherConfig.class);
ctx.register(AdditionalConfig.class);
ctx.refresh();
MyServicemyService=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")
publicclassAppConfig{
...
}

Experienced Spring users will be familiar with the XML declaration equivalent from Springs context: namespace
<beans>
<context:componentscanbasepackage="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 denitions within the container. AnnotationConfigApplicationContext exposes the scan(String
) method to
allow for the same component-scanning functionality:

publicstaticvoidmain(String[]args){
AnnotationConfigApplicationContextctx=newAnnotationConfigApplicationContext();
ctx.scan("com.acme");
ctx.refresh();
MyServicemyService=ctx.getBean(MyService.class);
}

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 denitions within the container.

Support for web applications with AnnotationCongWebApplicationContext

A WebApplicationContext variant of AnnotationConfigApplicationContext is available with
AnnotationConfigWebApplicationContext . This implementation may be used when conguring the Spring ContextLoaderListener

<webapp>
<!ConfigureContextLoaderListenertouseAnnotationConfigWebApplicationContext
insteadofthedefaultXmlWebApplicationContext>
<contextparam>
<paramname>contextClass</paramname>
<paramvalue>
org.springframework.web.context.support.AnnotationConfigWebApplicationContext
</paramvalue>
</contextparam>

<!Configurationlocationsmustconsistofoneormorecommaorspacedelimited
fullyqualified@Configurationclasses.Fullyqualifiedpackagesmayalsobe
specifiedforcomponentscanning>
<contextparam>
<paramname>contextConfigLocation</paramname>
<paramvalue>com.acme.AppConfig</paramvalue>
</contextparam>

<!BootstraptherootapplicationcontextasusualusingContextLoaderListener>
<listener>
<listenerclass>org.springframework.web.context.ContextLoaderListener</listenerclass>
</listener>

<!DeclareaSpringMVCDispatcherServletasusual>
<servlet>
<servletname>dispatcher</servletname>
<servletclass>org.springframework.web.servlet.DispatcherServlet</servletclass>
<!ConfigureDispatcherServlettouseAnnotationConfigWebApplicationContext
insteadofthedefaultXmlWebApplicationContext>
<initparam>
<paramname>contextClass</paramname>
<paramvalue>
org.springframework.web.context.support.AnnotationConfigWebApplicationContext
</paramvalue>
</initparam>
<!Again,configlocationsmustconsistofoneormorecommaorspacedelimited
andfullyqualified@Configurationclasses>
<initparam>
<paramname>contextConfigLocation</paramname>
<paramvalue>com.acme.web.MvcConfig</paramvalue>
</initparam>
</servlet>

<!mapallrequestsfor/app/*tothedispatcherservlet>
<servletmapping>
<servletname>dispatcher</servletname>
<urlpattern>/app/*</urlpattern>
</servletmapping>
</webapp>

3.12.3Using 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 denition within an
ApplicationContext of the type specied 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
publicclassAppConfig{

@Bean
publicTransferServicetransferService(){

The preceding conguration 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
publicclassAppConfig{

@Bean
publicTransferServicetransferService(AccountRepositoryaccountRepository){
returnnewTransferServiceImpl(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 dened 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.

The standard set of *Aware interfaces such as BeanFactoryAware, BeanNameAware, MessageSourceAware, ApplicationContextAware, and
so on are also fully supported.

The @Bean annotation supports specifying arbitrary initialization and destruction callback methods, much like Spring XMLs initmethod and
destroymethod attributes on the bean element:

publicclassFoo{
publicvoidinit(){
//initializationlogic
}
}

publicclassBar{
publicvoidcleanup(){
//destructionlogic
}
}

@Configuration
publicclassAppConfig{

@Bean(initMethod="init")
publicFoofoo(){
returnnewFoo();
}

@Bean(destroyMethod="cleanup")
publicBarbar(){
returnnewBar();
}

By default, beans dened using Java cong 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 denition 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="")
publicDataSourcedataSource()throwsNamingException{
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
publicclassAppConfig{
@Bean
publicFoofoo(){
Foofoo=newFoo();
foo.init();
returnfoo;
}

//...

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 dened with the @Bean annotation should have a specic scope. You can use any of the standard scopes
specied in the Bean Scopes section.

The default scope is singleton , but you can override this with the @Scope annotation:

@Configuration
publicclassMyConfiguration{

@Bean
@Scope("prototype")
publicEncryptorencryptor(){
//...
}

@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 conguration is the <aop:scopedproxy/> element. Conguring 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 .

//anHTTPSessionscopedbeanexposedasaproxy
@Bean
@SessionScope
publicUserPreferencesuserPreferences(){
returnnewUserPreferences();
}

@Bean
publicServiceuserService(){
UserServiceservice=newSimpleUserService();
//areferencetotheproxieduserPreferencesbean
service.setUserPreferences(userPreferences());
returnservice;
}

Customizing bean naming

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

@Configuration
publicclassAppConfig{

@Bean(name="myFoo")
publicFoofoo(){
returnnewFoo();
}

Bean aliasing
As discussed in Section3.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
publicclassAppConfig{

@Bean(name={"dataSource","subsystemAdataSource","subsystemBdataSource"})
publicDataSourcedataSource(){
//instantiate,configureandreturnDataSourcebean...
}

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
publicclassAppConfig{

@Bean
@Description("Providesabasicexampleofabean")
publicFoofoo(){
returnnewFoo();
}

3.12.4Using the @Conguration annotation

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
publicclassAppConfig{

@Bean
publicFoofoo(){
returnnewFoo(bar());
}

@Bean
publicBarbar(){
returnnewBar();
}

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 conguration provides a natural means for implementing this
pattern.

publicabstractclassCommandManager{
publicObjectprocess(ObjectcommandState){
//grabanewinstanceoftheappropriateCommandinterface
Commandcommand=createCommand();
//setthestateonthe(hopefullybrandnew)Commandinstance
command.setState(commandState);
returncommand.execute();
}

//okay...butwhereistheimplementationofthismethod?
protectedabstractCommandcreateCommand();
}

Using Java-conguration 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")
publicAsyncCommandasyncCommand(){
AsyncCommandcommand=newAsyncCommand();
//injectdependencieshereasrequired
returncommand;
}

@Bean
publicCommandManagercommandManager(){
//returnnewanonymousimplementationofCommandManagerwithcommand()overridden
//toreturnanewprototypeCommandobject
returnnewCommandManager(){
protectedCommandcreateCommand(){
returnasyncCommand();
}
}
}

Further information about how Java-based conguration works internally

The following example shows a @Bean annotated method being called twice:

@Configuration
publicclassAppConfig{

@Bean
publicClientServiceclientService1(){
ClientServiceImplclientService=newClientServiceImpl();
clientService.setClientDao(clientDao());
returnclientService;
}

@Bean
publicClientServiceclientService2(){
ClientServiceImplclientService=newClientServiceImpl();
clientService.setClientDao(clientDao());
returnclientService;
}

@Bean
publicClientDaoclientDao(){
returnnewClientDaoImpl();
}

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 denitely 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 rst 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, in particular that conguration
classes must not be nal. However, as of 4.3, any constructors are allowed on conguration classes, including the use of
@Autowired or a single non-default constructor declaration for default injection.
If you prefer to avoid any CGLIB-imposed limitations, consider declaring your @Bean methods on non- @Configuration classes,
e.g. on plain @Component classes instead. Cross-method calls between @Bean methods wont get intercepted then, so youll
have to exclusively rely on dependency injection at the constructor or method level there.

3.12.5Composing Java-based congurations

Using the @Import annotation

Much as the <import/> element is used within Spring XML les to aid in modularizing congurations, the @Import annotation allows for
loading @Bean denitions from another conguration class:

@Configuration
publicclassConfigA{

@Bean
publicAa(){
returnnewA();
}

@Configuration
@Import(ConfigA.class)
publicclassConfigB{

@Bean

Now, rather than needing to specify both ConfigA.class and ConfigB.class when instantiating the context, only ConfigB needs to be
supplied explicitly:

publicstaticvoidmain(String[]args){
ApplicationContextctx=newAnnotationConfigApplicationContext(ConfigB.class);

//nowbothbeansAandBwillbeavailable...
Aa=ctx.getBean(A.class);
Bb=ctx.getBean(B.class);
}

This approach simplies 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.

As of Spring Framework 4.2, @Import also supports references to regular component classes, analogous to the
AnnotationConfigApplicationContext.register method. This is particularly useful if youd like to avoid component
scanning, using a few conguration classes as entry points for explicitly dening all your components.

Injecting dependencies on imported @Bean denitions

The example above works, but is simplistic. In most practical scenarios, beans will have dependencies on one another across conguration
classes. When using XML, this is not an issue, per se, because there is no compiler involved, and one can simply declare 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 conguration 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
publicclassServiceConfig{

@Bean
publicTransferServicetransferService(AccountRepositoryaccountRepository){
returnnewTransferServiceImpl(accountRepository);
}

@Configuration
publicclassRepositoryConfig{

@Bean
publicAccountRepositoryaccountRepository(DataSourcedataSource){
returnnewJdbcAccountRepository(dataSource);
}

@Configuration
@Import({ServiceConfig.class,RepositoryConfig.class})
publicclassSystemTestConfig{

@Bean
publicDataSourcedataSource(){
//returnnewDataSource
}

publicstaticvoidmain(String[]args){
ApplicationContextctx=newAnnotationConfigApplicationContext(SystemTestConfig.class);
//everythingwiresupacrossconfigurationclasses...
TransferServicetransferService=ctx.getBean(TransferService.class);
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 100/616
2/20/2017 Spring Framework Reference Documentation
transferService.transfer(100.00,"A123","C456");
}

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 denitions via @Bean . Those should
usually be declared as static@Bean methods, not triggering the instantiation of their containing conguration class. Otherwise,
@Autowired and @Value wont work on the conguration class itself since it is being created as a bean instance too early.

@Configuration
publicclassServiceConfig{

@Autowired
privateAccountRepositoryaccountRepository;

@Bean
publicTransferServicetransferService(){
returnnewTransferServiceImpl(accountRepository);
}

@Configuration
publicclassRepositoryConfig{

privatefinalDataSourcedataSource;

@Autowired
publicRepositoryConfig(DataSourcedataSource){
this.dataSource=dataSource;
}

@Bean
publicAccountRepositoryaccountRepository(){
returnnewJdbcAccountRepository(dataSource);
}

@Configuration
@Import({ServiceConfig.class,RepositoryConfig.class})
publicclassSystemTestConfig{

@Bean
publicDataSourcedataSource(){
//returnnewDataSource
}

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 denes 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
denitions are declared is still somewhat ambiguous. For example, as a developer looking at ServiceConfig , how do you know exactly where

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 conguration classes themselves:

@Configuration
publicclassServiceConfig{

@Autowired
privateRepositoryConfigrepositoryConfig;

@Bean
publicTransferServicetransferService(){
//navigate'through'theconfigclasstothe@Beanmethod!
returnnewTransferServiceImpl(repositoryConfig.accountRepository());
}

In the situation above, it is completely explicit where AccountRepository is dened. 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
publicclassServiceConfig{

@Autowired
privateRepositoryConfigrepositoryConfig;

@Bean
publicTransferServicetransferService(){
returnnewTransferServiceImpl(repositoryConfig.accountRepository());
}
}

@Configuration
publicinterfaceRepositoryConfig{

@Bean
AccountRepositoryaccountRepository();

@Configuration
publicclassDefaultRepositoryConfigimplementsRepositoryConfig{

@Bean
publicAccountRepositoryaccountRepository(){
returnnewJdbcAccountRepository(...);
}

@Configuration
@Import({ServiceConfig.class,DefaultRepositoryConfig.class})//importtheconcreteconfig!
publicclassSystemTestConfig{

@Bean
publicDataSourcedataSource(){
//returnDataSource
}

publicstaticvoidmain(String[]args){
ApplicationContextctx=newAnnotationConfigApplicationContext(SystemTestConfig.class);
TransferServicetransferService=ctx.getBean(TransferService.class);
transferService.transfer(100.00,"A123","C456");
}

Conditionally include @Conguration 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 specic prole has been
enabled in the Spring Environment (see Section3.13.1, Bean denition proles for details).

The @Profile annotation is actually implemented using a much more exible annotation called @Conditional . The @Conditional
annotation indicates specic 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
publicbooleanmatches(ConditionContextcontext,AnnotatedTypeMetadatametadata){
if(context.getEnvironment()!=null){
//Readthe@Profileannotationattributes
MultiValueMap<String,Object>attrs=metadata.getAllAnnotationAttributes(Profile.class.getName());
if(attrs!=null){
for(Objectvalue:attrs.get("value")){
if(context.getEnvironment().acceptsProfiles(((String[])value))){
returntrue;
}
}
returnfalse;
}
}
returntrue;
}

See the @Conditional javadocs for more detail.

Combining Java and XML conguration

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 congure 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 @Conguration 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 les. Below youll nd the options for using @Configuration classes in this kind of "XML-centric" situation.

Remember that @Configuration classes are ultimately just bean denitions in the container. In this example, we create a @Configuration
class named AppConfig and include it within systemtestconfig.xml as a <bean/> denition. Because
<context:annotationconfig/> is switched on, the container will recognize the @Configuration annotation and process the @Bean
methods declared in AppConfig properly.

@Configuration
publicclassAppConfig{

@Autowired
privateDataSourcedataSource;

@Bean
publicAccountRepositoryaccountRepository(){
returnnewJdbcAccountRepository(dataSource);
}

@Bean
publicTransferServicetransferService(){
returnnewTransferService(accountRepository());
}

system-test-cong.xml:

<beanclass="com.acme.AppConfig"/>

<beanclass="org.springframework.jdbc.datasource.DriverManagerDataSource">
<propertyname="url"value="${jdbc.url}"/>
<propertyname="username"value="${jdbc.username}"/>
<propertyname="password"value="${jdbc.password}"/>
</bean>
</beans>

jdbc.properties:

jdbc.url=jdbc:hsqldb:hsql://localhost/xdb
jdbc.username=sa
jdbc.password=

publicstaticvoidmain(String[]args){
ApplicationContextctx=newClassPathXmlApplicationContext("classpath:/com/acme/systemtestconfig.xml");
TransferServicetransferService=ctx.getBean(TransferService.class);
//...
}

In systemtestconfig.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 redene systemtestconfig.xml to take advantage of component-
scanning. Note that in this case, we dont need to explicitly declare <context:annotationconfig/> , because
<context:componentscan/> enables the same functionality.

system-test-cong.xml:

@Conguration class-centric use of XML with @ImportResource

In applications where @Configuration classes are the primary mechanism for conguring the container, it will still likely be necessary to use
at least some XML. In these scenarios, simply use @ImportResource and dene only as much XML as is needed. Doing so achieves a "Java-
centric" approach to conguring the container and keeps XML to a bare minimum.

@Configuration
@ImportResource("classpath:/com/acme/propertiesconfig.xml")
publicclassAppConfig{

@Value("${jdbc.url}")
privateStringurl;

@Value("${jdbc.username}")
privateStringusername;

@Value("${jdbc.password}")
privateStringpassword;

@Bean
publicDataSourcedataSource(){
returnnewDriverManagerDataSource(url,username,password);
}

propertiesconfig.xml
<beans>
<context:propertyplaceholderlocation="classpath:/com/acme/jdbc.properties"/>
</beans>

jdbc.properties
jdbc.url=jdbc:hsqldb:hsql://localhost/xdb
jdbc.username=sa
jdbc.password=

publicstaticvoidmain(String[]args){
ApplicationContextctx=newAnnotationConfigApplicationContext(AppConfig.class);
TransferServicetransferService=ctx.getBean(TransferService.class);
//...
}

3.13Environment abstraction
The Environment is an abstraction integrated in the container that models two key aspects of the application environment: proles and
properties.

A prole is a named, logical group of bean denitions to be registered with the container only if the given prole is active. Beans may be
assigned to a prole whether dened in XML or via annotations. The role of the Environment object with relation to proles is in determining
which proles (if any) are currently active, and which proles (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 les, 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 convenient service interface for conguring property sources and resolving
properties from them.

3.13.1Bean denition proles

Bean denition proles 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 rst use case in a practical application that requires a DataSource . In a test environment, the conguration may look like
this:

@Bean
publicDataSourcedataSource(){
returnnewEmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("myschema.sql")
.addScript("mytestdata.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="")
publicDataSourcedataSource()throwsException{
Contextctx=newInitialContext();
return(DataSource)ctx.lookup("java:comp/env/jdbc/datasource");
}

If we generalize the example use case above of environment-specic bean denitions, we end up with the need to register certain bean
denitions in certain contexts, while not in others. You could say that you want to register a certain prole of bean denitions in situation A, and
a different prole in situation B. Lets rst see how we can update our conguration to reect this need.

@Prole
The @Profile annotation allows you to indicate that a component is eligible for registration when one or more specied proles are active.
Using our example above, we can rewrite the dataSource conguration as follows:

@Configuration
@Profile("dev")
publicclassStandaloneDataConfig{

@Bean
publicDataSourcedataSource(){
returnnewEmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("classpath:com/bank/config/sql/schema.sql")
.addScript("classpath:com/bank/config/sql/testdata.sql")
.build();
}
}

@Configuration
@Profile("production")
publicclassJndiDataConfig{

@Bean(destroyMethod="")
publicDataSourcedataSource()throwsException{
Contextctx=newInitialContext();
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.

@Profile can be used as a meta-annotation for the purpose of creating a custom composed annotation. The following example denes 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@interfaceProduction{
}

@Profile can also be declared at the method level to include only one particular bean of a conguration class:

@Configuration
publicclassAppConfig{

@Bean
@Profile("dev")
publicDataSourcedevDataSource(){
returnnewEmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("classpath:com/bank/config/sql/schema.sql")
.addScript("classpath:com/bank/config/sql/testdata.sql")
.build();
}

@Bean
@Profile("production")
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 106/616
2/20/2017 Spring Framework Reference Documentation
publicDataSourceproductionDataSource()throwsException{
Contextctx=newInitialContext();
return(DataSource)ctx.lookup("java:comp/env/jdbc/datasource");
}
}

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 specied proles are active. If a @Component or @Configuration class is
marked with @Profile({"p1","p2"}) , that class will not be registered/processed unless proles 'p1' and/or 'p2' have been
activated. If a given prole is prexed with the NOT operator ( ! ), the annotated element will be registered if the prole is not
active. For example, given @Profile({"p1","!p2"}) , registration will occur if prole 'p1' is active or if prole 'p2' is not active.

3.13.2XML bean denition proles

The XML counterpart is the profile attribute of the <beans> element. Our sample conguration above can be rewritten in two XML les as
follows:

<beansprofile="dev"
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:jdbc="http://www.springframework.org/schema/jdbc"
xsi:schemaLocation="...">

<jdbc:embeddeddatabaseid="dataSource">
<jdbc:scriptlocation="classpath:com/bank/config/sql/schema.sql"/>
<jdbc:scriptlocation="classpath:com/bank/config/sql/testdata.sql"/>
</jdbc:embeddeddatabase>
</beans>

<beansprofile="production"
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:jee="http://www.springframework.org/schema/jee"
xsi:schemaLocation="...">

<jee:jndilookupid="dataSource"jndiname="java:comp/env/jdbc/datasource"/>
</beans>

It is also possible to avoid that split and nest <beans/> elements within the same le:

<!otherbeandefinitions>

<beansprofile="dev">
<jdbc:embeddeddatabaseid="dataSource">
<jdbc:scriptlocation="classpath:com/bank/config/sql/schema.sql"/>
<jdbc:scriptlocation="classpath:com/bank/config/sql/testdata.sql"/>
</jdbc:embeddeddatabase>
</beans>

<beansprofile="production">
<jee:jndilookupid="dataSource"jndiname="java:comp/env/jdbc/datasource"/>
</beans>
</beans>

The springbean.xsd has been constrained to allow such elements only as the last ones in the le. This should help provide exibility without
incurring clutter in the XML les.

Activating a prole
Now that we have updated our conguration, we still need to instruct Spring which prole is active. If we started our sample application right
now, we would see a NoSuchBeanDefinitionException thrown, because the container could not nd the Spring bean named dataSource .

AnnotationConfigApplicationContextctx=newAnnotationConfigApplicationContext();
ctx.getEnvironment().setActiveProfiles("dev");
ctx.register(SomeConfig.class,StandaloneDataConfig.class,JndiDataConfig.class);
ctx.refresh();

In addition, proles may also be activated declaratively through the spring.profiles.active property which may be specied through
system environment variables, JVM system properties, servlet context parameters in web.xml , or even as an entry in JNDI (see
Section3.13.3, PropertySource abstraction). In integration tests, active proles can be declared via the @ActiveProfiles annotation in the
springtest module (see the section called Context conguration with environment proles).

Note that proles are not an "either-or" proposition; it is possible to activate multiple proles at once. Programmatically, simply provide multiple
prole names to the setActiveProfiles() method, which accepts Stringvarargs:

ctx.getEnvironment().setActiveProfiles("profile1","profile2");

Declaratively, spring.profiles.active may accept a comma-separated list of prole names:

Dspring.profiles.active="profile1,profile2"

Default prole
The default prole represents the prole that is enabled by default. Consider the following:

@Configuration
@Profile("default")
publicclassDefaultDataConfig{

@Bean
publicDataSourcedataSource(){
returnnewEmbeddedDatabaseBuilder()
.setType(EmbeddedDatabaseType.HSQL)
.addScript("classpath:com/bank/config/sql/schema.sql")
.build();
}
}

If no prole is active, the dataSource above will be created; this can be seen as a way to provide a default denition for one or more beans. If
any prole is enabled, the default prole will not apply.

The name of the default prole can be changed using setDefaultProfiles() on the Environment or declaratively using the
spring.profiles.default property.

3.13.3PropertySource abstraction
Springs Environment abstraction provides search operations over a congurable hierarchy of property sources. To explain fully, consider the
following:

ApplicationContextctx=newGenericApplicationContext();
Environmentenv=ctx.getEnvironment();
booleancontainsFoo=env.containsProperty("foo");
System.out.println("Doesmyenvironmentcontainthe'foo'property?"+containsFoo);

In the snippet above, we see a high-level way of asking Spring whether the foo property is dened 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 congured 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 cong and servlet context
parameters. It can optionally enable a JndiPropertySource . See the javadocs for details.

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:
ServletCong 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 congurable. Perhaps you have a custom source of properties that youd like to integrate into this
search. No problemsimply implement and instantiate your own PropertySource and add it to the set of PropertySources for the current
Environment :

ConfigurableApplicationContextctx=newGenericApplicationContext();
MutablePropertySourcessources=ctx.getEnvironment().getPropertySources();
sources.addFirst(newMyPropertySource());

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.

3.13.4@PropertySource
The @PropertySource annotation provides a convenient and declarative mechanism for adding a PropertySource to Springs
Environment .

Given a le "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")
publicclassAppConfig{
@Autowired
Environmentenv;

@Bean
publicTestBeantestBean(){
TestBeantestBean=newTestBean();
testBean.setName(env.getProperty("testbean.name"));
returntestBean;
}
}

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")
publicclassAppConfig{
@Autowired
Environmentenv;

@Bean
publicTestBeantestBean(){
TestBeantestBean=newTestBean();
testBean.setName(env.getProperty("testbean.name"));
returntestBean;
}
}

3.13.5Placeholder 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 congure 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 dened, as long as it is available in the
Environment :

3.14Registering 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
publicclassAppConfig{

Alternatively for XML conguration use the context:loadtimeweaver element:

Once congured 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 Section7.8.4, Load-time weaving with AspectJ in the Spring Framework.

3.15Additional 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 les, 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 HierarchicalBeanFactory interface.

3.15.1Internationalization 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

StringgetMessage(Stringcode,Object[]args,Stringdefault,Localeloc) : The basic method used to retrieve a message

from the MessageSource . When no message is found for the specied locale, the default message is used. Any arguments passed in
become replacement values, using the MessageFormat functionality provided by the standard library.
StringgetMessage(Stringcode,Object[]args,Localeloc) : Essentially the same as the previous method, but with one
difference: no default message can be specied; if the message cannot be found, a NoSuchMessageException is thrown.
StringgetMessage(MessageSourceResolvableresolvable,Localelocale) : 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 dened 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 nd a parent containing a bean with the same name. If it does, it uses that bean as the
MessageSource . If the ApplicationContext cannot nd any source for messages, an empty DelegatingMessageSource is instantiated in
order to be able to accept calls to the methods dened 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>
<beanid="messageSource"
class="org.springframework.context.support.ResourceBundleMessageSource">
<propertyname="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 dened 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 les are

#informat.properties
message=Alligatorsrock!

#inexceptions.properties
argument.required=The{0}argumentisrequired.

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.

publicstaticvoidmain(String[]args){
MessageSourceresources=newClassPathXmlApplicationContext("beans.xml");
Stringmessage=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 dened in a le called beans.xml , which exists at the root of your classpath. The messageSource
bean denition refers to a number of resource bundles through its basenames property. The three les that are passed in the list to the
basenames property exist as les 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.

<beans>

<!thisMessageSourceisbeingusedinawebapplication>
<beanid="messageSource"class="org.springframework.context.support.ResourceBundleMessageSource">
<propertyname="basename"value="exceptions"/>

<!letsinjecttheaboveMessageSourceintothisPOJO>
<beanid="example"class="com.foo.Example">
<propertyname="messages"ref="messageSource"/>
</bean>

</beans>

publicclassExample{

privateMessageSourcemessages;

publicvoidsetMessages(MessageSourcemessages){
this.messages=messages;
}

publicvoidexecute(){
Stringmessage=this.messages.getMessage("argument.required",
newObject[]{"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 dened previously, if you want to
resolve messages against the British ( enGB ) locale, you would create les 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 specied manually.

# in exceptions_en_GB.properties
argument.required=Ebagum lad, the {0} argument is required, I say, required.

publicstaticvoidmain(finalString[]args){
MessageSourceresources=newClassPathXmlApplicationContext("beans.xml");
Stringmessage=resources.getMessage("argument.required",
newObject[]{"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 dened. Any bean that is
dened in an ApplicationContext that implements the MessageSourceAware interface is injected with the application contexts
MessageSource when the bean is created and congured.

As an alternative to ResourceBundleMessageSource , Spring provides a ReloadableResourceBundleMessageSource class.

This variant supports the same bundle le format but is more exible than the standard JDK based
ResourceBundleMessageSource implementation. In particular, it allows for reading les from any Spring resource location (not
just from the classpath) and supports hot reloading of bundle property les (while efciently caching them in between). Check out
the ReloadableResourceBundleMessageSource javadocs for details.

3.15.2Standard 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 notied. Essentially, this is the standard Observer design pattern.

As of Spring 4.2, the event infrastructure has been signicantly 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

Spring provides the following standard events:

Table3.7.Built-in Events

Event Explanation

ContextRefreshedEvent 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 congured 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. "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-specic 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:

publicclassBlackListEventextendsApplicationEvent{

privatefinalStringaddress;
privatefinalStringtest;

publicBlackListEvent(Objectsource,Stringaddress,Stringtest){
super(source);
this.address=address;
this.test=test;
}

//accessorandothermethods...

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:

publicclassEmailServiceimplementsApplicationEventPublisherAware{

privateList<String>blackList;
privateApplicationEventPublisherpublisher;

publicvoidsetBlackList(List<String>blackList){
this.blackList=blackList;
}

publicvoidsetApplicationEventPublisher(ApplicationEventPublisherpublisher){

publicvoidsendEmail(Stringaddress,Stringtext){
if(blackList.contains(address)){
BlackListEventevent=newBlackListEvent(this,address,text);
publisher.publishEvent(event);
return;
}
//sendemail...
}

At conguration 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:

publicclassBlackListNotifierimplementsApplicationListener<BlackListEvent>{

privateStringnotificationAddress;

publicvoidsetNotificationAddress(StringnotificationAddress){
this.notificationAddress=notificationAddress;
}

publicvoidonApplicationEvent(BlackListEventevent){
//notifyappropriatepartiesvianotificationAddress...
}

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 nished 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 denitions used to register and congure each of the classes above:

<beanid="emailService"class="example.EmailService">
<propertyname="blackList">
<list>
<value>[email protected]</value>
<value>[email protected]</value>
<value>[email protected]</value>
</list>
</property>
</bean>

<beanid="blackListNotifier"class="example.BlackListNotifier">
<propertyname="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

publicclassBlackListNotifier{

privateStringnotificationAddress;

publicvoidsetNotificationAddress(StringnotificationAddress){
this.notificationAddress=notificationAddress;
}

@EventListener
publicvoidprocessBlackListEvent(BlackListEventevent){
//notifyappropriatepartiesvianotificationAddress...
}

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 lter on.

If your method should listen to several events or if you want to dene it with no parameter at all, the event type(s) can also be specied on the
annotation itself:

@EventListener({ContextStartedEvent.class,ContextRefreshedEvent.class})
publicvoidhandleContextStart(){

It is also possible to add additional runtime ltering via the condition attribute of the annotation that denes a SpEL expression that should
match to actually invoke the method for a particular event.

For instance, our notier can be rewritten to be only invoked if the test attribute of the event is equal to foo :

@EventListener(condition="#blEvent.test=='foo'")
publicvoidprocessBlackListEvent(BlackListEventblEvent){
//notifyappropriatepartiesvianotificationAddress...
}

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:

Table3.8.Event SpEL available metadata

Name Location Description Example

Event root object The actual ApplicationEvent #root.event

Arguments root object The arguments (as array) used for invoking the target #root.args[0]
array

Argument evaluation Name of any of the method arguments. If for some reason the names are not #blEvent or #a0 (one
name context available (e.g. no debug information), the argument names are also available can also use #p0 or
under the #a<#arg> where #arg stands for the argument index (starting from #p<#arg> notation as an
0). alias).

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
publicListUpdateEventhandleBlackListEvent(BlackListEventevent){
//notifyappropriatepartiesvianotificationAddressand
//thenpublishaListUpdateEvent...
}

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
@Async
publicvoidprocessBlackListEvent(BlackListEventevent){
//BlackListEventisprocessedinaseparatethread
}

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)
publicvoidprocessBlackListEvent(BlackListEventevent){
//notifyappropriatepartiesvianotificationAddress...
}

Generic Events
You may also use generics to further dene 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 denition to only receive EntityCreatedEvent for a Person :

@EventListener
publicvoidonPersonCreated(EntityCreatedEvent<Person>event){
...
}

Due to type erasure, this will only work if the event that is red resolves the generic parameter(s) on which the event listener lters on (that is
something like classPersonCreatedEventextendsEntityCreatedEvent<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 environment provides:

publicclassEntityCreatedEvent<T>
extendsApplicationEventimplementsResolvableTypeProvider{

publicEntityCreatedEvent(Tentity){
super(entity);
}

@Override
publicResolvableTypegetResolvableType(){
returnResolvableType.forClassWithGenerics(getClass(),
ResolvableType.forInstance(getSource()));
}
}

This works not only for ApplicationEvent but any arbitrary object that youd send as an event.

3.15.3Convenient access to low-level 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 lesystem location,
anywhere describable with a standard URL, and some other variations. If the resource location string is a simple path without any special
prexes, where those resources come from is specic and appropriate to the actual application context type.

You can congure 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.

The location path or paths supplied to an ApplicationContext constructor are actually resource strings, and in simple form are treated
appropriately to the specic context implementation. ClassPathXmlApplicationContext treats a simple location path as a classpath
location. You can also use location paths (resource strings) with special prexes to force loading of denitions from the classpath or a URL,
regardless of the actual context type.

3.15.4Convenient 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:

<contextparam>
<paramname>contextConfigLocation</paramname>
<paramvalue>/WEBINF/daoContext.xml/WEBINF/applicationContext.xml</paramvalue>
</contextparam>

<listener>
<listenerclass>org.springframework.web.context.ContextLoaderListener</listenerclass>
</listener>

The listener inspects the contextConfigLocation parameter. If the parameter does not exist, the listener uses
/WEBINF/applicationContext.xml as a default. When the parameter does exist, the listener separates the String by using predened
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 /WEBINF/*Context.xml for all les with names ending with "Context.xml", residing in the
"WEB-INF" directory, and /WEBINF/**/*Context.xml , for all such les in any subdirectory of "WEB-INF".

3.15.5Deploying a Spring ApplicationContext as a Java EE RAR le

It is possible to deploy a Spring ApplicationContext as a RAR le, encapsulating the context and all of its required bean classes and library
JARs in a Java EE RAR deployment unit. This is the equivalent of bootstrapping a standalone ApplicationContext, 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 le, in effect, a WAR le 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 conguration details involved in RAR deployment.

For a simple deployment of a Spring ApplicationContext as a Java EE RAR le: package all application classes into a RAR le, which is a
standard JAR le with a different le extension. Add all required library JARs into the root of the RAR archive. Add a "META-INF/ra.xml"
deployment descriptor (as shown in SpringContextResourceAdapter s JavaDoc) and the corresponding Spring XML bean denition le(s)
(typically "META-INF/applicationContext.xml"), and drop the resulting RAR le 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

3.16The 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, 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.

3.16.1BeanFactory 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 conguration.

The following table lists features provided by the BeanFactory and ApplicationContext interfaces and implementations.

Table3.9.Feature Matrix

Feature BeanFactory ApplicationContext

Bean instantiation/wiring Yes Yes

Automatic BeanPostProcessor registration No Yes

Automatic BeanFactoryPostProcessor registration No Yes

Convenient MessageSource access (for i18n) No Yes

ApplicationEvent publication No Yes

To explicitly register a bean post-processor with a BeanFactory implementation, you need to write code like this:

DefaultListableBeanFactoryfactory=newDefaultListableBeanFactory();
//populatethefactorywithbeandefinitions

//nowregisteranyneededBeanPostProcessorinstances
MyBeanPostProcessorpostProcessor=newMyBeanPostProcessor();
factory.addBeanPostProcessor(postProcessor);

//nowstartusingthefactory

To explicitly register a BeanFactoryPostProcessor when using a BeanFactory implementation, you must write code like this:

DefaultListableBeanFactoryfactory=newDefaultListableBeanFactory();
XmlBeanDefinitionReaderreader=newXmlBeanDefinitionReader(factory);
reader.loadBeanDefinitions(newFileSystemResource("beans.xml"));

//bringinsomepropertyvaluesfromaPropertiesfile
PropertyPlaceholderConfigurercfg=newPropertyPlaceholderConfigurer();
cfg.setLocation(newFileSystemResource("jdbc.properties"));

//nowactuallydothereplacement
cfg.postProcessBeanFactory(factory);

3.16.2Glue code and the evil singleton

It is best to write most application code in a dependency-injection (DI) style, where that 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 benets. 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
les. In this case you should look into using the utility class ContextSingletonBeanFactoryLocator locator that is described in this Spring
team blog entry.

[1] See Background

[2] See Section3.4.1, Dependency Injection

4.Resources

4.1Introduction
Javas standard java.net.URL class and standard handlers for various URL prexes 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 prexes
(similar to existing handlers for prexes such as http: ), this is generally quite complicated, and the URL interface still lacks some desirable
functionality, such as a method to check for the existence of the resource being pointed to.

4.2The Resource interface

Springs Resource interface is meant to be a more capable interface for abstracting access to low-level resources.

publicinterfaceResourceextendsInputStreamSource{

booleanexists();

booleanisOpen();

URLgetURL()throwsIOException;

FilegetFile()throwsIOException;

ResourcecreateRelative(StringrelativePath)throwsIOException;

StringgetFilename();

StringgetDescription();

publicinterfaceInputStreamSource{

InputStreamgetInputStream()throwsIOException;

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 output when working with the resource. This is often the
fully qualied le name or 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 prexes on the String
path, allow the caller to specify that a specic 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.

4.3Built-in Resource implementations

There are a number of Resource implementations that come supplied straight out of the box in Spring:

4.3.1UrlResource
The UrlResource wraps a java.net.URL , and may be used to access any object that is normally accessible via a URL, such as les, an
HTTP target, an FTP target, etc. All URLs have a standardized String representation, such that appropriate standardized prexes are used to
indicate one URL type from another. This includes file: for accessing lesystem 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 string contains a few well-known (to it, that is) prexes such as classpath: , it will create
an appropriate specialized Resource for that prex. However, if it doesnt recognize the prex, it will assume the this is just a standard URL
string, and will create a UrlResource .

4.3.2ClassPathResource
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 le 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 lesystem.
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 prex classpath: on the string path, and create a ClassPathResource in that case.

4.3.3FileSystemResource
This is a Resource implementation for java.io.File handles. It obviously supports resolution as a File , and as a URL .

4.3.4ServletContextResource
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 lesystem. Whether or not its expanded and on the lesystem like this, or accessed directly from the JAR
or somewhere else like a DB (its conceivable) is actually dependent on the Servlet container.

4.3.5InputStreamResource
A Resource implementation for a given InputStream . This should only be used if no specic Resource implementation is applicable. In
particular, prefer ByteArrayResource or any of the le-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.

4.3.6ByteArrayResource
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 .

4.4The ResourceLoader
The ResourceLoader interface is meant to be implemented by objects that can return (i.e. load) Resource instances.

publicinterfaceResourceLoader{

ResourcegetResource(Stringlocation);

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 specic application context, and the location path specied doesnt have a specic prex, 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:

Resourcetemplate=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 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: prex:

Resourcetemplate=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 prexes:

Resourcetemplate=ctx.getResource("file:///some/resource/path/myTemplate.txt");

Resourcetemplate=ctx.getResource("http://myhost.com/resource/path/myTemplate.txt");

The following table summarizes the strategy for converting String s to Resource s:

Table4.1.Resource strings

Prex Example Explanation

classpath: classpath:com/myapp/config.xml Loaded from the classpath.

Prex Example Explanation

le: file:///data/config.xml Loaded as a URL , from the lesystem. [1]

http: http://myserver/logo.png Loaded as a URL .

(none) /data/config.xml Depends on the underlying ApplicationContext .

[1] But see also Section4.7.3, FileSystemResource caveats.

4.5The ResourceLoaderAware interface

The ResourceLoaderAware interface is a special marker interface, identifying objects that expect to be provided with a ResourceLoader
reference.

publicinterfaceResourceLoaderAware{

voidsetResourceLoader(ResourceLoaderresourceLoader);
}

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 Section3.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 exibility (including the ability to autowire elds and multiple parameter methods), consider using the new annotation-based autowiring
features. In that case, the ResourceLoader will be autowired into a eld, constructor argument, or method parameter that is expecting the
ResourceLoader type as long as the eld, constructor, or method in question carries the @Autowired annotation. For more information, see
Section3.9.2, @Autowired.

4.6Resources 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
specic 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 congured with a
simple string for that resource, as follows:

<beanid="myBean"class="...">
<propertyname="template"value="some/resource/path/myTemplate.txt"/>
</bean>

Note that the resource path has no prex, 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 specic Resource type to be used, then a prex may be used. The following two examples show how to force a
ClassPathResource and a UrlResource (the latter being used to access a lesystem le).

<propertyname="template"value="classpath:some/resource/path/myTemplate.txt">

<propertyname="template"value="file:///some/resource/path/myTemplate.txt"/>

4.7Application contexts and Resource paths

4.7.1Constructing application contexts

An application context constructor (for a specic application context type) generally takes a string or array of strings as the location path(s) of
the resource(s) such as XML les that make up the denition of the context.

When such a location path doesnt have a prex, the specic Resource type built from that path and used to load the bean denitions,
depends on and is appropriate to the specic application context. For example, if you create a ClassPathXmlApplicationContext as
follows:

ApplicationContextctx=newClassPathXmlApplicationContext("conf/appContext.xml");

The bean denitions will be loaded from the classpath, as a ClassPathResource will be used. But if you create a
FileSystemXmlApplicationContext as follows:

ApplicationContextctx=
newFileSystemXmlApplicationContext("conf/appContext.xml");

The bean denition will be loaded from a lesystem location, in this case relative to the current working directory.

Note that the use of the special classpath prex or a standard URL prex on the location path will override the default type of Resource
created to load the denition. So this FileSystemXmlApplicationContext

ApplicationContextctx=
newFileSystemXmlApplicationContext("classpath:conf/appContext.xml");

i. will actually load its bean denitions from the classpath. However, it is still a FileSystemXmlApplicationContext . If it is subsequently
used as a ResourceLoader , any unprexed paths will still be treated as lesystem 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 lenames of the XML les 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 dened in the 'services.xml' and 'daos.xml' could be
instantiated like so

ApplicationContextctx=newClassPathXmlApplicationContext(
newString[]{"services.xml","daos.xml"},MessengerService.class);

Please do consult the ClassPathXmlApplicationContext javadocs for details on the various constructors.

4.7.2Wildcards 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*:" prex and/or internal Ant-style regular expressions (matched using Springs
PathMatcher utility). Both of the latter are effectively wildcards

One use for this mechanism is when doing component-style application assembly. All components can 'publish' context denition fragments to a
well-known location path, and when the nal application context is created using the same path prexed via classpath*: , all component
fragments will be picked up automatically.

Note that this wildcarding is specic 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*: prex to construct an actual Resource , as a resource points to just one resource at a time.

Ant-style Patterns

/WEB-INF/*-context.xml
com/mycompany/**/applicationContext.xml
file:C:/some/path/*-context.xml
classpath:com/mycompany/**/applicationContext.xml

The resolver follows a more complex but dened 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-specic 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 lesystem. 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 le to resolve the wildcards.

Implications on portability
If the specied path is already a le URL (either explicitly, or implicitly because the base ResourceLoader is a lesystem one, then wildcarding
is guaranteed to work in a completely portable fashion.

If the specied 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 le at the end) it is actually undened (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 lesystem 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.

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 specic
environment before you rely on it.

The Classpath: portability classpath: prex

When constructing an XML-based application context, a location string may use the special classpath*: prex:

ApplicationContextctx=
newClassPathXmlApplicationContext("classpath*:conf/appContext.xml");

This special prex species that all classpath resources that match the given name must be obtained (internally, this essentially happens via a
) call), and then merged to form the nal application context denition.
ClassLoader.getResources(

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 les. A simple
test to check if classpath* works is to use the classloader to load a le from within a jar on the classpath:
getClass().getClassLoader().getResources("<someFileInsideTheJar>") . Try this test with les 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*: prex can also be combined with a PathMatcher pattern in the rest of the location path, for example
classpath*:METAINF/*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 les reside in the le system. This means that a pattern like classpath*:*.xml will not retrieve les from the
root of jar les but rather only from the root of expanded directories. This originates from a limitation in the JDKs
ClassLoader.getResources() method which only returns le system locations for a passed-in empty string (indicating potential roots to
search).

Ant-style patterns with classpath: resources are not guaranteed to nd 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

4.7.3FileSystemResource 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 lesystem.

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:

ApplicationContextctx=
newFileSystemXmlApplicationContext("conf/context.xml");

ApplicationContextctx=
newFileSystemXmlApplicationContext("/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.)

FileSystemXmlApplicationContextctx=...;
ctx.getResource("some/resource/path/myTemplate.txt");

FileSystemXmlApplicationContextctx=...;
ctx.getResource("/some/resource/path/myTemplate.txt");

In practice, if true absolute lesystem 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 prex.

//actualcontexttypedoesn'tmatter,theResourcewillalwaysbeUrlResource
ctx.getResource("file:///some/resource/path/myTemplate.txt");

//forcethisFileSystemXmlApplicationContexttoloaditsdefinitionviaaUrlResource
ApplicationContextctx=
newFileSystemXmlApplicationContext("file:///conf/context.xml");

5.Validation, Data Binding, and Type Conversion

5.1Introduction

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 Section5.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 Section5.8.3,
Conguring 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. Specically 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 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

Springs DataBinder and the lower-level BeanWrapper both use PropertyEditors to parse and format property values. The PropertyEditor
concept is part of the JavaBeans specication, 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 eld values. These new packages may be used as
simpler alternatives to PropertyEditors, and will also be discussed in this chapter.

5.2Validation 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:

publicclassPerson{

privateStringname;
privateintage;

//theusualgettersandsetters...
}

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

Implementing a Validator is fairly straightforward, especially when you know of the ValidationUtils helper class that the Spring
Framework also provides.

publicclassPersonValidatorimplementsValidator{

/**
*ThisValidatorvalidates*just*Personinstances
*/
publicbooleansupports(Classclazz){
returnPerson.class.equals(clazz);
}

publicvoidvalidate(Objectobj,Errorse){
ValidationUtils.rejectIfEmpty(e,"name","name.empty");
Personp=(Person)obj;
if(p.getAge()<0){
e.rejectValue("age","negativevalue");
}elseif(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 rst 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
dependency-inject or instantiate an AddressValidator within your CustomerValidator , and use it like so:

publicclassCustomerValidatorimplementsValidator{

privatefinalValidatoraddressValidator;

publicCustomerValidator(ValidatoraddressValidator){
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 126/616
2/20/2017 Spring Framework Reference Documentation
if(addressValidator==null){
thrownewIllegalArgumentException("Thesupplied[Validator]is"+
"requiredandmustnotbenull.");
}
if(!addressValidator.supports(Address.class)){
thrownewIllegalArgumentException("Thesupplied[Validator]must"+
"supportthevalidationof[Address]instances.");
}
this.addressValidator=addressValidator;
}

/**
*ThisValidatorvalidatesCustomerinstances,andanysubclassesofCustomertoo
*/
publicbooleansupports(Classclazz){
returnCustomer.class.isAssignableFrom(clazz);
}

publicvoidvalidate(Objecttarget,Errorserrors){
ValidationUtils.rejectIfEmptyOrWhitespace(errors,"firstName","field.required");
ValidationUtils.rejectIfEmptyOrWhitespace(errors,"surname","field.required");
Customercustomer=(Customer)target;
try{
errors.pushNestedPath("address");
ValidationUtils.invokeValidator(this.addressValidator,customer.getAddress(),errors);
}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.

5.3Resolving 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 eld. 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 eld ('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 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 eld name you passed to the reject
method. So in case you reject a eld 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 rst will include the eld name and the second will include the type of the
eld); 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.

5.4Bean 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
specication, 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 .

5.4.1Setting and getting basic and nested properties

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:

Table5.1.Examples of properties

Expression Explanation

name 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 nd 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:

publicclassCompany{

privateStringname;
privateEmployeemanagingDirector;

publicStringgetName(){
returnthis.name;
}

publicvoidsetName(Stringname){
this.name=name;
}

publicEmployeegetManagingDirector(){
returnthis.managingDirector;
}

publicvoidsetManagingDirector(EmployeemanagingDirector){
this.managingDirector=managingDirector;
}
}

publicclassEmployee{

privateStringname;

privatefloatsalary;

publicStringgetName(){
returnthis.name;
}

publicvoidsetName(Stringname){
this.name=name;
}

publicfloatgetSalary(){
returnsalary;

publicvoidsetSalary(floatsalary){
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 :

BeanWrappercompany=newBeanWrapperImpl(newCompany());
//settingthecompanyname..
company.setPropertyValue("name","SomeCompanyInc.");
//...canalsobedonelikethis:
PropertyValuevalue=newPropertyValue("name","SomeCompanyInc.");
company.setPropertyValue(value);

//ok,let'screatethedirectorandtieittothecompany:
BeanWrapperjim=newBeanWrapperImpl(newEmployee());
jim.setPropertyValue("name","JimStravinsky");
company.setPropertyValue("managingDirector",jim.getWrappedInstance());

//retrievingthesalaryofthemanagingDirectorthroughthecompany
Floatsalary=(Float)company.getPropertyValue("managingDirector.salary");

5.4.2Built-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 '20071409' ), 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 specic 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 le, 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 congurable in some fashion, you can of course still register your own variant to override the
default one:

Table5.2.Built-in PropertyEditors

Class Explanation

ByteArrayPropertyEditor 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.

Class Explanation

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
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 dened 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 have the following class and package structure, which would be sufcient for the 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.

publicclassFooBeanInfoextendsSimpleBeanInfo{

publicPropertyDescriptor[]getPropertyDescriptors(){
try{
finalPropertyEditornumberPE=newCustomNumberEditor(Integer.class,true);
PropertyDescriptorageDescriptor=newPropertyDescriptor("age",Foo.class){
publicPropertyEditorcreatePropertyEditor(Objectbean){
returnnumberPE;
};
};
returnnewPropertyDescriptor[]{ageDescriptor};
}
catch(IntrospectionExceptionex){
thrownewError(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 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 specic 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:

packageexample;

publicclassExoticType{

privateStringname;

publicExoticType(Stringname){
this.name=name;
}
}

publicclassDependsOnExoticType{

privateExoticTypetype;

publicvoidsetType(ExoticTypetype){
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:

<beanid="sample"class="example.DependsOnExoticType">
<propertyname="type"value="aNameForExoticType"/>
</bean>

The PropertyEditor implementation could look similar to this:

//convertsstringrepresentationtoExoticTypeobject
packageexample;

publicclassExoticTypeEditorextendsPropertyEditorSupport{

publicvoidsetAsText(Stringtext){
setValue(newExoticType(text.toUpperCase()));
}
}

Finally, we use CustomEditorConfigurer to register the new PropertyEditor with the ApplicationContext , which will then be able to
use it as needed:

<beanclass="org.springframework.beans.factory.config.CustomEditorConfigurer">
<propertyname="customEditors">

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 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:

packagecom.foo.editors.spring;

publicfinalclassCustomPropertyEditorRegistrarimplementsPropertyEditorRegistrar{

publicvoidregisterCustomEditors(PropertyEditorRegistryregistry){

//itisexpectedthatnewPropertyEditorinstancesarecreated
registry.registerCustomEditor(ExoticType.class,newExoticTypeEditor());

//youcouldregisterasmanycustompropertyeditorsasarerequiredhere...
}
}

5.5Spring Type Conversion

Spring 3 introduces a core.convert package that provides a general type conversion system. The system denes 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.

5.5.1Converter SPI
The SPI to implement type conversion logic is simple and strongly typed:

packageorg.springframework.core.convert.converter;

publicinterfaceConverter<S,T>{

Tconvert(Ssource);

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; specically, 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:

packageorg.springframework.core.convert.support;

finalclassStringToIntegerimplementsConverter<String,Integer>{

publicIntegerconvert(Stringsource){
returnInteger.valueOf(source);
}

5.5.2ConverterFactory
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 :

packageorg.springframework.core.convert.converter;

publicinterfaceConverterFactory<S,R>{

<TextendsR>Converter<S,T>getConverter(Class<T>targetType);

Parameterize S to be the type you are converting from and R to be the base type dening 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:

packageorg.springframework.core.convert.support;

finalclassStringToEnumConverterFactoryimplementsConverterFactory<String,Enum>{

privatefinalclassStringToEnumConverter<TextendsEnum>implementsConverter<String,T>{

privateClass<T>enumType;

publicStringToEnumConverter(Class<T>enumType){
this.enumType=enumType;
}

publicTconvert(Stringsource){
return(T)Enum.valueOf(this.enumType,source.trim());
}
}
}

5.5.3GenericConverter
When you require a sophisticated Converter implementation, consider the GenericConverter interface. With a more exible but less strongly
typed signature, a GenericConverter supports converting between multiple source and target types. In addition, a GenericConverter makes
available source and target eld context you can use when implementing your conversion logic. Such context allows a type conversion to be
driven by a eld annotation, or generic information declared on a eld signature.

packageorg.springframework.core.convert.converter;

publicinterfaceGenericConverter{

publicSet<ConvertiblePair>getConvertibleTypes();

Objectconvert(Objectsource,TypeDescriptorsourceType,TypeDescriptortargetType);

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 eld holding the
value being converted. The target TypeDescriptor provides access to the target eld 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 eld 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 eld.

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 specic condition holds true. For example, you might only want to execute a
Converter if a specic annotation is present on the target eld. Or you might only want to execute a Converter if a specic method, such as
a staticvalueOf method, is dened on the target class. ConditionalGenericConverter is the union of the GenericConverter and
ConditionalConverter interfaces that allows you to dene such custom matching criteria:

publicinterfaceConditionalGenericConverter
extendsGenericConverter,ConditionalConverter{

booleanmatches(TypeDescriptorsourceType,TypeDescriptortargetType);

A good example of a ConditionalGenericConverter is an EntityConverter that converts between an persistent entity identier and an entity
reference. Such a EntityConverter might only match if the target entity type declares a static nder method e.g. findAccount(Long) . You
would perform such a nder method check in the implementation of matches(TypeDescriptor,TypeDescriptor) .

5.5.4ConversionService API

packageorg.springframework.core.convert;

publicinterfaceConversionService{

booleancanConvert(Class<?>sourceType,Class<?>targetType);

<T>Tconvert(Objectsource,Class<T>targetType);

booleancanConvert(TypeDescriptorsourceType,TypeDescriptortargetType);

Objectconvert(Objectsource,TypeDescriptorsourceType,TypeDescriptortargetType);

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 congurations.

5.5.5Conguring 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 congure 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 denition with id conversionService :

<beanid="conversionService"
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.

<beanid="conversionService"
class="org.springframework.context.support.ConversionServiceFactoryBean">
<propertyname="converters">
<set>
<beanclass="example.MyCustomConverter"/>
</set>
</property>
</bean>

It is also common to use a ConversionService within a Spring MVC application. See Section18.16.3, Conversion and Formatting in the Spring
MVC chapter.

In certain situations you may wish to apply formatting during conversion. See Section5.6.3, FormatterRegistry SPI for details on using
FormattingConversionServiceFactoryBean .

5.5.6Using a ConversionService programmatically

To work with a ConversionService instance programmatically, simply inject a reference to it like you would for any other bean:

@Service
publicclassMyService{

@Autowired
publicMyService(ConversionServiceconversionService){
this.conversionService=conversionService;

publicvoiddoIt(){
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 instance, you
need to provide a formal denition of the source and target types.

Fortunately, TypeDescriptor provides various options to make that straightforward:

DefaultConversionServicecs=newDefaultConversionService();

List<Integer>input=....
cs.convert(input,
TypeDescriptor.forObject(input),//List<Integer>typedescriptor
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 specic converter to convert from a
Collection of S to a Collection of T , assuming that standard collection handling is appropriate.

5.6Spring Field Formatting

As discussed in the previous section, core.convert is a general-purpose type conversion system. It provides a unied 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 eld values. For
example, when SpEL needs to coerce a Short to a Long to complete an expression.setValue(Objectbean,Objectvalue) 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 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 eld values. The ConversionService provides a unied type conversion API for both SPIs.

5.6.1Formatter SPI
The Formatter SPI to implement eld formatting logic is simple and strongly typed:

packageorg.springframework.format;

publicinterfaceFormatter<T>extendsPrinter<T>,Parser<T>{
}

Where Formatter extends from the Printer and Parser building-block interfaces:

publicinterfacePrinter<T>{
Stringprint(TfieldValue,Localelocale);
}

importjava.text.ParseException;

publicinterfaceParser<T>{
Tparse(StringclientValue,Localelocale)throwsParseException;
}

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:

packageorg.springframework.format.datetime;

publicfinalclassDateFormatterimplementsFormatter<Date>{

privateStringpattern;

publicDateFormatter(Stringpattern){
this.pattern=pattern;
}

publicStringprint(Datedate,Localelocale){
if(date==null){
return"";
}
returngetDateFormat(locale).format(date);
}

publicDateparse(Stringformatted,Localelocale)throwsParseException{
if(formatted.length()==0){
returnnull;
}
returngetDateFormat(locale).parse(formatted);
}

protectedDateFormatgetDateFormat(Localelocale){
DateFormatdateFormat=newSimpleDateFormat(this.pattern,locale);
dateFormat.setLenient(false);
returndateFormat;
}

The Spring team welcomes community-driven Formatter contributions; see jira.spring.io to contribute.

5.6.2Annotation-driven Formatting
As you will see, eld formatting can be congured by eld type or annotation. To bind an Annotation to a formatter, implement
AnnotationFormatterFactory:

packageorg.springframework.format;

publicinterfaceAnnotationFormatterFactory<AextendsAnnotation>{

Set<Class<?>>getFieldTypes();

Printer<?>getPrinter(Aannotation,Class<?>fieldType);

Parser<?>getParser(Aannotation,Class<?>fieldType);

Parameterize A to be the eld annotationType you wish to associate formatting logic with, for example
org.springframework.format.annotation.DateTimeFormat . Have getFieldTypes() return the types of elds the annotation may be
used on. Have getPrinter() return a Printer to print the value of an annotated eld. Have getParser() return a Parser to parse a
clientValue for an annotated eld.

The example AnnotationFormatterFactory implementation below binds the @NumberFormat Annotation to a formatter. This annotation allows
either a number style or pattern to be specied:

publicfinalclassNumberFormatAnnotationFormatterFactory
implementsAnnotationFormatterFactory<NumberFormat>{

publicSet<Class<?>>getFieldTypes(){
returnnewHashSet<Class<?>>(asList(newClass<?>[]{
Short.class,Integer.class,Long.class,Float.class,
Double.class,BigDecimal.class,BigInteger.class}));
}

publicPrinter<Number>getPrinter(NumberFormatannotation,Class<?>fieldType){
returnconfigureFormatterFrom(annotation,fieldType);
}

publicParser<Number>getParser(NumberFormatannotation,Class<?>fieldType){
returnconfigureFormatterFrom(annotation,fieldType);
}

privateFormatter<Number>configureFormatterFrom(NumberFormatannotation,
Class<?>fieldType){
if(!annotation.pattern().isEmpty()){
returnnewNumberFormatter(annotation.pattern());
}else{
Stylestyle=annotation.style();
if(style==Style.PERCENT){
returnnewPercentFormatter();
}elseif(style==Style.CURRENCY){
returnnewCurrencyFormatter();
}else{
returnnewNumberFormatter();
}
}
}
}

To trigger formatting, simply annotate elds with @NumberFormat:

publicclassMyModel{

@NumberFormat(style=Style.CURRENCY)
privateBigDecimaldecimal;

Format Annotation API

A portable format annotation API exists in the org.springframework.format.annotation package. Use @NumberFormat to format
java.lang.Number elds. Use @DateTimeFormat to format java.util.Date, java.util.Calendar, java.util.Long, or Joda Time elds.

The example below uses @DateTimeFormat to format a java.util.Date as a ISO Date (yyyy-MM-dd):

publicclassMyModel{

@DateTimeFormat(iso=ISO.DATE)
privateDatedate;

5.6.3FormatterRegistry 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 congured programmatically or declaratively as a Spring bean
using FormattingConversionServiceFactoryBean . Because this implementation also implements ConversionService , it can be directly
congured for use with Springs DataBinder and the Spring Expression Language (SpEL).

Review the FormatterRegistry SPI below:

packageorg.springframework.format;

publicinterfaceFormatterRegistryextendsConverterRegistry{

voidaddFormatterForFieldType(Class<?>fieldType,Printer<?>printer,Parser<?>parser);
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 138/616
2/20/2017 Spring Framework Reference Documentation

voidaddFormatterForFieldType(Class<?>fieldType,Formatter<?>formatter);

voidaddFormatterForFieldType(Formatter<?>formatter);

voidaddFormatterForAnnotation(AnnotationFormatterFactory<?,?>factory);

As shown above, Formatters can be registered by eldType or annotation.

The FormatterRegistry SPI allows you to congure Formatting rules centrally, instead of duplicating such conguration across your Controllers.
For example, you might want to enforce that all Date elds are formatted a certain way, or elds with a specic annotation are formatted in a
certain way. With a shared FormatterRegistry, you dene these rules once and they are applied whenever formatting is needed.

5.6.4FormatterRegistrar SPI
The FormatterRegistrar is an SPI for registering formatters and converters through the FormatterRegistry:

packageorg.springframework.format;

publicinterfaceFormatterRegistrar{

voidregisterFormatters(FormatterRegistryregistry);

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 insufcient. For example when a formatter needs to be indexed under a
specic eld type different from its own <T> or when registering a Printer/Parser pair. The next section provides more information on converter
and formatter registration.

5.6.5Conguring Formatting in Spring MVC

See Section18.16.3, Conversion and Formatting in the Spring MVC chapter.

5.7Conguring a global date & time format

By default, date and time elds that are not annotated with @DateTimeFormat are converted from strings using the DateFormat.SHORT style.
If you prefer, you can change this by dening 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 conguration will register a global ' `yyyyMMdd format. This example does not depend on the Joda Time
library:

@Configuration
publicclassAppConfig{

@Bean
publicFormattingConversionServiceconversionService(){

//UsetheDefaultFormattingConversionServicebutdonotregisterdefaults
DefaultFormattingConversionServiceconversionService=newDefaultFormattingConversionService(false);

//Ensure@NumberFormatisstillsupported
conversionService.addFormatterForFieldAnnotation(newNumberFormatAnnotationFormatterFactory());

//Registerdateconversionwithaspecificglobalformat
DateFormatterRegistrarregistrar=newDateFormatterRegistrar();
registrar.setFormatter(newDateFormatter("yyyyMMdd"));
registrar.registerFormatters(conversionService);

returnconversionService;
}
}

<beanid="conversionService"class="org.springframework.format.support.FormattingConversionServiceFactoryBean">
<propertyname="registerDefaultFormatters"value="false"/>
<propertyname="formatters">
<set>
<beanclass="org.springframework.format.number.NumberFormatAnnotationFormatterFactory"/>
</set>
</property>
<propertyname="formatterRegistrars">
<set>
<beanclass="org.springframework.format.datetime.joda.JodaTimeFormatterRegistrar">
<propertyname="dateFormatter">
<beanclass="org.springframework.format.datetime.joda.DateTimeFormatterFactoryBean"
<propertyname="pattern"value="yyyyMMdd"/>
</bean>
</property>
</bean>
</set>
</property>
</bean>
</beans>

Joda Time provides separate distinct types to represent date , time and datetime values. The dateFormatter ,
timeFormatter and dateTimeFormatter properties of the JodaTimeFormatterRegistrar should be used to congure the
different formats for each type. The DateTimeFormatterFactoryBean provides a convenient way to create formatters.

If you are using Spring MVC remember to explicitly congure 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
'conversionservice' attribute of the mvc:annotationdriven element. See Section18.16.3, Conversion and Formatting for details.

5.8Spring 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 now has support for
declaratively validating @Controller inputs.

5.8.1Overview 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 dene your own custom constraints.

To illustrate, consider a simple PersonForm model with two properties:

publicclassPersonForm{
privateStringname;
privateintage;
}

JSR-303 allows you to dene declarative validation constraints against such properties:

publicclassPersonForm{

@NotNull
@Size(max=64)
privateStringname;

@Min(0)

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 specic 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.

5.8.2Conguring 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 application.

Use the LocalValidatorFactoryBean to congure a default Validator as a Spring bean:

<beanid="validator"
class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean"/>

The basic conguration 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:

importjavax.validation.Validator;

@Service
publicclassMyService{

@Autowired
privateValidatorvalidator;

Inject a reference to org.springframework.validation.Validator if your bean requires the Spring Validation API:

importorg.springframework.validation.Validator;

@Service
publicclassMyService{

@Autowired
privateValidatorvalidator;

Conguring Custom Constraints

Each Bean Validation constraint consists of two parts. First, a @Constraint annotation that declares the constraint and its congurable
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 congures a SpringConstraintValidatorFactory that uses Spring to create

ConstraintValidator instances. This allows your custom ConstraintValidators to benet 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)

importjavax.validation.ConstraintValidator;

publicclassMyConstraintValidatorimplementsConstraintValidator{

@Autowired;
privateFooaDependency;

...
}

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 denition:

<beanclass="org.springframework.validation.beanvalidation.MethodValidationPostProcessor"/>

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 Conguration Options

The default LocalValidatorFactoryBean conguration should prove sufcient for most cases. There are a number of conguration options
for various Bean Validation constructs, from message interpolation to traversal resolution. See the LocalValidatorFactoryBean javadocs for
more information on these options.

5.8.3Conguring a DataBinder
Since Spring 3, a DataBinder instance can be congured with a Validator. Once congured, 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:

Footarget=newFoo();
DataBinderbinder=newDataBinder(target);
binder.setValidator(newFooValidator());

//bindtothetargetobject
binder.bind(propertyValues);

//validatethetargetobject
binder.validate();

//getBindingResultthatincludesanyvalidationerrors
BindingResultresults=binder.getBindingResult();

A DataBinder can also be congured with multiple Validator instances via dataBinder.addValidators and
dataBinder.replaceValidators . This is useful when combining globally congured Bean Validation with a Spring Validator congured
locally on a DataBinder instance. See ???.

5.8.4Spring MVC 3 Validation

See Section18.16.4, Validation in the Spring MVC chapter.

6.Spring Expression Language (SpEL)

6.1Introduction

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 denitions as shown in the section Expression support for dening bean denitions.

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.

6.2Feature Overview
The expression language supports the following functionality

Literal expressions
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 dened functions
Collection projection
Collection selection
Templated expressions

6.3Expression 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'.

ExpressionParserparser=newSpelExpressionParser();
Expressionexp=parser.parseExpression("'HelloWorld'");
Stringmessage=(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 dened expression string.
There are two exceptions that can be thrown, ParseException and EvaluationException when calling parser.parseExpression and
exp.getValue respectively.

As an example of method invocation, we call the concat method on the string literal.

ExpressionParserparser=newSpelExpressionParser();
Expressionexp=parser.parseExpression("'HelloWorld'.concat('!')");
Stringmessage=(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.

ExpressionParserparser=newSpelExpressionParser();

//invokes'getBytes()'
Expressionexp=parser.parseExpression("'HelloWorld'.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 elds may also be accessed.

ExpressionParserparser=newSpelExpressionParser();

//invokes'getBytes().length'
Expressionexp=parser.parseExpression("'HelloWorld'.bytes.length");
intlength=(Integer)exp.getValue();

The Strings constructor can be called instead of using a string literal.

ExpressionParserparser=newSpelExpressionParser();
Expressionexp=parser.parseExpression("newString('helloworld').toUpperCase()");
Stringmessage=exp.getValue(String.class);

Note the use of the generic method public<T>TgetValue(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.

The more common usage of SpEL is to provide an expression string that is evaluated against a specic 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.

//Createandsetacalendar
GregorianCalendarc=newGregorianCalendar();
c.set(1856,7,9);

//Theconstructorargumentsarename,birthday,andnationality.
Inventortesla=newInventor("NikolaTesla",c.getTime(),"Serbian");

ExpressionParserparser=newSpelExpressionParser();
Expressionexp=parser.parseExpression("name");

EvaluationContextcontext=newStandardEvaluationContext(tesla);
Stringname=(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:

/Createandsetacalendar
GregorianCalendarc=newGregorianCalendar();
c.set(1856,7,9);

//Theconstructorargumentsarename,birthday,andnationality.
Inventortesla=newInventor("NikolaTesla",c.getTime(),"Serbian");

ExpressionParserparser=newSpelExpressionParser();
Expressionexp=parser.parseExpression("name");
Stringname=(String)exp.getValue(tesla);

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 possible, rather
than construct a new one for each expression evaluation.

In some cases it can be desirable to use a congured evaluation context and yet still supply a different root object on each call to getValue .
getValue allows both to be specied on the same call. In these situations the root object passed on the call is considered to override any
(which maybe null) specied 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 conguration le,
for example for Spring bean or Spring Web Flow denitions. In this case, the parser, evaluation context, root object and any
predened variables are all set up implicitly, requiring the user to specify nothing other than the expressions.

As a nal introductory example, the use of a boolean operator is shown using the Inventor object in the previous example.

Expressionexp=parser.parseExpression("name=='NikolaTesla'");
booleanresult=exp.getValue(context,Boolean.class);//evaluatestotrue

6.3.1The EvaluationContext interface

The interface EvaluationContext is used when evaluating an expression to resolve properties, methods, elds, and to help perform type
conversion. The out-of-the-box implementation, StandardEvaluationContext , uses reection 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
By default SpEL uses the conversion service available in Spring core ( 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:

classSimple{
publicList<Boolean>booleanList=newArrayList<Boolean>();
}

Simplesimple=newSimple();

simple.booleanList.add(true);

StandardEvaluationContextsimpleContext=newStandardEvaluationContext(simple);

//falseispassedinhereasastring.SpELandtheconversionservicewill
//correctlyrecognizethatitneedstobeaBooleanandconvertit
parser.parseExpression("booleanList[0]").setValue(simpleContext,"false");

//bwillbefalse
Booleanb=simple.booleanList.get(0);

6.3.2Parser conguration
It is possible to congure the SpEL expression parser using a parser conguration object
( org.springframework.expression.spel.SpelParserConfiguration ). The conguration object controls the behavior of some of the

classDemo{
publicList<String>list;
}

//Turnon:
//autonullreferenceinitialization
//autocollectiongrowing
SpelParserConfigurationconfig=newSpelParserConfiguration(true,true);

ExpressionParserparser=newSpelExpressionParser(config);

Expressionexpression=parser.parseExpression("list[3]");

Demodemo=newDemo();

Objecto=expression.getValue(demo);

//demo.listwillnowbearealcollectionof4entries
//EachentryisanewemptyString

It is also possible to congure the behaviour of the SpEL expression compiler.

6.3.3SpEL compilation
Spring Framework 4.1 includes a basic expression compiler. Expressions are usually interpreted which provides a lot of dynamic exibility
during evaluation but does not provide the optimum performance. For occasional expression usage this is ne, 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 y 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 rst interpreted evaluation it will nd 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 iterations, it was taking 75ms to evaluate using only the interpreter and just 3ms using the compiled version of
the expression.

Compiler conguration
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 conguration 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 rst 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

After selecting a mode, use the SpelParserConfiguration to congure the parser:

SpelParserConfigurationconfig=newSpelParserConfiguration(SpelCompilerMode.IMMEDIATE,
this.getClass().getClassLoader());

SpelExpressionParserparser=newSpelExpressionParser(config);

Expressionexpr=parser.parseExpression("payload");

MyMessagemessage=newMyMessage();

Objectpayload=expr.getValue(message);

When specifying the compiler mode it is also possible to specify a classloader (passing null is allowed). Compiled expressions will be dened in
a child classloader created under any that is supplied. It is important to ensure if a classloader is specied it can see all the types involved in the
expression evaluation process. If none is specied then a default classloader will be used (typically the context classloader for the thread that is
running during expression evaluation).

The second way to congure the compiler is for use when SpEL is embedded inside some other component and it may not be possible to
congure via a conguration 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.

6.4Expression support for dening bean denitions

SpEL expressions can be used with XML or annotation-based conguration metadata for dening BeanDefinition s. In both cases the syntax
to dene the expression is of the form #{<expressionstring>} .

6.4.1XML based conguration

A property or constructor-arg value can be set using expressions as shown below.

<beanid="numberGuess"class="org.spring.samples.NumberGuess">
<propertyname="randomNumber"value="#{T(java.lang.Math).random()*100.0}"/>

<!otherproperties>
</bean>

The variable systemProperties is predened, so you can use it in your expressions as shown below. Note that you do not have to prex the
predened variable with the # symbol in this context.

<beanid="taxCalculator"class="org.spring.samples.TaxCalculator">
<propertyname="defaultLocale"value="#{systemProperties['user.region']}"/>

<!otherproperties>
</bean>

You can also refer to other bean properties by name, for example.

<beanid="numberGuess"class="org.spring.samples.NumberGuess">
<propertyname="randomNumber"value="#{T(java.lang.Math).random()*100.0}"/>

<!otherproperties>
</bean>

<beanid="shapeGuess"class="org.spring.samples.ShapeGuess">
<propertyname="initialShapeSeed"value="#{numberGuess.randomNumber}"/>

<!otherproperties>
</bean>

6.4.2Annotation-based conguration
The @Value annotation can be placed on elds, methods and method/constructor parameters to specify a default value.

Here is an example to set the default value of a eld variable.

publicstaticclassFieldValueTestBean

@Value("#{systemProperties['user.region']}")
privateStringdefaultLocale;

publicvoidsetDefaultLocale(StringdefaultLocale){
this.defaultLocale=defaultLocale;
}

publicStringgetDefaultLocale(){
returnthis.defaultLocale;
}

The equivalent but on a property setter method is shown below.

publicstaticclassPropertyValueTestBean

privateStringdefaultLocale;

@Value("#{systemProperties['user.region']}")
publicvoidsetDefaultLocale(StringdefaultLocale){
this.defaultLocale=defaultLocale;
}

publicStringgetDefaultLocale(){
returnthis.defaultLocale;
}

Autowired methods and constructors can also use the @Value annotation.

publicclassSimpleMovieLister{

privateMovieFindermovieFinder;
privateStringdefaultLocale;

@Autowired
publicvoidconfigure(MovieFindermovieFinder,
@Value("#{systemProperties['user.region']}")StringdefaultLocale){
this.movieFinder=movieFinder;
this.defaultLocale=defaultLocale;
}

//...
}

publicclassMovieRecommender{

privateStringdefaultLocale;

privateCustomerPreferenceDaocustomerPreferenceDao;

@Autowired
publicMovieRecommender(CustomerPreferenceDaocustomerPreferenceDao,
@Value("#{systemProperties['user.country']}")StringdefaultLocale){
this.customerPreferenceDao=customerPreferenceDao;

//...
}

6.5Language Reference

6.5.1Literal expressions
The types of literal expressions supported are strings, numeric values (int, real, 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 rather as part of a more complex
expression, for example using a literal on one side of a logical comparison operator.

ExpressionParserparser=newSpelExpressionParser();

//evalsto"HelloWorld"
StringhelloWorld=(String)parser.parseExpression("'HelloWorld'").getValue();

doubleavogadrosNumber=(Double)parser.parseExpression("6.0221415E+23").getValue();

//evalsto2147483647
intmaxValue=(Integer)parser.parseExpression("0x7FFFFFFF").getValue();

booleantrueValue=(Boolean)parser.parseExpression("true").getValue();

ObjectnullValue=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().

6.5.2Properties, 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 Teslas year of birth and
Pupins city of birth the following expressions are used.

//evalsto1856
intyear=(Integer)parser.parseExpression("Birthdate.Year+1900").getValue(context);

Stringcity=(String)parser.parseExpression("placeOfBirth.City").getValue(context);

Case insensitivity is allowed for the rst letter of property names. The contents of arrays and lists are obtained using square bracket notation.

ExpressionParserparser=newSpelExpressionParser();

//InventionsArray
StandardEvaluationContextteslaContext=newStandardEvaluationContext(tesla);

//evaluatesto"Inductionmotor"
Stringinvention=parser.parseExpression("inventions[3]").getValue(
teslaContext,String.class);

//MembersList
StandardEvaluationContextsocietyContext=newStandardEvaluationContext(ieee);

//evaluatesto"NikolaTesla"
Stringname=parser.parseExpression("Members[0].Name").getValue(
societyContext,String.class);

//ListandArraynavigation
//evaluatesto"Wirelesscommunication"
Stringinvention=parser.parseExpression("Members[0].Inventions[6]").getValue(
societyContext,String.class);

//Officer'sDictionary

Inventorpupin=parser.parseExpression("Officers['president']").getValue(
societyContext,Inventor.class);

//evaluatesto"Idvor"
Stringcity=parser.parseExpression("Officers['president'].PlaceOfBirth.City").getValue(
societyContext,String.class);

//settingvalues
parser.parseExpression("Officers['advisors'][0].PlaceOfBirth.Country").setValue(
societyContext,"Croatia");

6.5.3Inline lists
Lists can be expressed directly in an expression using {} notation.

//evaluatestoaJavalistcontainingthefournumbers
Listnumbers=(List)parser.parseExpression("{1,2,3,4}").getValue(context);

ListlistOfLists=(List)parser.parseExpression("{{'a','b'},{'x','y'}}").getValue(context);

{} by itself means an empty list. For performance reasons, if the list is itself entirely composed of xed literals then a constant list is created to
represent the expression, rather than building a new list on each evaluation.

6.5.4Inline Maps
Maps can also be expressed directly in an expression using {key:value} notation.

//evaluatestoaJavamapcontainingthetwoentries
MapinventorInfo=(Map)parser.parseExpression("{name:'Nikola',dob:'10July1856'}").getValue(context);

MapmapOfMaps=(Map)parser.parseExpression("{name:{first:'Nikola',last:'Tesla'},dob:{day:10,month:'July',year:1856}}").getValue(con

{:} by itself means an empty map. For performance reasons, if the map is itself composed of xed 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.

6.5.5Array 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("newint[4]").getValue(context);

//Arraywithinitializer
int[]numbers2=(int[])parser.parseExpression("newint[]{1,2,3}").getValue(context);

//Multidimensionalarray
int[][]numbers3=(int[][])parser.parseExpression("newint[4][5]").getValue(context);

It is not currently allowed to supply an initializer when constructing a multi-dimensional array.

6.5.6Methods
Methods are invoked using typical Java programming syntax. You may also invoke methods on literals. Varargs are also supported.

//stringliteral,evaluatesto"bc"
Stringc=parser.parseExpression("'abc'.substring(2,3)").getValue(String.class);

//evaluatestotrue
booleanisMember=parser.parseExpression("isMember('MihajloPupin')").getValue(
societyContext,Boolean.class);

6.5.7Operators

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.

//evaluatestotrue
booleantrueValue=parser.parseExpression("2==2").getValue(Boolean.class);

//evaluatestofalse
booleanfalseValue=parser.parseExpression("2<5.0").getValue(Boolean.class);

//evaluatestotrue
booleantrueValue=parser.parseExpression("'black'<'block'").getValue(Boolean.class);

Greater/less-than comparisons against null follow a simple rule: null is treated as nothing here (i.e. NOT as zero). As a
consequence, any other value is always greater than null ( X>null is always true ) and no other value is ever less than
nothing ( X<null is always false ).
If you prefer numeric comparisons instead, please avoid number-based null comparisons in favor of comparisons against zero
(e.g. X>0 or X<0 ).

In addition to standard relational operators SpEL supports the instanceof and regular expression based matches operator.

//evaluatestofalse
booleanfalseValue=parser.parseExpression(
"'xyz'instanceofT(Integer)").getValue(Boolean.class);

//evaluatestotrue
booleantrueValue=parser.parseExpression(
"'5.00'matches'\^?\\d+(\\.\\d{2})?$'").getValue(Boolean.class);

//evaluatestofalse
booleanfalseValue=parser.parseExpression(
"'5.0067'matches'\^?\\d+(\\.\\d{2})?$'").getValue(Boolean.class);

Be careful with primitive types as they are immediately boxed up to the wrapper type, so 1instanceofT(int) evaluates to
false while 1instanceofT(Integer) evaluates to true , as expected.

Each symbolic operator can also be specied 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

//evaluatestofalse
booleanfalseValue=parser.parseExpression("trueandfalse").getValue(Boolean.class);

//evaluatestotrue
Stringexpression="isMember('NikolaTesla')andisMember('MihajloPupin')";
booleantrueValue=parser.parseExpression(expression).getValue(societyContext,Boolean.class);

//OR

//evaluatestotrue
booleantrueValue=parser.parseExpression("trueorfalse").getValue(Boolean.class);

//evaluatestotrue
Stringexpression="isMember('NikolaTesla')orisMember('AlbertEinstein')";
booleantrueValue=parser.parseExpression(expression).getValue(societyContext,Boolean.class);

//NOT

//evaluatestofalse
booleanfalseValue=parser.parseExpression("!true").getValue(Boolean.class);

//ANDandNOT
Stringexpression="isMember('NikolaTesla')and!isMember('MihajloPupin')";
booleanfalseValue=parser.parseExpression(expression).getValue(societyContext,Boolean.class);

Mathematical operators
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
inttwo=parser.parseExpression("1+1").getValue(Integer.class);//2

StringtestString=parser.parseExpression(
"'test'+''+'string'").getValue(String.class);//'teststring'

//Subtraction
intfour=parser.parseExpression("13").getValue(Integer.class);//4

doubled=parser.parseExpression("1000.001e4").getValue(Double.class);//9000

//Multiplication
intsix=parser.parseExpression("2*3").getValue(Integer.class);//6

doubletwentyFour=parser.parseExpression("2.0*3e0*4").getValue(Double.class);//24.0

//Division
intminusTwo=parser.parseExpression("6/3").getValue(Integer.class);//2

doubleone=parser.parseExpression("8.0/4e0/2").getValue(Double.class);//1.0

//Modulus
intthree=parser.parseExpression("7%4").getValue(Integer.class);//3

intone=parser.parseExpression("8/5%2").getValue(Integer.class);//1

//Operatorprecedence
intminusTwentyOne=parser.parseExpression("1+23*8").getValue(Integer.class);//21

6.5.8Assignment
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 .

Inventorinventor=newInventor();
StandardEvaluationContextinventorContext=newStandardEvaluationContext(inventor);

parser.parseExpression("Name").setValue(inventorContext,"AlexanderSeovic2");

//alternatively

Stringaleks=parser.parseExpression(
"Name='AlexandarSeovic'").getValue(inventorContext,String.class);

6.5.9Types
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 nd 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 qualied, but all other
type references must be.

ClassdateClass=parser.parseExpression("T(java.util.Date)").getValue(Class.class);

ClassstringClass=parser.parseExpression("T(String)").getValue(Class.class);

6.5.10Constructors
Constructors can be invoked using the new operator. The fully qualied class name should be used for all but the primitive type and String
(where int, oat, etc, can be used).

Inventoreinstein=p.parseExpression(
"neworg.spring.samples.spel.inventor.Inventor('AlbertEinstein','German')")
.getValue(Inventor.class);

//createnewinventorinstancewithinaddmethodofList
p.parseExpression(
"Members.add(neworg.spring.samples.spel.inventor.Inventor(
'AlbertEinstein','German'))").getValue(societyContext);

6.5.11Variables
Variables can be referenced in the expression using the syntax #variableName . Variables are set using the method setVariable on the
StandardEvaluationContext .

Inventortesla=newInventor("NikolaTesla","Serbian");
StandardEvaluationContextcontext=newStandardEvaluationContext(tesla);
context.setVariable("newName","MikeTesla");

parser.parseExpression("Name=#newName").getValue(context);

System.out.println(tesla.getName())//"MikeTesla"

The #this and #root variables

The variable #this is always dened and refers to the current evaluation object (against which unqualied references are resolved). The variable
#root is always dened and refers to the root context object. Although #this may vary as components of an expression are evaluated, #root
always refers to the root.

//createanarrayofintegers
List<Integer>primes=newArrayList<Integer>();
primes.addAll(Arrays.asList(2,3,5,7,11,13,17));

//createparserandsetvariable'primes'asthearrayofintegers
ExpressionParserparser=newSpelExpressionParser();
StandardEvaluationContextcontext=newStandardEvaluationContext();
context.setVariable("primes",primes);

//allprimenumbers>10fromthelist(usingselection?{...})
//evaluatesto[11,13,17]
List<Integer>primesGreaterThanTen=(List<Integer>)parser.parseExpression(
"#primes.?[#this>10]").getValue(context);

6.5.12Functions
You can extend SpEL by registering user dened functions that can be called within the expression string. The function is registered with the
StandardEvaluationContext using the method.

publicvoidregisterFunction(Stringname,Methodm)

A reference to a Java Method provides the implementation of the function. For example, a utility method to reverse a string is shown below.

publicabstractclassStringUtils{

publicstaticStringreverseString(Stringinput){
StringBuilderbackwards=newStringBuilder();
for(inti=0;i<input.length();i++)
backwards.append(input.charAt(input.length()1i));
}
returnbackwards.toString();
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 153/616
2/20/2017 Spring Framework Reference Documentation
}
}

This method is then registered with the evaluation context and can be used within an expression string.

ExpressionParserparser=newSpelExpressionParser();
StandardEvaluationContextcontext=newStandardEvaluationContext();

context.registerFunction("reverseString",
StringUtils.class.getDeclaredMethod("reverseString",newClass[]{String.class}));

StringhelloWorldReversed=parser.parseExpression(
"#reverseString('hello')").getValue(context,String.class);

6.5.13Bean references
If the evaluation context has been congured with a bean resolver it is possible to lookup beans from an expression using the (@) symbol.

ExpressionParserparser=newSpelExpressionParser();
StandardEvaluationContextcontext=newStandardEvaluationContext();
context.setBeanResolver(newMyBeanResolver());

//Thiswillendupcallingresolve(context,"foo")onMyBeanResolverduringevaluation
Objectbean=parser.parseExpression("@foo").getValue(context);

To access a factory bean itself, the bean name should instead be prexed with a (&) symbol.

ExpressionParserparser=newSpelExpressionParser();
StandardEvaluationContextcontext=newStandardEvaluationContext();
context.setBeanResolver(newMyBeanResolver());

//Thiswillendupcallingresolve(context,"&foo")onMyBeanResolverduringevaluation
Objectbean=parser.parseExpression("&foo").getValue(context);

6.5.14Ternary Operator (If-Then-Else)

You can use the ternary operator for performing if-then-else conditional logic inside the expression. A minimal example is:

StringfalseString=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","NikolaTesla");

expression="isMember(#queryName)?#queryName+'isamemberofthe'"+
"+Name+'Society':#queryName+'isnotamemberofthe'+Name+'Society'";

StringqueryResultString=parser.parseExpression(expression)
.getValue(societyContext,String.class);
//queryResultString="NikolaTeslaisamemberoftheIEEESociety"

Also see the next section on the Elvis operator for an even shorter syntax for the ternary operator.

6.5.15The 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:

Stringname="ElvisPresley";
StringdisplayName=name!=null?name:"Unknown";

Instead you can use the Elvis operator, named for the resemblance to Elvis' hair style.

ExpressionParserparser=newSpelExpressionParser();

Stringname=parser.parseExpression("name?:'Unknown'").getValue(String.class);

System.out.println(name);//'Unknown'

Here is a more complex example.

ExpressionParserparser=newSpelExpressionParser();

Inventortesla=newInventor("NikolaTesla","Serbian");
StandardEvaluationContextcontext=newStandardEvaluationContext(tesla);

Stringname=parser.parseExpression("Name?:'ElvisPresley'").getValue(context,String.class);

System.out.println(name);//NikolaTesla

tesla.setName(null);

name=parser.parseExpression("Name?:'ElvisPresley'").getValue(context,String.class);

System.out.println(name);//ElvisPresley

6.5.16Safe 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.

ExpressionParserparser=newSpelExpressionParser();

Inventortesla=newInventor("NikolaTesla","Serbian");
tesla.setPlaceOfBirth(newPlaceOfBirth("Smiljan"));

StandardEvaluationContextcontext=newStandardEvaluationContext(tesla);

Stringcity=parser.parseExpression("PlaceOfBirth?.City").getValue(context,String.class);
System.out.println(city);//Smiljan

tesla.setPlaceOfBirth(null);

city=parser.parseExpression("PlaceOfBirth?.City").getValue(context,String.class);

System.out.println(city);//nulldoesnotthrowNullPointerException!!!

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 dened or 25 if not.

6.5.17Collection Selection
Selection is a powerful expression language feature that allows you to transform some source collection into another by selecting from its
entries.

Selection uses the syntax .?[selectionExpression] . This will lter 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.

MapnewMap=parser.parseExpression("map.?[value<27]").getValue();

In addition to returning all the selected elements, it is possible to retrieve just the rst or the last value. To obtain the rst entry matching the
selection the syntax is ^[
] whilst to obtain the last matching selection the syntax is $[
].
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 155/616
2/20/2017 Spring Framework Reference Documentation

6.5.18Collection 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']
ListplacesOfBirth=(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.

6.5.19Expression templating
Expression templates allow a mixing of literal text with one or more evaluation blocks. Each evaluation block is delimited with prex and sufx
characters that you can dene, a common choice is to use #{} as the delimiters. For example,

StringrandomPhrase=parser.parseExpression(
"randomnumberis#{T(java.lang.Math).random()}",
newTemplateParserContext()).getValue(String.class);

//evaluatesto"randomnumberis0.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 inuence how the expression is parsed in order to support the expression
templating functionality. The denition of TemplateParserContext is shown below.

publicclassTemplateParserContextimplementsParserContext{

publicStringgetExpressionPrefix(){
return"#{";
}

publicStringgetExpressionSuffix(){
return"}";
}

publicbooleanisTemplate(){
returntrue;
}
}

6.6Classes used in the examples

Inventor.java

packageorg.spring.samples.spel.inventor;

importjava.util.Date;
importjava.util.GregorianCalendar;

publicclassInventor{

privateStringname;
privateStringnationality;
privateString[]inventions;
privateDatebirthdate;
privatePlaceOfBirthplaceOfBirth;

publicInventor(Stringname,Stringnationality){
GregorianCalendarc=newGregorianCalendar();
this.name=name;
this.nationality=nationality;
this.birthdate=c.getTime();
}

publicInventor(Stringname,Datebirthdate,Stringnationality){

publicInventor(){
}

publicStringgetName(){
returnname;
}

publicvoidsetName(Stringname){
this.name=name;
}

publicStringgetNationality(){
returnnationality;
}

publicvoidsetNationality(Stringnationality){
this.nationality=nationality;
}

publicDategetBirthdate(){
returnbirthdate;
}

publicvoidsetBirthdate(Datebirthdate){
this.birthdate=birthdate;
}

publicPlaceOfBirthgetPlaceOfBirth(){
returnplaceOfBirth;
}

publicvoidsetPlaceOfBirth(PlaceOfBirthplaceOfBirth){
this.placeOfBirth=placeOfBirth;
}

publicvoidsetInventions(String[]inventions){
this.inventions=inventions;
}

publicString[]getInventions(){
returninventions;
}
}

PlaceOfBirth.java

packageorg.spring.samples.spel.inventor;

publicclassPlaceOfBirth{

privateStringcity;
privateStringcountry;

publicPlaceOfBirth(Stringcity){
this.city=city;
}

publicPlaceOfBirth(Stringcity,Stringcountry){
this(city);
this.country=country;
}

publicStringgetCity(){
returncity;
}

publicvoidsetCity(Strings){
this.city=s;
}

publicStringgetCountry(){
returncountry;
}

publicvoidsetCountry(Stringcountry){
this.country=country;
}

Society.java

packageorg.spring.samples.spel.inventor;

importjava.util.*;

publicclassSociety{

privateStringname;

publicstaticStringAdvisors="advisors";
publicstaticStringPresident="president";

privateList<Inventor>members=newArrayList<Inventor>();
privateMapofficers=newHashMap();

publicListgetMembers(){
returnmembers;
}

publicMapgetOfficers(){
returnofficers;
}

publicStringgetName(){
returnname;
}

publicvoidsetName(Stringname){
this.name=name;
}

publicbooleanisMember(Stringname){
for(Inventorinventor:members){
if(inventor.getName().equals(name)){
returntrue;
}
}
returnfalse;
}

7.Aspect Oriented Programming with Spring

7.1Introduction
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
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 158/616
2/20/2017 Spring Framework Reference Documentation
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.

7.1.1AOP concepts
Let us begin by dening some central AOP concepts and terminology. These terms are not Spring-specic unfortunately, AOP terminology is
not particularly intuitive; however, it would be even more confusing if Spring used its own terminology.

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 elds 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 ow 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.
After throwing advice: Advice to be executed if a method exits by throwing an exception.
After (nally) 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 specic 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).

7.1.2Spring 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 eld interception could be added without breaking the core Spring AOP APIs. If you need to advise eld
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 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
congured using normal bean denition 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 efciently with Spring AOP, such as advise very ne-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-specic classes and interfaces into your business/domain model. However, in some places the Spring
Framework does give you the option to introduce Spring Framework-specic 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 specic 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 conguration-style approach. The fact that this chapter chooses to introduce the @AspectJ-style approach rst
should not be taken as an indication that the Spring team favors the @AspectJ annotation-style approach over the Spring XML
conguration-style.
See Section7.4, Choosing which AOP declaration style to use for a more complete discussion of the whys and wherefores of
each style.

7.1.3AOP 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 Section7.6.1, Understanding AOP proxies for a thorough examination of
exactly what this implementation detail actually means.

7.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 Section7.8, Using AspectJ
with Spring applications.

7.2.1Enabling @AspectJ Support

To use @AspectJ aspects in a Spring conguration you need to enable Spring support for conguring 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 Spring determines that a
bean is advised by one or more aspects, it will automatically 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 conguration. 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 conguration

To enable @AspectJ support with Java @Configuration add the @EnableAspectJAutoProxy annotation:

@Configuration
@EnableAspectJAutoProxy
publicclassAppConfig{

Enabling @AspectJ Support with XML conguration

To enable @AspectJ support with XML based conguration use the aop:aspectjautoproxy element:

<aop:aspectjautoproxy/>

This assumes that you are using schema support as described in Chapter38, XML Schema-based conguration. See Section38.2.7, the aop
schema for how to import the tags in the aop namespace.

7.2.2Declaring an aspect
With the @AspectJ support enabled, any bean dened 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 congure Spring AOP. The following example shows the minimal denition
required for a not-very-useful aspect:

A regular bean denition in the application context, pointing to a bean class that has the @Aspect annotation:

<beanid="myAspect"class="org.xyz.NotVeryUsefulAspect">
<!configurepropertiesofaspecthereasnormal>
</bean>

And the NotVeryUsefulAspect class denition, annotated with org.aspectj.lang.annotation.Aspect annotation;

packageorg.xyz;
importorg.aspectj.lang.annotation.Aspect;

@Aspect
publicclassNotVeryUsefulAspect{

Aspects (classes annotated with @Aspect ) may have methods and elds 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 conguration, or autodetect them through classpath
scanning - just like any other Spring-managed bean. However, note that the @Aspect annotation is not sufcient for autodetection
in the classpath: For that purpose, you need to add a separate @Component annotation (or alternatively a custom stereotype
annotation that qualies, 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.

7.2.3Declaring 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 denition, and
the pointcut expression is indicated using the @Pointcut annotation (the method serving as the pointcut signature must have a void return
type).

An example will help make this distinction between a pointcut signature and a pointcut expression clear. The following example denes a
pointcut named 'anyOldTransfer' that will match the execution of any method named 'transfer' :

@Pointcut("execution(*transfer(..))")//thepointcutexpression
privatevoidanyOldTransfer(){}//thepointcutsignature

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,handler,adviceexecution,withincode,cflow,cflow
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 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
denition than you will nd 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 denition 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 rst before making a decision.

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, and ! (negated) too.

Please note that the bean PCD is only supported in Spring AOP - and not in native AspectJ weaving. It is a Spring-specic
extension to the standard PCDs that AspectJ denes 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
specic 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**(..))")
privatevoidanyPublicOperation(){}

@Pointcut("within(com.xyz.someapp.trading..*)")
privatevoidinTrading(){}

@Pointcut("anyPublicOperation()&&inTrading()")
privatevoidtradingOperation(){}

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 denitions

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 dening a "SystemArchitecture" aspect that captures common pointcut expressions for this purpose. A typical
such aspect would look as follows:

packagecom.xyz.someapp;

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.Pointcut;

@Aspect
publicclassSystemArchitecture{

/**
*Ajoinpointisintheweblayerifthemethodisdefined
*inatypeinthecom.xyz.someapp.webpackageoranysubpackage
*underthat.
*/
@Pointcut("within(com.xyz.someapp.web..*)")
publicvoidinWebLayer(){}

/**
*Ajoinpointisintheservicelayerifthemethodisdefined
*inatypeinthecom.xyz.someapp.servicepackageoranysubpackage
*underthat.
*/
@Pointcut("within(com.xyz.someapp.service..*)")
publicvoidinServiceLayer(){}

/**
*Ajoinpointisinthedataaccesslayerifthemethodisdefined
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 163/616
2/20/2017 Spring Framework Reference Documentation
*inatypeinthecom.xyz.someapp.daopackageoranysubpackage
*underthat.
*/
@Pointcut("within(com.xyz.someapp.dao..*)")
publicvoidinDataAccessLayer(){}

/**
*Abusinessserviceistheexecutionofanymethoddefinedonaservice
*interface.Thisdefinitionassumesthatinterfacesareplacedinthe
*"service"package,andthatimplementationtypesareinsubpackages.
*
*Ifyougroupserviceinterfacesbyfunctionalarea(forexample,
*inpackagescom.xyz.someapp.abc.serviceandcom.xyz.someapp.def.service)then
*thepointcutexpression"execution(*com.xyz.someapp..service.*.*(..))"
*couldbeusedinstead.
*
*Alternatively,youcanwritetheexpressionusingthe'bean'
*PCD,likeso"bean(*Service)".(Thisassumesthatyouhave
*namedyourSpringservicebeansinaconsistentfashion.)
*/
@Pointcut("execution(*com.xyz.someapp..service.*.*(..))")
publicvoidbusinessService(){}

/**
*Adataaccessoperationistheexecutionofanymethoddefinedona
*daointerface.Thisdefinitionassumesthatinterfacesareplacedinthe
*"dao"package,andthatimplementationtypesareinsubpackages.
*/
@Pointcut("execution(*com.xyz.someapp.dao.*.*(..))")
publicvoiddataAccessOperation(){}

The pointcuts dened 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()"
adviceref="txadvice"/>
</aop:config>

<tx:adviceid="txadvice">
<tx:attributes>
<tx:methodname="*"propagation="REQUIRED"/>
</tx:attributes>
</tx:advice>

The <aop:config> and <aop:advisor> elements are discussed in Section7.3, Schema-based AOP support. The transaction elements are
discussed in Chapter13, 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(modifierspattern?rettypepatterndeclaringtypepattern?namepattern(parampattern)
throwspattern?)

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-qualied type name will match only when the method returns the
given type. The name pattern matches the method name. You can use the * wildcard as all or part of a 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 rst 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 dened by the AccountService interface:

execution(*com.xyz.service.AccountService.*(..))

the execution of any method dened in the service package:

execution(*com.xyz.service.*.*(..))

the execution of any method dened 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)

'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:

@within(org.springframework.transaction.annotation.Transactional)

'@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 cannot be fully
determined from static analysis and a test will be placed in the code to determine if there is an actual match when the code is running). On rst
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 rst. 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 denition. 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 rst 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.

7.2.4Declaring 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:

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.Before;

@Aspect
publicclassBeforeExample{

@Before("com.xyz.myapp.SystemArchitecture.dataAccessOperation()")
publicvoiddoAccessCheck(){
//...
}

If using an in-place pointcut expression we could rewrite the above example as:

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.Before;

@Aspect
publicclassBeforeExample{

@Before("execution(*com.xyz.myapp.dao.*.*(..))")
publicvoiddoAccessCheck(){
//...
}

After returning advice

After returning advice runs when a matched method execution returns normally. It is declared using the @AfterReturning annotation:

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.AfterReturning;

@Aspect
publicclassAfterReturningExample{

@AfterReturning("com.xyz.myapp.SystemArchitecture.dataAccessOperation()")
publicvoiddoAccessCheck(){
//...
}

Note: it is of course possible to have multiple advice declarations, and other 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:

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.AfterReturning;

@Aspect
publicclassAfterReturningExample{

@AfterReturning(
pointcut="com.xyz.myapp.SystemArchitecture.dataAccessOperation()",
returning="retVal")
publicvoiddoAccessCheck(ObjectretVal){
//...
}

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 specied type ( Object in this case, which will match any return value).

After throwing advice

After throwing advice runs when a matched method execution exits by throwing an exception. It is declared using the @AfterThrowing
annotation:

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.AfterThrowing;

@Aspect
publicclassAfterThrowingExample{

@AfterThrowing("com.xyz.myapp.SystemArchitecture.dataAccessOperation()")
publicvoiddoRecoveryActions(){
//...
}

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.

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.AfterThrowing;

@Aspect
publicclassAfterThrowingExample{

@AfterThrowing(
pointcut="com.xyz.myapp.SystemArchitecture.dataAccessOperation()",
throwing="ex")
publicvoiddoRecoveryActions(DataAccessExceptionex){
//...
}

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 specied type ( DataAccessException in this case).

After (nally) advice

After (nally) 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.

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.After;

@Aspect
publicclassAfterFinallyExample{

@After("com.xyz.myapp.SystemArchitecture.dataAccessOperation()")
publicvoiddoReleaseLock(){
//...
}

Around advice
The nal 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 rst 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
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 168/616
2/20/2017 Spring Framework Reference Documentation
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.

importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.Around;
importorg.aspectj.lang.ProceedingJoinPoint;

@Aspect
publicclassAroundExample{

@Around("com.xyz.myapp.SystemArchitecture.businessService()")
publicObjectdoBasicProfiling(ProceedingJoinPointpjp)throwsThrowable{
//startstopwatch
ObjectretVal=pjp.proceed();
//stopstopwatch
returnretVal;
}

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 nd out about the method the advice is
currently advising.

Access to the current JoinPoint

Any advice method may declare as its rst parameter, a parameter of type org.aspectj.lang.JoinPoint (please note that around advice is
required to declare a rst 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 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 rst 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,..)")
publicvoidvalidateAccount(Accountaccount){
//...
}

The args(account,..) part of the pointcut expression serves two purposes: rstly, 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.

@Pointcut("com.xyz.myapp.SystemArchitecture.dataAccessOperation()&&args(account,..)")
privatevoidaccountDataAccessOperation(Accountaccount){}

@Before("accountDataAccessOperation(account)")
publicvoidvalidateAccount(Accountaccount){
//...
}

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 denition of the @Auditable annotation:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public@interfaceAuditable{
AuditCodevalue();
}

And then the advice that matches the execution of @Auditable methods:

@Before("com.xyz.lib.Pointcuts.anyPublicMethod()&&@annotation(auditable)")
publicvoidaudit(Auditableauditable){
AuditCodecode=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:

publicinterfaceSample<T>{
voidsampleGenericMethod(Tparam);
voidsampleGenericCollectionMethod(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)")
publicvoidbeforeSampleMethod(MyTypeparam){
//Adviceimplementation
}

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 dene a pointcut like this:

@Before("execution(*..Sample+.sampleGenericCollectionMethod(*))&&args(param)")
publicvoidbeforeSampleMethod(Collection<MyType>param){
//Adviceimplementation
}

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. Parameter names are not available through Java reection, so Spring AOP uses the following strategies to
determine parameter names:

@Before(value="com.xyz.lib.Pointcuts.anyPublicMethod()&&target(bean)&&@annotation(auditable)",
argNames="bean,auditable")
publicvoidaudit(Objectbean,Auditableauditable){
AuditCodecode=auditable.value();
//...usecodeandbean
}

If the rst 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(auditable)",
argNames="bean,auditable")
publicvoidaudit(JoinPointjp,Objectbean,Auditableauditable){
AuditCodecode=auditable.value();
//...usecode,bean,andjp
}

The special treatment given to the rst 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()")
publicvoidaudit(JoinPointjp){
//...usejp
}

Using the 'argNames' attribute is a little clumsy, so if the 'argNames' attribute has not been specied, 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 information ( 'g:vars' at a minimum). The consequences of compiling with this ag
on are: (1) your code will be slightly easier to understand (reverse engineer), (2) the class le 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 difculties building with this ag 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)")
publicObjectpreProcessQueryPattern(ProceedingJoinPointpjp,
StringaccountHolderNamePattern)throwsThrowable{
StringnewPattern=preProcess(accountHolderNamePattern);
returnpjp.proceed(newObject[]{newPattern});
}

In many cases you will be doing this binding anyway (as in the example above).

Advice ordering

When two pieces of advice dened in different aspects both need to run at the same join point, unless you specify otherwise the order of
execution is undened. 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 dened in the same aspect both need to run at the same join point, the ordering is undened (since there is no way
to retrieve the declaration order via reection 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.

7.2.5Introductions
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
publicclassUsageTracking{

@DeclareParents(value="com.xzy.myapp.service.*+",defaultImpl=DefaultUsageTracked.class)
publicstaticUsageTrackedmixin;

@Before("com.xyz.myapp.SystemArchitecture.businessService()&&this(usageTracked)")
publicvoidrecordUsage(UsageTrackedusageTracked){
usageTracked.incrementUseCount();
}

The interface to be implemented is determined by the type of the annotated eld. 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:

UsageTrackedusageTracked=(UsageTracked)context.getBean("myService");

7.2.6Aspect 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 dene 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())")
publicclassMyAspect{

privateintsomeState;

@Before(com.xyz.myapp.SystemArchitecture.businessService())
publicvoidrecordServiceUsage(){
//...
}

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 rst 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 advice within it executes. As soon as the aspect instance has been created, the advice 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.

7.2.7Example
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 conict 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
publicclassConcurrentOperationExecutorimplementsOrdered{

privatestaticfinalintDEFAULT_MAX_RETRIES=2;

privateintmaxRetries=DEFAULT_MAX_RETRIES;
privateintorder=1;

publicvoidsetMaxRetries(intmaxRetries){
this.maxRetries=maxRetries;
}

publicintgetOrder(){
returnthis.order;
}

publicvoidsetOrder(intorder){
this.order=order;
}

@Around("com.xyz.myapp.SystemArchitecture.businessService()")
publicObjectdoConcurrentOperation(ProceedingJoinPointpjp)throwsThrowable{
intnumAttempts=0;
PessimisticLockingFailureExceptionlockFailureException;
do{
numAttempts++;
try{
returnpjp.proceed();
}
catch(PessimisticLockingFailureExceptionex){
lockFailureException=ex;
}
}while(numAttempts<=this.maxRetries);
throwlockFailureException;
}

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 congured 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.

<aop:aspectjautoproxy/>

<beanid="concurrentOperationExecutor"class="com.xyz.myapp.service.impl.ConcurrentOperationExecutor">
<propertyname="maxRetries"value="3"/>
<propertyname="order"value="100"/>
</bean>

To rene the aspect so that it only retries idempotent operations, we might dene an Idempotent annotation:

@Retention(RetentionPolicy.RUNTIME)
public@interfaceIdempotent{
//markerannotation
}

and use the annotation to annotate the implementation of service operations. The change to the aspect to only retry idempotent operations
simply involves rening the pointcut expression so that only @Idempotent operations match:

@Around("com.xyz.myapp.SystemArchitecture.businessService()&&"+
"@annotation(com.xyz.myapp.service.Idempotent)")
publicObjectdoConcurrentOperation(ProceedingJoinPointpjp)throwsThrowable{
...
}

7.3Schema-based AOP support

If you prefer an XML-based format, then Spring also offers support for dening 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 (Section7.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 springaop schema as described in Chapter38, XML
Schema-based conguration. See Section38.2.7, the aop schema for how to import the tags in the aop namespace.

Within your Spring congurations, 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 conguration). An <aop:config> element can contain pointcut, advisor, and aspect
elements (note these must be declared in that order).

The <aop:config> style of conguration 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.

7.3.1Declaring an aspect
Using the schema support, an aspect is simply a regular Java object dened as a bean in your Spring application context. The state and
behavior is captured in the elds 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:

<aop:config>
<aop:aspectid="myAspect"ref="aBean">
...
</aop:aspect>
</aop:config>

<beanid="aBean"class="...">
...
</bean>

The bean backing the aspect (" `aBean`" in this case) can of course be congured and dependency injected just like any other Spring bean.

7.3.2Declaring a pointcut

A pointcut representing the execution of any business service in the service layer could be dened as follows:

<aop:config>

<aop:pointcutid="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 Section7.2, @AspectJ
support. If you are using the schema based declaration style, you can refer to named pointcuts dened in types (@Aspects) within the pointcut
expression. Another way of dening the above pointcut would be:

<aop:config>

<aop:pointcutid="businessService"
expression="com.xyz.myapp.SystemArchitecture.businessService()"/>

</aop:config>

Assuming you have a SystemArchitecture aspect as described in the section called Sharing common pointcut denitions.

Declaring a pointcut inside an aspect is very similar to declaring a top-level pointcut:

<aop:config>

<aop:aspectid="myAspect"ref="aBean">

<aop:pointcutid="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 denition 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:aspectid="myAspect"ref="aBean">

<aop:pointcutid="businessService"
expression="execution(*com.xyz.myapp.service.*.*(..))&&this(service)"/>

<aop:beforepointcutref="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:

publicvoidmonitor(Objectservice){
...
}

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:aspectid="myAspect"ref="aBean">

<aop:pointcutid="businessService"

<aop:beforepointcutref="businessService"method="monitor"/>

...
</aop:aspect>
</aop:config>

Note that pointcuts dened 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 denition style is thus more limited than that offered by the @AspectJ style.

7.3.3Declaring advice
The same ve 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:aspectid="beforeExample"ref="aBean">

<aop:before
pointcutref="dataAccessOperation"
method="doAccessCheck"/>

...

</aop:aspect>

Here dataAccessOperation is the id of a pointcut dened at the top ( <aop:config> ) level. To dene the pointcut inline instead, replace the
pointcutref attribute with a pointcut attribute:

<aop:aspectid="beforeExample"ref="aBean">

<aop:before
pointcut="execution(*com.xyz.myapp.dao.*.*(..))"
method="doAccessCheck"/>

...

</aop:aspect>

As we noted in the discussion of the @AspectJ style, using named pointcuts can signicantly improve the readability of your code.

The method attribute identies a method ( doAccessCheck ) that provides the body of the advice. This method must be dened 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:aspectid="afterReturningExample"ref="aBean">

<aop:afterreturning
pointcutref="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:aspectid="afterReturningExample"ref="aBean">

<aop:afterreturning
pointcutref="dataAccessOperation"

...

</aop:aspect>

The doAccessCheck method must declare a parameter named retVal . The type of this parameter constrains matching in the same way as
described for @AfterReturning. For example, the method signature may be declared as:

publicvoiddoAccessCheck(ObjectretVal){...

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:aspectid="afterThrowingExample"ref="aBean">

<aop:afterthrowing
pointcutref="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:aspectid="afterThrowingExample"ref="aBean">

<aop:afterthrowing
pointcutref="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:

publicvoiddoRecoveryActions(DataAccessExceptiondataAccessEx){...

After (nally) advice

After (nally) advice runs however a matched method execution exits. It is declared using the after element:

<aop:aspectid="afterFinallyExample"ref="aBean">

<aop:after
pointcutref="dataAccessOperation"
method="doReleaseLock"/>

...

</aop:aspect>

Around advice
The nal 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 rst 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

<aop:aspectid="aroundExample"ref="aBean">

<aop:around
pointcutref="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):

publicObjectdoBasicProfiling(ProceedingJoinPointpjp)throwsThrowable{
//startstopwatch
ObjectretVal=pjp.proceed();
//stopstopwatch
returnretVal;
}

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 argnames
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"
argnames="auditable"/>

The argnames 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.

packagex.y.service;

publicinterfaceFooService{

FoogetFoo(StringfooName,intage);
}

publicclassDefaultFooServiceimplementsFooService{

publicFoogetFoo(Stringname,intage){
returnnewFoo(name,age);
}
}

Next up is the aspect. Notice the fact that the profile(..) method accepts a number of strongly-typed parameters, the rst 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:

packagex.y;

importorg.aspectj.lang.ProceedingJoinPoint;
importorg.springframework.util.StopWatch;

publicclassSimpleProfiler{

publicObjectprofile(ProceedingJoinPointcall,Stringname,intage)throwsThrowable{
StopWatchclock=newStopWatch("Profilingfor'"+name+"'and'"+age+"'");
try{
clock.start(call.toShortString());

Finally, here is the XML conguration that is required to effect the execution of the above advice for a particular join point:

<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:aop="http://www.springframework.org/schema/aop"
xsi:schemaLocation="
http://www.springframework.org/schema/beanshttp://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/aophttp://www.springframework.org/schema/aop/springaop.xsd">

<!thisistheobjectthatwillbeproxiedbySpring'sAOPinfrastructure>
<beanid="fooService"class="x.y.service.DefaultFooService"/>

<!thisistheactualadviceitself>
<beanid="profiler"class="x.y.SimpleProfiler"/>

<aop:config>
<aop:aspectref="profiler">

<aop:pointcutid="theExecutionOfSomeFooServiceMethod"
expression="execution(*x.y.service.FooService.getFoo(String,int))
andargs(name,age)"/>

<aop:aroundpointcutref="theExecutionOfSomeFooServiceMethod"
method="profile"/>

</aop:aspect>
</aop:config>

</beans>

If we had the following driver script, we would get output something like this on standard output:

importorg.springframework.beans.factory.BeanFactory;
importorg.springframework.context.support.ClassPathXmlApplicationContext;
importx.y.service.FooService;

publicfinalclassBoot{

publicstaticvoidmain(finalString[]args)throwsException{
BeanFactoryctx=newClassPathXmlApplicationContext("x/y/plain.xml");
FooServicefoo=(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.

7.3.4Introductions
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:declareparents 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

<aop:aspectid="usageTrackerAspect"ref="usageTracking">

<aop:declareparents
typesmatching="com.xzy.myapp.service.*+"
implementinterface="com.xyz.myapp.service.tracking.UsageTracked"
defaultimpl="com.xyz.myapp.service.tracking.DefaultUsageTracked"/>

<aop:before
pointcut="com.xyz.myapp.SystemArchitecture.businessService()
andthis(usageTracked)"
method="recordUsage"/>

</aop:aspect>

The class backing the usageTracking bean would contain the method:

publicvoidrecordUsage(UsageTrackedusageTracked){
usageTracked.incrementUseCount();
}

The interface to be implemented is determined by implementinterface attribute. The value of the typesmatching 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:

UsageTrackedusageTracked=(UsageTracked)context.getBean("myService");

7.3.5Aspect instantiation models

The only supported instantiation model for schema-dened aspects is the singleton model. Other instantiation models may be supported in
future releases.

7.3.6Advisors
The concept of "advisors" is brought forward from the AOP support dened 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 Section8.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 commonly see it used in conjunction with transactional
advice, which also has its own namespace support in Spring. Heres how it looks:

<aop:config>

<aop:pointcutid="businessService"
expression="execution(*com.xyz.myapp.service.*.*(..))"/>

<aop:advisor
pointcutref="businessService"
adviceref="txadvice"/>

</aop:config>

<tx:adviceid="txadvice">
<tx:attributes>
<tx:methodname="*"propagation="REQUIRED"/>
</tx:attributes>
</tx:advice>

As well as the pointcutref attribute used in the above example, you can also use the pointcut attribute to dene a pointcut expression
inline.

To dene the precedence of an advisor so that the advice can participate in ordering, use the order attribute to dene the Ordered value of
the advisor.

7.3.7Example
Lets see how the concurrent locking failure retry example from Section7.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 conict 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):

publicclassConcurrentOperationExecutorimplementsOrdered{

privatestaticfinalintDEFAULT_MAX_RETRIES=2;

privateintmaxRetries=DEFAULT_MAX_RETRIES;
privateintorder=1;

publicvoidsetMaxRetries(intmaxRetries){
this.maxRetries=maxRetries;
}

publicintgetOrder(){
returnthis.order;
}

publicvoidsetOrder(intorder){
this.order=order;
}

publicObjectdoConcurrentOperation(ProceedingJoinPointpjp)throwsThrowable{
intnumAttempts=0;
PessimisticLockingFailureExceptionlockFailureException;
do{
numAttempts++;
try{
returnpjp.proceed();
}
catch(PessimisticLockingFailureExceptionex){
lockFailureException=ex;
}
}while(numAttempts<=this.maxRetries);
throwlockFailureException;
}

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 congured 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.

The corresponding Spring conguration is:

<aop:config>

<aop:aspectid="concurrentOperationRetry"ref="concurrentOperationExecutor">

<aop:pointcutid="idempotentOperation"
expression="execution(*com.xyz.myapp.service.*.*(..))"/>

<aop:around
pointcutref="idempotentOperation"
method="doConcurrentOperation"/>

</aop:aspect>

</aop:config>

<beanid="concurrentOperationExecutor"
class="com.xyz.myapp.service.impl.ConcurrentOperationExecutor">
<propertyname="maxRetries"value="3"/>
<propertyname="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 rene the aspect so that it only
retries genuinely idempotent operations, by introducing an Idempotent annotation:

@Retention(RetentionPolicy.RUNTIME)
public@interfaceIdempotent{
//markerannotation
}

and using the annotation to annotate the implementation of service operations. The change to the aspect to retry only idempotent operations
simply involves rening the pointcut expression so that only @Idempotent operations match:

<aop:pointcutid="idempotentOperation"
expression="execution(*com.xyz.myapp.service.*.*(..))and
@annotation(com.xyz.myapp.service.Idempotent)"/>

7.4Choosing 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
inuenced by a number of factors including application requirements, development tools, and team familiarity with AOP.

7.4.1Spring 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,
eld 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.

7.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 congure
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
conguration you might want to change independently). With the XML style arguably it is clearer from your conguration 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 conguration le. When using the @AspectJ style there is a single module - 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*()))
publicvoidpropertyAccess(){}

@Pointcut(execution(org.xyz.Account+*(..))

@Pointcut(propertyAccess()&&operationReturningAnAccount())
publicvoidaccountPropertyAccess(){}

In the XML style I can declare the rst two pointcuts:

<aop:pointcutid="propertyAccess"
expression="execution(*get*())"/>

<aop:pointcutid="operationReturningAnAccount"
expression="execution(org.xyz.Account+*(..))"/>

The downside of the XML approach is that you cannot dene the accountPropertyAccess pointcut by combining these denitions.

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 "conguration"
of enterprise services.

7.5Mixing aspect types

It is perfectly possible to mix @AspectJ style aspects using the autoproxying support, schema-dened <aop:aspect> aspects,
<aop:advisor> declared advisors and even proxies and interceptors dened using the Spring 1.2 style in the same conguration. All of these
are implemented using the same underlying support mechanism and will co-exist without any difculty.

7.6Proxying 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 dened 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 proxytargetclass attribute of the <aop:config> element to true:

<aop:configproxytargetclass="true">
<!otherbeansdefinedhere...>
</aop:config>

To force CGLIB proxying when using the @AspectJ autoproxy support, set the 'proxytargetclass' attribute of the
<aop:aspectjautoproxy> element to true :

<aop:aspectjautoproxyproxytargetclass="true"/>

Multiple <aop:config/> sections are collapsed into a single unied auto-proxy creator at runtime, which applies the strongest
proxy settings that any of the <aop:config/> sections (typically from different XML bean denition les) specied. This also
applies to the <tx:annotationdriven/> and <aop:aspectjautoproxy/> elements.
To be clear: using proxytargetclass="true" on <tx:annotationdriven/> , <aop:aspectjautoproxy/> or
<aop:config/> elements will force the use of CGLIB proxies for all three of them.

7.6.1Understanding 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 rst the scenario where you have a plain-vanilla, un-proxied, nothing-special-about-it, straight object reference, as illustrated by the
following code snippet.

publicclassSimplePojoimplementsPojo{

publicvoidfoo(){
//thisnextmethodinvocationisadirectcallonthe'this'reference
this.bar();
}

publicvoidbar(){
//somelogic...
}
}

If you invoke a method on an object reference, the method is invoked directly on that object reference, as can be seen below.

publicclassMain{

publicstaticvoidmain(String[]args){

Pojopojo=newSimplePojo();

//thisisadirectmethodcallonthe'pojo'reference
pojo.foo();
}
}

Things change slightly when the reference that client code has is a proxy. Consider the following diagram and code snippet.

publicclassMain{

publicstaticvoidmain(String[]args){

ProxyFactoryfactory=newProxyFactory(newSimplePojo());
factory.addInterface(Pojo.class);
factory.addAdvice(newRetryAdvice());

Pojopojo=(Pojo)factory.getProxy();

//thisisamethodcallontheproxy!
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 nally reached the target object, the SimplePojo reference in this

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 because it is so horrendous. You can (choke!) totally tie the logic within
your class to Spring AOP by doing this:

publicclassSimplePojoimplementsPojo{

publicvoidfoo(){
//thisworks,but...gah!
((Pojo)AopContext.currentProxy()).bar();
}

publicvoidbar(){
//somelogic...
}
}

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 ies in
the face of AOP. It also requires some additional conguration when the proxy is being created:

publicclassMain{

publicstaticvoidmain(String[]args){

ProxyFactoryfactory=newProxyFactory(newSimplePojo());
factory.adddInterface(Pojo.class);
factory.addAdvice(newRetryAdvice());
factory.setExposeProxy(true);

Pojopojo=(Pojo)factory.getProxy();

//thisisamethodcallontheproxy!
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.

7.7Programmatic creation of @AspectJ Proxies

In addition to declaring aspects in your conguration using either <aop:config> or <aop:aspectjautoproxy> , 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.

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.

//createafactorythatcangenerateaproxyforthegiventargetobject
AspectJProxyFactoryfactory=newAspectJProxyFactory(targetObject);

//addanaspect,theclassmustbean@AspectJaspect
//youcancallthisasmanytimesasyouneedwithdifferentaspects
factory.addAspect(SecurityManager.class);

//youcanalsoaddexistingaspectinstances,thetypeoftheobjectsuppliedmustbean@AspectJaspect
factory.addAspect(usageTracker);

//nowgettheproxyobject...
MyInterfaceTypeproxy=factory.getProxy();

7.8Using 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.

7.8.1Using AspectJ to dependency inject domain objects with Spring

The Spring container instantiates and congures beans dened in your application context. It is also possible to ask a bean factory to congure
a pre-existing object given the name of a bean denition containing the conguration to be applied. The springaspects.jar contains an
annotation-driven aspect that exploits this capability 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 conguration. In the simplest case it can be used just as a marker
annotation:

packagecom.xyz.myapp.domain;

importorg.springframework.beans.factory.annotation.Configurable;

@Configurable
publicclassAccount{
//...
}

When used as a marker interface in this way, Spring will congure new instances of the annotated type ( Account in this case) using a bean
denition (typically prototype-scoped) with the same name as the fully-qualied type name ( com.xyz.myapp.domain.Account ). Since the
default name for a bean is the fully-qualied name of its type, a convenient way to declare the prototype denition is simply to omit the id
attribute:

<beanclass="com.xyz.myapp.domain.Account"scope="prototype">
<propertyname="fundsTransferService"ref="fundsTransferService"/>
</bean>

If you want to explicitly specify the name of the prototype bean denition to use, you can do so directly in the annotation:

packagecom.xyz.myapp.domain;

importorg.springframework.beans.factory.annotation.Configurable;

@Configurable("account")
publicclassAccount{
//...
}

Spring will now look for a bean denition named "account" and use that as the denition to congure new Account instances.

You can also use autowiring to avoid having to specify a dedicated bean denition at all. To have Spring apply autowiring use the autowire
property of the @Configurable 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 eld or method level (see Section3.9, Annotation-based container conguration for further details).

Finally you can enable Spring dependency checking for the object references in the newly created and congured 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 conguration 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 springaspects.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 , congure 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

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 Section7.8.4, Load-time weaving with AspectJ in the
Spring Framework). The AnnotationBeanConfigurerAspect itself needs conguring by Spring (in order to obtain a reference to the bean
factory that is to be used to congure new objects). If you are using Java based conguration simply add @EnableSpringConfigured to any
@Configuration class.

@Configuration
@EnableSpringConfigured
publicclassAppConfig{

If you prefer XML based conguration, the Spring context namespace denes a convenient context:springconfigured element:

<context:springconfigured/>

Instances of @Configurable objects created before the aspect has been congured will result in a message being issued to the debug log
and no conguration of the object taking place. An example might be a bean in the Spring conguration 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 conguration
aspect.

<beanid="myService"
class="com.xzy.myapp.service.MyService"
dependson="org.springframework.beans.factory.aspectj.AnnotationBeanConfigurerAspect">

<!...>

</bean>

Do not activate @Configurable processing through the bean congurer 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 @Congurable objects

One of the goals of the @Configurable support is to enable independent unit testing of domain objects without the difculties associated with
hard-coded lookups. If @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 congured 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 denes the
type. This means that if you dene multiple application contexts within the same classloader hierarchy you need to consider where to dene the
@EnableSpringConfigured bean and where to place springaspects.jar on the classpath.

Consider a typical Spring web-app conguration with a shared parent application context dening common business services and everything
needed to support them, and one child application context per servlet containing denitions 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 dening the @EnableSpringConfigured bean in the shared (parent) application context: this denes the services
that you are likely to want to inject into domain objects. A consequence is that you cannot congure domain objects with references to beans
dened in the child (servlet-specic) contexts using the @Congurable mechanism (probably not something you want to do anyway!).

7.8.2Other Spring aspects for AspectJ

In addition to the @Configurable aspect, springaspects.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 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 species 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, springaspects 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 conguration and transaction management support but dont want to (or cannot) use
annotations, springaspects.jar also contains abstract aspects you can extend to provide your own pointcut denitions. 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 congure all instances of objects dened in the domain model using prototype bean denitions
that match the fully-qualied class names:

publicaspectDomainObjectConfigurationextendsAbstractBeanConfigurerAspect{

publicDomainObjectConfiguration(){
setBeanWiringInfoResolver(newClassNameBeanWiringInfoResolver());
}

//thecreationofanewbean(anyobjectinthedomainmodel)
protectedpointcutbeanCreation(ObjectbeanInstance):
initialization(new(..))&&
SystemArchitecture.inDomainModel()&&
this(beanInstance);

7.8.3Conguring AspectJ aspects using Spring IoC

When using AspectJ aspects with Spring applications, it is natural to both want and expect to be able to congure such aspects using Spring.
The AspectJ runtime itself is responsible for aspect creation, and the means of conguring the AspectJ created aspects via Spring depends on
the AspectJ instantiation model (the perxxx clause) used by the aspect.

The majority of AspectJ aspects are singleton aspects. Conguration of these aspects is very easy: simply create a bean denition referencing
the aspect type as normal, and include the bean attribute 'factorymethod="aspectOf"' . This ensures that Spring obtains the aspect
instance by asking AspectJ for it rather than trying to create an instance itself. For example:

<beanid="profiler"class="com.xyz.profiler.Profiler"
factorymethod="aspectOf">

<propertyname="profilingStrategy"ref="jamonProfilingStrategy"/>
</bean>

Non-singleton aspects are harder to congure: however it is possible to do so by creating prototype bean denitions and using the
@Configurable support from springaspects.jar to congure 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 congured using Spring, then you will need to tell the

<aop:aspectjautoproxy>
<aop:includename="thisBean"/>
<aop:includename="thatBean"/>
</aop:aspectjautoproxy>

Do not be misled by the name of the <aop:aspectjautoproxy/> 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.

7.8.4Load-time weaving with AspectJ in the Spring Framework

Load-time weaving (LTW) refers to the process of weaving AspectJ aspects into an applications class les as they are being loaded into the
Java virtual machine (JVM). The focus of this section is on conguring and using LTW in the specic context of the Spring Framework: this
section is not an introduction to LTW though. For full details on the specics of LTW and conguring 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 ner-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 ne 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 ne-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 modications 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 springagent.jar ). Developers simply
modify one or more les that form the application context to enable load-time weaving instead of relying on administrators who typically are in
charge of the deployment conguration such as the launch script.

Now that the sales pitch is over, let us rst walk through a quick example of AspectJ LTW using Spring, followed by detailed specics about
elements introduced in the following example. For a complete example, please see the Petclinic sample application.

A rst example
Let us assume that you are an application developer who has been tasked with diagnosing the cause of some performance problems in a
system. Rather than break out a proling tool, what we are going to do is switch on a simple proling aspect that will enable us to very quickly
get some performance metrics, so that we can then apply a ner-grained proling tool to that specic area immediately afterwards.

The example presented here uses XML style conguration, it is also possible to congure and use @AspectJ with Java
Conguration. Specically the @EnableLoadTimeWeaving annotation can be used as an alternative to
<context:loadtimeweaver/> (see below for details).

Here is the proling aspect. Nothing too fancy, just a quick-and-dirty time-based proler, using the @AspectJ-style of aspect declaration.

packagefoo;

importorg.aspectj.lang.ProceedingJoinPoint;
importorg.aspectj.lang.annotation.Aspect;
importorg.aspectj.lang.annotation.Around;
importorg.aspectj.lang.annotation.Pointcut;
importorg.springframework.util.StopWatch;
importorg.springframework.core.annotation.Order;

@Aspect
publicclassProfilingAspect{

@Around("methodsToBeProfiled()")
publicObjectprofile(ProceedingJoinPointpjp)throwsThrowable{
StopWatchsw=newStopWatch(getClass().getSimpleName());
try{
sw.start(pjp.getSignature().getName());
returnpjp.proceed();

@Pointcut("execution(public*foo..*.*(..))")
publicvoidmethodsToBeProfiled(){}
}

We will also need to create an METAINF/aop.xml le, to inform the AspectJ weaver that we want to weave our ProfilingAspect into our
classes. This le convention, namely the presence of a le (or les) on the Java classpath called METAINF/aop.xml is standard AspectJ.

<!DOCTYPEaspectjPUBLIC"//AspectJ//DTD//EN""http://www.eclipse.org/aspectj/dtd/aspectj.dtd">
<aspectj>

</aspectj>

Now to the Spring-specic portion of the conguration. We need to congure 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 conguration in one or more METAINF/aop.xml
les into the classes in your application. The good thing is that it does not require a lot of conguration, as can be seen below (there are some
more options that you can specify, but these are detailed later).

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/springcontext.xsd">

<!aserviceobject;wewillbeprofilingitsmethods>
<beanid="entitlementCalculationService"
class="foo.StubEntitlementCalculationService"/>

<!thisswitchesontheloadtimeweaving>
<context:loadtimeweaver/>
</beans>

Now that all the required artifacts are in place - the aspect, the METAINF/aop.xml le, and the Spring conguration -, let us create a simple
driver class with a main(..) method to demonstrate the LTW in action.

packagefoo;

importorg.springframework.context.support.ClassPathXmlApplicationContext;

publicfinalclassMain{

publicstaticvoidmain(String[]args){

ApplicationContextctx=newClassPathXmlApplicationContext("beans.xml",Main.class);

EntitlementCalculationServiceentitlementCalculationService
=(EntitlementCalculationService)ctx.getBean("entitlementCalculationService");

//theprofilingaspectis'woven'aroundthismethodexecution
entitlementCalculationService.calculateEntitlement();
}
}

java -javaagent:C:/projects/foo/lib/global/spring-instrument.jar foo.Main

The javaagent is a ag 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 springinstrument.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 proler 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.

packagefoo;

importorg.springframework.context.support.ClassPathXmlApplicationContext;

publicfinalclassMain{

publicstaticvoidmain(String[]args){

newClassPathXmlApplicationContext("beans.xml",Main.class);

EntitlementCalculationServiceentitlementCalculationService=
newStubEntitlementCalculationService();

//theprofilingaspectwillbe'woven'aroundthismethodexecution
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 proling 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 conguration 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 congured using one or more METAINF/aop.xml les, that are on the Java classpath (either directly, or
more typically in jar les).

The structure and contents of this le 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 le is 100% AspectJ - there is no Spring-specic 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)

springaop.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:

springinstrument.jar

Spring conguration
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 le 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.

Conguring 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 congure a LoadTimeWeaver , which typically is done using the
@EnableLoadTimeWeaving annotation.

@Configuration
@EnableLoadTimeWeaving
publicclassAppConfig{

Alternatively, if you prefer XML based conguration, use the <context:loadtimeweaver/> element. Note that the element is dened in the
context namespace.

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/springcontext.xsd">

<context:loadtimeweaver/>

</beans>

The above conguration will dene and register a number of LTW-specic 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).

Table7.1.DefaultContextLoadTimeWeaver LoadTimeWeavers

Runtime Environment LoadTimeWeaver

implementation

Running in Oracles WebLogic WebLogicLoadTimeWeaver

Running in Oracles GlassFish GlassFishLoadTimeWeaver

Running in Apache Tomcat TomcatLoadTimeWeaver

Runtime Environment LoadTimeWeaver

implementation

Running in Red Hats JBoss AS or WildFly JBossLoadTimeWeaver

Running in IBMs WebSphere WebSphereLoadTimeWeaver

JVM started with Spring InstrumentationSavingAgent (java -javaagent:path/to/spring- InstrumentationLoadTimeWeaver

instrument.jar)

Fallback, expecting the underlying ClassLoader to follow common conventions (e.g. applicable ReflectiveLoadTimeWeaver
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 specic LoadTimeWeaver with Java conguration implement the LoadTimeWeavingConfigurer interface and override the
getLoadTimeWeaver() method:

@Configuration
@EnableLoadTimeWeaving
publicclassAppConfigimplementsLoadTimeWeavingConfigurer{

@Override
publicLoadTimeWeavergetLoadTimeWeaver(){
returnnewReflectiveLoadTimeWeaver();
}
}

If you are using XML based conguration you can specify the fully-qualied classname as the value of the weaverclass attribute on the
<context:loadtimeweaver/> element:

<?xmlversion="1.0"encoding="UTF8"?>
<beansxmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/springbeans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/springcontext.xsd">

<context:loadtimeweaver
weaverclass="org.springframework.instrument.classloading.ReflectiveLoadTimeWeaver"/>

</beans>

The LoadTimeWeaver that is dened and registered by the conguration 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 specics of how the weaving is actually effected is beyond the scope of this section.

There is one nal attribute of the conguration left to discuss: the aspectjWeaving attribute (or aspectjweaving 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.

Table7.2.AspectJ weaving attribute values

Annotation XML Value Explanation

Value

ENABLED on 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 nd at least one METAINF/aop.xml le, then AspectJ weaving is
on, else it is off. This is the default value.

Annotation XML Value Explanation

Value

Environment-specic conguration
This last section contains any additional settings and conguration 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 dene 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 le:

<Contextpath="/myWebApp"docBase="/my/webApp/location">
<Loader
loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/>
</Context>

Apache Tomcat (6.0+) supports several context locations:

server conguration le - $CATALINA_HOME/conf/server.xml

default context conguration - $CATALINA_HOME/conf/context.xml - that affects all deployed web applications
per-web application conguration 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

For efciency, the embedded per-web-app conguration style is recommended because it will impact only applications that use the custom
class loader and does not require any changes to the server conguration. 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 specied 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. Specically, you do not need to
modify the launch script to add javaagent:path/to/springinstrument.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 le named WEBINF/jbossscanning.xml with the following content:

<scanningxmlns="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-specic (but very general) VM agent, org.springframework.instrument{version}.jar (previously named springagent.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

For performance reasons, it is recommended to use this conguration only if your target environment (such as Jetty) does not have (or does not
support) a dedicated LTW.

7.9Further 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).

8.Spring AOP APIs

8.1Introduction
The previous chapter described the Springs support for AOP using @AspectJ and schema-based aspect denitions. 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.

8.2Pointcut API in Spring

Lets look at how Spring handles the crucial pointcut concept.

8.2.1Concepts
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 target advices to particular classes and methods. The
complete interface is shown below:

publicinterfacePointcut{

ClassFiltergetClassFilter();

MethodMatchergetMethodMatcher();

Splitting the Pointcut interface into two parts allows reuse of class and method matching parts, and ne-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:

publicinterfaceClassFilter{

booleanmatches(Classclazz);
}

The MethodMatcher interface is normally more important. The complete interface is shown below:

publicinterfaceMethodMatcher{

booleanmatches(Methodm,ClasstargetClass);

booleanisRuntime();

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.

If possible, try to make pointcuts static, allowing the AOP framework to cache the results of pointcut evaluation when an AOP
proxy is created.

8.2.2Operations 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.

8.2.3AspectJ 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.

8.2.4Convenience pointcut implementations

Spring provides several convenient pointcut implementations. Some can be used out of the box; others are intended to be subclassed in
application-specic pointcuts.

Static pointcuts
Static pointcuts are based on method and target class, and cannot take into account the methods arguments. Static pointcuts are sufcient -
and best - for most usages. Its possible for Spring to evaluate a static pointcut only once, when a method is rst 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

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:

<beanid="settersAndAbsquatulatePointcut"
class="org.springframework.aop.support.JdkRegexpMethodPointcut">
<propertyname="patterns">
<list>
<value>.*set.*</value>
<value>.*absquatulate</value>
</list>
</property>
</bean>

<beanid="settersAndAbsquatulateAdvisor"
class="org.springframework.aop.support.RegexpMethodPointcutAdvisor">
<propertyname="advice">
<refbean="beanNameOfAopAllianceInterceptor"/>
</property>
<propertyname="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 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 controlflow pointcut.

Control ow pointcuts
Spring control ow pointcuts are conceptually similar to AspectJ cow 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 ow pointcut matches the current call stack. For example, it
might re if the join point was invoked by a method in the com.mycompany.web package, or by the SomeCaller class. Control ow pointcuts
are specied using the org.springframework.aop.support.ControlFlowPointcut class.

Control ow pointcuts are signicantly 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.

8.2.5Pointcut 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):

classTestStaticPointcutextendsStaticMethodMatcherPointcut{

publicbooleanmatches(Methodm,ClasstargetClass){
//returntrueifcustomcriteriamatch
}
}

There are also superclasses for dynamic pointcuts.

You can use custom pointcuts with any advice type in Spring 1.0 RC2 and above.

8.2.6Custom 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

8.3Advice API in Spring

Lets now look at how Spring AOP handles advice.

8.3.1Advice 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.

8.3.2Advice 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

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:

publicinterfaceMethodInterceptorextendsInterceptor{

Objectinvoke(MethodInvocationinvocation)throwsThrowable;
}

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:

publicclassDebugInterceptorimplementsMethodInterceptor{

publicObjectinvoke(MethodInvocationinvocation)throwsThrowable{
System.out.println("Before:invocation=["+invocation+"]");
Objectrval=invocation.proceed();
System.out.println("Invocationreturned");
returnrval;
}
}

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-specic way. While there is an
advantage in using the most specic 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 dene pointcut interfaces.

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 MethodBeforeAdvice interface is shown below. (Springs API design would allow for eld before advice, although the usual objects apply
to eld interception and its unlikely that Spring will ever implement it).

publicinterfaceMethodBeforeAdviceextendsBeforeAdvice{

voidbefore(Methodm,Object[]args,Objecttarget)throwsThrowable;
}

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:

publicclassCountingBeforeAdviceimplementsMethodBeforeAdvice{

privateintcount;

publicvoidbefore(Methodm,Object[]args,Objecttarget)throwsThrowable{
++count;
}

publicintgetCount(){
returncount;
}
}

Before advice can be used with any pointcut.

Throws advice
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):

publicclassRemoteThrowsAdviceimplementsThrowsAdvice{

publicvoidafterThrowing(RemoteExceptionex)throwsThrowable{
//Dosomethingwithremoteexception
}
}

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:

publicclassServletThrowsAdviceWithArgumentsimplementsThrowsAdvice{

publicvoidafterThrowing(Methodm,Object[]args,Objecttarget,ServletExceptionex){
//Dosomethingwithallarguments
}
}

The nal 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.

publicstaticclassCombinedThrowsAdviceimplementsThrowsAdvice{

publicvoidafterThrowing(Methodm,Object[]args,Objecttarget,ServletExceptionex){
//Dosomethingwithallarguments
}
}

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 specic 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:

publicinterfaceAfterReturningAdviceextendsAdvice{

voidafterReturning(ObjectreturnValue,Methodm,Object[]args,Objecttarget)
throwsThrowable;
}

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:

publicclassCountingAfterReturningAdviceimplementsAfterReturningAdvice{

privateintcount;

publicvoidafterReturning(ObjectreturnValue,Methodm,Object[]args,Objecttarget)
throwsThrowable{
++count;
}

publicintgetCount(){
returncount;
}
}

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:

publicinterfaceIntroductionInterceptorextendsMethodInterceptor{

booleanimplementsInterface(Classintf);
}

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:

publicinterfaceIntroductionAdvisorextendsAdvisor,IntroductionInfo{

ClassFiltergetClassFilter();

voidvalidateInterfaces()throwsIllegalArgumentException;
}

publicinterfaceIntroductionInfo{

Class[]getInterfaces();
}

There is no MethodMatcher , and hence no Pointcut , associated with introduction advice. Only class ltering is logical.

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 congured
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:

publicinterfaceLockable{
voidlock();
voidunlock();
booleanlocked();
}

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(Classintf) 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 Lockable itself. The superclass automatically picks up
that Lockable can be supported 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.

publicclassLockMixinextendsDelegatingIntroductionInterceptorimplementsLockable{

privatebooleanlocked;

publicvoidlock(){
this.locked=true;
}

publicvoidunlock(){
this.locked=false;
}

publicbooleanlocked(){
returnthis.locked;
}

publicObjectinvoke(MethodInvocationinvocation)throwsThrowable{
if(locked()&&invocation.getMethod().getName().indexOf("set")==0){
thrownewLockedException();
}
returnsuper.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 sufcient. 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 dened as a
prototype): in this case, theres no conguration relevant for a LockMixin , so we simply create it using new .

publicclassLockMixinAdvisorextendsDefaultIntroductionAdvisor{

publicLockMixinAdvisor(){
super(newLockMixin(),Lockable.class);
}
}

We can apply this advisor very simply: it requires no conguration. (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 conguration, like
any other advisor. All proxy creation choices discussed below, including "auto proxy creators," correctly handle introductions and stateful mixins.

8.4Advisor 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 conguration: Spring will automatically create the necessary interceptor chain.

8.5Using 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.

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.

8.5.1Basics
The ProxyFactoryBean , like other Spring FactoryBean implementations, introduces a level of indirection. If you dene a
ProxyFactoryBean with name foo , what objects referencing foo see is not the ProxyFactoryBean instance itself, but an object created
by the ProxyFactoryBeansimplementationofthe`getObject() method. This method will create an AOP proxy wrapping a target
object.

One of the most important benets 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), beneting from all the pluggability provided by Dependency Injection.

8.5.2JavaBean properties

Specify the target you want to proxy.

Specify whether to use CGLIB (see below and also Section8.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 Section8.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.
frozen : if a proxy conguration is frozen , then changes to the conguration are 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 specic 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
Section8.5.3, JDK- and CGLIB-based proxies).
interceptorNames : String array of Advisor , interceptor or other advice names to apply. Ordering is signicant, on a rst come-rst
served basis. That is to say that the rst interceptor in the list will be the rst 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 Section8.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 .

8.5.3JDK- and CGLIB-based proxies

This section serves as the denitive 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 CGLIB-based proxies changed between versions 1.2.x
and 2.0 of Spring. 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 species 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 denition 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 conguration 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 qualied 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 qualied interface names, then a JDK-based
proxy will be created. The created proxy will implement all of the interfaces that were specied in the proxyInterfaces property; if the target

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
signicantly less work, and less prone to typos.

8.5.4Proxying 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 denition in the example below.
An Advisor and an Interceptor used to provide advice.
An AOP proxy bean denition specifying the target object (the personTarget bean) and the interfaces to proxy, along with the advices to
apply.

<beanid="personTarget"class="com.mycompany.PersonImpl">
<propertyname="name"value="Tony"/>
<propertyname="age"value="51"/>
</bean>

<beanid="myAdvisor"class="com.mycompany.MyAdvisor">
<propertyname="someProperty"value="Customstringpropertyvalue"/>
</bean>

<beanid="debugInterceptor"class="org.springframework.aop.interceptor.DebugInterceptor">
</bean>

<beanid="person"
class="org.springframework.aop.framework.ProxyFactoryBean">
<propertyname="proxyInterfaces"value="com.mycompany.Person"/>

<propertyname="target"ref="personTarget"/>
<propertyname="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 signicant.

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 from the
factory; holding a reference isnt sufcient.

The "person" bean denition above can be used in place of a Person implementation, as follows:

Personperson=(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:

<beanid="personUser"class="com.mycompany.PersonUser">
<propertyname="person"><refbean="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
denition is different; the advice is included only for completeness:

<beanid="myAdvisor"class="com.mycompany.MyAdvisor">
<propertyname="someProperty"value="Customstringpropertyvalue"/>
</bean>

<beanid="debugInterceptor"class="org.springframework.aop.interceptor.DebugInterceptor"/>

<beanid="person"class="org.springframework.aop.framework.ProxyFactoryBean">
<propertyname="proxyInterfaces"value="com.mycompany.Person"/>
<!Useinnerbean,notlocalreferencetotarget>
<propertyname="target">
<beanclass="com.mycompany.PersonImpl">
<propertyname="name"value="Tony"/>
<propertyname="age"value="51"/>
</bean>
</property>
<propertyname="interceptorNames">
<list>
<value>myAdvisor</value>
<value>debugInterceptor</value>
</list>
</property>
</bean>

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 denition 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.

8.5.5Proxying 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 congure 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 congures 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.

8.5.6Using 'global' advisors

By appending an asterisk to an interceptor name, all advisors with bean names matching 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:

<beanid="proxy"class="org.springframework.aop.framework.ProxyFactoryBean">
<propertyname="target"ref="service"/>
<propertyname="interceptorNames">
<list>
<value>global*</value>
</list>
</property>
</bean>

<beanid="global_debug"class="org.springframework.aop.interceptor.DebugInterceptor"/>
<beanid="global_performance"class="org.springframework.aop.interceptor.PerformanceMonitorInterceptor"/>

8.6Concise proxy denitions

Especially when dening transactional proxies, you may end up with many similar proxy denitions. The use of parent and child bean
denitions, along with inner bean denitions, can result in much cleaner and more concise proxy denitions.

First a parent, template, bean denition is created for the proxy:

<beanid="txProxyTemplate"abstract="true"
class="org.springframework.transaction.interceptor.TransactionProxyFactoryBean">
<propertyname="transactionManager"ref="transactionManager"/>
<propertyname="transactionAttributes">
<props>
<propkey="*">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 denition,
which wraps the target of the proxy as an inner bean denition, since the target will never be used on its own anyway.

<beanid="myService"parent="txProxyTemplate">
<propertyname="target">
<beanclass="org.springframework.samples.MyServiceImpl">
</bean>
</property>
</bean>

It is of course possible to override properties from the parent template, such as in this case, the transaction propagation settings:

<beanid="mySpecialService"parent="txProxyTemplate">
<propertyname="target">
<beanclass="org.springframework.samples.MySpecialServiceImpl">
</bean>
</property>
<propertyname="transactionAttributes">
<props>
<propkey="get*">PROPAGATION_REQUIRED,readOnly</prop>
<propkey="find*">PROPAGATION_REQUIRED,readOnly</prop>
<propkey="load*">PROPAGATION_REQUIRED,readOnly</prop>
<propkey="store*">PROPAGATION_REQUIRED</prop>
</props>
</property>
</bean>

Note that in the example above, we have explicitly marked the parent bean denition 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 denition which you intend to use only as a
template, and this denition species a class, you must make sure to set the abstract attribute to true, otherwise the application context will
actually try to pre-instantiate it.

8.7Creating 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:

ProxyFactoryfactory=newProxyFactory(myBusinessInterfaceImpl);
factory.addAdvice(myMethodInterceptor);
factory.addAdvisor(myAdvisor);
MyBusinessInterfacetb=(MyBusinessInterface)factory.getProxy();

The rst 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 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.
http://docs.spring.io/spring/docs/5.0.0.M4/spring-framework-reference/htmlsingle/#beans-java 206/616
2/20/2017 Spring Framework Reference Documentation

Integrating AOP proxy creation with the IoC framework is best practice in most applications. We recommend that you externalize
conguration from Java code with AOP, as in general.

8.8Manipulating 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();

voidaddAdvice(Adviceadvice)throwsAopConfigException;

voidaddAdvice(intpos,Adviceadvice)throwsAopConfigException;

voidaddAdvisor(Advisoradvisor)throwsAopConfigException;

voidaddAdvisor(intpos,Advisoradvisor)throwsAopConfigException;

intindexOf(Advisoradvisor);

booleanremoveAdvisor(Advisoradvisor)throwsAopConfigException;

voidremoveAdvisor(intindex)throwsAopConfigException;

booleanreplaceAdvisor(Advisora,Advisorb)throwsAopConfigException;

booleanisFrozen();

The getAdvisors() method will return an Advisor for every advisor, interceptor or other 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:

Advisedadvised=(Advised)myObject;
Advisor[]advisors=advised.getAdvisors();
intoldAdvisorCount=advisors.length;
System.out.println(oldAdvisorCount+"advisors");

//Addanadvicelikeaninterceptorwithoutapointcut
//Willmatchallproxiedmethods
//Canuseforinterceptors,before,afterreturningorthrowsadvice
advised.addAdvice(newDebugInterceptor());

//Addselectiveadviceusingapointcut
advised.addAdvisor(newDefaultPointcutAdvisor(mySpecialPointcut,myAdvice));

assertEquals("Addedtwoadvisors",oldAdvisorCount+2,advised.getAdvisors().length);

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 ag, 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

8.9Using 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 denitions, which can automatically proxy selected bean denitions. This is built on Spring "bean
post processor" infrastructure, which enables modication of any bean denition as the container loads.

In this model, you set up some special bean denitions in your XML bean denition le to congure 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 specic 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.

8.9.1Autoproxy bean denitions

The org.springframework.aop.framework.autoproxy package provides the 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.

<beanclass="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator">
<propertyname="beanNames"value="jdk*,onlyJdk"/>
<propertyname="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 conguration consistently to
multiple objects, with minimal volume of conguration. It is a popular choice for applying declarative transactions to multiple objects.

Bean denitions whose names match, such as "jdkMyBean" and "onlyJdk" in the above example, are plain old bean denitions 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 specic bean names in the auto-proxy advisors bean denition. It offers the same
merit of consistent conguration and avoidance of duplication as BeanNameAutoProxyCreator .

Using this mechanism involves:

Specifying a DefaultAdvisorAutoProxyCreator bean denition.

Specifying any number of Advisors in the same or related contexts. Note that these must be Advisors, not just interceptors or other advices.
This is necessary because there must be a pointcut to evaluate, to check the eligibility of each advice to candidate bean denitions.

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 denitions are added for new business objects, they will automatically be
proxied if necessary.

<beanclass="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator"/>

<beanclass="org.springframework.transaction.interceptor.TransactionAttributeSourceAdvisor">
<propertyname="transactionInterceptor"ref="transactionInterceptor"/>
</bean>

<beanid="customAdvisor"class="com.mycompany.MyAdvisor"/>

<beanid="businessObject1"class="com.mycompany.BusinessObject1">
<!Propertiesomitted>
</bean>

<beanid="businessObject2"class="com.mycompany.BusinessObject2"/>

The DefaultAdvisorAutoProxyCreator is very useful if you want to apply the same advice consistently to many business objects. Once the
infrastructure denitions are in place, you can simply add new business objects without including specic proxy conguration. You can also drop
in additional aspects very easily - for example, tracing or performance monitoring aspects - with minimal change to conguration.

The DefaultAdvisorAutoProxyCreator offers support for ltering (using a naming convention so that only certain advisors are evaluated, allowing
use of multiple, differently congured, 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 congurable order value; the default setting is unordered.

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 denitions offer insufcient customization to the behavior of the framework DefaultAdvisorAutoProxyCreator .

8.9.2Using 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 dening metadata in XML descriptors, conguration 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 specics 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 dening transactional attributes on business objects is sufcient, because of the use of
metadata-aware pointcuts. The bean denitions include the following code, in /WEBINF/declarativeServices.xml . Note that this is
generic, and can be used outside the JPetStore:

<beanclass="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator"/>

<beanclass="org.springframework.transaction.interceptor.TransactionAttributeSourceAdvisor">
<propertyname="transactionInterceptor"ref="transactionInterceptor"/>
</bean>

<beanid="transactionInterceptor"
class="org.springframework.transaction.interceptor.TransactionInterceptor">
<propertyname="transactionManager"ref="transactionManager"/>
<propertyname="transactionAttributeSource">
<beanclass="org.springframework.transaction.interceptor.AttributesTransactionAttributeSource">
<propertyname="attributes"ref="attributes"/>
</bean>
</property>
</bean>

<beanid="attributes"class="org.springframework.metadata.commons.CommonsAttributes"/>

The DefaultAdvisorAutoProxyCreator bean denition (the name is not signicant, hence it can even be omitted) will pick up all eligible
pointcuts in the current application context. In this case, the "transactionAdvisor" bean denition, of type

The /annotation directory of the JPetStore sample application contains an analogous example for auto-proxying driven by JDK 1.5+
annotations. The following conguration enables automatic detection of Springs Transactional annotation, leading to implicit proxies for
beans containing that annotation:

<beanclass="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator"/>

<beanclass="org.springframework.transaction.interceptor.TransactionAttributeSourceAdvisor">
<propertyname="transactionInterceptor"ref="transactionInterceptor"/>
</bean>

<beanid="transactionInterceptor"
class="org.springframework.transaction.interceptor.TransactionInterceptor">
<propertyname="transactionManager"ref="transactionManager"/>
<propertyname="transactionAttributeSource">
<beanclass="org.springframework.transaction.annotation.AnnotationTransactionAttributeSource"/>
</property>
</bean>

The TransactionInterceptor dened here depends on a PlatformTransactionManager denition, which is not included in this generic
le (although it could be) because it will be specic to the applications transaction requirements (typically JTA, as in this example, or Hibernate
or JDBC):

<beanid="transactionManager"
class="org.springframework.transaction.jta.JtaTransactionManager"/>

If you require only declarative transaction management, using these generic XML denitions 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:

Dene 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 dened as prototype, rather than
singleton, bean denitions. For example, the LockMixin introduction interceptor from the Spring test suite, shown above, could be used in
conjunction with a generic DefaultIntroductionAdvisor :

<beanid="lockMixin"class="test.mixin.LockMixin"scope="prototype"/>

<beanid="lockableAdvisor"class="org.springframework.aop.support.DefaultIntroductionAdvisor"
scope="prototype">
<constructorargref="lockMixin"/>
</bean>

Note that both lockMixin and lockableAdvisor are dened as prototypes.

8.10Using 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 instance for each
invocation, using a pool to manage instances.

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).

When using a custom target source, your target will usually need to be a prototype rather than a singleton bean denition. This
allows Spring to create a new target instance when required.

8.10.1Hot 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:

HotSwappableTargetSourceswapper=(HotSwappableTargetSource)beanFactory.getBean("swapper");
ObjectoldTarget=swapper.swap(newTarget);

The XML denitions required look as follows:

<beanid="initialTarget"class="mycompany.OldTarget"/>

<beanid="swapper"class="org.springframework.aop.target.HotSwappableTargetSource">
<constructorargref="initialTarget"/>
</bean>

<beanid="swappable"class="org.springframework.aop.framework.ProxyFactoryBean">
<propertyname="targetSource"ref="swapper"/>
</bean>

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 use a TargetSource - of course any TargetSource
can be used in conjunction with arbitrary advice.

8.10.2Pooling 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 efcient 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 conguration is shown below:

<beanid="businessObjectTarget"class="com.mycompany.MyBusinessObject"
scope="prototype">
...propertiesomitted
</bean>

<beanid="poolTargetSource"class="org.springframework.aop.target.CommonsPool2TargetSource">
<propertyname="targetBeanName"value="businessObjectTarget"/>
<propertyname="maxSize"value="25"/>
</bean>

<beanid="businessObject"class="org.springframework.aop.framework.ProxyFactoryBean">
<propertyname="targetSource"ref="poolTargetSource"/>
<propertyname="interceptorNames"value="myInterceptor"/>
</bean>

In this case, "myInterceptor" is the name of an interceptor that would need to be dened 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 congure Spring so as to be able to cast any pooled object to the org.springframework.aop.target.PoolingConfig
interface, which exposes information about the conguration and current size of the pool through an introduction. Youll need to dene an
advisor like this:

<beanid="poolConfigAdvisor"class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
<propertyname="targetObject"ref="poolTargetSource"/>
<propertyname="targetMethod"value="getPoolingConfigMixin"/>
</bean>

This advisor is obtained by calling a convenience method on the AbstractPoolingTargetSource class, hence the use of
MethodInvokingFactoryBean. This advisors name ("poolCongAdvisor" here) must be in the list of interceptors names in the ProxyFactoryBean
exposing the pooled object.

The cast will look as follows:

PoolingConfigconf=(PoolingConfig)beanFactory.getBean("businessObject");
System.out.println("Maxpoolsizeis"+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.

8.10.3Prototype 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 approach without very good reason.

To do this, you could modify the poolTargetSource denition shown above as follows. (Ive also changed the name, for clarity.)

<beanid="prototypeTargetSource"class="org.springframework.aop.target.PrototypeTargetSource">
<propertyname="targetBeanName"ref="businessObjectTarget"/>
</bean>

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 denition.

8.10.4ThreadLocal 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:

<beanid="threadlocalTargetSource"class="org.springframework.aop.target.ThreadLocalTargetSource">
<propertyname="targetBeanName"value="businessObjectTarget"/>
</bean>

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.

8.11Dening new Advice types

Spring AOP is designed to be extensible. While the interception implementation strategy 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.

8.12Further resources
Please refer to the Spring sample applications for further examples of Spring AOP:

The JPetStores default conguration 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.

PartIII.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.

9.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 benets of the Spring Frameworks support for integration testing. (A thorough treatment of testing in the enterprise is beyond the scope of
this reference manual.)

10.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.

10.1Mock Objects

10.1.1Environment
The org.springframework.mock.env package contains mock implementations of the Environment and PropertySource abstractions
(see Section3.13.1, Bean denition proles and Section3.13.3, PropertySource abstraction). MockEnvironment and
MockPropertySource are useful for developing out-of-container tests for code that depends on environment-specic properties.

10.1.2JNDI

10.1.3Servlet 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 lters. 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 conguration
for Spring MVC, see the Spring MVC Test Framework.

10.2Unit Testing support Classes

10.2.1General 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 reection-based utility methods. Developers use these methods in testing scenarios where they need
to change the value of a constant, set a non- public eld, invoke a non- public setter method, or invoke a non- public conguration 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 eld 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 elds, setter methods, and conguration methods.
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 congured 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 congure expectations on it
and perform verications. For Springs core AOP utilities, see AopUtils and AopProxyUtils .

10.2.2Spring 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 conguration for Spring MVC, use the Spring MVC Test
Framework instead.

11.Integration Testing

11.1Overview
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 rst-class support for integration testing in the springtest module. The name of the actual JAR le might
include the release version and might also be in the long org.springframework.test form, depending on where you get it from (see the
section on Dependency Management for an explanation). This library includes the org.springframework.test package, which contains

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.

11.2Goals 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 xture instances.
To provide transaction management appropriate to integration testing.
To supply Spring-specic base classes that assist developers in writing integration tests.

The next few sections describe each goal and provide links to implementation and conguration details.

11.2.1Context 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 cachin