11/29/13

Reference Documentation

Spring Framework Reference Documentation

3.1 Copyright 2004-2012 Rod Johnson, Juergen Hoeller, Keith Donald, Colin Sampaleanu, Rob Harrop, Alef Arendsen, Thomas Risberg, 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
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. Introduction to Spring Framework 1.1. Dependency Injection and Inversion of Control 1.2. Modules 1.2.1. Core Container 1.2.2. Data Access/Integration 1.2.3. Web 1.2.4. AOP and Instrumentation 1.2.5. Test 1.3. Usage scenarios 1.3.1. Dependency Management and Naming Conventions 1.3.1.1. Spring Dependencies and Depending on Spring 1.3.1.2. Maven Dependency Management 1.3.1.3. Ivy Dependency Management 1.3.2. Logging 1.3.2.1. Not Using Commons Logging 1.3.2.2. Using SLF4J 1.3.2.3. Using Log4J II. What's New in Spring 3 2. New Features and Enhancements in Spring 3.0 2.1. Java 5 2.2. Improved documentation 2.3. New articles and tutorials 2.4. New module organization and build system 2.5. Overview of new features 2.5.1. Core APIs updated for Java 5 2.5.2. Spring Expression Language
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 1/81

11/29/13

Reference Documentation

2.5.3. The Inversion of Control (IoC) container 2.5.3.1. Java based bean metadata 2.5.3.2. Defining bean metadata within components 2.5.4. General purpose type conversion system and field formatting system 2.5.5. The Data Tier 2.5.6. The Web Tier 2.5.6.1. Comprehensive REST support 2.5.6.2. @MVC additions 2.5.7. Declarative model validation 2.5.8. Early support for Java EE 6 2.5.9. Support for embedded databases 3. New Features and Enhancements in Spring 3.1 3.1. Overview of new features 3.1.1. Cache Abstraction 3.1.2. Bean Definition Profiles 3.1.3. Environment Abstraction 3.1.4. PropertySource Abstraction 3.1.5. Code equivalents for Spring's XML namespaces 3.1.6. Support for Hibernate 4.x 3.1.7. TestContext framework support for @Configuration classes and bean definition profiles 3.1.8. c: namespace for more concise constructor injection 3.1.9. Support for injection against non-standard JavaBeans setters 3.1.10. Support for Servlet 3 code-based configuration of Servlet Container 3.1.11. Support for Servlet 3 MultipartResolver 3.1.12. JPA EntityManagerFactory bootstrapping without persistence.xml 3.1.13. New HandlerMethod-based Support Classes For Annotated Controller Processing 3.1.14. "consumes" and "produces" conditions in @RequestMapping 3.1.15. Flash Attributes and RedirectAttributes 3.1.16. URI Template Variable Enhancements 3.1.17. @Valid On @RequestBody Controller Method Arguments 3.1.18. @RequestPart Annotation On Controller Method Arguments 3.1.19. UriComponentsBuilder and UriComponents III. Core Technologies 4. The IoC container 4.1. Introduction to the Spring IoC container and beans 4.2. Container overview 4.2.1. Configuration metadata 4.2.2. Instantiating a container 4.2.2.1. Composing XML-based configuration metadata 4.2.3. Using the container 4.3. Bean overview 4.3.1. Naming beans
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 2/81

11/29/13

Reference Documentation

4.3.1.1. Aliasing a bean outside the bean definition 4.3.2. Instantiating beans 4.3.2.1. Instantiation with a constructor 4.3.2.2. Instantiation with a static factory method 4.3.2.3. Instantiation using an instance factory method 4.4. Dependencies 4.4.1. Dependency injection 4.4.1.1. Constructor-based dependency injection 4.4.1.2. Setter-based dependency injection 4.4.1.3. Dependency resolution process 4.4.1.4. Examples of dependency injection 4.4.2. Dependencies and configuration in detail 4.4.2.1. Straight values (primitives, Strings, and so on) 4.4.2.2. References to other beans (collaborators) 4.4.2.3. Inner beans 4.4.2.4. Collections 4.4.2.5. Null and empty string values 4.4.2.6. XML shortcut with the p-namespace 4.4.2.7. XML shortcut with the c-namespace 4.4.2.8. Compound property names 4.4.3. Using depends-on 4.4.4. Lazy-initialized beans 4.4.5. Autowiring collaborators 4.4.5.1. Limitations and disadvantages of autowiring 4.4.5.2. Excluding a bean from autowiring 4.4.6. Method injection 4.4.6.1. Lookup method injection 4.4.6.2. Arbitrary method replacement 4.5. Bean scopes 4.5.1. The singleton scope 4.5.2. The prototype scope 4.5.3. Singleton beans with prototype-bean dependencies 4.5.4. Request, session, and global session scopes 4.5.4.1. Initial web configuration 4.5.4.2. Request scope 4.5.4.3. Session scope 4.5.4.4. Global session scope 4.5.4.5. Scoped beans as dependencies 4.5.5. Custom scopes 4.5.5.1. Creating a custom scope 4.5.5.2. Using a custom scope 4.6. Customizing the nature of a bean

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

3/81

11/29/13

Reference Documentation

4.6.1. Lifecycle callbacks 4.6.1.1. Initialization callbacks 4.6.1.2. Destruction callbacks 4.6.1.3. Default initialization and destroy methods 4.6.1.4. Combining lifecycle mechanisms 4.6.1.5. Startup and shutdown callbacks 4.6.1.6. Shutting down the Spring IoC container gracefully in non-web applications 4.6.2. ApplicationContextAware and BeanNameAware 4.6.3. Other Aware interfaces 4.7. Bean definition inheritance 4.8. Container Extension Points 4.8.1. Customizing beans using a BeanPostProcessor 4.8.1.1. Example: Hello World, BeanPostProcessor-style 4.8.1.2. Example: The RequiredAnnotationBeanPostProcessor 4.8.2. Customizing configuration metadata with a BeanFactoryPostProcessor 4.8.2.1. Example: the PropertyPlaceholderConfigurer 4.8.2.2. Example: the PropertyOverrideConfigurer 4.8.3. Customizing instantiation logic with a FactoryBean 4.9. Annotation-based container configuration 4.9.1. @Required 4.9.2. @Autowired 4.9.3. Fine-tuning annotation-based autowiring with qualifiers 4.9.4. CustomAutowireConfigurer 4.9.5. @Resource 4.9.6. @PostConstruct and @PreDestroy 4.10. Classpath scanning and managed components 4.10.1. @Component and further stereotype annotations 4.10.2. Automatically detecting classes and registering bean definitions 4.10.3. Using filters to customize scanning 4.10.4. Defining bean metadata within components 4.10.5. Naming autodetected components 4.10.6. Providing a scope for autodetected components 4.10.7. Providing qualifier metadata with annotations 4.11. Using JSR 330 Standard Annotations 4.11.1. Dependency Injection with @Inject and @Named 4.11.2. @Named: a standard equivalent to the @Component annotation 4.11.3. Limitations of the standard approach 4.12. Java-based container configuration 4.12.1. Basic concepts: @Configuration and @Bean 4.12.2. Instantiating the Spring container using AnnotationConfigApplicationContext 4.12.2.1. Simple construction
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 4/81

11/29/13

Reference Documentation

4.12.2.2. Building the container programmatically using register(Class<? >...) 4.12.2.3. Enabling component scanning with scan(String...) 4.12.2.4. Support for web applications with AnnotationConfigWebApplicationContext 4.12.3. Composing Java-based configurations 4.12.3.1. Using the @Import annotation 4.12.3.2. Combining Java and XML configuration 4.12.4. Using the @Bean annotation 4.12.4.1. Declaring a bean 4.12.4.2. Injecting dependencies 4.12.4.3. Receiving lifecycle callbacks 4.12.4.4. Specifying bean scope 4.12.4.5. Customizing bean naming 4.12.4.6. Bean aliasing 4.12.5. Further information about how Java-based configuration works internally 4.13. Registering a LoadTimeWeaver 4.14. Additional Capabilities of the ApplicationContext 4.14.1. Internationalization using MessageSource 4.14.2. Standard and Custom Events 4.14.3. Convenient access to low-level resources 4.14.4. Convenient ApplicationContext instantiation for web applications 4.14.5. Deploying a Spring ApplicationContext as a J2EE RAR file 4.15. The BeanFactory 4.15.1. BeanFactory or ApplicationContext? 4.15.2. Glue code and the evil singleton 5. Resources 5.1. Introduction 5.2. The Resource interface 5.3. Built-in Resource implementations 5.3.1. UrlResource 5.3.2. ClassPathResource 5.3.3. FileSystemResource 5.3.4. ServletContextResource 5.3.5. InputStreamResource 5.3.6. ByteArrayResource 5.4. The ResourceLoader 5.5. The ResourceLoaderAware interface 5.6. Resources as dependencies 5.7. Application contexts and Resource paths 5.7.1. Constructing application contexts 5.7.1.1. Constructing ClassPathXmlApplicationContext instances shortcuts 5.7.2. Wildcards in application context constructor resource paths
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 5/81

11/29/13

Reference Documentation

5.7.2.1. Ant-style Patterns 5.7.2.2. The classpath*: prefix 5.7.2.3. Other notes relating to wildcards 5.7.3. FileSystemResource caveats 6. Validation, Data Binding, and Type Conversion 6.1. Introduction 6.2. Validation using Spring's Validator interface 6.3. Resolving codes to error messages 6.4. Bean manipulation and the BeanWrapper 6.4.1. Setting and getting basic and nested properties 6.4.2. Built-in PropertyEditor implementations 6.4.2.1. Registering additional custom PropertyEditors 6.5. Spring 3 Type Conversion 6.5.1. Converter SPI 6.5.2. ConverterFactory 6.5.3. GenericConverter 6.5.3.1. ConditionalGenericConverter 6.5.4. ConversionService API 6.5.5. Configuring a ConversionService 6.5.6. Using a ConversionService programatically 6.6. Spring 3 Field Formatting 6.6.1. Formatter SPI 6.6.2. Annotation-driven Formatting 6.6.2.1. Format Annotation API 6.6.3. FormatterRegistry SPI 6.6.4. FormatterRegistrar SPI 6.6.5. Configuring Formatting in Spring MVC 6.7. Spring 3 Validation 6.7.1. Overview of the JSR-303 Bean Validation API 6.7.2. Configuring a Bean Validation Implementation 6.7.2.1. Injecting a Validator 6.7.2.2. Configuring Custom Constraints 6.7.2.3. Additional Configuration Options 6.7.3. Configuring a DataBinder 6.7.4. Spring MVC 3 Validation 6.7.4.1. Triggering @Controller Input Validation 6.7.4.2. Configuring a Validator for use by Spring MVC 6.7.4.3. Configuring a JSR-303 Validator for use by Spring MVC 7. Spring Expression Language (SpEL) 7.1. Introduction 7.2. Feature Overview
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 6/81

11/29/13

Reference Documentation

7.3. Expression Evaluation using Spring's Expression Interface 7.3.1. The EvaluationContext interface 7.3.1.1. Type Conversion 7.4. Expression support for defining bean definitions 7.4.1. XML based configuration 7.4.2. Annotation-based configuration 7.5. Language Reference 7.5.1. Literal expressions 7.5.2. Properties, Arrays, Lists, Maps, Indexers 7.5.3. Inline lists 7.5.4. Array construction 7.5.5. Methods 7.5.6. Operators 7.5.6.1. Relational operators 7.5.6.2. Logical operators 7.5.6.3. Mathematical operators 7.5.7. Assignment 7.5.8. Types 7.5.9. Constructors 7.5.10. Variables 7.5.10.1. The #this and #root variables 7.5.11. Functions 7.5.12. Bean references 7.5.13. Ternary Operator (If-Then-Else) 7.5.14. The Elvis Operator 7.5.15. Safe Navigation operator 7.5.16. Collection Selection 7.5.17. Collection Projection 7.5.18. Expression templating 7.6. Classes used in the examples 8. Aspect Oriented Programming with Spring 8.1. Introduction 8.1.1. AOP concepts 8.1.2. Spring AOP capabilities and goals 8.1.3. AOP Proxies 8.2. @AspectJ support 8.2.1. Enabling @AspectJ Support 8.2.2. Declaring an aspect 8.2.3. Declaring a pointcut 8.2.3.1. Supported Pointcut Designators 8.2.3.2. Combining pointcut expressions 8.2.3.3. Sharing common pointcut definitions 8.2.3.4. Examples
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 7/81

11/29/13

Reference Documentation

8.2.3.5. Writing good pointcuts 8.2.4. Declaring advice 8.2.4.1. Before advice 8.2.4.2. After returning advice 8.2.4.3. After throwing advice 8.2.4.4. After (finally) advice 8.2.4.5. Around advice 8.2.4.6. Advice parameters 8.2.4.7. Advice ordering 8.2.5. Introductions 8.2.6. Aspect instantiation models 8.2.7. Example 8.3. Schema-based AOP support 8.3.1. Declaring an aspect 8.3.2. Declaring a pointcut 8.3.3. Declaring advice 8.3.3.1. Before advice 8.3.3.2. After returning advice 8.3.3.3. After throwing advice 8.3.3.4. After (finally) advice 8.3.3.5. Around advice 8.3.3.6. Advice parameters 8.3.3.7. Advice ordering 8.3.4. Introductions 8.3.5. Aspect instantiation models 8.3.6. Advisors 8.3.7. Example 8.4. Choosing which AOP declaration style to use 8.4.1. Spring AOP or full AspectJ? 8.4.2. @AspectJ or XML for Spring AOP? 8.5. Mixing aspect types 8.6. Proxying mechanisms 8.6.1. Understanding AOP proxies 8.7. Programmatic creation of @AspectJ Proxies 8.8. Using AspectJ with Spring applications 8.8.1. Using AspectJ to dependency inject domain objects with Spring 8.8.1.1. Unit testing @Configurable objects 8.8.1.2. Working with multiple application contexts 8.8.2. Other Spring aspects for AspectJ 8.8.3. Configuring AspectJ aspects using Spring IoC 8.8.4. Load-time weaving with AspectJ in the Spring Framework 8.8.4.1. A first example 8.8.4.2. Aspects 8.8.4.3. 'META-INF/aop.xml'
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 8/81

11/29/13

Reference Documentation

8.8.4.4. Required libraries (JARS) 8.8.4.5. Spring configuration 8.8.4.6. Environment-specific configuration 8.9. Further Resources 9. Spring AOP APIs 9.1. Introduction 9.2. Pointcut API in Spring 9.2.1. Concepts 9.2.2. Operations on pointcuts 9.2.3. AspectJ expression pointcuts 9.2.4. Convenience pointcut implementations 9.2.4.1. Static pointcuts 9.2.4.2. Dynamic pointcuts 9.2.5. Pointcut superclasses 9.2.6. Custom pointcuts 9.3. Advice API in Spring 9.3.1. Advice lifecycles 9.3.2. Advice types in Spring 9.3.2.1. Interception around advice 9.3.2.2. Before advice 9.3.2.3. Throws advice 9.3.2.4. After Returning advice 9.3.2.5. Introduction advice 9.4. Advisor API in Spring 9.5. Using the ProxyFactoryBean to create AOP proxies 9.5.1. Basics 9.5.2. JavaBean properties 9.5.3. JDK- and CGLIB-based proxies 9.5.4. Proxying interfaces 9.5.5. Proxying classes 9.5.6. Using 'global' advisors 9.6. Concise proxy definitions 9.7. Creating AOP proxies programmatically with the ProxyFactory 9.8. Manipulating advised objects 9.9. Using the "autoproxy" facility 9.9.1. Autoproxy bean definitions 9.9.1.1. BeanNameAutoProxyCreator 9.9.1.2. DefaultAdvisorAutoProxyCreator 9.9.1.3. AbstractAdvisorAutoProxyCreator 9.9.2. Using metadata-driven auto-proxying 9.10. Using TargetSources 9.10.1. Hot swappable target sources 9.10.2. Pooling target sources
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 9/81

11/29/13

Reference Documentation

9.10.3. Prototype target sources 9.10.4. ThreadLocal target sources 9.11. Defining new Advice types 9.12. Further resources 10. Testing 10.1. Introduction to Spring Testing 10.2. Unit Testing 10.2.1. Mock Objects 10.2.1.1. JNDI 10.2.1.2. Servlet API 10.2.1.3. Portlet API 10.2.2. Unit Testing support Classes 10.2.2.1. General utilities 10.2.2.2. Spring MVC 10.3. Integration Testing 10.3.1. Overview 10.3.2. Goals of Integration Testing 10.3.2.1. Context management and caching 10.3.2.2. Dependency Injection of test fixtures 10.3.2.3. Transaction management 10.3.2.4. Support classes for integration testing 10.3.3. JDBC Testing Support 10.3.4. Annotations 10.3.4.1. Spring Testing Annotations 10.3.4.2. Standard Annotation Support 10.3.4.3. Spring JUnit Testing Annotations 10.3.5. Spring TestContext Framework 10.3.5.1. Key abstractions 10.3.5.2. Context management 10.3.5.3. Dependency injection of test fixtures 10.3.5.4. Transaction management 10.3.5.5. TestContext support classes 10.3.6. PetClinic Example 10.4. Further Resources IV. Data Access 11. Transaction Management 11.1. Introduction to Spring Framework transaction management 11.2. Advantages of the Spring Framework's transaction support model 11.2.1. Global transactions 11.2.2. Local transactions 11.2.3. Spring Framework's consistent programming model
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 10/81

11/29/13

Reference Documentation

11.3. Understanding the Spring Framework transaction abstraction 11.4. Synchronizing resources with transactions 11.4.1. High-level synchronization approach 11.4.2. Low-level synchronization approach 11.4.3. TransactionAwareDataSourceProxy 11.5. Declarative transaction management 11.5.1. Understanding the Spring Framework's declarative transaction implementation 11.5.2. Example of declarative transaction implementation 11.5.3. Rolling back a declarative transaction 11.5.4. Configuring different transactional semantics for different beans 11.5.5. <tx:advice/> settings 11.5.6. Using @Transactional 11.5.6.1. @Transactional settings 11.5.6.2. Multiple Transaction Managers with @Transactional 11.5.6.3. Custom shortcut annotations 11.5.7. Transaction propagation 11.5.7.1. Required 11.5.7.2. RequiresNew 11.5.7.3. Nested 11.5.8. Advising transactional operations 11.5.9. Using @Transactional with AspectJ 11.6. Programmatic transaction management 11.6.1. Using the TransactionTemplate 11.6.1.1. Specifying transaction settings 11.6.2. Using the PlatformTransactionManager 11.7. Choosing between programmatic and declarative transaction management 11.8. Application server-specific integration 11.8.1. IBM WebSphere 11.8.2. BEA WebLogic Server 11.8.3. Oracle OC4J 11.9. Solutions to common problems 11.9.1. Use of the wrong transaction manager for a specific DataSource 11.10. Further Resources 12. DAO support 12.1. Introduction 12.2. Consistent exception hierarchy 12.3. Annotations used for configuring DAO or Repository classes 13. Data access with JDBC 13.1. Introduction to Spring Framework JDBC
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 11/81

11/29/13

Reference Documentation

13.1.1. Choosing an approach for JDBC database access 13.1.2. Package hierarchy 13.2. Using the JDBC core classes to control basic JDBC processing and error handling 13.2.1. JdbcTemplate 13.2.1.1. Examples of JdbcTemplate class usage 13.2.1.2. JdbcTemplate best practices 13.2.2. NamedParameterJdbcTemplate 13.2.3. SimpleJdbcTemplate 13.2.4. SQLExceptionTranslator 13.2.5. Executing statements 13.2.6. Running queries 13.2.7. Updating the database 13.2.8. Retrieving auto-generated keys 13.3. Controlling database connections 13.3.1. DataSource 13.3.2. DataSourceUtils 13.3.3. SmartDataSource 13.3.4. AbstractDataSource 13.3.5. SingleConnectionDataSource 13.3.6. DriverManagerDataSource 13.3.7. TransactionAwareDataSourceProxy 13.3.8. DataSourceTransactionManager 13.3.9. NativeJdbcExtractor 13.4. JDBC batch operations 13.4.1. Basic batch operations with the JdbcTemplate 13.4.2. Batch operations with a List of objects 13.4.3. Batch operations with multiple batches 13.5. Simplifying JDBC operations with the SimpleJdbc classes 13.5.1. Inserting data using SimpleJdbcInsert 13.5.2. Retrieving auto-generated keys using SimpleJdbcInsert 13.5.3. Specifying columns for a SimpleJdbcInsert 13.5.4. Using SqlParameterSource to provide parameter values 13.5.5. Calling a stored procedure with SimpleJdbcCall 13.5.6. Explicitly declaring parameters to use for a SimpleJdbcCall 13.5.7. How to define SqlParameters 13.5.8. Calling a stored function using SimpleJdbcCall 13.5.9. Returning ResultSet/REF Cursor from a SimpleJdbcCall 13.6. Modeling JDBC operations as Java objects 13.6.1. SqlQuery 13.6.2. MappingSqlQuery 13.6.3. SqlUpdate 13.6.4. StoredProcedure 13.7. Common problems with parameter and data value handling 13.7.1. Providing SQL type information for parameters 13.7.2. Handling BLOB and CLOB objects
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 12/81

11/29/13

Reference Documentation

13.7.3. Passing in lists of values for IN clause 13.7.4. Handling complex types for stored procedure calls 13.8. Embedded database support 13.8.1. Why use an embedded database? 13.8.2. Creating an embedded database instance using Spring XML 13.8.3. Creating an embedded database instance programmatically 13.8.4. Extending the embedded database support 13.8.5. Using HSQL 13.8.6. Using H2 13.8.7. Using Derby 13.8.8. Testing data access logic with an embedded database 13.9. Initializing a DataSource 13.9.1. Initializing a database instance using Spring XML 13.9.1.1. Initialization of Other Components that Depend on the Database 14. Object Relational Mapping (ORM) Data Access 14.1. Introduction to ORM with Spring 14.2. General ORM integration considerations 14.2.1. Resource and transaction management 14.2.2. Exception translation 14.3. Hibernate 14.3.1. SessionFactory setup in a Spring container 14.3.2. Implementing DAOs based on plain Hibernate 3 API 14.3.3. Declarative transaction demarcation 14.3.4. Programmatic transaction demarcation 14.3.5. Transaction management strategies 14.3.6. Comparing container-managed and locally defined resources 14.3.7. Spurious application server warnings with Hibernate 14.4. JDO 14.4.1. PersistenceManagerFactory setup 14.4.2. Implementing DAOs based on the plain JDO API 14.4.3. Transaction management 14.4.4. JdoDialect 14.5. JPA 14.5.1. Three options for JPA setup in a Spring environment 14.5.1.1. LocalEntityManagerFactoryBean 14.5.1.2. Obtaining an EntityManagerFactory from JNDI 14.5.1.3. LocalContainerEntityManagerFactoryBean 14.5.1.4. Dealing with multiple persistence units 14.5.2. Implementing DAOs based on plain JPA 14.5.3. Transaction Management 14.5.4. JpaDialect 14.6. iBATIS SQL Maps

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

13/81

11/29/13

Reference Documentation

14.6.1. Setting up the SqlMapClient 14.6.2. Using SqlMapClientTemplate and SqlMapClientDaoSupport 14.6.3. Implementing DAOs based on plain iBATIS API 15. Marshalling XML using O/X Mappers 15.1. Introduction 15.2. Marshaller and Unmarshaller 15.2.1. Marshaller 15.2.2. Unmarshaller 15.2.3. XmlMappingException 15.3. Using Marshaller and Unmarshaller 15.4. XML Schema-based Configuration 15.5. JAXB 15.5.1. Jaxb2Marshaller 15.5.1.1. XML Schema-based Configuration 15.6. Castor 15.6.1. CastorMarshaller 15.6.2. Mapping 15.7. XMLBeans 15.7.1. XmlBeansMarshaller 15.7.1.1. XML Schema-based Configuration 15.8. JiBX 15.8.1. JibxMarshaller 15.8.1.1. XML Schema-based Configuration 15.9. XStream 15.9.1. XStreamMarshaller V. The Web 16. Web MVC framework 16.1. Introduction to Spring Web MVC framework 16.1.1. Features of Spring Web MVC 16.1.2. Pluggability of other MVC implementations 16.2. The DispatcherServlet 16.2.1. Special Bean Types In the WebApplicationContext 16.2.2. Default DispatcherServlet Configuration 16.2.3. DispatcherServlet Processing Sequence 16.3. Implementing Controllers 16.3.1. Defining a controller with @Controller 16.3.2. Mapping Requests With @RequestMapping
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 14/81

11/29/13

Reference Documentation

16.3.2.1. New Support Classes for @RequestMapping methods in Spring MVC 3.1 16.3.2.2. URI Template Patterns 16.3.2.3. URI Template Patterns with Regular Expressions 16.3.2.4. Path Patterns 16.3.2.5. Consumable Media Types 16.3.2.6. Producible Media Types 16.3.2.7. Request Parameters and Header Values 16.3.3. Defining @RequestMapping handler methods 16.3.3.1. Supported method argument types 16.3.3.2. Supported method return types 16.3.3.3. Binding request parameters to method parameters with @RequestParam 16.3.3.4. Mapping the request body with the @RequestBody annotation 16.3.3.5. Mapping the response body with the @ResponseBody annotation 16.3.3.6. Using HttpEntity<?> 16.3.3.7. Using @ModelAttribute on a method 16.3.3.8. Using @ModelAttribute on a method argument 16.3.3.9. Using @SessionAttributes to store model attributes in the HTTP session between requests 16.3.3.10. Specifying redirect and flash attributes 16.3.3.11. Working with "application/x-www-form-urlencoded" data 16.3.3.12. Mapping cookie values with the @CookieValue annotation 16.3.3.13. Mapping request header attributes with the @RequestHeader annotation 16.3.3.14. Method Parameters And Type Conversion 16.3.3.15. Customizing WebDataBinder initialization 16.3.3.16. Support for the 'Last-Modified' Response Header To Facilitate Content Caching 16.4. Handler mappings 16.4.1. Intercepting requests with a HandlerInterceptor 16.5. Resolving views 16.5.1. Resolving views with the ViewResolver interface 16.5.2. Chaining ViewResolvers 16.5.3. Redirecting to views 16.5.3.1. RedirectView 16.5.3.2. The redirect: prefix 16.5.3.3. The forward: prefix 16.5.4. ContentNegotiatingViewResolver 16.6. Using flash attributes 16.7. Building URIs 16.8. Using locales 16.8.1. AcceptHeaderLocaleResolver 16.8.2. CookieLocaleResolver 16.8.3. SessionLocaleResolver 16.8.4. LocaleChangeInterceptor 16.9. Using themes
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 15/81

11/29/13

Reference Documentation

16.9.1. Overview of themes 16.9.2. Defining themes 16.9.3. Theme resolvers 16.10. Spring's multipart (file upload) support 16.10.1. Introduction 16.10.2. Using a MultipartResolver with Commons FileUpload 16.10.3. Using a MultipartResolver with Servlet 3.0 16.10.4. Handling a file upload in a form 16.10.5. Handling a file upload request from programmatic clients 16.11. Handling exceptions 16.11.1. HandlerExceptionResolver 16.11.2. @ExceptionHandler 16.12. Convention over configuration support 16.12.1. The Controller ControllerClassNameHandlerMapping 16.12.2. The Model ModelMap (ModelAndView) 16.12.3. The View - RequestToViewNameTranslator 16.13. ETag support 16.14. Configuring Spring MVC 16.14.1. Enabling MVC Java Config or the MVC XML Namespace 16.14.2. Customizing the Provided Configuration 16.14.3. Configuring Interceptors 16.14.4. Configuring View Controllers 16.14.5. Configuring Serving of Resources 16.14.6. mvc:default-servlet-handler 16.14.7. More Spring Web MVC Resources 16.14.8. Advanced Customizations with MVC Java Config 16.14.9. Advanced Customizations with the MVC Namespace 17. View technologies 17.1. Introduction 17.2. JSP & JSTL 17.2.1. View resolvers 17.2.2. 'Plain-old' JSPs versus JSTL 17.2.3. Additional tags facilitating development 17.2.4. Using Spring's form tag library 17.2.4.1. Configuration 17.2.4.2. The form tag 17.2.4.3. The input tag 17.2.4.4. The checkbox tag 17.2.4.5. The checkboxes tag 17.2.4.6. The radiobutton tag 17.2.4.7. The radiobuttons tag 17.2.4.8. The password tag 17.2.4.9. The select tag 17.2.4.10. The option tag 17.2.4.11. The options tag 17.2.4.12. The textarea tag 17.2.4.13. The hidden tag 17.2.4.14. The errors tag
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 16/81

11/29/13

Reference Documentation

17.2.4.15. HTTP Method Conversion 17.2.4.16. HTML5 Tags 17.3. Tiles 17.3.1. Dependencies 17.3.2. How to integrate Tiles 17.3.2.1. UrlBasedViewResolver 17.3.2.2. ResourceBundleViewResolver 17.3.2.3. SimpleSpringPreparerFactory and SpringBeanPreparerFactory 17.4. Velocity & FreeMarker 17.4.1. Dependencies 17.4.2. Context configuration 17.4.3. Creating templates 17.4.4. Advanced configuration 17.4.4.1. velocity.properties 17.4.4.2. FreeMarker 17.4.5. Bind support and form handling 17.4.5.1. The bind macros 17.4.5.2. Simple binding 17.4.5.3. Form input generation macros 17.4.5.4. HTML escaping and XHTML compliance 17.5. XSLT 17.5.1. My First Words 17.5.1.1. Bean definitions 17.5.1.2. Standard MVC controller code 17.5.1.3. Convert the model data to XML 17.5.1.4. Defining the view properties 17.5.1.5. Document transformation 17.5.2. Summary 17.6. Document views (PDF/Excel) 17.6.1. Introduction 17.6.2. Configuration and setup 17.6.2.1. Document view definitions 17.6.2.2. Controller code 17.6.2.3. Subclassing for Excel views 17.6.2.4. Subclassing for PDF views 17.7. JasperReports 17.7.1. Dependencies 17.7.2. Configuration 17.7.2.1. Configuring the ViewResolver 17.7.2.2. Configuring the Views 17.7.2.3. About Report Files 17.7.2.4. Using JasperReportsMultiFormatView
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 17/81

11/29/13

Reference Documentation

17.7.3. Populating the ModelAndView 17.7.4. Working with Sub-Reports 17.7.4.1. Configuring Sub-Report Files 17.7.4.2. Configuring Sub-Report Data Sources 17.7.5. Configuring Exporter Parameters 17.8. Feed Views 17.9. XML Marshalling View 17.10. JSON Mapping View 18. Integrating with other web frameworks 18.1. Introduction 18.2. Common configuration 18.3. JavaServer Faces 1.1 and 1.2 18.3.1. DelegatingVariableResolver (JSF 1.1/1.2) 18.3.2. SpringBeanVariableResolver (JSF 1.1/1.2) 18.3.3. SpringBeanFacesELResolver (JSF 1.2+) 18.3.4. FacesContextUtils 18.4. Apache Struts 1.x and 2.x 18.4.1. ContextLoaderPlugin 18.4.1.1. DelegatingRequestProcessor 18.4.1.2. DelegatingActionProxy 18.4.2. ActionSupport Classes 18.5. WebWork 2.x 18.6. Tapestry 3.x and 4.x 18.6.1. Injecting Spring-managed beans 18.6.1.1. Dependency Injecting Spring Beans into Tapestry pages 18.6.1.2. Component definition files 18.6.1.3. Adding abstract accessors 18.6.1.4. Dependency Injecting Spring Beans into Tapestry pages Tapestry 4.x style 18.7. Further Resources 19. Portlet MVC Framework 19.1. Introduction 19.1.1. Controllers - The C in MVC 19.1.2. Views - The V in MVC 19.1.3. Web-scoped beans 19.2. The DispatcherPortlet 19.3. The ViewRendererServlet 19.4. Controllers 19.4.1. AbstractController and PortletContentGenerator 19.4.2. Other simple controllers 19.4.3. Command Controllers 19.4.4. PortletWrappingController
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 18/81

11/29/13

Reference Documentation

19.5. Handler mappings 19.5.1. PortletModeHandlerMapping 19.5.2. ParameterHandlerMapping 19.5.3. PortletModeParameterHandlerMapping 19.5.4. Adding HandlerInterceptors 19.5.5. HandlerInterceptorAdapter 19.5.6. ParameterMappingInterceptor 19.6. Views and resolving them 19.7. Multipart (file upload) support 19.7.1. Using the PortletMultipartResolver 19.7.2. Handling a file upload in a form 19.8. Handling exceptions 19.9. Annotation-based controller configuration 19.9.1. Setting up the dispatcher for annotation support 19.9.2. Defining a controller with @Controller 19.9.3. Mapping requests with @RequestMapping 19.9.4. Supported handler method arguments 19.9.5. Binding request parameters to method parameters with @RequestParam 19.9.6. Providing a link to data from the model with @ModelAttribute 19.9.7. Specifying attributes to store in a Session with @SessionAttributes 19.9.8. Customizing WebDataBinder initialization 19.9.8.1. Customizing data binding with @InitBinder 19.9.8.2. Configuring a custom WebBindingInitializer 19.10. Portlet application deployment VI. Integration 20. Remoting and web services using Spring 20.1. Introduction 20.2. Exposing services using RMI 20.2.1. Exporting the service using the RmiServiceExporter 20.2.2. Linking in the service at the client 20.3. Using Hessian or Burlap to remotely call services via HTTP 20.3.1. Wiring up the DispatcherServlet for Hessian and co. 20.3.2. Exposing your beans by using the HessianServiceExporter 20.3.3. Linking in the service on the client 20.3.4. Using Burlap 20.3.5. Applying HTTP basic authentication to a service exposed through Hessian or Burlap 20.4. Exposing services using HTTP invokers 20.4.1. Exposing the service object 20.4.2. Linking in the service at the client 20.5. Web services 20.5.1. Exposing servlet-based web services using JAX-RPC
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 19/81

11/29/13

Reference Documentation

20.5.2. Accessing web services using JAX-RPC 20.5.3. Registering JAX-RPC Bean Mappings 20.5.4. Registering your own JAX-RPC Handler 20.5.5. Exposing servlet-based web services using JAX-WS 20.5.6. Exporting standalone web services using JAX-WS 20.5.7. Exporting web services using the JAX-WS RI's Spring support 20.5.8. Accessing web services using JAX-WS 20.6. JMS 20.6.1. Server-side configuration 20.6.2. Client-side configuration 20.7. Auto-detection is not implemented for remote interfaces 20.8. Considerations when choosing a technology 20.9. Accessing RESTful services on the Client 20.9.1. RestTemplate 20.9.1.1. Working with the URI 20.9.1.2. Dealing with request and response headers 20.9.2. HTTP Message Conversion 20.9.2.1. StringHttpMessageConverter 20.9.2.2. FormHttpMessageConverter 20.9.2.3. ByteArrayHttpMessageConverter 20.9.2.4. MarshallingHttpMessageConverter 20.9.2.5. MappingJacksonHttpMessageConverter 20.9.2.6. SourceHttpMessageConverter 20.9.2.7. BufferedImageHttpMessageConverter 21. Enterprise JavaBeans (EJB) integration 21.1. Introduction 21.2. Accessing EJBs 21.2.1. Concepts 21.2.2. Accessing local SLSBs 21.2.3. Accessing remote SLSBs 21.2.4. Accessing EJB 2.x SLSBs versus EJB 3 SLSBs 21.3. Using Spring's EJB implementation support classes 21.3.1. EJB 2.x base classes 21.3.2. EJB 3 injection interceptor 22. JMS (Java Message Service) 22.1. Introduction 22.2. Using Spring JMS 22.2.1. JmsTemplate 22.2.2. Connections 22.2.2.1. Caching Messaging Resources 22.2.2.2. SingleConnectionFactory 22.2.2.3. CachingConnectionFactory 22.2.3. Destination Management
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 20/81

11/29/13

Reference Documentation

22.2.4. Message Listener Containers 22.2.4.1. SimpleMessageListenerContainer 22.2.4.2. DefaultMessageListenerContainer 22.2.5. Transaction management 22.3. Sending a Message 22.3.1. Using Message Converters 22.3.2. SessionCallback and ProducerCallback 22.4. Receiving a message 22.4.1. Synchronous Reception 22.4.2. Asynchronous Reception - Message-Driven POJOs 22.4.3. The SessionAwareMessageListener interface 22.4.4. The MessageListenerAdapter 22.4.5. Processing messages within transactions 22.5. Support for JCA Message Endpoints 22.6. JMS Namespace Support 23. JMX 23.1. Introduction 23.2. Exporting your beans to JMX 23.2.1. Creating an MBeanServer 23.2.2. Reusing an existing MBeanServer 23.2.3. Lazy-initialized MBeans 23.2.4. Automatic registration of MBeans 23.2.5. Controlling the registration behavior 23.3. Controlling the management interface of your beans 23.3.1. The MBeanInfoAssembler Interface 23.3.2. Using Source-Level Metadata (JDK 5.0 annotations) 23.3.3. Source-Level Metadata Types 23.3.4. The AutodetectCapableMBeanInfoAssembler interface 23.3.5. Defining management interfaces using Java interfaces 23.3.6. Using MethodNameBasedMBeanInfoAssembler 23.4. Controlling the ObjectNames for your beans 23.4.1. Reading ObjectNames from Properties 23.4.2. Using the MetadataNamingStrategy 23.4.3. The <context:mbean-export/> element 23.5. JSR-160 Connectors 23.5.1. Server-side Connectors 23.5.2. Client-side Connectors 23.5.3. JMX over Burlap/Hessian/SOAP 23.6. Accessing MBeans via Proxies 23.7. Notifications 23.7.1. Registering Listeners for Notifications 23.7.2. Publishing Notifications
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 21/81

11/29/13

Reference Documentation

23.8. Further Resources 24. JCA CCI 24.1. Introduction 24.2. Configuring CCI 24.2.1. Connector configuration 24.2.2. ConnectionFactory configuration in Spring 24.2.3. Configuring CCI connections 24.2.4. Using a single CCI connection 24.3. Using Spring's CCI access support 24.3.1. Record conversion 24.3.2. The CciTemplate 24.3.3. DAO support 24.3.4. Automatic output record generation 24.3.5. Summary 24.3.6. Using a CCI Connection and Interaction directly 24.3.7. Example for CciTemplate usage 24.4. Modeling CCI access as operation objects 24.4.1. MappingRecordOperation 24.4.2. MappingCommAreaOperation 24.4.3. Automatic output record generation 24.4.4. Summary 24.4.5. Example for MappingRecordOperation usage 24.4.6. Example for MappingCommAreaOperation usage 24.5. Transactions 25. Email 25.1. Introduction 25.2. Usage 25.2.1. Basic MailSender and SimpleMailMessage usage 25.2.2. Using the JavaMailSender and the MimeMessagePreparator 25.3. Using the JavaMail MimeMessageHelper 25.3.1. Sending attachments and inline resources 25.3.1.1. Attachments 25.3.1.2. Inline resources 25.3.2. Creating email content using a templating library 25.3.2.1. A Velocity-based example 26. Task Execution and Scheduling 26.1. Introduction 26.2. The Spring TaskExecutor abstraction 26.2.1. TaskExecutor types 26.2.2. Using a TaskExecutor 26.3. The Spring TaskScheduler abstraction
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 22/81

11/29/13

Reference Documentation

26.3.1. The Trigger interface 26.3.2. Trigger implementations 26.3.3. TaskScheduler implementations 26.4. The Task Namespace 26.4.1. The 'scheduler' element 26.4.2. The 'executor' element 26.4.3. The 'scheduled-tasks' element 26.5. Annotation Support for Scheduling and Asynchronous Execution 26.5.1. The @Scheduled Annotation 26.5.2. The @Async Annotation 26.5.3. The <annotation-driven> Element 26.5.4. Executor qualification with @Async 26.6. Using the Quartz Scheduler 26.6.1. Using the JobDetailBean 26.6.2. Using the MethodInvokingJobDetailFactoryBean 26.6.3. Wiring up jobs using triggers and the SchedulerFactoryBean 27. Dynamic language support 27.1. Introduction 27.2. A first example 27.3. Defining beans that are backed by dynamic languages 27.3.1. Common concepts 27.3.1.1. The <lang:language/> element 27.3.1.2. Refreshable beans 27.3.1.3. Inline dynamic language source files 27.3.1.4. Understanding Constructor Injection in the context of dynamiclanguage-backed beans 27.3.2. JRuby beans 27.3.3. Groovy beans 27.3.3.1. Customising Groovy objects via a callback 27.3.4. BeanShell beans 27.4. Scenarios 27.4.1. Scripted Spring MVC Controllers 27.4.2. Scripted Validators 27.5. Bits and bobs 27.5.1. AOP - advising scripted beans 27.5.2. Scoping 27.6. Further Resources 28. Cache Abstraction 28.1. Introduction 28.2. Understanding the cache abstraction 28.3. Declarative annotation-based caching
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 23/81

11/29/13

Reference Documentation

28.3.1. @Cacheable annotation 28.3.1.1. Default Key Generation 28.3.1.2. Custom Key Generation Declaration 28.3.1.3. Conditional caching 28.3.1.4. Available caching SpEL evaluation context 28.3.2. @CachePut annotation 28.3.3. @CacheEvict annotation 28.3.4. @Caching annotation 28.3.5. Enable caching annotations 28.3.6. Using custom annotations 28.4. Declarative XML-based caching 28.5. Configuring the cache storage 28.5.1. JDK ConcurrentMap-based Cache 28.5.2. Ehcache-based Cache 28.5.3. Dealing with caches without a backing store 28.6. Plugging-in different back-end caches 28.7. How can I set the TTL/TTI/Eviction policy/XXX feature? VII. Appendices A. Classic Spring Usage A.1. Classic ORM usage A.1.1. Hibernate A.1.1.1. The HibernateTemplate A.1.1.2. Implementing Spring-based DAOs without callbacks A.1.2. JDO A.1.2.1. JdoTemplate and JdoDaoSupport A.1.3. JPA A.1.3.1. JpaTemplate and JpaDaoSupport A.2. Classic Spring MVC A.3. JMS Usage A.3.1. JmsTemplate A.3.2. Asynchronous Message Reception A.3.3. Connections A.3.4. Transaction Management B. Migrating to Spring Framework 3.1 B.1. Component scanning against the "org" base package C. Classic Spring AOP Usage C.1. Pointcut API in Spring C.1.1. Concepts C.1.2. Operations on pointcuts C.1.3. AspectJ expression pointcuts
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 24/81

11/29/13

Reference Documentation

C.1.4. Convenience pointcut implementations C.1.4.1. Static pointcuts C.1.4.2. Dynamic pointcuts C.1.5. Pointcut superclasses C.1.6. Custom pointcuts C.2. Advice API in Spring C.2.1. Advice lifecycles C.2.2. Advice types in Spring C.2.2.1. Interception around advice C.2.2.2. Before advice C.2.2.3. Throws advice C.2.2.4. After Returning advice C.2.2.5. Introduction advice C.3. Advisor API in Spring C.4. Using the ProxyFactoryBean to create AOP proxies C.4.1. Basics C.4.2. JavaBean properties C.4.3. JDK- and CGLIB-based proxies C.4.4. Proxying interfaces C.4.5. Proxying classes C.4.6. Using 'global' advisors C.5. Concise proxy definitions C.6. Creating AOP proxies programmatically with the ProxyFactory C.7. Manipulating advised objects C.8. Using the "autoproxy" facility C.8.1. Autoproxy bean definitions C.8.1.1. BeanNameAutoProxyCreator C.8.1.2. DefaultAdvisorAutoProxyCreator C.8.1.3. AbstractAdvisorAutoProxyCreator C.8.2. Using metadata-driven auto-proxying C.9. Using TargetSources C.9.1. Hot swappable target sources C.9.2. Pooling target sources C.9.3. Prototype target sources C.9.4. ThreadLocal target sources C.10. Defining new Advice types C.11. Further resources D. XML Schema-based configuration D.1. Introduction D.2. XML Schema-based configuration D.2.1. Referencing the schemas D.2.2. The util schema

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

25/81

11/29/13

Reference Documentation

D.2.2.1. <util:constant/> D.2.2.2. <util:property-path/> D.2.2.3. <util:properties/> D.2.2.4. <util:list/> D.2.2.5. <util:map/> D.2.2.6. <util:set/> D.2.3. The jee schema D.2.3.1. <jee:jndi-lookup/> (simple) D.2.3.2. <jee:jndi-lookup/> (with single JNDI environment setting) D.2.3.3. <jee:jndi-lookup/> (with multiple JNDI environment settings) D.2.3.4. <jee:jndi-lookup/> (complex) D.2.3.5. <jee:local-slsb/> (simple) D.2.3.6. <jee:local-slsb/> (complex) D.2.3.7. <jee:remote-slsb/> D.2.4. The lang schema D.2.5. The jms schema D.2.6. The tx (transaction) schema D.2.7. The aop schema D.2.8. The context schema D.2.8.1. <property-placeholder/> D.2.8.2. <annotation-config/> D.2.8.3. <component-scan/> D.2.8.4. <load-time-weaver/> D.2.8.5. <spring-configured/> D.2.8.6. <mbean-export/> D.2.9. The tool schema D.2.10. The beans schema E. Extensible XML authoring E.1. Introduction E.2. Authoring the schema E.3. Coding a NamespaceHandler E.4. Coding a BeanDefinitionParser E.5. Registering the handler and the schema E.5.1. 'META-INF/spring.handlers' E.5.2. 'META-INF/spring.schemas' E.6. Using a custom extension in your Spring XML configuration E.7. Meatier examples E.7.1. Nesting custom tags within custom tags E.7.2. Custom attributes on 'normal' elements E.8. Further Resources F. spring-beans-2.0.dtd G. spring.tld G.1. Introduction G.2. The bind tag G.3. The escapeBody tag G.4. The hasBindErrors tag G.5. The htmlEscape tag
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 26/81

11/29/13

Reference Documentation

G.6. The message tag G.7. The nestedPath tag G.8. The theme tag G.9. The transform tag G.10. The url tag G.11. The eval tag H. spring-form.tld H.1. Introduction H.2. The checkbox tag H.3. The checkboxes tag H.4. The errors tag H.5. The form tag H.6. The hidden tag H.7. The input tag H.8. The label tag H.9. The option tag H.10. The options tag H.11. The password tag H.12. The radiobutton tag H.13. The radiobuttons tag H.14. The select tag H.15. The textarea tag

Part I. 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 Struts 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 or on the support forums at http://forum.springsource.org/.

1. Introduction to Spring Framework

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 use the Spring platform advantage: Make a Java method execute in a database transaction without having to deal with
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 27/81

11/29/13

Reference Documentation

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.

1.1 Dependency Injection and Inversion of Control

Java applications -- a loose term that runs the gamut from constrained applets to n-tier server-side enterprise applications -- typically consist of objects that collaborate to form the application proper. Thus the objects in an application have dependencies on each other.
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.

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 For insight into IoC and DI, refer to developers. True, you can use design patterns such as Fowler's article at Factory, Abstract Factory, Builder, Decorator, and http://martinfowler.com/articles/injection.html. Service Locator to compose the various classes and object instances that make up an application. However, these patterns are simply that: best practices given a name, with a description of what the pattern does, where to apply it, the problems it addresses, and so forth. Patterns are formalized best practices that you must implement yourself in your application. The Spring Framework Inversion of Control (IoC) component addresses this concern by providing a formalized means of composing disparate components into a fully working application ready for use. The Spring Framework codifies formalized design patterns as firstclass 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.

1.2 Modules
The Spring Framework consists of features organized into about 20 modules. These modules are grouped into Core Container, Data Access/Integration, Web, AOP (Aspect Oriented Programming), Instrumentation, and Test, as shown in the following diagram.

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

28/81

11/29/13

Reference Documentation

Overview of the Spring Framework

1.2.1 Core Container

The Core Container consists of the Core, Beans, Context, and Expression Language modules. The Core and Beans modules provide the fundamental parts of the framework, including the IoC and Dependency Injection features. The B e a n F a c t o r y is a sophisticated implementation of the factory pattern. It removes the need for programmatic singletons and allows you to decouple the configuration and specification of dependencies from your actual program logic. The Context 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 A p p l i c a t i o n C o n t e x tinterface is the focal point of the Context module. The Expression Language module provides a powerful expression language for querying and manipulating an object graph at runtime. It is an extension of the unified expression language (unified EL) as specified in the JSP 2.1 specification. The language supports setting and getting property values, property assignment, method invocation, accessing the context of arrays, collections and indexers, logical and arithmetic operators, named variables, and retrieval of objects by name from Spring's IoC container. It also supports list projection and selection as well as common list aggregations.

1.2.2 Data Access/Integration

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 29/81

11/29/13

Reference Documentation

The Data Access/Integration layer consists of the JDBC, ORM, OXM, JMS and Transaction modules. The JDBC module provides a JDBC-abstraction layer that removes the need to do tedious JDBC coding and parsing of database-vendor specific error codes. The ORM module provides integration layers for popular object-relational mapping APIs, including JPA, JDO, Hibernate, and iBatis. Using the ORM package you can use all of these O/Rmapping frameworks in combination with all of the other features Spring offers, such as the simple declarative transaction management feature mentioned previously. The OXM module provides an abstraction layer that supports Object/XML mapping implementations for JAXB, Castor, XMLBeans, JiBX and XStream. The Java Messaging Service (JMS) module contains features for producing and consuming messages. The Transaction module supports programmatic and declarative transaction management for classes that implement special interfaces and for all your POJOs (plain old Java objects).

1.2.3 Web
The Web layer consists of the Web, Web-Servlet, Web-Struts, and Web-Portlet modules. Spring's Web module provides basic web-oriented integration features such as multipart fileupload functionality and the initialization of the IoC container using servlet listeners and a weboriented application context. It also contains the web-related parts of Spring's remoting support. The Web-Servlet module contains Spring's model-view-controller (MVC) implementation for web applications. Spring's MVC framework provides a clean separation between domain model code and web forms, and integrates with all the other features of the Spring Framework. The Web-Struts module contains the support classes for integrating a classic Struts web tier within a Spring application. Note that this support is now deprecated as of Spring 3.0. Consider migrating your application to Struts 2.0 and its Spring integration or to a Spring MVC solution. The Web-Portlet module provides the MVC implementation to be used in a portlet environment and mirrors the functionality of Web-Servlet module.

1.2.4 AOP and Instrumentation

Spring's AOP module provides an AOP Alliance-compliant aspect-oriented programming implementation allowing you to define, for example, method-interceptors and pointcuts to cleanly decouple code that implements functionality that should be 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 Aspects module provides integration with AspectJ. The Instrumentation module provides class instrumentation support and classloader implementations to be used in certain application servers.

1.2.5 Test
The Test module supports the testing of Spring components with JUnit or TestNG. It provides consistent loading of Spring ApplicationContexts and caching of those contexts. It also provides mock objects that you can use to test your code in isolation.
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 30/81

11/29/13

Reference Documentation

1.3 Usage scenarios

The building blocks described previously make Spring a logical choice in many scenarios, from applets to full-fledged enterprise applications that use Spring's transaction management functionality and web framework integration.

Typical full-fledged Spring web application

Spring's 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 Spring's 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. Spring's ORM support is integrated with JPA, Hibernate, JDO and iBatis; for example, when using Hibernate, you can continue to use your existing mapping files and standard Hibernate S e s s i o n F a c t o r y configuration. Form controllers seamlessly integrate the web-layer with the domain model, removing the need for A c t i o n F o r m s or other classes that transform HTTP parameters to values for your domain model.

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

31/81

11/29/13

Reference Documentation

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 WebWork, Struts, Tapestry, 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 A p p l i c a t i o n C o n t e x t and use a W e b A p p l i c a t i o n C o n t e x t to integrate your web layer.

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

32/81

11/29/13

Reference Documentation

Remoting usage scenario

When you need to access existing code through web services, you can use Spring's H e s s i a n , Enabling remote access to existing applications is not difficult.
B u r l a p ,R m i -or J a x R p c P r o x y F a c t o r yclasses.

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.

1.3.1 Dependency Management and Naming Conventions

Dependency management and dependency injection are different things. To get those nice features of Spring into your application (like dependency injection) you need to assemble all the libraries needed (jar files) and get them onto your classpath at runtime, and possibly at compile time. These dependencies are not virtual components that are injected, but physical resources in a file system (typically). The process of dependency management involves locating those resources, storing them and adding them to classpaths. Dependencies can be direct (e.g. my application depends on Spring at runtime), or indirect (e.g. my application depends on c o m m o n s docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 33/81

11/29/13

Reference Documentation

d b c pwhich depends

on c o m m o n s p o o l ). 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 don't want to write a web application you don't need the spring-web modules. To refer to Spring library modules in this guide we use a shorthand naming convention s p r i n g * or s p r i n g * . j a r , where "*" represents the short name for the module (e.g. s p r i n g c o r e ,s p r i n g w e b m v c ,s p r i n g j m s , etc.). The actual jar file name that you use may be in this form (see below) or it may not, and normally it also has a version number in the file name (e.g. s p r i n g c o r e 3 . 0 . 0 . R E L E A S E . j a r ). In general, Spring publishes its artifacts to four different places: On the community download site http://www.springsource.org/download/community. Here you find all the Spring jars bundled together into a zip file for easy download. The names of the jars here since version 3.0 are in the form o r g . s p r i n g f r a m e w o r k . * < v e r s i o n > . j a r . Maven Central, which is the default repository that Maven queries, and does not require any special configuration to use. Many of the common libraries that Spring depends on also are available from Maven Central and a large section of the Spring community uses Maven for dependency management, so this is convenient for them. The names of the jars here are in the form s p r i n g * < v e r s i o n > . j a rand the Maven groupId is o r g . s p r i n g f r a m e w o r k . The Enterprise Bundle Repository (EBR), which is run by SpringSource and also hosts all the libraries that integrate with Spring. Both Maven and Ivy repositories are available here for all Spring jars and their dependencies, plus a large number of other common libraries that people use in applications with Spring. Both full releases and also milestones and development snapshots are deployed here. The names of the jar files are in the same form as the community download (o r g . s p r i n g f r a m e w o r k . * < v e r s i o n > . j a r ), and the dependencies are also in this "long" form, with external libraries (not from SpringSource) having the prefix c o m . s p r i n g s o u r c e . See the FAQ for more information. In a public Maven repository hosted on Amazon S3 for development snapshots and milestone releases (a copy of the final releases is also held here). The jar file names are in the same form as Maven Central, so this is a useful place to get development versions of Spring to use with other libraries depoyed in Maven Central. So the first thing you need to decide is how to manage your dependencies: most people use an automated system like Maven or Ivy, but you can also do it manually by downloading all the jars yourself. When obtaining Spring with Maven or Ivy you have then to decide which place you'll get it from. In general, if you care about OSGi, use the EBR, since it houses OSGi compatible artifacts for all of Spring's dependencies, such as Hibernate and Freemarker. If OSGi does not matter to you, either place works, though there are some pros and cons between them. In general, pick one place or the other for your project; do not mix them. This is particularly important since EBR artifacts necessarily use a different naming convention than Maven Central artifacts.

Table 1.1. Comparison of Maven Central and SpringSource EBR Repositories Feature OSGi Compatible Number of Artifacts Consistent Naming Conventions Maven Central Not explicit Tens of thousands; all kinds No Yes Hundreds; those that Spring integrates with Yes
34/81

EBR

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

11/29/13

Reference Documentation

Naming Convention: GroupId

Varies. Newer artifacts often use domain name, e.g. org.slf4j. Older ones often just use the artifact name, e.g. log4j. Varies. Generally the project or module name, using a hyphen "-" separator, e.g. spring-core, logj4. Varies. Many new artifacts use m.m.m or m.m.m.X (with m=digit, X=text). Older ones use m.m. Some neither. Ordering is defined but not often relied on, so not strictly reliable. Usually automatic via rsync or source control updates. Project authors can upload individual jars to JIRA. By policy. Accuracy is responsibility of authors. Contegix. Funded by Sonatype with several mirrors. Various Integration through STS with Maven dependency management

Domain name of origin or main package root, e.g. org.springframework Bundle Symbolic Name, derived from the main package root, e.g. org.springframework.beans. If the jar had to be patched to ensure OSGi compliance then com.springsource is appended, e.g. com.springsource.org.apache.log4j OSGi version number m.m.m.X, e.g. 3.0.0.RC3. The text qualifier imposes alphabetic ordering on versions with the same numeric values.

Naming Convention: ArtifactId

Naming Convention: Version

Publishing

Manual (JIRA processed by SpringSource) Extensive for OSGi manifest, Maven POM and Ivy metadata. QA performed by Spring team. S3 funded by SpringSource. http://www.springsource.com/repository Extensive integration through STS with Maven, Roo, CloudFoundry

Quality Assurance Hosting Search Utilities Integration with SpringSource Tools

1.3.1.1 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 shouldn't have to locate and download (even automatically) a large number of jar libraries in order to use Spring for simple use cases. For basic dependency injection there is only one mandatory external dependency, and that is for logging (see below for a more detailed description of logging options). Next we outline the basic steps needed to configure an application that depends on Spring, first with Maven and then with 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 Ivy to manage dependencies when it is building, and our samples mostly use Maven. 1.3.1.2 Maven Dependency Management If you are using Maven for dependency management you don't even need to supply the logging dependency explicitly. For example, to create an application context and use dependency
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 35/81

11/29/13

Reference Documentation

injection to configure an application, your Maven dependencies will look like this:
< d e p e n d e n c i e s > < d e p e n d e n c y > < g r o u p I d > o r g . s p r i n g f r a m e w o r k < / g r o u p I d > < a r t i f a c t I d > s p r i n g c o n t e x t < / a r t i f a c t I d > < v e r s i o n > 3 . 0 . 0 . R E L E A S E < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < / d e p e n d e n c y > < / d e p e n d e n c i e s >

That's it. Note the scope can be declared as runtime if you don't need to compile against Spring APIs, which is typically the case for basic dependency injection use cases. We used the Maven Central naming conventions in the example above, so that works with Maven Central or the SpringSource S3 Maven repository. To use the S3 Maven repository (e.g. for milestones or developer snaphots), you need to specify the repository location in your Maven configuration. For full releases:
< r e p o s i t o r i e s > < r e p o s i t o r y > < i d > c o m . s p r i n g s o u r c e . r e p o s i t o r y . m a v e n . r e l e a s e < / i d > < u r l > h t t p : / / m a v e n . s p r i n g f r a m e w o r k . o r g / r e l e a s e / < / u r l > < s n a p s h o t s > < e n a b l e d > f a l s e < / e n a b l e d > < / s n a p s h o t s > < / r e p o s i t o r y > < / r e p o s i t o r i e s >

For milestones:
< r e p o s i t o r i e s > < r e p o s i t o r y > < i d > c o m . s p r i n g s o u r c e . r e p o s i t o r y . m a v e n . m i l e s t o n e < / i d > < u r l > h t t p : / / m a v e n . s p r i n g f r a m e w o r k . o r g / m i l e s t o n e / < / u r l > < s n a p s h o t s > < e n a b l e d > f a l s e < / e n a b l e d > < / s n a p s h o t s > < / r e p o s i t o r y > < / r e p o s i t o r i e s >

And for snapshots:

< r e p o s i t o r i e s > < r e p o s i t o r y > < i d > c o m . s p r i n g s o u r c e . r e p o s i t o r y . m a v e n . s n a p s h o t < / i d > < u r l > h t t p : / / m a v e n . s p r i n g f r a m e w o r k . o r g / s n a p s h o t / < / u r l > < s n a p s h o t s > < e n a b l e d > t r u e < / e n a b l e d > < / s n a p s h o t s > < / r e p o s i t o r y > < / r e p o s i t o r i e s >

To use the SpringSource EBR you would need to use a different naming convention for the dependencies. The names are usually easy to guess, e.g. in this case it is:
< d e p e n d e n c i e s > < d e p e n d e n c y > < g r o u p I d > o r g . s p r i n g f r a m e w o r k < / g r o u p I d > < a r t i f a c t I d > o r g . s p r i n g f r a m e w o r k . c o n t e x t < / a r t i f a c t I d > < v e r s i o n > 3 . 0 . 0 . R E L E A S E < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < / d e p e n d e n c y > < / d e p e n d e n c i e s >

You also need to declare the location of the repository explicitly (only the URL is important):
< r e p o s i t o r i e s > < r e p o s i t o r y > < i d > c o m . s p r i n g s o u r c e . r e p o s i t o r y . b u n d l e s . r e l e a s e < / i d > < u r l > h t t p : / / r e p o s i t o r y . s p r i n g s o u r c e . c o m / m a v e n / b u n d l e s / r e l e a s e / < / u r l > < / r e p o s i t o r y > < / r e p o s i t o r i e s >
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 36/81

11/29/13

Reference Documentation

If you are managing your dependencies by hand, the URL in the repository declaration above is not browseable, but there is a user interface at http://www.springsource.com/repository that can be used to search for and download dependencies. It also has handy snippets of Maven and Ivy configuration that you can copy and paste if you are using those tools. 1.3.1.3 Ivy Dependency Management If you prefer to use Ivy to manage dependencies then there are similar names and configuration options. To configure Ivy to point to the SpringSource EBR add the following resolvers to your i v y s e t t i n g s . x m l :
< r e s o l v e r s > < u r ln a m e = " c o m . s p r i n g s o u r c e . r e p o s i t o r y . b u n d l e s . r e l e a s e " > < i v yp a t t e r n = " h t t p : / / r e p o s i t o r y . s p r i n g s o u r c e . c o m / i v y / b u n d l e s / r e l e a s e / [ o r g a n i s a t i o n ] / [ m o d u l e ] / [ r e v i s i o n ] / [ a r t i f a c t ] [ r e v i s i o n ] . [ e x t ] "/ > < a r t i f a c tp a t t e r n = " h t t p : / / r e p o s i t o r y . s p r i n g s o u r c e . c o m / i v y / b u n d l e s / r e l e a s e / [ o r g a n i s a t i o n ] / [ m o d u l e ] / [ r e v i s i o n ] / [ a r t i f a c t ] [ r e v i s i o n ] . [ e x t ] "/ > < / u r l > < u r ln a m e = " c o m . s p r i n g s o u r c e . r e p o s i t o r y . b u n d l e s . e x t e r n a l " > < i v yp a t t e r n = " h t t p : / / r e p o s i t o r y . s p r i n g s o u r c e . c o m / i v y / b u n d l e s / e x t e r n a l / [ o r g a n i s a t i o n ] / [ m o d u l e ] / [ r e v i s i o n ] / [ a r t i f a c t ] [ r e v i s i o n ] . [ e x t ] "/ > < a r t i f a c tp a t t e r n = " h t t p : / / r e p o s i t o r y . s p r i n g s o u r c e . c o m / i v y / b u n d l e s / e x t e r n a l / [ o r g a n i s a t i o n ] / [ m o d u l e ] / [ r e v i s i o n ] / [ a r t i f a c t ] [ r e v i s i o n ] . [ e x t ] "/ > < / u r l > < / r e s o l v e r s >

The XML above is not valid because the lines are too long - if you copy-paste then remove the extra line endings in the middle of the url patterns. Once Ivy is configured to look in the EBR adding a dependency is easy. Simply pull up the details page for the bundle in question in the repository browser and you'll find an Ivy snippet ready for you to include in your dependencies section. For example (in i v y . x m l ):
< d e p e n d e n c yo r g = " o r g . s p r i n g f r a m e w o r k " n a m e = " o r g . s p r i n g f r a m e w o r k . c o r e "r e v = " 3 . 0 . 0 . R E L E A S E "c o n f = " c o m p i l e > r u n t i m e " / >

1.3.2 Logging
Logging is a very important dependency for Spring because a) it is the only mandatory external dependency, b) everyone likes to see some output from the tools they are using, and c) Spring integrates with lots of other tools all of which have also made a choice of logging dependency. One of the goals of an application developer is often to have unified logging configured in a central place for the whole application, including all external components. This is more difficult than it might have been since there are so many choices of logging framework. The mandatory logging dependency in Spring is the Jakarta Commons Logging API (JCL). We compile against JCL and we also make JCL L o g objects visible for classes that extend the Spring Framework. It's 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 c o m m o n s l o g g i n g (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 c o m m o n s l o g g i n g , then it is from Spring and specifically from the central module called s p r i n g c o r e .
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 37/81

11/29/13

Reference Documentation

The nice thing about c o m m o n s l o g g i n g is that you don't need anything else to make your application work. It has a runtime discovery algorithm that looks for other logging frameworks in well known places on the classpath and uses one that it thinks is appropriate (or you can tell it which one if you need to). If nothing else is available you get pretty nice looking logs just from the JDK (java.util.logging or JUL for short). You should find that your Spring application works and logs happily to the console out of the box in most situations, and that's important. 1.3.2.1 Not Using Commons Logging Unfortunately, the runtime discovery algorithm in c o m m o n s l o g g i n g , while convenient for the enduser, is problematic. If we could turn back the clock and start Spring now as a new project it would use a different logging dependency. The first choice would probably be the Simple Logging Facade for Java (SLF4J), which is also used by a lot of other tools that people use with Spring inside their applications. Switching off c o m m o n s l o g g i n g is easy: just make sure it isn't on the classpath at runtime. In Maven terms you exclude the dependency, and because of the way that the Spring dependencies are declared, you only have to do that once.
< d e p e n d e n c i e s > < d e p e n d e n c y > < g r o u p I d > o r g . s p r i n g f r a m e w o r k < / g r o u p I d > < a r t i f a c t I d > s p r i n g c o n t e x t < / a r t i f a c t I d > < v e r s i o n > 3 . 0 . 0 . R E L E A S E < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < e x c l u s i o n s > < e x c l u s i o n > < g r o u p I d > c o m m o n s l o g g i n g < / g r o u p I d > < a r t i f a c t I d > c o m m o n s l o g g i n g < / a r t i f a c t I d > < / e x c l u s i o n > < / e x c l u s i o n s > < / d e p e n d e n c y > < / d e p e n d e n c i e s >

Now this application is probably broken because there is no implementation of the JCL API on the classpath, so to fix it a new one has to be provided. In the next section we show you how to provide an alternative implementation of JCL using SLF4J as an example. 1.3.2.2 Using SLF4J SLF4J is a cleaner dependency and more efficient at runtime than c o m m o n s l o g g i n g because it uses compile-time bindings instead of runtime discovery of the other logging frameworks it integrates. This also means that you have to be more explicit about what you want to happen at runtime, and declare it or configure it accordingly. SLF4J provides bindings to many common logging frameworks, so you can usually choose one that you already use, and bind to that for configuration and management. SLF4J provides bindings to many common logging frameworks, including JCL, and it also does the reverse: bridges between other logging frameworks and itself. So to use SLF4J with Spring you need to replace the c o m m o n s l o g g i n g dependency with the SLF4J-JCL bridge. Once you have done that then logging calls from within Spring will be translated into logging calls to the SLF4J API, so if other libraries in your application use that API, then you have a single place to configure and manage logging. A common choice might be to bridge Spring to SLF4J, and then provide explicit binding from SLF4J to Log4J. You need to supply 4 dependencies (and exclude the existing c o m m o n s l o g g i n g ): the bridge, the SLF4J API, the binding to Log4J, and the Log4J implementation itself. In Maven you would do that like this
< d e p e n d e n c i e s > < d e p e n d e n c y > < g r o u p I d > o r g . s p r i n g f r a m e w o r k < / g r o u p I d >
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 38/81

11/29/13

Reference Documentation

< a r t i f a c t I d > s p r i n g c o n t e x t < / a r t i f a c t I d > < v e r s i o n > 3 . 0 . 0 . R E L E A S E < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < e x c l u s i o n s > < e x c l u s i o n > < g r o u p I d > c o m m o n s l o g g i n g < / g r o u p I d > < a r t i f a c t I d > c o m m o n s l o g g i n g < / a r t i f a c t I d > < / e x c l u s i o n > < / e x c l u s i o n s > < / d e p e n d e n c y > < d e p e n d e n c y > < g r o u p I d > o r g . s l f 4 j < / g r o u p I d > < a r t i f a c t I d > j c l o v e r s l f 4 j < / a r t i f a c t I d > < v e r s i o n > 1 . 5 . 8 < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < / d e p e n d e n c y > < d e p e n d e n c y > < g r o u p I d > o r g . s l f 4 j < / g r o u p I d > < a r t i f a c t I d > s l f 4 j a p i < / a r t i f a c t I d > < v e r s i o n > 1 . 5 . 8 < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < / d e p e n d e n c y > < d e p e n d e n c y > < g r o u p I d > o r g . s l f 4 j < / g r o u p I d > < a r t i f a c t I d > s l f 4 j l o g 4 j 1 2 < / a r t i f a c t I d > < v e r s i o n > 1 . 5 . 8 < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < / d e p e n d e n c y > < d e p e n d e n c y > < g r o u p I d > l o g 4 j < / g r o u p I d > < a r t i f a c t I d > l o g 4 j < / a r t i f a c t I d > < v e r s i o n > 1 . 2 . 1 4 < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < / d e p e n d e n c y > < / d e p e n d e n c i e s >

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 c o m m o n s l o g g i n gwith respect to classloader issues, notably if you are in a strict container like an OSGi platform. Allegedly there is also a performance benefit because the bindings are at compile-time not runtime. A more common choice amongst SLF4J users, which uses fewer steps and generates fewer dependencies, is to bind directly to Logback. This removes the extra binding step because Logback implements SLF4J directly, so you only need to depend on two libaries not four (j c l o v e r s l f 4 jand l o g b a c k ). If you do that you might also need to exlude the slf4j-api dependency from other external dependencies (not Spring), because you only want one version of that API on the classpath. 1.3.2.3 Using Log4J Many people use Log4j as a logging framework for configuration and management purposes. It's efficient and well-established, and in fact it's what we use at runtime when we build and test Spring. Spring also provides some utilities for configuring 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 (c o m m o n s l o g g i n g ) all you need to do is put Log4j on the classpath, and provide it with a configuration file (l o g 4 j . p r o p e r t i e s or l o g 4 j . x m lin the root of the classpath). So for Maven users this is your dependency declaration:
< d e p e n d e n c i e s > < d e p e n d e n c y > < g r o u p I d > o r g . s p r i n g f r a m e w o r k < / g r o u p I d > < a r t i f a c t I d > s p r i n g c o n t e x t < / a r t i f a c t I d > < v e r s i o n > 3 . 0 . 0 . R E L E A S E < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < / d e p e n d e n c y > < d e p e n d e n c y > < g r o u p I d > l o g 4 j < / g r o u p I d > < a r t i f a c t I d > l o g 4 j < / a r t i f a c t I d > < v e r s i o n > 1 . 2 . 1 4 < / v e r s i o n > < s c o p e > r u n t i m e < / s c o p e > < / d e p e n d e n c y >
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 39/81

11/29/13

Reference Documentation

< / d e p e n d e n c i e s >

And here's a sample log4j.properties for logging to the console:

l o g 4 j . r o o t C a t e g o r y = I N F O ,s t d o u t l o g 4 j . a p p e n d e r . s t d o u t = o r g . a p a c h e . l o g 4 j . C o n s o l e A p p e n d e r l o g 4 j . a p p e n d e r . s t d o u t . l a y o u t = o r g . a p a c h e . l o g 4 j . P a t t e r n L a y o u t l o g 4 j . a p p e n d e r . s t d o u t . l a y o u t . C o n v e r s i o n P a t t e r n = % d { A B S O L U T E }% 5 p% t% c { 2 } : % L-% m % n l o g 4 j . c a t e g o r y . o r g . s p r i n g f r a m e w o r k . b e a n s . f a c t o r y = D E B U G 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 c o m m o n s l o g g i n g from your application is not enough in most situations. To be clear about this: the problems reported are usually not with JCL per se, or even with c o m m o n s l o g g i n g : rather they are to do with binding c o m m o n s l o g g i n g to another framework (often Log4J). This can fail because c o m m o n s l o g g i n g changed the way they do the runtime discovery in between the older versions (1.0) found in some containers and the modern versions that most people use now (1.1). Spring does not use any unusual parts of the JCL API, so nothing breaks there, but as soon as Spring or your application tries to do any logging you can find that the bindings to Log4J are not working. In such cases with WAS the easiest thing to do is to invert the class loader hierarchy (IBM calls it "parent last") so that the application controls the JCL dependency, not the container. That option isn't always open, but there are plenty of other suggestions in the public domain for alternative approaches, and your mileage may vary depending on the exact version and feature set of the container.

Part II. What's New in Spring 3

2. New Features and Enhancements in Spring 3.0
If you have been using the Spring Framework for some time, you will be aware that Spring has undergone two major revisions: Spring 2.0, released in October 2006, and Spring 2.5, released in November 2007. It is now time for a third overhaul resulting in Spring 3.0.

Java SE and Java EE Support The Spring Framework is now based on Java 5, and Java 6 is fully supported. Furthermore, Spring is compatible with J2EE 1.4 and Java EE 5, while at the same time introducing some early support for Java EE 6.

2.1 Java 5
The entire framework code has been revised to take advantage of Java 5 features like generics,
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 40/81

11/29/13

Reference Documentation

varargs and other language improvements. We have done our best to still keep the code backwards compatible. We now have consistent use of generic Collections and Maps, consistent use of generic FactoryBeans, and also consistent resolution of bridge methods in the Spring AOP API. Generic ApplicationListeners automatically receive specific event types only. All callback interfaces such as TransactionCallback and HibernateCallback declare a generic result value now. Overall, the Spring core codebase is now freshly revised and optimized for Java 5. Spring's TaskExecutor abstraction has been updated for close integration with Java 5's java.util.concurrent facilities. We provide first-class support for Callables and Futures now, as well as ExecutorService adapters, ThreadFactory integration, etc. This has been aligned with JSR236 (Concurrency Utilities for Java EE 6) as far as possible. Furthermore, we provide support for asynchronous method invocations through the use of the new @Async annotation (or EJB 3.1's @Asynchronous annotation).

2.2 Improved documentation

The Spring reference documentation has also substantially been updated to reflect all of the changes and new features for Spring 3.0. While every effort has been made to ensure that there are no errors in this documentation, some errors may nevertheless have crept in. If you do spot any typos or even more serious errors, and you can spare a few cycles during lunch, please do bring the error to the attention of the Spring team by raising an issue.

2.3 New articles and tutorials

There are many excellent articles and tutorials that show how to get started with Spring 3 features. Read them at the Spring Documentation page. The samples have been improved and updated to take advantage of the new features in Spring 3. Additionally, the samples have been moved out of the source tree into a dedicated SVN repository available at:
h t t p s : / / a n o n s v n . s p r i n g f r a m e w o r k . o r g / s v n / s p r i n g s a m p l e s /

As such, the samples are no longer distributed alongside Spring 3 and need to be downloaded separately from the repository mentioned above. However, this documentation will continue to refer to some samples (in particular Petclinic) to illustrate various features. Note For more information on Subversion (or in short SVN), see the project homepage at: h t t p : / / s u b v e r s i o n . a p a c h e . o r g /

2.4 New module organization and build system

The framework modules have been revised and are now managed separately with one sourcetree per module jar: org.springframework.aop org.springframework.beans org.springframework.context org.springframework.context.support org.springframework.expression org.springframework.instrument
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 41/81

11/29/13

Reference Documentation

org.springframework.jdbc org.springframework.jms org.springframework.orm org.springframework.oxm org.springframework.test org.springframework.transaction org.springframework.web org.springframework.web.portlet org.springframework.web.servlet org.springframework.web.struts We are now using a new Spring build system as known from Spring Web Flow 2.0. This gives us: Ivy-based "Spring Build" system consistent deployment procedure consistent dependency management consistent generation of OSGi manifests

Note: The spring.jar artifact that contained almost the entire framework is no longer provided.

2.5 Overview of new features

This is a list of new features for Spring 3.0. We will cover these features in more detail later in this section. Spring Expression Language IoC enhancements/Java based bean metadata General-purpose type conversion system and field formatting system Object to XML mapping functionality (OXM) moved from Spring Web Services project Comprehensive REST support @MVC additions Declarative model validation Early support for Java EE 6 Embedded database support

2.5.1 Core APIs updated for Java 5

BeanFactory interface returns typed bean instances as far as possible: T getBean(Class<T> requiredType) T getBean(String name, Class<T> requiredType)
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 42/81

11/29/13

Reference Documentation

Map<String, T> getBeansOfType(Class<T> type) Spring's TaskExecutor interface now extends j a v a . u t i l . c o n c u r r e n t . E x e c u t o r : extended AsyncTaskExecutor supports standard Callables with Futures New Java 5 based converter API and SPI: stateless ConversionService and Converters superseding standard JDK PropertyEditors Typed ApplicationListener<E>

2.5.2 Spring Expression Language

Spring introduces an expression language which is similar to Unified EL in its syntax but offers significantly more features. The expression language can be used when defining XML and Annotation based bean definitions and also serves as the foundation for expression language support across the Spring portfolio. Details of this new functionality can be found in the chapter Spring Expression Language (SpEL). The Spring Expression Language was created to provide the Spring community 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 SpringSource Tool Suite. The following is an example of how the Expression Language can be used to configure some properties of a database setup
< b e a nc l a s s = " m y c o m p a n y . R e w a r d s T e s t D a t a b a s e " > < p r o p e r t yn a m e = " d a t a b a s e N a m e " v a l u e = " # { s y s t e m P r o p e r t i e s . d a t a b a s e N a m e } " / > < p r o p e r t yn a m e = " k e y G e n e r a t o r " v a l u e = " # { s t r a t e g y B e a n . d a t a b a s e K e y G e n e r a t o r } " / > < / b e a n >

This functionality is also available if you prefer to configure your components using annotations:
@ R e p o s i t o r y p u b l i cc l a s sR e w a r d s T e s t D a t a b a s e{ @ V a l u e ( " # { s y s t e m P r o p e r t i e s . d a t a b a s e N a m e } " ) p u b l i cv o i ds e t D a t a b a s e N a m e ( S t r i n gd b N a m e ){} @ V a l u e ( " # { s t r a t e g y B e a n . d a t a b a s e K e y G e n e r a t o r } " ) p u b l i cv o i ds e t K e y G e n e r a t o r ( K e y G e n e r a t o rk g ){}

2.5.3 The Inversion of Control (IoC) container

2.5.3.1 Java based bean metadata Some core features from the JavaConfig project have been added to the Spring Framework now. This means that the following annotations are now directly supported: @Configuration @Bean @DependsOn
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 43/81

11/29/13

Reference Documentation

@Primary @Lazy @Import @ImportResource @Value Here is an example of a Java class providing basic configuration using the new JavaConfig features:
p a c k a g eo r g . e x a m p l e . c o n f i g ; @ C o n f i g u r a t i o n p u b l i cc l a s sA p p C o n f i g{ p r i v a t e@ V a l u e ( " # { j d b c P r o p e r t i e s . u r l } " )S t r i n gj d b c U r l ; p r i v a t e@ V a l u e ( " # { j d b c P r o p e r t i e s . u s e r n a m e } " )S t r i n gu s e r n a m e ; p r i v a t e@ V a l u e ( " # { j d b c P r o p e r t i e s . p a s s w o r d } " )S t r i n gp a s s w o r d ; @ B e a n p u b l i cF o o S e r v i c ef o o S e r v i c e ( ){ r e t u r nn e wF o o S e r v i c e I m p l ( f o o R e p o s i t o r y ( ) ) ; } @ B e a n p u b l i cF o o R e p o s i t o r yf o o R e p o s i t o r y ( ){ r e t u r nn e wH i b e r n a t e F o o R e p o s i t o r y ( s e s s i o n F a c t o r y ( ) ) ; } @ B e a n p u b l i cS e s s i o n F a c t o r ys e s s i o n F a c t o r y ( ){ / /w i r eu pas e s s i o nf a c t o r y A n n o t a t i o n S e s s i o n F a c t o r y B e a na s F a c t o r y B e a n= n e wA n n o t a t i o n S e s s i o n F a c t o r y B e a n ( ) ; a s F a c t o r y B e a n . s e t D a t a S o u r c e ( d a t a S o u r c e ( ) ) ; / /a d d i t i o n a lc o n f i g r e t u r na s F a c t o r y B e a n . g e t O b j e c t ( ) ; } @ B e a n p u b l i cD a t a S o u r c ed a t a S o u r c e ( ){ r e t u r nn e wD r i v e r M a n a g e r D a t a S o u r c e ( j d b c U r l ,u s e r n a m e ,p a s s w o r d ) ; }

To get this to work you need to add the following component scanning entry in your minimal application context XML file.
< c o n t e x t : c o m p o n e n t s c a nb a s e p a c k a g e = " o r g . e x a m p l e . c o n f i g " / > < u t i l : p r o p e r t i e si d = " j d b c P r o p e r t i e s "l o c a t i o n = " c l a s s p a t h : o r g / e x a m p l e / c o n f i g / j d b c . p r o p e r t i e s " / >

Or

you

can

bootstrap

@ C o n f i g u r a t i o n

class

directly

using

A n n o t a t i o n C o n f i g A p p l i c a t i o n C o n t e x t : p u b l i cs t a t i cv o i dm a i n ( S t r i n g [ ]a r g s ){ A p p l i c a t i o n C o n t e x tc t x=n e wA n n o t a t i o n C o n f i g A p p l i c a t i o n C o n t e x t ( A p p C o n f i g . c l a s s ) ; F o o S e r v i c ef o o S e r v i c e=c t x . g e t B e a n ( F o o S e r v i c e . c l a s s ) ; f o o S e r v i c e . d o S t u f f ( ) ; }

See Section 4.12.2, Instantiating AnnotationConfigApplicationContext for A n n o t a t i o n C o n f i g A p p l i c a t i o n C o n t e x t .

the full

Spring

container information

using on

2.5.3.2 Defining bean metadata within components

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 44/81

11/29/13

Reference Documentation

@ B e a n annotated

methods are also supported inside Spring components. They contribute a factory bean definition to the container. See Defining bean metadata within components for more information

2.5.4 General purpose type conversion system and field formatting system
A general purpose type conversion system has been introduced. The system is currently used by SpEL for type conversion, and may also be used by a Spring Container and DataBinder when binding bean property values. In addition, a formatter SPI has been introduced for formatting field values. This SPI provides a simpler and more robust alternative to JavaBean PropertyEditors for use in client environments such as Spring MVC.

2.5.5 The Data Tier

Object to XML mapping functionality (OXM) from the Spring Web Services project has been moved to the core Spring Framework now. The functionality is found in the o r g . s p r i n g f r a m e w o r k . o x mpackage. More information on the use of the O X Mmodule can be found in the Marshalling XML using O/X Mappers chapter.

2.5.6 The Web Tier

The most exciting new feature for the Web Tier is the support for building RESTful web services and web applications. There are also some new annotations that can be used in any web application. 2.5.6.1 Comprehensive REST support Server-side support for building RESTful applications has been provided as an extension of the existing annotation driven MVC web framework. Client-side support is provided by the R e s t T e m p l a t e class in the spirit of other template classes such as J d b c T e m p l a t e and J m s T e m p l a t e . Both server and client side REST functionality make use of H t t p C o n v e r t e r s to facilitate the conversion between objects and their representation in HTTP requests and responses. The M a r s h a l l i n g H t t p M e s s a g e C o n v e r t e r uses the Object to XML mapping functionality mentioned earlier. Refer to the sections on MVC and the RestTemplate for more information. 2.5.6.2 @MVC additions Am v cnamespace has been introduced that greatly simplifies Spring MVC configuration. Additional annotations such as @ C o o k i e V a l u e and @ R e q u e s t H e a d e r s have been added. See Mapping cookie values with the @CookieValue annotation and Mapping request header attributes with the @RequestHeader annotation for more information.

2.5.7 Declarative model validation

Several validation enhancements, including JSR 303 support that uses Hibernate Validator as the default provider.

2.5.8 Early support for Java EE 6

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 45/81

11/29/13

Reference Documentation

We provide support for asynchronous method invocations through the use of the new @Async annotation (or EJB 3.1's @Asynchronous annotation). JSR 303, JSF 2.0, JPA 2.0, etc

2.5.9 Support for embedded databases

Convenient support for embedded Java database engines, including HSQL, H2, and Derby, is now provided.

3. New Features and Enhancements in Spring 3.1

Building on the support introduced in Spring 3.0, Spring 3.1 is currently under development, and at the time of this writing Spring 3.1 RC1 is being prepared for release.

3.1 Overview of new features

This is a list of new features for Spring 3.1. Most features do not yet have dedicated reference documentation but do have Javadoc. In such cases, fully-qualified class names are given. See also Appendix B, Migrating to Spring Framework 3.1

3.1.1 Cache Abstraction

Chapter 28, Cache Abstraction Cache Abstraction (SpringSource team blog)

3.1.2 Bean Definition Profiles

XML profiles (SpringSource Team Blog) Introducing @Profile (SpringSource Team Blog) See org.springframework.context.annotation.Configuration Javadoc See org.springframework.context.annotation.Profile Javadoc

3.1.3 Environment Abstraction

Environment Abstraction (SpringSource Team Blog) See org.springframework.core.env.Environment Javadoc

3.1.4 PropertySource Abstraction

Unified Property Management (SpringSource Team Blog) See org.springframework.core.env.Environment Javadoc See org.springframework.core.env.PropertySource Javadoc See org.springframework.context.annotation.PropertySource Javadoc

3.1.5 Code equivalents for Spring's XML namespaces

Code-based equivalents to popular Spring XML namespace elements <context:componentdocs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 46/81

11/29/13

Reference Documentation

scan/>, <tx:annotation-driven/> and <mvc:annotation-driven> have been developed, most in the form of @ E n a b l e annotations. These are designed for use in conjunction with Spring's @ C o n f i g u r a t i o nclasses, which were introduced in Spring 3.0. See org.springframework.context.annotation.Configuration Javadoc See org.springframework.context.annotation.ComponentScan Javadoc See org.springframework.transaction.annotation.EnableTransactionManagement Javadoc See org.springframework.cache.annotation.EnableCaching Javadoc See org.springframework.web.servlet.config.annotation.EnableWebMvc Javadoc See org.springframework.scheduling.annotation.EnableScheduling Javadoc See org.springframework.scheduling.annotation.EnableAsync Javadoc See org.springframework.context.annotation.EnableAspectJAutoProxy Javadoc See org.springframework.context.annotation.EnableLoadTimeWeaving Javadoc See org.springframework.beans.factory.aspectj.EnableSpringConfigured Javadoc

3.1.6 Support for Hibernate 4.x

See Javadoc for classes within the new org.springframework.orm.hibernate4 package

3.1.7 TestContext framework support for @Configuration classes and bean definition profiles
The @ C o n t e x t C o n f i g u r a t i o n annotation now supports supplying @ C o n f i g u r a t i o n classes for configuring the Spring T e s t C o n t e x t . In addition, a new @ A c t i v e P r o f i l e s annotation has been introduced to support declarative configuration of active bean definition profiles in A p p l i c a t i o n C o n t e x tintegration tests. Spring 3.1 M2: Testing with @Configuration Classes and Profiles (SpringSource Team Blog) See Section 10.3.5, Spring TestContext Framework See the section called Context configuration with @Configuration classes and o r g . s p r i n g f r a m e w o r k . t e s t . c o n t e x t . C o n t e x t C o n f i g u r a t i o nJavadoc See o r g . s p r i n g f r a m e w o r k . t e s t . c o n t e x t . A c t i v e P r o f i l e sJavadoc See o r g . s p r i n g f r a m e w o r k . t e s t . c o n t e x t . S m a r t C o n t e x t L o a d e rJavadoc See o r g . s p r i n g f r a m e w o r k . t e s t . c o n t e x t . s u p p o r t . D e l e g a t i n g S m a r t C o n t e x t L o a d e r Javadoc See o r g . s p r i n g f r a m e w o r k . t e s t . c o n t e x t . s u p p o r t . A n n o t a t i o n C o n f i g C o n t e x t L o a d e r Javadoc

3.1.8 c: namespace for more concise constructor injection

Section 4.4.2.7, XML shortcut with the c-namespace

3.1.9 Support for injection against non-standard JavaBeans setters

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 47/81

11/29/13

Reference Documentation

Prior to Spring 3.1, in order to inject against a property method it had to conform strictly to JavaBeans property signature rules, namely that any 'setter' method must be void-returning. It is now possible in Spring XML to specify setter methods that return any object type. This is useful when considering designing APIs for method-chaining, where setter methods return a reference to 'this'.

3.1.10 Support for Servlet 3 code-based configuration of Servlet Container

The new W e b A p p l i c a t i o n I n i t i a l i z e r builds atop Servlet 3.0's S e r v l e t C o n t a i n e r I n i t i a l i z e r support to provide a programmatic alternative to the traditional web.xml. See org.springframework.web.WebApplicationInitializer Javadoc Diff from Spring's Greenhouse reference application demonstrating migration from web.xml to W e b A p p l i c a t i o n I n i t i a l i z e r

3.1.11 Support for Servlet 3 MultipartResolver

See org.springframework.web.multipart.support.StandardServletMultipartResolver Javadoc

3.1.12 JPA EntityManagerFactory bootstrapping without persistence.xml

In standard JPA, persistence units get defined through M E T A I N F / p e r s i s t e n c e . x m l files in specific jar files which will in turn get searched for @ E n t i t y classes. In many cases, persistence.xml does not contain more than a unit name and relies on defaults and/or external setup for all other concerns (such as the DataSource to use, etc). For that reason, Spring 3.1 provides an alternative: L o c a l C o n t a i n e r E n t i t y M a n a g e r F a c t o r y B e a n accepts a 'packagesToScan' property, specifying base packages to scan for @ E n t i t y classes. This is analogous to A n n o t a t i o n S e s s i o n F a c t o r y B e a n 's property of the same name for native Hibernate setup, and also to Spring's component-scan feature for regular Spring beans. Effectively, this allows for XML-free JPA setup at the mere expense of specifying a base package for entity scanning: a particularly fine match for Spring applications which rely on component scanning for Spring beans as well, possibly even bootstrapped using a code-based Servlet 3.0 initializer.

3.1.13 New HandlerMethod-based Support Classes For Annotated Controller Processing

Spring 3.1 introduces a new set of support classes for processing requests with annotated controllers:
R e q u e s t M a p p i n g H a n d l e r M a p p i n g R e q u e s t M a p p i n g H a n d l e r A d a p t e r E x c e p t i o n H a n d l e r E x c e p t i o n R e s o l v e r

These classes are a replacement for the existing:

D e f a u l t A n n o t a t i o n H a n d l e r M a p p i n g A n n o t a t i o n M e t h o d H a n d l e r A d a p t e r A n n o t a t i o n M e t h o d H a n d l e r E x c e p t i o n R e s o l v e r

The new classes were developed in response to many requests to make annotation controller support classes more customizable and open for extension. Whereas previously you could
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 48/81

11/29/13

Reference Documentation

configure a custom annotated controller method argument resolver, with the new support classes you can customize the processing for any supported method argument or return value type. See org.springframework.web.method.support.HandlerMethodArgumentResolver Javadoc See Javadoc org.springframework.web.method.support.HandlerMethodReturnValueHandler

A second notable difference is the introduction of a H a n d l e r M e t h o d abstraction to represent an @RequestMapping method. This abstraction is used throughout by the new support classes as the h a n d l e rinstance. For example a H a n d l e r I n t e r c e p t o rcan cast the h a n d l e r from O b j e c t to H a n d l e r M e t h o dand get access to the target controller method, its annotations, etc. The new classes are enabled by default by the MVC namespace and by Java-based configuration via @EnableWebMvc. The existing classes will continue to be available but use of the new classes is recommended going forward. See Section 16.3.2.1, New Support Classes for @RequestMapping methods in Spring MVC 3.1 for additional details and a list of features not available with the new support classes.

3.1.14 "consumes" and "produces" conditions in @RequestMapping

Improved support for specifying media types consumed by a method through the ' C o n t e n t T y p e ' header as well as for producible types specified through the ' A c c e p t ' header. See Section 16.3.2.5, Consumable Media Types and Section 16.3.2.6, Producible Media Types

3.1.15 Flash Attributes and R e d i r e c t A t t r i b u t e s

Flash attributes can now be stored in a F l a s h M a p and saved in the HTTP session to survive a redirect. For an overview of the general support for flash attributes in Spring MVC see Section 16.6, Using flash attributes. In annotated controllers, an @ R e q u e s t M a p p i n g method can add flash attributes by declaring a method argument of type R e d i r e c t A t t r i b u t e s . This method argument can now also be used to get precise control over the attributes used in a redirect scenario. See Section 16.3.3.10, Specifying redirect and flash attributes for more details.

3.1.16 URI Template Variable Enhancements

URI template variables from the current request are used in more places: URI template variables are used in addition to request parameters when binding a request to @ M o d e l A t t r i b u t emethod arguments. @PathVariable method argument values are merged into the model before rendering, except in views that generate content in an automated fashion such as JSON serialization or XML marshalling. contain placeholders for URI variables (e.g. When expanding the placeholders, URI template variables from the current request are automatically considered.
" r e d i r e c t : / b l o g / { y e a r } / { m o n t h } " ).

redirect

string

can

An @ M o d e l A t t r i b u t e method argument can be instantiated from a URI template variable provided there is a registered Converter or PropertyEditor to convert from a String to the target object type.

3.1.17 @ V a l i dOn @RequestBody Controller Method Arguments

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 49/81

11/29/13

Reference Documentation

An @RequestBody method argument can be annotated with @Valid to invoke automatic validation similar to the support for @ModelAttribute method arguments. A resulting M e t h o d A r g u m e n t N o t V a l i d E x c e p t i o n is handled in the D e f a u l t H a n d l e r E x c e p t i o n R e s o l v e r and results in a 4 0 0response code.

3.1.18 @ R e q u e s t P a r tAnnotation On Controller Method Arguments

This new annotation provides access to the content of a "multipart/form-data" request part. See Section 16.10.5, Handling a file upload request from programmatic clients and Section 16.10, Spring's multipart (file upload) support.

3.1.19 U r i C o m p o n e n t s B u i l d e rand U r i C o m p o n e n t s
A new U r i C o m p o n e n t s class has been added, which is an immutable container of URI components providing access to all contained URI components. A new U r i C o m p o n e n t s B u i l d e r class is also provided to help create U r i C o m p o n e n t s instances. Together the two classes give fine-grained control over all aspects of preparing a URI including construction, expansion from URI template variables, and encoding. In most cases the new classes can be used as a more flexible alternative to the existing U r i T e m p l a t eespecially since U r i T e m p l a t erelies on those same classes internally. AS e r v l e t U r i C o m p o n e n t s B u i l d e rsub-class provides static factory methods to copy information from a Servlet request. See Section 16.7, Building URIs.

Part III. Core Technologies

This part of the reference documentation covers all of those technologies that are absolutely integral to the Spring Framework. Foremost amongst these is the Spring Framework's Inversion of Control (IoC) container. A thorough treatment of the Spring Framework's IoC container is closely followed by comprehensive coverage of Spring's 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 Spring's integration with AspectJ (currently the richest - in terms of features - and certainly most mature AOP implementation in the Java enterprise space) is also provided. Finally, the adoption of the test-driven-development (TDD) approach to software development is certainly advocated by the Spring team, and so coverage of Spring's 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. Chapter 4, The IoC container Chapter 5, Resources Chapter 6, Validation, Data Binding, and Type Conversion Chapter 7, Spring Expression Language (SpEL) Chapter 8, Aspect Oriented Programming with Spring
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 50/81

11/29/13

Reference Documentation

Chapter 9, Spring AOP APIs Chapter 10, Testing

4. The IoC container 4.1 Introduction to the Spring IoC container and beans
This chapter covers the Spring Framework implementation of the Inversion of Control (IoC) [1]principle. IoC is also known as dependency injection (DI). It is a process whereby objects define their dependencies, that is, the other objects they work with, only through constructor arguments, arguments to a factory method, or properties that are set on the object instance after it is constructed or returned from a factory method. The container then injects those dependencies when it creates the bean. This process is fundamentally the inverse, hence the name Inversion of Control (IoC), of the bean itself controlling the instantiation or location of its dependencies by using direct construction of classes, or a mechanism such as the Service Locator pattern. The o r g . s p r i n g f r a m e w o r k . b e a n s and o r g . s p r i n g f r a m e w o r k . c o n t e x t packages are the basis for Spring Framework's IoC container. The B e a n F a c t o r y interface provides an advanced configuration mechanism capable of managing any type of object. A p p l i c a t i o n C o n t e x tis a subinterface of B e a n F a c t o r y . It adds easier integration with Spring's AOP features; message resource handling (for use in internationalization), event publication; and application-layer specific contexts such as the W e b A p p l i c a t i o n C o n t e x tfor use in web applications. In short, the B e a n F a c t o r y provides the configuration framework and basic functionality, and the A p p l i c a t i o n C o n t e x t adds more enterprise-specific functionality. The A p p l i c a t i o n C o n t e x t is a complete superset of the B e a n F a c t o r y , and is used exclusively in this chapter in descriptions of Spring's IoC container. For more information on using the B e a n F a c t o r y instead of the A p p l i c a t i o n C o n t e x t ,refer to Section 4.15, The BeanFactory. In Spring, the objects that form the backbone of your application and that are managed by the Spring IoC container are called beans. A bean is an object that is instantiated, assembled, and otherwise managed by a Spring IoC container. Otherwise, a bean is simply one of many objects in your application. Beans, and the dependencies among them, are reflected in the configuration metadata used by a container.

4.2 Container overview

The interface o r g . s p r i n g f r a m e w o r k . c o n t e x t . A p p l i c a t i o n C o n t e x t represents the Spring IoC container and is responsible for instantiating, configuring, and assembling the aforementioned beans. The container gets its instructions on what objects to instantiate, configure, and assemble by reading configuration metadata. The configuration metadata is represented in XML, Java annotations, or Java code. It allows you to express the objects that compose your application and the rich interdependencies between such objects. Several implementations of the A p p l i c a t i o n C o n t e x t interface are supplied out-of-the-box with Spring. In standalone applications it is common to create an instance of C l a s s P a t h X m l A p p l i c a t i o n C o n t e x tor F i l e S y s t e m X m l A p p l i c a t i o n C o n t e x t . While XML has been the traditional format for defining configuration metadata you can instruct the container to use Java annotations or code as the metadata format by providng a small amount of XML configuration to declaratively enable support for these additional metadata formats. In most application scenarios, explicit user code is not required to instantiate one or more instances of a Spring IoC container. For example, in a web application scenario, a simple eight (or so) lines of boilerplate J2EE web descriptor XML in the w e b . x m l file of the application will
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 51/81

11/29/13

Reference Documentation

typically suffice (see Section 4.14.4, Convenient ApplicationContext instantiation for web applications). If you are using the SpringSource Tool Suite Eclipse-powered development environment or Spring Roo this boilerplate configuration can be easily created with few mouse clicks or keystrokes. The following diagram is a high-level view of how Spring works. Your application classes are combined with configuration metadata so that after the A p p l i c a t i o n C o n t e x t is created and initialized, you have a fully configured and executable system or application.

The Spring IoC container

4.2.1 Configuration metadata

As the preceding diagram shows, the Spring IoC container consumes a form of configuration metadata; this configuration metadata represents how you as an application developer tell the Spring container to instantiate, configure, and assemble the objects in your application. Configuration metadata is traditionally supplied in a simple and intuitive XML format, which is what most of this chapter uses to convey key concepts and features of the Spring IoC container. Note XML-based metadata is not the only allowed form of configuration metadata. The Spring IoC container itself is totally decoupled from the format in which this configuration metadata is actually written. For information about using other forms of metadata with the Spring container, see: Annotation-based configuration: Spring 2.5 introduced support for annotation-based configuration metadata. Java-based configuration: Starting with Spring 3.0, many features provided by the Spring JavaConfig project became part of the core Spring Framework. Thus you can define beans external to your application classes by using Java rather than XML files. To use these new features, see the @ C o n f i g u r a t i o n ,@ B e a n ,@ I m p o r tand @ D e p e n d s O nannotations. Spring configuration consists of at least one and typically more than one bean definition that the container must manage. XML-based configuration metadata shows these beans configured as
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 52/81

11/29/13

Reference Documentation

< b e a n / >elements

inside a top-level < b e a n s / >element.

These bean definitions correspond to the actual objects that make up your application. Typically you define service layer objects, data access objects (DAOs), presentation objects such as Struts A c t i o n instances, infrastructure objects such as Hibernate S e s s i o n F a c t o r i e s , JMS Q u e u e s , and so forth. Typically one does not configure fine-grained domain objects in the container, because it is usually the responsibility of DAOs and business logic to create and load domain objects. However, you can use Spring's integration with AspectJ to configure objects that have been created outside the control of an IoC container. See Using AspectJ to dependencyinject domain objects with Spring. The following example shows the basic structure of XML-based configuration metadata:
< ? x m lv e r s i o n = " 1 . 0 "e n c o d i n g = " U T F 8 " ? > < b e a n sx m l n s = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s " x m l n s : x s i = " h t t p : / / w w w . w 3 . o r g / 2 0 0 1 / X M L S c h e m a i n s t a n c e " x s i : s c h e m a L o c a t i o n = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s / s p r i n g b e a n s . x s d " > < b e a ni d = " . . . "c l a s s = " . . . " > < ! -c o l l a b o r a t o r sa n dc o n f i g u r a t i o nf o rt h i sb e a ng oh e r e> < / b e a n > < b e a ni d = " . . . "c l a s s = " . . . " > < ! -c o l l a b o r a t o r sa n dc o n f i g u r a t i o nf o rt h i sb e a ng oh e r e> < / b e a n > < ! -m o r eb e a nd e f i n i t i o n sg oh e r e> < / b e a n s >

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

4.2.2 Instantiating a container

Instantiating a Spring IoC container is straightforward. The location path or paths supplied to an A p p l i c a t i o n C o n t e x t constructor are actually resource strings that allow the container to load configuration metadata from a variety of external resources such as the local file system, from the Java C L A S S P A T H , and so on.
A p p l i c a t i o n C o n t e x tc o n t e x t= n e wC l a s s P a t h X m l A p p l i c a t i o n C o n t e x t ( n e wS t r i n g [ ]{ " s e r v i c e s . x m l " ," d a o s . x m l " } ) ;

Note After you learn about Spring's IoC container, you may want to know more about Spring's R e s o u r c eabstraction, as described in Chapter 5, Resources, which provides a convenient mechanism for reading an InputSream from locations defined in a URI syntax. In particular, R e s o u r c e paths are used to construct applications contexts as described in Section 5.7, Application contexts and Resource paths. The following example shows the service layer objects ( s e r v i c e s . x m l )configuration file:
< ? x m lv e r s i o n = " 1 . 0 "e n c o d i n g = " U T F 8 " ? > < b e a n sx m l n s = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s " x m l n s : x s i = " h t t p : / / w w w . w 3 . o r g / 2 0 0 1 / X M L S c h e m a i n s t a n c e " x s i : s c h e m a L o c a t i o n = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s / s p r i n g b e a n s . x s d " > < ! -s e r v i c e s>
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 53/81

11/29/13

Reference Documentation

< b e a ni d = " p e t S t o r e " c l a s s = " o r g . s p r i n g f r a m e w o r k . s a m p l e s . j p e t s t o r e . s e r v i c e s . P e t S t o r e S e r v i c e I m p l " > < p r o p e r t yn a m e = " a c c o u n t D a o "r e f = " a c c o u n t D a o " / > < p r o p e r t yn a m e = " i t e m D a o "r e f = " i t e m D a o " / > < ! -a d d i t i o n a lc o l l a b o r a t o r sa n dc o n f i g u r a t i o nf o rt h i sb e a ng oh e r e> < / b e a n > < ! -m o r eb e a nd e f i n i t i o n sf o rs e r v i c e sg oh e r e> < / b e a n s >

The following example shows the data access objects d a o s . x m lfile:

< ? x m lv e r s i o n = " 1 . 0 "e n c o d i n g = " U T F 8 " ? > < b e a n sx m l n s = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s " x m l n s : x s i = " h t t p : / / w w w . w 3 . o r g / 2 0 0 1 / X M L S c h e m a i n s t a n c e " x s i : s c h e m a L o c a t i o n = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s / s p r i n g b e a n s . x s d " > < b e a ni d = " a c c o u n t D a o " c l a s s = " o r g . s p r i n g f r a m e w o r k . s a m p l e s . j p e t s t o r e . d a o . i b a t i s . S q l M a p A c c o u n t D a o " > < ! -a d d i t i o n a lc o l l a b o r a t o r sa n dc o n f i g u r a t i o nf o rt h i sb e a ng oh e r e> < / b e a n > < b e a ni d = " i t e m D a o "c l a s s = " o r g . s p r i n g f r a m e w o r k . s a m p l e s . j p e t s t o r e . d a o . i b a t i s . S q l M a p I t e m D a o " > < ! -a d d i t i o n a lc o l l a b o r a t o r sa n dc o n f i g u r a t i o nf o rt h i sb e a ng oh e r e> < / b e a n > < ! -m o r eb e a nd e f i n i t i o n sf o rd a t aa c c e s so b j e c t sg oh e r e> < / b e a n s >

In the preceding example, the service layer consists of the class P e t S t o r e S e r v i c e I m p l , and two data access objects of the type S q l M a p A c c o u n t D a oand SqlMapItemDao are based on the iBatis Object/Relational mapping framework. The p r o p e r t y n a m e element refers to the name of the JavaBean property, and the r e f element refers to the name of another bean definition. This linkage between id and ref elements expresses the dependency between collaborating objects. For details of configuring an object's dependencies, see Dependencies. 4.2.2.1 Composing XML-based configuration metadata It can be useful to have bean definitions span multiple XML files. Often each individual XML configuration file represents a logical layer or module in your architecture. You can use the application context constructor to load bean definitions from all these XML fragments. This constructor takes multiple R e s o u r c e locations, as was shown in the previous section. Alternatively, use one or more occurrences of the < i m p o r t / > element to load bean definitions from another file or files. For example:
< b e a n s > < i m p o r tr e s o u r c e = " s e r v i c e s . x m l " / > < i m p o r tr e s o u r c e = " r e s o u r c e s / m e s s a g e S o u r c e . x m l " / > < i m p o r tr e s o u r c e = " / r e s o u r c e s / t h e m e S o u r c e . x m l " / > < b e a ni d = " b e a n 1 "c l a s s = " . . . " / > < b e a ni d = " b e a n 2 "c l a s s = " . . . " / > < / b e a n s >

In the preceding example, external bean definitions are loaded from three files, s e r v i c e s . x m l , m e s s a g e S o u r c e . x m l , and t h e m e S o u r c e . x m l . All location paths are relative to the definition file doing the importing, so s e r v i c e s . x m lmust be in the same directory or classpath location as the file doing the importing, while m e s s a g e S o u r c e . x m land t h e m e S o u r c e . x m lmust be in a r e s o u r c e s location below the location of the importing file. As you can see, a leading slash is ignored, but given that these paths are relative, it is better form not to use the slash at all. The contents of the files being imported, including the top level < b e a n s / > element, must be valid XML bean
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 54/81

11/29/13

Reference Documentation

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

4.2.3 Using the container

The A p p l i c a t i o n C o n t e x t is the interface for an advanced factory capable of maintaining a registry of different beans and their dependencies. Using the method T g e t B e a n ( S t r i n gn a m e , C l a s s < T >r e q u i r e d T y p e )you can retrieve instances of your beans. The A p p l i c a t i o n C o n t e x tenables you to read bean definitions and access them as follows:
/ /c r e a t ea n dc o n f i g u r eb e a n s A p p l i c a t i o n C o n t e x tc o n t e x t= n e wC l a s s P a t h X m l A p p l i c a t i o n C o n t e x t ( n e wS t r i n g [ ]{ " s e r v i c e s . x m l " ," d a o s . x m l " } ) ; / /r e t r i e v ec o n f i g u r e di n s t a n c e P e t S t o r e S e r v i c e I m p ls e r v i c e=c o n t e x t . g e t B e a n ( " p e t S t o r e " ,P e t S t o r e S e r v i c e I m p l . c l a s s ) ; / /u s ec o n f i g u r e di n s t a n c e L i s tu s e r L i s ts e r v i c e . g e t U s e r n a m e L i s t ( ) ;

You use g e t B e a n ( )to retrieve instances of your beans. The A p p l i c a t i o n C o n t e x tinterface has a few other methods for retrieving beans, but ideally your application code should never use them. Indeed, your application code should have no calls to the g e t B e a n ( ) method at all, and thus no dependency on Spring APIs at all. For example, Spring's integration with web frameworks provides for dependency injection for various web framework classes such as controllers and JSF-managed beans.

4.3 Bean overview

A Spring IoC container manages one or more beans. These beans are created with the configuration metadata that you supply to the container, for example, in the form of XML < b e a n / > definitions. Within the container itself, these bean definitions are represented as B e a n D e f i n i t i o n objects, which contain (among other information) the following metadata: A package-qualified class name: typically the actual implementation class of the bean being defined. Bean behavioral configuration elements, which state how the bean should behave in the container (scope, lifecycle callbacks, and so forth).
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 55/81

11/29/13

Reference Documentation

References to other beans that are needed for the bean to do its work; these references are also called collaborators or dependencies. Other configuration settings to set in the newly created object, for example, the number of connections to use in a bean that manages a connection pool, or the size limit of the pool. This metadata translates to a set of properties that make up each bean definition.

Table 4.1. The bean definition Property class name scope constructor arguments properties autowiring mode lazy-initialization mode initialization method destruction method Explained in... Section 4.3.2, Instantiating beans Section 4.3.1, Naming beans Section 4.5, Bean scopes Section 4.4.1, Dependency injection Section 4.4.1, Dependency injection Section 4.4.5, Autowiring collaborators Section 4.4.4, Lazy-initialized beans Section 4.6.1.1, Initialization callbacks Section 4.6.1.2, Destruction callbacks

In addition to bean definitions that contain information on how to create a specific bean, the A p p l i c a t i o n C o n t e x t implementations also permit the registration of existing objects that are created outside the container, by users. This is done by accessing the ApplicationContext's BeanFactory via the method g e t B e a n F a c t o r y ( ) which returns the BeanFactory implementation D e f a u l t L i s t a b l e B e a n F a c t o r y .D e f a u l t L i s t a b l e B e a n F a c t o r y supports this registration through the methods r e g i s t e r S i n g l e t o n ( . . ) and r e g i s t e r B e a n D e f i n i t i o n ( . . ) . However, typical applications work solely with beans defined through metadata bean definitions.

4.3.1 Naming beans

Every bean has one or more identifiers. These identifiers must be unique within the container that hosts the bean. A bean usually has only one identifier, but if it requires more than one, the extra ones can be considered aliases. In XML-based configuration metadata, you use the i dand/or n a m eattributes to specify the bean identifier(s). The i dattribute allows you to specify exactly one id. Conventionally these names are alphanumeric ('myBean', 'fooService', etc), but may special characters as well. If you want to introduce other aliases to the bean, you can also specify them in the n a m eattribute, separated by a comma (, ), semicolon (; ), or white space. As a historical note, in versions prior to Spring 3.1, the i d attribute was typed as an x s d : I D , which constrained possible characters. As of 3.1, it is now x s d : s t r i n g . Note that bean id uniqueness is still enforced by the container, though no longer by XML parsers. You are not required to supply a name or id for a bean. If no name or id is supplied explicitly, the container generates a unique name for that bean. However, if you want to refer to that bean by name, through the use of the r e f 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. 4.3.1.1 Aliasing a bean outside the bean definition In a bean definition itself, you can supply more than one name for the bean, by using a combination of up
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

Bean naming conventions The convention is to use the

56/81

11/29/13

Reference Documentation

to one name specified by the i d attribute, and any number of other names in the n a m e attribute. These names can be equivalent aliases to the same bean, and are useful for some situations, such as allowing each component in an application to refer to a common dependency by using a bean name that is specific to that component itself. Specifying all aliases where the bean is actually defined is not always adequate, however. It is sometimes desirable to introduce an alias for a bean that is defined elsewhere. This is commonly the case in large systems where configuration is split amongst each subsystem, each subsystem having its own set of object definitions. In XML-based configuration metadata, you can use the < a l i a s / > element to accomplish this.
< a l i a sn a m e = " f r o m N a m e "a l i a s = " t o N a m e " / >

standard Java convention for instance field names when naming beans. That is, bean names start with a lowercase letter, and are camel-cased from then on. Examples of such names would be (without quotes) ' a c c o u n t M a n a g e r ' , ' a c c o u n t S e r v i c e ' , ' u s e r D a o ' , ' l o g i n C o n t r o l l e r ' , and so forth. Naming beans consistently makes your configuration easier to read and understand, and if you are using Spring AOP it helps a lot when applying advice to a set of beans related by name.

In this case, a bean in the same container which is named f r o m N a m e , may also after the use of this alias definition, be referred to as t o N a m e . For example, the configuration metadata for subsystem A may refer to a DataSource via the name 'subsystemA-dataSource. The configuration metadata for subsystem B may refer to a DataSource via the name 'subsystemB-dataSource'. When composing the main application that uses both these subsystems the main application refers to the DataSource via the name 'myAppdataSource'. To have all three names refer to the same object you add to the MyApp configuration metadata the following aliases definitions:
< a l i a sn a m e = " s u b s y s t e m A d a t a S o u r c e "a l i a s = " s u b s y s t e m B d a t a S o u r c e " / > < a l i a sn a m e = " s u b s y s t e m A d a t a S o u r c e "a l i a s = " m y A p p d a t a S o u r c e "/ >

Now each component and the main application can refer to the dataSource through a name that is unique and guaranteed not to clash with any other definition (effectively creating a namespace), yet they refer to the same bean.

4.3.2 Instantiating beans

A bean definition essentially is a recipe for creating one or more objects. The container looks at the recipe for a named bean when asked, and uses the configuration metadata encapsulated by that bean definition to create (or acquire) an actual object. If you use XML-based configuration metadata, you specify the type (or class) of object that is to be instantiated in the c l a s sattribute of the < b e a n / >element. This c l a s sattribute, which internally is a C l a s s property on a B e a n D e f i n i t i o n instance, is usually mandatory. (For exceptions, see Section 4.3.2.3, Instantiation using an instance factory method and Section 4.7, Bean definition inheritance.) You use the C l a s sproperty in one of two ways: Typically, to specify the bean class to be constructed in the case where the container itself directly creates the bean by calling its constructor reflectively, somewhat equivalent to Java code using the n e woperator. To specify the actual class containing the s t a t i c factory method that will be invoked to create the object, in the less common case where the container invokes a s t a t i c , factory method on a class to create the bean. The object type returned from the invocation of the s t a t i cfactory method may be the same class or another class entirely.
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 57/81

11/29/13

Reference Documentation

4.3.2.1 Instantiation with a constructor When you create a bean by the constructor approach, all normal classes are usable by and compatible with Spring. That is, the class being developed does not need to implement any specific interfaces or to be coded in a specific fashion. Simply specifying the bean class should suffice. However, depending on what type of IoC you use for that specific bean, you may need a default (empty) constructor. The Spring IoC container can manage virtually any class you want it to manage; it is not limited to managing true JavaBeans. Most Spring users prefer actual JavaBeans with only a default (no-argument) constructor and appropriate setters and getters modeled after the properties in the container. You can also have more exotic non-bean-style classes in your container. If, for example, you need to use a legacy connection pool that absolutely does not adhere to the JavaBean specification, Spring can manage it as well.
Inner class names If you want to configure a bean definition for a s t a t i c nested class, you have to use the binary name of the inner class. For example, if you have a class called F o o in the c o m . e x a m p l e package, and this F o oclass has a s t a t i cinner class called B a r , the value of the ' c l a s s 'attribute on a bean definition would be... c o m . e x a m p l e . F o o $ B a r Notice the use of the $ character in the name to separate the inner class name from the outer class name.

With XML-based configuration metadata you can specify your bean class as follows:
< b e a ni d = " e x a m p l e B e a n "c l a s s = " e x a m p l e s . E x a m p l e B e a n " / > < b e a nn a m e = " a n o t h e r E x a m p l e "c l a s s = " e x a m p l e s . E x a m p l e B e a n T w o " / >

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. 4.3.2.2 Instantiation with a static factory method When defining a bean that you create with a static factory method, you use the c l a s sattribute to specify the class containing the s t a t i cfactory method and an attribute named f a c t o r y m e t h o d to specify the name of the factory method itself. You should be able to call this method (with optional arguments as described later) and return a live object, which subsequently is treated as if it had been created through a constructor. One use for such a bean definition is to call s t a t i c factories in legacy code. The following bean definition specifies that the bean will be created by calling a factory-method. The definition does not specify the type (class) of the returned object, only the class containing the factory method. In this example, the c r e a t e I n s t a n c e ( )method must be a static method.
< b e a ni d = " c l i e n t S e r v i c e " c l a s s = " e x a m p l e s . C l i e n t S e r v i c e " f a c t o r y m e t h o d = " c r e a t e I n s t a n c e " / > p u b l i cc l a s sC l i e n t S e r v i c e{ p r i v a t es t a t i cC l i e n t S e r v i c ec l i e n t S e r v i c e=n e wC l i e n t S e r v i c e ( ) ; p r i v a t eC l i e n t S e r v i c e ( ){ } p u b l i cs t a t i cC l i e n t S e r v i c ec r e a t e I n s t a n c e ( ){ r e t u r nc l i e n t S e r v i c e ; }

For details about the mechanism for supplying (optional) arguments to the factory method and setting object instance properties after the object is returned from the factory, see Dependencies and configuration in detail.
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 58/81

11/29/13

Reference Documentation

4.3.2.3 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 c l a s s attribute empty, and in the f a c t o r y b e a n 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 f a c t o r y m e t h o dattribute.
< ! -t h ef a c t o r yb e a n ,w h i c hc o n t a i n sam e t h o dc a l l e dc r e a t e I n s t a n c e ( )> < b e a ni d = " s e r v i c e L o c a t o r "c l a s s = " e x a m p l e s . D e f a u l t S e r v i c e L o c a t o r " > < ! -i n j e c ta n yd e p e n d e n c i e sr e q u i r e db yt h i sl o c a t o rb e a n> < / b e a n > < ! -t h eb e a nt ob ec r e a t e dv i at h ef a c t o r yb e a n> < b e a ni d = " c l i e n t S e r v i c e " f a c t o r y b e a n = " s e r v i c e L o c a t o r " f a c t o r y m e t h o d = " c r e a t e C l i e n t S e r v i c e I n s t a n c e " / > p u b l i cc l a s sD e f a u l t S e r v i c e L o c a t o r{ p r i v a t es t a t i cC l i e n t S e r v i c ec l i e n t S e r v i c e=n e wC l i e n t S e r v i c e I m p l ( ) ; p r i v a t eD e f a u l t S e r v i c e L o c a t o r ( ){ } p u b l i cC l i e n t S e r v i c ec r e a t e C l i e n t S e r v i c e I n s t a n c e ( ){ r e t u r nc l i e n t S e r v i c e ; }

One factory class can also hold more than one factory method as shown here:
< b e a ni d = " s e r v i c e L o c a t o r "c l a s s = " e x a m p l e s . D e f a u l t S e r v i c e L o c a t o r " > < ! -i n j e c ta n yd e p e n d e n c i e sr e q u i r e db yt h i sl o c a t o rb e a n> < / b e a n > < b e a ni d = " c l i e n t S e r v i c e " f a c t o r y b e a n = " s e r v i c e L o c a t o r " f a c t o r y m e t h o d = " c r e a t e C l i e n t S e r v i c e I n s t a n c e " / > < b e a ni d = " a c c o u n t S e r v i c e " f a c t o r y b e a n = " s e r v i c e L o c a t o r " f a c t o r y m e t h o d = " c r e a t e A c c o u n t S e r v i c e I n s t a n c e " / > p u b l i cc l a s sD e f a u l t S e r v i c e L o c a t o r{ p r i v a t es t a t i cC l i e n t S e r v i c ec l i e n t S e r v i c e=n e wC l i e n t S e r v i c e I m p l ( ) ; p r i v a t es t a t i cA c c o u n t S e r v i c ea c c o u n t S e r v i c e=n e wA c c o u n t S e r v i c e I m p l ( ) ; p r i v a t eD e f a u l t S e r v i c e L o c a t o r ( ){ } p u b l i cC l i e n t S e r v i c ec r e a t e C l i e n t S e r v i c e I n s t a n c e ( ){ r e t u r nc l i e n t S e r v i c e ; } p u b l i cA c c o u n t S e r v i c ec r e a t e A c c o u n t S e r v i c e I n s t a n c e ( ){ r e t u r na c c o u n t S e r v i c e ; }

This approach shows that the factory bean itself can be managed and configured through dependency injection (DI). See Dependencies and configuration in detail. Note In Spring documentation, factory bean refers to a bean that is configured in the Spring container that will create objects through an instance or static factory method. By contrast, F a c t o r y B e a n(notice the capitalization) refers to a Spring-specific F a c t o r y B e a n.

4.4 Dependencies
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 59/81

11/29/13

Reference Documentation

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

4.4.1 Dependency injection

Dependency injection (DI) is a process whereby objects define their dependencies, that is, the other objects they work with, only through constructor arguments, arguments to a factory method, or properties that are set on the object instance after it is constructed or returned from a factory method. The container then injects those dependencies when it creates the bean. This process is fundamentally the inverse, hence the name Inversion of Control (IoC), of the bean itself controlling the instantiation or location of its dependencies on its own by using direct construction of classes, or the Service Locator pattern. Code is cleaner with the DI principle and decoupling is more effective when objects are provided with their dependencies. The object does not look up its dependencies, and does not know the location or class of the dependencies. As such, your classes become easier to test, in particular when the dependencies are on interfaces or abstract base classes, which allow for stub or mock implementations to be used in unit tests. DI exists in two major variants, Constructor-based dependency injection and Setter-based dependency injection. 4.4.1.1 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 s t a t i c factory method with specific arguments to construct the bean is nearly equivalent, and this discussion treats arguments to a constructor and to a s t a t i c factory method similarly. The following example shows a class that can only be dependency-injected with constructor injection. Notice that there is nothing special about this class, it is a POJO that has no dependencies on container specific interfaces, base classes or annotations.
p u b l i cc l a s sS i m p l e M o v i e L i s t e r{ / /t h eS i m p l e M o v i e L i s t e rh a sad e p e n d e n c yo naM o v i e F i n d e r p r i v a t eM o v i e F i n d e rm o v i e F i n d e r ; / /ac o n s t r u c t o rs ot h a tt h eS p r i n gc o n t a i n e rc a n' i n j e c t 'aM o v i e F i n d e r p u b l i cS i m p l e M o v i e L i s t e r ( M o v i e F i n d e rm o v i e F i n d e r ){ t h i s . m o v i e F i n d e r=m o v i e F i n d e r ; } } / /b u s i n e s sl o g i ct h a ta c t u a l l y' u s e s 't h ei n j e c t e dM o v i e F i n d e ri so m i t t e d . . .

Constructor argument resolution

Constructor argument resolution matching occurs using the argument's type. If no potential ambiguity exists in the constructor arguments of a bean definition, then the order in which the constructor arguments are defined in a bean definition is the order in which those arguments are supplied to the appropriate constructor when the bean is being instantiated. Consider the following class:
p a c k a g ex . y ; p u b l i cc l a s sF o o{ p u b l i cF o o ( B a rb a r ,B a zb a z ){
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 60/81

11/29/13

Reference Documentation

/ /. . .

No potential ambiguity exists, assuming that B a rand B a zclasses are not related by inheritance. Thus the following configuration works fine, and you do not need to specify the constructor argument indexes and/or types explicitly in the < c o n s t r u c t o r a r g / >element.
< b e a n s > < b e a ni d = " f o o "c l a s s = " x . y . F o o " > < c o n s t r u c t o r a r gr e f = " b a r " / > < c o n s t r u c t o r a r gr e f = " b a z " / > < / b e a n > < b e a ni d = " b a r "c l a s s = " x . y . B a r " / > < b e a ni d = " b a z "c l a s s = " x . y . B a z " / > < / b e a n s >

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 < v a l u e > t r u e < v a l u e > , Spring cannot determine the type of the value, and so cannot match by type without help. Consider the following class:
p a c k a g ee x a m p l e s ; p u b l i cc l a s sE x a m p l e B e a n{ / /N o .o fy e a r st ot h ec a l c u l a t et h eU l t i m a t eA n s w e r p r i v a t ei n ty e a r s ; / /T h eA n s w e rt oL i f e ,t h eU n i v e r s e ,a n dE v e r y t h i n g p r i v a t eS t r i n gu l t i m a t e A n s w e r ; p u b l i cE x a m p l e B e a n ( i n ty e a r s ,S t r i n gu l t i m a t e A n s w e r ){ t h i s . y e a r s=y e a r s ; t h i s . u l t i m a t e A n s w e r=u l t i m a t e A n s w e r ; }

Constructor argum ent type m atching

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 t y p eattribute. For example:
< b e a ni d = " e x a m p l e B e a n "c l a s s = " e x a m p l e s . E x a m p l e B e a n " > < c o n s t r u c t o r a r gt y p e = " i n t "v a l u e = " 7 5 0 0 0 0 0 " / > < c o n s t r u c t o r a r gt y p e = " j a v a . l a n g . S t r i n g "v a l u e = " 4 2 " / > < / b e a n >

Constructor argum ent index

Use the i n d e xattribute to specify explicitly the index of constructor arguments. For example:
< b e a ni d = " e x a m p l e B e a n "c l a s s = " e x a m p l e s . E x a m p l e B e a n " > < c o n s t r u c t o r a r gi n d e x = " 0 "v a l u e = " 7 5 0 0 0 0 0 " / > < c o n s t r u c t o r a r gi n d e x = " 1 "v a l u e = " 4 2 " / > < / b e a n >

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.
Constructor argum ent nam e

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

61/81

11/29/13

Reference Documentation

As of Spring 3.0 you can also use the constructor parameter name for value disambiguation:
< b e a ni d = " e x a m p l e B e a n "c l a s s = " e x a m p l e s . E x a m p l e B e a n " > < c o n s t r u c t o r a r gn a m e = " y e a r s "v a l u e = " 7 5 0 0 0 0 0 " / > < c o n s t r u c t o r a r gn a m e = " u l t i m a t e a n s w e r "v a l u e = " 4 2 " / > < / b e a n >

Keep in mind that to make this work out of the box your code must be compiled with the debug flag enabled so that Spring can look up the parameter name from the constructor. If you can't compile your code with debug flag (or don't want to) you can use @ C o n s t r u c t o r P r o p e r t i e sJDK annotation to explicitly name your constructor arguments. The sample class would then have to look as follows:
p a c k a g ee x a m p l e s ; p u b l i cc l a s sE x a m p l e B e a n{ / /F i e l d so m i t t e d @ C o n s t r u c t o r P r o p e r t i e s ( { " y e a r s " ," u l t i m a t e A n s w e r " } ) p u b l i cE x a m p l e B e a n ( i n ty e a r s ,S t r i n gu l t i m a t e A n s w e r ){ t h i s . y e a r s=y e a r s ; t h i s . u l t i m a t e A n s w e r=u l t i m a t e A n s w e r ; }

4.4.1.2 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 s t a t i c factory method to instantiate your bean. The following example shows a class that can only be dependency-injected using pure setter injection. This class is conventional Java. It is a POJO that has no dependencies on container specific interfaces, base classes or annotations.
p u b l i cc l a s sS i m p l e M o v i e L i s t e r{ / /t h eS i m p l e M o v i e L i s t e rh a sad e p e n d e n c yo nt h eM o v i e F i n d e r p r i v a t eM o v i e F i n d e rm o v i e F i n d e r ; / /as e t t e rm e t h o ds ot h a tt h eS p r i n gc o n t a i n e rc a n' i n j e c t 'aM o v i e F i n d e r p u b l i cv o i ds e t M o v i e F i n d e r ( M o v i e F i n d e rm o v i e F i n d e r ){ t h i s . m o v i e F i n d e r=m o v i e F i n d e r ; } } / /b u s i n e s sl o g i ct h a ta c t u a l l y' u s e s 't h ei n j e c t e dM o v i e F i n d e ri so m i t t e d . . .

The A p p l i c a t i o n C o n t e x tsupports constructor- and setter-based DI for the beans it manages. It also supports setter-based DI after some dependencies are already injected through the constructor approach. You configure the dependencies in the form of a B e a n D e f i n i t i o n , which you use with P r o p e r t y E d i t o r instances to convert properties from one format to another. However, most Spring users do not work with these classes directly (programmatically), but rather with an XML definition file that is then converted internally into instances of these classes, and used to load an entire Spring IoC container instance. 4.4.1.3 Dependency resolution process The container performs bean dependency resolution as follows: 1. The
A p p l i c a t i o n C o n t e x t

Constructor-based or setterbased DI? Since you can mix both, Constructor- and Setter-based DI, it is a good rule of thumb to use
62/81

is

created

and

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

11/29/13

Reference Documentation

initialized with configuration metadata that describes all the beans. Configuration metadata can be specified via XML, Java code or annotations. 2. 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. 3. Each property or constructor argument is an actual definition of the value to set, or a reference to another bean in the container. 4. Each property or constructor argument which is a value is converted from its specified format to the actual type of that property or constructor argument. By default Spring can convert a value supplied in string format to all built-in types, such as i n t ,l o n g ,S t r i n g ,b o o l e a n , etc. The Spring container validates the configuration of each bean as the container is created, including the validation of whether bean reference properties refer to valid beans. However, the bean properties themselves are not set until the bean is actually created. Beans that are singleton-scoped and set to be pre-instantiated (the default) are created when the container is created. Scopes are defined in Section 4.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 bean's dependencies and its dependencies' dependencies (and so on) are created and assigned. You can generally trust Spring to do the right thing. It detects configuration problems, such as references to non-existent beans and circular dependencies, at container load-time. Spring sets properties and resolves dependencies as late as possible, when the bean is actually created. This means that a Spring container which has loaded correctly can later generate an exception when you request an object if there is a problem creating that object or one of its dependencies. For example, the bean throws an exception as a result of a missing or invalid property. This potentially delayed visibility of some configuration issues is why A p p l i c a t i o n C o n t e x t implementations by default pre-instantiate singleton beans. At the cost of some upfront time and memory to create these beans before they are actually needed, you discover configuration issues when the A p p l i c a t i o n C o n t e x t is created, not later. You can still override this default behavior so that singleton beans will lazy-initialize, rather than be pre-instantiated.
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

constructor arguments for mandatory dependencies and setters for optional dependencies. Note that the use of a @Required annotation on a setter can be used to make setters required dependencies. The Spring team generally advocates setter injection, because large numbers of constructor arguments can get unwieldy, especially when properties are optional. Setter methods also make objects of that class amenable to reconfiguration or re-injection later. Management through JMX MBeans is a compelling use case. Some purists favor constructorbased injection. Supplying all object dependencies means that the object is always returned to client (calling) code in a totally initialized state. The disadvantage is that the object becomes less amenable to reconfiguration and re-injection. Use the DI that makes the most sense for a particular class. Sometimes, when dealing with third-party classes to which you do not have the source, the choice is made for you. A legacy class may not expose any setter methods, and so constructor injection is the only available DI.

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 configure beans for classes A and B to be injected into each other, the Spring IoC container detects this circular reference at runtime, and throws a B e a n C u r r e n t l y I n C r e a t i o n E x c e p t i o n . One possible solution is to edit the source code of some classes to be configured by setters rather than constructors. Alternatively, avoid
63/81

11/29/13

Reference Documentation

If no circular dependencies exist, when one or more collaborating beans are being injected into a dependent bean, each collaborating bean is totally configured prior to being injected into the dependent bean. This means that if bean A has a dependency on bean B, the Spring IoC container completely configures bean B prior to invoking the setter method on bean A. In other words, the bean is instantiated (if not a pre-instantiated singleton), its dependencies are set, and the relevant lifecycle methods (such as a configured init method or the InitializingBean callback method) are invoked. 4.4.1.4 Examples of dependency injection

constructor injection and use setter injection only. In other words, although it is not recommended, you can configure circular dependencies with setter injection. Unlike the typical case (with no circular dependencies), a circular dependency between bean A and bean B forces one of the beans to be injected into the other prior to being fully initialized itself (a classic chicken/egg scenario).

The following example uses XML-based configuration metadata for setter-based DI. A small part of a Spring XML configuration file specifies some bean definitions:
< b e a ni d = " e x a m p l e B e a n "c l a s s = " e x a m p l e s . E x a m p l e B e a n " > < ! -s e t t e ri n j e c t i o nu s i n gt h en e s t e d< r e f / >e l e m e n t> < p r o p e r t yn a m e = " b e a n O n e " > < r e fb e a n = " a n o t h e r E x a m p l e B e a n " / > < / p r o p e r t y > < ! -s e t t e ri n j e c t i o nu s i n gt h en e a t e r' r e f 'a t t r i b u t e> < p r o p e r t yn a m e = " b e a n T w o "r e f = " y e t A n o t h e r B e a n " / > < p r o p e r t yn a m e = " i n t e g e r P r o p e r t y "v a l u e = " 1 " / > < / b e a n > < b e a ni d = " a n o t h e r E x a m p l e B e a n "c l a s s = " e x a m p l e s . A n o t h e r B e a n " / > < b e a ni d = " y e t A n o t h e r B e a n "c l a s s = " e x a m p l e s . Y e t A n o t h e r B e a n " / > p u b l i cc l a s sE x a m p l e B e a n{ p r i v a t eA n o t h e r B e a nb e a n O n e ; p r i v a t eY e t A n o t h e r B e a nb e a n T w o ; p r i v a t ei n ti ; p u b l i cv o i ds e t B e a n O n e ( A n o t h e r B e a nb e a n O n e ){ t h i s . b e a n O n e=b e a n O n e ; } p u b l i cv o i ds e t B e a n T w o ( Y e t A n o t h e r B e a nb e a n T w o ){ t h i s . b e a n T w o=b e a n T w o ; } p u b l i cv o i ds e t I n t e g e r P r o p e r t y ( i n ti ){ t h i s . i=i ; }

In the preceding example, setters are declared to match against the properties specified in the XML file. The following example uses constructor-based DI:
< b e a ni d = " e x a m p l e B e a n "c l a s s = " e x a m p l e s . E x a m p l e B e a n " > < ! -c o n s t r u c t o ri n j e c t i o nu s i n gt h en e s t e d< r e f / >e l e m e n t> < c o n s t r u c t o r a r g > < r e fb e a n = " a n o t h e r E x a m p l e B e a n " / > < / c o n s t r u c t o r a r g > < ! -c o n s t r u c t o ri n j e c t i o nu s i n gt h en e a t e r' r e f 'a t t r i b u t e> < c o n s t r u c t o r a r gr e f = " y e t A n o t h e r B e a n " / > < c o n s t r u c t o r a r gt y p e = " i n t "v a l u e = " 1 " / > < / b e a n > < b e a ni d = " a n o t h e r E x a m p l e B e a n "c l a s s = " e x a m p l e s . A n o t h e r B e a n " / > < b e a ni d = " y e t A n o t h e r B e a n "c l a s s = " e x a m p l e s . Y e t A n o t h e r B e a n " / >

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

64/81

11/29/13

Reference Documentation

p u b l i cc l a s sE x a m p l e B e a n{ p r i v a t eA n o t h e r B e a nb e a n O n e ; p r i v a t eY e t A n o t h e r B e a nb e a n T w o ; p r i v a t ei n ti ; p u b l i cE x a m p l e B e a n ( A n o t h e r B e a na n o t h e r B e a n ,Y e t A n o t h e r B e a ny e t A n o t h e r B e a n ,i n ti ){ t h i s . b e a n O n e=a n o t h e r B e a n ; t h i s . b e a n T w o=y e t A n o t h e r B e a n ; t h i s . i=i ; }

The constructor arguments specified in the bean definition will be used as arguments to the constructor of the E x a m p l e B e a n . Now consider a variant of this example, where instead of using a constructor, Spring is told to call as t a t i cfactory method to return an instance of the object:
< b e a ni d = " e x a m p l e B e a n "c l a s s = " e x a m p l e s . E x a m p l e B e a n " f a c t o r y m e t h o d = " c r e a t e I n s t a n c e " > < c o n s t r u c t o r a r gr e f = " a n o t h e r E x a m p l e B e a n " / > < c o n s t r u c t o r a r gr e f = " y e t A n o t h e r B e a n " / > < c o n s t r u c t o r a r gv a l u e = " 1 " / > < / b e a n > < b e a ni d = " a n o t h e r E x a m p l e B e a n "c l a s s = " e x a m p l e s . A n o t h e r B e a n " / > < b e a ni d = " y e t A n o t h e r B e a n "c l a s s = " e x a m p l e s . Y e t A n o t h e r B e a n " / > p u b l i cc l a s sE x a m p l e B e a n{ / /ap r i v a t ec o n s t r u c t o r p r i v a t eE x a m p l e B e a n ( . . . ){ . . . } / /as t a t i cf a c t o r ym e t h o d ;t h ea r g u m e n t st ot h i sm e t h o dc a nb e / /c o n s i d e r e dt h ed e p e n d e n c i e so ft h eb e a nt h a ti sr e t u r n e d , / /r e g a r d l e s so fh o wt h o s ea r g u m e n t sa r ea c t u a l l yu s e d . p u b l i cs t a t i cE x a m p l e B e a nc r e a t e I n s t a n c e( A n o t h e r B e a na n o t h e r B e a n ,Y e t A n o t h e r B e a ny e t A n o t h e r B e a n ,i n ti ){ E x a m p l e B e a ne b=n e wE x a m p l e B e a n( . . . ) ; / /s o m eo t h e ro p e r a t i o n s . . . r e t u r ne b ;

Arguments to the s t a t i cfactory method are supplied via < c o n s t r u c t o r a r g / >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 s t a t i cfactory 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 f a c t o r y b e a n attribute instead of the c l a s sattribute), so details will not be discussed here.

4.4.2 Dependencies and configuration in detail

As mentioned in the previous section, you can define bean properties and constructor arguments as references to other managed beans (collaborators), or as values defined inline. Spring's XMLbased configuration metadata supports sub-element types within its < p r o p e r t y / > and < c o n s t r u c t o r a r g / >elements for this purpose. 4.4.2.1 Straight values (primitives, S t r i n g s , and so on) The v a l u eattribute of the < p r o p e r t y / >element specifies a property or constructor argument as a human-readable string representation. As mentioned previously, JavaBeans P r o p e r t y E d i t o r s
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 65/81

11/29/13

Reference Documentation

are used to convert these string values from a S t r i n g to the actual type of the property or argument.
< b e a ni d = " m y D a t a S o u r c e "c l a s s = " o r g . a p a c h e . c o m m o n s . d b c p . B a s i c D a t a S o u r c e "d e s t r o y m e t h o d = " c l o s e " < ! -r e s u l t si nas e t D r i v e r C l a s s N a m e ( S t r i n g )c a l l> < p r o p e r t yn a m e = " d r i v e r C l a s s N a m e "v a l u e = " c o m . m y s q l . j d b c . D r i v e r " / > < p r o p e r t yn a m e = " u r l "v a l u e = " j d b c : m y s q l : / / l o c a l h o s t : 3 3 0 6 / m y d b " / > < p r o p e r t yn a m e = " u s e r n a m e "v a l u e = " r o o t " / > < p r o p e r t yn a m e = " p a s s w o r d "v a l u e = " m a s t e r k a o l i " / > < / b e a n >

The following example uses the p-namespace for even more succinct XML configuration.
< b e a n sx m l n s = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s " x m l n s : x s i = " h t t p : / / w w w . w 3 . o r g / 2 0 0 1 / X M L S c h e m a i n s t a n c e " x m l n s : p = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / p " x s i : s c h e m a L o c a t i o n = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s / s p r i n g b e a n s . x s d " > < b e a ni d = " m y D a t a S o u r c e "c l a s s = " o r g . a p a c h e . c o m m o n s . d b c p . B a s i c D a t a S o u r c e " d e s t r o y m e t h o d = " c l o s e " p : d r i v e r C l a s s N a m e = " c o m . m y s q l . j d b c . D r i v e r " p : u r l = " j d b c : m y s q l : / / l o c a l h o s t : 3 3 0 6 / m y d b " p : u s e r n a m e = " r o o t " p : p a s s w o r d = " m a s t e r k a o l i " / > < / b e a n s >

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 SpringSource Tool Suite (STS) that support automatic property completion when you create bean definitions. Such IDE assistance is highly recommended. You can also configure a j a v a . u t i l . P r o p e r t i e sinstance as:
< b e a ni d = " m a p p i n g s " c l a s s = " o r g . s p r i n g f r a m e w o r k . b e a n s . f a c t o r y . c o n f i g . P r o p e r t y P l a c e h o l d e r C o n f i g u r e r " > < ! -t y p e da saj a v a . u t i l . P r o p e r t i e s> < p r o p e r t yn a m e = " p r o p e r t i e s " > < v a l u e > j d b c . d r i v e r . c l a s s N a m e = c o m . m y s q l . j d b c . D r i v e r j d b c . u r l = j d b c : m y s q l : / / l o c a l h o s t : 3 3 0 6 / m y d b < / v a l u e > < / p r o p e r t y > < / b e a n >

The Spring container converts the text inside the < v a l u e / >element into a j a v a . u t i l . P r o p e r t i e s instance by using the JavaBeans P r o p e r t y E d i t o rmechanism. This is a nice shortcut, and is one of a few places where the Spring team do favor the use of the nested < v a l u e / >element over the v a l u eattribute style.
The i d r e felement

The i d r e felement is simply an error-proof way to pass the id (string value - not a reference) of another bean in the container to a < c o n s t r u c t o r a r g / >or < p r o p e r t y / >element.
< b e a ni d = " t h e T a r g e t B e a n "c l a s s = " . . . " / > < b e a ni d = " t h e C l i e n t B e a n "c l a s s = " . . . " > < p r o p e r t yn a m e = " t a r g e t N a m e " > < i d r e fb e a n = " t h e T a r g e t B e a n "/ > < / p r o p e r t y > < / b e a n >

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

66/81

11/29/13

Reference Documentation

The above bean definition snippet is exactly equivalent (at runtime) to the following snippet:
< b e a ni d = " t h e T a r g e t B e a n "c l a s s = " . . . "/ > < b e a ni d = " c l i e n t "c l a s s = " . . . " > < p r o p e r t yn a m e = " t a r g e t N a m e "v a l u e = " t h e T a r g e t B e a n "/ > < / b e a n >

The first form is preferable to the second, because using the i d r e f 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 t a r g e t N a m eproperty of the c l i e n tbean. Typos are only discovered (with most likely fatal results) when the c l i e n t bean is actually instantiated. If the c l i e n tbean is a prototype bean, this typo and the resulting exception may only be discovered long after the container is deployed. Additionally, if the referenced bean is in the same XML unit, and the bean name is the bean id, you can use the l o c a lattribute, which allows the XML parser itself to validate the bean id earlier, at XML document parse time.
< p r o p e r t yn a m e = " t a r g e t N a m e " > < ! -ab e a nw i t hi d' t h e T a r g e t B e a n 'm u s te x i s t ;o t h e r w i s ea ne x c e p t i o nw i l lb et h r o w n> < i d r e fl o c a l = " t h e T a r g e t B e a n " / > < / p r o p e r t y >

A common place (at least in versions earlier than Spring 2.0) where the <idref/> element brings value is in the configuration of AOP interceptors in a P r o x y F a c t o r y B e a n bean definition. Using <idref/> elements when you specify the interceptor names prevents you from misspelling an interceptor id. 4.4.2.2 References to other beans (collaborators) The r e f element is the final element inside a < c o n s t r u c t o r a r g / > or < p r o p e r t y / > definition element. Here you set the value of the specified property of a bean to be a reference to another bean (a collaborator) managed by the container. The referenced bean is a dependency of the bean whose property will be set, and it is initialized on demand as needed before the property is set. (If the collaborator is a singleton bean, it may be initialized already by the container.) All references are ultimately a reference to another object. Scoping and validation depend on whether you specify the id/name of the other object through the b e a n , l o c a l ,or p a r e n tattributes. Specifying the target bean through the b e a nattribute of the < r e f / >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 file. The value of the b e a nattribute may be the same as the i d attribute of the target bean, or as one of the values in the n a m e attribute of the target bean.
< r e fb e a n = " s o m e B e a n " / >

Specifying the target bean through the l o c a lattribute leverages the ability of the XML parser to validate XML id references within the same file. The value of the l o c a l attribute must be the same as the i d attribute of the target bean. The XML parser issues an error if no matching element is found in the same file. As such, using the local variant is the best choice (in order to know about errors as early as possible) if the target bean is in the same XML file.
< r e fl o c a l = " s o m e B e a n " / >

Specifying the target bean through the p a r e n tattribute creates a reference to a bean that is in a parent container of the current container. The value of the p a r e n tattribute may be the same as either the i d attribute of the target bean, or one of the values in the n a m e attribute of the target
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 67/81

11/29/13

Reference Documentation

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.
< ! -i nt h ep a r e n tc o n t e x t> < b e a ni d = " a c c o u n t S e r v i c e "c l a s s = " c o m . f o o . S i m p l e A c c o u n t S e r v i c e " > < ! -i n s e r td e p e n d e n c i e sa sr e q u i r e da sh e r e> < / b e a n >

< ! -i nt h ec h i l d( d e s c e n d a n t )c o n t e x t> < b e a ni d = " a c c o u n t S e r v i c e " < -b e a nn a m ei st h es a m ea st h ep a r e n tb e a n> c l a s s = " o r g . s p r i n g f r a m e w o r k . a o p . f r a m e w o r k . P r o x y F a c t o r y B e a n " > < p r o p e r t yn a m e = " t a r g e t " > < r e fp a r e n t = " a c c o u n t S e r v i c e " / > < ! -n o t i c eh o ww er e f e rt ot h ep a r e n tb e a n> < / p r o p e r t y > < ! -i n s e r to t h e rc o n f i g u r a t i o na n dd e p e n d e n c i e sa sr e q u i r e dh e r e> < / b e a n >

4.4.2.3 Inner beans A< b e a n / >element inside the < p r o p e r t y / >or < c o n s t r u c t o r a r g / >elements defines a so-called inner bean.
< b e a ni d = " o u t e r "c l a s s = " . . . " > < ! -i n s t e a do fu s i n gar e f e r e n c et oat a r g e tb e a n ,s i m p l yd e f i n et h et a r g e tb e a ni n l i n e> < p r o p e r t yn a m e = " t a r g e t " > < b e a nc l a s s = " c o m . e x a m p l e . P e r s o n " >< ! -t h i si st h ei n n e rb e a n> < p r o p e r t yn a m e = " n a m e "v a l u e = " F i o n aA p p l e " / > < p r o p e r t yn a m e = " a g e "v a l u e = " 2 5 " / > < / b e a n > < / p r o p e r t y > < / b e a n >

An inner bean definition does not require a defined id or name; the container ignores these values. It also ignores the s c o p e flag. Inner beans are always anonymous and they are always scoped as prototypes. It is not possible to inject inner beans into collaborating beans other than into the enclosing bean. 4.4.2.4 Collections In the < l i s t / > ,< s e t / > ,< m a p / > , and < p r o p s / >elements, you set the properties and arguments of the Java C o l l e c t i o ntypes L i s t ,S e t ,M a p , and P r o p e r t i e s , respectively.
< b e a ni d = " m o r e C o m p l e x O b j e c t "c l a s s = " e x a m p l e . C o m p l e x O b j e c t " > < ! -r e s u l t si nas e t A d m i n E m a i l s ( j a v a . u t i l . P r o p e r t i e s )c a l l> < p r o p e r t yn a m e = " a d m i n E m a i l s " > < p r o p s > < p r o pk e y = " a d m i n i s t r a t o r " > a d m i n i s t r a t o r @ e x a m p l e . o r g < / p r o p > < p r o pk e y = " s u p p o r t " > s u p p o r t @ e x a m p l e . o r g < / p r o p > < p r o pk e y = " d e v e l o p m e n t " > d e v e l o p m e n t @ e x a m p l e . o r g < / p r o p > < / p r o p s > < / p r o p e r t y > < ! -r e s u l t si nas e t S o m e L i s t ( j a v a . u t i l . L i s t )c a l l> < p r o p e r t yn a m e = " s o m e L i s t " > < l i s t > < v a l u e > al i s te l e m e n tf o l l o w e db yar e f e r e n c e < / v a l u e > < r e fb e a n = " m y D a t a S o u r c e "/ > < / l i s t > < / p r o p e r t y > < ! -r e s u l t si nas e t S o m e M a p ( j a v a . u t i l . M a p )c a l l> < p r o p e r t yn a m e = " s o m e M a p " > < m a p > < e n t r yk e y = " a ne n t r y "v a l u e = " j u s ts o m es t r i n g " / > < e n t r yk e y= " ar e f "v a l u e r e f = " m y D a t a S o u r c e " / > < / m a p > < / p r o p e r t y > < ! -r e s u l t si nas e t S o m e S e t ( j a v a . u t i l . S e t )c a l l> < p r o p e r t yn a m e = " s o m e S e t " >
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 68/81

11/29/13

Reference Documentation

< s e t > < v a l u e > j u s ts o m es t r i n g < / v a l u e > < r e fb e a n = " m y D a t a S o u r c e "/ > < / s e t > < / p r o p e r t y > < / b e a n >

The value of a map key or value, or a set value, can also again be any of the following elements:
b e a n|r e f|i d r e f|l i s t|s e t|m a p|p r o p s|v a l u e|n u l l Collection merging

As of Spring 2.0, the container supports the merging of collections. An application developer can define a parent-style < l i s t / > ,< m a p / > ,< s e t / >or < p r o p s / >element, and have child-style < l i s t / > , < m a p / > ,< s e t / >or < p r o p s / >elements inherit and override values from the parent collection. That is, the child collection's values are the result of merging the elements of the parent and child collections, with the child's collection elements overriding values specified in the parent collection. This section on merging discusses the parent-child bean mechanism. Readers unfamiliar with parent and child bean definitions may wish to read the relevant section before continuing. The following example demonstrates collection merging:
< b e a n s > < b e a ni d = " p a r e n t "a b s t r a c t = " t r u e "c l a s s = " e x a m p l e . C o m p l e x O b j e c t " > < p r o p e r t yn a m e = " a d m i n E m a i l s " > < p r o p s > < p r o pk e y = " a d m i n i s t r a t o r " > a d m i n i s t r a t o r @ e x a m p l e . c o m < / p r o p > < p r o pk e y = " s u p p o r t " > s u p p o r t @ e x a m p l e . c o m < / p r o p > < / p r o p s > < / p r o p e r t y > < / b e a n > < b e a ni d = " c h i l d "p a r e n t = " p a r e n t " > < p r o p e r t yn a m e = " a d m i n E m a i l s " > < ! -t h em e r g ei ss p e c i f i e do nt h e* c h i l d *c o l l e c t i o nd e f i n i t i o n> < p r o p sm e r g e = " t r u e " > < p r o pk e y = " s a l e s " > s a l e s @ e x a m p l e . c o m < / p r o p > < p r o pk e y = " s u p p o r t " > s u p p o r t @ e x a m p l e . c o . u k < / p r o p > < / p r o p s > < / p r o p e r t y > < / b e a n > < b e a n s >

Notice the use of the m e r g e = t r u eattribute on the < p r o p s / >element of the a d m i n E m a i l sproperty of the c h i l dbean definition. When the c h i l dbean is resolved and instantiated by the container, the resulting instance has an a d m i n E m a i l sP r o p e r t i e s collection that contains the result of the merging of the child's a d m i n E m a i l scollection with the parent's a d m i n E m a i l scollection.
a d m i n i s t r a t o r = a d m i n i s t r a t o r @ e x a m p l e . c o m s a l e s = s a l e s @ e x a m p l e . c o m s u p p o r t = s u p p o r t @ e x a m p l e . c o . u k

The child P r o p e r t i e s collection's value set inherits all property elements from the parent < p r o p s / > , and the child's value for the s u p p o r tvalue overrides the value in the parent collection. This merging behavior applies similarly to the < l i s t / > ,< m a p / > , and < s e t / >collection types. In the specific case of the < l i s t / >element, the semantics associated with the L i s tcollection type, that is, the notion of an o r d e r e dcollection of values, is maintained; the parent's values precede all of the child list's values. In the case of the M a p ,S e t , and P r o p e r t i e s collection types, no ordering exists. Hence no ordering semantics are in effect for the collection types that underlie the associated M a p ,S e t , and P r o p e r t i e simplementation types that the container uses internally.
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 69/81

11/29/13

Reference Documentation

Limitations of collection merging

You cannot merge different collection types (such as a M a pand a L i s t ), and if you do attempt to do so an appropriate E x c e p t i o n is thrown. The m e r g e attribute must be specified on the lower, inherited, child definition; specifying the m e r g e attribute on a parent collection definition is redundant and will not result in the desired merging. The merging feature is available only in Spring 2.0 and later.
Strongly-typed collection (Java 5+ only)

In Java 5 and later, you can use strongly typed collections (using generic types). That is, it is possible to declare a C o l l e c t i o n type such that it can only contain S t r i n g elements (for example). If you are using Spring to dependency-inject a strongly-typed C o l l e c t i o ninto a bean, you can take advantage of Spring's type-conversion support such that the elements of your strongly-typed C o l l e c t i o ninstances are converted to the appropriate type prior to being added to the C o l l e c t i o n .
p u b l i cc l a s sF o o{ p r i v a t eM a p < S t r i n g ,F l o a t >a c c o u n t s ; p u b l i cv o i ds e t A c c o u n t s ( M a p < S t r i n g ,F l o a t >a c c o u n t s ){ t h i s . a c c o u n t s=a c c o u n t s ; }

< b e a n s > < b e a ni d = " f o o "c l a s s = " x . y . F o o " > < p r o p e r t yn a m e = " a c c o u n t s " > < m a p > < e n t r yk e y = " o n e "v a l u e = " 9 . 9 9 " / > < e n t r yk e y = " t w o "v a l u e = " 2 . 7 5 " / > < e n t r yk e y = " s i x "v a l u e = " 3 . 9 9 " / > < / m a p > < / p r o p e r t y > < / b e a n > < / b e a n s >

When the a c c o u n t s property of the f o o bean is prepared for injection, the generics information about the element type of the strongly-typed M a p < S t r i n g ,F l o a t >is available by reflection. Thus Spring's type conversion infrastructure recognizes the various value elements as being of type F l o a t , and the string values 9 . 9 9 ,2 . 7 5 , and 3 . 9 9are converted into an actual F l o a ttype. 4.4.2.5 Null and empty string values Spring treats empty arguments for properties and the like as empty S t r i n g s . The following XMLbased configuration metadata snippet sets the email property to the empty S t r i n gvalue ("")
< b e a nc l a s s = " E x a m p l e B e a n " > < p r o p e r t yn a m e = " e m a i l "v a l u e = " " / > < / b e a n >

The preceding example is equivalent to the following Java code: e x a m p l e B e a n . s e t E m a i l ( " " ) . The < n u l l / >element handles n u l lvalues. For example:
< b e a nc l a s s = " E x a m p l e B e a n " > < p r o p e r t yn a m e = " e m a i l " > < n u l l / > < / p r o p e r t y > < / b e a n >

The above configuration is equivalent to the following Java code: e x a m p l e B e a n . s e t E m a i l ( n u l l ) . 4.4.2.6 XML shortcut with the p-namespace
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 70/81

11/29/13

Reference Documentation

< p r o p e r t y / >elements, to

The p-namespace enables you to use the b e a n element's attributes, instead of nested describe your property values and/or collaborating beans.

Spring 2.0 and later supports extensible configuration formats with namespaces, which are based on an XML Schema definition. The b e a n sconfiguration format discussed in this chapter is defined in an XML Schema document. However, the p-namespace is not defined in an XSD file and exists only in the core of Spring. The following example shows two XML snippets that resolve to the same result: The first uses standard XML format and the second uses the p-namespace.
< b e a n sx m l n s = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s " x m l n s : x s i = " h t t p : / / w w w . w 3 . o r g / 2 0 0 1 / X M L S c h e m a i n s t a n c e " x m l n s : p = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / p " x s i : s c h e m a L o c a t i o n = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s / s p r i n g b e a n s . x s d " > < b e a nn a m e = " c l a s s i c "c l a s s = " c o m . e x a m p l e . E x a m p l e B e a n " > < p r o p e r t yn a m e = " e m a i l "v a l u e = " f o o @ b a r . c o m " / > < / b e a n > < b e a nn a m e = " p n a m e s p a c e "c l a s s = " c o m . e x a m p l e . E x a m p l e B e a n " p : e m a i l = " f o o @ b a r . c o m " / > < / b e a n s >

The example shows an attribute in the p-namespace called email in the bean definition. This tells Spring to include a property declaration. As previously mentioned, the p-namespace does not have a schema definition, so you can set the name of the attribute to the property name. This next example includes two more bean definitions that both have a reference to another bean:
< b e a n sx m l n s = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s " x m l n s : x s i = " h t t p : / / w w w . w 3 . o r g / 2 0 0 1 / X M L S c h e m a i n s t a n c e " x m l n s : p = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / p " x s i : s c h e m a L o c a t i o n = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s / s p r i n g b e a n s . x s d " > < b e a nn a m e = " j o h n c l a s s i c "c l a s s = " c o m . e x a m p l e . P e r s o n " > < p r o p e r t yn a m e = " n a m e "v a l u e = " J o h nD o e " / > < p r o p e r t yn a m e = " s p o u s e "r e f = " j a n e " / > < / b e a n > < b e a nn a m e = " j o h n m o d e r n " c l a s s = " c o m . e x a m p l e . P e r s o n " p : n a m e = " J o h nD o e " p : s p o u s e r e f = " j a n e " / > < b e a nn a m e = " j a n e "c l a s s = " c o m . e x a m p l e . P e r s o n " > < p r o p e r t yn a m e = " n a m e "v a l u e = " J a n eD o e " / > < / b e a n > < / b e a n s >

As you can see, this example includes not only a property value using the p-namespace, but also uses a special format to declare property references. Whereas the first bean definition uses < p r o p e r t yn a m e = " s p o u s e "r e f = " j a n e " / >to create a reference from bean j o h nto bean j a n e , the second bean definition uses p : s p o u s e r e f = " j a n e "as an attribute to do the exact same thing. In this case s p o u s eis the property name, whereas the r e fpart indicates that this is not a straight value but rather a reference to another bean. Note The p-namespace is not as flexible as the standard XML format. For example, the format for declaring property references clashes with properties that end in R e f , 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.
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 71/81

11/29/13

Reference Documentation

4.4.2.7 XML shortcut with the c-namespace Similar to the Section 4.4.2.6, XML shortcut with the p-namespace, the c-namespace, newly introduced in Spring 3.1, allows usage of inlined attributes for configuring the constructor arguments rather then nested c o n s t r u c t o r a r gelements. Let's review the examples from Section 4.4.1.1, Constructor-based dependency injection with the cnamespace:
< b e a n sx m l n s = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s " x m l n s : x s i = " h t t p : / / w w w . w 3 . o r g / 2 0 0 1 / X M L S c h e m a i n s t a n c e " x m l n s : c = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / c " x s i : s c h e m a L o c a t i o n = " h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s h t t p : / / w w w . s p r i n g f r a m e w o r k . o r g / s c h e m a / b e a n s / s p r i n g b e a n s . x s d " > < b e a ni d = " b a r "c l a s s = " x . y . B a r " / > < b e a ni d = " b a z "c l a s s = " x . y . B a z " / > < -' t r a d i t i o n a l 'd e c l a r a t i o n> < b e a ni d = " f o o "c l a s s = " x . y . F o o " > < c o n s t r u c t o r a r gr e f = " b a r " / > < c o n s t r u c t o r a r gr e f = " b a z " / > < c o n s t r u c t o r a r gv a l u e = " f o o @ b a r . c o m " / > < / b e a n > < -' c n a m e s p a c e 'd e c l a r a t i o n> < b e a ni d = " f o o "c l a s s = " x . y . F o o "c : b a r r e f = " b a r "c : b a z r e f = " b a z "c : e m a i l = " f o o @ b a r . c o m " > < / b e a n s >

The c :namespace uses the same conventions as the p :one (trailing r e ffor bean references) for setting the constructor arguments by their names. And just as well, it needs to be declared even though it is not defined in an XSD schema (but it exists inside the Spring core). For the rare cases where the constructor argument names are not available (usually if the bytecode was compiled without debugging information), one can use fallback to the argument indexes:
< -' c n a m e s p a c e 'i n d e xd e c l a r a t i o n> < b e a ni d = " f o o "c l a s s = " x . y . F o o "c : _ 0 r e f = " b a r "c : _ 1 r e f = " b a z " >

Note Due to the XML grammar, the index notation requires the presence of the leading _ as XML attribute names cannot start with a number (even though some IDE allow it). In practice, the constructor resolution mechanism is quite efficient in matching arguments so unless one really needs to, we recommend using the name notation through-out your configuration. 4.4.2.8 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 final property name are not n u l l . Consider the following bean definition.
< b e a ni d = " f o o "c l a s s = " f o o . B a r " > < p r o p e r t yn a m e = " f r e d . b o b . s a m m y "v a l u e = " 1 2 3 "/ > < / b e a n >

The f o obean has a f r e dproperty, which has a b o bproperty, which has a s a m m yproperty, and that final s a m m yproperty is being set to the value 1 2 3 . In order for this to work, the f r e dproperty of f o o , and the b o b property of f r e d must not be n u l l after the bean is constructed, or a
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 72/81

11/29/13

Reference Documentation

N u l l P o i n t e r E x c e p t i o nis

thrown.

4.4.3 Using d e p e n d s o n
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 < r e f / > element in XML-based configuration metadata. However, sometimes dependencies between beans are less direct; for example, a static initializer in a class needs to be triggered, such as database driver registration. The d e p e n d s o nattribute can explicitly force one or more beans to be initialized before the bean using this element is initialized. The following example uses the d e p e n d s o n attribute to express a dependency on a single bean:
< b e a ni d = " b e a n O n e "c l a s s = " E x a m p l e B e a n "d e p e n d s o n = " m a n a g e r " / > < b e a ni d = " m a n a g e r "c l a s s = " M a n a g e r B e a n "/ >

To express a dependency on multiple beans, supply a list of bean names as the value of the d e p e n d s o nattribute, with commas, whitespace and semicolons, used as valid delimiters:
< b e a ni d = " b e a n O n e "c l a s s = " E x a m p l e B e a n "d e p e n d s o n = " m a n a g e r , a c c o u n t D a o " > < p r o p e r t yn a m e = " m a n a g e r "r e f = " m a n a g e r "/ > < / b e a n > < b e a ni d = " m a n a g e r "c l a s s = " M a n a g e r B e a n "/ > < b e a ni d = " a c c o u n t D a o "c l a s s = " x . y . j d b c . J d b c A c c o u n t D a o "/ >

Note The d e p e n d s o n attribute in the bean definition can specify both an initialization time dependency and, in the case of singleton beans only, a corresponding destroy time dependency. Dependent beans that define a d e p e n d s o n relationship with a given bean are destroyed first, prior to the given bean itself being destroyed. Thus d e p e n d s o n can also control shutdown order.

4.4.4 Lazy-initialized beans

By default, A p p l i c a t i o n C o n t e x t implementations eagerly create and configure all singleton beans as part of the initialization process. Generally, this pre-instantiation is desirable, because errors in the configuration or surrounding environment are discovered immediately, as opposed to hours or even days later. When this behavior is not desirable, you can prevent pre-instantiation of a singleton bean by marking the bean definition as lazy-initialized. A lazy-initialized bean tells the IoC container to create a bean instance when it is first requested, rather than at startup. In XML, this behavior is controlled by the l a z y i n i t attribute on the < b e a n / > element; for example:
< b e a ni d = " l a z y "c l a s s = " c o m . f o o . E x p e n s i v e T o C r e a t e B e a n "l a z y i n i t = " t r u e " / > < b e a nn a m e = " n o t . l a z y "c l a s s = " c o m . f o o . A n o t h e r B e a n " / >

When the preceding configuration is consumed by an A p p l i c a t i o n C o n t e x t , the bean named l a z y is not eagerly pre-instantiated when the A p p l i c a t i o n C o n t e x t is starting up, whereas the n o t . l a z ybean is eagerly pre-instantiated. However, when a lazy-initialized bean is a dependency of a singleton bean that is not lazyinitialized, the A p p l i c a t i o n C o n t e x t creates the lazy-initialized bean at startup, because it must satisfy the singleton's dependencies. The lazy-initialized bean is injected into a singleton bean elsewhere that is not lazy-initialized.
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 73/81

11/29/13

Reference Documentation

You can also control lazy-initialization at the container level by using the d e f a u l t l a z y i n i t attribute on the < b e a n s / >element; for example:
< b e a n sd e f a u l t l a z y i n i t = " t r u e " > < ! -n ob e a n sw i l lb ep r e i n s t a n t i a t e d . . .> < / b e a n s >

4.4.5 Autowiring collaborators

The Spring container can autowire relationships between collaborating beans. You can allow Spring to resolve collaborators (other beans) automatically for your bean by inspecting the contents of the A p p l i c a t i o n C o n t e x t . Autowiring has the following advantages: Autowiring can significantly reduce the need to specify properties or constructor arguments. (Other mechanisms such as a bean template discussed elsewhere in this chapter are also valuable in this regard.) Autowiring can update a configuration as your objects evolve. For example, if you need to add a dependency to a class, that dependency can be satisfied automatically without you needing to modify the configuration. Thus autowiring can be especially useful during development, without negating the option of switching to explicit wiring when the code base becomes more stable. When using XML-based configuration metadata[2], you specify autowire mode for a bean definition with the a u t o w i r eattribute of the < b e a n / >element. The autowiring functionality has five modes. You specify autowiring per bean and thus can choose which ones to autowire.

Table 4.2. Autowiring modes Explanation (Default) No autowiring. Bean references must be defined via a r e f element. Changing the default setting is not recommended for larger no deployments, because specifying collaborators explicitly gives greater control and clarity. To some extent, it documents the structure of a system. 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 byName definition is set to autowire by name, and it contains a master property (that is, it has a setMaster(..) method), Spring looks for a bean definition named m a s t e r , and uses it to set the property. 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, byType 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. Analogous to byType, but applies to constructor arguments. If there is not constructor exactly one bean of the constructor argument type in the container, a fatal error is raised. Mode

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 S t r i n g . 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
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 74/81

11/29/13

Reference Documentation

autowiring completes. 4.4.5.1 Limitations and disadvantages of autowiring Autowiring works best when it is used consistently across a project. If autowiring is not used in general, it might be confusing to developers to use it to wire only one or two bean definitions. Consider the limitations and disadvantages of autowiring: Explicit dependencies in p r o p e r t y and c o n s t r u c t o r a r g settings always override autowiring. You cannot autowire so-called simple properties such as primitives, S t r i n g s , and C l a s s e s(and arrays of such simple properties). This limitation is by-design. Autowiring is less exact than explicit wiring. Although, as noted in the above table, Spring is careful to avoid guessing in case of ambiguity that might have unexpected results, the relationships between your Spring-managed objects are no longer documented explicitly. Wiring information may not be available to tools that may generate documentation from a Spring container. Multiple bean definitions within the container may match the type specified by the setter method or constructor argument to be autowired. For arrays, collections, or Maps, this is not necessarily a problem. However for dependencies that expect a single value, this ambiguity is not arbitrarily resolved. If no unique bean definition is available, an exception is thrown. In the latter scenario, you have several options: Abandon autowiring in favor of explicit wiring. Avoid autowiring for a bean definition by setting its a u t o w i r e c a n d i d a t eattributes to f a l s e as described in the next section. Designate a single bean definition as the primary candidate by setting the p r i m a r y attribute of its < b e a n / >element to t r u e . If you are using Java 5 or later, implement the more fine-grained control available with annotation-based configuration, as described in Section 4.9, Annotation-based container configuration. 4.4.5.2 Excluding a bean from autowiring On a per-bean basis, you can exclude a bean from autowiring. In Spring's XML format, set the a u t o w i r e c a n d i d a t eattribute of the < b e a n / >element to f a l s e ; the container makes that specific bean definition unavailable to the autowiring infrastructure (including annotation style configurations such as @ A u t o w i r e d ). You can also limit autowire candidates based on pattern-matching against bean names. The toplevel < b e a n s / > element accepts one or more patterns within its d e f a u l t a u t o w i r e c a n d i d a t e s attribute. For example, to limit autowire candidate status to any bean whose name ends with Repository, provide a value of *Repository. To provide multiple patterns, define them in a comma-separated list. An explicit value of t r u e or f a l s e for a bean definitions a u t o w i r e c a n d i d a t eattribute always takes precedence, and for such beans, the pattern matching rules do not apply. These techniques are useful for beans that you never want to be injected into other beans by autowiring. It does not mean that an excluded bean cannot itself be configured using autowiring. Rather, the bean itself is not a candidate for autowiring other beans.
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 75/81

11/29/13

Reference Documentation

4.4.6 Method injection

In most application scenarios, most beans in the container are singletons. When a singleton bean needs to collaborate with another singleton bean, or a non-singleton bean needs to collaborate with another non-singleton bean, you typically handle the dependency by defining one bean as a property of the other. A problem arises when the bean lifecycles are different. Suppose singleton bean A needs to use non-singleton (prototype) bean B, perhaps on each method invocation on A. The container only creates the singleton bean A once, and thus only gets one opportunity to set the properties. The container cannot provide bean A with a new instance of bean B every time one is needed. A solution is to forego some inversion of control. You can make bean A aware of the container by implementing the A p p l i c a t i o n C o n t e x t A w a r einterface, 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:
/ /ac l a s st h a tu s e sas t a t e f u lC o m m a n d s t y l ec l a s st op e r f o r ms o m ep r o c e s s i n g p a c k a g ef i o n a . a p p l e ; / /S p r i n g A P Ii m p o r t s i m p o r to r g . s p r i n g f r a m e w o r k . b e a n s . B e a n s E x c e p t i o n ; i m p o r to r g . s p r i n g f r a m e w o r k . c o n t e x t . A p p l i c a t i o n C o n t e x t ; i m p o r to r g . s p r i n g f r a m e w o r k . c o n t e x t . A p p l i c a t i o n C o n t e x t A w a r e ; p u b l i cc l a s sC o m m a n d M a n a g e ri m p l e m e n t sA p p l i c a t i o n C o n t e x t A w a r e{ p r i v a t eA p p l i c a t i o n C o n t e x ta p p l i c a t i o n C o n t e x t ; p u b l i cO b j e c tp r o c e s s ( M a pc o m m a n d S t a t e ){ / /g r a ban e wi n s t a n c eo ft h ea p p r o p r i a t eC o m m a n d C o m m a n dc o m m a n d=c r e a t e C o m m a n d ( ) ; / /s e tt h es t a t eo nt h e( h o p e f u l l yb r a n dn e w )C o m m a n di n s t a n c e c o m m a n d . s e t S t a t e ( c o m m a n d S t a t e ) ; r e t u r nc o m m a n d . e x e c u t e ( ) ; } p r o t e c t e dC o m m a n dc r e a t e C o m m a n d ( ){ / /n o t i c et h eS p r i n gA P Id e p e n d e n c y ! r e t u r nt h i s . a p p l i c a t i o n C o n t e x t . g e t B e a n ( " c o m m a n d " ,C o m m a n d . c l a s s ) ; } p u b l i cv o i ds e t A p p l i c a t i o n C o n t e x t ( A p p l i c a t i o n C o n t e x ta p p l i c a t i o n C o n t e x t ) t h r o w sB e a n s E x c e p t i o n{ t h i s . a p p l i c a t i o n C o n t e x t=a p p l i c a t i o n C o n t e x t ; } }

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. 4.4.6.1 Lookup method injection Lookup method injection is the ability of the container motivation for Method Injection in this blog entry. 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. Note For this dynamic subclassing to work, you must have the CGLIB jar(s) in your classpath. The class that the Spring container will subclass cannot be f i n a l , and the method to be overridden cannot be f i n a leither. Also, testing a class
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 76/81

You can read more about the

11/29/13

Reference Documentation

that has an a b s t r a c tmethod requires you to subclass the class yourself and to supply a stub implementation of the a b s t r a c tmethod. Finally, objects that have been the target of method injection cannot be serialized. Looking at the C o m m a n d M a n a g e r class in the previous code snippet, you see that the Spring container will dynamically override the implementation of the c r e a t e C o m m a n d ( ) method. Your C o m m a n d M a n a g e r class will not have any Spring dependencies, as can be seen in the reworked example:
p a c k a g ef i o n a . a p p l e ; / /n om o r eS p r i n gi m p o r t s ! p u b l i ca b s t r a c tc l a s sC o m m a n d M a n a g e r{ p u b l i cO b j e c tp r o c e s s ( O b j e c tc o m m a n d S t a t e ){ / /g r a ban e wi n s t a n c eo ft h ea p p r o p r i a t eC o m m a n di n t e r f a c e C o m m a n dc o m m a n d=c r e a t e C o m m a n d ( ) ; / /s e tt h es t a t eo nt h e( h o p e f u l l yb r a n dn e w )C o m m a n di n s t a n c e c o m m a n d . s e t S t a t e ( c o m m a n d S t a t e ) ; r e t u r nc o m m a n d . e x e c u t e ( ) ; } / /o k a y . . .b u tw h e r ei st h ei m p l e m e n t a t i o no ft h i sm e t h o d ? p r o t e c t e da b s t r a c tC o m m a n dc r e a t e C o m m a n d ( ) ; }

In the client class containing the method to be injected (the C o m m a n d M a n a g e r in this case), the method to be injected requires a signature of the following form:
< p u b l i c | p r o t e c t e d >[ a b s t r a c t ]< r e t u r n t y p e >t h e M e t h o d N a m e ( n o a r g u m e n t s ) ;

If the method is a b s t r a c t , the dynamically-generated subclass implements the method. Otherwise, the dynamically-generated subclass overrides the concrete method defined in the original class. For example:
< ! -as t a t e f u lb e a nd e p l o y e da sap r o t o t y p e( n o n s i n g l e t o n )> < b e a ni d = " c o m m a n d "c l a s s = " f i o n a . a p p l e . A s y n c C o m m a n d "s c o p e = " p r o t o t y p e " > < ! -i n j e c td e p e n d e n c i e sh e r ea sr e q u i r e d> < / b e a n > < ! -c o m m a n d P r o c e s s o ru s e ss t a t e f u l C o m m a n d H e l p e r> < b e a ni d = " c o m m a n d M a n a g e r "c l a s s = " f i o n a . a p p l e . C o m m a n d M a n a g e r " > < l o o k u p m e t h o dn a m e = " c r e a t e C o m m a n d "b e a n = " c o m m a n d " / > < / b e a n >

The bean identified as commandManager calls its own method c r e a t e C o m m a n d ( ) whenever it needs a new instance of the command bean. You must be careful to deploy the c o m m a n dbean as a prototype, if that is actually what is needed. If it is deployed as a singleton, the same instance of the c o m m a n dbean is returned each time. Tip The interested reader may also find the S e r v i c e L o c a t o r F a c t o r y B e a n (in the o r g . s p r i n g f r a m e w o r k . b e a n s . f a c t o r y . c o n f i g package) to be of use. The approach used in ServiceLocatorFactoryBean is similar to that of another utility class, O b j e c t F a c t o r y C r e a t i n g F a c t o r y B e a n , but it allows you to specify your own lookup interface as opposed to a Spring-specific lookup interface. Consult the JavaDocs for these classes as well as this blog entry for additional information ServiceLocatorFactoryBean. 4.4.6.2 Arbitrary method replacement A less useful form of method injection than lookup method Injection is the ability to replace
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 77/81

11/29/13

Reference Documentation

arbitrary methods in a managed bean with another method implementation. Users may safely skip the rest of this section until the functionality is actually needed. With XML-based configuration metadata, you can use the r e p l a c e d m e t h o d 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:
p u b l i cc l a s sM y V a l u e C a l c u l a t o r{ p u b l i cS t r i n gc o m p u t e V a l u e ( S t r i n gi n p u t ){ / /s o m er e a lc o d e . . . } / /s o m eo t h e rm e t h o d s . . . }

A class implementing the o r g . s p r i n g f r a m e w o r k . b e a n s . f a c t o r y . s u p p o r t . M e t h o d R e p l a c e r interface provides the new method definition.

/ * *m e a n tt ob eu s e dt oo v e r r i d et h ee x i s t i n gc o m p u t e V a l u e ( S t r i n g ) i m p l e m e n t a t i o ni nM y V a l u e C a l c u l a t o r * / p u b l i cc l a s sR e p l a c e m e n t C o m p u t e V a l u ei m p l e m e n t sM e t h o d R e p l a c e r{ p u b l i cO b j e c tr e i m p l e m e n t ( O b j e c to ,M e t h o dm ,O b j e c t [ ]a r g s )t h r o w sT h r o w a b l e{ / /g e tt h ei n p u tv a l u e ,w o r kw i t hi t ,a n dr e t u r nac o m p u t e dr e s u l t S t r i n gi n p u t=( S t r i n g )a r g s [ 0 ] ; . . . r e t u r n. . . ; }

The bean definition to deploy the original class and specify the method override would look like this:
< b e a ni d = " m y V a l u e C a l c u l a t o r "c l a s s = " x . y . z . M y V a l u e C a l c u l a t o r " > < ! -a r b i t r a r ym e t h o dr e p l a c e m e n t> < r e p l a c e d m e t h o dn a m e = " c o m p u t e V a l u e "r e p l a c e r = " r e p l a c e m e n t C o m p u t e V a l u e " > < a r g t y p e > S t r i n g < / a r g t y p e > < / r e p l a c e d m e t h o d > < / b e a n > < b e a ni d = " r e p l a c e m e n t C o m p u t e V a l u e "c l a s s = " a . b . c . R e p l a c e m e n t C o m p u t e V a l u e " / >

You can use one or more contained < a r g t y p e / > elements within the < r e p l a c e d m e t h o d / > element to indicate the method signature of the method being overridden. The signature for the arguments is necessary only if the method is overloaded and multiple variants exist within the class. For convenience, the type string for an argument may be a substring of the fully qualified type name. For example, the following all match j a v a . l a n g . S t r i n g :
j a v a . l a n g . S t r i n g S t r i n g S t r

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.

4.5 Bean scopes

When you create a bean definition, you create a recipe for creating actual instances of the class defined by that bean definition. The idea that a bean definition is a recipe is important, because it
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 78/81

11/29/13

Reference Documentation

means that, as with a class, you can create many object instances from a single recipe. You can control not only the various dependencies and configuration values that are to be plugged into an object that is created from a particular bean definition, but also the scope of the objects created from a particular bean definition. This approach is powerful and flexible in that you can choose the scope of the objects you create through configuration instead of having to bake in the scope of an object at the Java class level. Beans can be defined to be deployed in one of a number of scopes: out of the box, the Spring Framework supports five scopes, three of which are available only if you use a web-aware A p p l i c a t i o n C o n t e x t . The following scopes are supported out of the box. You can also create a custom scope.

Table 4.3. Bean scopes Description (Default) Scopes a single bean definition to a single object instance per singleton Spring IoC container. prototype Scopes a single bean definition to any number of object instances. Scopes a single bean definition to the lifecycle of a single HTTP request; that is, each HTTP request has its own instance of a bean created off the request back of a single bean definition. Only valid in the context of a web-aware Spring A p p l i c a t i o n C o n t e x t . Scopes a single bean definition to the lifecycle of an HTTP S e s s i o n . Only session valid in the context of a web-aware Spring A p p l i c a t i o n C o n t e x t . Scopes a single bean definition to the lifecycle of a global HTTP S e s s i o n . global Typically only valid when used in a portlet context. Only valid in the context of session a web-aware Spring A p p l i c a t i o n C o n t e x t . Scope

Thread-scoped beans 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 Section 4.5.5.2, Using a custom scope.

4.5.1 The singleton scope

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

Spring's concept of a singleton bean differs from the Singleton pattern as defined in the Gang of Four (GoF) patterns book. The GoF Singleton hard-codes the scope of an object such that one and only one instance of a particular class is created per C l a s s L o a d e r . The scope of the Spring singleton is best described as per container and per bean. This means that if you define one
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 79/81

11/29/13

Reference Documentation

bean for a particular class in a single Spring container, then the Spring container creates one and only one instance of the class defined by that bean definition. The singleton scope is the default scope in Spring. To define a bean as a singleton in XML, you would write, for example:
< b e a ni d = " a c c o u n t S e r v i c e "c l a s s = " c o m . f o o . D e f a u l t A c c o u n t S e r v i c e " / > < ! -t h ef o l l o w i n gi se q u i v a l e n t ,t h o u g hr e d u n d a n t( s i n g l e t o ns c o p ei st h ed e f a u l t )> < b e a ni d = " a c c o u n t S e r v i c e "c l a s s = " c o m . f o o . D e f a u l t A c c o u n t S e r v i c e "s c o p e = " s i n g l e t o n " / >

4.5.2 The prototype scope

The non-singleton, prototype scope of bean deployment results in the creation of a new bean instance every time a request for that specific bean is made. That is, the bean is injected into another bean or you request it through a g e t B e a n ( )method call on the container. As a rule, use the prototype scope for all stateful beans and the singleton scope for stateless beans. The following diagram illustrates the Spring prototype scope. A data access object (DAO) is not typically configured as a prototype, because a typical DAO does not hold any conversational state; it was just easier for this author to reuse the core of the singleton diagram.

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

< ! -u s i n gs p r i n g b e a n s 2 . 0 . d t d> < b e a ni d = " a c c o u n t S e r v i c e "c l a s s = " c o m . f o o . D e f a u l t A c c o u n t S e r v i c e "s c o p e = " p r o t o t y p e " / >

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

4.5.3 Singleton 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 prototypescoped 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
docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/ 80/81

11/29/13

Reference Documentation

instance of a prototype bean at runtime more than once, see Section 4.4.6, Method injection

4.5.4 Request, session, and global session scopes

The r e q u e s t ,s e s s i o n , and g l o b a ls e s s i o n scopes are only available if you use a web-aware Spring A p p l i c a t i o n C o n t e x t implementation (such as X m l W e b A p p l i c a t i o n C o n t e x t ). If you use these scopes with regular Spring IoC containers such as the C l a s s P a t h X m l A p p l i c a t i o n C o n t e x t , you get an I l l e g a l S t a t e E x c e p t i o ncomplaining about an unknown bean scope. 4.5.4.1 Initial web configuration To support the scoping of beans at the r e q u e s t , s e s s i o n , and g l o b a l s e s s i o n levels (webscoped beans), some minor initial configuration is required before you define your beans. (This initial setup is not required for the standard scopes, singleton and prototype.) How you accomplish this initial setup depends on your particular Servlet environment.. If you access scoped beans within Spring Web MVC, in effect, within a request that is processed by the Spring D i s p a t c h e r S e r v l e t , or D i s p a t c h e r P o r t l e t , then no special setup is necessary: D i s p a t c h e r S e r v l e tand D i s p a t c h e r P o r t l e talready expose all relevant state. If you use a Servlet 2.4+ web contai

docs.spring.io/spring/docs/3.1.4.RELEASE/spring-framework-reference/htmlsingle/

81/81