Reference Documentation(Work in progress)
3.0.0.M4Copyright 2004-2009 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 Abed Rabbo
Copies of this document may be made for your own use and for
distribution to others, provided that you do not charge any fee for
such copies and further provided that each copy contains this
Copyright Notice, whether distributed in print or
electronically.
Spring Framework
Table of ContentsI. Overview of Spring Framework
..............................................................................................1
Preface
............................................................................................................................
ii 1. Introduction to Spring Framework
..................................................................................3
1.1. Dependency Injection
.........................................................................................3
1.2. Modules
............................................................................................................4
Core Container
.................................................................................................5
Data Access/Integration
....................................................................................6
Web
.................................................................................................................6
AOP and Instrumentation
..................................................................................7
Test
.................................................................................................................7
1.3. Usage scenarios
.................................................................................................7
II. What's New in Spring 3.0
...................................................................................................12
2. New Features and Enhancements in Spring 3.0
.............................................................13
2.1. Java 5
..............................................................................................................13
2.2. Improved documentation
..................................................................................13
2.3. New getting started tutorial
...............................................................................13
2.4. New module organization and build system
.......................................................14 2.5.
Overview of new features
.................................................................................15
Core APIs updated for Java 5
..........................................................................15
Spring Expression Language
...........................................................................16
The Inversion of Control (IoC) container
..........................................................16 Java
based bean metadata
........................................................................16
Defining bean metadata within components
..............................................17 The Data Tier
.................................................................................................18
The Web Tier
.................................................................................................18
Comprehensive REST support
.................................................................18
@MVC additions
...................................................................................18
Declarative model validation
...........................................................................18
Early support for Java EE 6
.............................................................................18
Support for embedded databases
......................................................................19
III. Core Technologies
............................................................................................................20
3. The IoC container
.......................................................................................................21
3.1. Introduction to the Spring IoC container and beans
.............................................21 3.2. Container
overview
..........................................................................................21
Configuration metadata
...................................................................................22
Instantiating a container
..................................................................................24
Composing XML-based configuration metadata
.......................................25 Using the container
.........................................................................................26
3.3. Bean overview
.................................................................................................26
Naming beans
.................................................................................................28
3.0.0.M4
Reference Documentation
ii
Spring Framework
Aliasing a bean outside the bean definition
...............................................28 Instantiating
beans
..........................................................................................29
Instantiation with a constructor
................................................................30
Instantiation with a static factory method
.................................................30 Instantiation
using an instance factory method
..........................................31 3.4. Dependencies
...................................................................................................31
Dependency injection
......................................................................................31
Constructor-based dependency injection
...................................................32 Setter-based
dependency injection
...........................................................33
Dependency resolution process
................................................................35
Examples of dependency injection
...........................................................36
Dependencies and configuration in detail
.........................................................38
Straight values (primitives, Strings, and so on)
.........................................38 References to other
beans (collaborators)
.................................................40 Inner beans
.............................................................................................41
Collections
.............................................................................................41
Null and empty string values
...................................................................43
XML shortcut with the p-namespace
........................................................44 Compound
property names
......................................................................45
Using depends-on
...........................................................................................45
Lazy-initialized beans
.....................................................................................46
Autowiring collaborators
.................................................................................47
Limitations and disadvantages of autowiring
............................................48 Excluding a bean
from autowiring
...........................................................49
Checking for dependencies
..............................................................................49
Method injection
............................................................................................50
Lookup method injection
.........................................................................51
Arbitrary method replacement
.................................................................52
3.5. Bean scopes
.....................................................................................................53
The singleton scope
........................................................................................54
The prototype scope
........................................................................................55
Singleton beans with prototype-bean dependencies
...........................................56 Request, session, and
global session scopes
......................................................57 Initial
web configuration
.........................................................................57
Request scope
.........................................................................................58
Session scope
.........................................................................................58
Global session scope
...............................................................................59
Scoped beans as dependencies
.................................................................59
Custom scopes
...............................................................................................61
Creating a custom scope
..........................................................................62
Using a custom scope
..............................................................................62
3.6. Customizing the nature of a bean
.......................................................................63
Lifecycle callbacks
.........................................................................................64
Initialization callbacks
............................................................................64
Destruction callbacks
..............................................................................65
3.0.0.M4 Reference Documentation iii
Spring Framework
Default initialization and destroy methods
................................................65 Combining
lifecycle mechanisms
............................................................66
Shutting down the Spring IoC container gracefully in non-web
applications 67 ApplicationContextAware and BeanNameAware
..............................................68 3.7. Bean
definition inheritance
...............................................................................69
3.8. Container extension points
................................................................................70
Customizing beans using the BeanPostProcessor Interface
................................70 Example: Hello World,
BeanPostProcessor-style ......................................72
Example: The RequiredAnnotationBeanPostProcessor
..............................73 Customizing configuration metadata
with BeanFactoryPostProcessor interface ...73 Example: the
PropertyPlaceholderConfigurer
...........................................74 Example: the
PropertyOverrideConfigurer
...............................................76 Customizing
instantiation logic with the FactoryBean Interface
.........................77 3.9. Annotation-based container
configuration
..........................................................77
@Required
.....................................................................................................78
@Autowired
...................................................................................................79
Fine-tuning annotation-based autowiring with qualifiers
...................................81 CustomAutowireConfigurer
............................................................................86
@Resource
.....................................................................................................86
@PostConstruct and @PreDestroy
...................................................................88
3.10. Classpath scanning and managed components
..................................................88 @Component and
further stereotype annotations
..............................................89 Automatically
detecting classes and registering bean definitions
........................89 Using filters to customize scanning
..................................................................90
Defining bean metadata within components
......................................................91 Naming
autodetected components
....................................................................93
Providing a scope for autodetected components
................................................93 Providing
qualifier metadata with annotations
..................................................94 3.11.
Java-based container configuration
..................................................................95
Using the @Configuration annotation
..............................................................95
Using the @Bean annotation
...........................................................................95
Declaring a bean
.....................................................................................96
Injecting dependencies
............................................................................96
Receiving lifecycle callbacks
...................................................................96
Specifying bean scope
.............................................................................98
Customizing bean naming
.......................................................................99
3.12. Registering a LoadTimeWeaver
......................................................................99
3.13. Additional Capabilities of the ApplicationContext
.......................................... 100 Internationalization
using MessageSource
...................................................... 100 Standard
and Custom Events
.........................................................................
103 Convenient access to low-level resources
....................................................... 106
Convenient ApplicationContext instantiation for web applications
................... 106 Deploying a Spring ApplicationContext as a
J2EE RAR file ............................ 107 3.14. The
BeanFactory
..........................................................................................
108 BeanFactory or ApplicationContext?
............................................................. 108
3.0.0.M4 Reference Documentation iv
Spring Framework
Glue code and the evil singleton
....................................................................
110 4. Resources
.................................................................................................................
111 4.1. Introduction
...................................................................................................
111 4.2. The Resource interface
...................................................................................
111 4.3. Built-in Resource implementations
..................................................................
112 UrlResource
.................................................................................................
112 ClassPathResource
.......................................................................................
113 FileSystemResource
.....................................................................................
113 ServletContextResource
................................................................................
113 InputStreamResource
....................................................................................
113 ByteArrayResource
......................................................................................
114 4.4. The ResourceLoader
.......................................................................................
114 4.5. The ResourceLoaderAware interface
............................................................... 115
4.6. Resources as dependencies
.............................................................................
116 4.7. Application contexts and Resource paths
......................................................... 116
Constructing application contexts
..................................................................
116 Constructing ClassPathXmlApplicationContext instances -
shortcuts ....... 117 Wildcards in application context constructor
resource paths ............................ 118 Ant-style Patterns
.................................................................................
118 The classpath*: prefix
...........................................................................
119 Other notes relating to wildcards
............................................................ 119
FileSystemResource caveats
..........................................................................
120 5. Validation, Data-binding, the BeanWrapper, and
PropertyEditors ................................ 122 5.1.
Introduction
...................................................................................................
122 5.2. Validation using Spring's Validator interface
.................................................... 122 5.3.
Resolving codes to error messages
..................................................................
124 5.4. Bean manipulation and the BeanWrapper
........................................................ 124
Setting and getting basic and nested properties
............................................... 125 Built-in
PropertyEditor implementations
........................................................ 126
Registering additional custom PropertyEditors
....................................... 129 6. Spring Expression
Language (SpEL)
..........................................................................
133 6.1. Introduction
...................................................................................................
133 6.2. Feature Overview
...........................................................................................
133 6.3. Expression Evaluation using Spring's Expression Interface
............................... 134 The EvaluationContext interface
....................................................................
136 Type Conversion
..................................................................................
136 6.4. Expression support for defining bean definitions
.............................................. 137 XML based
configuration
.............................................................................
137 Annotation-based configuration
.....................................................................
138 6.5. Language Reference
.......................................................................................
139 Literal expressions
........................................................................................
139 Properties, Arrays, Lists, Maps, Indexers
........................................................ 139
Methods
.......................................................................................................
140 Operators
.....................................................................................................
141 Relational operators
..............................................................................
141 3.0.0.M4 Reference Documentation v
Spring Framework
Logical operators
..................................................................................
141 Mathematical operators
.........................................................................
142 Assignment
..................................................................................................
142 Types
...........................................................................................................
143 Constructors
.................................................................................................
143 Variables
......................................................................................................
143 The #this variable
.................................................................................
144 Functions
.....................................................................................................
144 Ternary Operator (If-Then-Else)
....................................................................
144 The Elvis Operator
.......................................................................................
145 Safe Navigation operator
...............................................................................
146 Collection Selection
......................................................................................
146 Collection Projection
....................................................................................
147 Expression templating
...................................................................................
147 6.6. Classes used in the examples
...........................................................................
147 7. Aspect Oriented Programming with Spring
.................................................................
151 7.1. Introduction
...................................................................................................
151 AOP concepts
...............................................................................................
151 Spring AOP capabilities and goals
.................................................................
153 AOP Proxies
................................................................................................
154 7.2. @AspectJ support
..........................................................................................
155 Enabling @AspectJ Support
..........................................................................
155 Declaring an aspect
.......................................................................................
155 Declaring a pointcut
......................................................................................
156 Supported Pointcut Designators
............................................................. 157
Combining pointcut expressions
............................................................ 158
Sharing common pointcut definitions
..................................................... 159 Examples
.............................................................................................
160 Declaring advice
...........................................................................................
163 Before advice
.......................................................................................
163 After returning advice
...........................................................................
163 After throwing advice
...........................................................................
164 After (finally) advice
............................................................................
165 Around advice
......................................................................................
165 Advice parameters
................................................................................
166 Advice ordering
....................................................................................
169 Introductions
................................................................................................
170 Aspect instantiation models
...........................................................................
170 Example
.......................................................................................................
171 7.3. Schema-based AOP support
............................................................................
173 Declaring an aspect
.......................................................................................
173 Declaring a pointcut
......................................................................................
174 Declaring advice
...........................................................................................
175 Before advice
.......................................................................................
175 After returning advice
...........................................................................
176 3.0.0.M4 Reference Documentation vi
Spring Framework
After throwing advice
...........................................................................
177 After (finally) advice
............................................................................
177 Around advice
......................................................................................
178 Advice parameters
................................................................................
178 Advice ordering
....................................................................................
180 Introductions
................................................................................................
180 Aspect instantiation models
...........................................................................
181 Advisors
......................................................................................................
181 Example
.......................................................................................................
182 7.4. Choosing which AOP declaration style to use
.................................................. 184 Spring AOP
or full AspectJ?
.........................................................................
184 @AspectJ or XML for Spring AOP?
.............................................................. 184
7.5. Mixing aspect types
........................................................................................
185 7.6. Proxying mechanisms
.....................................................................................
185 Understanding AOP proxies
..........................................................................
186 7.7. Programmatic creation of @AspectJ Proxies
.................................................... 189 7.8. Using
AspectJ with Spring applications
........................................................... 189
Using AspectJ to dependency inject domain objects with Spring
...................... 190 Unit testing @Configurable objects
....................................................... 192 Working
with multiple application contexts
............................................ 192 Other Spring
aspects for AspectJ
...................................................................
193 Configuring AspectJ aspects using Spring IoC
................................................ 194 Load-time
weaving with AspectJ in the Spring Framework
............................. 195 A first example
.....................................................................................
195 Aspects
................................................................................................
198 'META-INF/aop.xml'
............................................................................
198 Required libraries (JARS)
.....................................................................
199 Spring configuration
.............................................................................
199 Environment-specific configuration
....................................................... 201 7.9.
Further Resources
..........................................................................................
202 8. Spring AOP APIs
......................................................................................................
204 8.1. Introduction
...................................................................................................
204 8.2. Pointcut API in Spring
....................................................................................
204 Concepts
......................................................................................................
204 Operations on pointcuts
.................................................................................
205 AspectJ expression pointcuts
.........................................................................
205 Convenience pointcut implementations
.......................................................... 205
Static pointcuts
.....................................................................................
206 Dynamic pointcuts
................................................................................
207 Pointcut superclasses
....................................................................................
207 Custom pointcuts
..........................................................................................
208 8.3. Advice API in Spring
.....................................................................................
208 Advice lifecycles
..........................................................................................
208 Advice types in Spring
..................................................................................
208 Interception around advice
....................................................................
208 3.0.0.M4 Reference Documentation vii
Spring Framework
Before advice
.......................................................................................
209 Throws advice
......................................................................................
210 After Returning advice
..........................................................................
211 Introduction advice
...............................................................................
212 8.4. Advisor API in Spring
....................................................................................
215 8.5. Using the ProxyFactoryBean to create AOP proxies
......................................... 215 Basics
..........................................................................................................
215 JavaBean properties
......................................................................................
216 JDK- and CGLIB-based proxies
....................................................................
217 Proxying interfaces
.......................................................................................
218 Proxying classes
...........................................................................................
220 Using 'global' advisors
..................................................................................
220 8.6. Concise proxy definitions
...............................................................................
221 8.7. Creating AOP proxies programmatically with the
ProxyFactory ........................ 222 8.8. Manipulating advised
objects
..........................................................................
222 8.9. Using the "autoproxy" facility
.........................................................................
224 Autoproxy bean definitions
...........................................................................
224 BeanNameAutoProxyCreator
................................................................
224 DefaultAdvisorAutoProxyCreator
.......................................................... 225
AbstractAdvisorAutoProxyCreator
........................................................ 226 Using
metadata-driven auto-proxying
............................................................ 226
8.10. Using TargetSources
....................................................................................
229 Hot swappable target sources
.........................................................................
229 Pooling target sources
...................................................................................
230 Prototype target sources
................................................................................
231 ThreadLocal target sources
............................................................................
231 8.11. Defining new Advice types
...........................................................................
232 8.12. Further resources
..........................................................................................
232 9. Testing
.....................................................................................................................
234 9.1. Introduction
...................................................................................................
234 9.2. Unit testing
....................................................................................................
234 Mock objects
................................................................................................
234 JNDI
....................................................................................................
234 Servlet API
..........................................................................................
234 Portlet API
...........................................................................................
235 Unit testing support classes
...........................................................................
235 General utilities
....................................................................................
235 Spring MVC
.........................................................................................
235 9.3. Integration testing
..........................................................................................
235 Overview
.....................................................................................................
235 Goals
...........................................................................................................
236 Context management and caching
.......................................................... 236
Dependency Injection of test fixtures
..................................................... 237
Transaction management
.......................................................................
237 Integration testing support classes
.......................................................... 238
3.0.0.M4 Reference Documentation viii
Spring Framework
JDBC testing support
....................................................................................
238 Annotations
..................................................................................................
239 Spring TestContext Framework
.....................................................................
243 Key abstractions
...................................................................................
244 Context management and caching
.......................................................... 245
Dependency Injection of test fixtures
..................................................... 247
Transaction management
.......................................................................
250 TestContext support classes
...................................................................
252 PetClinic example
.........................................................................................
255 9.4. Further Resources
..........................................................................................
257 IV. Data Access
....................................................................................................................
258 10. Transaction Management
.........................................................................................
259 10.1. Introduction to Spring Framework transaction management
............................ 259 10.2. Advantages of the Spring
Framework's transaction support model ................... 259
Global transactions
.......................................................................................
260 Local transactions
.........................................................................................
260 Spring Framework's consistent programming model
....................................... 260 10.3. Understanding the
Spring Framework transaction abstraction ..........................
261 10.4. Synchronizing resources with transactions
..................................................... 265
High-level synchronization approach
............................................................. 265
Low-level synchronization approach
.............................................................. 265
TransactionAwareDataSourceProxy
............................................................... 266
10.5. Declarative transaction management
.............................................................. 266
Understanding the Spring Framework's declarative transaction
implementation 268 Example of declarative transaction
implementation ......................................... 269
Rolling back a declarative transaction
............................................................ 273
Configuring different transactional semantics for different beans
..................... 274 settings
.....................................................................................
276 Using @Transactional
...................................................................................
277 @Transactional settings
........................................................................
281 Transaction propagation
................................................................................
282 Required
..............................................................................................
282 RequiresNew
........................................................................................
283 Nested
.................................................................................................
284 Advising transactional operations
..................................................................
284 Using @Transactional with AspectJ
............................................................... 287
10.6. Programmatic transaction management
.......................................................... 288
Using the TransactionTemplate
.....................................................................
288 Specifying transaction settings
............................................................... 289
Using the PlatformTransactionManager
......................................................... 290 10.7.
Choosing between programmatic and declarative transaction
management ....... 291 10.8. Application server-specific
integration
........................................................... 291 IBM
WebSphere
...........................................................................................
292 BEA WebLogic Server
.................................................................................
292 Oracle OC4J
.................................................................................................
292 3.0.0.M4 Reference Documentation ix
Spring Framework
10.9. Solutions to common problems
.....................................................................
292 Use of the wrong transaction manager for a specific DataSource
...................... 292 10.10. Further Resources
.......................................................................................
292 11. DAO support
..........................................................................................................
294 11.1. Introduction
.................................................................................................
294 11.2. Consistent exception hierarchy
......................................................................
294 11.3. Annotations used for configuring DAO or Repository
classes .......................... 295 12. Data access using JDBC
..........................................................................................
297 12.1. Introduction
.................................................................................................
297 Choosing a style
...........................................................................................
297 The package hierarchy
..................................................................................
298 12.2. Using the JDBC Core classes to control basic JDBC
processing and error handling
.............................................................................................................................
299 JdbcTemplate
...............................................................................................
299 Examples
.............................................................................................
299 JdbcTemplate idioms (best practices)
..................................................... 301
NamedParameterJdbcTemplate
......................................................................
303 SimpleJdbcTemplate
.....................................................................................
305 DataSource
..................................................................................................
307 SQLExceptionTranslator
...............................................................................
308 Executing statements
....................................................................................
309 Running Queries
...........................................................................................
310 Updating the database
...................................................................................
311 Retrieving auto-generated keys
......................................................................
311 12.3. Controlling database connections
..................................................................
312 DataSourceUtils
...........................................................................................
312 SmartDataSource
..........................................................................................
312 AbstractDataSource
......................................................................................
312 SingleConnectionDataSource
........................................................................
312 DriverManagerDataSource
............................................................................
313 TransactionAwareDataSourceProxy
............................................................... 313
DataSourceTransactionManager
....................................................................
313 NativeJdbcExtractor
.....................................................................................
314 12.4. JDBC batch operations
.................................................................................
314 Batch operations with the JdbcTemplate
......................................................... 314 Batch
operations with the SimpleJdbcTemplate
.............................................. 315 12.5.
Simplifying JDBC operations with the SimpleJdbc classes
.............................. 316 Inserting data using
SimpleJdbcInsert
............................................................ 317
Retrieving auto-generated keys using SimpleJdbcInsert
................................... 317 Specifying the columns to
use for a SimpleJdbcInsert .....................................
318 Using SqlParameterSource to provide parameter values
.................................. 319 Calling a stored procedure
using SimpleJdbcCall ............................................
320 Declaring parameters to use for a SimpleJdbcCall
........................................... 321 How to define
SqlParameters
.........................................................................
322 Calling a stored function using SimpleJdbcCall
.............................................. 323 3.0.0.M4
Reference Documentation x
Spring Framework
Returning ResultSet/REF Cursor from a SimpleJdbcCall
................................. 324 12.6. Modeling JDBC
operations as Java objects
.................................................... 325 SqlQuery
......................................................................................................
325 MappingSqlQuery
........................................................................................
325 SqlUpdate
....................................................................................................
326 StoredProcedure
...........................................................................................
327 12.7. Common issues with parameter and data value handling
................................. 331 Providing SQL type
information for parameters
.............................................. 331 Handling BLOB
and CLOB objects
............................................................... 331
Passing in lists of values for IN clause
........................................................... 333
Handling complex types for stored procedure calls
......................................... 333 12.8. Embedded
database support
..........................................................................
334 Why use an embedded database?
...................................................................
335 Creating an embedded database instance using Spring XML
........................... 335 Creating an embedded database
instance programatically ................................ 335
Extending the embedded database support
...................................................... 335 Using
HSQL
................................................................................................
336 Using H2
.....................................................................................................
336 Using Derby
.................................................................................................
336 Unit testing data access logic with an EmbeddedDatabase
............................... 336 13. Object Relational Mapping
(ORM) Data Access
....................................................... 337 13.1.
Introduction to ORM with Spring
..................................................................
337 13.2. General ORM integration considerations
........................................................ 338
Resource and transaction management
........................................................... 338
Exception translation
....................................................................................
339 13.3. Hibernate
.....................................................................................................
340 SessionFactory setup in a Spring container
..................................................... 340
Implementing DAOs based on plain Hibernate 3 API
...................................... 341 Declarative transaction
demarcation
............................................................... 342
Programmatic transaction demarcation
........................................................... 344
Transaction management strategies
................................................................
345 Comparing container-managed and locally defined resources
.......................... 347 Spurious application server warnings
with Hibernate ...................................... 348 13.4. JDO
.............................................................................................................
349 PersistenceManagerFactory setup
..................................................................
349 Implementing DAOs based on the plain JDO API
........................................... 350 Transaction
management
...............................................................................
352 JdoDialect
....................................................................................................
353 13.5. JPA
.............................................................................................................
354 Three options for JPA setup in a Spring environment
...................................... 354
LocalEntityManagerFactoryBean
........................................................... 354
Obtaining an EntityManagerFactory from JNDI
...................................... 355
LocalContainerEntityManagerFactoryBean
............................................ 355 Dealing with
multiple persistence units
.................................................. 359 Implementing
DAOs based on plain JPA
........................................................ 360
3.0.0.M4 Reference Documentation xi
Spring Framework
Transaction Management
..............................................................................
362 JpaDialect
....................................................................................................
363 13.6. iBATIS SQL Maps
.......................................................................................
364 Setting up the SqlMapClient
..........................................................................
364 Using SqlMapClientTemplate and SqlMapClientDaoSupport
.......................... 366 Implementing DAOs based on plain
iBATIS API ........................................... 366 14.
Marshalling XML using O/X Mappers
.....................................................................
368 14.1. Introduction
.................................................................................................
368 14.2. Marshaller and Unmarshaller
........................................................................
368 Marshaller
....................................................................................................
368 Unmarshaller
................................................................................................
369 XmlMappingException
.................................................................................
370 14.3. Using Marshaller and Unmarshaller
............................................................... 370
14.4. XML Schema-based Configuration
................................................................
372 14.5. JAXB
..........................................................................................................
373 Jaxb2Marshaller
...........................................................................................
373 XML Schema-based Configuration
........................................................ 374 14.6.
Castor
..........................................................................................................
374 CastorMarshaller
..........................................................................................
374 Mapping
......................................................................................................
375 14.7. XMLBeans
..................................................................................................
375 XmlBeansMarshaller
....................................................................................
375 XML Schema-based Configuration
........................................................ 375 14.8.
JiBX
............................................................................................................
376 JibxMarshaller
..............................................................................................
376 XML Schema-based Configuration
........................................................ 376 14.9.
XStream
......................................................................................................
377 XStreamMarshaller
.......................................................................................
377 V. The Web
..........................................................................................................................
378 15. Web MVC framework
.............................................................................................
379 15.1. Introduction to Spring Web MVC framework
................................................. 379 Features of
Spring Web MVC
.......................................................................
380 Pluggability of other MVC implementations
................................................... 381 15.2. The
DispatcherServlet
..................................................................................
381 15.3. Implementing Controllers
.............................................................................
386 Defining a controller with @Controller
.......................................................... 387
Mapping requests with @RequestMapping
..................................................... 387 URI
Templates
.....................................................................................
389 Advanced @RequestMapping options
.................................................... 390 Supported
handler method arguments and return types
............................ 391 Binding request parameters to
method parameters with @RequestParam .. 394 Mapping the request
body with the @RequestBody annotation ................ 394 Mapping
the response body with the @ResponseBody annotation ........... 395
Providing a link to data from the model with @ModelAttribute
............... 395 Specifying attributes to store in a session
with @SessionAttributes .......... 396 3.0.0.M4 Reference
Documentation xii
Spring Framework
Mapping cookie values with the @CookieValue annotation
.................... 397 Mapping request header attributes with the
@RequestHeader annotation .. 397 Customizing WebDataBinder
initialization ............................................. 398
15.4. Handler mappings
........................................................................................
399 Intercepting requests - the HandlerInterceptor interface
................................... 400 15.5. Resolving views
...........................................................................................
401 Resolving views with the ViewResolver interface
........................................... 401 Chaining
ViewResolvers
...............................................................................
403 Redirecting to views
.....................................................................................
404 RedirectView
.......................................................................................
404 The redirect: prefix
...............................................................................
405 The forward: prefix
...............................................................................
405 ContentNegotiatingViewResolver
..................................................................
405 15.6. Using locales
...............................................................................................
408 AcceptHeaderLocaleResolver
........................................................................
408 CookieLocaleResolver
..................................................................................
408 SessionLocaleResolver
.................................................................................
409 LocaleChangeInterceptor
..............................................................................
409 15.7. Using themes
...............................................................................................
409 Overview of themes
......................................................................................
409 Defining themes
...........................................................................................
410 Theme resolvers
...........................................................................................
410 15.8. Spring's multipart (fileupload) support
........................................................... 411
Introduction
.................................................................................................
411 Using the MultipartResolver
..........................................................................
411 Handling a file upload in a form
....................................................................
412 15.9. Handling exceptions
.....................................................................................
415 HandlerExceptionResolver
............................................................................
415 @ExceptionHandler
......................................................................................
415 15.10. Convention over configuration support
........................................................ 416 The
Controller ControllerClassNameHandlerMapping
.................................... 416 The Model ModelMap
(ModelAndView)
....................................................... 417 The
View - RequestToViewNameTranslator
.................................................. 419 15.11. ETag
support
..............................................................................................
420 15.12. More Spring Web MVC Resources
.............................................................. 421
16. View technologies
...................................................................................................
422 16.1. Introduction
.................................................................................................
422 16.2. JSP & JSTL
.................................................................................................
422 View resolvers
.............................................................................................
422 'Plain-old' JSPs versus JSTL
..........................................................................
423 Additional tags facilitating development
........................................................ 423 Using
Spring's form tag library
......................................................................
423 Configuration
.......................................................................................
423 The form tag
........................................................................................
423 The input tag
........................................................................................
425 3.0.0.M4 Reference Documentation xiii
Spring Framework
The checkbox tag
..................................................................................
425 The checkboxes tag
..............................................................................
427 The radiobutton tag
...............................................................................
427 The radiobuttons tag
.............................................................................
427 The password tag
..................................................................................
428 The select tag
.......................................................................................
428 The option tag
......................................................................................
429 The options tag
.....................................................................................
429 The textarea tag
....................................................................................
430 The hidden tag
......................................................................................
430 The errors tag
.......................................................................................
430 HTTP Method Conversion
....................................................................
432 16.3. Tiles
............................................................................................................
433 Dependencies
...............................................................................................
433 How to integrate Tiles
...................................................................................
434 UrlBasedViewResolver
.........................................................................
434 ResourceBundleViewResolver
.............................................................. 434
SimpleSpringPreparerFactory and SpringBeanPreparerFactory
................ 435 16.4. Velocity & FreeMarker
.................................................................................
436 Dependencies
...............................................................................................
436 Context configuration
...................................................................................
436 Creating templates
........................................................................................
437 Advanced configuration
................................................................................
437 velocity.properties
................................................................................
437 FreeMarker
..........................................................................................
438 Bind support and form handling
.....................................................................
438 The bind macros
...................................................................................
438 Simple binding
.....................................................................................
439 Form input generation macros
............................................................... 440
HTML escaping and XHTML compliance
............................................. 444 16.5. XSLT
..........................................................................................................
444 My First Words
............................................................................................
445 Bean definitions
...................................................................................
445 Standard MVC controller code
.............................................................. 445
Convert the model data to XML
............................................................ 446
Defining the view properties
..................................................................
446 Document transformation
......................................................................
447 Summary
.....................................................................................................
447 16.6. Document views (PDF/Excel)
.......................................................................
448 Introduction
.................................................................................................
448 Configuration and setup
................................................................................
448 Document view definitions
....................................................................
448 Controller code
.....................................................................................
448 Subclassing for Excel views
..................................................................
449 Subclassing for PDF views
....................................................................
450 3.0.0.M4 Reference Documentation xiv
Spring Framework
16.7. JasperReports
...............................................................................................
450 Dependencies
...............................................................................................
451 Configuration
...............................................................................................
451 Configuring the ViewResolver
.............................................................. 451
Configuring the Views
..........................................................................
451 About Report Files
...............................................................................
452 Using JasperReportsMultiFormatView
................................................... 452 Populating
the ModelAndView
......................................................................
453 Working with Sub-Reports
............................................................................
454 Configuring Sub-Report Files
................................................................
454 Configuring Sub-Report Data Sources
................................................... 455 Configuring
Exporter Parameters
...................................................................
455 16.8. Feed Views
..................................................................................................
456 16.9. XML Marshalling View
................................................................................
457 17. Integrating with other web frameworks
.....................................................................
458 17.1. Introduction
.................................................................................................
458 17.2. Common configuration
.................................................................................
459 17.3. JavaServer Faces 1.1 and 1.2
.........................................................................
460 DelegatingVariableResolver (JSF 1.1/1.2)
...................................................... 461
SpringBeanVariableResolver (JSF 1.1/1.2)
..................................................... 461
SpringBeanFacesELResolver (JSF 1.2+)
........................................................ 462
FacesContextUtils
........................................................................................
462 17.4. Apache Struts 1.x and 2.x
.............................................................................
462 ContextLoaderPlugin
....................................................................................
463 DelegatingRequestProcessor
.................................................................
464 DelegatingActionProxy
.........................................................................
464 ActionSupport Classes
..................................................................................
465 17.5. WebWork 2.x
...............................................................................................
465 17.6. Tapestry 3.x and 4.x
.....................................................................................
466 Injecting Spring-managed beans
....................................................................
467 Dependency Injecting Spring Beans into Tapestry pages
......................... 468 Component definition files
....................................................................
469 Adding abstract accessors
......................................................................
470 Dependency Injecting Spring Beans into Tapestry pages -
Tapestry 4.x style
.............................................................................................................
472 17.7. Further Resources
.........................................................................................
473 18. Portlet MVC Framework
.........................................................................................
475 18.1. Introduction
.................................................................................................
475 Controllers - The C in MVC
..........................................................................
476 Views - The V in MVC
.................................................................................
476 Web-scoped beans
........................................................................................
477 18.2. The DispatcherPortlet
...................................................................................
477 18.3. The ViewRendererServlet
.............................................................................
479 18.4. Controllers
...................................................................................................
480 AbstractController and PortletContentGenerator
............................................. 481 3.0.0.M4
Reference Documentation xv
Spring Framework
Other simple controllers
................................................................................
482 Command Controllers
...................................................................................
482 PortletWrappingController
............................................................................
483 18.5. Handler mappings
........................................................................................
484 PortletModeHandlerMapping
........................................................................
485 ParameterHandlerMapping
............................................................................
485 PortletModeParameterHandlerMapping
......................................................... 485
Adding HandlerInterceptors
..........................................................................
486 HandlerInterceptorAdapter
............................................................................
487 ParameterMappingInterceptor
.......................................................................
487 18.6. Views and resolving them
.............................................................................
487 18.7. Multipart (file upload) support
......................................................................
488 Using the PortletMultipartResolver
................................................................
488 Handling a file upload in a form
....................................................................
489 18.8. Handling exceptions
.....................................................................................
492 18.9. Annotation-based controller configuration
..................................................... 492 Setting
up the dispatcher for annotation support
.............................................. 492 Defining a
controller with @Controller
.......................................................... 493
Mapping requests with @RequestMapping
..................................................... 493 Supported
handler method arguments
............................................................ 495
Binding request parameters to method parameters with @RequestParam
.......... 496 Providing a link to data from the model with
@ModelAttribute ....................... 497 Specifying attributes
to store in a Session with @SessionAttributes ................. 498
Customizing WebDataBinder initialization
..................................................... 498
Customizing data binding with @InitBinder
........................................... 498 Configuring a
custom WebBindingInitializer
.......................................... 499 18.10. Portlet
application deployment
....................................................................
499 VI. Integration
......................................................................................................................
500 19. Remoting and web services using Spring
..................................................................
501 19.1. Introduction
.................................................................................................
501 19.2. Exposing services using RMI
........................................................................
502 Exporting the service using the RmiServiceExporter
....................................... 502 Linking in the service
at the client
.................................................................
503 19.3. Using Hessian or Burlap to remotely call services via
HTTP ........................... 504 Wiring up the
DispatcherServlet for Hessian and co.
....................................... 504 Exposing your beans by
using the HessianServiceExporter .............................. 504
Linking in the service on the client
................................................................
505 Using Burlap
................................................................................................
505 Applying HTTP basic authentication to a service exposed through
Hessian or Burlap
..........................................................................................................
506 19.4. Exposing services using HTTP invokers
........................................................ 506
Exposing the service object
...........................................................................
506 Linking in the service at the client
.................................................................
507 19.5. Web services
................................................................................................
508 Exposing servlet-based web services using JAX-RPC
..................................... 509 3.0.0.M4 Reference
Documentation xvi
Spring Framework
Accessing web services using JAX-RPC
........................................................ 509
Registering JAX-RPC Bean Mappings
........................................................... 511
Registering your own JAX-RPC Handler
....................................................... 512
Exposing servlet-based web services using JAX-WS
...................................... 512 Exporting standalone web
services using JAX-WS ......................................... 513
Exporting web services using the JAX-WS RI's Spring support
....................... 514 Accessing web services using JAX-WS
.......................................................... 514
Exposing web services using XFire
................................................................
515 19.6. JMS
.............................................................................................................
516 Server-side configuration
..............................................................................
517 Client-side configuration
...............................................................................
518 19.7. Auto-detection is not implemented for remote interfaces
................................. 518 19.8. Considerations when
choosing a technology
................................................... 519 19.9.
Accessing RESTful services on the Client
...................................................... 519
RestTemplate
...............................................................................................
520 HTTP Message Conversion
...........................................................................
522 StringHttpMessageConverter
.................................................................
523 FormHttpMessageConverter
..................................................................
523 ByteArrayMessageConverter
.................................................................
523 MarshallingHttpMessageConverter
........................................................ 523
SourceHttpMessageConverter
............................................................... 523
BufferedImageHttpMessageConverter
................................................... 523 20.
Enterprise JavaBeans (EJB) integration
....................................................................
525 20.1. Introduction
.................................................................................................
525 20.2. Accessing EJBs
............................................................................................
525 Concepts
......................................................................................................
525 Accessing local SLSBs
.................................................................................
526 Accessing remote SLSBs
..............................................................................
527 Accessing EJB 2.x SLSBs versus EJB 3 SLSBs
.............................................. 528 20.3. Using
Spring's EJB implementation support classes
........................................ 528 EJB 2.x base classes
.....................................................................................
528 EJB 3 injection interceptor
............................................................................
530 21. JMS (Java Message Service)
....................................................................................
532 21.1. Introduction
.................................................................................................
532 21.2. Using Spring JMS
........................................................................................
532 JmsTemplate
................................................................................................
532 Connections
.................................................................................................
533 Caching Messaging Resources
............................................................... 534
SingleConnectionFactory
......................................................................
534 CachingConnectionFactory
...................................................................
534 Destination Management
...............................................................................
534 Message Listener Containers
.........................................................................
535 SimpleMessageListenerContainer
.......................................................... 536
DefaultMessageListenerContainer
......................................................... 536
ServerSessionMessageListenerContainer
................................................ 536 3.0.0.M4
Reference Documentation xvii
Spring Framework
Transaction management
...............................................................................
536 21.3. Sending a Message
.......................................................................................
537 Using Message Converters
............................................................................
538 SessionCallback and ProducerCallback
.......................................................... 539
21.4. Receiving a message
.....................................................................................
539 Synchronous Reception
.................................................................................
539 Asynchronous Reception - Message-Driven POJOs
........................................ 539 The
SessionAwareMessageListener interface
................................................. 540 The
MessageListenerAdapter
........................................................................
541 Processing messages within transactions
........................................................ 542 21.5.
Support for JCA Message Endpoints
.............................................................. 543
21.6. JMS Namespace Support
..............................................................................
545 22. JMX
.......................................................................................................................
550 22.1. Introduction
.................................................................................................
550 22.2. Exporting your beans to JMX
........................................................................
550 Creating an MBeanServer
.............................................................................
551 Reusing an existing MBeanServer
.................................................................
552 Lazy-initialized MBeans
...............................................................................
553 Automatic registration of MBeans
.................................................................
553 Controlling the registration behavior
.............................................................. 553
22.3. Controlling the management interface of your beans
....................................... 555 The MBeanInfoAssembler
Interface
.............................................................. 555
Using source-Level metadata
.........................................................................
555 Using JDK 5.0 Annotations
...........................................................................
558 Source-Level Metadata Types
.......................................................................
559 The AutodetectCapableMBeanInfoAssembler interface
................................... 561 Defining management
interfaces using Java interfaces
.................................... 561 Using
MethodNameBasedMBeanInfoAssembler
............................................ 563 22.4. Controlling
the ObjectNames for your beans
.................................................. 563 Reading
ObjectNames from Properties
........................................................... 564
Using the MetadataNamingStrategy
............................................................... 564
The element
........................................................... 565
22.5. JSR-160 Connectors
.....................................................................................
566 Server-side Connectors
.................................................................................
566 Client-side Connectors
..................................................................................
567 JMX over Burlap/Hessian/SOAP
...................................................................
567 22.6. Accessing MBeans via Proxies
......................................................................
567 22.7. Notifications
................................................................................................
568 Registering Listeners for Notifications
........................................................... 568
Publishing Notifications
................................................................................
571 22.8. Further Resources
.........................................................................................
573 23. JCA CCI
.................................................................................................................
574 23.1. Introduction
.................................................................................................
574 23.2. Configuring CCI
..........................................................................................
574 Connector configuration
................................................................................
574 3.0.0.M4 Reference Documentation xviii
Spring Framework
ConnectionFactory configuration in Spring
.................................................... 575
Configuring CCI connections
........................................................................
576 Using a single CCI connection
.......................................................................
576 23.3. Using Spring's CCI access support
.................................................................
577 Record conversion
........................................................................................
577 The CciTemplate
..........................................................................................
578 DAO support
................................................................................................
579 Automatic output record generation
............................................................... 580
Summary
.....................................................................................................
580 Using a CCI Connection and Interaction directly
............................................ 581 Example for
CciTemplate usage
....................................................................
582 23.4. Modeling CCI access as operation objects
...................................................... 584
MappingRecordOperation
.............................................................................
584 MappingCommAreaOperation
.......................................................................
585 Automatic output record generation
............................................................... 585
Summary
.....................................................................................................
585 Example for MappingRecordOperation usage
................................................. 586 Example for
MappingCommAreaOperation usage
.......................................... 588 23.5. Transactions
.................................................................................................
589 24. Email
.....................................................................................................................
591 24.1. Introduction
.................................................................................................
591 24.2. Usage
..........................................................................................................
591 Basic MailSender and SimpleMailMessage usage
........................................... 592 Using the
JavaMailSender and the MimeMessagePreparator
........................... 593 24.3. Using the JavaMail
MimeMessageHelper
...................................................... 594 Sending
attachments and inline resources
....................................................... 594
Attachments
.........................................................................................
594 Inline resources
....................................................................................
595 Creating email content using a templating library
........................................... 595 A Velocity-based
example
....................................................................
596 25. Scheduling and Thread Pooling
................................................................................
598 25.1. Introduction
.................................................................................................
598 25.2. Using the OpenSymphony Quartz Scheduler
.................................................. 598 Using the
JobDetailBean
...............................................................................
598 Using the MethodInvokingJobDetailFactoryBean
........................................... 599 Wiring up jobs
using triggers and the SchedulerFactoryBean
........................... 600 25.3. Using JDK Timer support
.............................................................................
601 Creating custom timers
.................................................................................
601 Using the MethodInvokingTimerTaskFactoryBean
......................................... 601 Wrapping up: setting
up the tasks using the TimerFactoryBean ........................
602 25.4. The Spring TaskExecutor abstraction
............................................................. 602
TaskExecutor types
.......................................................................................
603 Using a TaskExecutor
...................................................................................
604 26. Dynamic language support
.......................................................................................
606 26.1. Introduction
.................................................................................................
606 3.0.0.M4 Reference Documentation xix
Spring Framework
26.2. A first example
.............................................................................................
606 26.3. Defining beans that are backed by dynamic languages
.................................... 608 Common concepts
........................................................................................
608 The element
............................................................... 609
Refreshable beans
.................................................................................
609 Inline dynamic language source files
...................................................... 612
Understanding Constructor Injection in the context of
dynamic-language-backed beans
............................................................ 612
JRuby beans
.................................................................................................
613 Groovy beans
...............................................................................................
615 Customising Groovy objects via a callback
............................................. 617 BeanShell beans
...........................................................................................
618 26.4. Scenarios
.....................................................................................................
619 Scripted Spring MVC Controllers
..................................................................
619 Scripted Validators
.......................................................................................
620 26.5. Bits and bobs
...............................................................................................
621 AOP - advising scripted beans
.......................................................................
621 Scoping
........................................................................................................
621 26.6. Further Resources
.........................................................................................
622 27. Annotations and Source Level Metadata Support
...................................................... 623 27.1.
Introduction
.................................................................................................
623 27.2. Annotations
.................................................................................................
623 @Required
...................................................................................................
623 Other @Annotations in Spring
.......................................................................
625 VII. Appendices
...................................................................................................................
626 A. Classic Spring Usage
................................................................................................
627 A.1. Classic ORM usage
.................................................................