Reference Documentation

Version 1.3.0

Last Updated December 17, 2009 (Latest documentation)

Copyright © 2004-2008 Mark Pollack, Rick Evans, Aleksandar Seovic,

Bruno Baia, Erich Eichinger, Federico Spinazzi, Rob Harrop, Griffin
Caprio, Ruben Bartelink, Choy Rim, Erez Mazor, The Spring Java Team

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.
1. Preface ................................................................................................................................................ 1
2. Introduction ......................................................................................................................................... 2
2.1. Overview .................................................................................................................................... 2
2.2. Background ................................................................................................................................. 2
2.3. Modules ...................................................................................................................................... 3
2.4. Usage Scenarios .......................................................................................................................... 4
2.5. Quickstart applications ................................................................................................................. 4
2.6. License Information ..................................................................................................................... 5
2.7. Support ....................................................................................................................................... 5
3. Background information ....................................................................................................................... 6
3.1. Inversion of Control .................................................................................................................... 6
4. Migrating from 1.1 M2 ........................................................................................................................ 7
4.1. Introduction ................................................................................................................................. 7
4.2. Important Changes ...................................................................................................................... 7
4.2.1. Namespaces .................................................................................................................. 7
4.2.2. Core ............................................................................................................................. 8
4.2.3. Web ............................................................................................................................. 8
4.2.4. Data ............................................................................................................................. 8
I. Core Technologies ................................................................................................................................ 9
5. The IoC container ........................................................................................................................ 10
5.1. Introduction ................................................................................................................... 10
5.2. Container overview ........................................................................................................ 10
5.2.1. Configuration metadata ............................................................................. 11
5.2.2. Instantiating a container ............................................................................ 12
5.2.3. Using the container ................................................................................... 16
5.2.4. Object definition overview ........................................................................ 16
5.2.5. Instantiating objects .................................................................................. 18
5.2.6. Object creation of generic types ................................................................. 20
5.3. Dependencies ................................................................................................................ 22
5.3.1. Dependency injection ................................................................................ 22
5.3.2. Dependencies and configuration in detail .................................................... 29
5.3.3. Declarative Event Listener Registration ...................................................... 38
5.3.4. Using depends-on ..................................................................................... 40
5.3.5. Lazily-initialized objects ............................................................................ 40
5.3.6. Autowiring collaborators ........................................................................... 41
5.3.7. Checking for dependencies ........................................................................ 42
5.3.8. Method injection ....................................................................................... 43
5.3.9. Setting a reference using the members of other objects and classes. ............... 46
5.3.10. Provided IFactoryObject implementations ................................................. 50
5.4. Object Scopes ............................................................................................................... 50
5.4.1. The singleton scope .................................................................................. 51
5.4.2. The prototype scope .................................................................................. 51
5.4.3. Singleton objects with prototype-object dependencies .................................. 52
5.4.4. Request, session and web application scopes ............................................... 52
5.5. Type conversion ............................................................................................................ 52
5.5.1. Type Conversion for Enumerations ............................................................ 53
5.5.2. Built-in TypeConverters ............................................................................ 53
5.5.3. Custom Type Conversion .......................................................................... 54
5.6. Customizing the nature of an object ................................................................................ 56

Spring Framework (Version 1.3.0) ii

 The [Link] Framework

5.6.1. Lifecycle interfaces ................................................................................... 56

5.6.2. IApplicationContextAware and IObjectNameAware .................................... 57
5.7. Object definition inheritance .......................................................................................... 58
5.8. Container extension points ............................................................................................. 59
5.8.1. Obtaining an IFactoryObject, not its product ............................................... 60
5.9. Container extension points ............................................................................................. 60
5.9.1. Customizing objects with IObjectPostProcessors ......................................... 61
5.9.2. Customizing configuration metadata with ObjectFactoryPostProcessors ........ 65
5.9.3. Customizing instantiation logic using IFactoryObjects ................................. 70
5.10. The IApplicationContext .............................................................................................. 71
5.10.1. IObjectFactory or IApplicationContext? .................................................... 71
5.11. Configuration of IApplicationContext ........................................................................... 72
5.11.1. Registering custom parsers ...................................................................... 73
5.11.2. Registering custom resource handlers ....................................................... 74
5.11.3. Registering Type Aliases ......................................................................... 74
5.11.4. Registering Type Converters .................................................................... 75
5.12. Added functionality of the IApplicationContext ............................................................. 76
5.12.1. Context Hierarchies ................................................................................. 76
5.12.2. Using IMessageSource ............................................................................ 77
5.12.3. Using resources within [Link] .......................................................... 79
5.12.4. Loosely coupled events ........................................................................... 79
5.12.5. Event notification from IApplicationContext ............................................. 80
5.13. Customized behavior in the ApplicationContext ............................................................. 81
5.13.1. The IApplicationContextAware marker interface ....................................... 81
5.13.2. The IObjectPostProcessor ........................................................................ 81
5.13.3. The IObjectFactoryPostProcessor ............................................................. 82
5.13.4. The PropertyPlaceholderConfigurer .......................................................... 82
5.14. Configuration of ApplicationContext without using XML ............................................... 82
5.15. Service Locator access ................................................................................................. 82
5.16. Stereotype attributes ..................................................................................................... 83
6. The IObjectWrapper and Type conversion ..................................................................................... 85
6.1. Introduction ................................................................................................................... 85
6.2. Manipulating objects using the IObjectWrapper ............................................................... 85
6.2.1. Setting and getting basic and nested properties ............................................ 85
6.2.2. Other features worth mentioning ................................................................ 87
6.3. Type conversion ............................................................................................................ 87
6.3.1. Type Conversion for Enumerations ............................................................ 88
6.4. Built-in TypeConverters ................................................................................................. 88
6.4.1. Custom type converters ............................................................................. 89
7. Resources .................................................................................................................................... 90
7.1. Introduction ................................................................................................................... 90
7.2. The IResource interface ................................................................................................. 90
7.3. Built-in IResource implementations ................................................................................ 91
7.3.1. Registering custom IResource implementations ........................................... 91
7.4. The IResourceLoader ..................................................................................................... 92
7.5. The IResourceLoaderAware interface ............................................................................. 92
7.6. Application contexts and IResource paths ....................................................................... 93
8. Threading and Concurrency Support ............................................................................................. 94
8.1. Introduction ................................................................................................................... 94

Spring Framework (Version 1.3.0) iii

 The [Link] Framework

8.2. Thread Local Storage ..................................................................................................... 94

8.3. Synchronization Primitives ............................................................................................. 95
8.3.1. ISync ........................................................................................................ 95
8.3.2. SyncHolder ............................................................................................... 95
8.3.3. Latch ........................................................................................................ 96
8.3.4. Semaphore ................................................................................................ 96
9. Object Pooling ............................................................................................................................. 98
9.1. Introduction ................................................................................................................... 98
9.2. Interfaces and Implementations ...................................................................................... 98
10. [Link] miscellanea .............................................................................................................. 99
10.1. Introduction ................................................................................................................. 99
10.2. PathMatcher ................................................................................................................ 99
10.2.1. General rules .......................................................................................... 99
10.2.2. Matching filenames ................................................................................. 99
10.2.3. Matching subdirectories ......................................................................... 100
10.2.4. Case does matter, slashes don't ............................................................... 100
11. Expression Evaluation ............................................................................................................... 102
11.1. Introduction ............................................................................................................... 102
11.2. Evaluating Expressions ............................................................................................... 102
11.3. Language Reference ................................................................................................... 103
11.3.1. Literal expressions ................................................................................. 103
11.3.2. Properties, Arrays, Lists, Dictionaries, Indexers ....................................... 104
11.3.3. Methods ................................................................................................ 105
11.3.4. Operators .............................................................................................. 105
11.3.5. Assignment ........................................................................................... 108
11.3.6. Expression lists ..................................................................................... 108
11.3.7. Types .................................................................................................... 108
11.3.8. Type Registration .................................................................................. 108
11.3.9. Constructors .......................................................................................... 109
11.3.10. Variables ............................................................................................. 109
11.3.11. Ternary Operator (If-Then-Else) ........................................................... 110
11.3.12. List Projection and Selection ................................................................ 110
11.3.13. Collection Processors and Aggregators .................................................. 111
11.3.14. Spring Object References ..................................................................... 114
11.3.15. Lambda Expressions ............................................................................ 114
11.3.16. Delegate Expressions ........................................................................... 115
11.3.17. Null Context ....................................................................................... 116
11.4. Classes used in the examples ...................................................................................... 116
12. Validation Framework .............................................................................................................. 118
12.1. Introduction ............................................................................................................... 118
12.2. Example Usage .......................................................................................................... 118
12.3. Validator Groups ....................................................................................................... 119
12.4. Validators .................................................................................................................. 120
12.4.1. Condition Validator ............................................................................... 120
12.4.2. Required Validator ................................................................................ 121
12.4.3. Regular Expression Validator ................................................................. 121
12.4.4. Generic Validator .................................................................................. 122
12.4.5. Conditional Validator Execution ............................................................. 122
12.5. Validator Actions ....................................................................................................... 123

Spring Framework (Version 1.3.0) iv

 The [Link] Framework

12.5.1. Error Message Action ............................................................................ 123

12.5.2. Exception Action ................................................................................... 123
12.5.3. Generic Actions .................................................................................... 123
12.6. Validator References .................................................................................................. 124
12.7. Progammatic usage .................................................................................................... 124
12.8. Usage tips within [Link] ....................................................................................... 125
12.8.1. Rendering Validation Errors ................................................................... 126
12.8.2. How Validate() and Validation Controls play together ............................. 127
13. Aspect Oriented Programming with [Link] ........................................................................ 129
13.1. Introduction ............................................................................................................... 129
13.1.1. AOP concepts ....................................................................................... 129
13.1.2. [Link] AOP capabilities ................................................................. 130
13.1.3. AOP Proxies in [Link] .................................................................. 131
13.2. Pointcut API in [Link] ....................................................................................... 131
13.2.1. Concepts ............................................................................................... 132
13.2.2. Operations on pointcuts ......................................................................... 132
13.2.3. Convenience pointcut implementations ................................................... 133
13.2.4. Custom pointcuts ................................................................................... 135
13.3. Advice API in [Link] ......................................................................................... 136
13.3.1. Advice Lifecycle ................................................................................... 136
13.3.2. Advice types ......................................................................................... 136
13.4. Advisor API in [Link] ....................................................................................... 141
13.5. Using the ProxyFactoryObject to create AOP proxies ................................................... 141
13.5.1. Basics ................................................................................................... 142
13.5.2. ProxyFactoryObject Properties ............................................................... 142
13.5.3. Proxying Interfaces ................................................................................ 143
13.5.4. Proxying Classes ................................................................................... 145
13.5.5. Concise proxy definitions ...................................................................... 145
13.6. Proxying mechanisms ................................................................................................. 146
13.6.1. InheritanceBasedAopConfigurer ............................................................. 147
13.7. Creating AOP Proxies Programatically with the ProxyFactory ...................................... 147
13.8. Manipulating Advised Objects .................................................................................... 148
13.9. Using the "autoproxy" facility .................................................................................... 149
13.9.1. Autoproxy object definitions .................................................................. 149
13.9.2. Using attribute-driven auto-proxying ...................................................... 154
13.10. Using AOP Namespace ............................................................................................ 154
13.11. Using TargetSources ................................................................................................ 155
13.11.1. Hot swappable target sources ............................................................... 156
13.11.2. Pooling target sources .......................................................................... 156
13.11.3. Prototype target sources ....................................................................... 157
13.11.4. ThreadLocal target sources ................................................................... 158
13.12. Defining new Advice types ....................................................................................... 158
13.13. Further reading and resources ................................................................................... 158
14. Aspect Library .......................................................................................................................... 159
14.1. Introduction ............................................................................................................... 159
14.2. Caching ..................................................................................................................... 159
14.3. Exception Handling .................................................................................................... 161
14.3.1. Language Reference .............................................................................. 164
14.4. Logging ..................................................................................................................... 164

Spring Framework (Version 1.3.0) v

 The [Link] Framework

14.5. Retry ......................................................................................................................... 166

14.5.1. Language Reference .............................................................................. 167
14.6. Transactions ............................................................................................................... 167
14.7. Parameter Validation .................................................................................................. 167
15. Common Logging ..................................................................................................................... 169
15.1. Introduction ............................................................................................................... 169
16. Testing ..................................................................................................................................... 170
16.1. Introduction ............................................................................................................... 170
16.2. Unit testing ................................................................................................................ 170
16.3. Integration testing ...................................................................................................... 170
16.3.1. Context management and caching ........................................................... 171
16.3.2. Dependency Injection of test fixtures ...................................................... 171
16.3.3. Transaction management ........................................................................ 173
16.3.4. Convenience variables ........................................................................... 174
II. Middle Tier Data Access .................................................................................................................. 175
17. Transaction management ........................................................................................................... 176
17.1. Introduction ............................................................................................................... 176
17.2. Motivations ................................................................................................................ 176
17.3. Key Abstractions ....................................................................................................... 178
17.4. Resource synchronization with transactions ................................................................. 179
17.4.1. High-level approach .............................................................................. 180
17.4.2. Low-level approach ............................................................................... 180
17.5. Declarative transaction management ............................................................................ 180
17.5.1. Understanding Spring's declarative transaction implementation ................. 181
17.5.2. Example of declarative transaction implementation .................................. 182
17.5.3. Declarative transactions using the transaction namespace ......................... 184
17.5.4. Transaction attribute settings .................................................................. 189
17.5.5. Declarative Transactions using AutoProxy .............................................. 190
17.6. Programmatic transaction management ........................................................................ 191
17.6.1. Using the TransactionTemplate .............................................................. 191
17.6.2. Using the PlatformTransactionManager .................................................. 193
17.7. Choosing between programmatic and declarative transaction management ..................... 194
17.8. Transaction lifecycle and status information ................................................................ 194
18. DAO support ............................................................................................................................ 195
18.1. Introduction ............................................................................................................... 195
18.2. Consistent exception hierarchy .................................................................................... 195
18.3. Consistent abstract classes for DAO support ................................................................ 198
19. DbProvider ............................................................................................................................... 200
19.1. Introduction ............................................................................................................... 200
19.2. IDbProvider and DbProviderFactory ........................................................................... 200
19.3. XML based configuration ........................................................................................... 203
19.4. Connection String management ................................................................................... 204
19.5. Additional IDbProvider implementations ..................................................................... 205
19.5.1. UserCredentialsDbProvider .................................................................... 205
19.5.2. MultiDelegatingDbProvider ................................................................... 205
20. Data access using [Link] .................................................................................................... 207
20.1. Introduction ............................................................................................................... 207
20.2. Motivations ................................................................................................................ 208
20.3. Provider Abstraction .................................................................................................. 209

Spring Framework (Version 1.3.0) vi

 The [Link] Framework

20.3.1. Creating an instance of IDbProvider ....................................................... 210

20.4. Namespaces ............................................................................................................... 210
20.5. Approaches to Data Access ........................................................................................ 210
20.6. Introduction to AdoTemplate ...................................................................................... 211
20.6.1. Execute Callback ................................................................................... 211
20.6.2. Execute Callback in .NET 2.0 ................................................................ 211
20.6.3. Execute Callback in .NET 1.1 ................................................................ 213
20.6.4. Quick Guide to AdoTemplate Methods ................................................... 214
20.6.5. Quick Guide to AdoTemplate Properties ................................................. 216
20.7. Transaction Management ............................................................................................ 217
20.8. Exception Translation ................................................................................................. 217
20.9. Parameter Management .............................................................................................. 217
20.9.1. IDbParametersBuilder ............................................................................ 218
20.9.2. IDbParameters ....................................................................................... 218
20.9.3. Parameter names in SQL text ................................................................. 219
20.10. Custom IDataReader implementations ....................................................................... 219
20.11. Basic data access operations ..................................................................................... 219
20.11.1. ExecuteNonQuery ................................................................................ 220
20.11.2. ExecuteScalar ...................................................................................... 220
20.12. Queries and Lightweight Object Mapping .................................................................. 220
20.12.1. ResultSetExtractor ............................................................................... 220
20.12.2. RowCallback ....................................................................................... 221
20.12.3. RowMapper ........................................................................................ 222
20.12.4. Query for a single object ...................................................................... 223
20.12.5. Query using a CommandCreator ........................................................... 223
20.13. DataTable and DataSet ............................................................................................. 225
20.13.1. DataTables .......................................................................................... 226
20.13.2. DataSets .............................................................................................. 226
20.14. TableAdapters and participation in transactional context ............................................. 228
20.15. Database operations as Objects ................................................................................. 229
20.15.1. AdoQuery ........................................................................................... 229
20.15.2. MappingAdoQuery .............................................................................. 230
20.15.3. AdoNonQuery ..................................................................................... 230
20.15.4. Stored Procedure ................................................................................. 231
21. Object Relational Mapping (ORM) data access .......................................................................... 233
21.1. Introduction ............................................................................................................... 233
21.2. NHibernate ................................................................................................................ 234
21.2.1. Resource management ........................................................................... 234
21.2.2. Transaction Management ....................................................................... 235
21.2.3. SessionFactory set up in a Spring container ............................................. 235
21.2.4. Implementing DAOs based on plain Hibernate 1.2/2.x API ....................... 237
21.2.5. Declarative transaction demarcation ........................................................ 240
21.2.6. Programmatic transaction demarcation .................................................... 241
21.2.7. Transaction management strategies ......................................................... 242
21.2.8. Web Session Management ..................................................................... 243
21.2.9. Session Scope ....................................................................................... 244
21.2.10. Integration Testing ............................................................................... 244
III. The Web ........................................................................................................................................ 245
22. [Link] Web Framework .................................................................................................... 246

Spring Framework (Version 1.3.0) vii

 The [Link] Framework

22.1. Introduction to [Link] Web Framework ............................................................... 246

22.2. Comparing [Link] and [Link] ........................................................................ 247
22.3. Automatic context loading and hierarchical contexts .................................................... 248
22.3.1. Configuration of a web application ......................................................... 248
22.3.2. Context hierarchy .................................................................................. 250
22.4. Dependency injection for [Link] pages ................................................................... 251
22.4.1. Injecting dependencies into controls ....................................................... 252
22.4.2. Injecting dependencies into custom HTTP modules ................................. 253
22.4.3. Injecting dependencies into HTTP handlers and handler factories .............. 253
22.4.4. Injecting dependencies in custom [Link] providers ............................. 254
22.4.5. Customizing control dependency injection .............................................. 255
22.5. Web object scopes ..................................................................................................... 256
22.6. Support for [Link] 1.1 master pages in [Link] ................................................. 256
22.6.1. Linking child pages to their master page file ........................................... 257
22.7. Bidirectional data binding and data model management ................................................ 258
22.7.1. Data binding under the hood .................................................................. 262
22.7.2. Using DataBindingPanel ........................................................................ 267
22.7.3. Customizing model persistence .............................................................. 268
22.8. Localization and message sources ............................................................................... 268
22.8.1. Working with localizers ......................................................................... 268
22.8.2. Automatic localization with localizers ("push" localization) ...................... 269
22.8.3. Global message sources ......................................................................... 271
22.8.4. Applying resources manually ("pull" localization) ................................... 272
22.8.5. Localizing images within a web application ............................................ 272
22.8.6. User culture management ....................................................................... 273
22.8.7. Changing cultures .................................................................................. 274
22.9. Result mapping .......................................................................................................... 274
22.9.1. Registering user defined transfer modes .................................................. 277
22.10. Client-side scripting ................................................................................................. 278
22.10.1. Registering scripts within the head HTML section ................................. 278
22.10.2. Adding CSS definitions to the head section ........................................... 278
22.10.3. Well-known directories ........................................................................ 278
22.11. Spring user controls ................................................................................................. 279
22.11.1. Validation controls .............................................................................. 279
22.11.2. Databinding controls ............................................................................ 279
22.11.3. Calendar control .................................................................................. 279
22.11.4. Panel control ....................................................................................... 279
23. [Link] AJAX ....................................................................................................................... 280
23.1. Introduction ............................................................................................................... 280
23.2. Web Services ............................................................................................................. 280
23.2.1. Exposing Web Services ......................................................................... 280
23.2.2. Calling Web Services by using JavaScript ............................................... 281
IV. Services ......................................................................................................................................... 282
24. Introduction to Spring Services ................................................................................................. 283
24.1. Introduction ............................................................................................................... 283
25. .NET Remoting ......................................................................................................................... 285
25.1. Introduction ............................................................................................................... 285
25.2. Publishing SAOs on the Server ................................................................................... 285
25.2.1. SAO Singleton ...................................................................................... 285

Spring Framework (Version 1.3.0) viii

 The [Link] Framework

25.2.2. SAO SingleCall ..................................................................................... 286

25.2.3. IIS Application Configuration ................................................................ 287
25.3. Accessing a SAO on the Client .................................................................................. 288
25.4. CAO best practices .................................................................................................... 289
25.5. Registering a CAO object on the Server ...................................................................... 289
25.5.1. Applying AOP advice to exported CAO objects ...................................... 290
25.6. Accessing a CAO on the Client .................................................................................. 290
25.6.1. Applying AOP advice to client side CAO objects. ................................... 290
25.7. XML Schema for configuration .................................................................................. 290
25.8. Additional Resources ................................................................................................. 291
26. .NET Enterprise Services .......................................................................................................... 292
26.1. Introduction ............................................................................................................... 292
26.2. Serviced Components ................................................................................................. 292
26.3. Server Side ................................................................................................................ 292
26.4. Client Side ................................................................................................................ 294
27. Web Services ........................................................................................................................... 295
27.1. Introduction ............................................................................................................... 295
27.2. Server-side ................................................................................................................. 295
27.2.1. Removing the need for .asmx files .......................................................... 295
27.2.2. Injecting dependencies into web services ................................................ 296
27.2.3. Exposing PONOs as Web Services ......................................................... 298
27.2.4. Exporting an AOP Proxy as a Web Service ............................................. 299
27.3. Client-side ................................................................................................................. 299
27.3.1. Using [Link] generated proxy ............................................................. 300
27.3.2. Generating proxies dynamically ............................................................. 300
27.3.3. Configuring the proxy instance .............................................................. 301
28. Windows Communication Foundation (WCF) ............................................................................ 302
28.1. Introduction ............................................................................................................... 302
28.2. Configuring WCF services via Dependency Injection ................................................... 302
28.2.1. Dependency Injection ............................................................................ 302
28.3. Apply AOP advice to WCF services ........................................................................... 304
28.4. Creating client side proxies declaratively ..................................................................... 304
28.5. Exporting PONOs as WCF Services ........................................................................... 305
V. Integration ....................................................................................................................................... 306
29. Message Oriented Middleware - Apache ActiveMQ and TIBCO EMS ......................................... 307
29.1. Introduction ............................................................................................................... 307
29.1.1. Multiple Vendor Support ....................................................................... 307
29.1.2. Separation of Concerns .......................................................................... 308
29.1.3. Interoperability and provider portability .................................................. 309
29.1.4. The role of Messaging API in a 'WCF world' .......................................... 309
29.2. Using Spring Messaging ............................................................................................. 309
29.2.1. Messaging Template overview ............................................................... 309
29.2.2. Connections .......................................................................................... 310
29.2.3. Caching Messaging Resources ............................................................... 310
29.2.4. Dynamic Destination Management ......................................................... 311
29.2.5. Message Listener Containers .................................................................. 312
29.2.6. Transaction Management ....................................................................... 312
29.3. Sending a Message .................................................................................................... 312
29.3.1. Using MessageConverters ...................................................................... 313

Spring Framework (Version 1.3.0) ix

 The [Link] Framework

29.. Session and Producer Callback ..................................................................................... 315

29.5. Receiving a message .................................................................................................. 315
29.5.1. Synchronous Reception .......................................................................... 315
29.5.2. Asynchronous Reception ........................................................................ 316
29.5.3. The ISessionAwareMessageListener interface ......................................... 318
29.5.4. MessageListenerAdapater ....................................................................... 318
29.5.5. Processing messages within a messaging transaction ................................ 320
29.5.6. Messaging Namespace support ............................................................... 320
30. Message Oriented Middleware - TIBCO EMS ............................................................................ 323
30.1. Introduction ............................................................................................................... 323
30.2. Interface based APIs .................................................................................................. 323
30.3. Using Spring's EMS based Messaging ......................................................................... 324
30.3.1. Overivew .............................................................................................. 324
30.3.2. Connections .......................................................................................... 324
30.3.3. Caching Messaging Resources ............................................................... 324
30.3.4. Dynamic Destination Management ......................................................... 325
30.3.5. Accessing Admistrated objects via JNDI ................................................. 325
30.3.6. MessageListenerContainers .................................................................... 326
30.3.7. Transaction Management ....................................................................... 327
30.3.8. Sending a Message ................................................................................ 327
30.4. Using MessageConverters ........................................................................................... 328
30.5. Session and Producer Callback ................................................................................... 328
30.6. Receiving a messages ................................................................................................. 328
30.6.1. Synchronous Reception .......................................................................... 328
30.6.2. Asynchronous Reception ...................................................................... 328
30.6.3. The ISessionAwareMessageListener interface ......................................... 329
30.6.4. MessageListenerAdapter ........................................................................ 329
30.6.5. Processing messages within a messaging transaction ................................ 329
30.6.6. Messaging Namespace support ............................................................... 330
31. Message Oriented Middleware - MSMQ .................................................................................... 331
31.1. Introduction ............................................................................................................... 331
31.2. A quick tour for the impatient .................................................................................... 332
31.3. Using Spring MSMQ ................................................................................................. 334
31.3.1. MessageQueueTemplate ......................................................................... 334
31.3.2. MessageQueueFactoryObject ................................................................. 336
31.3.3. MessageQueue and IMessageConverter resource management .................. 337
31.3.4. Message Listener Containers .................................................................. 337
31.4. MessageConverters .................................................................................................... 342
31.4.1. Using MessageConverters ...................................................................... 342
31.5. Interface based message processing ............................................................................. 343
31.5.1. ............................................................................................................ 343
31.6. Comparison with using WCF ...................................................................................... 344
32. Scheduling and Thread Pooling ................................................................................................. 345
32.1. Introduction ............................................................................................................... 345
32.2. Using the [Link] Scheduler ................................................................................ 345
32.2.1. Using the JobDetailObject ..................................................................... 345
32.2.2. Using the MethodInvokingJobDetailFactoryObject .................................. 346
32.2.3. Wiring up jobs using triggers and the SchedulerFactoryObject .................. 347
33. Template Engine Support .......................................................................................................... 348

Spring Framework (Version 1.3.0) x

 The [Link] Framework

33.1. Introduction ............................................................................................................... 348

33.2. Dependencies ............................................................................................................. 348
33.3. Configuring a VelocityEngine ..................................................................................... 348
33.3.1. Simple file based template engine definition ........................................... 348
33.3.2. Configuration Options ........................................................................... 348
33.3.3. Assembly based template loading ........................................................... 349
33.3.4. Using Spring's IResourceLoader to load templates ................................... 349
33.3.5. Defining a custom resource loader .......................................................... 350
33.3.6. Resource Loader configuration options ................................................... 350
33.3.7. Using a custom configuration file ........................................................... 350
33.3.8. Logging ................................................................................................ 351
33.4. Merging a template .................................................................................................... 351
33.5. Configuring a VelocityEngine without a custom namespace .......................................... 351
VI. [Link] Integration ........................................................................................................................ 353
34. Visual [Link] Integration .................................................................................................. 354
34.1. XML Editing and Validation ...................................................................................... 354
34.2. Solution Templates .................................................................................................... 356
34.2.1. Class Library ........................................................................................ 356
34.2.2. [Link] based application library ....................................................... 357
34.2.3. NHibernate based application library ...................................................... 358
34.2.4. Spring based web application ................................................................. 359
34.3. Resharper Type Completion ....................................................................................... 360
34.4. Resharper templates ................................................................................................... 361
34.5. Versions of XML Schema .......................................................................................... 362
34.6. API documentation .................................................................................................... 362
VII. Quickstart applications .................................................................................................................. 363
35. IoC Quickstarts ......................................................................................................................... 364
35.1. Introduction ............................................................................................................... 364
35.2. Movie Finder ............................................................................................................. 364
35.2.1. Getting Started - Movie Finder ............................................................... 364
35.2.2. First Object Definition ........................................................................... 365
35.2.3. Setter Injection ...................................................................................... 366
35.2.4. Constructor Injection ............................................................................. 366
35.2.5. Summary .............................................................................................. 367
35.2.6. Logging ................................................................................................ 368
35.3. ApplicationContext and IMessageSource ..................................................................... 369
35.3.1. Introduction .......................................................................................... 369
35.4. ApplicationContext and IEventRegistry ....................................................................... 371
35.4.1. Introduction .......................................................................................... 371
35.5. Pooling example ........................................................................................................ 372
35.5.1. Implementing [Link] .................................. 372
35.5.2. Being smart using pooled objects ........................................................... 374
35.5.3. Using the executor to do a parallel grep .................................................. 375
35.6. AOP .......................................................................................................................... 375
36. AOP QuickStart ........................................................................................................................ 376
36.1. Introduction ............................................................................................................... 376
36.2. The basics ................................................................................................................. 376
36.2.1. Applying advice .................................................................................... 376
36.2.2. Using Pointcuts - the basics ................................................................... 379

Spring Framework (Version 1.3.0) xi

 The [Link] Framework

36.3. Going deeper ............................................................................................................. 381

36.3.1. Other types of Advice ........................................................................... 381
36.3.2. Using Attributes to define Pointcuts ....................................................... 387
36.4. The [Link] AOP Cookbook ................................................................................ 388
36.4.1. Caching ................................................................................................ 388
36.4.2. Performance Monitoring ........................................................................ 389
36.4.3. Retry Rules ........................................................................................... 389
36.5. [Link] AOP Best Practices ................................................................................. 389
37. Portable Service Abstraction Quick Start ................................................................................... 390
37.1. Introduction ............................................................................................................... 390
37.2. .NET Remoting Example ............................................................................................ 390
37.3. Implementation .......................................................................................................... 392
37.4. Running the application .............................................................................................. 397
37.5. Remoting Schema ...................................................................................................... 398
37.6. .NET Enterprise Services Example .............................................................................. 398
37.7. Web Services Example ............................................................................................... 400
37.8. Additional Resources ................................................................................................. 403
38. Web Quickstarts ....................................................................................................................... 404
38.1. Introduction ............................................................................................................... 404
39. SpringAir - Reference Application ............................................................................................. 405
39.1. Introduction ............................................................................................................... 405
39.2. Getting Started ........................................................................................................... 405
39.3. Container configuration .............................................................................................. 405
39.4. Bi-directional data binding ......................................................................................... 407
39.5. Declarative Validation ................................................................................................ 407
39.6. Internationalization ..................................................................................................... 408
39.7. Web Services ............................................................................................................. 408
40. Data Access QuickStart ............................................................................................................ 410
40.1. Introduction ............................................................................................................... 410
40.1.1. Database configuration .......................................................................... 410
40.1.2. CommandCallback ................................................................................ 411
41. Transactions QuickStart ............................................................................................................ 413
41.1. Introduction ............................................................................................................... 413
41.2. Application Overview ................................................................................................ 413
41.2.1. Interfaces .............................................................................................. 413
41.3. Implementation .......................................................................................................... 414
41.4. Configuration ............................................................................................................. 417
41.4.1. Rollback Rules ...................................................................................... 418
41.5. Adding additional Aspects .......................................................................................... 419
42. NHibernate QuickStart .............................................................................................................. 421
42.1. Introduction ............................................................................................................... 421
42.2. Getting Started ........................................................................................................... 421
42.3. Implementation ......................................................................................................... 424
42.3.1. The Data Access Layer .......................................................................... 424
42.3.2. The domain objects ............................................................................... 425
42.3.3. NHibernate based DAO implementation ................................................. 426
42.3.4. The Service layer .................................................................................. 429
42.3.5. Integration testing .................................................................................. 430
42.3.6. Web Application ................................................................................... 432

Spring Framework (Version 1.3.0) xii

 The [Link] Framework

43. Quartz QuickStart ..................................................................................................................... 434

43.1. Introduction ............................................................................................................... 434
43.2. Application Overview ................................................................................................ 434
43.3. Standard job scheduling ............................................................................................. 434
43.4. Scheduling arbitrary methods as jobs .......................................................................... 435
44. NMS QuickStart ....................................................................................................................... 437
44.1. Introduction ............................................................................................................... 437
44.2. Message Destinations ................................................................................................. 437
44.3. Gateways ................................................................................................................... 438
44.4. Message Data ............................................................................................................ 438
44.5. Message Handlers ...................................................................................................... 440
44.6. Message Converters ................................................................................................... 441
44.7. Messaging Infrastructure ............................................................................................ 441
44.8. Running the application .............................................................................................. 442
45. TIBCO EMS QuickStart ........................................................................................................... 444
45.1. Introduction ............................................................................................................... 444
45.2. Message Destinations ................................................................................................. 444
45.3. Messaging Infrastructure ............................................................................................ 445
45.4. Running the application .............................................................................................. 446
46. MSMQ QuickStart .................................................................................................................... 447
46.1. Introduction ............................................................................................................... 447
46.2. Message Destinations ................................................................................................. 447
46.3. Gateways ................................................................................................................... 447
46.4. Message Data ............................................................................................................ 447
46.5. Message Handlers ...................................................................................................... 448
46.6. MessageConverters .................................................................................................... 448
46.7. Messaging Infrastructure ............................................................................................ 448
46.8. Running the application .............................................................................................. 450
47. WCF QuickStart ....................................................................................................................... 451
47.1. Introduction ............................................................................................................... 451
47.2. The server side .......................................................................................................... 451
47.2.1. WCF Dependency Injection and AOP in self-hosted application ................ 452
47.2.2. WCF Dependency Injection and AOP in IIS web application .................... 452
47.3. Client access .............................................................................................................. 452
VIII. [Link] for Java developers ................................................................................................... 454
48. [Link] for Java Developers ............................................................................................... 455
48.1. Introduction ............................................................................................................... 455
48.2. Beans to Objects ........................................................................................................ 455
48.3. PropertyEditors to TypeConverters .............................................................................. 456
48.4. ResourceBundle-ResourceManager ............................................................................. 456
48.5. Exceptions ................................................................................................................. 456
48.6. Application Configuration .......................................................................................... 456
48.7. AOP Framework ........................................................................................................ 457
48.7.1. Cannot specify target name at the end of interceptorNames for
ProxyFactoryObject .......................................................................................... 457
IX. Appendices .................................................................................................................................... 459
A. Classic Spring Usage ................................................................................................................. 460
A.1. Classic Hibernate Usage .............................................................................................. 460
A.1.1. The HibernateTemplate ........................................................................... 460

Spring Framework (Version 1.3.0) xiii

 The [Link] Framework

A.1.2. Implementing Spring-based DAOs without callbacks ................................ 461

A.2. Classic Declarative Transaction Configurations ............................................................. 462
A.2.1. Declarative Transaction Configuration using
DefaultAdvisorAutoProxyCreator ...................................................................... 462
A.2.2. Declarative Transactions using TransactionProxyFactoryObject ................. 463
A.2.3. Concise proxy definitions ....................................................................... 464
A.2.4. Declarative Transactions using ProxyFactoryObject .................................. 465
B. XML Schema-based configuration .............................................................................................. 467
B.1. Introduction ................................................................................................................ 467
B.2. XML Schema-based configuration ............................................................................... 467
B.2.1. Referencing the schemas ......................................................................... 467
B.2.2. The tx (transaction) schema .................................................................... 468
B.2.3. The aop schema ..................................................................................... 469
B.2.4. The db schema ....................................................................................... 469
B.2.5. The remoting schema .............................................................................. 470
B.2.6. The nms messaging schema .................................................................... 471
B.2.7. The validation schema ............................................................................ 471
B.2.8. The objects schema ................................................................................ 472
B.3. Setting up your IDE .................................................................................................... 472
C. Extensible XML authoring ......................................................................................................... 473
C.1. Introduction ................................................................................................................ 473
C.2. Authoring the schema .................................................................................................. 473
C.3. Coding a INamespaceParser ......................................................................................... 474
C.4. Coding an IObjectDefinitionParser ............................................................................... 475
C.5. Registering the handler and the schema ........................................................................ 476
C.5.1. NamespaceParsersSectionHandler ............................................................ 476
C.6. Using a custom extension in your Spring XML configuration ......................................... 476
C.7. Further Resources ....................................................................................................... 477
D. [Link]'s [Link] ................................................................................................. 478

Spring Framework (Version 1.3.0) xiv

Chapter 1. Preface
Developing software applications is hard enough even with good tools and technologies. Spring provides a light-
weight solution for building enterprise-ready applications. Spring provides a consistent and transparent means
to configure your application and integrate AOP into your software. Highlights of Spring's functionality are
providing declarative transaction management for your middle tier as well as a full-featured [Link] framework.

Spring could potentially be a one-stop-shop for many areas of enterprise application development; however,
Spring is modular, allowing you to use just those parts of it that you need, without having to bring in the rest. You
can use just the IoC container to configure your application and use traditional [Link] based data access code,
but you could also choose to use just the Hibernate integration code or the [Link] abstraction layer. Spring
has been (and continues to be) designed to be non-intrusive, meaning dependencies on the framework itself are
generally none (or absolutely minimal, depending on the area of use).

This document provides a reference guide to Spring's features. Since this document is still to be considered very
much work-in-progress, if you have any requests or comments, please post them on the user mailing list or on
the support forums at [Link].

Before we go on, a few words of gratitude are due to Christian Bauer (of the Hibernate team), who prepared and
adapted the DocBook-XSL software in order to be able to create Hibernate's reference guide, thus also allowing us
to create this one. Also thanks to Russell Healy for doing an extensive and valuable review of some of the material.

Spring Framework (Version 1.3.0) 1

Chapter 2. Introduction
2.1. Overview
[Link] is an application framework that provides comprehensive infrastructural support for developing
enterprise .NET applications. It allows you to remove incidental complexity when using the base class libraries
makes best practices, such as test driven development, easy practices. [Link] is created, supported and
sustained by SpringSource.

The design of [Link] is based on the Java version of the Spring Framework, which has shown real-world
benefits and is used in thousands of enterprise applications world wide. Spring .NET is not a quick port from the
Java version, but rather a 'spiritual port' based on following proven architectural and design patterns in that are
not tied to a particular platform. The breadth of functionality in Spring .NET spans application tiers which allows
you to treat it as a ‘one stop shop’ but that is not required. Spring .NET is not an all-or-nothing solution. You can
use the functionality in its modules independently. These modules are described below.

Enterprise applications typically are composed of a number of a variety of physical tiers and within each tier
functionality is often split into functional layers. The business service layer for example typically uses a objects
in the data access layer to fulfill a use-case. No matter how your application is architected, at the end of the day
there are a variety of objects that collaborate with one another to form the application proper. The objects in an
application can thus be said to have dependencies between themselves.

The .NET platform provides a wealth of functionality for architecting and building applications, ranging all the
way from the very basic building blocks of primitive types and classes (and the means to define new classes), to
rich full-featured application servers and web frameworks. One area that is decidedly conspicuous by its absence
is any means of taking the basic building blocks and composing them into a coherent whole; this area has typically
been left to the purvey of the architects and developers tasked with building an application (or applications). Now
to be fair, there are a number of design patterns devoted to the business of composing the various classes and
object instances that makeup an all-singing, all-dancing application. Design patterns such as Factory, Abstract
Factory, Builder, Decorator, and Service Locator (to name but a few) have widespread recognition and acceptance
within the software development industry (presumably that is why these patterns have been formalized as patterns
in the first place). This is all very well, but these patterns are just that: best practices given a name, typically
together with a description of what the pattern does, where the pattern is typically best applied, the problems
that the application of the pattern addresses, and so forth. Notice that the last paragraph used the phrase “... a
description of what the pattern does...”; pattern books and wikis are typically listings of such formalized best
practice that you can certainly take away, mull over, and then implement yourself in your application.

The Spring Framework takes best practices that have been proven over the years in numerous applications and
formalized as design patterns, and actually codifies these patterns as first class objects that you as an architect
and developer can take away and integrate into your own application(s). This is a Very Good Thing Indeed as
attested to by the numerous organizations and institutions that have used the Spring Framework to engineer robust,
maintainable applications. For example, the IoC component of the Spring Framework addresses the enterprise
concern of taking the classes, objects, and services that are to compose an application, by providing a formalized
means of composing these various disparate components into a fully working application ready for use

2.2. Background
In early 2004, Martin Fowler asked the readers of his site: when talking about Inversion of Control: “the question
is, what aspect of control are [they] inverting?”. Fowler then suggested renaming the principle (or at least giving

Spring Framework (Version 1.3.0) 2

 Introduction

it a more self-explanatory name), and started to use the term Dependency Injection. His article then continued
to explain the ideas underpinning the Inversion of Control (IoC) and Dependency Injection (DI) principle. If
you need a decent insight into IoC and DI, please do refer to the article : [Link]
[Link].

2.3. Modules
The Spring Framework contains a lot of features, which are well-organized into modules shown in the diagram
below. The diagram below shows the various core modules of [Link].

Click on the module name for more information.

[Link] is the most fundamental part of the framework allowing you to configure your application using
Dependency Injection. Other supporting functionality, listed below, is located in [Link]

[Link] - Use this module to perform Aspect-Oriented Programming (AOP). AOP centralizes common
functionality that can then be declaratively applied across your application in a targeted manner. Spring's aspect
library provides predefined easy to use aspects for transactions, logging, performance monitoring, caching,
method retry, and exception handling.

[Link] - Use this module to achieve greater efficiency and consistency in writing data access functionality
in [Link] and to perform declarative transaction management.

Spring Framework (Version 1.3.0) 3

 Introduction

[Link] - Use this module to integrate NHibernate with Spring’s declarative transaction
management functionality allowing easy mixing of [Link] and NHibernate operations within the same
transaction. NHibernate 1.0 users will benefit from ease of use APIs to perform data access operations.

[Link] - Use this module to raise the level of abstraction when writing [Link] web applications allowing
you to effectively address common pain-points in [Link] such as data binding, validation, and [Link] page/
control/module/provider configuration.

[Link] - Use this module to raise the level of abstraction when writing [Link] web
applications allowing you to effectively address common pain-points in [Link] such as data binding,
validation, and [Link] page/control/module/provider configuration.

[Link] - Use this module to adapt plain .NET objects so they can be used with a specific distributed
communication technology, such as .NET Remoting, Enterprise Services, and ASMX Web Services. These
services can be configured via dependency injection and ‘decorated’ by applying AOP.

[Link] - Use this module to perform integration testing with NUnit.

The [Link] module also includes the following additional features

• Expression Language - provides efficient querying and manipulation of an object graphs at runtime.

• Validation Framework - a robust UI agnostic framework for creating complex validation rules for business
objects either programatically or declaratively.

• Data binding Framework - a UI agnostic framework for performing data binding.

• Dynamic Reflection - provides a high performance reflection API

• Threading - provides additional concurrency abstractions such as Latch, Semaphore and Thread Local Storage.

• Resource abstraction - provides a common interface to treat the InputStream from a file and from a URL in a
polymorphic and protocol-independent manner.

2.4. Usage Scenarios

With the building blocks described above you can use Spring in all sorts of scenarios, from simple stand alone
console applications to fully-fledged enterprise applications using Spring's transaction management functionality
and web framework integration.

It is important to note that the Spring Framework does not force you to use everything within it; it is not an all-
or-nothing solution. Existing front-ends built using standard [Link] can be integrated perfectly well with a
Spring-based middle-tier, allowing you to use the transaction and/or data access features that Spring offers. The
only things you need to do is wire up your business logic using Spring's IoC container and integrate it into your
web layer using WebApplicationContext to locate middle tier services and/or configure your standard [Link]
pages with depdenency injection.

While the Spring framework does not force any particular application architecure it encourages the use of a well
layered application architecture with distinct tiers for the presentation, service, data access, and database.

2.5. Quickstart applications

There are several sample applications that showcase individual features. If you are already familiar with the
concepts of dependency injection, AOP, or have experience using the Java version of the Spring framework you

Spring Framework (Version 1.3.0) 4

 Introduction

may find jumping into the examples a better way to bootstrap the learning processing process. The following
quickstart applications are available and can be found in the examples directory in the distribution. Click on the
links for additional information.

• Movie Finder - A simple demonstration of Dependency Injection (DI) techniques using Spring's Inversion of
Control (IoC) container.

• Application Context - Demonstrates IoC container features such as localization, accessing of ResourceSet
objects, and applying resources to object properties.

• Aspect Oriented Programming - Demonstrates use of the AOP framework to add additional behavior to your
existing objects. Examples of programmatic and declarative AOP configuration are shown.

• Distributed Computing - A calculator demonstrating remote service abstractions that let you 'export' a
plain .NET object (PONO) via .NET Remoting, Web Services, or an EnterpriseService ServiceComponent.
Corresponding client side proxies are also demonstrated.

• WCF - Shows a WCF based calculator example that configures your WCF service via dependency injection
and apply AOP advice.

• Web Application - SpringAir -A ticket booking application that demonstrates the [Link] framework
showing features such as DI for [Link] pages, data binding, validation, and localization.

• Web Development - Introductory examples showing use of dependency injection and Spring's bi-directional
data binding in [Link].

• Data Access - Demonstrates the [Link] framework showing how to simplify developing [Link] based
data access layers.

• Transaction Management : Demonstrates the use of declarative transaction management for both local and
distributed transaction in both .NET 1.1 and 2.0.

• AJAX : Demonstrates how to access a plain .NET object as a webservice in client side JavaScript

• NHibernate Northwind: Demonstrates use of Spring's NHibernate integration to simplify the use of NHibernate.
Web tier is also included showing how to use the Open-Session In View approach to session management in
the web tier.

• Quartz Quickstart - Application that shows the use of [Link] integration for scheduling.

• NMS - Applicatoin demonstrating NMS helper classes.

2.6. License Information

[Link] is licensed according to the terms of the Apache License, Version 2.0. The full text of this license are
available online at [Link] . You can also view the full text of the license
in the [Link] file located in the root installation directory.

2.7. Support
Training and support are available through SpringSource in addition to the mailing lists and forums you can find
on the main [Link] website.

Spring Framework (Version 1.3.0) 5

Chapter 3. Background information
3.1. Inversion of Control
In early 2004, Martin Fowler asked the readers of his site: when talking about Inversion of Control: "the question,
is what aspect of control are they inverting?". After talking about the term Inversion of Control Martin suggests
renaming the pattern, or at least giving it a more self-explanatory name, and starts to use the term Dependency
Injection. His article continues to explain some of the ideas behind this important software engineering principle.

Other references you may find useful are

• Wikipedia Article - Dependency Injection

• CodeProject article - Dependency Injection for Loose Coupling

Spring Framework (Version 1.3.0) 6

Chapter 4. Migrating from 1.1 M2
4.1. Introduction
Several API changes were made after 1.1 M2 (before 1.1 RC1)due primarily by the need to refactor the code base
to remove circular dependency cycles, which are now all removed. Class and schema name changes were also
made to provide a more consistent naming convention across the codebase. As a result of these changes, you can
not simply drop in the new .dlls as you may have done in previous release. This document serves as a high level
guide to the most likely areas where you will need to make changes to either your configuration or your code.

The file, [Link], in the root directory of the distribution contains the full listing of breaking
changes made for RC1 and higher

4.2. Important Changes

This section covers the common areas were you will need to make changes in code/configuration when migration
from M2 to RC1or higher.

4.2.1. Namespaces

Note: If you previously installed Spring .xsd files to your [Link] installation directory, remove them manually,
and copy over the new ones, which have the -[Link] suffix.

The names of the section handlers to register custom schemas has changed, from ConfigParsersSectionHandler
to NamespaceParsersSectionHandler.

The target namespaces have changed, the 'directory' named /schema/ has been removed. For example, the target
schema changed from [Link] to [Link]

A typical declaration to use custom schemas within your configuration file looks like this

<objects xmlns='[Link]
xml