Spring Framework Reference Documentation I. Overview of Spring Framework II. What's New in ...

645 Pages·2017·6.77 MB·English

08/01/2017 Spring Framework Reference Documentation
Spring Framework Reference Documentation
Authors
Rod Johnson , Juergen Hoeller , Keith Donald , Colin Sampaleanu , Rob Harrop , Thomas Risberg , Alef Arendsen , Darren Davison , Dmitriy
Kopylenko , Mark Pollack , Thierry Templier , Erwin Vervaet , Portia Tung , Ben Hale , Adrian Colyer , John Lewis , Costin Leau , Mark Fisher ,
Sam Brannen , Ramnivas Laddad , Arjen Poutsma , Chris Beams , Tareq Abedrabbo , Andy Clement , Dave Syer , Oliver Gierke , Rossen
Stoyanchev , Phillip Webb , Rob Winch , Brian Clozel , Stephane Nicoll , Sebastien Deleuze
4.3.5.RELEASE
Copyright © 2004­2016
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further
provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
Table of Contents
I. Overview of Spring Framework
1. Getting Started with Spring
2. Introduction to the Spring Framework
2.1. Dependency Injection and Inversion of Control
2.2. Modules
2.2.1. Core Container
2.2.2. AOP and Instrumentation
2.2.3. Messaging
2.2.4. Data Access/Integration
2.2.5. Web
2.2.6. Test
2.3. Usage scenarios
2.3.1. Dependency Management and Naming Conventions
Spring Dependencies and Depending on Spring
Maven Dependency Management
Maven "Bill Of Materials" Dependency
Gradle Dependency Management
Ivy Dependency Management
Distribution Zip Files
2.3.2. Logging
Not Using Commons Logging
Using SLF4J
Using Log4J
II. What’s New in Spring Framework 4.x
3. New Features and Enhancements in Spring Framework 4.0
3.1. Improved Getting Started Experience
3.2. Removed Deprecated Packages and Methods
3.3. Java 8 (as well as 6 and 7)
3.4. Java EE 6 and 7
3.5. Groovy Bean Definition DSL
3.6. Core Container Improvements
3.7. General Web Improvements
3.8. WebSocket, SockJS, and STOMP Messaging
3.9. Testing Improvements
4. New Features and Enhancements in Spring Framework 4.1
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 1/645
08/01/2017 Spring Framework Reference Documentation
4.1. JMS Improvements
4.2. Caching Improvements
4.3. Web Improvements
4.4. WebSocket Messaging Improvements
4.5. Testing Improvements
5. New Features and Enhancements in Spring Framework 4.2
5.1. Core Container Improvements
5.2. Data Access Improvements
5.3. JMS Improvements
5.4. Web Improvements
5.5. WebSocket Messaging Improvements
5.6. Testing Improvements
6. New Features and Enhancements in Spring Framework 4.3
6.1. Core Container Improvements
6.2. Data Access Improvements
6.3. Caching Improvements
6.4. JMS Improvements
6.5. Web Improvements
6.6. WebSocket Messaging Improvements
6.7. Testing Improvements
6.8. Support for new library and server generations
III. Core Technologies
7. The IoC container
7.1. Introduction to the Spring IoC container and beans
7.2. Container overview
7.2.1. Configuration metadata
7.2.2. Instantiating a container
Composing XML­based configuration metadata
7.2.3. Using the container
7.3. Bean overview
7.3.1. Naming beans
Aliasing a bean outside the bean definition
7.3.2. Instantiating beans
Instantiation with a constructor
Instantiation with a static factory method
Instantiation using an instance factory method
7.4. Dependencies
7.4.1. Dependency Injection
Constructor­based dependency injection
Setter­based dependency injection
Dependency resolution process
Examples of dependency injection
7.4.2. Dependencies and configuration in detail
Straight values (primitives, Strings, and so on)
References to other beans (collaborators)
Inner beans
Collections
Null and empty string values
XML shortcut with the p­namespace
XML shortcut with the c­namespace
Compound property names
7.4.3. Using depends­on
7.4.4. Lazy­initialized beans
7.4.5. Autowiring collaborators
Limitations and disadvantages of autowiring
Excluding a bean from autowiring
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 2/645
08/01/2017 Spring Framework Reference Documentation
7.4.6. Method injection
Lookup method injection
Arbitrary method replacement
7.5. Bean scopes
7.5.1. The singleton scope
7.5.2. The prototype scope
7.5.3. Singleton beans with prototype­bean dependencies
7.5.4. Request, session, global session, application, and WebSocket scopes
Initial web configuration
Request scope
Session scope
Global session scope
Application scope
Scoped beans as dependencies
7.5.5. Custom scopes
Creating a custom scope
Using a custom scope
7.6. Customizing the nature of a bean
7.6.1. Lifecycle callbacks
Initialization callbacks
Destruction callbacks
Default initialization and destroy methods
Combining lifecycle mechanisms
Startup and shutdown callbacks
Shutting down the Spring IoC container gracefully in non­web applications
7.6.2. ApplicationContextAware and BeanNameAware
7.6.3. Other Aware interfaces
7.7. Bean definition inheritance
7.8. Container Extension Points
7.8.1. Customizing beans using a BeanPostProcessor
Example: Hello World, BeanPostProcessor­style
Example: The RequiredAnnotationBeanPostProcessor
7.8.2. Customizing configuration metadata with a BeanFactoryPostProcessor
Example: the Class name substitution PropertyPlaceholderConfigurer
Example: the PropertyOverrideConfigurer
7.8.3. Customizing instantiation logic with a FactoryBean
7.9. Annotation­based container configuration
7.9.1. @Required
7.9.2. @Autowired
7.9.3. Fine­tuning annotation­based autowiring with @Primary
7.9.4. Fine­tuning annotation­based autowiring with qualifiers
7.9.5. Using generics as autowiring qualifiers
7.9.6. CustomAutowireConfigurer
7.9.7. @Resource
7.9.8. @PostConstruct and @PreDestroy
7.10. Classpath scanning and managed components
7.10.1. @Component and further stereotype annotations
7.10.2. Meta­annotations
7.10.3. Automatically detecting classes and registering bean definitions
7.10.4. Using filters to customize scanning
7.10.5. Defining bean metadata within components
7.10.6. Naming autodetected components
7.10.7. Providing a scope for autodetected components
7.10.8. Providing qualifier metadata with annotations
7.11. Using JSR 330 Standard Annotations
7.11.1. Dependency Injection with @Inject and @Named
7.11.2. @Named and @ManagedBean: standard equivalents to the @Component annotation
7.11.3. Limitations of JSR­330 standard annotations
7.12. Java­based container configuration
7.12.1. Basic concepts: @Bean and @Configuration
7.12.2. Instantiating the Spring container using AnnotationConfigApplicationContext
Simple construction
Building the container programmatically using register(Class<?>… )
Enabling component scanning with scan(String… )
Support for web applications with AnnotationConfigWebApplicationContext
7.12.3. Using the @Bean annotation
Declaring a bean
Bean dependencies
Receiving lifecycle callbacks
Specifying bean scope
Customizing bean naming
Bean aliasing
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 3/645
08/01/2017 Spring Framework Reference Documentation
Bean description
7.12.4. Using the @Configuration annotation
Injecting inter­bean dependencies
Lookup method injection
Further information about how Java­based configuration works internally
7.12.5. Composing Java­based configurations
Using the @Import annotation
Conditionally include @Configuration classes or @Bean methods
Combining Java and XML configuration
7.13. Environment abstraction
7.13.1. Bean definition profiles
@Profile
7.13.2. XML bean definition profiles
Activating a profile
Default profile
7.13.3. PropertySource abstraction
7.13.4. @PropertySource
7.13.5. Placeholder resolution in statements
7.14. Registering a LoadTimeWeaver
7.15. Additional Capabilities of the ApplicationContext
7.15.1. Internationalization using MessageSource
7.15.2. Standard and Custom Events
Annotation­based Event Listeners
Asynchronous Listeners
Ordering Listeners
Generic Events
7.15.3. Convenient access to low­level resources
7.15.4. Convenient ApplicationContext instantiation for web applications
7.15.5. Deploying a Spring ApplicationContext as a Java EE RAR file
7.16. The BeanFactory
7.16.1. BeanFactory or ApplicationContext?
7.16.2. Glue code and the evil singleton
8. Resources
8.1. Introduction
8.2. The Resource interface
8.3. Built­in Resource implementations
8.3.1. UrlResource
8.3.2. ClassPathResource
8.3.3. FileSystemResource
8.3.4. ServletContextResource
8.3.5. InputStreamResource
8.3.6. ByteArrayResource
8.4. The ResourceLoader
8.5. The ResourceLoaderAware interface
8.6. Resources as dependencies
8.7. Application contexts and Resource paths
8.7.1. Constructing application contexts
Constructing ClassPathXmlApplicationContext instances ­ shortcuts
8.7.2. Wildcards in application context constructor resource paths
Ant­style Patterns
The Classpath*: portability classpath*: prefix
Other notes relating to wildcards
8.7.3. FileSystemResource caveats
9. Validation, Data Binding, and Type Conversion
9.1. Introduction
9.2. Validation using Spring’s Validator interface
9.3. Resolving codes to error messages
9.4. Bean manipulation and the BeanWrapper
9.4.1. Setting and getting basic and nested properties
9.4.2. Built­in PropertyEditor implementations
Registering additional custom PropertyEditors
9.5. Spring Type Conversion
9.5.1. Converter SPI
9.5.2. ConverterFactory
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 4/645
08/01/2017 Spring Framework Reference Documentation
9.5.3. GenericConverter
ConditionalGenericConverter
9.5.4. ConversionService API
9.5.5. Configuring a ConversionService
9.5.6. Using a ConversionService programmatically
9.6. Spring Field Formatting
9.6.1. Formatter SPI
9.6.2. Annotation­driven Formatting
Format Annotation API
9.6.3. FormatterRegistry SPI
9.6.4. FormatterRegistrar SPI
9.6.5. Configuring Formatting in Spring MVC
9.7. Configuring a global date & time format
9.8. Spring Validation
9.8.1. Overview of the JSR­303 Bean Validation API
9.8.2. Configuring a Bean Validation Provider
Injecting a Validator
Configuring Custom Constraints
Spring­driven Method Validation
Additional Configuration Options
9.8.3. Configuring a DataBinder
9.8.4. Spring MVC 3 Validation
10. Spring Expression Language (SpEL)
10.1. Introduction
10.2. Feature Overview
10.3. Expression Evaluation using Spring’s Expression Interface
10.3.1. The EvaluationContext interface
Type Conversion
10.3.2. Parser configuration
10.3.3. SpEL compilation
Compiler configuration
Compiler limitations
10.4. Expression support for defining bean definitions
10.4.1. XML based configuration
10.4.2. Annotation­based configuration
10.5. Language Reference
10.5.1. Literal expressions
10.5.2. Properties, Arrays, Lists, Maps, Indexers
10.5.3. Inline lists
10.5.4. Inline Maps
10.5.5. Array construction
10.5.6. Methods
10.5.7. Operators
Relational operators
Logical operators
Mathematical operators
10.5.8. Assignment
10.5.9. Types
10.5.10. Constructors
10.5.11. Variables
The #this and #root variables
10.5.12. Functions
10.5.13. Bean references
10.5.14. Ternary Operator (If­Then­Else)
10.5.15. The Elvis Operator
10.5.16. Safe Navigation operator
10.5.17. Collection Selection
10.5.18. Collection Projection
10.5.19. Expression templating
10.6. Classes used in the examples
11. Aspect Oriented Programming with Spring
11.1. Introduction
11.1.1. AOP concepts
11.1.2. Spring AOP capabilities and goals
11.1.3. AOP Proxies
11.2. @AspectJ support
11.2.1. Enabling @AspectJ Support
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 5/645
08/01/2017 Spring Framework Reference Documentation
Enabling @AspectJ Support with Java configuration
Enabling @AspectJ Support with XML configuration
11.2.2. Declaring an aspect
11.2.3. Declaring a pointcut
Supported Pointcut Designators
Combining pointcut expressions
Sharing common pointcut definitions
Examples
Writing good pointcuts
11.2.4. Declaring advice
Before advice
After returning advice
After throwing advice
After (finally) advice
Around advice
Advice parameters
Advice ordering
11.2.5. Introductions
11.2.6. Aspect instantiation models
11.2.7. Example
11.3. Schema­based AOP support
11.3.1. Declaring an aspect
11.3.2. Declaring a pointcut
11.3.3. Declaring advice
Before advice
After returning advice
After throwing advice
After (finally) advice
Around advice
Advice parameters
Advice ordering
11.3.4. Introductions
11.3.5. Aspect instantiation models
11.3.6. Advisors
11.3.7. Example
11.4. Choosing which AOP declaration style to use
11.4.1. Spring AOP or full AspectJ?
11.4.2. @AspectJ or XML for Spring AOP?
11.5. Mixing aspect types
11.6. Proxying mechanisms
11.6.1. Understanding AOP proxies
11.7. Programmatic creation of @AspectJ Proxies
11.8. Using AspectJ with Spring applications
11.8.1. Using AspectJ to dependency inject domain objects with Spring
Unit testing @Configurable objects
Working with multiple application contexts
11.8.2. Other Spring aspects for AspectJ
11.8.3. Configuring AspectJ aspects using Spring IoC
11.8.4. Load­time weaving with AspectJ in the Spring Framework
A first example
Aspects
'META­INF/aop.xml'
Required libraries (JARS)
Spring configuration
Environment­specific configuration
11.9. Further Resources
12. Spring AOP APIs
12.1. Introduction
12.2. Pointcut API in Spring
12.2.1. Concepts
12.2.2. Operations on pointcuts
12.2.3. AspectJ expression pointcuts
12.2.4. Convenience pointcut implementations
Static pointcuts
Dynamic pointcuts
12.2.5. Pointcut superclasses
12.2.6. Custom pointcuts
12.3. Advice API in Spring
12.3.1. Advice lifecycles
12.3.2. Advice types in Spring
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 6/645
08/01/2017 Spring Framework Reference Documentation
Interception around advice
Before advice
Throws advice
After Returning advice
Introduction advice
12.4. Advisor API in Spring
12.5. Using the ProxyFactoryBean to create AOP proxies
12.5.1. Basics
12.5.2. JavaBean properties
12.5.3. JDK­ and CGLIB­based proxies
12.5.4. Proxying interfaces
12.5.5. Proxying classes
12.5.6. Using 'global' advisors
12.6. Concise proxy definitions
12.7. Creating AOP proxies programmatically with the ProxyFactory
12.8. Manipulating advised objects
12.9. Using the "auto­proxy" facility
12.9.1. Autoproxy bean definitions
BeanNameAutoProxyCreator
DefaultAdvisorAutoProxyCreator
AbstractAdvisorAutoProxyCreator
12.9.2. Using metadata­driven auto­proxying
12.10. Using TargetSources
12.10.1. Hot swappable target sources
12.10.2. Pooling target sources
12.10.3. Prototype target sources
12.10.4. ThreadLocal target sources
12.11. Defining new Advice types
12.12. Further resources
IV. Testing
13. Introduction to Spring Testing
14. Unit Testing
14.1. Mock Objects
14.1.1. Environment
14.1.2. JNDI
14.1.3. Servlet API
14.1.4. Portlet API
14.2. Unit Testing support Classes
14.2.1. General testing utilities
14.2.2. Spring MVC
15. Integration Testing
15.1. Overview
15.2. Goals of Integration Testing
15.2.1. Context management and caching
15.2.2. Dependency Injection of test fixtures
15.2.3. Transaction management
15.2.4. Support classes for integration testing
15.3. JDBC Testing Support
15.4. Annotations
15.4.1. Spring Testing Annotations
@BootstrapWith
@ContextConfiguration
@WebAppConfiguration
@ContextHierarchy
@ActiveProfiles
@TestPropertySource
@DirtiesContext
@TestExecutionListeners
@Commit
@Rollback
@BeforeTransaction
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 7/645
08/01/2017 Spring Framework Reference Documentation
@AfterTransaction
@Sql
@SqlConfig
@SqlGroup
15.4.2. Standard Annotation Support
15.4.3. Spring JUnit 4 Testing Annotations
@IfProfileValue
@ProfileValueSourceConfiguration
@Timed
@Repeat
15.4.4. Meta­Annotation Support for Testing
15.5. Spring TestContext Framework
15.5.1. Key abstractions
TestContext
TestContextManager
TestExecutionListener
Context Loaders
15.5.2. Bootstrapping the TestContext framework
15.5.3. TestExecutionListener configuration
Registering custom TestExecutionListeners
Automatic discovery of default TestExecutionListeners
Ordering TestExecutionListeners
Merging TestExecutionListeners
15.5.4. Context management
Context configuration with XML resources
Context configuration with Groovy scripts
Context configuration with annotated classes
Mixing XML, Groovy scripts, and annotated classes
Context configuration with context initializers
Context configuration inheritance
Context configuration with environment profiles
Context configuration with test property sources
Loading a WebApplicationContext
Context caching
Context hierarchies
15.5.5. Dependency injection of test fixtures
15.5.6. Testing request and session scoped beans
15.5.7. Transaction management
Test­managed transactions
Enabling and disabling transactions
Transaction rollback and commit behavior
Programmatic transaction management
Executing code outside of a transaction
Configuring a transaction manager
Demonstration of all transaction­related annotations
15.5.8. Executing SQL scripts
Executing SQL scripts programmatically
Executing SQL scripts declaratively with @Sql
15.5.9. TestContext Framework support classes
Spring JUnit 4 Runner
Spring JUnit 4 Rules
JUnit 4 support classes
TestNG support classes
15.6. Spring MVC Test Framework
15.6.1. Server­Side Tests
Static Imports
Setup Options
Performing Requests
Defining Expectations
Filter Registrations
Differences between Out­of­Container and End­to­End Integration Tests
Further Server­Side Test Examples
15.6.2. HtmlUnit Integration
Why HtmlUnit Integration?
MockMvc and HtmlUnit
MockMvc and WebDriver
MockMvc and Geb
15.6.3. Client­Side REST Tests
Static Imports
Further Examples of Client­side REST Tests
15.7. PetClinic Example
16. Further Resources
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 8/645
08/01/2017 Spring Framework Reference Documentation
V. Data Access
17. Transaction Management
17.1. Introduction to Spring Framework transaction management
17.2. Advantages of the Spring Framework’s transaction support model
17.2.1. Global transactions
17.2.2. Local transactions
17.2.3. Spring Framework’s consistent programming model
17.3. Understanding the Spring Framework transaction abstraction
17.4. Synchronizing resources with transactions
17.4.1. High­level synchronization approach
17.4.2. Low­level synchronization approach
17.4.3. TransactionAwareDataSourceProxy
17.5. Declarative transaction management
17.5.1. Understanding the Spring Framework’s declarative transaction implementation
17.5.2. Example of declarative transaction implementation
17.5.3. Rolling back a declarative transaction
17.5.4. Configuring different transactional semantics for different beans
17.5.5. <tx:advice/> settings
17.5.6. Using @Transactional
@Transactional settings
Multiple Transaction Managers with @Transactional
Custom shortcut annotations
17.5.7. Transaction propagation
Required
RequiresNew
Nested
17.5.8. Advising transactional operations
17.5.9. Using @Transactional with AspectJ
17.6. Programmatic transaction management
17.6.1. Using the TransactionTemplate
Specifying transaction settings
17.6.2. Using the PlatformTransactionManager
17.7. Choosing between programmatic and declarative transaction management
17.8. Transaction bound event
17.9. Application server­specific integration
17.9.1. IBM WebSphere
17.9.2. Oracle WebLogic Server
17.10. Solutions to common problems
17.10.1. Use of the wrong transaction manager for a specific DataSource
17.11. Further Resources
18. DAO support
18.1. Introduction
18.2. Consistent exception hierarchy
18.3. Annotations used for configuring DAO or Repository classes
19. Data access with JDBC
19.1. Introduction to Spring Framework JDBC
19.1.1. Choosing an approach for JDBC database access
19.1.2. Package hierarchy
19.2. Using the JDBC core classes to control basic JDBC processing and error handling
19.2.1. JdbcTemplate
Examples of JdbcTemplate class usage
JdbcTemplate best practices
19.2.2. NamedParameterJdbcTemplate
19.2.3. SQLExceptionTranslator
19.2.4. Executing statements
19.2.5. Running queries
19.2.6. Updating the database
19.2.7. Retrieving auto­generated keys
19.3. Controlling database connections
19.3.1. DataSource
19.3.2. DataSourceUtils
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 9/645
08/01/2017 Spring Framework Reference Documentation
19.3.3. SmartDataSource
19.3.4. AbstractDataSource
19.3.5. SingleConnectionDataSource
19.3.6. DriverManagerDataSource
19.3.7. TransactionAwareDataSourceProxy
19.3.8. DataSourceTransactionManager
19.3.9. NativeJdbcExtractor
19.4. JDBC batch operations
19.4.1. Basic batch operations with the JdbcTemplate
19.4.2. Batch operations with a List of objects
19.4.3. Batch operations with multiple batches
19.5. Simplifying JDBC operations with the SimpleJdbc classes
19.5.1. Inserting data using SimpleJdbcInsert
19.5.2. Retrieving auto­generated keys using SimpleJdbcInsert
19.5.3. Specifying columns for a SimpleJdbcInsert
19.5.4. Using SqlParameterSource to provide parameter values
19.5.5. Calling a stored procedure with SimpleJdbcCall
19.5.6. Explicitly declaring parameters to use for a SimpleJdbcCall
19.5.7. How to define SqlParameters
19.5.8. Calling a stored function using SimpleJdbcCall
19.5.9. Returning ResultSet/REF Cursor from a SimpleJdbcCall
19.6. Modeling JDBC operations as Java objects
19.6.1. SqlQuery
19.6.2. MappingSqlQuery
19.6.3. SqlUpdate
19.6.4. StoredProcedure
19.7. Common problems with parameter and data value handling
19.7.1. Providing SQL type information for parameters
19.7.2. Handling BLOB and CLOB objects
19.7.3. Passing in lists of values for IN clause
19.7.4. Handling complex types for stored procedure calls
19.8. Embedded database support
19.8.1. Why use an embedded database?
19.8.2. Creating an embedded database using Spring XML
19.8.3. Creating an embedded database programmatically
19.8.4. Selecting the embedded database type
Using HSQL
Using H2
Using Derby
19.8.5. Testing data access logic with an embedded database
19.8.6. Generating unique names for embedded databases
19.8.7. Extending the embedded database support
19.9. Initializing a DataSource
19.9.1. Initializing a database using Spring XML
Initialization of other components that depend on the database
20. Object Relational Mapping (ORM) Data Access
20.1. Introduction to ORM with Spring
20.2. General ORM integration considerations
20.2.1. Resource and transaction management
20.2.2. Exception translation
20.3. Hibernate
20.3.1. SessionFactory setup in a Spring container
20.3.2. Implementing DAOs based on plain Hibernate API
20.3.3. Declarative transaction demarcation
20.3.4. Programmatic transaction demarcation
20.3.5. Transaction management strategies
20.3.6. Comparing container­managed and locally defined resources
20.3.7. Spurious application server warnings with Hibernate
20.4. JDO
20.4.1. PersistenceManagerFactory setup
20.4.2. Implementing DAOs based on the plain JDO API
20.4.3. Transaction management
20.4.4. JdoDialect
20.5. JPA
20.5.1. Three options for JPA setup in a Spring environment
LocalEntityManagerFactoryBean
Obtaining an EntityManagerFactory from JNDI
LocalContainerEntityManagerFactoryBean
Dealing with multiple persistence units
http://docs.spring.io/spring/docs/current/spring­framework­reference/htmlsingle/ 10/645