Spring - Java/J2EE Application Framework

Reference Documentation

Rod Johnson

Juergen Hoeller

Alef Arendsen

Colin Sampaleanu

Rob Harrop

Thomas Risberg

Darren Davison

Dmitriy Kopylenko

Mark Pollack

Thierry Templier

Erwin Vervaet

Version 1.2.8

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.

(Work in progress)


Table of Contents

Preface
1. Introduction
1.1. Overview
1.2. Usage scenarios
2. Background information
2.1. Inversion of Control / Dependency Injection
3. Beans, BeanFactory and the ApplicationContext
3.1. Introduction
3.2. BeanFactory and BeanDefinitions - the basics
3.2.1. The BeanFactory
3.2.2. The BeanDefinition
3.2.3. The bean class
3.2.3.1. Bean creation via constructor
3.2.3.2. Bean creation via static factory method
3.2.3.3. Bean creation via instance factory method
3.2.4. The bean identifiers (id and name)
3.2.5. To singleton or not to singleton
3.3. Properties, collaborators, autowiring and dependency checking
3.3.1. Setting bean properties and collaborators
3.3.2. Constructor Argument Resolution
3.3.2.1. Constructor Argument Type Matching
3.3.2.2. Constructor Argument Index
3.3.3. Bean properties and constructor arguments detailed
3.3.3.1. The value element
3.3.3.2. The null element
3.3.3.3. The collection elements
3.3.3.4. Inner bean definitions via nested bean elements
3.3.3.5. The idref element
3.3.3.6. The ref element
3.3.3.7. Value and Ref shortcut forms
3.3.3.8. Compound property names
3.3.4. Method Injection
3.3.4.1. Lookup method Injection
3.3.4.2. Arbitrary method replacement
3.3.5. Using depends-on
3.3.6. Autowiring collaborators
3.3.7. Checking for dependencies
3.4. Customizing the nature of a bean
3.4.1. Lifecycle interfaces
3.4.1.1. InitializingBean / init-method
3.4.1.2. DisposableBean / destroy-method
3.4.2. Knowing who you are
3.4.2.1. BeanFactoryAware
3.4.2.2. BeanNameAware
3.4.3. FactoryBean
3.5. Abstract and child bean definitions
3.6. Interacting with the BeanFactory
3.6.1. Obtaining a FactoryBean, not its product
3.7. Customizing beans with BeanPostProcessors
3.8. Customizing bean factories with BeanFactoryPostProcessors
3.8.1. The PropertyPlaceholderConfigurer
3.8.2. The PropertyOverrideConfigurer
3.9. Registering additional custom PropertyEditors
3.10. Using the alias element to add aliases for existing beans
3.11. Introduction to the ApplicationContext
3.12. Added functionality of the ApplicationContext
3.12.1. Using the MessageSource
3.12.2. Propagating events
3.12.3. Low-level resources and the application context
3.13. Customized behavior in the ApplicationContext
3.13.1. ApplicationContextAware marker interface
3.13.2. The BeanPostProcessor
3.13.3. The BeanFactoryPostProcessor
3.13.4. The PropertyPlaceholderConfigurer
3.14. Registering additional custom PropertyEditors
3.15. Setting a bean property or constructor arg from a property expression
3.16. Setting a bean property or constructor arg from a field value
3.17. Invoking another method and optionally using the return value.
3.18. Importing Bean Definitions from One File Into Another
3.19. Creating an ApplicationContext from a web application
3.20. Glue code and the evil singleton
3.20.1. Using SingletonBeanFactoryLocator and ContextSingletonBeanFactoryLocator
4. Abstracting Access to Low-Level Resources
4.1. Overview
4.2. The Resource interface
4.3. Built-in Resource implementations
4.3.1. UrlResource
4.3.2. ClassPathResource
4.3.3. FileSystemResource
4.3.4. ServletContextResource
4.3.5. InputStreamResource
4.3.6. ByteArrayResource
4.4. The ResourceLoader Interface
4.5. The ResourceLoaderAware interface
4.6. Setting Resources as properties
4.7. Application contexts and Resource paths
4.7.1. Constructing application contexts
4.7.2. The classpath*: prefix
4.7.3. Unexpected application context handling of FileSystemResource absolute paths
5. PropertyEditors, data binding, validation and the BeanWrapper
5.1. Introduction
5.2. Binding data using the DataBinder
5.3. Bean manipulation and the BeanWrapper
5.3.1. Setting and getting basic and nested properties
5.3.2. Built-in PropertyEditors, converting types
5.3.3. Other features worth mentioning
5.4. Validation using Spring's Validator interface
5.5. The Errors interface
5.6. Resolving codes to error messages
6. Spring AOP: Aspect Oriented Programming with Spring
6.1. Concepts
6.1.1. AOP concepts
6.1.2. Spring AOP capabilities and goals
6.1.3. AOP Proxies in Spring
6.2. Pointcuts in Spring
6.2.1. Concepts
6.2.2. Operations on pointcuts
6.2.3. Convenience pointcut implementations
6.2.3.1. Static pointcuts
6.2.3.2. Dynamic pointcuts
6.2.4. Pointcut superclasses
6.2.5. Custom pointcuts
6.3. Advice types in Spring
6.3.1. Advice lifecycles
6.3.2. Advice types in Spring
6.3.2.1. Interception around advice
6.3.2.2. Before advice
6.3.2.3. Throws advice
6.3.2.4. After Returning advice
6.3.2.5. Introduction advice
6.4. Advisors in Spring
6.5. Using the ProxyFactoryBean to create AOP proxies
6.5.1. Basics
6.5.2. JavaBean properties
6.5.3. Proxying interfaces
6.5.4. Proxying classes
6.5.5. Using 'global' advisors
6.6. Convenient proxy creation
6.6.1. TransactionProxyFactoryBean
6.6.2. EJB proxies
6.7. Concise proxy definitions
6.8. Creating AOP proxies programmatically with the ProxyFactory
6.9. Manipulating advised objects
6.10. Using the "autoproxy" facility
6.10.1. Autoproxy bean definitions
6.10.1.1. BeanNameAutoProxyCreator
6.10.1.2. DefaultAdvisorAutoProxyCreator
6.10.1.3. AbstractAdvisorAutoProxyCreator
6.10.2. Using metadata-driven auto-proxying
6.11. Using TargetSources
6.11.1. Hot swappable target sources
6.11.2. Pooling target sources
6.11.3. Prototype target sources
6.11.4. ThreadLocal target sources
6.12. Defining new Advice types
6.13. Further reading and resources
7. AspectJ Integration
7.1. Overview
7.2. Configuring AspectJ aspects using Spring IoC
7.2.1. "Singleton" aspects
7.2.1.1. Example
7.2.1.2. Ordering issues
7.2.2. Non-singleton aspects
7.2.3. Gotchas
7.3. Using AspectJ pointcuts to target Spring advice
7.4. Spring aspects for AspectJ
8. Transaction management
8.1. The Spring transaction abstraction
8.2. Transaction strategies
8.3. Resource synchronization with transactions
8.3.1. High-level approach
8.3.2. Low-level approach
8.3.3. TransactionAwareDataSourceProxy
8.4. Programmatic transaction management
8.4.1. Using the TransactionTemplate
8.4.2. Using the PlatformTransactionManager
8.5. Declarative transaction management
8.5.1. Source Annotations for Transaction Demarcation
8.5.1.1. The Transactional Annotation
8.5.2. BeanNameAutoProxyCreator, another declarative approach
8.5.3. AOP and Transactions
8.6. Choosing between programmatic and declarative transaction management
8.7. Do you need an application server for transaction management?
8.8. AppServer-specific integration
8.8.1. BEA WebLogic
8.8.2. IBM WebSphere
8.9. Common problems
8.9.1. Use of the wrong transaction manager for a specific DataSource
8.9.2. Spurious AppServer warnings about the transaction or DataSource no longer being active
9. Source Level Metadata Support
9.1. Source-level metadata
9.2. Spring's metadata support
9.3. Integration with Jakarta Commons Attributes
9.4. Metadata and Spring AOP autoproxying
9.4.1. Fundamentals
9.4.2. Declarative transaction management
9.4.3. Pooling
9.4.4. Custom metadata
9.5. Using attributes to minimize MVC web tier configuration
9.6. Other uses of metadata attributes
9.7. Adding support for additional metadata APIs
10. DAO support
10.1. Introduction
10.2. Consistent Exception Hierarchy
10.3. Consistent Abstract Classes for DAO Support
11. Data Access using JDBC
11.1. Introduction
11.2. Using the JDBC Core classes to control basic JDBC processing and error handling
11.2.1. JdbcTemplate
11.2.2. DataSource
11.2.3. SQLExceptionTranslator
11.2.4. Executing Statements
11.2.5. Running Queries
11.2.6. Updating the database
11.3. Controlling how we connect to the database
11.3.1. DataSourceUtils
11.3.2. SmartDataSource
11.3.3. AbstractDataSource
11.3.4. SingleConnectionDataSource
11.3.5. DriverManagerDataSource
11.3.6. TransactionAwareDataSourceProxy
11.3.7. DataSourceTransactionManager
11.4. Modeling JDBC operations as Java objects
11.4.1. SqlQuery
11.4.2. MappingSqlQuery
11.4.3. SqlUpdate
11.4.4. StoredProcedure
11.4.5. SqlFunction
12. Data Access using O/R Mappers
12.1. Introduction
12.2. Hibernate
12.2.1. Resource management
12.2.2. SessionFactory setup in a Spring application context
12.2.3. Inversion of Control: HibernateTemplate and HibernateCallback
12.2.4. Implementing Spring-based DAOs without callbacks
12.2.5. Implementing DAOs based on plain Hibernate3 API
12.2.6. Programmatic transaction demarcation
12.2.7. Declarative transaction demarcation
12.2.8. Transaction management strategies
12.2.9. Container resources versus local resources
12.2.10. Spurious AppServer warnings about the transaction or DataSource no longer being active
12.3. JDO
12.3.1. PersistenceManagerFactory setup
12.3.2. JdoTemplate and JdoDaoSupport
12.3.3. Implementing DAOs based on plain JDO API
12.3.4. Transaction management
12.3.5. JdoDialect
12.4. Oracle TopLink
12.4.1. SessionFactory abstraction
12.4.2. TopLinkTemplate and TopLinkDaoSupport
12.4.3. Implementing DAOs based on plain TopLink API
12.4.4. Transaction management
12.5. Apache OJB
12.5.1. OJB setup in a Spring environment
12.5.2. PersistenceBrokerTemplate and PersistenceBrokerDaoSupport
12.5.3. Transaction management
12.6. iBATIS SQL Maps
12.6.1. Overview and differences between iBATIS 1.x and 2.x
12.6.2. iBATIS SQL Maps 1.x
12.6.2.1. Setting up the SqlMap
12.6.2.2. Using SqlMapTemplate and SqlMapDaoSupport
12.6.3. iBATIS SQL Maps 2.x
12.6.3.1. Setting up the SqlMapClient
12.6.3.2. Using SqlMapClientTemplate and SqlMapClientDaoSupport
12.6.3.3. Implementing DAOs based on plain iBATIS API
13. Web MVC framework
13.1. Introduction to the web MVC framework
13.1.1. Pluggability of other MVC implementations
13.1.2. Features of Spring MVC
13.2. The DispatcherServlet
13.3. Controllers
13.3.1. AbstractController and WebContentGenerator
13.3.2. Other simple controllers
13.3.3. The MultiActionController
13.3.4. CommandControllers
13.4. Handler mappings
13.4.1. BeanNameUrlHandlerMapping
13.4.2. SimpleUrlHandlerMapping
13.4.3. Adding HandlerInterceptors
13.5. Views and resolving them
13.5.1. ViewResolvers
13.5.2. Chaining ViewResolvers
13.5.3. Redirecting to views
13.5.3.1. RedirectView
13.5.3.2. The redirect: prefix
13.5.3.3. The forward: prefix
13.6. Using locales
13.6.1. AcceptHeaderLocaleResolver
13.6.2. CookieLocaleResolver
13.6.3. SessionLocaleResolver
13.6.4. LocaleChangeInterceptor
13.7. Using themes
13.7.1. Introduction
13.7.2. Defining themes
13.7.3. Theme resolvers
13.8. Spring's multipart (fileupload) support
13.8.1. Introduction
13.8.2. Using the MultipartResolver
13.8.3. Handling a fileupload in a form
13.9. Handling exceptions
14. Integrating view technologies
14.1. Introduction
14.2. JSP & JSTL
14.2.1. View resolvers
14.2.2. 'Plain-old' JSPs versus JSTL
14.2.3. Additional tags facilitating development
14.3. Tiles
14.3.1. Dependencies
14.3.2. How to integrate Tiles
14.3.2.1. InternalResourceViewResolver
14.3.2.2. ResourceBundleViewResolver
14.4. Velocity & FreeMarker
14.4.1. Dependencies
14.4.2. Context configuration
14.4.3. Creating templates
14.4.4. Advanced configuration
14.4.4.1. velocity.properties
14.4.4.2. FreeMarker
14.4.5. Bind support and form handling
14.4.5.1. the bind macros
14.4.5.2. simple binding
14.4.5.3. form input generation macros
14.4.5.4. Overriding HTML escaping and making tags XHTML compliant
14.5. XSLT
14.5.1. My First Words
14.5.1.1. Bean definitions
14.5.1.2. Standard MVC controller code
14.5.1.3. Convert the model data to XML
14.5.1.4. Defining the view properties
14.5.1.5. Document transformation
14.5.2. Summary
14.6. Document views (PDF/Excel)
14.6.1. Introduction
14.6.2. Configuration and setup
14.6.2.1. Document view definitions
14.6.2.2. Controller code
14.6.2.3. Subclassing for Excel views
14.6.2.4. Subclassing for PDF views
14.7. JasperReports
14.7.1. Dependencies
14.7.2. Configuration
14.7.2.1. Configuring the ViewResolver
14.7.2.2. Configuring the Views
14.7.2.3. About Report Files
14.7.2.4. Using JasperReportsMultiFormatView
14.7.3. Populating the ModelAndView
14.7.4. Working with Sub-Reports
14.7.4.1. Configuring Sub-Report Files
14.7.4.2. Configuring Sub-Report Data Sources
14.7.5. Configuring Exporter Parameters
15. Integrating with other web frameworks
15.1. Introduction
15.2. JavaServer Faces
15.2.1. DelegatingVariableResolver
15.2.2. FacesContextUtils
15.3. Struts
15.3.1. ContextLoaderPlugin
15.3.1.1. DelegatingRequestProcessor
15.3.1.2. DelegatingActionProxy
15.3.2. ActionSupport Classes
15.4. Tapestry
15.4.1. Architecture
15.4.2. Implementation
15.4.2.1. Sample application context
15.4.2.2. Obtaining beans in Tapestry pages
15.4.2.3. Exposing the application context to Tapestry
15.4.2.4. Component definition files
15.4.2.5. Adding abstract accessors
15.4.3. Summary
15.5. WebWork
16. Remoting and web services using Spring
16.1. Introduction
16.2. Exposing services using RMI
16.2.1. Exporting the service using the RmiServiceExporter
16.2.2. Linking in the service at the client
16.3. Using Hessian or Burlap to remotely call services via HTTP
16.3.1. Wiring up the DispatcherServlet for Hessian
16.3.2. Exposing your beans by using the HessianServiceExporter
16.3.3. Linking in the service on the client
16.3.4. Using Burlap
16.3.5. Applying HTTP basic authentication to a service exposed through Hessian or Burlap
16.4. Exposing services using HTTP invokers
16.4.1. Exposing the service object
16.4.2. Linking in the service at the client
16.5. Web Services
16.5.1. Exposing services using JAX-RPC
16.5.2. Accessing Web Services
16.5.3. Register Bean Mappings
16.5.4. Registering our own Handler
16.5.5. Exposing web services using XFire
16.6. Auto-detection is not implemented for remote interfaces
16.7. Considerations when choosing a technology
17. Accessing and implementing EJBs
17.1. Accessing EJBs
17.1.1. Concepts
17.1.2. Accessing local SLSBs
17.1.3. Accessing remote SLSBs
17.2. Using Spring convenience EJB implementation classes
18. JMS
18.1. Introduction
18.2. Domain unification
18.3. JmsTemplate
18.3.1. ConnectionFactory
18.3.2. Transaction Management
18.3.3. Destination Management
18.4. Using the JmsTemplate
18.4.1. Sending a message
18.4.2. Synchronous Receiving
18.4.3. Using Message Converters
18.4.4. SessionCallback and ProducerCallback
19. JMX Support
19.1. Introduction
19.2. Exporting your Beans to JMX
19.2.1. Creating an MBeanServer
19.2.2. Lazy-Initialized MBeans
19.2.3. Automatic Registration of MBeans
19.3. Controlling the Management Interface of Your Beans
19.3.1. The MBeanInfoAssembler Interface
19.3.2. Using Source-Level Metadata
19.3.3. Using JDK 5.0 Annotations
19.3.4. Source-Level Metadata Types
19.3.5. The AutodetectCapableMBeanInfoAssembler Interface
19.3.6. Defining Management Interfaces using Java Interfaces
19.3.7. Using MethodNameBasedMBeanInfoAssembler
19.4. Controlling the ObjectNames for your Beans
19.4.1. Reading ObjectNames from Properties
19.4.2. Using the MetadataNamingStrategy
19.5. Exporting your Beans with JSR-160 Connectors
19.5.1. Server-side Connectors
19.5.2. Client-side Connectors
19.5.3. JMX over Burlap/Hessian/SOAP
19.6. Accessing MBeans via Proxies
20. JCA CCI
20.1. Introduction
20.2. Configuring CCI
20.2.1. Connector configuration
20.2.2. ConnectionFactory configuration in Spring
20.2.3. Configuring CCI connections
20.2.4. Using a single CCI connection
20.3. Using Spring's CCI access support
20.3.1. Record conversion
20.3.2. CciTemplate
20.3.3. DAO support
20.3.4. Automatic output record generation
20.3.5. Summary
20.3.6. Using a CCI Connection and Interaction directly
20.3.7. Example for CciTemplate usage
20.4. Modeling CCI access as operation objects
20.4.1. MappingRecordOperation
20.4.2. MappingCommAreaOperation
20.4.3. Automatic output record generation
20.4.4. Summary
20.4.5. Example for MappingRecordOperation usage
20.4.6. Example for MappingCommAreaOperation usage
20.5. Transactions
21. Sending Email with Spring mail abstraction layer
21.1. Introduction
21.2. Spring mail abstraction structure
21.3. Using Spring mail abstraction
21.3.1. Pluggable MailSender implementations
21.4. Using the JavaMail MimeMessageHelper
21.4.1. Creating a simple MimeMessage and sending it
21.4.2. Sending attachments and inline resources
22. Scheduling jobs using Quartz or Timer
22.1. Introduction
22.2. Using the OpenSymphony Quartz Scheduler
22.2.1. Using the JobDetailBean
22.2.2. Using the MethodInvokingJobDetailFactoryBean
22.2.3. Wiring up jobs using triggers and the SchedulerFactoryBean
22.3. Using JDK Timer support
22.3.1. Creating custom timers
22.3.2. Using the MethodInvokingTimerTaskFactoryBean
22.3.3. Wrapping up: setting up the tasks using the TimerFactoryBean
23. Testing
23.1. Unit testing
23.2. Integration testing
23.2.1. Context management and caching
23.2.2. Dependency Injection of test class instances
23.2.3. Transaction management
23.2.4. Convenience variables
23.2.5. Example
23.2.6. Running integration tests
A. spring-beans.dtd