diff --git a/src/docs/asciidoc/data-access-appendix.adoc b/src/docs/asciidoc/data-access-appendix.adoc index e87b5c80805..852fbee592f 100644 --- a/src/docs/asciidoc/data-access-appendix.adoc +++ b/src/docs/asciidoc/data-access-appendix.adoc @@ -5,33 +5,34 @@ [[xsd-schemas]] == XML Schemas -This part of the appendix lists XML schemas for data access. +This part of the appendix lists XML schemas for data access, including the following: + +* <> +* <> [[xsd-schemas-tx]] -=== The `tx` schema +=== The `tx` Schema The `tx` tags deal with configuring all of those beans in Spring's comprehensive support for transactions. These tags are covered in the chapter entitled <>. -[TIP] -==== - -You are strongly encouraged to look at the `'spring-tx.xsd'` file that ships with the -Spring distribution. This file is (of course), the XML Schema for Spring's transaction -configuration, and covers all of the various tags in the `tx` namespace, including -attribute defaults and suchlike. This file is documented inline, and thus the +TIP: We strongly encourag you to look at the `'spring-tx.xsd'` file that ships with the +Spring distribution. This file contains the XML Schema for Spring's transaction +configuration and covers all of the various elements in the `tx` namespace, including +attribute defaults and similar information. This file is documented inline, and, thus, the information is not repeated here in the interests of adhering to the DRY (Don't Repeat Yourself) principle. ==== -In the interest of completeness, to use the tags in the `tx` schema, you need to have -the following preamble at the top of your Spring XML configuration file; the text in the +In the interest of completeness, to use the elements in the `tx` schema, you need to have +the following preamble at the top of your Spring XML configuration file. The text in the following snippet references the correct schema so that the tags in the `tx` namespace -are available to you. +are available to you: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -39,45 +40,49 @@ are available to you. ---- - -[NOTE] +<1> Specify the namespace. +<2> Specify the location (with other schema locations). ==== -Often when using the tags in the `tx` namespace you will also be using the tags from the + +NOTE: Often, when you use the elements in the `tx` namespace, you are also using the elements from the `aop` namespace (since the declarative transaction support in Spring is implemented -using AOP). The above XML snippet contains the relevant lines needed to reference the -`aop` schema so that the tags in the `aop` namespace are available to you. -==== +by using AOP). The preceding XML snippet contains the relevant lines needed to reference the +`aop` schema so that the elements in the `aop` namespace are available to you. [[xsd-schemas-jdbc]] -=== The `jdbc` schema +=== The `jdbc` Schema -The `jdbc` tags allow you to quickly configure an embedded database or initialize an -existing data source. These tags are documented in -<> -and <> respectively. +The `jdbc` elements let you quickly configure an embedded database or initialize an +existing data source. These elements are documented in +<> +and <>, respectively. -To use the tags in the `jdbc` schema, you need to have the following preamble at the top -of your Spring XML configuration file; the text in the following snippet references the -correct schema so that the tags in the `jdbc` namespace are available to you. +To use the elements in the `jdbc` schema, you need to have the following preamble at the top +of your Spring XML configuration file. The text in the following snippet references the +correct schema so that the elements in the `jdbc` namespace are available to you: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- + http://www.springframework.org/schema/jdbc http://www.springframework.org/schema/jdbc/spring-jdbc.xsd"> <2> ---- +<1> Specify the namespace. +<2> Specify the location (with other schema locations). +==== diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index 27f8a9c2864..55afeb64bff 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/src/docs/asciidoc/data-access.adoc @@ -12,42 +12,35 @@ interaction between the data access layer and the business or service layer. Spring's comprehensive transaction management support is covered in some detail, followed by thorough coverage of the various data access frameworks and technologies -that the Spring Framework integrates with. - +with which the Spring Framework integrates. [[transaction]] == Transaction Management - - -[[transaction-intro]] -=== Introduction to Spring Framework transaction management - Comprehensive transaction support is among the most compelling reasons to use the Spring Framework. The Spring Framework provides a consistent abstraction for transaction management that delivers the following benefits: -* Consistent programming model across different transaction APIs such as Java - Transaction API (JTA), JDBC, Hibernate, and Java Persistence API (JPA). +* A consistent programming model across different transaction APIs, such as Java + Transaction API (JTA), JDBC, Hibernate, and the Java Persistence API (JPA). * Support for <>. -* Simpler API for <> transaction management than - complex transaction APIs such as JTA. +* A simpler API for <> transaction management than + complex transaction APIs, such as JTA. * Excellent integration with Spring's data access abstractions. -The following sections describe the Spring Framework's transaction value-adds and -technologies. (The chapter also includes discussions of best practices, application -server integration, and solutions to common problems.) +The following sections describe the Spring Framework's transaction features and +technologies: * <> describes __why__ you would use the Spring Framework's transaction abstraction + model>> describes why you would use the Spring Framework's transaction abstraction instead of EJB Container-Managed Transactions (CMT) or choosing to drive local - transactions through a proprietary API such as Hibernate. + transactions through a proprietary API, such as Hibernate. * <> outlines the core classes and describes how to configure and obtain `DataSource` instances from a variety of sources. -* <>describes +* <> describes how the application code ensures that resources are created, reused, and cleaned up properly. * <> describes support for @@ -57,105 +50,111 @@ server integration, and solutions to common problems.) * <> describes how you could use application events within a transaction. +(The chapter also includes discussions of best practices, <>, and <>.) + [[transaction-motivation]] -=== Advantages of the Spring Framework's transaction support model +=== Advantages of the Spring Framework's Transaction Support Model Traditionally, Java EE developers have had two choices for transaction management: -__global__ or __local__ transactions, both of which have profound limitations. Global +global or local transactions, both of which have profound limitations. Global and local transaction management is reviewed in the next two sections, followed by a discussion of how the Spring Framework's transaction management support addresses the limitations of the global and local transaction models. [[transaction-global]] -==== Global transactions +==== Global Transactions -Global transactions enable you to work with multiple transactional resources, typically +Global transactions let you work with multiple transactional resources, typically relational databases and message queues. The application server manages global -transactions through the JTA, which is a cumbersome API to use (partly due to its +transactions through the JTA, which is a cumbersome API (partly due to its exception model). Furthermore, a JTA `UserTransaction` normally needs to be sourced from -JNDI, meaning that you __also__ need to use JNDI in order to use JTA. Obviously the use -of global transactions would limit any potential reuse of application code, as JTA is +JNDI, meaning that you also need to use JNDI in order to use JTA. The use +of global transactions limits any potential reuse of application code, as JTA is normally only available in an application server environment. -Previously, the preferred way to use global transactions was via EJB __CMT__ -(__Container Managed Transaction__): CMT is a form of __declarative transaction -management__ (as distinguished from __programmatic transaction management__). EJB CMT -removes the need for transaction-related JNDI lookups, although of course the use of EJB +Previously, the preferred way to use global transactions was through EJB CMT +(Container Managed Transaction). CMT is a form of declarative transaction +management (as distinguished from programmatic transaction management). EJB CMT +removes the need for transaction-related JNDI lookups, although the use of EJB itself necessitates the use of JNDI. It removes most but not all of the need to write Java code to control transactions. The significant downside is that CMT is tied to JTA and an application server environment. Also, it is only available if one chooses to -implement business logic in EJBs, or at least behind a transactional EJB facade. The +implement business logic in EJBs (or at least behind a transactional EJB facade). The negatives of EJB in general are so great that this is not an attractive proposition, especially in the face of compelling alternatives for declarative transaction management. + [[transaction-local]] -==== Local transactions +==== Local Transactions Local transactions are resource-specific, such as a transaction associated with a JDBC -connection. Local transactions may be easier to use, but have significant disadvantages: -they cannot work across multiple transactional resources. For example, code that manages -transactions using a JDBC connection cannot run within a global JTA transaction. Because +connection. Local transactions may be easier to use but have a significant disadvantage: +They cannot work across multiple transactional resources. For example, code that manages +transactions by using a JDBC connection cannot run within a global JTA transaction. Because the application server is not involved in transaction management, it cannot help ensure correctness across multiple resources. (It is worth noting that most applications use a single transaction resource.) Another downside is that local transactions are invasive to the programming model. + [[transaction-programming-model]] -==== Spring Framework's consistent programming model +==== Spring Framework's Consistent Programming Model -Spring resolves the disadvantages of global and local transactions. It enables -application developers to use a __consistent__ programming model __in any environment__. +Spring resolves the disadvantages of global and local transactions. It lets +application developers use a consistent programming model in any environment. You write your code once, and it can benefit from different transaction management strategies in different environments. The Spring Framework provides both declarative and programmatic transaction management. Most users prefer declarative transaction -management, which is recommended in most cases. +management, which we recommend in most cases. With programmatic transaction management, developers work with the Spring Framework transaction abstraction, which can run over any underlying transaction infrastructure. With the preferred declarative model, developers typically write little or no code -related to transaction management, and hence do not depend on the Spring Framework -transaction API, or any other transaction API. +related to transaction management and, hence, do not depend on the Spring Framework +transaction API or any other transaction API. .Do you need an application server for transaction management? **** The Spring Framework's transaction management support changes traditional rules as to when an enterprise Java application requires an application server. -In particular, you do not need an application server simply for declarative transactions +In particular, you do not need an application server purely for declarative transactions through EJBs. In fact, even if your application server has powerful JTA capabilities, you may decide that the Spring Framework's declarative transactions offer more power and a more productive programming model than EJB CMT. -Typically you need an application server's JTA capability only if your application needs +Typically, you need an application server's JTA capability only if your application needs to handle transactions across multiple resources, which is not a requirement for many applications. Many high-end applications use a single, highly scalable database (such as -Oracle RAC) instead. Standalone transaction managers such as -http://www.atomikos.com/[Atomikos Transactions] and http://jotm.objectweb.org/[JOTM] -are other options. Of course, you may need other application server capabilities such as +Oracle RAC) instead. Stand-alone transaction managers (such as +http://www.atomikos.com/[Atomikos Transactions] and http://jotm.objectweb.org/[JOTM]) +are other options. Of course, you may need other application server capabilities, such as Java Message Service (JMS) and Java EE Connector Architecture (JCA). -The Spring Framework __gives you the choice of when to scale your application to a fully -loaded application server__. Gone are the days when the only alternative to using EJB -CMT or JTA was to write code with local transactions such as those on JDBC connections, +The Spring Framework gives you the choice of when to scale your application to a fully +loaded application server. Gone are the days when the only alternative to using EJB +CMT or JTA was to write code with local transactions (such as those on JDBC connections) and face a hefty rework if you need that code to run within global, container-managed transactions. With the Spring Framework, only some of the bean definitions in your -configuration file, rather than your code, need to change. +configuration file need to change (rather than your code). **** [[transaction-strategies]] -=== Understanding the Spring Framework transaction abstraction +=== Understanding the Spring Framework Transaction Abstraction -The key to the Spring transaction abstraction is the notion of a __transaction -strategy__. A transaction strategy is defined by the -`org.springframework.transaction.PlatformTransactionManager` interface: +The key to the Spring transaction abstraction is the notion of a transaction +strategy. A transaction strategy is defined by the +`org.springframework.transaction.PlatformTransactionManager` interface, which the following listing shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -168,48 +167,49 @@ strategy__. A transaction strategy is defined by the void rollback(TransactionStatus status) throws TransactionException; } ---- +==== -This is primarily a service provider interface (SPI), although it can be used +This is primarily a service provider interface (SPI), although you can use it <> from your application code. Because -`PlatformTransactionManager` is an __interface__, it can be easily mocked or stubbed as -necessary. It is not tied to a lookup strategy such as JNDI. +`PlatformTransactionManager` is an interface, it can be easily mocked or stubbed as +necessary. It is not tied to a lookup strategy, such as JNDI. `PlatformTransactionManager` implementations are defined like any other object (or bean) in the Spring Framework IoC container. This benefit alone makes Spring Framework -transactions a worthwhile abstraction even when you work with JTA. Transactional code -can be tested much more easily than if it used JTA directly. +transactions a worthwhile abstraction, even when you work with JTA. You can test transactional code +much more easily than if it used JTA directly. -Again in keeping with Spring's philosophy, the `TransactionException` that can be thrown -by any of the `PlatformTransactionManager` interface's methods is __unchecked__ (that +Again, in keeping with Spring's philosophy, the `TransactionException` that can be thrown +by any of the `PlatformTransactionManager` interface's methods is unchecked (that is, it extends the `java.lang.RuntimeException` class). Transaction infrastructure failures are almost invariably fatal. In rare cases where application code can actually recover from a transaction failure, the application developer can still choose to catch and handle `TransactionException`. The salient point is that developers are not -__forced__ to do so. +_forced_ to do so. The `getTransaction(..)` method returns a `TransactionStatus` object, depending on a `TransactionDefinition` parameter. The returned `TransactionStatus` might represent a -new transaction, or can represent an existing transaction if a matching transaction +new transaction or can represent an existing transaction, if a matching transaction exists in the current call stack. The implication in this latter case is that, as with -Java EE transaction contexts, a `TransactionStatus` is associated with a __thread__ of +Java EE transaction contexts, a `TransactionStatus` is associated with a thread of execution. The `TransactionDefinition` interface specifies: -* __Propagation__: Typically, all code executed within a transaction scope will run in - that transaction. However, you have the option of specifying the behavior in the event - that a transactional method is executed when a transaction context already exists. For - example, code can continue running in the existing transaction (the common case); or - the existing transaction can be suspended and a new transaction created. __Spring - offers all of the transaction propagation options familiar from EJB CMT__. To read +* Propagation: Typically, all code executed within a transaction scope runs in + that transaction. However, you can specify the behavior if + a transactional method is executed when a transaction context already exists. For + example, code can continue running in the existing transaction (the common case), or + the existing transaction can be suspended and a new transaction created. Spring + offers all of the transaction propagation options familiar from EJB CMT. To read about the semantics of transaction propagation in Spring, see <>. -* __Isolation__: The degree to which this transaction is isolated from the work of other +* Isolation: The degree to which this transaction is isolated from the work of other transactions. For example, can this transaction see uncommitted writes from other transactions? -* __Timeout__: How long this transaction runs before timing out and being rolled back - automatically by the underlying transaction infrastructure. -* __Read-only status__: A read-only transaction can be used when your code reads but +* Timeout: How long this transaction runs before timing out and being automatically rolled back + by the underlying transaction infrastructure. +* Read-only status: You can use a read-only transaction when your code reads but does not modify data. Read-only transactions can be a useful optimization in some - cases, such as when you are using Hibernate. + cases, such as when you use Hibernate. These settings reflect standard transactional concepts. If necessary, refer to resources that discuss transaction isolation levels and other core transaction concepts. @@ -218,8 +218,10 @@ transaction management solution. The `TransactionStatus` interface provides a simple way for transactional code to control transaction execution and query transaction status. The concepts should be -familiar, as they are common to all transaction APIs: +familiar, as they are common to all transaction APIs. The following listing shows the +`TransactionStatus` interface: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -239,6 +241,7 @@ familiar, as they are common to all transaction APIs: } ---- +==== Regardless of whether you opt for declarative or programmatic transaction management in Spring, defining the correct `PlatformTransactionManager` implementation is absolutely @@ -246,11 +249,12 @@ essential. You typically define this implementation through dependency injection `PlatformTransactionManager` implementations normally require knowledge of the environment in which they work: JDBC, JTA, Hibernate, and so on. The following examples -show how you can define a local `PlatformTransactionManager` implementation. (This -example works with plain JDBC.) +show how you can define a local `PlatformTransactionManager` implementation (in this case, +with plain JDBC.) -You define a JDBC `DataSource` +You can define a JDBC `DataSource` by creating a bean similar to the following: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -261,10 +265,12 @@ You define a JDBC `DataSource` ---- +==== -The related `PlatformTransactionManager` bean definition will then have a reference to -the `DataSource` definition. It will look like this: +The related `PlatformTransactionManager` bean definition then has a reference to +the `DataSource` definition. It should resemble the following example: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -272,11 +278,13 @@ the `DataSource` definition. It will look like this: ---- +==== -If you use JTA in a Java EE container then you use a container `DataSource`, obtained -through JNDI, in conjunction with Spring's `JtaTransactionManager`. This is what the JTA +If you use JTA in a Java EE container, then you use a container `DataSource`, obtained +through JNDI, in conjunction with Spring's `JtaTransactionManager`. The following example shows what the JTA and JNDI lookup version would look like: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -298,36 +306,33 @@ and JNDI lookup version would look like: ---- +==== -The `JtaTransactionManager` does not need to know about the `DataSource`, or any other -specific resources, because it uses the container's global transaction management +The `JtaTransactionManager` does not need to know about the `DataSource` (or any other +specific resources) because it uses the container's global transaction management infrastructure. -[NOTE] -==== -The above definition of the `dataSource` bean uses the `` tag from the +NOTE: The preceding definition of the `dataSource` bean uses the `` tag from the `jee` namespace. For more information see -<>. -==== +<>. -You can also use Hibernate local transactions easily, as shown in the following +You can also use easily Hibernate local transactions, as shown in the following examples. In this case, you need to define a Hibernate `LocalSessionFactoryBean`, -which your application code will use to obtain Hibernate `Session` instances. +which your application code can use to obtain Hibernate `Session` instances. -The `DataSource` bean definition will be similar to the local JDBC example shown -previously and thus is not shown in the following example. +The `DataSource` bean definition is similar to the local JDBC example shown +previously and, thus, is not shown in the following example. -[NOTE] -==== -If the `DataSource`, used by any non-JTA transaction manager, is looked up via JNDI and -managed by a Java EE container, then it should be non-transactional because the Spring -Framework, rather than the Java EE container, will manage the transactions. -==== +NOTE: If the `DataSource` (used by any non-JTA transaction manager) is looked up through JNDI and +managed by a Java EE container, it should be non-transactional, because the Spring +Framework (rather than the Java EE container) manages the transactions. The `txManager` bean in this case is of the `HibernateTransactionManager` type. In the same way as the `DataSourceTransactionManager` needs a reference to the `DataSource`, the `HibernateTransactionManager` needs a reference to the `SessionFactory`. +The following example declares `sessionFactory` and `txManager` beans: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -349,10 +354,11 @@ the `HibernateTransactionManager` needs a reference to the `SessionFactory`. ---- +==== -If you are using Hibernate and Java EE container-managed JTA transactions, then you -should simply use the same `JtaTransactionManager` as in the previous JTA example for -JDBC. +If you use Hibernate and Java EE container-managed JTA transactions, you +should use the same `JtaTransactionManager` as in the previous JTA example for +JDBC, as the following example shows: [source,xml,indent=0] [subs="verbatim,quotes"] @@ -360,13 +366,10 @@ JDBC. ---- -[NOTE] -==== -If you use JTA , then your transaction manager definition will look the same regardless -of what data access technology you use, be it JDBC, Hibernate JPA or any other supported +NOTE: If you use JTA, your transaction manager definition should look the same, regardless +of what data access technology you use, be it JDBC, Hibernate JPA, or any other supported technology. This is due to the fact that JTA transactions are global transactions, which can enlist any transactional resource. -==== In all these cases, application code does not need to change. You can change how transactions are managed merely by changing configuration, even if that change means @@ -375,34 +378,36 @@ moving from local to global transactions or vice versa. [[tx-resource-synchronization]] -=== Synchronizing resources with transactions +=== Synchronizing Resources with Transactions -It should now be clear how you create different transaction managers, and how they are +How to create different transaction managers and how they are linked to related resources that need to be synchronized to transactions (for example `DataSourceTransactionManager` to a JDBC `DataSource`, `HibernateTransactionManager` to -a Hibernate `SessionFactory`, and so forth). This section describes how the application -code, directly or indirectly using a persistence API such as JDBC, Hibernate, or JPA, +a Hibernate `SessionFactory`, and so forth) should now be clear. This section describes how the application +code (directly or indirectly, by using a persistence API such as JDBC, Hibernate, or JPA) ensures that these resources are created, reused, and cleaned up properly. The section -also discusses how transaction synchronization is triggered (optionally) through the +also discusses how transaction synchronization is (optionally) triggered through the relevant `PlatformTransactionManager`. + [[tx-resource-synchronization-high]] -==== High-level synchronization approach +==== High-level Synchronization Approach -The preferred approach is to use Spring's highest level template based persistence -integration APIs or to use native ORM APIs with transaction- aware factory beans or +The preferred approach is to use Spring's highest-level template based persistence +integration APIs or to use native ORM APIs with transaction-aware factory beans or proxies for managing the native resource factories. These transaction-aware solutions internally handle resource creation and reuse, cleanup, optional transaction -synchronization of the resources, and exception mapping. Thus user data access code does -not have to address these tasks, but can be focused purely on non-boilerplate -persistence logic. Generally, you use the native ORM API or take a __template__ approach +synchronization of the resources, and exception mapping. Thus, user data access code does +not have to address these tasks but can focus purely on non-boilerplate +persistence logic. Generally, you use the native ORM API or take a template approach for JDBC access by using the `JdbcTemplate`. These solutions are detailed in subsequent chapters of this reference documentation. + [[tx-resource-synchronization-low]] -==== Low-level synchronization approach +==== Low-level Synchronization Approach Classes such as `DataSourceUtils` (for JDBC), `EntityManagerFactoryUtils` (for JPA), `SessionFactoryUtils` (for Hibernate), and so on exist at a lower level. When you want the @@ -412,90 +417,90 @@ transactions are (optionally) synchronized, and exceptions that occur in the pro properly mapped to a consistent API. For example, in the case of JDBC, instead of the traditional JDBC approach of calling -the `getConnection()` method on the `DataSource`, you instead use Spring's -`org.springframework.jdbc.datasource.DataSourceUtils` class as follows: +the `getConnection()` method on the `DataSource`, you can instead use Spring's +`org.springframework.jdbc.datasource.DataSourceUtils` class, as follows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- Connection conn = DataSourceUtils.getConnection(dataSource); ---- +==== If an existing transaction already has a connection synchronized (linked) to it, that instance is returned. Otherwise, the method call triggers the creation of a new -connection, which is (optionally) synchronized to any existing transaction, and made -available for subsequent reuse in that same transaction. As mentioned, any +connection, which is (optionally) synchronized to any existing transaction and made +available for subsequent reuse in that same transaction. As mentioned earlier, any `SQLException` is wrapped in a Spring Framework `CannotGetJdbcConnectionException`, one -of the Spring Framework's hierarchy of unchecked DataAccessExceptions. This approach -gives you more information than can be obtained easily from the `SQLException`, and -ensures portability across databases, even across different persistence technologies. +of the Spring Framework's hierarchy of unchecked `DataAccessException` types. This approach +gives you more information than can be obtained easily from the `SQLException` and +ensures portability across databases and even across different persistence technologies. This approach also works without Spring transaction management (transaction -synchronization is optional), so you can use it whether or not you are using Spring for +synchronization is optional), so you can use it whether or not you use Spring for transaction management. -Of course, once you have used Spring's JDBC support, JPA support or Hibernate support, -you will generally prefer not to use `DataSourceUtils` or the other helper classes, -because you will be much happier working through the Spring abstraction than directly +Of course, once you have used Spring's JDBC support, JPA support, or Hibernate support, +you generally prefer not to use `DataSourceUtils` or the other helper classes, +because you are much happier working through the Spring abstraction than directly with the relevant APIs. For example, if you use the Spring `JdbcTemplate` or `jdbc.object` package to simplify your use of JDBC, correct connection retrieval occurs -behind the scenes and you won't need to write any special code. +behind the scenes and you need not write any special code. + [[tx-resource-synchronization-tadsp]] -==== TransactionAwareDataSourceProxy +==== `TransactionAwareDataSourceProxy` At the very lowest level exists the `TransactionAwareDataSourceProxy` class. This is a proxy for a target `DataSource`, which wraps the target `DataSource` to add awareness of Spring-managed transactions. In this respect, it is similar to a transactional JNDI -`DataSource` as provided by a Java EE server. +`DataSource`, as provided by a Java EE server. -It should almost never be necessary or desirable to use this class, except when existing +You should almost never need or want to use this class, except when existing code must be called and passed a standard JDBC `DataSource` interface implementation. In -that case, it is possible that this code is usable, but participating in Spring managed -transactions. It is preferable to write your new code by using the higher level -abstractions mentioned above. +that case, it is possible that this code is usable but is participating in Spring-managed +transactions. You can write your new code by using the higher-level +abstractions mentioned earlier. [[transaction-declarative]] === Declarative transaction management -[NOTE] -==== -Most Spring Framework users choose declarative transaction management. This option has -the least impact on application code, and hence is most consistent with the ideals of a -__non-invasive__ lightweight container. -==== +NOTE: Most Spring Framework users choose declarative transaction management. This option has +the least impact on application code and, hence, is most consistent with the ideals of a +non-invasive lightweight container. The Spring Framework's declarative transaction management is made possible with Spring -aspect-oriented programming (AOP), although, as the transactional aspects code comes +aspect-oriented programming (AOP). However, as the transactional aspects code comes with the Spring Framework distribution and may be used in a boilerplate fashion, AOP concepts do not generally have to be understood to make effective use of this code. -The Spring Framework's declarative transaction management is similar to EJB CMT in that -you can specify transaction behavior (or lack of it) down to individual method level. It -is possible to make a `setRollbackOnly()` call within a transaction context if +The Spring Framework's declarative transaction management is similar to EJB CMT, in that +you can specify transaction behavior (or lack of it) down to the individual method level. +You can make a `setRollbackOnly()` call within a transaction context, if necessary. The differences between the two types of transaction management are: * Unlike EJB CMT, which is tied to JTA, the Spring Framework's declarative transaction management works in any environment. It can work with JTA transactions or local - transactions using JDBC, JPA or Hibernate by simply adjusting the configuration + transactions by using JDBC, JPA, or Hibernate by adjusting the configuration files. * You can apply the Spring Framework declarative transaction management to any class, not merely special classes such as EJBs. * The Spring Framework offers declarative - <>a feature with no EJB + <>, a feature with no EJB equivalent. Both programmatic and declarative support for rollback rules is provided. -* The Spring Framework enables you to customize transactional behavior, by using AOP. +* The Spring Framework lets you customize transactional behavior by using AOP. For example, you can insert custom behavior in the case of transaction rollback. You - can also add arbitrary advice, along with the transactional advice. With EJB CMT, you - cannot influence the container's transaction management except with + can also add arbitrary advice, along with transactional advice. With EJB CMT, you + cannot influence the container's transaction management, except with `setRollbackOnly()`. * The Spring Framework does not support propagation of transaction contexts across - remote calls, as do high-end application servers. If you need this feature, we + remote calls, as high-end application servers do. If you need this feature, we recommend that you use EJB. However, consider carefully before using such a feature, - because normally, one does not want transactions to span remote calls. + because, normally, one does not want transactions to span remote calls. .Where is TransactionProxyFactoryBean? **** @@ -503,12 +508,12 @@ Declarative transaction configuration in versions of Spring 2.0 and above differ considerably from previous versions of Spring. The main difference is that there is no longer any need to configure `TransactionProxyFactoryBean` beans. -The pre-Spring 2.0 configuration style is still 100% valid configuration; think of the -new `` as simply defining `TransactionProxyFactoryBean` beans on your behalf. +The pre-Spring 2.0 configuration style is still 100% valid configuration. Think of the +new `` as defining `TransactionProxyFactoryBean` beans on your behalf. **** -The concept of rollback rules is important: they enable you to specify which exceptions -(and throwables) should cause automatic rollback. You specify this declaratively, in +The concept of rollback rules is important. They let you specify which exceptions +(and throwables) should cause automatic rollback. You can specify this declaratively, in configuration, not in Java code. So, although you can still call `setRollbackOnly()` on the `TransactionStatus` object to roll back the current transaction back, most often you can specify a rule that `MyApplicationException` must always result in rollback. The @@ -517,51 +522,51 @@ transaction infrastructure. For example, they typically do not need to import Sp transaction APIs or other Spring APIs. Although EJB container default behavior automatically rolls back the transaction on a -__system exception__ (usually a runtime exception), EJB CMT does not roll back the -transaction automatically on an__application exception__ (that is, a checked exception +system exception (usually a runtime exception), EJB CMT does not roll back the +transaction automatically on an application exception (that is, a checked exception other than `java.rmi.RemoteException`). While the Spring default behavior for declarative transaction management follows EJB convention (roll back is automatic only on unchecked exceptions), it is often useful to customize this behavior. + [[tx-decl-explained]] -==== Understanding the Spring Framework's declarative transaction implementation +==== Understanding the Spring Framework's Declarative Transaction Implementation -It is not sufficient to tell you simply to annotate your classes with the +It is not sufficient merely to tell you to annotate your classes with the `@Transactional` annotation, add `@EnableTransactionManagement` to your configuration, -and then expect you to understand how it all works. This section explains the inner +and expect you to understand how it all works. To provide a deeper understanding, this section explains the inner workings of the Spring Framework's declarative transaction infrastructure in the event of transaction-related issues. The most important concepts to grasp with regard to the Spring Framework's declarative transaction support are that this support is enabled -<>, and that the transactional advice -is driven by __metadata__ (currently XML- or annotation-based). The combination of AOP +<> and that the transactional advice +is driven by metadata (currently XML- or annotation-based). The combination of AOP with transactional metadata yields an AOP proxy that uses a `TransactionInterceptor` in conjunction with an appropriate `PlatformTransactionManager` implementation to drive -transactions __around method invocations__. +transactions around method invocations. -[NOTE] -==== -Spring AOP is covered in <>. -==== +NOTE: Spring AOP is covered in <>. -Conceptually, calling a method on a transactional proxy looks like this... +The following images shows a Conceptual view of calling a method on a transactional proxy: image::images/tx.png[] + [[transaction-declarative-first-example]] -==== Example of declarative transaction implementation +==== Example of Declarative Transaction Implementation -Consider the following interface, and its attendant implementation. This example uses +Consider the following interface and its attendant implementation. This example uses `Foo` and `Bar` classes as placeholders so that you can concentrate on the transaction usage without focusing on a particular domain model. For the purposes of this example, the fact that the `DefaultFooService` class throws `UnsupportedOperationException` -instances in the body of each implemented method is good; it allows you to see -transactions created and then rolled back in response to the -`UnsupportedOperationException` instance. +instances in the body of each implemented method is good. That behavior lets you see +transactions be created and then rolled back in response to the +`UnsupportedOperationException` instance. The following listing shows the `FooService` interface: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -581,12 +586,14 @@ transactions created and then rolled back in response to the } ---- +==== + +The following exampl shows an implementation of the preceding interface: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- - // an implementation of the above interface - package x.y.service; public class DefaultFooService implements FooService { @@ -609,13 +616,15 @@ transactions created and then rolled back in response to the } ---- +==== Assume that the first two methods of the `FooService` interface, `getFoo(String)` and `getFoo(String, String)`, must execute in the context of a transaction with read-only semantics, and that the other methods, `insertFoo(Foo)` and `updateFoo(Foo)`, must execute in the context of a transaction with read-write semantics. The following -configuration is explained in detail in the next few paragraphs. +configuration is explained in detail in the next few paragraphs: +==== [source,xml,indent=0] [subs="verbatim"] ---- @@ -671,39 +680,38 @@ configuration is explained in detail in the next few paragraphs. ---- +==== -Examine the preceding configuration. You want to make a service object, the `fooService` +Examine the preceding configuration. It assumes that you want to make a service object, the `fooService` bean, transactional. The transaction semantics to apply are encapsulated in the -`` definition. The `` definition reads as "__... all methods on -starting with `'get'` are to execute in the context of a read-only transaction, and all -other methods are to execute with the default transaction semantics__". The +`` definition. The `` definition reads as "`all methods, on +starting with `get`, are to execute in the context of a read-only transaction, and all +other methods are to execute with the default transaction semantics`". The `transaction-manager` attribute of the `` tag is set to the name of the -`PlatformTransactionManager` bean that is going to __drive__ the transactions, in this -case, the `txManager` bean. +`PlatformTransactionManager` bean that is going to drive the transactions (in this +case, the `txManager` bean). -[TIP] -==== -You can omit the `transaction-manager` attribute in the transactional advice +TIP: You can omit the `transaction-manager` attribute in the transactional advice (``) if the bean name of the `PlatformTransactionManager` that you want to wire in has the name `transactionManager`. If the `PlatformTransactionManager` bean that -you want to wire in has any other name, then you must use the `transaction-manager` +you want to wire in has any other name, you must use the `transaction-manager` attribute explicitly, as in the preceding example. -==== The `` definition ensures that the transactional advice defined by the -`txAdvice` bean executes at the appropriate points in the program. First you define a +`txAdvice` bean executes at the appropriate points in the program. First, you define a pointcut that matches the execution of any operation defined in the `FooService` interface ( `fooServiceOperation`). Then you associate the pointcut with the `txAdvice` -using an advisor. The result indicates that at the execution of a `fooServiceOperation`, -the advice defined by `txAdvice` will be run. +by using an advisor. The result indicates that, at the execution of a `fooServiceOperation`, +the advice defined by `txAdvice` is run. The expression defined within the `` element is an AspectJ pointcut -expression; see <> for more details on pointcut expressions in Spring. +expression. See <> for more details on pointcut expressions in Spring. A common requirement is to make an entire service layer transactional. The best way to -do this is simply to change the pointcut expression to match any operation in your -service layer. For example: +do this is to change the pointcut expression to match any operation in your +service layer. The following example shows how to do so: +==== [source,xml,indent=0] [subs="verbatim"] ---- @@ -712,23 +720,22 @@ service layer. For example: ---- - -[NOTE] -==== -__In this example it is assumed that all your service interfaces are defined in the -`x.y.service` package; see <> for more details.__ ==== -Now that we've analyzed the configuration, you may be asking yourself, "__Okay... but -what does all this configuration actually do?__". +NOTE: In the preceding example, it is assumed that all your service interfaces are defined in the +`x.y.service` package. See <> for more details. -The above configuration will be used to create a transactional proxy around the object -that is created from the `fooService` bean definition. The proxy will be configured with -the transactional advice, so that when an appropriate method is invoked __on the -proxy__, a transaction is started, suspended, marked as read-only, and so on, depending +Now that we have analyzed the configuration, you may be asking yourself, +"`What does all this configuration actually do?`" + +The configuration shown earlier is used to create a transactional proxy around the object +that is created from the `fooService` bean definition. The proxy is configured with +the transactional advice so that, when an appropriate method is invoked on the +proxy, a transaction is started, suspended, marked as read-only, and so on, depending on the transaction configuration associated with that method. Consider the following -program that test drives the above configuration: +program that test drives the configuration shown earlier: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -741,11 +748,13 @@ program that test drives the above configuration: } } ---- +==== -The output from running the preceding program will resemble the following. (The Log4J +The output from running the preceding program should resemble the following (the Log4J output and the stack trace from the UnsupportedOperationException thrown by the -insertFoo(..) method of the DefaultFooService class have been truncated for clarity.) +insertFoo(..) method of the DefaultFooService class have been truncated for clarity): +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -776,33 +785,36 @@ insertFoo(..) method of the DefaultFooService class have been truncated for clar at $Proxy0.insertFoo(Unknown Source) at Boot.main(Boot.java:11) ---- +==== + [[transaction-declarative-rolling-back]] -==== Rolling back a declarative transaction +==== Rolling Back a Declarative Transaction The previous section outlined the basics of how to specify transactional settings for classes, typically service layer classes, declaratively in your application. This -section describes how you can control the rollback of transactions in a simple +section describes how you can control the rollback of transactions in a simple, declarative fashion. The recommended way to indicate to the Spring Framework's transaction infrastructure that a transaction's work is to be rolled back is to throw an `Exception` from code that is currently executing in the context of a transaction. The Spring Framework's -transaction infrastructure code will catch any unhandled `Exception` as it bubbles up -the call stack, and make a determination whether to mark the transaction for rollback. +transaction infrastructure code catches any unhandled `Exception` as it bubbles up +the call stack and makes a determination whether to mark the transaction for rollback. In its default configuration, the Spring Framework's transaction infrastructure code -__only__ marks a transaction for rollback in the case of runtime, unchecked exceptions; -that is, when the thrown exception is an instance or subclass of `RuntimeException`. ( -``Error``s will also - by default - result in a rollback). Checked exceptions that are -thrown from a transactional method do __not__ result in rollback in the default +marks a transaction for rollback only in the case of runtime, unchecked exceptions. +That is, when the thrown exception is an instance or subclass of `RuntimeException`. ( +`Error` instances also, by default, result in a rollback). Checked exceptions that are +thrown from a transactional method do not result in rollback in the default configuration. You can configure exactly which `Exception` types mark a transaction for rollback, including checked exceptions. The following XML snippet demonstrates how you configure -rollback for a checked, application-specific `Exception` type. +rollback for a checked, application-specific `Exception` type: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -813,12 +825,14 @@ rollback for a checked, application-specific `Exception` type. ---- +==== -You can also specify 'no rollback rules', if you do __not__ want a transaction rolled -back when an exception is thrown. The following example tells the Spring Framework's +If you do not want a transaction rolled +back when an exception is thrown, you can also specify 'no rollback rules'. The following example tells the Spring Framework's transaction infrastructure to commit the attendant transaction even in the face of an -unhandled `InstrumentNotFoundException`. +unhandled `InstrumentNotFoundException`: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -829,13 +843,15 @@ unhandled `InstrumentNotFoundException`. ---- +==== When the Spring Framework's transaction infrastructure catches an exception and it -consults configured rollback rules to determine whether to mark the transaction for -rollback, the __strongest__ matching rule wins. So in the case of the following +consults the configured rollback rules to determine whether to mark the transaction for +rollback, the strongest matching rule wins. So, in the case of the following configuration, any exception other than an `InstrumentNotFoundException` results in a -rollback of the attendant transaction. +rollback of the attendant transaction: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -845,11 +861,14 @@ rollback of the attendant transaction. ---- +==== -You can also indicate a required rollback __programmatically__. Although very simple, -this process is quite invasive, and tightly couples your code to the Spring Framework's -transaction infrastructure: +You can also indicate a required rollback programmatically. Although simple, +this process is quite invasive and tightly couples your code to the Spring Framework's +transaction infrastructure. The following example shows how to programmatically indicate +a required rollback: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -862,25 +881,28 @@ transaction infrastructure: } } ---- +==== -You are strongly encouraged to use the declarative approach to rollback if at all +You are strongly encouraged to use the declarative approach to rollback, if at all possible. Programmatic rollback is available should you absolutely need it, but its usage flies in the face of achieving a clean POJO-based architecture. + [[transaction-declarative-diff-tx]] -==== Configuring different transactional semantics for different beans +==== Configuring Different Transactional Semantics for Different Beans Consider the scenario where you have a number of service layer objects, and you want to -apply a __totally different__ transactional configuration to each of them. You do this +apply a totally different transactional configuration to each of them. You can do so by defining distinct `` elements with differing `pointcut` and `advice-ref` attribute values. As a point of comparison, first assume that all of your service layer classes are defined in a root `x.y.service` package. To make all beans that are instances of classes defined in that package (or in subpackages) and that have names ending in `Service` have -the default transactional configuration, you would write the following: +the default transactional configuration, you could write the following: +==== [source,xml,indent=0] [subs="verbatim"] ---- @@ -925,10 +947,12 @@ the default transactional configuration, you would write the following: ---- +==== The following example shows how to configure two distinct beans with totally different -transactional settings. +transactional settings: +==== [source,xml,indent=0] [subs="verbatim"] ---- @@ -982,23 +1006,25 @@ transactional settings. ---- +==== + [[transaction-declarative-txadvice-settings]] -==== settings +==== Settings -This section summarizes the various transactional settings that can be specified using +This section summarizes the various transactional settings that you can specifyi by using the `` tag. The default `` settings are: -* <> is `REQUIRED.` -* Isolation level is `DEFAULT.` -* Transaction is read/write. -* Transaction timeout defaults to the default timeout of the underlying transaction - system, or none if timeouts are not supported. +* The <> is `REQUIRED.` +* The isolation level is `DEFAULT.` +* The transaction is read-write. +* The transaction timeout defaults to the default timeout of the underlying transaction + system or none if timeouts are not supported. * Any `RuntimeException` triggers rollback, and any checked `Exception` does not. -You can change these default settings; the various attributes of the `` tags -that are nested within `` and `` tags are summarized below: +You can change these default settings. The following table summarizes the various attributes of the `` tags +that are nested within `` and `` tags: [[tx-method-settings]] . settings @@ -1008,47 +1034,48 @@ that are nested within `` and `` tags are summarized | `name` | Yes | -| Method name(s) with which the transaction attributes are to be associated. The +| Method names with which the transaction attributes are to be associated. The wildcard ({asterisk}) character can be used to associate the same transaction attribute - settings with a number of methods; for example, `get*`, `handle*`, `on*Event`, and so - forth. + settings with a number of methods (for example, `get*`, `handle*`, `on*Event`, and so + forth). | `propagation` | No -| REQUIRED +| `REQUIRED` | Transaction propagation behavior. | `isolation` | No -| DEFAULT -| Transaction isolation level. Only applicable to propagation REQUIRED or REQUIRES_NEW. +| `DEFAULT` +| Transaction isolation level. Only applicable to propagation settings of `REQUIRED` or `REQUIRES_NEW`. | `timeout` | No | -1 -| Transaction timeout (seconds). Only applicable to propagation REQUIRED or REQUIRES_NEW. +| Transaction timeout (seconds). Only applicable to propagation `REQUIRED` or `REQUIRES_NEW`. | `read-only` | No | false -| Read/write vs. read-only transaction. Only applicable to REQUIRED or REQUIRES_NEW. +| Read-write versus read-only transaction. Applies only to `REQUIRED` or `REQUIRES_NEW`. | `rollback-for` | No | -| `Exception(s)` that trigger rollback; comma-delimited. For example, +| Comma-delimited list of `Exception` instances that trigger rollback. For example, `com.foo.MyBusinessException,ServletException.` | `no-rollback-for` | No | -| `Exception(s)` that do __not__ trigger rollback; comma-delimited. For example, +| Comma-delimited list of `Exception` instances that do not trigger rollback. For example, `com.foo.MyBusinessException,ServletException.` |=== + [[transaction-declarative-annotations]] -==== Using @Transactional +==== Using `@Transactional` In addition to the XML-based declarative approach to transaction configuration, you can use an annotation-based approach. Declaring transaction semantics directly in the Java @@ -1056,17 +1083,15 @@ source code puts the declarations much closer to the affected code. There is not danger of undue coupling, because code that is meant to be used transactionally is almost always deployed that way anyway. -[NOTE] -==== -The standard `javax.transaction.Transactional` annotation is also supported as a drop-in +NOTE: The standard `javax.transaction.Transactional` annotation is also supported as a drop-in replacement to Spring's own annotation. Please refer to JTA 1.2 documentation for more details. -==== The ease-of-use afforded by the use of the `@Transactional` annotation is best illustrated with an example, which is explained in the text that follows. Consider the following class definition: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1083,10 +1108,12 @@ following class definition: void updateFoo(Foo foo); } ---- +==== -When the above POJO is defined as a bean in a Spring IoC container, the bean instance -can be made transactional by adding merely __one__ line of XML configuration: +When the preceding POJO is defined as a bean in a Spring IoC container, you can make the bean instance +transactional by adding only one line of XML configuration: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -1108,7 +1135,7 @@ can be made transactional by adding merely __one__ line of XML configuration: - ____ + <1> @@ -1118,68 +1145,58 @@ can be made transactional by adding merely __one__ line of XML configuration: ---- - -[TIP] +<1> The line that makes the bean instance transactional. ==== -You can omit the `transaction-manager` attribute in the `` tag if -the bean name of the `PlatformTransactionManager` that you want to wire in has the name + +TIP: You can omit the `transaction-manager` attribute in the `` tag if +the bean name of the `PlatformTransactionManager` that you want to wire in has the name, `transactionManager`. If the `PlatformTransactionManager` bean that you want to -dependency-inject has any other name, then you have to use the `transaction-manager` -attribute explicitly, as in the preceding example. -==== +dependency-inject has any other name, you have to use the `transaction-manager` +attribute, as in the preceding example. -[NOTE] -==== -The `@EnableTransactionManagement` annotation provides equivalent support if you are -using Java based configuration. Simply add the annotation to a `@Configuration` class. -See the javadocs for full details. -==== +NOTE: If you +use Java-based configuration, the `@EnableTransactionManagement` annotation provides equivalent support . You can add the annotation to a `@Configuration` class. +See the {api-spring-framework}/transaction/annotation/EnableTransactionManagement.html[Javadoc] for full details. -.Method visibility and @Transactional +.Method visibility and `@Transactional` **** -When using proxies, you should apply the `@Transactional` annotation only to methods -with __public__ visibility. If you do annotate protected, private or package-visible +When you use proxies, you should apply the `@Transactional` annotation only to methods +with public visibility. If you do annotate protected, private or package-visible methods with the `@Transactional` annotation, no error is raised, but the annotated -method does not exhibit the configured transactional settings. Consider the use of -AspectJ (see below) if you need to annotate non-public methods. +method does not exhibit the configured transactional settings. If you need to annotate non-public methods, consider using +AspectJ (described later). **** You can place the `@Transactional` annotation before an interface definition, a method -on an interface, a class definition, or a __public__ method on a class. However, the +on an interface, a class definition, or a public method on a class. However, the mere presence of the `@Transactional` annotation is not enough to activate the -transactional behavior. The `@Transactional` annotation is simply metadata that can be +transactional behavior. The `@Transactional` annotation is merely metadata that can be consumed by some runtime infrastructure that is `@Transactional`-aware and that can use the metadata to configure the appropriate beans with transactional behavior. In the -preceding example, the `` element __switches on__ the +preceding example, the `` element switches on the transactional behavior. -[TIP] -==== -Spring recommends that you only annotate concrete classes (and methods of concrete +TIP: The Spring team recommends that you annotate only concrete classes (and methods of concrete classes) with the `@Transactional` annotation, as opposed to annotating interfaces. You certainly can place the `@Transactional` annotation on an interface (or an interface -method), but this works only as you would expect it to if you are using interface-based -proxies. The fact that Java annotations are __not inherited from interfaces__ means that -if you are using class-based proxies ( `proxy-target-class="true"`) or the weaving-based -aspect ( `mode="aspectj"`), then the transaction settings are not recognized by the -proxying and weaving infrastructure, and the object will not be wrapped in a -transactional proxy, which would be decidedly __bad__. -==== - -[NOTE] -==== -In proxy mode (which is the default), only external method calls coming in through the -proxy are intercepted. This means that self-invocation, in effect, a method within the -target object calling another method of the target object, will not lead to an actual +method), but this works only as you would expect it to if you use interface-based +proxies. The fact that Java annotations are not inherited from interfaces means that, +if you use class-based proxies (`proxy-target-class="true"`) or the weaving-based +aspect (`mode="aspectj"`), the transaction settings are not recognized by the +proxying and weaving infrastructure, and the object is not wrapped in a +transactional proxy, which would be decidedly bad. + +NOTE: In proxy mode (which is the default), only external method calls coming in through the +proxy are intercepted. This means that self-invocation (in effect, a method within the +target object calling another method of the target object) does not lead to an actual transaction at runtime even if the invoked method is marked with `@Transactional`. Also, -the proxy must be fully initialized to provide the expected behaviour so you should not -rely on this feature in your initialization code, i.e. `@PostConstruct`. -==== +the proxy must be fully initialized to provide the expected behavior, so you should not +rely on this feature in your initialization code (that is, `@PostConstruct`). -Consider the use of AspectJ mode (see mode attribute in table below) if you expect -self-invocations to be wrapped with transactions as well. In this case, there will not -be a proxy in the first place; instead, the target class will be weaved (that is, its -byte code will be modified) in order to turn `@Transactional` into runtime behavior on +Consider using of AspectJ mode (see the `mode` attribute in the following table) if you expect +self-invocations to be wrapped with transactions as well. In this case, there no +proxy in the first place. Instead, the target class is woven (that is, its +byte code is modified) to turn `@Transactional` into runtime behavior on any kind of method. [[tx-annotation-driven-settings]] @@ -1188,68 +1205,59 @@ any kind of method. | XML Attribute| Annotation Attribute| Default| Description | `transaction-manager` -| N/A (See `TransactionManagementConfigurer` javadocs) -| transactionManager -| Name of transaction manager to use. Only required if the name of the transaction - manager is not `transactionManager`, as in the example above. +| N/A (See {api-spring-framework}/transaction/annotation/TransactionManagementConfigurer.html[`TransactionManagementConfigurer` Javadoc]) +| `transactionManager` +| Name of the transaction manager to use. Required only if the name of the transaction + manager is not `transactionManager`, as in the preceding example. | `mode` | `mode` -| proxy -| The default mode "proxy" processes annotated beans to be proxied using Spring's AOP - framework (following proxy semantics, as discussed above, applying to method calls - coming in through the proxy only). The alternative mode "aspectj" instead weaves the +| `proxy` +| The default mode (`proxy`) processes annotated beans to be proxied by using Spring's AOP + framework (following proxy semantics, as discussed earlier, applying to method calls + coming in through the proxy only). The alternative mode (`aspectj`) instead weaves the affected classes with Spring's AspectJ transaction aspect, modifying the target class byte code to apply to any kind of method call. AspectJ weaving requires - spring-aspects.jar in the classpath as well as load-time weaving (or compile-time + `spring-aspects.jar` in the classpath as well as having load-time weaving (or compile-time weaving) enabled. (See <> for details on how to set up load-time weaving.) | `proxy-target-class` | `proxyTargetClass` -| false -| Applies to proxy mode only. Controls what type of transactional proxies are created +| `false` +| Applies to `proxy` mode only. Controls what type of transactional proxies are created for classes annotated with the `@Transactional` annotation. If the - `proxy-target-class` attribute is set to `true`, then class-based proxies are created. + `proxy-target-class` attribute is set to `true`, class-based proxies are created. If `proxy-target-class` is `false` or if the attribute is omitted, then standard JDK interface-based proxies are created. (See <> for a detailed examination of the different proxy types.) | `order` | `order` -| Ordered.LOWEST_PRECEDENCE +| `Ordered.LOWEST_PRECEDENCE` | Defines the order of the transaction advice that is applied to beans annotated with `@Transactional`. (For more information about the rules related to ordering of AOP - advice, see <>.) + advice, see <>.) No specified ordering means that the AOP subsystem determines the order of the advice. |=== -[NOTE] -==== -The default advice mode for processing `@Transactional` annotations is "proxy" which -allows for interception of calls through the proxy only; local calls within the same +NOTE: The default advice mode for processing `@Transactional` annotations is `proxy`, which +allows for interception of calls through the proxy only. Local calls within the same class cannot get intercepted that way. For a more advanced mode of interception, -consider switching to "aspectj" mode in combination with compile/load-time weaving. -==== +consider switching to `aspectj` mode in combination with compile-time or load-time weaving. -[NOTE] -==== -The `proxy-target-class` attribute controls what type of transactional proxies are +NOTE: The `proxy-target-class` attribute controls what type of transactional proxies are created for classes annotated with the `@Transactional` annotation. If `proxy-target-class` is set to `true`, class-based proxies are created. If `proxy-target-class` is `false` or if the attribute is omitted, standard JDK interface-based proxies are created. (See <> for a discussion of the different proxy types.) -==== -[NOTE] -==== -`@EnableTransactionManagement` and `` only looks for -`@Transactional` on beans in the same application context they are defined in. This -means that, if you put annotation driven configuration in a `WebApplicationContext` for -a `DispatcherServlet`, it only checks for `@Transactional` beans in your controllers, +NOTE: `@EnableTransactionManagement` and `` looks for +`@Transactional` only on beans in the same application context in which they are defined. This +means that, if you put annotation-driven configuration in a `WebApplicationContext` for +a `DispatcherServlet`, it checks for `@Transactional` beans only in your controllers and not your services. See <> for more information. -==== The most derived location takes precedence when evaluating the transactional settings for a method. In the case of the following example, the `DefaultFooService` class is @@ -1257,6 +1265,7 @@ annotated at the class level with the settings for a read-only transaction, but `@Transactional` annotation on the `updateFoo(Foo)` method in the same class takes precedence over the transactional settings defined at the class level. +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1274,24 +1283,27 @@ precedence over the transactional settings defined at the class level. } } ---- +==== + + [[transaction-declarative-attransactional-settings]] -===== @Transactional settings +===== `@Transactional` Settings The `@Transactional` annotation is metadata that specifies that an interface, class, or -method must have transactional semantics; for example, "__start a brand new read-only -transaction when this method is invoked, suspending any existing transaction__". The +method must have transactional semantics (for example, "`start a brand new read-only +transaction when this method is invoked, suspending any existing transaction`"). The default `@Transactional` settings are as follows: -* Propagation setting is `PROPAGATION_REQUIRED.` -* Isolation level is `ISOLATION_DEFAULT.` -* Transaction is read/write. -* Transaction timeout defaults to the default timeout of the underlying transaction +* The propagation setting is `PROPAGATION_REQUIRED.` +* The isolation level is `ISOLATION_DEFAULT.` +* The transaction is read-write. +* The transaction timeout defaults to the default timeout of the underlying transaction system, or to none if timeouts are not supported. * Any `RuntimeException` triggers rollback, and any checked `Exception` does not. -These default settings can be changed; the various properties of the `@Transactional` -annotation are summarized in the following table: +You can change these default settings. The following table summarizes the various properties of the `@Transactional` +annotation: [[tx-attransactional-properties]] .@Transactional Settings @@ -1299,60 +1311,64 @@ annotation are summarized in the following table: | Property| Type| Description | <> -| String -| Optional qualifier specifying the transaction manager to be used. +| `String` +| Optional qualifier that specifies the transaction manager to be used. | <> -| enum: `Propagation` +| `enum`: `Propagation` | Optional propagation setting. | `isolation` -| enum: `Isolation` -| Optional isolation level. Only applicable to propagation REQUIRED or REQUIRES_NEW. +| `enum`: `Isolation` +| Optional isolation level. Applies only to propagation valeus of `REQUIRED` or `REQUIRES_NEW`. | `timeout` -| int (in seconds granularity) -| Optional transaction timeout. Only applicable to propagation REQUIRED or REQUIRES_NEW. +| `int` (in seconds of granularity) +| Optional transaction timeout. Applies only to propagation valeus of `REQUIRED` or `REQUIRES_NEW`. | `readOnly` -| boolean -| Read/write vs. read-only transaction. Only applicable to REQUIRED or REQUIRES_NEW. +| `boolean` +| Read-write versus read-only transaction. Only applicable to valeus of `REQUIRED` or `REQUIRES_NEW`. | `rollbackFor` | Array of `Class` objects, which must be derived from `Throwable.` -| Optional array of exception classes that __must__ cause rollback. +| Optional array of exception classes that must cause rollback. | `rollbackForClassName` -| Array of class names. Classes must be derived from `Throwable.` -| Optional array of names of exception classes that __must__ cause rollback. +| Array of class names. The classes must be derived from `Throwable.` +| Optional array of names of exception classes that must cause rollback. | `noRollbackFor` | Array of `Class` objects, which must be derived from `Throwable.` -| Optional array of exception classes that __must not__ cause rollback. +| Optional array of exception classes that must not cause rollback. | `noRollbackForClassName` | Array of `String` class names, which must be derived from `Throwable.` -| Optional array of names of exception classes that __must not__ cause rollback. +| Optional array of names of exception classes that must not cause rollback. |=== -Currently you cannot have explicit control over the name of a transaction, where 'name' -means the transaction name that will be shown in a transaction monitor, if applicable +Currently, you cannot have explicit control over the name of a transaction, where 'name' +means the transaction name that appears in a transaction monitor, if applicable (for example, WebLogic's transaction monitor), and in logging output. For declarative -transactions, the transaction name is always the fully-qualified class name + "." -+ method name of the transactionally-advised class. For example, if the +transactions, the transaction name is always the fully-qualified class name + `.` ++ the method name of the transactionally advised class. For example, if the `handlePayment(..)` method of the `BusinessService` class started a transaction, the -name of the transaction would be: `com.foo.BusinessService.handlePayment`. +name of the transaction would be: `com.example.BusinessService.handlePayment`. + + [[tx-multiple-tx-mgrs-with-attransactional]] -===== Multiple Transaction Managers with @Transactional +===== Multiple Transaction Managers with `@Transactional` -Most Spring applications only need a single transaction manager, but there may be +Most Spring applications need only a single transaction manager, but there may be situations where you want multiple independent transaction managers in a single -application. The value attribute of the `@Transactional` annotation can be used to +application. You can use the `value` attribute of the `@Transactional` annotation to optionally specify the identity of the `PlatformTransactionManager` to be used. This can either be the bean name or the qualifier value of the transaction manager bean. For -example, using the qualifier notation, the following Java code +example, using the qualifier notation, you can combine the following Java code with the +following transaction manager bean declarations in the application context: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1365,10 +1381,11 @@ example, using the qualifier notation, the following Java code public void doSomething() { ... } } ---- +==== -could be combined with the following transaction manager bean declarations in the -application context. +The following listing shows the bean declarations: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -1384,20 +1401,24 @@ application context. ---- +==== + +In this case, the two methods on `TransactionalService` run under separate +transaction managers, differentiated by the `order` and `account` qualifiers. The +default `` target bean name, `transactionManager`, is still +used if no specifically qualified `PlatformTransactionManager` bean is found. + -In this case, the two methods on `TransactionalService` will run under separate -transaction managers, differentiated by the "order" and "account" qualifiers. The -default `` target bean name `transactionManager` will still be -used if no specifically qualified PlatformTransactionManager bean is found. [[tx-custom-attributes]] -===== Custom shortcut annotations +===== Custom Shortcut Annotations -If you find you are repeatedly using the same attributes with `@Transactional` on many -different methods, then <> allows -you to define custom shortcut annotations for your specific use cases. For example, -defining the following annotations +If you find you repeatedly use the same attributes with `@Transactional` on many +different methods, <> lets +you define custom shortcut annotations for your specific use cases. For example, consider +the following annotation definitions: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1413,9 +1434,11 @@ defining the following annotations public @interface AccountTx { } ---- +==== -allows us to write the example from the previous section as +The preceding annotations lets us write the example from the previous section as follows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1428,115 +1451,111 @@ allows us to write the example from the previous section as public void doSomething() { ... } } ---- +==== + +In the preceding example, we used the syntax to define the transaction manager qualifier, but we could also +have included propagation behavior, rollback rules, timeouts, and other features. -Here we have used the syntax to define the transaction manager qualifier, but could also -have included propagation behavior, rollback rules, timeouts etc. [[tx-propagation]] -==== Transaction propagation +==== Transaction Propagation -This section describes some semantics of transaction propagation in Spring. Please note -that this section is not an introduction to transaction propagation proper; rather it +This section describes some semantics of transaction propagation in Spring. Note +that this section is not an introduction to transaction propagation proper. Rather, it details some of the semantics regarding transaction propagation in Spring. -In Spring-managed transactions, be aware of the difference between __physical__ and -__logical__ transactions, and how the propagation setting applies to this difference. +In Spring-managed transactions, be aware of the difference between physical and +logical transactions, and how the propagation setting applies to this difference. + + [[tx-propagation-required]] -===== Required +===== Understanding `PROPAGATION_REQUIRED` image::images/tx_prop_required.png[] -PROPAGATION_REQUIRED - -`PROPAGATION_REQUIRED` enforces a physical transaction: either locally for the current -scope if no transaction exists yet, or participating in an existing 'outer' transaction +`PROPAGATION_REQUIRED` enforces a physical transaction, either locally for the current +scope if no transaction exists yet or participating in an existing 'outer' transaction defined for a larger scope. This is a fine default in common call stack arrangements -within the same thread, e.g. a service facade delegating to several repository methods -where all the underlying resources have to participate in the service-level transaction. - -[NOTE] -==== -By default, a participating transaction will join the characteristics of the outer scope, -silently ignoring the local isolation level, timeout value or read-only flag (if any). -Consider switching the "validateExistingTransactions" flag to "true" on your transaction -manager if you'd like isolation level declarations to get rejected when participating in -an existing transaction with a different isolation level. This non-lenient mode will also -reject read-only mismatches, i.e. an inner read-write transaction trying to participate -in a read-only outer scope. -==== - -When the propagation setting is `PROPAGATION_REQUIRED`, a __logical__ transaction scope +within the same thread (for example, a service facade that delegates to several repository methods +where all the underlying resources have to participate in the service-level transaction). + +NOTE: By default, a participating transaction joins the characteristics of the outer scope, +silently ignoring the local isolation level, timeout value, or read-only flag (if any). +Consider switching the `validateExistingTransactions` flag to `true` on your transaction +manager if you want isolation level declarations to be rejected when participating in +an existing transaction with a different isolation level. This non-lenient mode also +rejects read-only mismatches (that is, an inner read-write transaction that tries to participate +in a read-only outer scope). + +When the propagation setting is `PROPAGATION_REQUIRED`, a logical transaction scope is created for each method upon which the setting is applied. Each such logical transaction scope can determine rollback-only status individually, with an outer transaction scope being logically independent from the inner transaction scope. -Of course, in case of standard `PROPAGATION_REQUIRED` behavior, all these scopes will be +In the case of standard `PROPAGATION_REQUIRED` behavior, all these scopes are mapped to the same physical transaction. So a rollback-only marker set in the inner -transaction scope does affect the outer transaction's chance to actually commit (as you -would expect it to). +transaction scope does affect the outer transaction's chance to actually commit. However, in the case where an inner transaction scope sets the rollback-only marker, the -outer transaction has not decided on the rollback itself, and so the rollback (silently +outer transaction has not decided on the rollback itself, so the rollback (silently triggered by the inner transaction scope) is unexpected. A corresponding -`UnexpectedRollbackException` is thrown at that point. This is __expected behavior__ so +`UnexpectedRollbackException` is thrown at that point. This is expected behavior so that the caller of a transaction can never be misled to assume that a commit was -performed when it really was not. So if an inner transaction (of which the outer caller +performed when it really was not. So, if an inner transaction (of which the outer caller is not aware) silently marks a transaction as rollback-only, the outer caller still calls commit. The outer caller needs to receive an `UnexpectedRollbackException` to indicate clearly that a rollback was performed instead. + + [[tx-propagation-requires_new]] -===== RequiresNew +===== Understanding `PROPAGATION_REQUIRES_NEW` image::images/tx_prop_requires_new.png[] -PROPAGATION_REQUIRES_NEW - `PROPAGATION_REQUIRES_NEW`, in contrast to `PROPAGATION_REQUIRED`, always uses an -__independent__ physical transaction for each affected transaction scope, never +independent physical transaction for each affected transaction scope, never participating in an existing transaction for an outer scope. In such an arrangement, -the underlying resource transactions are different and hence can commit or roll back +the underlying resource transactions are different and, hence, can commit or roll back independently, with an outer transaction not affected by an inner transaction's rollback -status, and with an inner transaction's locks released immediately after its completion. -Such an independent inner transaction may also declare its own isolation level, timeout -and read-only settings, never inheriting an outer transaction's characteristics. +status and with an inner transaction's locks released immediately after its completion. +Such an independent inner transaction can also declare its own isolation level, timeout, +and read-only settings and not inherit an outer transaction's characteristics. + + [[tx-propagation-nested]] -===== Nested +===== Understanding `PROPAGATION_NESTED` -`PROPAGATION_NESTED` uses a __single__ physical transaction with multiple savepoints -that it can roll back to. Such partial rollbacks allow an inner transaction scope to -trigger a rollback __for its scope__, with the outer transaction being able to continue +`PROPAGATION_NESTED` uses a single physical transaction with multiple savepoints +that it can roll back to. Such partial rollbacks let an inner transaction scope +trigger a rollback for its scope, with the outer transaction being able to continue the physical transaction despite some operations having been rolled back. This setting -is typically mapped onto JDBC savepoints, so will only work with JDBC resource -transactions. See Spring's `DataSourceTransactionManager`. +is typically mapped onto JDBC savepoints, so it works only with JDBC resource +transactions. See Spring's {api-spring-framework}/jdbc/datasource/DataSourceTransactionManager.html[`DataSourceTransactionManager`]. + [[transaction-declarative-applying-more-than-just-tx-advice]] -==== Advising transactional operations +==== Advising Transactional Operations -Suppose you want to execute __both__ transactional __and__ some basic profiling advice. +Suppose you want to execute both transactional operations and some basic profiling advice. How do you effect this in the context of ``? When you invoke the `updateFoo(Foo)` method, you want to see the following actions: -* Configured profiling aspect starts up. -* Transactional advice executes. -* Method on the advised object executes. -* Transaction commits. -* Profiling aspect reports exact duration of the whole transactional method invocation. +* The configured profiling aspect starts. +* The transactional advice executes. +* The method on the advised object executes. +* The transaction commits. +* The profiling aspect reports the exact duration of the whole transactional method invocation. -[NOTE] -==== -This chapter is not concerned with explaining AOP in any great detail (except as it -applies to transactions). See <> for detailed coverage of the following AOP +NOTE: This chapter is not concerned with explaining AOP in any great detail (except as it +applies to transactions). See <> for detailed coverage of the AOP configuration and AOP in general. -==== -Here is the code for a simple profiling aspect discussed above. The ordering of advice -is controlled through the `Ordered` interface. For full details on advice ordering, see -<>. +The following code shows the simple profiling aspect discussed earlier: . [source,java,indent=0] [subs="verbatim,quotes"] @@ -1576,6 +1595,14 @@ is controlled through the `Ordered` interface. For full details on advice orderi } ---- +The ordering of advice +is controlled through the `Ordered` interface. For full details on advice ordering, see +<>. + +The following configuration creates a `fooService` bean that has profiling and +transactional aspects applied to it in the desired order: + +==== [source,xml,indent=0] [subs="verbatim"] ---- @@ -1624,14 +1651,15 @@ is controlled through the `Ordered` interface. For full details on advice orderi ---- +==== -The result of the above configuration is a `fooService` bean that has profiling and -transactional aspects applied to it __in the desired order__. You configure any number +You can configure any number of additional aspects in similar fashion. -The following example effects the same setup as above, but uses the purely XML -declarative approach. +The following example creates the same setup as the previous two examples but uses the purely XML +declarative approach: +==== [source,xml,indent=0] [subs="verbatim"] ---- @@ -1682,39 +1710,42 @@ declarative approach. ---- +==== -The result of the above configuration will be a `fooService` bean that has profiling and -transactional aspects applied to it __in that order__. If you want the profiling advice -to execute __after__ the transactional advice on the way in, and __before__ the -transactional advice on the way out, then you simply swap the value of the profiling +The result of the preceding configuration is a `fooService` bean that has profiling and +transactional aspects applied to it in that order. If you want the profiling advice +to execute after the transactional advice on the way in and before the +transactional advice on the way out, you can swap the value of the profiling aspect bean's `order` property so that it is higher than the transactional advice's order value. You configure additional aspects in similar fashion. + [[transaction-declarative-aspectj]] -==== Using @Transactional with AspectJ +==== Using `@Transactional` with AspectJ -It is also possible to use the Spring Framework's `@Transactional` support outside of a -Spring container by means of an AspectJ aspect. To do so, you first annotate your +You can also use the Spring Framework's `@Transactional` support outside of a +Spring container by means of an AspectJ aspect. To do so, first annotate your classes (and optionally your classes' methods) with the `@Transactional` annotation, and -then you link (weave) your application with the +then link (weave) your application with the `org.springframework.transaction.aspectj.AnnotationTransactionAspect` defined in the -`spring-aspects.jar` file. The aspect must also be configured with a transaction -manager. You can of course use the Spring Framework's IoC container to take care of +`spring-aspects.jar` file. You must also configure The aspect with a transaction +manager. You can use the Spring Framework's IoC container to take care of dependency-injecting the aspect. The simplest way to configure the transaction management aspect is to use the `` element and specify the `mode` attribute to `aspectj` as described in <>. Because -we're focusing here on applications running outside of a Spring container, we'll show +we focus here on applications that run outside of a Spring container, we show you how to do it programmatically. -[NOTE] -==== -Prior to continuing, you may want to read <> and +NOTE: Prior to continuing, you may want to read <> and <> respectively. -==== +The following example shows how to create a transaction manager and configure the +`AnnotationTransactionAspect` to use it: + +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1724,66 +1755,63 @@ Prior to continuing, you may want to read < // configure the AnnotationTransactionAspect to use it; this must be done before executing any transactional methods AnnotationTransactionAspect.aspectOf().setTransactionManager(txManager); ---- - -[NOTE] -==== -When using this aspect, you must annotate the __implementation__ class (and/or methods -within that class), __not__ the interface (if any) that the class implements. AspectJ -follows Java's rule that annotations on interfaces are __not inherited__. ==== +NOTE: When you use this aspect, you must annotate the implementation class (or the methods +within that class or both), not the interface (if any) that the class implements. AspectJ +follows Java's rule that annotations on interfaces are not inherited. + The `@Transactional` annotation on a class specifies the default transaction semantics for the execution of any public method in the class. The `@Transactional` annotation on a method within the class overrides the default -transaction semantics given by the class annotation (if present). Any method may be -annotated, regardless of visibility. +transaction semantics given by the class annotation (if present). You can annotation any method, +regardless of visibility. -To weave your applications with the `AnnotationTransactionAspect` you must either build +To weave your applications with the `AnnotationTransactionAspect`, you must either build your application with AspectJ (see the http://www.eclipse.org/aspectj/doc/released/devguide/index.html[AspectJ Development -Guide]) or use load-time weaving. See <> for a discussion of load-time weaving with AspectJ. [[transaction-programmatic]] -=== Programmatic transaction management +=== Programmatic Transaction Management -The Spring Framework provides two means of programmatic transaction management: +The Spring Framework provides two means of programmatic transaction management, by using: -* Using the `TransactionTemplate`. -* Using a `PlatformTransactionManager` implementation directly. +* The `TransactionTemplate`. +* A `PlatformTransactionManager` implementation directly. The Spring team generally recommends the `TransactionTemplate` for programmatic transaction management. The second approach is similar to using the JTA `UserTransaction` API, although exception handling is less cumbersome. + [[tx-prog-template]] -==== Using the TransactionTemplate +==== Using the `TransactionTemplate` -The `TransactionTemplate` adopts the same approach as other Spring __templates__ such as -the `JdbcTemplate`. It uses a callback approach, to free application code from having to -do the boilerplate acquisition and release of transactional resources, and results in -code that is intention driven, in that the code that is written focuses solely on what -the developer wants to do. +The `TransactionTemplate` adopts the same approach as other Spring templates, such as +the `JdbcTemplate`. It uses a callback approach (to free application code from having to +do the boilerplate acquisition and release transactional resources) and results in +code that is intention driven, in that your code focuses solely on what +you want to do. -[NOTE] -==== -As you will see in the examples that follow, using the `TransactionTemplate` absolutely +NOTE: As the examples that follow show, using the `TransactionTemplate` absolutely couples you to Spring's transaction infrastructure and APIs. Whether or not programmatic transaction management is suitable for your development needs is a decision that you -will have to make yourself. -==== +have to make yourself. -Application code that must execute in a transactional context, and that will use the -`TransactionTemplate` explicitly, looks like the following. You, as an application -developer, write a `TransactionCallback` implementation (typically expressed as an +Application code that must execute in a transactional context and that explicitly uses the +`TransactionTemplate` resembles the next example. You, as an application +developer, can write a `TransactionCallback` implementation (typically expressed as an anonymous inner class) that contains the code that you need to execute in the context of -a transaction. You then pass an instance of your custom `TransactionCallback` to the -`execute(..)` method exposed on the `TransactionTemplate`. +a transaction. You can then pass an instance of your custom `TransactionCallback` to the +`execute(..)` method exposed on the `TransactionTemplate`. The following example shows how to do so: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1808,10 +1836,12 @@ a transaction. You then pass an instance of your custom `TransactionCallback` to } } ---- +==== -If there is no return value, use the convenient `TransactionCallbackWithoutResult` class -with an anonymous class as follows: +If there is no return value, you can use the convenient `TransactionCallbackWithoutResult` class +with an anonymous class, as follows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1822,10 +1852,12 @@ with an anonymous class as follows: } }); ---- +==== Code within the callback can roll the transaction back by calling the -`setRollbackOnly()` method on the supplied `TransactionStatus` object: +`setRollbackOnly()` method on the supplied `TransactionStatus` object, as follows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1841,17 +1873,21 @@ Code within the callback can roll the transaction back by calling the } }); ---- +==== + + [[tx-prog-template-settings]] -===== Specifying transaction settings +===== Specifying Transaction Settings -You can specify transaction settings such as the propagation mode, the isolation level, -the timeout, and so forth on the `TransactionTemplate` either programmatically or in -configuration. `TransactionTemplate` instances by default have the +You can specify transaction settings (such as the propagation mode, the isolation level, +the timeout, and so forth) on the `TransactionTemplate` either programmatically or in +configuration. By default, `TransactionTemplate` instances have the <>. The following example shows the programmatic customization of the transactional settings for a specific `TransactionTemplate:` +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1869,11 +1905,12 @@ a specific `TransactionTemplate:` } } ---- +==== The following example defines a `TransactionTemplate` with some custom transactional -settings, using Spring XML configuration. The `sharedTransactionTemplate` can then be -injected into as many services as are required. +settings by using Spring XML configuration: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -1883,29 +1920,35 @@ injected into as many services as are required. " ---- +==== + +You can then inject the `sharedTransactionTemplate` +into as many services as are required. -Finally, instances of the `TransactionTemplate` class are threadsafe, in that instances -do not maintain any conversational state. `TransactionTemplate` instances __do__ however -maintain configuration state, so while a number of classes may share a single instance +Finally, instances of the `TransactionTemplate` class are thread-safe, in that instances +do not maintain any conversational state. `TransactionTemplate` instances do, however, +maintain configuration state. So, while a number of classes may share a single instance of a `TransactionTemplate`, if a class needs to use a `TransactionTemplate` with -different settings (for example, a different isolation level), then you need to create +different settings (for example, a different isolation level), you need to create two distinct `TransactionTemplate` instances. + [[transaction-programmatic-ptm]] -==== Using the PlatformTransactionManager +==== Using the `PlatformTransactionManager` You can also use the `org.springframework.transaction.PlatformTransactionManager` -directly to manage your transaction. Simply pass the implementation of the -`PlatformTransactionManager` you are using to your bean through a bean reference. Then, -using the `TransactionDefinition` and `TransactionStatus` objects you can initiate -transactions, roll back, and commit. +directly to manage your transaction. To do so, pass the implementation of the +`PlatformTransactionManager` you use to your bean through a bean reference. Then, +by using the `TransactionDefinition` and `TransactionStatus` objects, you can initiate +transactions, roll back, and commit. The following example shows how to do so: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- DefaultTransactionDefinition def = new DefaultTransactionDefinition(); - // explicitly setting the transaction name is something that can only be done programmatically + // explicitly setting the transaction name is something that can be done only programmatically def.setName("SomeTxName"); def.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED); @@ -1919,44 +1962,47 @@ transactions, roll back, and commit. } txManager.commit(status); ---- +==== [[tx-decl-vs-prog]] -=== Choosing between programmatic and declarative transaction management +=== Choosing Between Programmatic and Declarative Transaction Management Programmatic transaction management is usually a good idea only if you have a small number of transactional operations. For example, if you have a web application that -require transactions only for certain update operations, you may not want to set up -transactional proxies using Spring or any other technology. In this case, using the -`TransactionTemplate` __may__ be a good approach. Being able to set the transaction name -explicitly is also something that can only be done using the programmatic approach to +requires transactions only for certain update operations, you may not want to set up +transactional proxies by using Spring or any other technology. In this case, using the +`TransactionTemplate` may be a good approach. Being able to set the transaction name +explicitly is also something that can be done only by using the programmatic approach to transaction management. On the other hand, if your application has numerous transactional operations, declarative transaction management is usually worthwhile. It keeps transaction -management out of business logic, and is not difficult to configure. When using the +management out of business logic and is not difficult to configure. When using the Spring Framework, rather than EJB CMT, the configuration cost of declarative transaction management is greatly reduced. [[transaction-event]] -=== Transaction bound event +=== Transaction-bound Events As of Spring 4.2, the listener of an event can be bound to a phase of the transaction. The -typical example is to handle the event when the transaction has completed successfully: this -allows events to be used with more flexibility when the outcome of the current transaction +typical example is to handle the event when the transaction has completed successfully. Doing so +lets events be used with more flexibility when the outcome of the current transaction actually matters to the listener. -Registering a regular event listener is done via the `@EventListener` annotation. If you need -to bind it to the transaction use `@TransactionalEventListener`. When you do so, the listener -will be bound to the commit phase of the transaction by default. +You can register a regular event listener by using the `@EventListener` annotation. If you need +to bind it to the transaction, use `@TransactionalEventListener`. When you do so, the listener +is bound to the commit phase of the transaction by default. -Let's take an example to illustrate this concept. Assume that a component publishes an order -created event and we want to define a listener that should only handle that event once the -transaction in which it has been published has committed successfully: +The next example shows this concept. Assume that a component publishes an order-created +event and that we want to define a listener that should only handle that event once the +transaction in which it has been published has committed successfully. The following +example sets up such an event listener: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -1969,14 +2015,15 @@ transaction in which it has been published has committed successfully: } } ---- +==== -The `TransactionalEventListener` annotation exposes a `phase` attribute that allows us to customize -which phase of the transaction the listener should be bound to. The valid phases are `BEFORE_COMMIT`, -`AFTER_COMMIT` (default), `AFTER_ROLLBACK` and `AFTER_COMPLETION` that aggregates the transaction +The `@TransactionalEventListener` annotation exposes a `phase` attribute that lets you customize +the phase of the transaction to which the listener should be bound. The valid phases are `BEFORE_COMMIT`, +`AFTER_COMMIT` (default), `AFTER_ROLLBACK`, and `AFTER_COMPLETION` that aggregates the transaction completion (be it a commit or a rollback). -If no transaction is running, the listener is not invoked at all since we can't honor the required -semantics. It is however possible to override that behaviour by setting the `fallbackExecution` attribute +If no transaction is running, the listener is not invoked at all, since we cannot honor the required +semantics. You can, however, override that behavior by setting the `fallbackExecution` attribute of the annotation to `true`. @@ -1984,82 +2031,87 @@ of the annotation to `true`. [[transaction-application-server-integration]] === Application server-specific integration -Spring's transaction abstraction generally is application server agnostic. Additionally, -Spring's `JtaTransactionManager` class, which can optionally perform a JNDI lookup for -the JTA `UserTransaction` and `TransactionManager` objects, autodetects the location for +Spring's transaction abstraction is generally application server-agnostic. Additionally, +Spring's `JtaTransactionManager` class (which can optionally perform a JNDI lookup for +the JTA `UserTransaction` and `TransactionManager` objects) autodetects the location for the latter object, which varies by application server. Having access to the JTA -`TransactionManager` allows for enhanced transaction semantics, in particular supporting -transaction suspension. See the `JtaTransactionManager` javadocs for details. +`TransactionManager` allows for enhanced transaction semantics -- in particular, supporting +transaction suspension. See the {api-spring-framework}/transaction/jta/JtaTransactionManager.html[`JtaTransactionManager` Javadoc] for details. Spring's `JtaTransactionManager` is the standard choice to run on Java EE application -servers, and is known to work on all common servers. Advanced functionality such as -transaction suspension works on many servers as well -- including GlassFish, JBoss and -Geronimo -- without any special configuration required. However, for fully supported -transaction suspension and further advanced integration, Spring ships special adapters +servers and is known to work on all common servers. Advanced functionality, such as +transaction suspension, works on many servers as well (including GlassFish, JBoss and +Geronimo) without any special configuration required. However, for fully supported +transaction suspension and further advanced integration, Spring includes special adapters for WebLogic Server and WebSphere. These adapters are discussed in the following sections. -__For standard scenarios, including WebLogic Server and WebSphere, consider using the -convenient `` configuration element.__ When configured, +For standard scenarios, including WebLogic Server and WebSphere, consider using the +convenient `` configuration element. When configured, this element automatically detects the underlying server and chooses the best -transaction manager available for the platform. This means that you won't have to -configure server-specific adapter classes (as discussed in the following sections) -explicitly; rather, they are chosen automatically, with the standard -`JtaTransactionManager` as default fallback. +transaction manager available for the platform. This means that you need not explicitly +configure server-specific adapter classes (as discussed in the following sections). +Rather, they are chosen automatically, with the standard +`JtaTransactionManager` as the default fallback. + [[transaction-application-server-integration-websphere]] ==== IBM WebSphere On WebSphere 6.1.0.9 and above, the recommended Spring JTA transaction manager to use is -`WebSphereUowTransactionManager`. This special adapter leverages IBM's `UOWManager` API, +`WebSphereUowTransactionManager`. This special adapter uses IBM's `UOWManager` API, which is available in WebSphere Application Server 6.1.0.9 and later. With this adapter, -Spring-driven transaction suspension (suspend/resume as initiated by +Spring-driven transaction suspension (suspend and resume as initiated by `PROPAGATION_REQUIRES_NEW`) is officially supported by IBM. + [[transaction-application-server-integration-weblogic]] ==== Oracle WebLogic Server -On WebLogic Server 9.0 or above, you typically would use the +On WebLogic Server 9.0 or above, you would typically use the `WebLogicJtaTransactionManager` instead of the stock `JtaTransactionManager` class. This special WebLogic-specific subclass of the normal `JtaTransactionManager` supports the full power of Spring's transaction definitions in a WebLogic-managed transaction -environment, beyond standard JTA semantics: Features include transaction names, +environment, beyond standard JTA semantics. Features include transaction names, per-transaction isolation levels, and proper resuming of transactions in all cases. [[transaction-solutions-to-common-problems]] -=== Solutions to common problems +=== Solutions to Common Problems + +This section describes solutions to some commmon problems. + [[transaction-solutions-to-common-problems-wrong-ptm]] -==== Use of the wrong transaction manager for a specific DataSource +==== Using the Wrong Transaction Manager for a Specific `DataSource` -Use the __correct__ `PlatformTransactionManager` implementation based on your choice of +Use the correct `PlatformTransactionManager` implementation based on your choice of transactional technologies and requirements. Used properly, the Spring Framework merely -provides a straightforward and portable abstraction. If you are using global -transactions, you __must__ use the +provides a straightforward and portable abstraction. If you use global +transactions, you must use the `org.springframework.transaction.jta.JtaTransactionManager` class (or an <> of -it) for all your transactional operations. Otherwise the transaction infrastructure -attempts to perform local transactions on resources such as container `DataSource` +it) for all your transactional operations. Otherwise, the transaction infrastructure +tries to perform local transactions on such resources as container `DataSource` instances. Such local transactions do not make sense, and a good application server treats them as errors. [[transaction-resources]] -=== Further resources +=== Further Resources -For more information about the Spring Framework's transaction support: +For more information about the Spring Framework's transaction support, see: * http://www.javaworld.com/javaworld/jw-01-2009/jw-01-spring-transactions.html[Distributed transactions in Spring, with and without XA] is a JavaWorld presentation in which Spring's David Syer guides you through seven patterns for distributed transactions in Spring applications, three of them with XA and four without. -* http://www.infoq.com/minibooks/JTDS[Java Transaction Design Strategies] is a book +* http://www.infoq.com/minibooks/JTDS[_Java Transaction Design Strategies_] is a book available from http://www.infoq.com/[InfoQ] that provides a well-paced introduction to transactions in Java. It also includes side-by-side examples of how to configure and use transactions with both the Spring Framework and EJB3. @@ -2068,49 +2120,44 @@ For more information about the Spring Framework's transaction support: [[dao]] -== DAO support - - - -[[dao-introduction]] -=== Introduction +== DAO Support The Data Access Object (DAO) support in Spring is aimed at making it easy to work with -data access technologies like JDBC, Hibernate or JPA in a consistent way. This -allows one to switch between the aforementioned persistence technologies fairly easily -and it also allows one to code without worrying about catching exceptions that are +data access technologies (such as JDBC, Hibernate, or JPA) in a consistent way. This +lets you switch between the aforementioned persistence technologies fairly easily, +and it also lets you code without worrying about catching exceptions that are specific to each technology. [[dao-exceptions]] -=== Consistent exception hierarchy - -Spring provides a convenient translation from technology-specific exceptions like -`SQLException` to its own exception class hierarchy with the `DataAccessException` as -the root exception. These exceptions wrap the original exception so there is never any -risk that one might lose any information as to what might have gone wrong. - -In addition to JDBC exceptions, Spring can also wrap Hibernate-specific exceptions, -converting them to a set of focused runtime exceptions (the same is true for JPA -exceptions). This allows one to handle most persistence exceptions, which are -non-recoverable, only in the appropriate layers, without having annoying boilerplate -catch-and-throw blocks and exception declarations in one's DAOs. (One can still trap -and handle exceptions anywhere one needs to though.) As mentioned above, JDBC +=== Consistent Exception Hierarchy + +Spring provides a convenient translation from technology-specific exceptions,, such as +`SQLException` to its own exception class hierarchy, which has `DataAccessException` as +the root exception. These exceptions wrap the original exception so that there is never any +risk that you might lose any information about what might have gone wrong. + +In addition to JDBC exceptions, Spring can also wrap JPA- and Hibernate-specific exceptions, +converting them to a set of focused runtime exceptions. +This lets you handle most non-recoverablepersistence exceptions +in only the appropriate layers, without having annoying boilerplate +catch-and-throw blocks and exception declarations in your DAOs. (You can still trap +and handle exceptions anywhere you need to though.) As mentioned above, JDBC exceptions (including database-specific dialects) are also converted to the same -hierarchy, meaning that one can perform some operations with JDBC within a consistent +hierarchy, meaning that you can perform some operations with JDBC within a consistent programming model. -The above holds true for the various template classes in Springs support for various ORM -frameworks. If one uses the interceptor-based classes then the application must care -about handling `HibernateExceptions` and `PersistenceExceptions` itself, preferably via -delegating to `SessionFactoryUtils`' `convertHibernateAccessException(..)` or -`convertJpaAccessException()` methods respectively. These methods convert the exceptions -to ones that are compatible with the exceptions in the `org.springframework.dao` -exception hierarchy. As `PersistenceExceptions` are unchecked, they can simply get -thrown too, sacrificing generic DAO abstraction in terms of exceptions though. +The preceding discussion holds true for the various template classes in Spring's support for various ORM +frameworks. If you use the interceptor-based classes, the application must care +about handling `HibernateExceptions` and `PersistenceExceptions` itself, preferably by +delegating to the `convertHibernateAccessException(..)` or +`convertJpaAccessException()` methods, respectively, of `SessionFactoryUtils`. These methods convert the exceptions +to exceptions that are compatible with the exceptions in the `org.springframework.dao` +exception hierarchy. As `PersistenceExceptions` are unchecked, they can get +thrown, too (sacrificing generic DAO abstraction in terms of exceptions, though). -The exception hierarchy that Spring provides can be seen below. (Please note that the +The following image shows the exception hierarchy that Spring provides. (Note that the class hierarchy detailed in the image shows only a subset of the entire `DataAccessException` hierarchy.) @@ -2119,29 +2166,34 @@ image::images/DataAccessException.png[] [[dao-annotations]] -=== Annotations used for configuring DAO or Repository classes +=== Annotations Used to Configure DAO or Repository Classes The best way to guarantee that your Data Access Objects (DAOs) or repositories provide exception translation is to use the `@Repository` annotation. This annotation also -allows the component scanning support to find and configure your DAOs and repositories -without having to provide XML configuration entries for them. +lets the component scanning support find and configure your DAOs and repositories +without having to provide XML configuration entries for them. The following example shows +how to use the `@Repository` annotation: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- - **@Repository** + @Repository <1> public class SomeMovieFinder implements MovieFinder { // ... } ---- +<1> The `@Repository` annotation. +==== -Any DAO or repository implementation will need to access to a persistence resource, -depending on the persistence technology used; for example, a JDBC-based repository will -need access to a JDBC `DataSource`; a JPA-based repository will need access to an +Any DAO or repository implementation needs access to a persistence resource, +depending on the persistence technology used. For example, a JDBC-based repository +needs access to a JDBC `DataSource`, and a JPA-based repository needs access to an `EntityManager`. The easiest way to accomplish this is to have this resource dependency -injected using one of the `@Autowired,`, `@Inject`, `@Resource` or `@PersistenceContext` -annotations. Here is an example for a JPA repository: +injected by using one of the `@Autowired,`, `@Inject`, `@Resource` or `@PersistenceContext` +annotations. The following example works for a JPA repository: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2155,9 +2207,12 @@ annotations. Here is an example for a JPA repository: } ---- +==== -If you are using the classic Hibernate APIs than you can inject the SessionFactory: +If you use the classic Hibernate APIs, you can inject `SessionFactory`, as the following +example shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2175,12 +2230,14 @@ If you are using the classic Hibernate APIs than you can inject the SessionFacto } ---- +==== -Last example we will show here is for typical JDBC support. You would have the -`DataSource` injected into an initialization method where you would create a -`JdbcTemplate` and other data access support classes like `SimpleJdbcCall` etc using -this `DataSource`. +The last example we show here is for typical JDBC support. You could have the +`DataSource` injected into an initialization method, where you would create a +`JdbcTemplate` and other data access support classes (such as `SimpleJdbcCall` and others) by using +this `DataSource`. The following example autowires a `DataSource`: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2198,28 +2255,19 @@ this `DataSource`. } ---- - -[NOTE] -==== -Please see the specific coverage of each persistence technology for details on how to -configure the application context to take advantage of these annotations. ==== +NOTE: See the specific coverage of each persistence technology for details on how to +configure the application context to take advantage of these annotations. [[jdbc]] -== Data access with JDBC - +== Data Access with JDBC - -[[jdbc-introduction]] -=== Introduction to Spring Framework's JDBC support - -The value-add provided by the Spring Framework JDBC abstraction is perhaps best shown by -the sequence of actions outlined in the table below. The table shows what actions Spring -will take care of and which actions are the responsibility of you, the application -developer. +The value provided by the Spring Framework JDBC abstraction is perhaps best shown by +the sequence of actions outlined in the following table below. The table shows which actions Spring +takes care of and which actions are your responsibility. [[jdbc-who-does-what]] .Spring JDBC - who does what? @@ -2262,51 +2310,52 @@ developer. | X | -| Close the connection, statement and resultset. +| Close the connection, the statement, and the resultset. | X | |=== The Spring Framework takes care of all the low-level details that can make JDBC such a -tedious API to develop with. +tedious API. + [[jdbc-choose-style]] -==== Choosing an approach for JDBC database access +==== Choosing an Approach for JDBC Database Access You can choose among several approaches to form the basis for your JDBC database access. -In addition to three flavors of the JdbcTemplate, a new SimpleJdbcInsert and -SimplejdbcCall approach optimizes database metadata, and the RDBMS Object style takes a +In addition to three flavors of `JdbcTemplate`, a new `SimpleJdbcInsert` and +`SimpleJdbcCall` approach optimizes database metadata, and the RDBMS Object style takes a more object-oriented approach similar to that of JDO Query design. Once you start using one of these approaches, you can still mix and match to include a feature from a different approach. All approaches require a JDBC 2.0-compliant driver, and some advanced features require a JDBC 3.0 driver. -* __JdbcTemplate__ is the classic Spring JDBC approach and the most popular. This - "lowest level" approach and all others use a JdbcTemplate under the covers. -* __NamedParameterJdbcTemplate__ wraps a `JdbcTemplate` to provide named parameters - instead of the traditional JDBC "?" placeholders. This approach provides better +* `JdbcTemplate` is the classic and most popular Spring JDBC approach. This + "`lowest-level`" approach and all others use a JdbcTemplate under the covers. +* `NamedParameterJdbcTemplate` wraps a `JdbcTemplate` to provide named parameters + instead of the traditional JDBC `?` placeholders. This approach provides better documentation and ease of use when you have multiple parameters for an SQL statement. -* __SimpleJdbcInsert and SimpleJdbcCall__ optimize database metadata to limit the amount - of necessary configuration. This approach simplifies coding so that you only need to - provide the name of the table or procedure and provide a map of parameters matching - the column names. This only works if the database provides adequate metadata. If the - database doesn't provide this metadata, you will have to provide explicit +* `SimpleJdbcInsert` and `SimpleJdbcCall` optimize database metadata to limit the amount + of necessary configuration. This approach simplifies coding so that you need to + provide only the name of the table or procedure and provide a map of parameters matching + the column names. This works only if the database provides adequate metadata. If the + database does not provide this metadata, you have to provide explicit configuration of the parameters. -* __RDBMS Objects including MappingSqlQuery, SqlUpdate and StoredProcedure__ requires - you to create reusable and thread-safe objects during initialization of your data - access layer. This approach is modeled after JDO Query wherein you define your query +* RDBMS objects, including `MappingSqlQuery`, `SqlUpdate` and `StoredProcedure`, require + you to create reusable and thread-safe objects during initialization of your data-access + layer. This approach is modeled after JDO Query, wherein you define your query string, declare parameters, and compile the query. Once you do that, execute methods - can be called multiple times with various parameter values passed in. + can be called multiple times with various parameter values. + [[jdbc-packages]] -==== Package hierarchy +==== Package Hierarchy -The Spring Framework's JDBC abstraction framework consists of four different packages, -namely `core`, `datasource`, `object`, and `support`. +The Spring Framework's JDBC abstraction framework consists of four different packages: -The `org.springframework.jdbc.core` package contains the `JdbcTemplate` class and its +* `core`: The `org.springframework.jdbc.core` package contains the `JdbcTemplate` class and its various callback interfaces, plus a variety of related classes. A subpackage named `org.springframework.jdbc.core.simple` contains the `SimpleJdbcInsert` and `SimpleJdbcCall` classes. Another subpackage named @@ -2314,98 +2363,118 @@ various callback interfaces, plus a variety of related classes. A subpackage nam class and the related support classes. See <>, <>, and <>. -The `org.springframework.jdbc.datasource` package contains a utility class for easy -`DataSource` access, and various simple `DataSource` implementations that can be used for +* `datasource`: The `org.springframework.jdbc.datasource` package contains a utility class for easy +`DataSource` access and various simple `DataSource` implementations that you can use for testing and running unmodified JDBC code outside of a Java EE container. A subpackage named `org.springfamework.jdbc.datasource.embedded` provides support for creating -embedded databases using Java database engines such as HSQL, H2, and Derby. See +embedded databases by using Java database engines, such as HSQL, H2, and Derby. See <> and <>. -The `org.springframework.jdbc.object` package contains classes that represent RDBMS +`object`: The `org.springframework.jdbc.object` package contains classes that represent RDBMS queries, updates, and stored procedures as thread-safe, reusable objects. See <>. This approach is modeled by JDO, although objects returned by queries -are naturally _disconnected_ from the database. This higher level of JDBC abstraction +are naturally disconnected from the database. This higher-level of JDBC abstraction depends on the lower-level abstraction in the `org.springframework.jdbc.core` package. -The `org.springframework.jdbc.support` package provides `SQLException` translation +`support`: The `org.springframework.jdbc.support` package provides `SQLException` translation functionality and some utility classes. Exceptions thrown during JDBC processing are translated to exceptions defined in the `org.springframework.dao` package. This means that code using the Spring JDBC abstraction layer does not need to implement JDBC or RDBMS-specific error handling. All translated exceptions are unchecked, which gives you -the option of catching the exceptions from which you can recover while allowing other -exceptions to be propagated to the caller. See <>. +the option of catching the exceptions from which you can recover while letting other +exceptions be propagated to the caller. See <>. [[jdbc-core]] -=== Using the JDBC core classes to control basic JDBC processing and error handling +=== Using the JDBC Core Classes to Control Basic JDBC Processing and Error Handling + +This section covers how to use the JDBC core classes to cotrol basic JDBC processing, +including error handling. It includes the following topics: + +* <> +* <> +* <> +* <> +* <> +* <> +* <> + [[jdbc-JdbcTemplate]] -==== JdbcTemplate +==== Using `JdbcTemplate` -The `JdbcTemplate` class is the central class in the JDBC core package. It handles the -creation and release of resources, which helps you avoid common errors such as +`JdbcTemplate` is the central class in the JDBC core package. It handles the +creation and release of resources, which helps you avoid common errors, such as forgetting to close the connection. It performs the basic tasks of the core JDBC -workflow such as statement creation and execution, leaving application code to provide -SQL and extract results. The `JdbcTemplate` class executes SQL queries, update -statements and stored procedure calls, performs iteration over ``ResultSet``s and -extraction of returned parameter values. It also catches JDBC exceptions and translates -them to the generic, more informative, exception hierarchy defined in the -`org.springframework.dao` package. - -When you use the `JdbcTemplate` for your code, you only need to implement callback -interfaces, giving them a clearly defined contract. The `PreparedStatementCreator` -callback interface creates a prepared statement given a `Connection` provided by this -class, providing SQL and any necessary parameters. The same is true for the +workflow (such as statement creation and execution), leaving application code to provide +SQL and extract results. The `JdbcTemplate` class: + +* Runs SQL queries +* Updates statements and stored procedure calls +* Performs iteration over `ResultSet` instances and extraction of returned parameter values. +* Catches JDBC exceptions and translates them to the generic, more informative, exception +hierarchy defined in the `org.springframework.dao` package. (See <>.) + +When you use the `JdbcTemplate` for your code, you need only to implement callback +interfaces, giving them a clearly defined contract. Given a `Connection` provided by the +`JdbcTemplate` class, the `PreparedStatementCreator` +callback interface creates a prepared statement, providing SQL and any necessary parameters. The same is true for the `CallableStatementCreator` interface, which creates callable statements. The `RowCallbackHandler` interface extracts values from each row of a `ResultSet`. -The `JdbcTemplate` can be used within a DAO implementation through direct instantiation -with a `DataSource` reference, or be configured in a Spring IoC container and given to +You can use `JdbcTemplate` within a DAO implementation through direct instantiation +with a `DataSource` reference, or you can configure it in a Spring IoC container and give it to DAOs as a bean reference. -[NOTE] -==== -The `DataSource` should always be configured as a bean in the Spring IoC container. In + +NOTE: The `DataSource` should always be configured as a bean in the Spring IoC container. In the first case the bean is given to the service directly; in the second case it is given to the prepared template. -==== All SQL issued by this class is logged at the `DEBUG` level under the category corresponding to the fully qualified class name of the template instance (typically -`JdbcTemplate`, but it may be different if you are using a custom subclass of the +`JdbcTemplate`, but it may be different if you use a custom subclass of the `JdbcTemplate` class). + [[jdbc-JdbcTemplate-examples]] ===== Examples of JdbcTemplate class usage This section provides some examples of `JdbcTemplate` class usage. These examples are -not an exhaustive list of all of the functionality exposed by the `JdbcTemplate`; see -the attendant javadocs for that. +not an exhaustive list of all of the functionality exposed by the `JdbcTemplate`. See +the attendant {api-spring-framework}/jdbc/core/JdbcTemplate.html[Javadoc] for that. + + [[jdbc-JdbcTemplate-examples-query]] -====== Querying (SELECT) +====== Querying (`SELECT`) -Here is a simple query for getting the number of rows in a relation: +The following query gets the number of rows in a relation: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- int rowCount = this.jdbcTemplate.queryForObject("select count(*) from t_actor", Integer.class); ---- +==== -A simple query using a bind variable: +The following query uses a bind variable: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- int countOfActorsNamedJoe = this.jdbcTemplate.queryForObject( "select count(*) from t_actor where first_name = ?", Integer.class, "Joe"); ---- +==== -Querying for a `String`: +The following query looks for a `String`: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2413,9 +2482,11 @@ Querying for a `String`: "select last_name from t_actor where id = ?", new Object[]{1212L}, String.class); ---- +==== -Querying and populating a __single__ domain object: +The following query finds and populates a single domain object: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2431,9 +2502,11 @@ Querying and populating a __single__ domain object: } }); ---- +==== -Querying and populating a number of domain objects: +The following query finds and populates a number of domain objects: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2448,13 +2521,15 @@ Querying and populating a number of domain objects: } }); ---- +==== If the last two snippets of code actually existed in the same application, it would make -sense to remove the duplication present in the two `RowMapper` anonymous inner classes, -and extract them out into a single class (typically a `static` nested class) that can +sense to remove the duplication present in the two `RowMapper` anonymous inner classes +and extract them out into a single class (typically a `static` nested class) that could then be referenced by DAO methods as needed. For example, it may be better to write the -last code snippet as follows: +preceding code snippet as follows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2472,13 +2547,19 @@ last code snippet as follows: } } ---- +==== + + [[jdbc-JdbcTemplate-examples-update]] -====== Updating (INSERT/UPDATE/DELETE) with JdbcTemplate +====== Updating (`INSERT`, `UPDATE`, and `DELETE`) with `JdbcTemplate` -You use the `update(..)` method to perform insert, update and delete operations. -Parameter values are usually provided as var args or alternatively as an object array. +You can use the `update(..)` method to perform insert, update, and delete operations. +Parameter values are usually provided as variable argumets or, alternatively, as an object array. +The following example inserts a new entry: + +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2486,7 +2567,11 @@ Parameter values are usually provided as var args or alternatively as an object "insert into t_actor (first_name, last_name) values (?, ?)", "Leonor", "Watling"); ---- +==== +The following example updates an existing entry: + +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2494,7 +2579,11 @@ Parameter values are usually provided as var args or alternatively as an object "update t_actor set last_name = ? where id = ?", "Banjo", 5276L); ---- +==== +The following example deletes an entry: + +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2502,23 +2591,29 @@ Parameter values are usually provided as var args or alternatively as an object "delete from actor where id = ?", Long.valueOf(actorId)); ---- +==== + + [[jdbc-JdbcTemplate-examples-other]] -====== Other JdbcTemplate operations +====== Other `JdbcTemplate` Operations -You can use the `execute(..)` method to execute any arbitrary SQL, and as such the -method is often used for DDL statements. It is heavily overloaded with variants taking -callback interfaces, binding variable arrays, and so on. +You can use the `execute(..)` method to run any arbitrary SQL. Consequently, the +method is often used for DDL statements. It is heavily overloaded with variants that take +callback interfaces, binding variable arrays, and so on. The following example creates a +table: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- this.jdbcTemplate.execute("create table mytable (id integer, name varchar(100))"); ---- +==== -The following example invokes a simple stored procedure. More sophisticated stored -procedure support is <>. +The following example invokes a stored procedure: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2526,22 +2621,28 @@ procedure support is <>. "call SUPPORT.REFRESH_ACTORS_SUMMARY(?)", Long.valueOf(unionId)); ---- +==== + +More sophisticated stored procedure support is <>. + + [[jdbc-JdbcTemplate-idioms]] -===== JdbcTemplate best practices +===== `JdbcTemplate` Best Practices -Instances of the `JdbcTemplate` class are __threadsafe once configured__. This is +Instances of the `JdbcTemplate` class are thread-safe, once configured. This is important because it means that you can configure a single instance of a `JdbcTemplate` -and then safely inject this __shared__ reference into multiple DAOs (or repositories). +and then safely inject this shared reference into multiple DAOs (or repositories). The `JdbcTemplate` is stateful, in that it maintains a reference to a `DataSource`, but -this state is __not__ conversational state. +this state is not conversational state. A common practice when using the `JdbcTemplate` class (and the associated -<> classes) is to -configure a `DataSource` in your Spring configuration file, and then dependency-inject -that shared `DataSource` bean into your DAO classes; the `JdbcTemplate` is created in -the setter for the `DataSource`. This leads to DAOs that look in part like the following: +<> class) is to +configure a `DataSource` in your Spring configuration file and then dependency-inject +that shared `DataSource` bean into your DAO classes. The `JdbcTemplate` is created in +the setter for the `DataSource`. This leads to DAOs that resemble the following: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2556,9 +2657,11 @@ the setter for the `DataSource`. This leads to DAOs that look in part like the f // JDBC-backed implementations of the methods on the CorporateEventDao follow... } ---- +==== -The corresponding configuration might look like this. +The following example shows the corresponding XML configuration: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -2587,31 +2690,38 @@ The corresponding configuration might look like this. ---- +==== An alternative to explicit configuration is to use component-scanning and annotation -support for dependency injection. In this case you annotate the class with `@Repository` +support for dependency injection. In this case, you can annotate the class with `@Repository` (which makes it a candidate for component-scanning) and annotate the `DataSource` setter -method with `@Autowired`. +method with `@Autowired`. The following example shows how to do so: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- - **@Repository** + @Repository <1> public class JdbcCorporateEventDao implements CorporateEventDao { private JdbcTemplate jdbcTemplate; - **@Autowired** + @Autowired <2> public void setDataSource(DataSource dataSource) { - **this.jdbcTemplate = new JdbcTemplate(dataSource);** + this.jdbcTemplate = new JdbcTemplate(dataSource); <3> } // JDBC-backed implementations of the methods on the CorporateEventDao follow... } ---- +<1> Annotate the class with `@Repository`. +<2> annotate the `DataSource` setter method with `@Autowired`. +<3> Create a new `JdbcTemplate` with the `DataSource`. +==== -The corresponding XML configuration file would look like the following: +The following example shows the corresponding XML configuration: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -2639,31 +2749,34 @@ The corresponding XML configuration file would look like the following: ---- +==== -If you are using Spring's `JdbcDaoSupport` class, and your various JDBC-backed DAO classes -extend from it, then your sub-class inherits a `setDataSource(..)` method from the +If you use Spring's `JdbcDaoSupport` class and your various JDBC-backed DAO classes +extend from it, your sub-class inherits a `setDataSource(..)` method from the `JdbcDaoSupport` class. You can choose whether to inherit from this class. The `JdbcDaoSupport` class is provided as a convenience only. Regardless of which of the above template initialization styles you choose to use (or not), it is seldom necessary to create a new instance of a `JdbcTemplate` class each -time you want to execute SQL. Once configured, a `JdbcTemplate` instance is threadsafe. -You may want multiple `JdbcTemplate` instances if your application accesses multiple -databases, which requires multiple `DataSources`, and subsequently multiple differently -configured `JdbcTemplates`. +time you want to run SQL. Once configured, a `JdbcTemplate` instance is thread-safe. +If your application accesses multiple +databases, you may want multiple `JdbcTemplate` instances, which requires multiple `DataSources` and, subsequently, multiple differently +configured `JdbcTemplate` instances. + [[jdbc-NamedParameterJdbcTemplate]] -==== NamedParameterJdbcTemplate +==== Using `NamedParameterJdbcTemplate` The `NamedParameterJdbcTemplate` class adds support for programming JDBC statements -using named parameters, as opposed to programming JDBC statements using only classic +by using named parameters, as opposed to programming JDBC statements using only classic placeholder ( `'?'`) arguments. The `NamedParameterJdbcTemplate` class wraps a -`JdbcTemplate`, and delegates to the wrapped `JdbcTemplate` to do much of its work. This +`JdbcTemplate` and delegates to the wrapped `JdbcTemplate` to do much of its work. This section describes only those areas of the `NamedParameterJdbcTemplate` class that differ -from the `JdbcTemplate` itself; namely, programming JDBC statements using named -parameters. +from the `JdbcTemplate` itself -- namely, programming JDBC statements by using named +parameters. The following exampe shows how to use `NamedParameterJdbcTemplate`: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2683,9 +2796,10 @@ parameters. return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); } ---- +==== Notice the use of the named parameter notation in the value assigned to the `sql` -variable, and the corresponding value that is plugged into the `namedParameters` +variable and the corresponding value that is plugged into the `namedParameters` variable (of type `MapSqlParameterSource`). Alternatively, you can pass along named parameters and their corresponding values to a @@ -2693,8 +2807,9 @@ Alternatively, you can pass along named parameters and their corresponding value methods exposed by the `NamedParameterJdbcOperations` and implemented by the `NamedParameterJdbcTemplate` class follow a similar pattern and are not covered here. -The following example shows the use of the `Map`-based style. +The following example shows the use of the `Map`-based style: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2714,21 +2829,25 @@ The following example shows the use of the `Map`-based style. return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); } ---- +==== One nice feature related to the `NamedParameterJdbcTemplate` (and existing in the same Java package) is the `SqlParameterSource` interface. You have already seen an example of -an implementation of this interface in one of the previous code snippet (the +an implementation of this interface in one of the previous code snippets (the `MapSqlParameterSource` class). An `SqlParameterSource` is a source of named parameter -values to a `NamedParameterJdbcTemplate`. The `MapSqlParameterSource` class is a very -simple implementation that is simply an adapter around a `java.util.Map`, where the keys +values to a `NamedParameterJdbcTemplate`. The `MapSqlParameterSource` class is a +simple implementation that is an adapter around a `java.util.Map`, where the keys are the parameter names and the values are the parameter values. Another `SqlParameterSource` implementation is the `BeanPropertySqlParameterSource` class. This class wraps an arbitrary JavaBean (that is, an instance of a class that adheres to http://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html[the -JavaBean conventions]), and uses the properties of the wrapped JavaBean as the source +JavaBean conventions]) and uses the properties of the wrapped JavaBean as the source of named parameter values. +The following example shows a typical JavaBean: + +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2754,7 +2873,12 @@ of named parameter values. } ---- +==== + +The following example uses a `NamedParameterJdbcTemplate` to return the count of the +members of the class shown in the preceding example: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2775,10 +2899,11 @@ of named parameter values. return this.namedParameterJdbcTemplate.queryForObject(sql, namedParameters, Integer.class); } ---- +==== -Remember that the `NamedParameterJdbcTemplate` class __wraps__ a classic `JdbcTemplate` -template; if you need access to the wrapped `JdbcTemplate` instance to access -functionality only present in the `JdbcTemplate` class, you can use the +Remember that the `NamedParameterJdbcTemplate` class wraps a classic `JdbcTemplate` +template. If you need access to the wrapped `JdbcTemplate` instance to access +functionality that is present only in the `JdbcTemplate` class, you can use the `getJdbcOperations()` method to access the wrapped `JdbcTemplate` through the `JdbcOperations` interface. @@ -2786,8 +2911,9 @@ See also <> for guidelines on using the `NamedParameterJdbcTemplate` class in the context of an application. + [[jdbc-SQLExceptionTranslator]] -==== SQLExceptionTranslator +==== Using `SQLExceptionTranslator` `SQLExceptionTranslator` is an interface to be implemented by classes that can translate between `SQLExceptions` and Spring's own `org.springframework.dao.DataAccessException`, @@ -2799,35 +2925,34 @@ codes) for greater precision. that is used by default. This implementation uses specific vendor codes. It is more precise than the `SQLState` implementation. The error code translations are based on codes held in a JavaBean type class called `SQLErrorCodes`. This class is created and -populated by an `SQLErrorCodesFactory` which as the name suggests is a factory for +populated by an `SQLErrorCodesFactory`, which (as the name suggests) is a factory for creating `SQLErrorCodes` based on the contents of a configuration file named `sql-error-codes.xml`. This file is populated with vendor codes and based on the -`DatabaseProductName` taken from the `DatabaseMetaData`. The codes for the actual +`DatabaseProductName` taken from `DatabaseMetaData`. The codes for the actual database you are using are used. The `SQLErrorCodeSQLExceptionTranslator` applies matching rules in the following sequence: -[NOTE] -==== -The `SQLErrorCodesFactory` is used by default to define Error codes and custom exception -translations. They are looked up in a file named `sql-error-codes.xml` from the -classpath and the matching `SQLErrorCodes` instance is located based on the database -name from the database metadata of the database in use. -==== -* Any custom translation implemented by a subclass. Normally the provided concrete - `SQLErrorCodeSQLExceptionTranslator` is used so this rule does not apply. It only - applies if you have actually provided a subclass implementation. -* Any custom implementation of the `SQLExceptionTranslator` interface that is provided +. Any custom translation implemented by a subclass. Normally, the provided concrete + `SQLErrorCodeSQLExceptionTranslator` is used, so this rule does not apply. It + applies only if you have actually provided a subclass implementation. +. Any custom implementation of the `SQLExceptionTranslator` interface that is provided as the `customSqlExceptionTranslator` property of the `SQLErrorCodes` class. -* The list of instances of the `CustomSQLErrorCodesTranslation` class, provided for the - `customTranslations` property of the `SQLErrorCodes` class, are searched for a match. -* Error code matching is applied. -* Use the fallback translator. `SQLExceptionSubclassTranslator` is the default fallback - translator. If this translation is not available then the next fallback translator is +. The list of instances of the `CustomSQLErrorCodesTranslation` class (provided for the + `customTranslations` property of the `SQLErrorCodes` class) are searched for a match. +. Error code matching is applied. +. Use the fallback translator. `SQLExceptionSubclassTranslator` is the default fallback + translator. If this translation is not available, the next fallback translator is the `SQLStateSQLExceptionTranslator`. -You can extend `SQLErrorCodeSQLExceptionTranslator:` +NOTE: The `SQLErrorCodesFactory` is used by default to define `Error` codes and custom exception +translations. They are looked up in a file named `sql-error-codes.xml` from the +classpath, and the matching `SQLErrorCodes` instance is located based on the database +name from the database metadata of the database in use. + +You can extend `SQLErrorCodeSQLExceptionTranslator`, as the following example shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2841,14 +2966,16 @@ You can extend `SQLErrorCodeSQLExceptionTranslator:` } } ---- +==== -In this example, the specific error code `-12345` is translated and other errors are +In the preceding example, the specific error code (`-12345`) is translated, while other errors are left to be translated by the default translator implementation. To use this custom -translator, it is necessary to pass it to the `JdbcTemplate` through the method -`setExceptionTranslator` and to use this `JdbcTemplate` for all of the data access -processing where this translator is needed. Here is an example of how this custom -translator can be used: +translator, you must pass it to the `JdbcTemplate` through the method +`setExceptionTranslator`, and you must use this `JdbcTemplate` for all of the data access +processing where this translator is needed. The following example shows how you can use this custom +translator: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2874,19 +3001,22 @@ translator can be used: " where id = ?", pct, orderId); } ---- +==== The custom translator is passed a data source in order to look up the error codes in `sql-error-codes.xml`. + [[jdbc-statements-executing]] -==== Executing statements +==== Running Statements -Executing an SQL statement requires very little code. You need a `DataSource` and a +Running an SQL statement requires very little code. You need a `DataSource` and a `JdbcTemplate`, including the convenience methods that are provided with the `JdbcTemplate`. The following example shows what you need to include for a minimal but fully functional class that creates a new table: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2906,17 +3036,20 @@ fully functional class that creates a new table: } } ---- +==== + [[jdbc-statements-querying]] -==== Running queries +==== Running Queries Some query methods return a single value. To retrieve a count or a specific value from one row, use `queryForObject(..)`. The latter converts the returned JDBC `Type` to the -Java class that is passed in as an argument. If the type conversion is invalid, then an -`InvalidDataAccessApiUsageException` is thrown. Here is an example that contains two -query methods, one for an `int` and one that queries for a `String`. +Java class that is passed in as an argument. If the type conversion is invalid, an +`InvalidDataAccessApiUsageException` is thrown. The following example contains two +query methods, one for an `int` and one that queries for a `String`: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2940,13 +3073,15 @@ query methods, one for an `int` and one that queries for a `String`. } } ---- +==== In addition to the single result query methods, several methods return a list with an -entry for each row that the query returned. The most generic method is `queryForList(..)` +entry for each row that the query returned. The most generic method is `queryForList(..)`, which returns a `List` where each element is a `Map` containing one entry for each column, -using the column name as the key. If you add a method to the above example to retrieve a -list of all the rows, it would look like this: +using the column name as the key. If you add a method to the preceding example to retrieve a +list of all the rows, it might be as follows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2960,24 +3095,26 @@ list of all the rows, it would look like this: return this.jdbcTemplate.queryForList("select * from mytable"); } ---- +==== -The list returned would look something like this: +The returned list would resemble the following: +==== [literal] [subs="verbatim,quotes"] ---- [{name=Bob, id=1}, {name=Mary, id=2}] ---- +==== + [[jdbc-updates]] -==== Updating the database +==== Updating the Database -The following example shows a column updated for a certain primary key. In this example, -an SQL statement has placeholders for row parameters. The parameter values can be passed -in as varargs or alternatively as an array of objects. Thus primitives should be wrapped -in the primitive wrapper classes explicitly or using auto-boxing. +The following example updates a column for a certain primary key: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -2997,20 +3134,28 @@ in the primitive wrapper classes explicitly or using auto-boxing. } } ---- +==== + +In the preceding example, +an SQL statement has placeholders for row parameters. You can pass the parameter values +in as varargs or ,alternatively, as an array of objects. Thus, you should explictly wrap primitives +in the primitive wrapper classes, or you should use auto-boxing. + [[jdbc-auto-genereted-keys]] -==== Retrieving auto-generated keys +==== Retrieving Auto-generated Keys An `update()` convenience method supports the retrieval of primary keys generated by the -database. This support is part of the JDBC 3.0 standard; see Chapter 13.6 of the +database. This support is part of the JDBC 3.0 standard. See Chapter 13.6 of the specification for details. The method takes a `PreparedStatementCreator` as its first argument, and this is the way the required insert statement is specified. The other argument is a `KeyHolder`, which contains the generated key on successful return from the -update. There is not a standard single way to create an appropriate `PreparedStatement` +update. There is no standard single way to create an appropriate `PreparedStatement` (which explains why the method signature is the way it is). The following example works on Oracle but may not work on other platforms: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3030,25 +3175,38 @@ on Oracle but may not work on other platforms: // keyHolder.getKey() now contains the generated key ---- +==== [[jdbc-connections]] -=== Controlling database connections +=== Controlling Database Connections + +This section covers: + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + [[jdbc-datasource]] -==== DataSource +==== Using `DataSource` Spring obtains a connection to the database through a `DataSource`. A `DataSource` is -part of the JDBC specification and is a generalized connection factory. It allows a -container or a framework to hide connection pooling and transaction management issues +part of the JDBC specification and is a generalized connection factory. It lets a +container or a framework hide connection pooling and transaction management issues from the application code. As a developer, you need not know details about how to -connect to the database; that is the responsibility of the administrator that sets up +connect to the database. That is the responsibility of the administrator who sets up the datasource. You most likely fill both roles as you develop and test code, but you do not necessarily have to know how the production data source is configured. -When using Spring's JDBC layer, you obtain a data source from JNDI or you configure your +When you use Spring's JDBC layer, you can obtain a data source from JNDI, or you can configure your own with a connection pool implementation provided by a third party. Popular implementations are Apache Jakarta Commons DBCP and C3P0. Implementations in the Spring distribution are meant only for testing purposes and do not provide pooling. @@ -3056,19 +3214,25 @@ distribution are meant only for testing purposes and do not provide pooling. This section uses Spring's `DriverManagerDataSource` implementation, and several additional implementations are covered later. -[NOTE] -==== -Only use the `DriverManagerDataSource` class should only be used for testing purposes -since it does not provide pooling and will perform poorly when multiple requests for a +NOTE: You should use the `DriverManagerDataSource` class only for testing purposes, +since it does not provide pooling and performs poorly when multiple requests for a connection are made. -==== -You obtain a connection with `DriverManagerDataSource` as you typically obtain a JDBC -connection. Specify the fully qualified classname of the JDBC driver so that the -`DriverManager` can load the driver class. Next, provide a URL that varies between JDBC -drivers. (Consult the documentation for your driver for the correct value.) Then provide -a username and a password to connect to the database. Here is an example of how to -configure a `DriverManagerDataSource` in Java code: +To configure a `DriverManagerDataSource`: + +. Obtain a connection with `DriverManagerDataSource` as you typically obtain a JDBC +connection. +. Specify the fully qualified classname of the JDBC driver so that the +`DriverManager` can load the driver class. +. Provide a URL that varies between JDBC +drivers. (See the documentation for your driver for the correct value.) +. Provide +a username and a password to connect to the database. + +The following example shows how to +configure a `DriverManagerDataSource` in Java: + +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3078,8 +3242,9 @@ configure a `DriverManagerDataSource` in Java code: dataSource.setUsername("sa"); dataSource.setPassword(""); ---- +==== -Here is the corresponding XML configuration: +The following example shows the corresponding XML configuration: [source,java,indent=0] [subs="verbatim,quotes"] @@ -3094,12 +3259,13 @@ Here is the corresponding XML configuration: ---- -The following examples show the basic connectivity and configuration for DBCP and C3P0. +The next two examples show the basic connectivity and configuration for DBCP and C3P0. To learn about more options that help control the pooling features, see the product documentation for the respective connection pooling implementations. -DBCP configuration: +The following example shows DBCP configuration: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3112,9 +3278,11 @@ DBCP configuration: ---- +==== -C3P0 configuration: +The following example shows C3P0 configuration: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3127,91 +3295,94 @@ C3P0 configuration: ---- +==== + [[jdbc-DataSourceUtils]] -==== DataSourceUtils +==== Using `DataSourceUtils` The `DataSourceUtils` class is a convenient and powerful helper class that provides `static` methods to obtain connections from JNDI and close connections if necessary. It supports thread-bound connections with, for example, `DataSourceTransactionManager`. + [[jdbc-SmartDataSource]] -==== SmartDataSource +==== Implementing `SmartDataSource` The `SmartDataSource` interface should be implemented by classes that can provide a -connection to a relational database. It extends the `DataSource` interface to allow -classes using it to query whether the connection should be closed after a given -operation. This usage is efficient when you know that you will reuse a connection. +connection to a relational database. It extends the `DataSource` interface to let +classes that use it query whether the connection should be closed after a given +operation. This usage is efficient when you know that you need to reuse a connection. + [[jdbc-AbstractDataSource]] -==== AbstractDataSource +==== Extending `AbstractDataSource` `AbstractDataSource` is an `abstract` base class for Spring's `DataSource` -implementations that implements code that is common to all `DataSource` implementations. -You extend the `AbstractDataSource` class if you are writing your own `DataSource` +implementations. It implements code that is common to all `DataSource` implementations. +You should extend the `AbstractDataSource` class if you write your own `DataSource` implementation. + [[jdbc-SingleConnectionDataSource]] -==== SingleConnectionDataSource +==== Using `SingleConnectionDataSource` The `SingleConnectionDataSource` class is an implementation of the `SmartDataSource` -interface that wraps a __single__ `Connection` that is __not__ closed after each use. -Obviously, this is not multi-threading capable. +interface that wraps a single `Connection` that is not closed after each use. +This is not multi-threading capable. -If any client code calls `close` in the assumption of a pooled connection, as when using -persistence tools, set the `suppressClose` property to `true`. This setting returns a -close-suppressing proxy wrapping the physical connection. Be aware that you will not be -able to cast this to a native Oracle `Connection` or the like anymore. +If any client code calls `close` on the assumption of a pooled connection (as when using +persistence tools), you should set the `suppressClose` property to `true`. This setting returns a +close-suppressing proxy that wraps the physical connection. Note that you can no longer +cast this to a native Oracle `Connection` or a similar object. -This is primarily a test class. For example, it enables easy testing of code outside an +`SingleConnectionDataSource` is primarily a test class. For example, it enables easy testing of code outside an application server, in conjunction with a simple JNDI environment. In contrast to `DriverManagerDataSource`, it reuses the same connection all the time, avoiding excessive creation of physical connections. + [[jdbc-DriverManagerDataSource]] -==== DriverManagerDataSource +==== Using `DriverManagerDataSource` The `DriverManagerDataSource` class is an implementation of the standard `DataSource` -interface that configures a plain JDBC driver through bean properties, and returns a new +interface that configures a plain JDBC driver through bean properties and returns a new `Connection` every time. This implementation is useful for test and stand-alone environments outside of a Java EE -container, either as a `DataSource` bean in a Spring IoC container, or in conjunction -with a simple JNDI environment. Pool-assuming `Connection.close()` calls will simply +container, either as a `DataSource` bean in a Spring IoC container or in conjunction +with a simple JNDI environment. Pool-assuming `Connection.close()` calls close the connection, so any `DataSource`-aware persistence code should work. However, -using JavaBean-style connection pools such as `commons-dbcp` is so easy, even in a test +using JavaBean-style connection pools (such as `commons-dbcp`) is so easy, even in a test environment, that it is almost always preferable to use such a connection pool over `DriverManagerDataSource`. [[jdbc-TransactionAwareDataSourceProxy]] -==== TransactionAwareDataSourceProxy +==== Using `TransactionAwareDataSourceProxy` -`TransactionAwareDataSourceProxy` is a proxy for a target `DataSource`, which wraps that +`TransactionAwareDataSourceProxy` is a proxy for a target `DataSource`. The proxy wraps that target `DataSource` to add awareness of Spring-managed transactions. In this respect, it -is similar to a transactional JNDI `DataSource` as provided by a Java EE server. +is similar to a transactional JNDI `DataSource`, as provided by a Java EE server. -[NOTE] -==== -It is rarely desirable to use this class, except when already existing code that must be +NOTE: It is rarely desirable to use this class, except when already existing code must be called and passed a standard JDBC `DataSource` interface implementation. In this case, -it's possible to still have this code be usable, and at the same time have this code +you can still have this code be usable and, at the same time, have this code participating in Spring managed transactions. It is generally preferable to write your -own new code using the higher level abstractions for resource management, such as +own new code by using the higher level abstractions for resource management, such as `JdbcTemplate` or `DataSourceUtils`. -==== -__(See the `TransactionAwareDataSourceProxy` javadocs for more details.)__ +See the {api-spring-framework}/jdbc/datasource/TransactionAwareDataSourceProxy.html[`TransactionAwareDataSourceProxy` Javadoc] for more details. [[jdbc-DataSourceTransactionManager]] -==== DataSourceTransactionManager +==== Using `DataSourceTransactionManager` The `DataSourceTransactionManager` class is a `PlatformTransactionManager` implementation for single JDBC datasources. It binds a JDBC connection from the @@ -3221,41 +3392,43 @@ thread connection per data source. Application code is required to retrieve the JDBC connection through `DataSourceUtils.getConnection(DataSource)` instead of Java EE's standard `DataSource.getConnection`. It throws unchecked `org.springframework.dao` exceptions -instead of checked `SQLExceptions`. All framework classes like `JdbcTemplate` use this +instead of checked `SQLExceptions`. All framework classes (such as `JdbcTemplate`) use this strategy implicitly. If not used with this transaction manager, the lookup strategy -behaves exactly like the common one - it can thus be used in any case. +behaves exactly like the common one. Thus, it can be used in any case. -The `DataSourceTransactionManager` class supports custom isolation levels, and timeouts +The `DataSourceTransactionManager` class supports custom isolation levels and timeouts that get applied as appropriate JDBC statement query timeouts. To support the latter, application code must either use `JdbcTemplate` or call the `DataSourceUtils.applyTransactionTimeout(..)` method for each created statement. -This implementation can be used instead of `JtaTransactionManager` in the single -resource case, as it does not require the container to support JTA. Switching between -both is just a matter of configuration, if you stick to the required connection lookup -pattern. JTA does not support custom isolation levels! +You can use this implementation instead of `JtaTransactionManager` in the single-resource +case, as it does not require the container to support JTA. Switching between +both is just a matter of configuration, provided you stick to the required connection lookup +pattern. JTA does not support custom isolation levels. [[jdbc-advanced-jdbc]] -=== JDBC batch operations +=== JDBC Batch Operations Most JDBC drivers provide improved performance if you batch multiple calls to the same -prepared statement. By grouping updates into batches you limit the number of round trips +prepared statement. By grouping updates into batches, you limit the number of round trips to the database. + [[jdbc-batch-classic]] -==== Basic batch operations with the JdbcTemplate +==== Basic Batch Operations with `JdbcTemplate` You accomplish `JdbcTemplate` batch processing by implementing two methods of a special -interface, `BatchPreparedStatementSetter`, and passing that in as the second parameter -in your `batchUpdate` method call. Use the `getBatchSize` method to provide the size of -the current batch. Use the `setValues` method to set the values for the parameters of -the prepared statement. This method will be called the number of times that you -specified in the `getBatchSize` call. The following example updates the actor table -based on entries in a list. The entire list is used as the batch in this example: +interface, `BatchPreparedStatementSetter`, and passing that implementation in as the second parameter +in your `batchUpdate` method call. You can use the `getBatchSize` method to provide the size of +the current batch. You can use the `setValues` method to set the values for the parameters of +the prepared statement. This method is called the number of times that you +specified in the `getBatchSize` call. The following example updates the `actor` table +based on entries in a list, and the entire list is used as the batch: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3285,29 +3458,32 @@ based on entries in a list. The entire list is used as the batch in this example // ... additional methods } ---- +==== -If you are processing a stream of updates or reading from a file, then you might have a +If you process a stream of updates or reading from a file, you might have a preferred batch size, but the last batch might not have that number of entries. In this -case you can use the `InterruptibleBatchPreparedStatementSetter` interface, which allows -you to interrupt a batch once the input source is exhausted. The `isBatchExhausted` method -allows you to signal the end of the batch. +case, you can use the `InterruptibleBatchPreparedStatementSetter` interface, which lets +you interrupt a batch once the input source is exhausted. The `isBatchExhausted` method +lets you signal the end of the batch. + [[jdbc-batch-list]] -==== Batch operations with a List of objects +==== Batch Operations with a List of Objects Both the `JdbcTemplate` and the `NamedParameterJdbcTemplate` provides an alternate way of providing the batch update. Instead of implementing a special batch interface, you provide all parameter values in the call as a list. The framework loops over these -values and uses an internal prepared statement setter. The API varies depending on -whether you use named parameters. For the named parameters you provide an array of +values and uses an internal prepared statement setter. The API varies, depending on +whether you use named parameters. For the named parameters, you provide an array of `SqlParameterSource`, one entry for each member of the batch. You can use the `SqlParameterSourceUtils.createBatch` convenience methods to create this array, passing -in an array of bean-style objects (with getter methods corresponding to parameters) -and/or String-keyed Maps (containing the corresponding parameters as values). +in an array of bean-style objects (with getter methods corresponding to parameters), +`String`-keyed `Map` instances (containing the corresponding parameters as values), or a mix of both. -This example shows a batch update using named parameters: +The following example shows a batch update using named parameters: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3328,14 +3504,16 @@ This example shows a batch update using named parameters: // ... additional methods } ---- +==== -For an SQL statement using the classic "?" placeholders, you pass in a list containing an +For an SQL statement that uses the classic `?` placeholders, you pass in a list containing an object array with the update values. This object array must have one entry for each placeholder in the SQL statement, and they must be in the same order as they are defined in the SQL statement. -The same example using classic JDBC "?" placeholders: +The following example is the same as the preceding example, except that it uses classic JDBC "?" placeholders: +=== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3362,44 +3540,47 @@ The same example using classic JDBC "?" placeholders: // ... additional methods } ---- +==== -All of the above batch update methods return an int array containing the number of +All of the batch update methods that we described earlier return an `int` array containing the number of affected rows for each batch entry. This count is reported by the JDBC driver. If the -count is not available, the JDBC driver returns a -2 value. +count is not available, the JDBC driver returns a value of `-2`. [NOTE] ==== -In such a scenario with automatic setting of values on an underlying `PreparedStatement`, +In such a scenario, with automatic setting of values on an underlying `PreparedStatement`, the corresponding JDBC type for each value needs to be derived from the given Java type. -While this usually works well, there is a potential for issues, e.g. with Map-contained -`null` values: Spring will by default call `ParameterMetaData.getParameterType` in such a -case which may be expensive with your JDBC driver. Please make sure to use a recent driver -version, and consider setting the "spring.jdbc.getParameterType.ignore" property to "true" +While this usually works well, there is a potential for issues (for example, with Map-contained +`null` values). Spring, by default, calls `ParameterMetaData.getParameterType` in such a +case, which can be expensive with your JDBC driver. You should use a recent driver +version and consider setting the `spring.jdbc.getParameterType.ignore` property to `true` (as a JVM system property or in a `spring.properties` file in the root of your classpath) -if you encounter a performance issue, e.g. as reported on Oracle 12c (SPR-16139). +if you encounter a performance issue -- for example, as reported on Oracle 12c (SPR-16139). -Alternatively, simply consider specifying the corresponding JDBC types explicitly: -either via a 'BatchPreparedStatementSetter' as shown above, or via an explicit type -array given to a 'List' based call, or via 'registerSqlType' calls on a -custom 'MapSqlParameterSource' instance, or via a 'BeanPropertySqlParameterSource' -which derives the SQL type from the Java-declared property type even for a null value. +Alternatively, you might consider specifying the corresponding JDBC types explicitly, +either through a 'BatchPreparedStatementSetter' (as shown earlier), through an explicit type +array given to a 'List' based call, through 'registerSqlType' calls on a +custom 'MapSqlParameterSource' instance, or through a 'BeanPropertySqlParameterSource' +that derives the SQL type from the Java-declared property type even for a null value. ==== + [[jdbc-batch-multi]] -==== Batch operations with multiple batches +==== Batch Operations with Multiple Batches -The last example of a batch update deals with batches that are so large that you want to -break them up into several smaller batches. You can of course do this with the methods -mentioned above by making multiple calls to the `batchUpdate` method, but there is now a +The preceding example of a batch update deals with batches that are so large that you want to +break them up into several smaller batches. You can do this with the methods +mentioned earlier by making multiple calls to the `batchUpdate` method, but there is now a more convenient method. This method takes, in addition to the SQL statement, a -Collection of objects containing the parameters, the number of updates to make for each -batch and a `ParameterizedPreparedStatementSetter` to set the values for the parameters +`Collection` of objects that contain the parameters, the number of updates to make for each +batch, and a `ParameterizedPreparedStatementSetter` to set the values for the parameters of the prepared statement. The framework loops over the provided values and breaks the update calls into batches of the size specified. -This example shows a batch update using a batch size of 100: +The following example shows a batch update that uses a batch size of 100: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3429,39 +3610,41 @@ This example shows a batch update using a batch size of 100: // ... additional methods } ---- +==== -The batch update methods for this call returns an array of int arrays containing an array +The batch update methods for this call returns an array of `int` arrays that contain an array entry for each batch with an array of the number of affected rows for each update. The top level array's length indicates the number of batches executed and the second level array's length indicates the number of updates in that batch. The number of updates in each batch -should be the batch size provided for all batches except for the last one that might -be less, depending on the total number of update objects provided. The update count for +should be the batch size provided for all batches (except that the last one that might +be less), depending on the total number of update objects provided. The update count for each update statement is the one reported by the JDBC driver. If the count is not -available, the JDBC driver returns a -2 value. +available, the JDBC driver returns a value of `-2`. [[jdbc-simple-jdbc]] -=== Simplifying JDBC operations with the SimpleJdbc classes +=== Simplifying JDBC Operations with the `SimpleJdbc` Classes The `SimpleJdbcInsert` and `SimpleJdbcCall` classes provide a simplified configuration by taking advantage of database metadata that can be retrieved through the JDBC driver. -This means there is less to configure up front, although you can override or turn off +This means that you have less to configure up front, although you can override or turn off the metadata processing if you prefer to provide all the details in your code. [[jdbc-simple-jdbc-insert-1]] -==== Inserting data using SimpleJdbcInsert +==== Inserting Data by Using `SimpleJdbcInsert` -Let's start by looking at the `SimpleJdbcInsert` class with the minimal amount of +We start by looking at the `SimpleJdbcInsert` class with the minimal amount of configuration options. You should instantiate the `SimpleJdbcInsert` in the data access layer's initialization method. For this example, the initializing method is the -`setDataSource` method. You do not need to subclass the `SimpleJdbcInsert` class; simply -create a new instance and set the table name using the `withTableName` method. -Configuration methods for this class follow the "fluid" style that returns the instance -of the `SimpleJdbcInsert`, which allows you to chain all configuration methods. This -example uses only one configuration method; you will see examples of multiple ones later. +`setDataSource` method. You do not need to subclass the `SimpleJdbcInsert` class. Instead, +you can create a new instance and set the table name by using the `withTableName` method. +Configuration methods for this class follow the `fluid` style that returns the instance +of the `SimpleJdbcInsert`, which lets you chain all configuration methods. The following +example uses only one configuration method (we shows examples of multiple methods later): +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3486,21 +3669,25 @@ example uses only one configuration method; you will see examples of multiple on // ... additional methods } ---- +==== + +The `execute` method used here takes a plain `java.utils.Map` as its only parameter. The +important thing to note here is that the keys used for the `Map` must match the column +names of the table, as defined in the database. This is because we read the metadata +to construct the actual insert statement. -The execute method used here takes a plain `java.utils.Map` as its only parameter. The -important thing to note here is that the keys used for the Map must match the column -names of the table as defined in the database. This is because we read the metadata in -order to construct the actual insert statement. [[jdbc-simple-jdbc-insert-2]] -==== Retrieving auto-generated keys using SimpleJdbcInsert +==== Retrieving Auto-generated Keys by Using `SimpleJdbcInsert` -This example uses the same insert as the preceding, but instead of passing in the id it -retrieves the auto-generated key and sets it on the new Actor object. When you create -the `SimpleJdbcInsert`, in addition to specifying the table name, you specify the name -of the generated key column with the `usingGeneratedKeyColumns` method. +The next example uses the same insert as the preceding example, but, instead of passing in the `id`, it +retrieves the auto-generated key and sets it on the new `Actor` object. When it creates +the `SimpleJdbcInsert`, in addition to specifying the table name, it specifies the name +of the generated key column with the `usingGeneratedKeyColumns` method. The following +listing shows how it works: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3527,22 +3714,25 @@ of the generated key column with the `usingGeneratedKeyColumns` method. // ... additional methods } ---- +==== -The main difference when executing the insert by this second approach is that you do not -add the id to the Map and you call the `executeAndReturnKey` method. This returns a +The main difference when you run the insert by using this second approach is that you do not +add the `id` to the `Map`, and you call the `executeAndReturnKey` method. This returns a `java.lang.Number` object with which you can create an instance of the numerical type that -is used in our domain class. You cannot rely on all databases to return a specific Java -class here; `java.lang.Number` is the base class that you can rely on. If you have -multiple auto-generated columns, or the generated values are non-numeric, then you can +is used in your domain class. You cannot rely on all databases to return a specific Java +class here. `java.lang.Number` is the base class that you can rely on. If you have +multiple auto-generated columns or the generated values are non-numeric, you can use a `KeyHolder` that is returned from the `executeAndReturnKeyHolder` method. + [[jdbc-simple-jdbc-insert-3]] -==== Specifying columns for a SimpleJdbcInsert +==== Specifying Columns for a `SimpleJdbcInsert` You can limit the columns for an insert by specifying a list of column names with the -`usingColumns` method: +`usingColumns` method, as the following example shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3570,21 +3760,24 @@ You can limit the columns for an insert by specifying a list of column names wit // ... additional methods } ---- +==== The execution of the insert is the same as if you had relied on the metadata to determine which columns to use. + [[jdbc-simple-jdbc-parameters]] -==== Using SqlParameterSource to provide parameter values +==== Using `SqlParameterSource` to Provide Parameter Values -Using a `Map` to provide parameter values works fine, but it's not the most convenient +Using a `Map` to provide parameter values works fine, but it is not the most convenient class to use. Spring provides a couple of implementations of the `SqlParameterSource` -interface that can be used instead.The first one is `BeanPropertySqlParameterSource`, +interface that you can use instead. The first one is `BeanPropertySqlParameterSource`, which is a very convenient class if you have a JavaBean-compliant class that contains -your values. It will use the corresponding getter method to extract the parameter -values. Here is an example: +your values. It uses the corresponding getter method to extract the parameter +values. The following example shows how to use `BeanPropertySqlParameterSource`: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3609,10 +3802,12 @@ values. Here is an example: // ... additional methods } ---- +==== -Another option is the `MapSqlParameterSource` that resembles a Map but provides a more -convenient `addValue` method that can be chained. +Another option is the `MapSqlParameterSource` that resembles a `Map` but provides a more +convenient `addValue` method that can be chained. The following example shows how to use it: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3639,22 +3834,26 @@ convenient `addValue` method that can be chained. // ... additional methods } ---- +==== -As you can see, the configuration is the same; only the executing code has to change to +As you can see, the configuration is the same. Only the executing code has to change to use these alternative input classes. + [[jdbc-simple-jdbc-call-1]] -==== Calling a stored procedure with SimpleJdbcCall +==== Calling a Stored Procedure with `SimpleJdbcCall` -The `SimpleJdbcCall` class leverages metadata in the database to look up names of `in` -and `out` parameters, so that you do not have to declare them explicitly. You can -declare parameters if you prefer to do that, or if you have parameters such as `ARRAY` -or `STRUCT` that do not have an automatic mapping to a Java class. The first example +The `SimpleJdbcCall` class uses metadata in the database to look up names of `in` +and `out` parameters so that you do not have to explicitly declare them. You can +declare parameters if you prefer to do that or if you have parameters (such as `ARRAY` +or `STRUCT`) that do not have an automatic mapping to a Java class. The first example shows a simple procedure that returns only scalar values in `VARCHAR` and `DATE` format from a MySQL database. The example procedure reads a specified actor entry and returns `first_name`, `last_name`, and `birth_date` columns in the form of `out` parameters. +The following listing shows the first example: +==== [source,sql,indent=0] [subs="verbatim,quotes"] ---- @@ -3669,18 +3868,20 @@ from a MySQL database. The example procedure reads a specified actor entry and r FROM t_actor where id = in_id; END; ---- +==== -The `in_id` parameter contains the `id` of the actor you are looking up. The `out` +The `in_id` parameter contains the `id` of the actor that you are looking up. The `out` parameters return the data read from the table. -The `SimpleJdbcCall` is declared in a similar manner to the `SimpleJdbcInsert`. You -should instantiate and configure the class in the initialization method of your data -access layer. Compared to the StoredProcedure class, you don't have to create a subclass -and you don't have to declare parameters that can be looked up in the database metadata. -Following is an example of a SimpleJdbcCall configuration using the above stored -procedure. The only configuration option, in addition to the `DataSource`, is the name -of the stored procedure. +You can declare `SimpleJdbcCall` in a manner similar to declaring `SimpleJdbcInsert`. You +should instantiate and configure the class in the initialization method of your data-access +layer. Compared to the `StoredProcedure` class, you need not create a subclass +and you need not to declare parameters that can be looked up in the database metadata. +The following example of a `SimpleJdbcCall` configuration uses the preceding stored +procedure (the only configuration option, in addition to the `DataSource`, is the name +of the stored procedure): +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3710,29 +3911,31 @@ of the stored procedure. // ... additional methods } ---- +==== The code you write for the execution of the call involves creating an `SqlParameterSource` -containing the IN parameter. It's important to match the name provided for the input value +containing the IN parameter. You must match the name provided for the input value with that of the parameter name declared in the stored procedure. The case does not have to match because you use metadata to determine how database objects should be referred to in a stored procedure. What is specified in the source for the stored procedure is not necessarily the way it is stored in the database. Some databases transform names to all -upper case while others use lower case or use the case as specified. +upper case, while others use lower case or use the case as specified. -The `execute` method takes the IN parameters and returns a Map containing any `out` -parameters keyed by the name as specified in the stored procedure. In this case they are -`out_first_name, out_last_name` and `out_birth_date`. +The `execute` method takes the IN parameters and returns a `Map` that contains any `out` +parameters keyed by the name, as specified in the stored procedure. In this case, they are +`out_first_name`, `out_last_name`, and `out_birth_date`. -The last part of the `execute` method creates an Actor instance to use to return the +The last part of the `execute` method creates an `Actor` instance to use to return the data retrieved. Again, it is important to use the names of the `out` parameters as they are declared in the stored procedure. Also, the case in the names of the `out` parameters stored in the results map matches that of the `out` parameter names in the -database, which could vary between databases. To make your code more portable you should +database, which could vary between databases. To make your code more portable, you should do a case-insensitive lookup or instruct Spring to use a `LinkedCaseInsensitiveMap`. -To do the latter, you create your own `JdbcTemplate` and set the `setResultsMapCaseInsensitive` -property to `true`. Then you pass this customized `JdbcTemplate` instance into -the constructor of your `SimpleJdbcCall`. Here is an example of this configuration: +To do the latter, you can create your own `JdbcTemplate` and set the `setResultsMapCaseInsensitive` +property to `true`. Then you can pass this customized `JdbcTemplate` instance into +the constructor of your `SimpleJdbcCall`. The following example shows this configuration: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3750,39 +3953,39 @@ the constructor of your `SimpleJdbcCall`. Here is an example of this configurati // ... additional methods } ---- +==== By taking this action, you avoid conflicts in the case used for the names of your returned `out` parameters. + [[jdbc-simple-jdbc-call-2]] -==== Explicitly declaring parameters to use for a SimpleJdbcCall +==== Explicitly Declaring Parameters to Use for a `SimpleJdbcCall` -You have seen how the parameters are deduced based on metadata, but you can declare then -explicitly if you wish. You do this by creating and configuring `SimpleJdbcCall` with +Earlier in this chapter, we described how parameters are deduced from metadata, but you can declare them +explicitly if you wish. You can do so by creating and configuring `SimpleJdbcCall` with the `declareParameters` method, which takes a variable number of `SqlParameter` objects -as input. See the next section for details on how to define an `SqlParameter`. +as input. See the <> for details on how to define an `SqlParameter`. -[NOTE] -==== -Explicit declarations are necessary if the database you use is not a Spring-supported -database. Currently Spring supports metadata lookup of stored procedure calls for the +NOTE: Explicit declarations are necessary if the database you use is not a Spring-supported +database. Currently, Spring supports metadata lookup of stored procedure calls for the following databases: Apache Derby, DB2, MySQL, Microsoft SQL Server, Oracle, and Sybase. We also support metadata lookup of stored functions for MySQL, Microsoft SQL Server, and Oracle. -==== -You can opt to declare one, some, or all the parameters explicitly. The parameter -metadata is still used where you do not declare parameters explicitly. To bypass all -processing of metadata lookups for potential parameters and only use the declared -parameters, you call the method `withoutProcedureColumnMetaDataAccess` as part of the +You can opt to explicitly declare one, some, or all of the parameters. The parameter +metadata is still used where you do not explicitly declare parameters. To bypass all +processing of metadata lookups for potential parameters and use only the declared +parameters, you can call the method `withoutProcedureColumnMetaDataAccess` as part of the declaration. Suppose that you have two or more different call signatures declared for a -database function. In this case you call the `useInParameterNames` to specify the list +database function. In this case, you call `useInParameterNames` to specify the list of IN parameter names to include for a given signature. -The following example shows a fully declared procedure call, using the information from -the preceding example. +The following example shows a fully declared procedure call and uses the information from +the preceding example: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3808,42 +4011,43 @@ the preceding example. // ... additional methods } ---- +==== -The execution and end results of the two examples are the same; this one specifies all +The execution and end results of the two examples are the same. The second example specifies all details explicitly rather than relying on metadata. + [[jdbc-params]] -==== How to define SqlParameters +==== How to Define `SqlParameters` -To define a parameter for the SimpleJdbc classes and also for the RDBMS operations -classes, covered in <>, you use an `SqlParameter` or one of its subclasses. -You typically specify the parameter name and SQL type in the constructor. The SQL type -is specified using the `java.sql.Types` constants. We have already seen declarations -like: +To define a parameter for the `SimpleJdbc` classes and also for the RDBMS operations +classes (covered in <>) you can use `SqlParameter` or one of its subclasses. +To do so, you typically specify the parameter name and SQL type in the constructor. The SQL type +is specified by using the `java.sql.Types` constants. Earlier in this chapter, we saw declarations +similar to the following: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- new SqlParameter("in_id", Types.NUMERIC), new SqlOutParameter("out_first_name", Types.VARCHAR), ---- +==== -The first line with the `SqlParameter` declares an IN parameter. IN parameters can be -used for both stored procedure calls and for queries using the `SqlQuery` and its -subclasses covered in the following section. +The first line with the `SqlParameter` declares an IN parameter. You can use IN parameters +for both stored procedure calls and for queries by using the `SqlQuery` and its +subclasses (covered in <>). -The second line with the `SqlOutParameter` declares an `out` parameter to be used in a -stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters, -parameters that provide an `IN` value to the procedure and that also return a value. +The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in a +stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters +(parameters that provide an IN value to the procedure and that also return a value). -[NOTE] -==== -Only parameters declared as `SqlParameter` and `SqlInOutParameter` will be used to -provide input values. This is different from the `StoredProcedure` class, which for -backwards compatibility reasons allows input values to be provided for parameters +NOTE: Only parameters declared as `SqlParameter` and `SqlInOutParameter` are used to +provide input values. This is different from the `StoredProcedure` class, which (for +backwards compatibility reasons) lets input values be provided for parameters declared as `SqlOutParameter`. -==== For IN parameters, in addition to the name and the SQL type, you can specify a scale for numeric data or a type name for custom database types. For `out` parameters, you can @@ -3852,20 +4056,22 @@ option is to specify an `SqlReturnType` that provides an opportunity to define customized handling of the return values. + [[jdbc-simple-jdbc-call-3]] -==== Calling a stored function using SimpleJdbcCall +==== Calling a Stored Function by Using `SimpleJdbcCall` -You call a stored function in almost the same way as you call a stored procedure, except +You can call a stored function in almost the same way as you call a stored procedure, except that you provide a function name rather than a procedure name. You use the -`withFunctionName` method as part of the configuration to indicate that we want to make +`withFunctionName` method as part of the configuration to indicate that you want to make a call to a function, and the corresponding string for a function call is generated. A -specialized execute call, `executeFunction,` is used to execute the function and it +specialized execute call (`executeFunction`) is used to execute the function, and it returns the function return value as an object of a specified type, which means you do not have to retrieve the return value from the results map. A similar convenience method -named `executeObject` is also available for stored procedures that only have one `out` -parameter. The following example is based on a stored function named `get_actor_name` -that returns an actor's full name. Here is the MySQL source for this function: +(named `executeObject`) is also available for stored procedures that have only one `out` +parameter. The following example (for MySQL) is based on a stored function named `get_actor_name` +that returns an actor's full name: +==== [source,sql,indent=0] [subs="verbatim,quotes"] ---- @@ -3879,9 +4085,12 @@ that returns an actor's full name. Here is the MySQL source for this function: RETURN out_name; END; ---- +==== -To call this function we again create a `SimpleJdbcCall` in the initialization method. +To call this function, we again create a `SimpleJdbcCall` in the initialization method, +as the following example shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3908,28 +4117,31 @@ To call this function we again create a `SimpleJdbcCall` in the initialization m // ... additional methods } ---- +==== -The execute method used returns a `String` containing the return value from the function +The `executeFunction` method used returns a `String` that contains the return value from the function call. + [[jdbc-simple-jdbc-call-4]] -==== Returning ResultSet/REF Cursor from a SimpleJdbcCall +==== Returning a `ResultSet` or REF Cursor from a `SimpleJdbcCall` Calling a stored procedure or function that returns a result set is a bit tricky. Some -databases return result sets during the JDBC results processing while others require an +databases return result sets during the JDBC results processing, while others require an explicitly registered `out` parameter of a specific type. Both approaches need additional processing to loop over the result set and process the returned rows. With -the `SimpleJdbcCall` you use the `returningResultSet` method and declare a `RowMapper` -implementation to be used for a specific parameter. In the case where the result set is +the `SimpleJdbcCall`, you can use the `returningResultSet` method and declare a `RowMapper` +implementation to be used for a specific parameter. If the result set is returned during the results processing, there are no names defined, so the returned -results will have to match the order in which you declare the `RowMapper` +results must match the order in which you declare the `RowMapper` implementations. The name specified is still used to store the processed list of results -in the results map that is returned from the execute statement. +in the results map that is returned from the `execute` statement. -The next example uses a stored procedure that takes no IN parameters and returns all -rows from the t_actor table. Here is the MySQL source for this procedure: +The next example (for MySQL) uses a stored procedure that takes no IN parameters and returns all +rows from the `t_actor` table: +==== [source,sql,indent=0] [subs="verbatim,quotes"] ---- @@ -3938,11 +4150,14 @@ rows from the t_actor table. Here is the MySQL source for this procedure: SELECT a.id, a.first_name, a.last_name, a.birth_date FROM t_actor a; END; ---- +==== -To call this procedure you declare the `RowMapper`. Because the class you want to map to +To call this procedure, you can declare the `RowMapper`. Because the class to which you want to map follows the JavaBean rules, you can use a `BeanPropertyRowMapper` that is created by passing in the required class to map to in the `newInstance` method. +The following example shows how to do so: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -3967,54 +4182,58 @@ created by passing in the required class to map to in the `newInstance` method. // ... additional methods } ---- +==== -The execute call passes in an empty Map because this call does not take any parameters. -The list of Actors is then retrieved from the results map and returned to the caller. +The `execute` call passes in an empty `Map`, because this call does not take any parameters. +The list of actors is then retrieved from the results map and returned to the caller. [[jdbc-object]] -=== Modeling JDBC operations as Java objects +=== Modeling JDBC Operations as Java Objects -The `org.springframework.jdbc.object` package contains classes that allow you to access +The `org.springframework.jdbc.object` package contains classes that let you access the database in a more object-oriented manner. As an example, you can execute queries -and get the results back as a list containing business objects with the relational -column data mapped to the properties of the business object. You can also execute stored +and get the results back as a list that contains business objects with the relational +column data mapped to the properties of the business object. You can also run stored procedures and run update, delete, and insert statements. [NOTE] ==== Many Spring developers believe that the various RDBMS operation classes described below (with the exception of the <> class) can often -be replaced with straight `JdbcTemplate` calls. Often it is simpler to write a DAO -method that simply calls a method on a `JdbcTemplate` directly (as opposed to +be replaced with straight `JdbcTemplate` calls. Often, it is simpler to write a DAO +method that calls a method on a `JdbcTemplate` directly (as opposed to encapsulating a query as a full-blown class). However, if you are getting measurable value from using the RDBMS operation classes, -continue using these classes. +you should continue to use these classes. ==== + [[jdbc-SqlQuery]] -==== SqlQuery +==== Understanding `SqlQuery` -`SqlQuery` is a reusable, threadsafe class that encapsulates an SQL query. Subclasses +`SqlQuery` is a reusable, thread-safe class that encapsulates an SQL query. Subclasses must implement the `newRowMapper(..)` method to provide a `RowMapper` instance that can create one object per row obtained from iterating over the `ResultSet` that is created -during the execution of the query. The `SqlQuery` class is rarely used directly because +during the execution of the query. The `SqlQuery` class is rarely used directly, because the `MappingSqlQuery` subclass provides a much more convenient implementation for mapping rows to Java classes. Other implementations that extend `SqlQuery` are `MappingSqlQueryWithParameters` and `UpdatableSqlQuery`. + [[jdbc-MappingSqlQuery]] -==== MappingSqlQuery +==== Using `MappingSqlQuery` `MappingSqlQuery` is a reusable query in which concrete subclasses must implement the abstract `mapRow(..)` method to convert each row of the supplied `ResultSet` into an object of the type specified. The following example shows a custom query that maps the -data from the `t_actor` relation to an instance of the `Actor` class. +data from the `t_actor` relation to an instance of the `Actor` class: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4037,18 +4256,20 @@ data from the `t_actor` relation to an instance of the `Actor` class. } ---- +==== The class extends `MappingSqlQuery` parameterized with the `Actor` type. The constructor -for this customer query takes the `DataSource` as the only parameter. In this -constructor you call the constructor on the superclass with the `DataSource` and the SQL -that should be executed to retrieve the rows for this query. This SQL will be used to -create a `PreparedStatement` so it may contain place holders for any parameters to be -passed in during execution. You must declare each parameter using the `declareParameter` -method passing in an `SqlParameter`. The `SqlParameter` takes a name and the JDBC type -as defined in `java.sql.Types`. After you define all parameters, you call the -`compile()` method so the statement can be prepared and later executed. This class is -thread-safe after it is compiled, so as long as these instances are created when the DAO -is initialized they can be kept as instance variables and be reused. +for this customer query takes a `DataSource` as the only parameter. In this +constructor, you can call the constructor on the superclass with the `DataSource` and the SQL +that should be executed to retrieve the rows for this query. This SQL is used to +create a `PreparedStatement`, so it may contain placeholders for any parameters to be +passed in during execution. You must declare each parameter by using the `declareParameter` +method passing in an `SqlParameter`. The `SqlParameter` takes a name, and the JDBC type +as defined in `java.sql.Types`. After you define all parameters, you can call the +`compile()` method so that the statement can be prepared and later run. This class is +thread-safe after it is compiled, so, as long as these instances are created when the DAO +is initialized, they can be kept as instance variables and be reused. The following +example shows how to define such a class: [source,java,indent=0] [subs="verbatim,quotes"] @@ -4065,12 +4286,14 @@ is initialized they can be kept as instance variables and be reused. } ---- -The method in this example retrieves the customer with the id that is passed in as the -only parameter. Since we only want one object returned we simply call the convenience -method `findObject` with the id as parameter. If we had instead a query that returned a -list of objects and took additional parameters then we would use one of the execute -methods that takes an array of parameter values passed in as varargs. +The method in the preceding example retrieves the customer with the `id` that is passed in as the +only parameter. Since we want only one object to be returned, we call the `findObject` convenience +method with the `id` as the parameter. If we had instead a query that returned a +list of objects and took additional parameters, we would use one of the `execute` +methods that takes an array of parameter values passed in as varargs. The following +example shows such a method: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4079,19 +4302,23 @@ methods that takes an array of parameter values passed in as varargs. return actors; } ---- +==== + [[jdbc-SqlUpdate]] -==== SqlUpdate +==== Using `SqlUpdate` -The `SqlUpdate` class encapsulates an SQL update. Like a query, an update object is -reusable, and like all `RdbmsOperation` classes, an update can have parameters and is +The `SqlUpdate` class encapsulates an SQL update. As with a query, an update object is +reusable, and, as with all `RdbmsOperation` classes, an update can have parameters and is defined in SQL. This class provides a number of `update(..)` methods analogous to the `execute(..)` methods of query objects. The `SQLUpdate` class is concrete. It can be -subclassed, for example, to add a custom update method, as in the following snippet -where it's simply called `execute`. However, you don't have to subclass the `SqlUpdate` -class since it can easily be parameterized by setting SQL and declaring parameters. +subclassed -- for example, to add a custom update method. +However, you do not have to subclass the `SqlUpdate` +class, since it can easily be parameterized by setting SQL and declaring parameters. +The following example creates a custom update method named `execute`: +==== [source,java,indent=0] [subs="verbatim"] ---- @@ -4120,54 +4347,61 @@ class since it can easily be parameterized by setting SQL and declaring paramete } } ---- +==== + [[jdbc-StoredProcedure]] -==== StoredProcedure +==== Using `StoredProcedure` The `StoredProcedure` class is a superclass for object abstractions of RDBMS stored procedures. This class is `abstract`, and its various `execute(..)` methods have `protected` access, preventing use other than through a subclass that offers tighter typing. -The inherited `sql` property will be the name of the stored procedure in the RDBMS. +The inherited `sql` property is the name of the stored procedure in the RDBMS. -To define a parameter for the `StoredProcedure` class, you use an `SqlParameter` or one -of its subclasses. You must specify the parameter name and SQL type in the constructor -like in the following code snippet. The SQL type is specified using the `java.sql.Types` -constants. +To define a parameter for the `StoredProcedure` class, you can use an `SqlParameter` or one +of its subclasses. You must specify the parameter name and SQL type in the constructor, +as the following code snippet shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- new SqlParameter("in_id", Types.NUMERIC), new SqlOutParameter("out_first_name", Types.VARCHAR), ---- +==== + +The SQL type is specified using the `java.sql.Types` constants. -The first line with the `SqlParameter` declares an IN parameter. IN parameters can be -used for both stored procedure calls and for queries using the `SqlQuery` and its -subclasses covered in the following section. +The first line (with the `SqlParameter`) declares an IN parameter. You can use IN parameters +both for stored procedure calls and for queries using the `SqlQuery` and its +subclasses (covered in <>). -The second line with the `SqlOutParameter` declares an `out` parameter to be used in the -stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters, -parameters that provide an `in` value to the procedure and that also return a value. +The second line (with the `SqlOutParameter`) declares an `out` parameter to be used in the +stored procedure call. There is also an `SqlInOutParameter` for `InOut` parameters +(parameters that provide an `in` value to the procedure and that also return a value). For `in` parameters, in addition to the name and the SQL type, you can specify a -scale for numeric data or a type name for custom database types. For `out` parameters -you can provide a `RowMapper` to handle mapping of rows returned from a REF cursor. -Another option is to specify an `SqlReturnType` that enables you to define customized +scale for numeric data or a type name for custom database types. For `out` parameters, +you can provide a `RowMapper` to handle mapping of rows returned from a `REF` cursor. +Another option is to specify an `SqlReturnType` that lets you define customized handling of the return values. -Here is an example of a simple DAO that uses a `StoredProcedure` to call a function, -`sysdate()`,which comes with any Oracle database. To use the stored procedure -functionality you have to create a class that extends `StoredProcedure`. In this -example, the `StoredProcedure` class is an inner class, but if you need to reuse the -`StoredProcedure` you declare it as a top-level class. This example has no input -parameters, but an output parameter is declared as a date type using the class -`SqlOutParameter`. The `execute()` method executes the procedure and extracts the +The next example of a simple DAO uses a `StoredProcedure` to call a function +(`sysdate()`), which comes with any Oracle database. To use the stored procedure +functionality, you have to create a class that extends `StoredProcedure`. In this +example, the `StoredProcedure` class is an inner class. However, if you need to reuse the +`StoredProcedure`, you can declare it as a top-level class. This example has no input +parameters, but an output parameter is declared as a date type by using the +`SqlOutParameter` class. The `execute()` method runs the procedure and extracts the returned date from the results `Map`. The results `Map` has an entry for each declared -output parameter, in this case only one, using the parameter name as the key. +output parameter (in this case, only one) byusing the parameter name as the key. +The following listing shows our custom StoredProcedure class: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4215,10 +4449,12 @@ output parameter, in this case only one, using the parameter name as the key. } ---- +==== The following example of a `StoredProcedure` has two output parameters (in this case, -Oracle REF cursors). +Oracle REF cursors): +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4246,15 +4482,17 @@ Oracle REF cursors). } } ---- +==== Notice how the overloaded variants of the `declareParameter(..)` method that have been used in the `TitlesAndGenresStoredProcedure` constructor are passed `RowMapper` -implementation instances; this is a very convenient and powerful way to reuse existing -functionality. The code for the two `RowMapper` implementations is provided below. +implementation instances. This is a very convenient and powerful way to reuse existing +functionality. The next two examples provide code for the two `RowMapper` implementations. The `TitleMapper` class maps a `ResultSet` to a `Title` domain object for each row in -the supplied `ResultSet`: +the supplied `ResultSet`, as follows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4273,10 +4511,12 @@ the supplied `ResultSet`: } } ---- +==== The `GenreMapper` class maps a `ResultSet` to a `Genre` domain object for each row in -the supplied `ResultSet`. +the supplied `ResultSet`, as follows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4292,11 +4532,13 @@ the supplied `ResultSet`. } } ---- +==== To pass parameters to a stored procedure that has one or more input parameters in its definition in the RDBMS, you can code a strongly typed `execute(..)` method that would -delegate to the untyped `execute(Map)` method in the superclass; for example: +delegate to the untyped `execute(Map)` method in the superclass, as the following example shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4329,72 +4571,78 @@ delegate to the untyped `execute(Map)` method in the superclass; for example: } } ---- +==== [[jdbc-parameter-handling]] -=== Common problems with parameter and data value handling +=== Common Problems with Parameter and Data Value Handling Common problems with parameters and data values exist in the different approaches -provided by Spring Framework's JDBC support. +provided by Spring Framework's JDBC support. This section covers how to address them. + [[jdbc-type-information]] -==== Providing SQL type information for parameters +==== Providing SQL Type Information for Parameters -Usually Spring determines the SQL type of the parameters based on the type of parameter +Usually, Spring determines the SQL type of the parameters based on the type of parameter passed in. It is possible to explicitly provide the SQL type to be used when setting -parameter values. This is sometimes necessary to correctly set NULL values. +parameter values. This is sometimes necessary to correctly set `NULL` values. You can provide SQL type information in several ways: * Many update and query methods of the `JdbcTemplate` take an additional parameter in the form of an `int` array. This array is used to indicate the SQL type of the - corresponding parameter using constant values from the `java.sql.Types` class. Provide + corresponding parameter by using constant values from the `java.sql.Types` class. Provide one entry for each parameter. * You can use the `SqlParameterValue` class to wrap the parameter value that needs this - additional information.Create a new instance for each value and pass in the SQL type - and parameter value in the constructor. You can also provide an optional scale + additional information. To do so, create a new instance for each value and pass in the SQL type + and the parameter value in the constructor. You can also provide an optional scale parameter for numeric values. -* For methods working with named parameters, use the `SqlParameterSource` classes +* For methods that work with named parameters, you can use the `SqlParameterSource` classes, `BeanPropertySqlParameterSource` or `MapSqlParameterSource`. They both have methods for registering the SQL type for any of the named parameter values. + [[jdbc-lob]] ==== Handling BLOB and CLOB objects You can store images, other binary data, and large chunks of text in the database. These large objects are called BLOBs (Binary Large OBject) for binary data and CLOBs (Character -Large OBject) for character data. In Spring you can handle these large objects by using +Large OBject) for character data. In Spring, you can handle these large objects by using the `JdbcTemplate` directly and also when using the higher abstractions provided by RDBMS Objects and the `SimpleJdbc` classes. All of these approaches use an implementation of -the `LobHandler` interface for the actual management of the LOB (Large OBject) data. The +the `LobHandler` interface for the actual management of the LOB (Large OBject) data. `LobHandler` provides access to a `LobCreator` class, through the `getLobCreator` method, -used for creating new LOB objects to be inserted. +that is used for creating new LOB objects to be inserted. -The `LobCreator/LobHandler` provides the following support for LOB input and output: +`LobCreator` and `LobHandler` provide the following support for LOB input and output: * BLOB -** `byte[]` -- `getBlobAsBytes` and `setBlobAsBytes` -** `InputStream` -- `getBlobAsBinaryStream` and `setBlobAsBinaryStream` +** `byte[]`: `getBlobAsBytes` and `setBlobAsBytes` +** `InputStream`: `getBlobAsBinaryStream` and `setBlobAsBinaryStream` * CLOB -** `String` -- `getClobAsString` and `setClobAsString` -** `InputStream` -- `getClobAsAsciiStream` and `setClobAsAsciiStream` -** `Reader` -- `getClobAsCharacterStream` and `setClobAsCharacterStream` +** `String`: `getClobAsString` and `setClobAsString` +** `InputStream`: `getClobAsAsciiStream` and `setClobAsAsciiStream` +** `Reader`: `getClobAsCharacterStream` and `setClobAsCharacterStream` -The next example shows how to create and insert a BLOB. Later you will see how to read +The next example shows how to create and insert a BLOB. Later we show how to read it back from the database. This example uses a `JdbcTemplate` and an implementation of the `AbstractLobCreatingPreparedStatementCallback`. It implements one method, -`setValues`. This method provides a `LobCreator` that you use to set the values for the +`setValues`. This method provides a `LobCreator` that we use to set the values for the LOB columns in your SQL insert statement. -For this example we assume that there is a variable, `lobHandler`, that already is +For this example, we assume that there is a variable, `lobHandler`, that is already set to an instance of a `DefaultLobHandler`. You typically set this value through dependency injection. +The following example shows how to create and insert a BLOB: + +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4419,10 +4667,10 @@ dependency injection. clobReader.close(); ---- -<1> Pass in the `lobHandler` that in this example is a plain `DefaultLobHandler`. -<2> Using the method `setClobAsCharacterStream`, pass in the contents of the CLOB. -<3> Using the method `setBlobAsBinaryStream`, pass in the contents of the BLOB. - +<1> Pass in the `lobHandler` that (in this example) is a plain `DefaultLobHandler`. +<2> Using the method `setClobAsCharacterStream` to pass in the contents of the CLOB. +<3> Using the method `setBlobAsBinaryStream` to pass in the contents of the BLOB. +==== [NOTE] ==== @@ -4430,17 +4678,18 @@ If you invoke the `setBlobAsBinaryStream`, `setClobAsAsciiStream`, or `setClobAsCharacterStream` method on the `LobCreator` returned from `DefaultLobHandler.getLobCreator()`, you can optionally specify a negative value for the `contentLength` argument. If the specified content length is negative, the -`DefaultLobHandler` will use the JDBC 4.0 variants of the set-stream methods without a -length parameter; otherwise, it will pass the specified length on to the driver. +`DefaultLobHandler` uses the JDBC 4.0 variants of the set-stream methods without a +length parameter. Otherwise, it passes the specified length on to the driver. -Consult the documentation for the JDBC driver in use to verify support for streaming a +See the documentation for the JDBC driver you use to verify that it supports streaming a LOB without providing the content length. ==== - -Now it's time to read the LOB data from the database. Again, you use a `JdbcTemplate` +Now it is time to read the LOB data from the database. Again, you use a `JdbcTemplate` with the same instance variable `lobHandler` and a reference to a `DefaultLobHandler`. +The following example shows how to do so: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4457,51 +4706,52 @@ with the same instance variable `lobHandler` and a reference to a `DefaultLobHan }); ---- -<1> Using the method `getClobAsString`, retrieve the contents of the CLOB. -<2> Using the method `getBlobAsBytes`, retrieve the contents of the BLOB. +<1> Using the method `getClobAsString` to retrieve the contents of the CLOB. +<2> Using the method `getBlobAsBytes` to retrieve the contents of the BLOB. +==== + [[jdbc-in-clause]] -==== Passing in lists of values for IN clause +==== Passing in Lists of Values for IN Clause The SQL standard allows for selecting rows based on an expression that includes a variable list of values. A typical example would be `select * from T_ACTOR where id in (1, 2, 3)`. This variable list is not directly supported for prepared statements by the -JDBC standard; you cannot declare a variable number of placeholders. You need a number +JDBC standard. You cannot declare a variable number of placeholders. You need a number of variations with the desired number of placeholders prepared, or you need to generate the SQL string dynamically once you know how many placeholders are required. The named parameter support provided in the `NamedParameterJdbcTemplate` and `JdbcTemplate` takes -the latter approach. Pass in the values as a `java.util.List` of primitive objects. This -list will be used to insert the required placeholders and pass in the values during the +the latter approach. You can pass in the values as a `java.util.List` of primitive objects. This +list is used to insert the required placeholders and pass in the values during statement execution. -[NOTE] -==== -Be careful when passing in many values. The JDBC standard does not guarantee that you +NOTE: Be careful when passing in many values. The JDBC standard does not guarantee that you can use more than 100 values for an `in` expression list. Various databases exceed this -number, but they usually have a hard limit for how many values are allowed. Oracle's +number, but they usually have a hard limit for how many values are allowed. For example, Oracle's limit is 1000. -==== In addition to the primitive values in the value list, you can create a `java.util.List` -of object arrays. This list would support multiple expressions defined for the `in` -clause such as `select * from T_ACTOR where (id, last_name) in \((1, 'Johnson'), (2, -'Harrop'\))`. This of course requires that your database supports this syntax. +of object arrays. This list can support multiple expressions being defined for the `in` +clause, such as `select * from T_ACTOR where (id, last_name) in \((1, 'Johnson'), (2, +'Harrop'\))`. This, of course, requires that your database supports this syntax. + [[jdbc-complex-types]] -==== Handling complex types for stored procedure calls +==== Handling Complex Types for Stored Procedure Calls -When you call stored procedures you can sometimes use complex types specific to the +When you call stored procedures, you can sometimes use complex types specific to the database. To accommodate these types, Spring provides a `SqlReturnType` for handling them when they are returned from the stored procedure call and `SqlTypeValue` when they are passed in as a parameter to the stored procedure. -Here is an example of returning the value of an Oracle `STRUCT` object of the user -declared type `ITEM_TYPE`. The `SqlReturnType` interface has a single method named -`getTypeValue` that must be implemented. This interface is used as part of the -declaration of an `SqlOutParameter`. +The `SqlReturnType` interface has a single method (named +`getTypeValue`) that must be implemented. This interface is used as part of the +declaration of an `SqlOutParameter`. The following example shows returning the value of an Oracle `STRUCT` object of the user +declared type `ITEM_TYPE`: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4524,13 +4774,15 @@ declaration of an `SqlOutParameter`. ... } ---- +==== -You use the `SqlTypeValue` to pass in the value of a Java object like `TestItem` into a -stored procedure. The `SqlTypeValue` interface has a single method named -`createTypeValue` that you must implement. The active connection is passed in, and you -can use it to create database-specific objects such as ``StructDescriptor``s, as shown in -the following example, or ``ArrayDescriptor``s. +You can use `SqlTypeValue` to pass the value of a Java object (such as `TestItem`) to a +stored procedure. The `SqlTypeValue` interface has a single method (named +`createTypeValue`) that you must implement. The active connection is passed in, and you +can use it to create database-specific objects, such as `StructDescriptor` instances +or `ArrayDescriptor` instances. The following example creates a `StructDescriptor` instance: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4550,15 +4802,17 @@ the following example, or ``ArrayDescriptor``s. } }; ---- +==== -This `SqlTypeValue` can now be added to the Map containing the input parameters for the -execute call of the stored procedure. +You can now add this `SqlTypeValue` to the `Map` that contains the input parameters for the +`execute` call of the stored procedure. Another use for the `SqlTypeValue` is passing in an array of values to an Oracle stored procedure. Oracle has its own internal `ARRAY` class that must be used in this case, and you can use the `SqlTypeValue` to create an instance of the Oracle `ARRAY` and populate -it with values from the Java `ARRAY`. +it with values from the Java `ARRAY`, as the following example shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4572,11 +4826,12 @@ it with values from the Java `ARRAY`. } }; ---- +==== [[jdbc-embedded-database-support]] -=== Embedded database support +=== Embedded Database Support The `org.springframework.jdbc.datasource.embedded` package provides support for embedded Java database engines. Support for http://www.hsqldb.org[HSQL], @@ -4585,20 +4840,23 @@ natively. You can also use an extensible API to plug in new embedded database ty `DataSource` implementations. + [[jdbc-why-embedded-database]] -==== Why use an embedded database? +==== Why Use an Embedded Database? -An embedded database is useful during the development phase of a project because of its +An embedded database can be useful during the development phase of a project because of its lightweight nature. Benefits include ease of configuration, quick startup time, -testability, and the ability to rapidly evolve SQL during development. +testability, and the ability to rapidly evolve your SQL during development. + [[jdbc-embedded-database-xml]] -==== Creating an embedded database using Spring XML +==== Creating an Embedded Database by Using Spring XML If you want to expose an embedded database instance as a bean in a Spring -`ApplicationContext`, use the `embedded-database` tag in the `spring-jdbc` namespace: +`ApplicationContext`, you can use the `embedded-database` tag in the `spring-jdbc` namespace: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -4607,21 +4865,24 @@ If you want to expose an embedded database instance as a bean in a Spring ---- +==== -The preceding configuration creates an embedded HSQL database populated with SQL from -`schema.sql` and `test-data.sql` resources in the root of the classpath. In addition, as -a best practice, the embedded database will be assigned a uniquely generated name. The +The preceding configuration creates an embedded HSQL database that is populated with SQL from +the `schema.sql` and `test-data.sql` resources in the root of the classpath. In addition, as +a best practice, the embedded database is assigned a uniquely generated name. The embedded database is made available to the Spring container as a bean of type -`javax.sql.DataSource` which can then be injected into data access objects as needed. +`javax.sql.DataSource` that can then be injected into data access objects as needed. + [[jdbc-embedded-database-java]] -==== Creating an embedded database programmatically +==== Creating an Embedded Database Programmatically The `EmbeddedDatabaseBuilder` class provides a fluent API for constructing an embedded -database programmatically. Use this when you need to create an embedded database in a -standalone environment or in a standalone integration test like in the following example. +database programmatically. You can use this when you need to create an embedded database in a +stand-alone environment or in a stand-alone integration test, as in the following example: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4638,13 +4899,15 @@ EmbeddedDatabase db = new EmbeddedDatabaseBuilder() db.shutdown() ---- +==== -Consult the Javadoc for `EmbeddedDatabaseBuilder` for further details on all supported +See the {api-spring-framework}/jdbc/datasource/embedded/EmbeddedDatabaseBuilder.html[Javadoc for `EmbeddedDatabaseBuilder`] for further details on all supported options. -The `EmbeddedDatabaseBuilder` can also be used to create an embedded database using Java -Config like in the following example. +You can also use the `EmbeddedDatabaseBuilder` to create an embedded database by using Java +configuration, as the following example shows: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4664,48 +4927,63 @@ public class DataSourceConfig { } } ---- +==== + [[jdbc-embedded-database-types]] -==== Selecting the embedded database type +==== Selecting the Embedded Database Type + +This section covers how to select one of the three embedded databases that Spring +supports. It includes the following topics: + +* <> +* <> +* <> + + [[jdbc-embedded-database-using-HSQL]] ===== Using HSQL Spring supports HSQL 1.8.0 and above. HSQL is the default embedded database if no type is -specified explicitly. To specify HSQL explicitly, set the `type` attribute of the -`embedded-database` tag to `HSQL`. If you are using the builder API, call the +explicitly specified. To specify HSQL explicitly, set the `type` attribute of the +`embedded-database` tag to `HSQL`. If you use the builder API, call the `setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.HSQL`. + [[jdbc-embedded-database-using-H2]] ===== Using H2 -Spring supports the H2 database as well. To enable H2, set the `type` attribute of the -`embedded-database` tag to `H2`. If you are using the builder API, call the +Spring supports the H2 database. To enable H2, set the `type` attribute of the +`embedded-database` tag to `H2`. If you use the builder API, call the `setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.H2`. + [[jdbc-embedded-database-using-Derby]] ===== Using Derby -Spring also supports Apache Derby 10.5 and above. To enable Derby, set the `type` -attribute of the `embedded-database` tag to `DERBY`. If you are using the builder API, +Spring supports Apache Derby 10.5 and above. To enable Derby, set the `type` +attribute of the `embedded-database` tag to `DERBY`. If you use the builder API, call the `setType(EmbeddedDatabaseType)` method with `EmbeddedDatabaseType.DERBY`. + [[jdbc-embedded-database-dao-testing]] -==== Testing data access logic with an embedded database +==== Testing Data Access Logic with an Embedded Database -Embedded databases provide a lightweight way to test data access code. The following is a -data access integration test template that uses an embedded database. Using a template -like this can be useful for _one-offs_ when the embedded database does not need to be +Embedded databases provide a lightweight way to test data access code. The next example is a +data access integration test template that uses an embedded database. Using such a template +can be useful for one-offs when the embedded database does not need to be reused across test classes. However, if you wish to create an embedded database that is shared within a test suite, consider using the <> and configuring the embedded database as a bean in the Spring `ApplicationContext` as described in <> and -<>. +<>. The following listing shows the test template: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -4736,32 +5014,34 @@ Framework>> and configuring the embedded database as a bean in the Spring } ---- +==== + [[jdbc-embedded-database-unique-names]] -==== Generating unique names for embedded databases +==== Generating Unique Names for Embedded Databases Development teams often encounter errors with embedded databases if their test suite inadvertently attempts to recreate additional instances of the same database. This can happen quite easily if an XML configuration file or `@Configuration` class is responsible for creating an embedded database and the corresponding configuration is then reused -across multiple testing scenarios within the same test suite (i.e., within the same JVM +across multiple testing scenarios within the same test suite (that is, within the same JVM process) –- for example, integration tests against embedded databases whose -`ApplicationContext` configuration only differs with regard to which bean definition +`ApplicationContext` configuration differs only with regard to which bean definition profiles are active. The root cause of such errors is the fact that Spring's `EmbeddedDatabaseFactory` (used internally by both the `` XML namespace element and the -`EmbeddedDatabaseBuilder` for Java Config) will set the name of the embedded database to -`"testdb"` if not otherwise specified. For the case of ``, the -embedded database is typically assigned a name equal to the bean's `id` (i.e., often -something like `"dataSource"`). Thus, subsequent attempts to create an embedded database -will not result in a new database. Instead, the same JDBC connection URL will be reused, -and attempts to create a new embedded database will actually point to an existing +`EmbeddedDatabaseBuilder` for Java configuration) sets the name of the embedded database to +`testdb` if not otherwise specified. For the case of ``, the +embedded database is typically assigned a name equal to the bean's `id` (often, +something like `dataSource`). Thus, subsequent attempts to create an embedded database +do not result in a new database. Instead, the same JDBC connection URL is reused, +and attempts to create a new embedded database actually point to an existing embedded database created from the same configuration. -To address this common issue Spring Framework 4.2 provides support for generating -_unique_ names for embedded databases. To enable the use of generated names, use one of +To address this common issue, Spring Framework 4.2 provides support for generating +unique names for embedded databases. To enable the use of generated names, use one of the following options. * `EmbeddedDatabaseFactory.setGenerateUniqueDatabaseName()` @@ -4769,35 +5049,38 @@ the following options. * `` + [[jdbc-embedded-database-extension]] -==== Extending the embedded database support +==== Extending the Embedded Database Support -Spring JDBC embedded database support can be extended in two ways: +You can extend Spring JDBC embedded database support in two ways: * Implement `EmbeddedDatabaseConfigurer` to support a new embedded database type. * Implement `DataSourceFactory` to support a new `DataSource` implementation, such as a connection pool to manage embedded database connections. -You are encouraged to contribute back extensions to the Spring community at +We encourage you to contribute extensions to the Spring community at https://jira.spring.io/browse/SPR[jira.spring.io]. [[jdbc-initializing-datasource]] -=== Initializing a DataSource +=== Initializing a `DataSource` The `org.springframework.jdbc.datasource.init` package provides support for initializing an existing `DataSource`. The embedded database support provides one option for creating -and initializing a `DataSource` for an application, but sometimes you need to initialize -an instance running on a server somewhere. +and initializing a `DataSource` for an application. However, you may sometimes need to initialize +an instance that runs on a server somewhere. + [[jdbc-initializing-datasource-xml]] -==== Initializing a database using Spring XML +==== Initializing a Database by Using Spring XML If you want to initialize a database and you can provide a reference to a `DataSource` -bean, use the `initialize-database` tag in the `spring-jdbc` namespace: +bean, you can use the `initialize-database` tag in the `spring-jdbc` namespace: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -4806,39 +5089,44 @@ bean, use the `initialize-database` tag in the `spring-jdbc` namespace: ---- +==== -The example above executes the two scripts specified against the database: the first +The preceding example runs the two specified scripts against the database. The first script creates a schema, and the second populates tables with a test data set. The script -locations can also be patterns with wildcards in the usual ant style used for resources -in Spring (e.g. -`classpath{asterisk}:/com/foo/{asterisk}{asterisk}/sql/{asterisk}-data.sql`). If a -pattern is used, the scripts are executed in lexical order of their URL or filename. - -The default behavior of the database initializer is to unconditionally execute the -scripts provided. This will not always be what you want, for instance, if you are -executing the scripts against a database that already has test data in it. The likelihood -of accidentally deleting data is reduced by following the common pattern (as shown above) -of creating the tables first and then inserting the data -- the first step will fail if +locations can also be patterns with wildcards in the usual Ant style used for resources +in Spring (for example, +`classpath{asterisk}:/com/foo/{asterisk}{asterisk}/sql/{asterisk}-data.sql`). If you use a +pattern, the scripts are run in the lexical order of their URL or filename. + +The default behavior of the database initializer is to unconditionally run the provided +scripts. This may not always be what you want -- for instance, if you run +the scripts against a database that already has test data in it. The likelihood +of accidentally deleting data is reduced by following the common pattern (shown earlier) +of creating the tables first and then inserting the data. The first step fails if the tables already exist. However, to gain more control over the creation and deletion of existing data, the XML namespace provides a few additional options. The first is a flag to switch the -initialization on and off. This can be set according to the environment (e.g. to pull a -boolean value from system properties or an environment bean), for example: +initialization on and off. You can set this according to the environment (such as pulling a +boolean value from system properties or from an environment bean). The following example gets a value from a system property: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- + enabled="#{systemProperties.INITIALIZE_DATABASE}"> <1> ---- +<1> Get the value for `enabled` from a system property called `INITIALIZE_DATABASE`. +==== The second option to control what happens with existing data is to be more tolerant of -failures. To this end you can control the ability of the initializer to ignore certain -errors in the SQL it executes from the scripts, for example: +failures. To this end, you can control the ability of the initializer to ignore certain +errors in the SQL it executes from the scripts, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -4846,10 +5134,11 @@ errors in the SQL it executes from the scripts, for example: ---- +==== -In this example we are saying we expect that sometimes the scripts will be executed -against an empty database, and there are some `DROP` statements in the scripts which -would therefore fail. So failed SQL `DROP` statements will be ignored, but other failures +In the preceding example, we are saying that we expect that, sometimes, the scripts are run +against an empty database, and there are some `DROP` statements in the scripts that +would, therefore, fail. So failed SQL `DROP` statements will be ignored, but other failures will cause an exception. This is useful if your SQL dialect doesn't support `DROP ... IF EXISTS` (or similar) but you want to unconditionally remove all test data before re-creating it. In that case the first script is usually a set of `DROP` statements, @@ -4859,90 +5148,97 @@ The `ignore-failures` option can be set to `NONE` (the default), `DROPS` (ignore drops), or `ALL` (ignore all failures). Each statement should be separated by `;` or a new line if the `;` character is not -present at all in the script. You can control that globally or script by script, for -example: +present at all in the script. You can control that globally or script by script, as the +following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- - - - - + <1> + <2> + + ---- +<1> Set the separator scripts to `@@`. +<2> Set the separator for `db-schema.sql` to `;`. +==== In this example, the two `test-data` scripts use `@@` as statement separator and only the `db-schema.sql` uses `;`. This configuration specifies that the default separator -is `@@` and override that default for the `db-schema` script. +is `@@` and overrides that default for the `db-schema` script. -If you need more control than you get from the XML namespace, you can simply use the +If you need more control than you get from the XML namespace, you can use the `DataSourceInitializer` directly and define it as a component in your application. + + [[jdbc-client-component-initialization]] -===== Initialization of other components that depend on the database +===== Initialization of Other Components that Depend on the Database -A large class of applications can just use the database initializer with no further -complications: those that do not use the database until after the Spring context has -started. If your application is __not__ one of those then you might need to read the rest +A large class of applications (those that do not use the database until after the Spring context has +started) can use the database initializer with no further +complications. If your application is not one of those, you might need to read the rest of this section. -The database initializer depends on a `DataSource` instance and executes the scripts +The database initializer depends on a `DataSource` instance and runs the scripts provided in its initialization callback (analogous to an `init-method` in an XML bean definition, a `@PostConstruct` method in a component, or the `afterPropertiesSet()` method in a component that implements `InitializingBean`). If other beans depend on the -same data source and also use the data source in an initialization callback, then there +same data source and use the data source in an initialization callback, there might be a problem because the data has not yet been initialized. A common example of this is a cache that initializes eagerly and loads data from the database on application startup. -To get around this issue you have two options: change your cache initialization strategy -to a later phase, or ensure that the database initializer is initialized first. +To get around this issue, you have two options: change your cache initialization strategy +to a later phase or ensure that the database initializer is initialized first. -The first option might be easy if the application is in your control, and not otherwise. +Changing your cache initialization strategy might be easy if the application is in your control and not otherwise. Some suggestions for how to implement this include: * Make the cache initialize lazily on first usage, which improves application startup time. * Have your cache or a separate component that initializes the cache implement - `Lifecycle` or `SmartLifecycle`. When the application context starts up a - `SmartLifecycle` can be automatically started if its `autoStartup` flag is set, and a - `Lifecycle` can be started manually by calling `ConfigurableApplicationContext.start()` + `Lifecycle` or `SmartLifecycle`. When the application context starts, you can + automatically start a `SmartLifecycle` by setting its `autoStartup` flag, and you can + manually start a `Lifecycle`by calling `ConfigurableApplicationContext.start()` on the enclosing context. * Use a Spring `ApplicationEvent` or similar custom observer mechanism to trigger the cache initialization. `ContextRefreshedEvent` is always published by the context when it is ready for use (after all beans have been initialized), so that is often a useful hook (this is how the `SmartLifecycle` works by default). -The second option can also be easy. Some suggestions on how to implement this include: +Ensuring that the database initializer is initialized first can also be easy. Some suggestions on how to implement this include: * Rely on the default behavior of the Spring `BeanFactory`, which is that beans are initialized in registration order. You can easily arrange that by adopting the common practice of a set of `` elements in XML configuration that order your - application modules, and ensure that the database and database initialization are + application modules and ensuring that the database and database initialization are listed first. -* Separate the `DataSource` and the business components that use it, and control their - startup order by putting them in separate `ApplicationContext` instances (e.g. the - parent context contains the `DataSource`, and child context contains the business +* Separate the `DataSource` and the business components that use it and control their + startup order by putting them in separate `ApplicationContext` instances (for example, the + parent context contains the `DataSource`, and the child context contains the business components). This structure is common in Spring web applications but can be more generally applied. - [[orm]] == Object Relational Mapping (ORM) Data Access +This section covers data access when you use Object Relational Mapping (ORM). + [[orm-introduction]] === Introduction to ORM with Spring -The Spring Framework supports integration with the Java Persistence API (JPA) as well -as native Hibernate for resource management, data access object (DAO) implementations, -and transaction strategies. For example, for Hibernate there is first-class support with +The Spring Framework supports integration with the Java Persistence API (JPA) and +supports native Hibernate for resource management, data access object (DAO) implementations, +and transaction strategies. For example, for Hibernate, there is first-class support with several convenient IoC features that address many typical Hibernate integration issues. -You can configure all of the supported features for O/R (object relational) mapping +You can configure all of the supported features for OR (object relational) mapping tools through Dependency Injection. They can participate in Spring's resource and transaction management, and they comply with Spring's generic transaction and DAO exception hierarchies. The recommended integration style is to code DAOs against plain @@ -4953,81 +5249,79 @@ data access applications. You can leverage as much of the integration support as wish, and you should compare this integration effort with the cost and risk of building a similar infrastructure in-house. You can use much of the ORM support as you would a library, regardless of technology, because everything is designed as a set of reusable -JavaBeans. ORM in a Spring IoC container facilitates configuration and deployment. Thus +JavaBeans. ORM in a Spring IoC container facilitates configuration and deployment. Thus, most examples in this section show configuration inside a Spring container. -Benefits of using the Spring Framework to create your ORM DAOs include: +The benefits of using the Spring Framework to create your ORM DAOs include: -* __Easier testing.__ Spring's IoC approach makes it easy to swap the implementations +* *Easier testing.* Spring's IoC approach makes it easy to swap the implementations and configuration locations of Hibernate `SessionFactory` instances, JDBC `DataSource` instances, transaction managers, and mapped object implementations (if needed). This in turn makes it much easier to test each piece of persistence-related code in isolation. -* __Common data access exceptions.__ Spring can wrap exceptions from your ORM tool, +* *Common data access exceptions.* Spring can wrap exceptions from your ORM tool, converting them from proprietary (potentially checked) exceptions to a common runtime - DataAccessException hierarchy. This feature allows you to handle most persistence + `DataAccessException` hierarchy. This feature lets you handle most persistence exceptions, which are non-recoverable, only in the appropriate layers, without annoying boilerplate catches, throws, and exception declarations. You can still trap and handle exceptions as necessary. Remember that JDBC exceptions (including DB-specific dialects) are also converted to the same hierarchy, meaning that you can perform some operations with JDBC within a consistent programming model. -* __General resource management.__ Spring application contexts can handle the location +* *General resource management.* Spring application contexts can handle the location and configuration of Hibernate `SessionFactory` instances, JPA `EntityManagerFactory` instances, JDBC `DataSource` instances, and other related resources. This makes these values easy to manage and change. Spring offers efficient, easy, and safe handling of persistence resources. For example, related code that uses Hibernate generally needs to use the same Hibernate `Session` to ensure efficiency and proper transaction handling. Spring makes it easy to create and bind a `Session` to the current thread transparently, - by exposing a current `Session` through the Hibernate `SessionFactory`. Thus Spring + by exposing a current `Session` through the Hibernate `SessionFactory`. Thus, Spring solves many chronic problems of typical Hibernate usage, for any local or JTA transaction environment. -* __Integrated transaction management.__ You can wrap your ORM code with a declarative, +* *Integrated transaction management.* You can wrap your ORM code with a declarative, aspect-oriented programming (AOP) style method interceptor either through the `@Transactional` annotation or by explicitly configuring the transaction AOP advice in an XML configuration file. In both cases, transaction semantics and exception handling - (rollback, and so on) are handled for you. As discussed below, in - <>, you can also swap various + (rollback and so on) are handled for you. As discussed in + <>, you can also swap various transaction managers, without affecting your ORM-related code. For example, you can swap between local transactions and JTA, with the same full services (such as declarative transactions) available in both scenarios. Additionally, JDBC-related code can fully integrate transactionally with the code you use to do ORM. This is useful - for data access that is not suitable for ORM, such as batch processing and BLOB - streaming, which still need to share common transactions with ORM operations. + for data access that is not suitable for ORM (such as batch processing and BLOB + streaming) but that still needs to share common transactions with ORM operations. -[TIP] -==== -For more comprehensive ORM support, including support for alternative database +TIP: For more comprehensive ORM support, including support for alternative database technologies such as MongoDB, you might want to check out the http://projects.spring.io/spring-data/[Spring Data] suite of projects. If you are a JPA user, the https://spring.io/guides/gs/accessing-data-jpa/[Getting Started Accessing Data with JPA] guide from https://spring.io provides a great introduction. -==== [[orm-general]] -=== General ORM integration considerations +=== General ORM Integration Considerations This section highlights considerations that apply to all ORM technologies. The <> section provides more details and also show these features and configurations in a concrete context. -The major goal of Spring's ORM integration is clear application layering, with any data -access and transaction technology, and for loose coupling of application objects. No +The major goal of Spring's ORM integration is clear application layering (with any data +access and transaction technology) and for loose coupling of application objects -- no more business service dependencies on the data access or transaction strategy, no more hard-coded resource lookups, no more hard-to-replace singletons, no more custom service -registries. One simple and consistent approach to wiring up application objects, keeping +registries. The goal is to have one simple and consistent approach to wiring up application objects, keeping them as reusable and free from container dependencies as possible. All the individual data access features are usable on their own but integrate nicely with Spring's application context concept, providing XML-based configuration and cross-referencing of plain JavaBean instances that need not be Spring-aware. In a typical Spring application, many important objects are JavaBeans: data access templates, data access objects, transaction managers, business services that use the data access objects and transaction -managers, web view resolvers, web controllers that use the business services,and so on. +managers, web view resolvers, web controllers that use the business services, and so on. + [[orm-resource-mngmnt]] -==== Resource and transaction management +==== Resource and Transaction Management Typical business applications are cluttered with repetitive resource management code. Many projects try to invent their own solutions, sometimes sacrificing proper handling @@ -5038,34 +5332,36 @@ interceptors for the ORM technologies. The infrastructure provides proper resource handling and appropriate conversion of specific API exceptions to an unchecked infrastructure exception hierarchy. Spring introduces a DAO exception hierarchy, applicable to any data access strategy. For direct -JDBC, the `JdbcTemplate` class mentioned in a previous section provides connection +JDBC, the `JdbcTemplate` class mentioned in a <> provides connection handling and proper conversion of `SQLException` to the `DataAccessException` hierarchy, including translation of database-specific SQL error codes to meaningful exception -classes. For ORM technologies, see the next section for how to get the same exception +classes. For ORM technologies, see the <> for how to get the same exception translation benefits. When it comes to transaction management, the `JdbcTemplate` class hooks in to the Spring transaction support and supports both JTA and JDBC transactions, through respective -Spring transaction managers. For the supported ORM technologies Spring offers Hibernate +Spring transaction managers. For the supported ORM technologies, Spring offers Hibernate and JPA support through the Hibernate and JPA transaction managers as well as JTA support. For details on transaction support, see the <> chapter. [[orm-exception-translation]] -==== Exception translation +==== Exception Translation When you use Hibernate or JPA in a DAO, you must decide how to handle the persistence technology's native exception classes. The DAO throws a subclass of a `HibernateException` -or `PersistenceException` depending on the technology. These exceptions are all runtime +or `PersistenceException`, depending on the technology. These exceptions are all runtime exceptions and do not have to be declared or caught. You may also have to deal with `IllegalArgumentException` and `IllegalStateException`. This means that callers can only -treat exceptions as generally fatal, unless they want to depend on the persistence -technology's own exception structure. Catching specific causes such as an optimistic -locking failure is not possible without tying the caller to the implementation strategy. -This trade-off might be acceptable to applications that are strongly ORM-based and/or -do not need any special exception treatment. However, Spring enables exception -translation to be applied transparently through the `@Repository` annotation: +treat exceptions as being generally fatal, unless they want to depend on the persistence +technology's own exception structure. Catching specific causes (such as an optimistic +locking failure) is not possible without tying the caller to the implementation strategy. +This trade-off might be acceptable to applications that are strongly ORM-based or +do not need any special exception treatment (or both). However, Spring lets exception +translation be applied transparently through the `@Repository` annotation. The following +examples (one for Java configuration and one for XML configuration) show how to do so: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -5089,14 +5385,15 @@ translation to be applied transparently through the `@Repository` annotation: ---- +==== The postprocessor automatically looks for all exception translators (implementations of the `PersistenceExceptionTranslator` interface) and advises all beans marked with the `@Repository` annotation so that the discovered translators can intercept and apply the appropriate translation on the thrown exceptions. -In summary: you can implement DAOs based on the plain persistence technology's API and -annotations, while still benefiting from Spring-managed transactions, dependency +In summary, you can implement DAOs based on the plain persistence technology's API and +annotations while still benefiting from Spring-managed transactions, dependency injection, and transparent exception conversion (if desired) to Spring's custom exception hierarchies. @@ -5105,34 +5402,33 @@ exception hierarchies. [[orm-hibernate]] === Hibernate -We will start with a coverage of http://www.hibernate.org/[Hibernate 5] in a Spring +We start with a coverage of http://www.hibernate.org/[Hibernate 5] in a Spring environment, using it to demonstrate the approach that Spring takes towards integrating -O/R mappers. This section will cover many issues in detail and show different variations +OR mappers. This section covers many issues in detail and shows different variations of DAO implementations and transaction demarcation. Most of these patterns can be -directly translated to all other supported ORM tools. The following sections in this -chapter will then cover the other ORM technologies, showing briefer examples there. +directly translated to all other supported ORM tools. The later sections in this +chapter then cover the other ORM technologies and show brief examples. -[NOTE] -==== -As of Spring Framework 5.0, Spring requires Hibernate ORM 4.3 or later for JPA support +NOTE: As of Spring Framework 5.0, Spring requires Hibernate ORM 4.3 or later for JPA support and even Hibernate ORM 5.0+ for programming against the native Hibernate Session API. Note that the Hibernate team does not maintain any versions prior to 5.1 anymore and is likely to focus on 5.3+ exclusively soon. -==== + [[orm-session-factory-setup]] -==== SessionFactory setup in a Spring container +==== `SessionFactory` Setup in a Spring Container To avoid tying application objects to hard-coded resource lookups, you can define -resources such as a JDBC `DataSource` or a Hibernate `SessionFactory` as beans in the +resources (such as a JDBC `DataSource` or a Hibernate `SessionFactory`) as beans in the Spring container. Application objects that need to access resources receive references to such predefined instances through bean references, as illustrated in the DAO -definition in the next section. +definition in the <>. The following excerpt from an XML application context definition shows how to set up a JDBC `DataSource` and a Hibernate `SessionFactory` on top of it: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5161,11 +5457,13 @@ JDBC `DataSource` and a Hibernate `SessionFactory` on top of it: ---- +==== Switching from a local Jakarta Commons DBCP `BasicDataSource` to a JNDI-located -`DataSource` (usually managed by an application server) is just a matter of -configuration: +`DataSource` (usually managed by an application server) is only a matter of +configuration, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5173,6 +5471,7 @@ configuration: ---- +==== You can also access a JNDI-located `SessionFactory`, using Spring's `JndiObjectFactoryBean` / `` to retrieve and expose it. @@ -5185,25 +5484,27 @@ with `@Bean` style configuration and programmatic setup (no `FactoryBean` involv Both `LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background bootstrapping, with Hibernate initialization running in parallel to the application -bootstrap thread on a given bootstrap executor (e.g. a `SimpleAsyncTaskExecutor`). -On `LocalSessionFactoryBean`, this is available through the "bootstrapExecutor" -property; on the programmatic `LocalSessionFactoryBuilder`, there is an overloaded -`buildSessionFactory` method which takes a bootstrap executor argument. +bootstrap thread on a given bootstrap executor (such as a `SimpleAsyncTaskExecutor`). +On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor` +property. On the programmatic `LocalSessionFactoryBuilder`, there is an overloaded +`buildSessionFactory` method that takes a bootstrap executor argument. As of Spring Framework 5.1, such a native Hibernate setup can also expose a JPA `EntityManagerFactory` for standard JPA interaction next to native Hibernate access. -See <> for details. +See <> for details. ==== + [[orm-hibernate-straight]] -==== Implementing DAOs based on plain Hibernate API +==== Implementing DAOs Based on the Plain Hibernate API Hibernate has a feature called contextual sessions, wherein Hibernate itself manages one current `Session` per transaction. This is roughly equivalent to Spring's synchronization of one Hibernate `Session` per transaction. A corresponding DAO implementation resembles the following example, based on the plain Hibernate API: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -5223,19 +5524,21 @@ implementation resembles the following example, based on the plain Hibernate API } } ---- +==== This style is similar to that of the Hibernate reference documentation and examples, except for holding the `SessionFactory` in an instance variable. We strongly recommend such an instance-based setup over the old-school `static` `HibernateUtil` class from Hibernate's CaveatEmptor sample application. (In general, do not keep any resources in -`static` variables unless __absolutely__ necessary.) +`static` variables unless absolutely necessary.) -The above DAO follows the dependency injection pattern: it fits nicely into a Spring IoC -container, just as it would if coded against Spring's `HibernateTemplate`. Of course, -such a DAO can also be set up in plain Java (for example, in unit tests). Simply +The preceding DAO example follows the dependency injection pattern. It fits nicely into a Spring IoC +container, as it would if coded against Spring's `HibernateTemplate`. +You can also set up such a DAO in plain Java (for example, in unit tests). To do so, instantiate it and call `setSessionFactory(..)` with the desired factory reference. As a Spring bean definition, the DAO would resemble the following: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5247,51 +5550,51 @@ Spring bean definition, the DAO would resemble the following: ---- +==== -The main advantage of this DAO style is that it depends on Hibernate API only; no import -of any Spring class is required. This is of course appealing from a non-invasiveness -perspective, and will no doubt feel more natural to Hibernate developers. +The main advantage of this DAO style is that it depends on Hibernate API only. No import +of any Spring class is required. This is appealing from a non-invasiveness +perspective and may feel more natural to Hibernate developers. -However, the DAO throws plain `HibernateException` (which is unchecked, so does not have -to be declared or caught), which means that callers can only treat exceptions as -generally fatal - unless they want to depend on Hibernate's own exception hierarchy. -Catching specific causes such as an optimistic locking failure is not possible without +However, the DAO throws plain `HibernateException` (which is unchecked, so it does not have +to be declared or caught), which means that callers can treat exceptions only as being +generally fatal -- unless they want to depend on Hibernate's own exception hierarchy. +Catching specific causes (such as an optimistic locking failure) is not possible without tying the caller to the implementation strategy. This trade off might be acceptable to -applications that are strongly Hibernate-based and/or do not need any special exception -treatment. +applications that are strongly Hibernate-based, do not need any special exception +treatment, or both. Fortunately, Spring's `LocalSessionFactoryBean` supports Hibernate's `SessionFactory.getCurrentSession()` method for any Spring transaction strategy, -returning the current Spring-managed transactional `Session` even with -`HibernateTransactionManager`. Of course, the standard behavior of that method remains -the return of the current `Session` associated with the ongoing JTA transaction, if any. -This behavior applies regardless of whether you are using Spring's +returning the current Spring-managed transactional `Session`, even with +`HibernateTransactionManager`. The standard behavior of that method remains +to return the current `Session` associated with the ongoing JTA transaction, if any. +This behavior applies regardless of whether you use Spring's `JtaTransactionManager`, EJB container managed transactions (CMTs), or JTA. -In summary: you can implement DAOs based on the plain Hibernate API, while still being +In summary, you can implement DAOs based on the plain Hibernate API, while still being able to participate in Spring-managed transactions. + [[orm-hibernate-tx-declarative]] -==== Declarative transaction demarcation +==== Declarative Transaction Demarcation -We recommend that you use Spring's declarative transaction support, which enables you to +We recommend that you use Spring's declarative transaction support, which lets you replace explicit transaction demarcation API calls in your Java code with an AOP -transaction interceptor. This transaction interceptor can be configured in a Spring -container using either Java annotations or XML. This declarative transaction capability -allows you to keep business services free of repetitive transaction demarcation code and -to focus on adding business logic, which is the real value of your application. +transaction interceptor. You can configure this transaction interceptor in a Spring +container by using either Java annotations or XML. This declarative transaction capability +lets you keep business services free of repetitive transaction demarcation code and +focus on adding business logic, which is the real value of your application. -[NOTE] -==== -Prior to continuing, you are __strongly__ encouraged to read <> -if you have not done so. -==== +NOTE: Before you continue, we are strongly encourage you to read <> +if you have not already done so. -You may annotate the service layer with `@Transactional` annotations and instruct the +You cN annotate the service layer with `@Transactional` annotations and instruct the Spring container to find these annotations and provide transactional semantics for -these annotated methods. +these annotated methods. The following example shows how to do so: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -5316,11 +5619,13 @@ these annotated methods. } ---- +==== -All you need to set up in the container is the `PlatformTransactionManager` -implementation as a bean as well as a "" entry, -opting into `@Transactional` processing at runtime. +In the container, you need to set up the `PlatformTransactionManager` +implementation (as a bean) and a `` entry, +opting into `@Transactional` processing at runtime. The following example shows how to do so: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5352,20 +5657,23 @@ opting into `@Transactional` processing at runtime. ---- +==== + [[orm-hibernate-tx-programmatic]] -==== Programmatic transaction demarcation +==== Programmatic Transaction Demarcation -You can demarcate transactions in a higher level of the application, on top of such -lower-level data access services spanning any number of operations. Nor do restrictions -exist on the implementation of the surrounding business service; it just needs a Spring +You can demarcate transactions in a higher level of the application, on top of +lower-level data access services that span any number of operations. Nor do restrictions +exist on the implementation of the surrounding business service. It needs only a Spring `PlatformTransactionManager`. Again, the latter can come from anywhere, but preferably -as a bean reference through a `setTransactionManager(..)` method, just as the -`productDAO` should be set by a `setProductDao(..)` method. The following snippets show -a transaction manager and a business service definition in a Spring application context, +as a bean reference through a `setTransactionManager(..)` method. Also, the +`productDAO` should be set by a `setProductDao(..)` method. The following pair of snippets show +a transaction manager and a business service definition in a Spring application context and an example for a business method implementation: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5409,46 +5717,48 @@ and an example for a business method implementation: } } ---- +==== -Spring's `TransactionInterceptor` allows any checked application exception to be thrown +Spring's `TransactionInterceptor` lets any checked application exception be thrown with the callback code, while `TransactionTemplate` is restricted to unchecked exceptions within the callback. `TransactionTemplate` triggers a rollback in case of an -unchecked application exception, or if the transaction is marked rollback-only by the -application (via `TransactionStatus`). `TransactionInterceptor` behaves the same way by -default but allows configurable rollback policies per method. +unchecked application exception or if the transaction is marked rollback-only by the +application (by setting `TransactionStatus`). By default, `TransactionInterceptor` behaves the same way +but allows configurable rollback policies per method. + [[orm-hibernate-tx-strategies]] -==== Transaction management strategies +==== Transaction Management Strategies Both `TransactionTemplate` and `TransactionInterceptor` delegate the actual transaction -handling to a `PlatformTransactionManager` instance, which can be a -`HibernateTransactionManager` (for a single Hibernate `SessionFactory`, using a +handling to a `PlatformTransactionManager` instance (which can be a +`HibernateTransactionManager` (for a single Hibernate `SessionFactory`) by using a `ThreadLocal` `Session` under the hood) or a `JtaTransactionManager` (delegating to the JTA subsystem of the container) for Hibernate applications. You can even use a custom `PlatformTransactionManager` implementation. Switching from native Hibernate transaction -management to JTA, such as when facing distributed transaction requirements for certain -deployments of your application, is just a matter of configuration. Simply replace +management to JTA (such as when facing distributed transaction requirements for certain +deployments of your application) is only a matter of configuration. You can replace the Hibernate transaction manager with Spring's JTA transaction implementation. Both -transaction demarcation and data access code will work without changes, because they -just use the generic transaction management APIs. +transaction demarcation and data access code work without changes, because they +use the generic transaction management APIs. -For distributed transactions across multiple Hibernate session factories, simply combine +For distributed transactions across multiple Hibernate session factories, you can combine `JtaTransactionManager` as a transaction strategy with multiple `LocalSessionFactoryBean` definitions. Each DAO then gets one specific `SessionFactory` reference passed into its corresponding bean property. If all underlying JDBC data sources are transactional container ones, a business service can demarcate transactions across any number of DAOs and any number of session factories without special regard, as -long as it is using `JtaTransactionManager` as the strategy. +long as it uses `JtaTransactionManager` as the strategy. Both `HibernateTransactionManager` and `JtaTransactionManager` allow for proper JVM-level cache handling with Hibernate, without container-specific transaction manager -lookup or a JCA connector (if you are not using EJB to initiate transactions). +lookup or a JCA connector (if you do not use EJB to initiate transactions). `HibernateTransactionManager` can export the Hibernate JDBC `Connection` to plain JDBC -access code, for a specific `DataSource`. This capability allows for high-level +access code for a specific `DataSource`. This ability allows for high-level transaction demarcation with mixed Hibernate and JDBC data access completely without -JTA, if you are accessing only one database. `HibernateTransactionManager` automatically +JTA, provided you access only one database. `HibernateTransactionManager` automatically exposes the Hibernate transaction as a JDBC transaction if you have set up the passed-in `SessionFactory` with a `DataSource` through the `dataSource` property of the `LocalSessionFactoryBean` class. Alternatively, you can specify explicitly the @@ -5456,11 +5766,12 @@ exposes the Hibernate transaction as a JDBC transaction if you have set up the p `dataSource` property of the `HibernateTransactionManager` class. + [[orm-hibernate-resources]] -==== Comparing container-managed and locally defined resources +==== Comparing Container-managed and Locally Defined Resources You can switch between a container-managed JNDI `SessionFactory` and a locally defined -one, without having to change a single line of application code. Whether to keep +one without having to change a single line of application code. Whether to keep resource definitions in the container or locally within the application is mainly a matter of the transaction strategy that you use. Compared to a Spring-defined local `SessionFactory`, a manually registered JNDI `SessionFactory` does not provide any @@ -5468,29 +5779,29 @@ benefits. Deploying a `SessionFactory` through Hibernate's JCA connector provide added value of participating in the Java EE server's management infrastructure, but does not add actual value beyond that. -Spring's transaction support is not bound to a container. Configured with any strategy +Spring's transaction support is not bound to a container. When configured with any strategy other than JTA, transaction support also works in a stand-alone or test environment. Especially in the typical case of single-database transactions, Spring's single-resource local transaction support is a lightweight and powerful alternative to JTA. When you use local EJB stateless session beans to drive transactions, you depend both on an EJB -container and JTA, even if you access only a single database, and only use stateless +container and on JTA, even if you access only a single database and use only stateless session beans to provide declarative transactions through container-managed -transactions. Also, direct use of JTA programmatically requires a Java EE environment as -well. JTA does not involve only container dependencies in terms of JTA itself and of +transactions. Direct use of JTA programmatically also requires a Java EE environment. +JTA does not involve only container dependencies in terms of JTA itself and of JNDI `DataSource` instances. For non-Spring, JTA-driven Hibernate transactions, you have -to use the Hibernate JCA connector, or extra Hibernate transaction code with the +to use the Hibernate JCA connector or extra Hibernate transaction code with the `TransactionManagerLookup` configured for proper JVM-level caching. Spring-driven transactions can work as well with a locally defined Hibernate -`SessionFactory` as they do with a local JDBC `DataSource` if they are accessing a -single database. Thus you only have to use Spring's JTA transaction strategy when you +`SessionFactory` as they do with a local JDBC `DataSource`, provided they access a +single database. Thus, you need only use Spring's JTA transaction strategy when you have distributed transaction requirements. A JCA connector requires container-specific -deployment steps, and obviously JCA support in the first place. This configuration +deployment steps, and (obviously) JCA support in the first place. This configuration requires more work than deploying a simple web application with local resource definitions and Spring-driven transactions. Also, you often need the Enterprise Edition -of your container if you are using, for example, WebLogic Express, which does not -provide JCA. A Spring application with local resources and transactions spanning one -single database works in any Java EE web container (without JTA, JCA, or EJB) such as +of your container if you use, for example, WebLogic Express, which does not +provide JCA. A Spring application with local resources and transactions that span one +single database works in any Java EE web container (without JTA, JCA, or EJB), such as Tomcat, Resin, or even plain Jetty. Additionally, you can easily reuse such a middle tier in desktop applications or test suites. @@ -5498,43 +5809,46 @@ All things considered, if you do not use EJBs, stick with local `SessionFactory` and Spring's `HibernateTransactionManager` or `JtaTransactionManager`. You get all of the benefits, including proper transactional JVM-level caching and distributed transactions, without the inconvenience of container deployment. JNDI registration of a -Hibernate `SessionFactory` through the JCA connector only adds value when used in +Hibernate `SessionFactory` through the JCA connector adds value only when used in conjunction with EJBs. + [[orm-hibernate-invalid-jdbc-access-error]] -==== Spurious application server warnings with Hibernate +==== Spurious Application Server Warnings with Hibernate -In some JTA environments with very strict `XADataSource` implementations -- currently -only some WebLogic Server and WebSphere versions -- when Hibernate is configured without -regard to the JTA `PlatformTransactionManager` object for that environment, it is -possible for spurious warning or exceptions to show up in the application server log. +In some JTA environments with very strict `XADataSource` implementations (currently +only some WebLogic Server and WebSphere versions), when Hibernate is configured without +regard to the JTA `PlatformTransactionManager` object for that environment, +spurious warning or exceptions can show up in the application server log. These warnings or exceptions indicate that the connection being accessed is no longer -valid, or JDBC access is no longer valid, possibly because the transaction is no longer +valid or JDBC access is no longer valid, possibly because the transaction is no longer active. As an example, here is an actual exception from WebLogic: +==== [literal] [subs="verbatim,quotes"] ---- java.sql.SQLException: The transaction is no longer active - status: 'Committed'. No further JDBC access is allowed within this transaction. ---- +==== -You resolve this warning by simply making Hibernate aware of the JTA -`PlatformTransactionManager` instance, to which it will synchronize (along with Spring). +You can resolve this warning by making Hibernate aware of the JTA +`PlatformTransactionManager` instance, to which it synchronizes (along with Spring). You have two options for doing this: -* If in your application context you are already directly obtaining the JTA +* If, in your application context, you already directly obtain the JTA `PlatformTransactionManager` object (presumably from JNDI through - `JndiObjectFactoryBean` or ``) and feeding it, for example, to - Spring's `JtaTransactionManager`, then the easiest way is to specify a reference to - the bean defining this JTA `PlatformTransactionManager` instance as the value of the + `JndiObjectFactoryBean` or ``) and feed it, for example, to + Spring's `JtaTransactionManager`, the easiest way is to specify a reference to + the bean that defines this JTA `PlatformTransactionManager` instance as the value of the `jtaTransactionManager` property for `LocalSessionFactoryBean.` Spring then makes the object available to Hibernate. -* More likely you do not already have the JTA `PlatformTransactionManager` instance, - because Spring's `JtaTransactionManager` can find it itself. Thus you need to +* More likely, you do not already have the JTA `PlatformTransactionManager` instance, + because Spring's `JtaTransactionManager` can find it itself. Thus, you need to configure Hibernate to look up JTA `PlatformTransactionManager` directly. You do this - by configuring an application server- specific `TransactionManagerLookup` class in the + by configuring an application server-specific `TransactionManagerLookup` class in the Hibernate configuration, as described in the Hibernate manual. The remainder of this section describes the sequence of events that occur with and @@ -5545,28 +5859,28 @@ When Hibernate is not configured with any awareness of the JTA * The JTA transaction commits. * Spring's `JtaTransactionManager` is synchronized to the JTA transaction, so it is - called back through an __afterCompletion__ callback by the JTA transaction manager. + called back through an `afterCompletion` callback by the JTA transaction manager. * Among other activities, this synchronization can trigger a callback by Spring to Hibernate, through Hibernate's `afterTransactionCompletion` callback (used to clear - the Hibernate cache), followed by an explicit `close()` call on the Hibernate Session, + the Hibernate cache), followed by an explicit `close()` call on the Hibernate session, which causes Hibernate to attempt to `close()` the JDBC Connection. * In some environments, this `Connection.close()` call then triggers the warning or - error, as the application server no longer considers the `Connection` usable at all, + error, as the application server no longer considers the `Connection` to be usable, because the transaction has already been committed. When Hibernate is configured with awareness of the JTA `PlatformTransactionManager`, the following events occur when a JTA transaction commits: -* the JTA transaction is ready to commit. +* The JTA transaction is ready to commit. * Spring's `JtaTransactionManager` is synchronized to the JTA transaction, so the - transaction is called back through a __beforeCompletion__ callback by the JTA + transaction is called back through a `beforeCompletion` callback by the JTA transaction manager. -* Spring is aware that Hibernate itself is synchronized to the JTA transaction, and +* Spring is aware that Hibernate itself is synchronized to the JTA transaction and behaves differently than in the previous scenario. Assuming the Hibernate `Session` - needs to be closed at all, Spring will close it now. + needs to be closed at all, Spring closes it now. * The JTA transaction commits. * Hibernate is synchronized to the JTA transaction, so the transaction is called back - through an __afterCompletion__ callback by the JTA transaction manager, and can + through an `afterCompletion` callback by the JTA transaction manager and can properly clear its cache. @@ -5577,31 +5891,36 @@ following events occur when a JTA transaction commits: The Spring JPA, available under the `org.springframework.orm.jpa` package, offers comprehensive support for the http://www.oracle.com/technetwork/articles/javaee/jpa-137156.html[Java Persistence -API] in a similar manner to the integration with Hibernate, while being aware of +API] in a manner similar to the integration with Hibernate while being aware of the underlying implementation in order to provide additional features. + [[orm-jpa-setup]] -==== Three options for JPA setup in a Spring environment +==== Three Options for JPA Setup in a Spring Environment The Spring JPA support offers three ways of setting up the JPA `EntityManagerFactory` -that will be used by the application to obtain an entity manager. +that is used by the application to obtain an entity manager. + +* <> +* <> +* <> + + [[orm-jpa-setup-lemfb]] -===== LocalEntityManagerFactoryBean +===== Using `LocalEntityManagerFactoryBean` -[NOTE] -==== -Only use this option in simple deployment environments such as stand-alone applications +You can use this option only in simple deployment environments such as stand-alone applications and integration tests. -==== The `LocalEntityManagerFactoryBean` creates an `EntityManagerFactory` suitable for simple deployment environments where the application uses only JPA for data access. The -factory bean uses the JPA `PersistenceProvider` autodetection mechanism (according to +factory bean uses the JPA `PersistenceProvider` auto-detection mechanism (according to JPA's Java SE bootstrapping) and, in most cases, requires you to specify only the -persistence unit name: +persistence unit name. The following XML example configures such a bean: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5611,27 +5930,28 @@ persistence unit name: ---- +==== This form of JPA deployment is the simplest and the most limited. You cannot refer to an -existing JDBC `DataSource` bean definition and no support for global transactions +existing JDBC `DataSource` bean definition, and no support for global transactions exists. Furthermore, weaving (byte-code transformation) of persistent classes is provider-specific, often requiring a specific JVM agent to specified on startup. This option is sufficient only for stand-alone applications and test environments, for which the JPA specification is designed. + + [[orm-jpa-setup-jndi]] ===== Obtaining an EntityManagerFactory from JNDI -[NOTE] -==== -Use this option when deploying to a Java EE server. Check your server's documentation +You can use this option when deploying to a Java EE server. Check your server's documentation on how to deploy a custom JPA provider into your server, allowing for a different provider than the server's default. -==== Obtaining an `EntityManagerFactory` from JNDI (for example in a Java EE environment), -is simply a matter of changing the XML configuration: +is a matter of changing the XML configuration, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5639,50 +5959,51 @@ is simply a matter of changing the XML configuration: ---- +==== -This action assumes standard Java EE bootstrapping: the Java EE server autodetects +This action assumes standard Java EE bootstrapping. The Java EE server auto-detects persistence units (in effect, `META-INF/persistence.xml` files in application jars) and `persistence-unit-ref` entries in the Java EE deployment descriptor (for example, `web.xml`) and defines environment naming context locations for those persistence units. In such a scenario, the entire persistence unit deployment, including the weaving (byte-code transformation) of persistent classes, is up to the Java EE server. The JDBC -`DataSource` is defined through a JNDI location in the `META-INF/persistence.xml` file; -EntityManager transactions are integrated with the server's JTA subsystem. Spring merely +`DataSource` is defined through a JNDI location in the `META-INF/persistence.xml` file. +`EntityManager` transactions are integrated with the server's JTA subsystem. Spring merely uses the obtained `EntityManagerFactory`, passing it on to application objects through -dependency injection, and managing transactions for the persistence unit, typically -through `JtaTransactionManager`. +dependency injection and managing transactions for the persistence unit (typically +through `JtaTransactionManager`). -If multiple persistence units are used in the same application, the bean names of such +If you use multiple persistence units in the same application, the bean names of such JNDI-retrieved persistence units should match the persistence unit names that the -application uses to refer to them, for example, in `@PersistenceUnit` and -`@PersistenceContext` annotations. +application uses to refer to them (for example, in `@PersistenceUnit` and +`@PersistenceContext` annotations). + + [[orm-jpa-setup-lcemfb]] -===== LocalContainerEntityManagerFactoryBean +===== Using `LocalContainerEntityManagerFactoryBean` -[NOTE] -==== -Use this option for full JPA capabilities in a Spring-based application environment. -This includes web containers such as Tomcat as well as stand-alone applications and +You can use this option for full JPA capabilities in a Spring-based application environment. +This includes web containers such as Tomcat, stand-alone applications, and integration tests with sophisticated persistence requirements. -If you'd like to specifically configure a Hibernate setup, an immediate alternative is -to go with Hibernate 5.2/5.3 and set up a native Hibernate `LocalSessionFactoryBean` +NOTE: If you want to specifically configure a Hibernate setup, an immediate alternative is +to go with Hibernate 5.2 or 5.3 and set up a native Hibernate `LocalSessionFactoryBean` instead of a plain JPA `LocalContainerEntityManagerFactoryBean`, letting it interact with JPA access code as well as native Hibernate access code. See <> for details. -==== The `LocalContainerEntityManagerFactoryBean` gives full control over `EntityManagerFactory` configuration and is appropriate for environments where fine-grained customization is required. The `LocalContainerEntityManagerFactoryBean` creates a `PersistenceUnitInfo` instance based on the `persistence.xml` file, the -supplied `dataSourceLookup` strategy, and the specified `loadTimeWeaver`. It is thus +supplied `dataSourceLookup` strategy, and the specified `loadTimeWeaver`. It is, thus, possible to work with custom data sources outside of JNDI and to control the weaving process. The following example shows a typical bean definition for a `LocalContainerEntityManagerFactoryBean`: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5695,9 +6016,11 @@ process. The following example shows a typical bean definition for a ---- +==== The following example shows a typical `persistence.xml` file: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5708,16 +6031,14 @@ The following example shows a typical `persistence.xml` file: ---- - -[NOTE] ==== -The `` shortcut indicates that __no__ scanning for -annotated entity classes is supposed to occur. An explicit 'true' value specified - -`true` - also means no scan. -`false` does trigger a scan; -however, it is recommended to simply omit the `exclude-unlisted-classes` element + +NOTE: The `` shortcut indicates that no scanning for +annotated entity classes is supposed to occur. An explicit 'true' value +(`true`) also means no scan. +`false` does trigger a scan. +However, we recommend omitting the `exclude-unlisted-classes` element if you want entity class scanning to occur. -==== Using the `LocalContainerEntityManagerFactoryBean` is the most powerful JPA setup option, allowing for flexible local configuration within the application. It supports @@ -5729,47 +6050,48 @@ byte-code transformation. This option may conflict with the built-in JPA capabilities of a Java EE server. In a full Java EE environment, consider obtaining your `EntityManagerFactory` from JNDI. Alternatively, specify a custom `persistenceXmlLocation` on your -`LocalContainerEntityManagerFactoryBean` definition, for example, -META-INF/my-persistence.xml, and only include a descriptor with that name in your -application jar files. Because the Java EE server only looks for default -`META-INF/persistence.xml` files, it ignores such custom persistence units and hence -avoid conflicts with a Spring-driven JPA setup upfront. (This applies to Resin 3.1, for +`LocalContainerEntityManagerFactoryBean` definition (for example, +META-INF/my-persistence.xml) and include only a descriptor with that name in your +application jar files. Because the Java EE server looks only for default +`META-INF/persistence.xml` files, it ignores such custom persistence units and, hence, +avoids conflicts with a Spring-driven JPA setup upfront. (This applies to Resin 3.1, for example.) .When is load-time weaving required? **** Not all JPA providers require a JVM agent. Hibernate is an example of one that does not. If your provider does not require an agent or you have other alternatives, such as -applying enhancements at build time through a custom compiler or an ant task, the -load-time weaver __should not__ be used. +applying enhancements at build time through a custom compiler or an Ant task, you should not use the +load-time weaver. **** -The `LoadTimeWeaver` interface is a Spring-provided class that allows JPA -`ClassTransformer` instances to be plugged in a specific manner, depending whether the +The `LoadTimeWeaver` interface is a Spring-provided class that lets JPA +`ClassTransformer` instances be plugged in a specific manner, depending on whether the environment is a web container or application server. Hooking `ClassTransformers` through an http://docs.oracle.com/javase/6/docs/api/java/lang/instrument/package-summary.html[agent] -typically is not efficient. The agents work against the __entire virtual machine__ and -inspect __every__ class that is loaded, which is usually undesirable in a production +is typically not efficient. The agents work against the entire virtual machine and +inspect every class that is loaded, which is usually undesirable in a production server environment. Spring provides a number of `LoadTimeWeaver` implementations for various environments, -allowing `ClassTransformer` instances to be applied only __per class loader__ and not -per VM. +letting `ClassTransformer` instances be applied only for each class loader and not +for each VM. -Refer to <> in the AOP chapter for +See <> in the AOP chapter for more insight regarding the `LoadTimeWeaver` implementations and their setup, either generic or customized to various platforms (such as Tomcat, WebLogic, GlassFish, -Resin and JBoss). - -As described in the aforementioned section, you can configure a context-wide -`LoadTimeWeaver` using the `@EnableLoadTimeWeaving` annotation of -`context:load-time-weaver` XML element. Such a global weaver is picked up by all JPA -`LocalContainerEntityManagerFactoryBeans` automatically. This is the preferred way of -setting up a load-time weaver, delivering autodetection of the platform (WebLogic, -GlassFish, Tomcat, Resin, JBoss or VM agent) and automatic propagation of the weaver to +Resin, and JBoss). + +As described in <>, you can configure a context-wide +`LoadTimeWeaver` by using the `@EnableLoadTimeWeaving` annotation of the +`context:load-time-weaver` XML element. Such a global weaver is automatically picked up by all JPA +`LocalContainerEntityManagerFactoryBean` instances. The following example shows the preferred way of +setting up a load-time weaver, delivering auto-detection of the platform (WebLogic, +GlassFish, Tomcat, Resin, JBoss, or VM agent) and automatic propagation of the weaver to all weaver-aware beans: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5778,10 +6100,12 @@ all weaver-aware beans: ... ---- +==== -However, if needed, one can manually specify a dedicated weaver through the -`loadTimeWeaver` property: +However, you can, if needed, manually specify a dedicated weaver through the +`loadTimeWeaver` property, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5791,23 +6115,28 @@ However, if needed, one can manually specify a dedicated weaver through the ---- +==== + +No matter how the LTW is configured, by using this technique, JPA applications relying on +instrumentation can run in the target platform (for example, Tomcat) without needing an agent. +This is especially important when the hosting applications rely on different JPA +implementations, because the JPA transformers are applied only at the class-loader level and +are, thus, isolated from each other. + -No matter how the LTW is configured, using this technique, JPA applications relying on -instrumentation can run in the target platform (ex: Tomcat) without needing an agent. -This is important especially when the hosting applications rely on different JPA -implementations because the JPA transformers are applied only at class loader level and -thus are isolated from each other. [[orm-jpa-setup-multiple]] -===== Dealing with multiple persistence units +===== Dealing with Multiple Persistence Units -For applications that rely on multiple persistence units locations, stored in various -JARS in the classpath, for example, Spring offers the `PersistenceUnitManager` to act as +For applications that rely on multiple persistence units locations (stored in various +JARS in the classpath, for example), Spring offers the `PersistenceUnitManager` to act as a central repository and to avoid the persistence units discovery process, which can be -expensive. The default implementation allows multiple locations to be specified that are +expensive. The default implementation lets multiple locations be specified. These locations are parsed and later retrieved through the persistence unit name. (By default, the classpath -is searched for `META-INF/persistence.xml` files.) +is searched for `META-INF/persistence.xml` files.) The following example configures +multiple locations: +==== [source,xml,indent=0] [subs="verbatim"] ---- @@ -5834,20 +6163,24 @@ is searched for `META-INF/persistence.xml` files.) ---- +==== -The default implementation allows customization of the `PersistenceUnitInfo` instances, -before they are fed to the JPA provider, declaratively through its properties, which -affect __all__ hosted units, or programmatically, through the -`PersistenceUnitPostProcessor`, which allows persistence unit selection. If no +The default implementation allows customization of the `PersistenceUnitInfo` instances +(before they are fed to the JPA provider) either declaratively (through its properties, which +affect all hosted units) or programmatically (through the +`PersistenceUnitPostProcessor`, which allows persistence unit selection). If no `PersistenceUnitManager` is specified, one is created and used internally by `LocalContainerEntityManagerFactoryBean`. + + [[orm-jpa-setup-background]] -===== Background bootstrapping +===== Background Bootstrapping `LocalContainerEntityManagerFactoryBean` supports background bootstrapping through -the `bootstrapExecutor` property: +the `bootstrapExecutor` property, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5857,34 +6190,34 @@ the `bootstrapExecutor` property: ---- +==== -The actual JPA provider bootstrapping will be handed off to the specified executor then, -running in parallel to the application bootstrap thread. The exposed `EntityManagerFactory` -proxy can be injected into other application components and is even able to respond +The actual JPA provider bootstrapping is handed off to the specified executor and then, +running in parallel, to the application bootstrap thread. The exposed `EntityManagerFactory` +proxy can be injected into other application components and is even able to respond to `EntityManagerFactoryInfo` configuration inspection. However, once the actual JPA provider -is being accessed by other components, e.g. calling `createEntityManager`, those calls -will block until the background bootstrapping has completed. In particular, when using +is being accessed by other components (for example, calling `createEntityManager`), those calls +block until the background bootstrapping has completed. In particular, when you use Spring Data JPA, make sure to set up deferred bootstrapping for its repositories as well. + [[orm-jpa-dao]] -==== Implementing DAOs based on JPA: EntityManagerFactory and EntityManager +==== Implementing DAOs Based on JPA: `EntityManagerFactory` and `EntityManager` -[NOTE] -==== -Although `EntityManagerFactory` instances are thread-safe, `EntityManager` instances are +NOTE: Although `EntityManagerFactory` instances are thread-safe, `EntityManager` instances are not. The injected JPA `EntityManager` behaves like an `EntityManager` fetched from an application server's JNDI environment, as defined by the JPA specification. It delegates -all calls to the current transactional `EntityManager`, if any; otherwise, it falls back +all calls to the current transactional `EntityManager`, if any. Otherwise, it falls back to a newly created `EntityManager` per operation, in effect making its usage thread-safe. -==== It is possible to write code against the plain JPA without any Spring dependencies, by -using an injected `EntityManagerFactory` or `EntityManager`. Spring can understand -`@PersistenceUnit` and `@PersistenceContext` annotations both at field and method level -if a `PersistenceAnnotationBeanPostProcessor` is enabled. A plain JPA DAO implementation -using the `@PersistenceUnit` annotation might look like this: +using an injected `EntityManagerFactory` or `EntityManager`. Spring can understand the +`@PersistenceUnit` and `@PersistenceContext` annotations both at the field and the method level +if a `PersistenceAnnotationBeanPostProcessor` is enabled. The following example shows a plain JPA DAO implementation +that uses the `@PersistenceUnit` annotation: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -5912,11 +6245,13 @@ using the `@PersistenceUnit` annotation might look like this: } } ---- +==== -The DAO above has no dependency on Spring and still fits nicely into a Spring +The preceding DAO has no dependency on Spring and still fits nicely into a Spring application context. Moreover, the DAO takes advantage of annotations to require the -injection of the default `EntityManagerFactory`: +injection of the default `EntityManagerFactory`, as the following example bean definition shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5929,13 +6264,17 @@ injection of the default `EntityManagerFactory`: ---- +==== -As an alternative to defining a `PersistenceAnnotationBeanPostProcessor` explicitly, +As an alternative to explicitly defining a `PersistenceAnnotationBeanPostProcessor`, consider using the Spring `context:annotation-config` XML element in your application context configuration. Doing so automatically registers all Spring standard post-processors for annotation-based configuration, including `CommonAnnotationBeanPostProcessor` and so on. +Consider the following example: + +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -5948,12 +6287,14 @@ post-processors for annotation-based configuration, including ---- +==== The main problem with such a DAO is that it always creates a new `EntityManager` through the factory. You can avoid this by requesting a transactional `EntityManager` (also -called "shared EntityManager" because it is a shared, thread-safe proxy for the actual -transactional EntityManager) to be injected instead of the factory: +called a "`shared EntityManager`" because it is a shared, thread-safe proxy for the actual +transactional EntityManager) to be injected instead of the factory. The following example shows how to do so: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -5969,25 +6310,26 @@ transactional EntityManager) to be injected instead of the factory: } } ---- +==== -The `@PersistenceContext` annotation has an optional attribute `type`, which defaults to -`PersistenceContextType.TRANSACTION`. This default is what you need to receive a shared -EntityManager proxy. The alternative, `PersistenceContextType.EXTENDED`, is a completely -different affair: This results in a so-called extended EntityManager, which is __not -thread-safe__ and hence must not be used in a concurrently accessed component such as a -Spring-managed singleton bean. Extended EntityManagers are only supposed to be used in +The `@PersistenceContext` annotation has an optional attribute called `type`, which defaults to +`PersistenceContextType.TRANSACTION`. You can use this default to receive a shared +`EntityManager` proxy. The alternative, `PersistenceContextType.EXTENDED`, is a completely +different affair. This results in a so-called extended `EntityManager`, which is not +thread-safe and, hence, must not be used in a concurrently accessed component, such as a +Spring-managed singleton bean. Extended `EntityManager` instances are only supposed to be used in stateful components that, for example, reside in a session, with the lifecycle of the -EntityManager not tied to a current transaction but rather being completely up to the +`EntityManager` not tied to a current transaction but rather being completely up to the application. .Method- and field-level Injection **** -Annotations that indicate dependency injections (such as `@PersistenceUnit` and -`@PersistenceContext`) can be applied on field or methods inside a class, hence the -expressions __method-level injection__ and __field-level injection__. Field-level -annotations are concise and easier to use while method-level allows for further -processing of the injected dependency. In both cases the member visibility (public, -protected, private) does not matter. +You can apply annotations that indicate dependency injections (such as `@PersistenceUnit` and +`@PersistenceContext`) on field or methods inside a class -- hence the +expressions "`method-level injection`" and "`field-level injection`". Field-level +annotations are concise and easier to use while method-level annotations allow for further +processing of the injected dependency. In both cases, the member visibility (public, +protected, or private) does not matter. What about class-level annotations? @@ -5995,216 +6337,222 @@ On the Java EE platform, they are used for dependency declaration and not for re injection. **** -The injected `EntityManager` is Spring-managed (aware of the ongoing transaction). It is -important to note that even though the new DAO implementation uses method level +The injected `EntityManager` is Spring-managed (aware of the ongoing transaction). +Even though the new DAO implementation uses method-level injection of an `EntityManager` instead of an `EntityManagerFactory`, no change is -required in the application context XML due to annotation usage. +required in the application context XML, due to annotation usage. -The main advantage of this DAO style is that it only depends on Java Persistence API; no +The main advantage of this DAO style is that it depends only on the Java Persistence API. No import of any Spring class is required. Moreover, as the JPA annotations are understood, the injections are applied automatically by the Spring container. This is appealing from -a non-invasiveness perspective, and might feel more natural to JPA developers. +a non-invasiveness perspective and can feel more natural to JPA developers. + [[orm-jpa-tx]] ==== Spring-driven JPA transactions -[NOTE] -==== -You are __strongly__ encouraged to read <> if you have not done -so, to get a more detailed coverage of Spring's declarative transaction support. -==== +NOTE: We strongly encourag you to read <>, if you have not already done +so, to get more detailed coverage of Spring's declarative transaction support. -The recommended strategy for JPA is local transactions via JPA's native transaction +The recommended strategy for JPA is local transactions through JPA's native transaction support. Spring's `JpaTransactionManager` provides many capabilities known from local -JDBC transactions, such as transaction-specific isolation levels and resource-level -read-only optimizations, against any regular JDBC connection pool (no XA requirement). +JDBC transactions (such as transaction-specific isolation levels and resource-level +read-only optimizations) against any regular JDBC connection pool (no XA requirement). -Spring JPA also allows a configured `JpaTransactionManager` to expose a JPA transaction +Spring JPA also lets a configured `JpaTransactionManager` expose a JPA transaction to JDBC access code that accesses the same `DataSource`, provided that the registered -`JpaDialect` supports retrieval of the underlying JDBC `Connection`. Out of the box, +`JpaDialect` supports retrieval of the underlying JDBC `Connection`. Spring provides dialects for the EclipseLink and Hibernate JPA implementations. -See the next section for details on the `JpaDialect` mechanism. +See the <> for details on the `JpaDialect` mechanism. -[NOTE] -==== -As an immediate alternative, Spring's native `HibernateTransactionManager` is capable +NOTE: As an immediate alternative, Spring's native `HibernateTransactionManager` is capable of interacting with JPA access code as of Spring Framework 5.1 and Hibernate 5.2/5.3, -adapting to several Hibernate specifics and providing JDBC interaction out of the box. +adapting to several Hibernate specifics and providing JDBC interaction. This makes particular sense in combination with `LocalSessionFactoryBean` setup. -See <> for details. -==== +See <> for details. + [[orm-jpa-dialect]] -==== JpaDialect and JpaVendorAdapter +==== Understanding `JpaDialect` and `JpaVendorAdapter` -As an advanced feature `JpaTransactionManager` and subclasses of -`AbstractEntityManagerFactoryBean` support a custom `JpaDialect`, to be passed into the -`jpaDialect` bean property. A `JpaDialect` implementation can enable some advanced +As an advanced feature, `JpaTransactionManager` and subclasses of +`AbstractEntityManagerFactoryBean` allow a custom `JpaDialect` to be passed into the +`jpaDialect` bean property. A `JpaDialect` implementation can enable the following advanced features supported by Spring, usually in a vendor-specific manner: -* Applying specific transaction semantics such as custom isolation level or transaction +* Applying specific transaction semantics (such as custom isolation level or transaction timeout) -* Retrieving the transactional JDBC `Connection` for exposure to JDBC-based DAOs) +* Retrieving the transactional JDBC `Connection` (for exposure to JDBC-based DAOs) * Advanced translation of `PersistenceExceptions` to Spring `DataAccessExceptions` This is particularly valuable for special transaction semantics and for advanced -translation of exception. The default implementation used (`DefaultJpaDialect`) does -not provide any special capabilities and if the above features are required, you have +translation of exception. The default implementation (`DefaultJpaDialect`) does +not provide any special abilities and, if the features listed earlier are required, you have to specify the appropriate dialect. -[TIP] -==== -As an even broader provider adaptation facility primarily for Spring's full-featured +TIP: As an even broader provider adaptation facility primarily for Spring's full-featured `LocalContainerEntityManagerFactoryBean` setup, `JpaVendorAdapter` combines the capabilities of `JpaDialect` with other provider-specific defaults. Specifying a `HibernateJpaVendorAdapter` or `EclipseLinkJpaVendorAdapter` is the most convenient way of auto-configuring an `EntityManagerFactory` setup for Hibernate or EclipseLink, respectively. Note that those provider adapters are primarily designed for use with -Spring-driven transaction management, i.e. for use with `JpaTransactionManager`. -==== +Spring-driven transaction management (that is, for use with `JpaTransactionManager`). -See the `JpaDialect` and `JpaVendorAdapter` javadocs for more details of its operations +See the {api-spring-framework}/orm/jpa/JpaDialect.html[`JpaDialect`] and {api-spring-framework}/orm/jpa/JpaVendorAdapter.html[`JpaVendorAdapter`] Javadoc for more details of its operations and how they are used within Spring's JPA support. + [[orm-jpa-jta]] -==== Setting up JPA with JTA transaction management +==== Setting up JPA with JTA Transaction Management As an alternative to `JpaTransactionManager`, Spring also allows for multi-resource -transaction coordination via JTA, either in a Java EE environment or with a -standalone transaction coordinator such as Atomikos. Aside from choosing Spring's -`JtaTransactionManager` instead of `JpaTransactionManager`, there are a few further -steps to take: +transaction coordination through JTA, either in a Java EE environment or with a +stand-alone transaction coordinator, such as Atomikos. Aside from choosing Spring's +`JtaTransactionManager` instead of `JpaTransactionManager`, you need to take few further +steps: -* The underlying JDBC connection pools need to be XA-capable and integrated with +* The underlying JDBC connection pools need to be XA-capable and be integrated with your transaction coordinator. This is usually straightforward in a Java EE environment, -simply exposing a different kind of `DataSource` via JNDI. Check your application server +exposing a different kind of `DataSource` through JNDI. See your application server documentation for details. Analogously, a standalone transaction coordinator usually -comes with special XA-integrated `DataSource` implementations; again, check its docs. +comes with special XA-integrated `DataSource` implementations. Again, check its documentation. * The JPA `EntityManagerFactory` setup needs to be configured for JTA. This is -provider-specific, typically via special properties to be specified as "jpaProperties" +provider-specific, typically through special properties to be specified as `jpaProperties` on `LocalContainerEntityManagerFactoryBean`. In the case of Hibernate, these properties -are even version-specific; please check your Hibernate documentation for details. - -* Spring's `HibernateJpaVendorAdapter` enforces certain Spring-oriented defaults such -as the connection release mode "on-close" which matches Hibernate's own default in -Hibernate 5.0 but not anymore in 5.1/5.2. For a JTA setup, either do not declare -`HibernateJpaVendorAdapter` to begin with, or turn off its `prepareConnection` flag. -Alternatively, set Hibernate 5.2's "hibernate.connection.handling_mode" property to -"DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT" to restore Hibernate's own default. +are even version-specific. See your Hibernate documentation for details. + +* Spring's `HibernateJpaVendorAdapter` enforces certain Spring-oriented defaults, such +as the connection release mode, `on-close`, which matches Hibernate's own default in +Hibernate 5.0 but not any more in 5.1/5.2. For a JTA setup, either do not declare +`HibernateJpaVendorAdapter` to begin with or turn off its `prepareConnection` flag. +Alternatively, set Hibernate 5.2's `hibernate.connection.handling_mode` property to +`DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT` to restore Hibernate's own default. See <> for a related note about WebLogic. * Alternatively, consider obtaining the `EntityManagerFactory` from your application -server itself, i.e. via a JNDI lookup instead of a locally declared -`LocalContainerEntityManagerFactoryBean`. A server-provided `EntityManagerFactory` -might require special definitions in your server configuration, making the deployment -less portable, but will be set up for the server's JTA environment out of the box. +server itself (that is, through a JNDI lookup instead of a locally declared +`LocalContainerEntityManagerFactoryBean`). A server-provided `EntityManagerFactory` +might require special definitions in your server configuration (making the deployment +less portable) but is set up for the server's JTA environment. + [[orm-jpa-hibernate]] -==== Native Hibernate setup and native Hibernate transactions for JPA interaction +==== Native Hibernate Setup and Native Hibernate Transactions for JPA Interaction As of Spring Framework 5.1 and Hibernate 5.2/5.3, a native `LocalSessionFactoryBean` setup in combination with `HibernateTransactionManager` allows for interaction with -`@PersistenceContext` and other JPA access code out of the box. A Hibernate -`SessionFactory` natively implements JPA's `EntityManagerFactory` interface now, -and a Hibernate `Session` handle natively is a JPA `EntityManager` as well. -Spring's JPA support facilities automatically detect native Hibernate Sessions. +`@PersistenceContext` and other JPA access code. A Hibernate +`SessionFactory` natively implements JPA's `EntityManagerFactory` interface now +and a Hibernate `Session` handle natively is a JPA `EntityManager`. +Spring's JPA support facilities automatically detect native Hibernate sessions. -Such native Hibernate setup can therefore serve as a replacement for a standard JPA +Such native Hibernate setup can, therefore, serve as a replacement for a standard JPA `LocalContainerEntityManagerFactoryBean` and `JpaTransactionManager` combination in many scenarios, allowing for interaction with `SessionFactory.getCurrentSession()` (and also `HibernateTemplate`) next to `@PersistenceContext EntityManager` within the same local transaction. Such a setup also provides stronger Hibernate integration -and more configuration flexibility, not being constrained by JPA bootstrap contracts. +and more configuration flexibility, because it is not constrained by JPA bootstrap contracts. -There is no need for `HibernateJpaVendorAdapter` configuration in such a scenario -since Spring's native Hibernate setup provides even more features out of the box: -e.g. custom Hibernate Integrator setup, Hibernate 5.3 bean container integration, -as well as stronger optimizations for read-only transactions. Last but not least, -native Hibernate setup can also be expressed through `LocalSessionFactoryBuilder`, +You do not need `HibernateJpaVendorAdapter` configuration in such a scenario, +since Spring's native Hibernate setup provides even more features +(for example, custom Hibernate Integrator setup, Hibernate 5.3 bean container integration, +and stronger optimizations for read-only transactions). Last but not least, you can also +express native Hibernate setup through `LocalSessionFactoryBuilder`, seamlessly integrating with `@Bean` style configuration (no `FactoryBean` involved). [NOTE] ==== `LocalSessionFactoryBean` and `LocalSessionFactoryBuilder` support background -bootstrapping, just like the JPA `LocalContainerEntityManagerFactoryBean`. -See <> for an introduction. +bootstrapping, just as the JPA `LocalContainerEntityManagerFactoryBean` does. +See <> for an introduction. -On `LocalSessionFactoryBean`, this is available through the "bootstrapExecutor" -property; on the programmatic `LocalSessionFactoryBuilder`, there is an overloaded -`buildSessionFactory` method which takes a bootstrap executor argument. +On `LocalSessionFactoryBean`, this is available through the `bootstrapExecutor` +property. On the programmatic `LocalSessionFactoryBuilder`, an overloaded +`buildSessionFactory` method takes a bootstrap executor argument. ==== - [[oxm]] -== Marshalling XML using O/X Mappers +== Marshalling XML by Using Object-XML Mappers [[oxm-introduction]] === Introduction -In this chapter, we will describe Spring's Object/XML Mapping support. Object/XML -Mapping, or O/X mapping for short, is the act of converting an XML document to and from +This chapter, describes Spring's Object-XML Mapping support. Object-XML +Mapping (O-X mapping for short) is the act of converting an XML document to and from an object. This conversion process is also known as XML Marshalling, or XML Serialization. This chapter uses these terms interchangeably. -Within the field of O/X mapping, a __marshaller__ is responsible for serializing an -object (graph) to XML. In similar fashion, an __unmarshaller__ deserializes the XML to +Within the field of O-X mapping, a marshaller is responsible for serializing an +object (graph) to XML. In similar fashion, an unmarshaller deserializes the XML to an object graph. This XML can take the form of a DOM document, an input or output stream, or a SAX handler. Some of the benefits of using Spring for your O/X mapping needs are: +* <> +* <> +* <> + + +[[oxm-ease-of-configuration]] ==== Ease of configuration Spring's bean factory makes it easy to configure marshallers, without needing to -construct JAXB context, JiBX binding factories, etc. The marshallers can be configured -as any other bean in your application context. Additionally, XML namespace-based +construct JAXB context, JiBX binding factories, and so on. You can configure the marshallers +as you would any other bean in your application context. Additionally, XML namespace-based configuration is available for a number of marshallers, making the configuration even simpler. -==== Consistent interfaces -Spring's O/X mapping operates through two global interfaces: the `Marshaller` and -`Unmarshaller` interface. These abstractions allow you to switch O/X mapping frameworks -with relative ease, with little or no changes required on the classes that do the +[[oxm-consistent-interfaces]] +==== Consistent Interfaces + +Spring's O-X mapping operates through two global interfaces: {api-spring-framework}/oxm/Marshaller.html[`Marshaller`] and +{api-spring-framework}/oxm/Unmarshaller.html[`Unmarshaller`]. These abstractions let you switch O-X mapping frameworks +with relative ease, with little or no change required on the classes that do the marshalling. This approach has the additional benefit of making it possible to do XML -marshalling with a mix-and-match approach (e.g. some marshalling performed using JAXB, -other using Castor) in a non-intrusive fashion, leveraging the strength of each +marshalling with a mix-and-match approach (for example, some marshalling performed using JAXB +and some by Castor) in a non-intrusive fashion, letting you use the strength of each technology. -==== Consistent exception hierarchy -Spring provides a conversion from exceptions from the underlying O/X mapping tool to its -own exception hierarchy with the `XmlMappingException` as the root exception. As can be -expected, these runtime exceptions wrap the original exception so no information is lost. +[[oxm-consistent-exception-hierarchy]] +==== Consistent Exception Hierarchy + +Spring provides a conversion from exceptions from the underlying O-X mapping tool to its +own exception hierarchy with the `XmlMappingException` as the root exception. +These runtime exceptions wrap the original exception so that no information is lost. [[oxm-marshaller-unmarshaller]] -=== Marshaller and Unmarshaller +=== `Marshaller` and `Unmarshaller` -As stated in the introduction, a __marshaller__ serializes an object to XML, and an -__unmarshaller__ deserializes XML stream to an object. In this section, we will describe +As stated in the <>, a marshaller serializes an object to XML, and an +unmarshaller deserializes XML stream to an object. This section describes the two Spring interfaces used for this purpose. + [[oxm-marshaller]] -==== Marshaller +==== Understanding `Marshaller` Spring abstracts all marshalling operations behind the -`org.springframework.oxm.Marshaller` interface, the main method of which is shown below. +`org.springframework.oxm.Marshaller` interface, the main method of which follows: +==== [source,java,indent=0] [subs="verbatim"] ---- @@ -6216,11 +6564,12 @@ Spring abstracts all marshalling operations behind the void marshal(Object graph, Result result) throws XmlMappingException, IOException; } ---- +==== The `Marshaller` interface has one main method, which marshals the given object to a -given `javax.xml.transform.Result`. Result is a tagging interface that basically -represents an XML output abstraction: concrete implementations wrap various XML -representations, as indicated in the table below. +given `javax.xml.transform.Result`. The result is a tagging interface that basically +represents an XML output abstraction. Concrete implementations wrap various XML +representations, as the following table indicates: [[oxm-marshller-tbl]] |=== @@ -6236,22 +6585,21 @@ representations, as indicated in the table below. | `java.io.File`, `java.io.OutputStream`, or `java.io.Writer` |=== -[NOTE] -==== -Although the `marshal()` method accepts a plain object as its first parameter, most +NOTE: Although the `marshal()` method accepts a plain object as its first parameter, most `Marshaller` implementations cannot handle arbitrary objects. Instead, an object class -must be mapped in a mapping file, marked with an annotation, registered with the -marshaller, or have a common base class. Refer to the further sections in this chapter -to determine how your O/X technology of choice manages this. -==== +must be mapped in a mapping file, be marked with an annotation, be registered with the +marshaller, or have a common base class. Refer to the later sections in this chapter +to determine how your O-X technology manages this. + [[oxm-unmarshaller]] -==== Unmarshaller +==== Understanding `Unmarshaller` -Similar to the `Marshaller`, there is the `org.springframework.oxm.Unmarshaller` -interface. +Similar to the `Marshaller`, we have the `org.springframework.oxm.Unmarshaller` +interface, which the following listing shows: +==== [source,java,indent=0] [subs="verbatim"] ---- @@ -6263,11 +6611,12 @@ interface. Object unmarshal(Source source) throws XmlMappingException, IOException; } ---- +==== This interface also has one method, which reads from the given -`javax.xml.transform.Source` (an XML input abstraction), and returns the object read. As -with Result, Source is a tagging interface that has three concrete implementations. Each -wraps a different XML representation, as indicated in the table below. +`javax.xml.transform.Source` (an XML input abstraction) and returns the object read. As +with `Result`, `Source` is a tagging interface that has three concrete implementations. Each +wraps a different XML representation, as the following table indicates: [[oxm-unmarshller-tbl]] |=== @@ -6284,37 +6633,37 @@ wraps a different XML representation, as indicated in the table below. |=== Even though there are two separate marshalling interfaces ( `Marshaller` and -`Unmarshaller`), all implementations found in Spring-WS implement both in one class. +`Unmarshaller`), all implementations in Spring-WS implement both in one class. This means that you can wire up one marshaller class and refer to it both as a -marshaller and an unmarshaller in your `applicationContext.xml`. +marshaller and as an unmarshaller in your `applicationContext.xml`. + [[oxm-xmlmappingexception]] -==== XmlMappingException +==== Understanding `XmlMappingException` -Spring converts exceptions from the underlying O/X mapping tool to its own exception -hierarchy with the `XmlMappingException` as the root exception. As can be expected, -these runtime exceptions wrap the original exception so no information will be lost. +Spring converts exceptions from the underlying O-X mapping tool to its own exception +hierarchy with the `XmlMappingException` as the root exception. +These runtime exceptions wrap the original exception so that no information will be lost. Additionally, the `MarshallingFailureException` and `UnmarshallingFailureException` provide a distinction between marshalling and unmarshalling operations, even though the -underlying O/X mapping tool does not do so. +underlying O-X mapping tool does not do so. -The O/X Mapping exception hierarchy is shown in the following figure: +The O-X Mapping exception hierarchy is shown in the following figure: image::images/oxm-exceptions.png[] -O/X Mapping exception hierarchy - [[oxm-usage]] -=== Using Marshaller and Unmarshaller +=== Using `Marshaller` and `Unmarshaller` -Spring's OXM can be used for a wide variety of situations. In the following example, we -will use it to marshal the settings of a Spring-managed application as an XML file. We -will use a simple JavaBean to represent the settings: +You can use Spring's OXM for a wide variety of situations. In the following example, we +use it to marshal the settings of a Spring-managed application as an XML file. In the following example, we +use a simple JavaBean to represent the settings: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -6331,12 +6680,14 @@ will use a simple JavaBean to represent the settings: } } ---- +==== The application class uses this bean to store its settings. Besides a main method, the class has two methods: `saveSettings()` saves the settings bean to a file named -`settings.xml`, and `loadSettings()` loads these settings again. A `main()` method -constructs a Spring application context, and calls these two methods. +`settings.xml`, and `loadSettings()` loads these settings again. The following `main()` method +constructs a Spring application context and calls these two methods: +==== [source,java,indent=0] [subs="verbatim,quotes"] ---- @@ -6398,10 +6749,12 @@ constructs a Spring application context, and calls these two methods. } } ---- +==== -The `Application` requires both a `marshaller` and `unmarshaller` property to be set. We -can do so using the following `applicationContext.xml`: +The `Application` requires both a `marshaller` and an `unmarshaller` property to be set. We +can do so by using the following `applicationContext.xml`: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -6413,55 +6766,63 @@ can do so using the following `applicationContext.xml`: ---- +==== This application context uses Castor, but we could have used any of the other marshaller -instances described later in this chapter. Note that Castor does not require any further -configuration by default, so the bean definition is rather simple. Also note that the +instances described later in this chapter. Note that, by default, Castor does not require any further +configuration, so the bean definition is rather simple. Also note that the `CastorMarshaller` implements both `Marshaller` and `Unmarshaller`, so we can refer to the `castorMarshaller` bean in both the `marshaller` and `unmarshaller` property of the application. This sample application produces the following `settings.xml` file: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- ---- +==== [[oxm-schema-based-config]] -=== XML configuration namespace +=== XML Configuration Namespace -Marshallers could be configured more concisely using tags from the OXM namespace. To -make these tags available, the appropriate schema has to be referenced first in the -preamble of the XML configuration file. Note the 'oxm' related text below: +You can configure marshallers more concisely by using tags from the OXM namespace. To +make these tags available, you must first reference the appropriate schema in the +preamble of the XML configuration file. The following example shows how to do so: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- + xmlns:oxm="http://www.springframework.org/schema/oxm" xsi:schemaLocation="http://www.springframework.org/schema/beans <1> http://www.springframework.org/schema/beans/spring-beans.xsd **http://www.springframework.org/schema/oxm http://www.springframework.org/schema/oxm/spring-oxm.xsd"**> ---- +<1> Reference the `oxm` schema. +==== -Currently, the following tags are available: +Currently, the schema makes the following elements available: * <> * <> * <> -Each tag will be explained in its respective marshaller's section. As an example though, -here is how the configuration of a JAXB2 marshaller might look like: +Each tag is explained in its respective marshaller's section. As an example, though, +the configuration of a JAXB2 marshaller might resemble the following: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- ---- +==== @@ -6478,16 +6839,18 @@ The corresponding integration classes reside in the `org.springframework.oxm.jax package. + [[oxm-jaxb2]] -==== Jaxb2Marshaller +==== Using `Jaxb2Marshaller` -The `Jaxb2Marshaller` class implements both the Spring `Marshaller` and `Unmarshaller` -interface. It requires a context path to operate, which you can set using the -`contextPath` property. The context path is a list of colon (:) separated Java package +The `Jaxb2Marshaller` class implements both of Spring's `Marshaller` and `Unmarshaller` +interfaces. It requires a context path to operate. You can set the context path by setting the +`contextPath` property. The context path is a list of colon-separated Java package names that contain schema derived classes. It also offers a `classesToBeBound` property, which allows you to set an array of classes to be supported by the marshaller. Schema -validation is performed by specifying one or more schema resource to the bean, like so: +validation is performed by specifying one or more schema resources to the bean, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -6506,22 +6869,28 @@ validation is performed by specifying one or more schema resource to the bean, l ---- +==== + + [[oxm-jaxb2-xsd]] -===== XML configuration namespace +===== XML Configuration Namespace -The `jaxb2-marshaller` tag configures a `org.springframework.oxm.jaxb.Jaxb2Marshaller`. -Here is an example: +The `jaxb2-marshaller` element configures a `org.springframework.oxm.jaxb.Jaxb2Marshaller`, +as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- ---- +==== -Alternatively, the list of classes to bind can be provided to the marshaller via the -`class-to-be-bound` child tag: +Alternatively, you can provide the list of classes to bind to the marshaller by using the +`class-to-be-bound` child element: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -6531,19 +6900,20 @@ Alternatively, the list of classes to bind can be provided to the marshaller via ... ---- +==== -Available attributes are: +The following table describes the available attributes: |=== | Attribute| Description| Required | `id` -| the id of the marshaller -| no +| The ID of the marshaller +| No | `contextPath` -| the JAXB Context path -| no +| The JAXB Context path +| No |=== @@ -6551,22 +6921,24 @@ Available attributes are: [[oxm-castor]] === Castor -Castor XML mapping is an open source XML binding framework. It allows you to transform -the data contained in a java object model into/from an XML document. By default, it does -not require any further configuration, though a mapping file can be used to have more +Castor XML mapping is an open source XML binding framework. It lets you transform +the data contained in a Java object model to and from an XML document. By default, it does +not require any further configuration, though you can use a mapping file to have more control over the behavior of Castor. -For more information on Castor, refer to the -http://castor-data-binding.github.io/castor[__Castor web site__]. The Spring +For more information on Castor, see the +http://castor-data-binding.github.io/castor[Castor web site]. The Spring integration classes reside in the `org.springframework.oxm.castor` package. + [[oxm-castor-marshaller]] -==== CastorMarshaller +==== Using `CastorMarshaller` As with JAXB, the `CastorMarshaller` implements both the `Marshaller` and `Unmarshaller` interface. It can be wired up as follows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -6575,19 +6947,22 @@ interface. It can be wired up as follows: ... ---- +==== + [[oxm-castor-mapping]] ==== Mapping Although it is possible to rely on Castor's default marshalling behavior, it might be -necessary to have more control over it. This can be accomplished using a Castor mapping -file. For more information, refer to http://castor-data-binding.github.io/castor/reference-guides/1.3.3/html-single/index.html#xml.mapping[Castor +necessary to have more control over it. You can get more control by using a Castor mapping +file. For more information, see http://castor-data-binding.github.io/castor/reference-guides/1.3.3/html-single/index.html#xml.mapping[Castor XML Mapping]. -The mapping can be set using the `mappingLocation` resource property, indicated below -with a classpath resource. +You can set the mapping by using the `mappingLocation` resource property, indicated in the following example +with a classpath resource: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -6597,52 +6972,57 @@ with a classpath resource. ---- +==== + + [[oxm-castor-xsd]] -===== XML configuration namespace +===== XML Configuration Namespace The `castor-marshaller` tag configures a -`org.springframework.oxm.castor.CastorMarshaller`. Here is an example: +`org.springframework.oxm.castor.CastorMarshaller`, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- ---- +==== -The marshaller instance can be configured in two ways, by specifying either the location -of a mapping file (through the `mapping-location` property), or by identifying Java +You can configure the marshaller instance in two ways: by specifying either the location +of a mapping file (through the `mapping-location` property) or by identifying Java POJOs (through the `target-class` or `target-package` properties) for which there exist corresponding XML descriptor classes. The latter way is usually used in conjunction with XML code generation from XML schemas. -Available attributes are: +The following table describes the available attributes: |=== | Attribute| Description| Required | `id` -| the id of the marshaller -| no +| The ID of the marshaller +| No | `encoding` -| the encoding to use for unmarshalling from XML -| no +| The encoding to use for unmarshalling from XML +| No | `target-class` -| a Java class name for a POJO for which an XML class descriptor is available (as +| A Java class name for a POJO for which an XML class descriptor is available (as generated through code generation) -| no +| No | `target-package` -| a Java package name that identifies a package that contains POJOs and their +| A Java package name that identifies a package that contains POJOs and their corresponding Castor XML descriptor classes (as generated through code generation from XML schemas) -| no +| No | `mapping-location` -| location of a Castor XML mapping file -| no +| Location of a Castor XML mapping file +| No |=== @@ -6650,25 +7030,27 @@ Available attributes are: [[oxm-jibx]] === JiBX -The JiBX framework offers a solution similar to that which Hibernate provides for ORM: a +The JiBX framework offers a solution similar to that which Hibernate provides for ORM: A binding definition defines the rules for how your Java objects are converted to or from XML. After preparing the binding and compiling the classes, a JiBX binding compiler -enhances the class files, and adds code to handle converting instances of the classes +enhances the class files and adds code to handle converting instances of the classes from or to XML. -For more information on JiBX, refer to the http://jibx.sourceforge.net/[__JiBX web -site__]. The Spring integration classes reside in the `org.springframework.oxm.jibx` +For more information on JiBX, see the http://jibx.sourceforge.net/[JiBX web +site]. The Spring integration classes reside in the `org.springframework.oxm.jibx` package. + [[oxm-jibx-marshaller]] -==== JibxMarshaller +==== Using `JibxMarshaller` The `JibxMarshaller` class implements both the `Marshaller` and `Unmarshaller` interface. To operate, it requires the name of the class to marshal in, which you can -set using the `targetClass` property. Optionally, you can set the binding name using the -`bindingName` property. In the next sample, we bind the `Flights` class: +set using the `targetClass` property. Optionally, you can set the binding name by setting the +`bindingName` property. In the following example, we bind the `Flights` class: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -6679,39 +7061,44 @@ set using the `targetClass` property. Optionally, you can set the binding name u ... ---- +==== A `JibxMarshaller` is configured for a single class. If you want to marshal multiple -classes, you have to configure multiple ``JibxMarshaller``s with different `targetClass` +classes, you have to configure multiple `JibxMarshaller` instances with different `targetClass` property values. + + [[oxm-jibx-xsd]] -===== XML configuration namespace +===== XML Configuration Namespace -The `jibx-marshaller` tag configures a `org.springframework.oxm.jibx.JibxMarshaller`. -Here is an example: +The `jibx-marshaller` tag configures a `org.springframework.oxm.jibx.JibxMarshaller`, +as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- ---- +==== -Available attributes are: +The following table describes the available attributes: |=== | Attribute| Description| Required | `id` -| the id of the marshaller -| no +| The ID of the marshaller +| No | `target-class` -| the target class for this marshaller -| yes +| The target class for this marshaller +| Yes | `bindingName` -| the binding name used by this marshaller -| no +| The binding name used by this marshaller +| No |=== @@ -6720,20 +7107,22 @@ Available attributes are: === XStream XStream is a simple library to serialize objects to XML and back again. It does not -require any mapping, and generates clean XML. +require any mapping and generates clean XML. -For more information on XStream, refer to the http://x-stream.github.io/[__XStream -web site__]. The Spring integration classes reside in the +For more information on XStream, see the http://x-stream.github.io/[XStream +web site]. The Spring integration classes reside in the `org.springframework.oxm.xstream` package. + [[oxm-xstream-marshaller]] -==== XStreamMarshaller +==== Using `XStreamMarshaller` -The `XStreamMarshaller` does not require any configuration, and can be configured in an -application context directly. To further customize the XML, you can set an__alias map__, -which consists of string aliases mapped to classes: +The `XStreamMarshaller` does not require any configuration and can be configured in an +application context directly. To further customize the XML, you can set an alias map, +which consists of string aliases mapped to classes, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -6748,17 +7137,19 @@ which consists of string aliases mapped to classes: ... ---- +==== [WARNING] -==== -By default, XStream allows for arbitrary classes to be unmarshalled, which can lead to -unsafe Java serialization effects. As such, it is __not recommended to use the -`XStreamMarshaller` to unmarshal XML from external sources__ (i.e. the Web), as this can -result in __security vulnerabilities__. +===== +By default, XStream lets arbitrary classes be unmarshalled, which can lead to +unsafe Java serialization effects. As such, we do not recommend using the +`XStreamMarshaller` to unmarshal XML from external sources (that is, the Web), as this can +result in security vulnerabilities. If you choose to use the `XStreamMarshaller` to unmarshal XML from an external source, -set the `supportedClasses` property on the `XStreamMarshaller`, like as follows: +set the `supportedClasses` property on the `XStreamMarshaller`, as the following example shows: +==== [source,xml,indent=0] [subs="verbatim,quotes"] ---- @@ -6767,8 +7158,9 @@ set the `supportedClasses` property on the `XStreamMarshaller`, like as follows: ... ---- +==== -This will make sure that only the registered classes are eligible for unmarshalling. +Doing so ensures that only the registered classes are eligible for unmarshalling. Additionally, you can register {api-spring-framework}/oxm/xstream/XStreamMarshaller.html#setConverters(com.thoughtworks.xstream.converters.ConverterMatcher...)[custom @@ -6777,13 +7169,12 @@ want to add a `CatchAllConverter` as the last converter in the list, in addition converters that explicitly support the domain classes that should be supported. As a result, default XStream converters with lower priorities and possible security vulnerabilities do not get invoked. -==== +===== NOTE: Note that XStream is an XML serialization library, not a data binding library. -Therefore, it has limited namespace support. As such, it is rather unsuitable for usage +Therefore, it has limited namespace support. As a result, it is rather unsuitable for usage within Web services. - include::data-access-appendix.adoc[leveloffset=+1]