root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

JPA/Hibernate docs: transaction management, JTA setup 

Issue: SPR-14957
This commit is contained in:
Juergen Hoeller 2016-12-08 18:24:12 +01:00
parent 05579fd1b9
commit 2f80b8485a
2 changed files with 102 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
spring-orm/src/main/java/org/springframework/orm/jpa/vendor/HibernateJpaVendorAdapter.java vendored
View File

@ -78,11 +78,16 @@ public class HibernateJpaVendorAdapter extends AbstractJpaVendorAdapter {
* JDBC Connection.
* <p>See {@link HibernateJpaDialect#setPrepareConnection(boolean)} for details.
* This is just a convenience flag passed through to {@code HibernateJpaDialect}.
* <p>On Hibernate 5.2, this flag remains {@code true} by default like against
* <p>On Hibernate 5.1/5.2, this flag remains {@code true} by default like against
* previous Hibernate versions. The vendor adapter manually enforces Hibernate's
* new connection handling mode {@code DELAYED_ACQUISITION_AND_HOLD} in that case
* unless a user-specified connection handling mode property indicates otherwise;
* switch this flag to {@code false} to avoid that interference.
* <p><b>NOTE: Per the explanation above, you may have to turn this flag off
* when using Hibernate in a JTA environment, e.g. on WebLogic.</b> Alternatively,
* set Hibernate 5.2's "hibernate.connection.handling_mode" property to
* "DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION" or even
* "DELAYED_ACQUISITION_AND_RELEASE_AFTER_STATEMENT" in such a scenario.
* @since 4.3.1
* @see #getJpaPropertyMap()
* @see HibernateJpaDialect#beginTransaction

329
src/asciidoc/data-access.adoc
View File

@ -686,9 +686,8 @@ case, the `txManager` bean.
[TIP]
====
You can omit the `transaction-manager` attribute in the transactional advice (
`<tx:advice/>`) if the bean name of the `PlatformTransactionManager` that you want to
You can omit the `transaction-manager` attribute in the transactional advice
(`<tx: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`
attribute explicitly, as in the preceding example.
@ -1950,7 +1949,6 @@ transaction in which it has been published as committed successfully:
public void handleOrderCreatedEvent(CreationEvent<Order> creationEvent) {
...
}
}
----
@ -1994,9 +1992,9 @@ explicitly; rather, they are chosen automatically, with the standard
==== 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,
which is available in WebSphere Application Server 6.0.2.19 and later and 6.1.0.9 and
later. With this adapter, Spring-driven transaction suspension (suspend/resume as
initiated by `PROPAGATION_REQUIRES_NEW`) is officially supported by IBM!
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
`PROPAGATION_REQUIRES_NEW`) is officially supported by IBM.
@ -4795,7 +4793,7 @@ https://jira.spring.io/browse/SPR[jira.spring.io].
[[jdbc-intializing-datasource]]
[[jdbc-initializing-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
@ -4942,6 +4940,7 @@ The second option can also be easy. Some suggestions on how to implement this in
[[orm]]
== Object Relational Mapping (ORM) Data Access
@ -5125,9 +5124,10 @@ chapter will then cover the other ORM technologies, showing briefer examples the
[NOTE]
====
As of Spring 4.0, Spring requires Hibernate 3.6 or later. Note that the Hibernate team
stopped supporting Hibernate 3 years ago and even phased out support for Hibernate 4.x
in late 2015. We therefore recommend Hibernate 5.1 and higher from a 2016+ perspective.
As of Spring 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.0 anymore and is likely
to focus on 5.2+ exclusively soon.
====
@ -5272,7 +5272,7 @@ able to participate in Spring-managed transactions.
We recommend that you use Spring's declarative transaction support, which enables you to
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
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.
@ -5282,83 +5282,9 @@ Prior to continuing, you are __strongly__ encouraged to read <<transaction-decla
if you have not done so.
====
Furthermore, transaction semantics like propagation behavior and isolation level can be
changed in a configuration file and do not affect the business service implementations.
The following example shows how you can configure an AOP transaction interceptor, using
XML, for a simple service class:
[source,xml,indent=0]
[subs="verbatim"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:aop="http://www.springframework.org/schema/aop"
xmlns:tx="http://www.springframework.org/schema/tx"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop.xsd">
<!-- SessionFactory, DataSource, etc. omitted -->
<bean id="transactionManager"
class="org.springframework.orm.hibernate5.HibernateTransactionManager">
<property name="sessionFactory" ref="sessionFactory"/>
</bean>
<aop:config>
<aop:pointcut id="productServiceMethods"
expression="execution(* product.ProductService.*(..))"/>
<aop:advisor advice-ref="txAdvice" pointcut-ref="productServiceMethods"/>
</aop:config>
<tx:advice id="txAdvice" transaction-manager="myTxManager">
<tx:attributes>
<tx:method name="increasePrice*" propagation="REQUIRED"/>
<tx:method name="someOtherBusinessMethod" propagation="REQUIRES_NEW"/>
<tx:method name="*" propagation="SUPPORTS" read-only="true"/>
</tx:attributes>
</tx:advice>
<bean id="myProductService" class="product.SimpleProductService">
<property name="productDao" ref="myProductDao"/>
</bean>
</beans>
----
This is the service class that is advised:
[source,java,indent=0]
[subs="verbatim,quotes"]
----
public class ProductServiceImpl implements ProductService {
private ProductDao productDao;
public void setProductDao(ProductDao productDao) {
this.productDao = productDao;
}
// notice the absence of transaction demarcation code in this method
// Spring's declarative transaction infrastructure will be demarcating
// transactions on your behalf
public void increasePriceOfAllProductsInCategory(final String category) {
List productsToChange = this.productDao.loadProductsByCategory(category);
// ...
}
}
----
We also show an attribute-support based configuration, in the following example. You
annotate the service layer with @Transactional annotations and instruct the Spring
container to find these annotations and provide transactional semantics for these
annotated methods.
You may annotate the service layer with `@Transactional` annotations and instruct the
Spring container to find these annotations and provide transactional semantics for
these annotated methods.
[source,java,indent=0]
[subs="verbatim,quotes"]
@ -5385,10 +5311,9 @@ annotated methods.
}
----
As you can see from the following configuration example, the configuration is much
simplified, compared to the XML example above, while still providing the same
functionality driven by the annotations in the service layer code. All you need to
provide is the TransactionManager implementation and a "<tx:annotation-driven/>" entry.
All you need to set up in the container is the `PlatformTransactionManager`
implementation as a bean as well as a "<tx:annotation-driven/>" entry,
opting into `@Transactional` processing at runtime.
[source,xml,indent=0]
[subs="verbatim,quotes"]
@ -5510,78 +5435,6 @@ sources are transactional container ones, a business service can demarcate trans
across any number of DAOs and any number of session factories without special regard, as
long as it is using `JtaTransactionManager` as the strategy.
[source,xml,indent=0]
[subs="verbatim"]
----
<beans>
<jee:jndi-lookup id="dataSource1" jndi-name="java:comp/env/jdbc/myds1"/>
<jee:jndi-lookup id="dataSource2" jndi-name="java:comp/env/jdbc/myds2"/>
<bean id="mySessionFactory1"
class="org.springframework.orm.hibernate5.LocalSessionFactoryBean">
<property name="dataSource" ref="myDataSource1"/>
<property name="mappingResources">
<list>
<value>product.hbm.xml</value>
</list>
</property>
<property name="hibernateProperties">
<value>
hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.show_sql=true
</value>
</property>
</bean>
<bean id="mySessionFactory2"
class="org.springframework.orm.hibernate5.LocalSessionFactoryBean">
<property name="dataSource" ref="myDataSource2"/>
<property name="mappingResources">
<list>
<value>inventory.hbm.xml</value>
</list>
</property>
<property name="hibernateProperties">
<value>
hibernate.dialect=org.hibernate.dialect.OracleDialect
</value>
</property>
</bean>
<bean id="myTxManager" class="org.springframework.transaction.jta.JtaTransactionManager"/>
<bean id="myProductDao" class="product.ProductDaoImpl">
<property name="sessionFactory" ref="mySessionFactory1"/>
</bean>
<bean id="myInventoryDao" class="product.InventoryDaoImpl">
<property name="sessionFactory" ref="mySessionFactory2"/>
</bean>
<bean id="myProductService" class="product.ProductServiceImpl">
<property name="productDao" ref="myProductDao"/>
<property name="inventoryDao" ref="myInventoryDao"/>
</bean>
<aop:config>
<aop:pointcut id="productServiceMethods"
expression="execution(* product.ProductService.*(..))"/>
<aop:advisor advice-ref="txAdvice" pointcut-ref="productServiceMethods"/>
</aop:config>
<tx:advice id="txAdvice" transaction-manager="myTxManager">
<tx:attributes>
<tx:method name="increasePrice*" propagation="REQUIRED"/>
<tx:method name="someOtherBusinessMethod" propagation="REQUIRES_NEW"/>
<tx:method name="*" propagation="SUPPORTS" read-only="true"/>
</tx:attributes>
</tx:advice>
</beans>
----
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).
@ -5767,12 +5620,12 @@ the JPA specification is designed.
[NOTE]
====
Use this option when deploying to a Java EE 5 server. Check your server's documentation
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 5 environment),
Obtaining an `EntityManagerFactory` from JNDI (for example in a Java EE environment),
is simply a matter of changing the XML configuration:
[source,xml,indent=0]
@ -5783,7 +5636,7 @@ is simply a matter of changing the XML configuration:
</beans>
----
This action assumes standard Java EE 5 bootstrapping: the Java EE server autodetects
This action assumes standard Java EE bootstrapping: the Java EE server autodetects
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.
@ -5864,20 +5717,20 @@ so on. However, it also imposes requirements on the runtime environment, such as
availability of a weaving-capable class loader if the persistence provider demands
byte-code transformation.
This option may conflict with the built-in JPA capabilities of a Java EE 5 server. In a
full Java EE 5 environment, consider obtaining your `EntityManagerFactory` from JNDI.
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 5 server only looks for default
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
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
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.
****
@ -5936,7 +5789,7 @@ implementations because the JPA transformers are applied only at class loader le
thus are isolated from each other.
[[orm-jpa-multiple-pu]]
[[orm-jpa-multiple]]
===== 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
@ -5981,8 +5834,8 @@ affect __all__ hosted units, or programmatically, through the
[[orm-jpa-straight]]
==== Implementing DAOs based on plain JPA
[[orm-jpa-dao]]
==== Implementing DAOs based on JPA: EntityManagerFactory and EntityManager
[NOTE]
====
Although `EntityManagerFactory` instances are thread-safe, `EntityManager` instances are
@ -6104,7 +5957,7 @@ protected, private) does not matter.
What about class-level annotations?
On the Java EE 5 platform, they are used for dependency declaration and not for resource
On the Java EE platform, they are used for dependency declaration and not for resource
injection.
****
@ -6121,58 +5974,21 @@ a non-invasiveness perspective, and might feel more natural to JPA developers.
[[orm-jpa-tx]]
==== Transaction Management
==== Spring-driven JPA transactions
[NOTE]
====
You are __strongly__ encouraged to read <<transaction-declarative>> if you have not done
so, to get a more detailed coverage of Spring's declarative transaction support.
====
To execute service operations within transactions, you can use Spring's common
declarative transaction facilities. For example:
The recommended strategy for JPA is local transactions via 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).
[source,xml,indent=0]
[subs="verbatim"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:aop="http://www.springframework.org/schema/aop"
xmlns:tx="http://www.springframework.org/schema/tx"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx.xsd
http://www.springframework.org/schema/aop
http://www.springframework.org/schema/aop/spring-aop.xsd">
<bean id="myTxManager" class="org.springframework.orm.jpa.JpaTransactionManager">
<property name="entityManagerFactory" ref="myEmf"/>
</bean>
<bean id="myProductService" class="product.ProductServiceImpl">
<property name="productDao" ref="myProductDao"/>
</bean>
<aop:config>
<aop:pointcut id="productServiceMethods" expression="execution(* product.ProductService.*(..))"/>
<aop:advisor advice-ref="txAdvice" pointcut-ref="productServiceMethods"/>
</aop:config>
<tx:advice id="txAdvice" transaction-manager="myTxManager">
<tx:attributes>
<tx:method name="increasePrice*" propagation="REQUIRED"/>
<tx:method name="someOtherBusinessMethod" propagation="REQUIRES_NEW"/>
<tx:method name="*" propagation="SUPPORTS" read-only="true"/>
</tx:attributes>
</tx:advice>
</beans>
----
Spring JPA allows a configured `JpaTransactionManager` to expose a JPA transaction to
JDBC access code that accesses the same JDBC `DataSource`, provided that the registered
Spring JPA also allows a configured `JpaTransactionManager` to 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,
Spring provides dialects for the EclipseLink and Hibernate JPA implementations.
See the next section for details on the `JpaDialect` mechanism.
@ -6180,7 +5996,7 @@ See the next section for details on the `JpaDialect` mechanism.
[[orm-jpa-dialect]]
==== JpaDialect
==== JpaDialect and JpaVendorAdapter
As an advanced feature `JpaTransactionManager` and subclasses of
`AbstractEntityManagerFactoryBean` support a custom `JpaDialect`, to be passed into the
@ -6193,12 +6009,61 @@ features supported by Spring, usually in a vendor-specific manner:
* 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 to
specify the appropriate dialect.
translation of exception. The default implementation used (`DefaultJpaDialect`) does
not provide any special capabilities and if the above features are required, you have
to specify the appropriate dialect.
[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`.
====
See the `JpaDialect` and `JpaVendorAdapter` javadocs 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
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:
* The underlying JDBC connection pools need to be XA-capable and 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
documentation for details. Analogously, a standalone transaction coordinator usually
comes with special XA-integrated `DataSource` implementations; again, check its docs.
* The JPA `EntityManagerFactory` setup needs to be configured for JTA. This is
provider-specific, typically via 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.
See <<orm-hibernate-invalid-jdbc-access-error>> 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.
See the `JpaDialect` javadocs for more details of its operations and how they are used
within Spring's JPA support.
[[oxm]]
@ -6260,8 +6125,7 @@ the two Spring interfaces used for this purpose.
[[oxm-marshaller]]
==== Marshaller
Spring abstracts all marshalling operations behind the
`org.springframework.oxm.Marshaller` interface, the main methods of which is listed
below.
`org.springframework.oxm.Marshaller` interface, the main method of which is shown below.
[source,java,indent=0]
[subs="verbatim"]
@ -6269,10 +6133,9 @@ below.
public interface Marshaller {
/**
* Marshals the object graph with the given root into the provided Result.
* Marshal the object graph with the given root into the provided Result.
*/
void marshal(Object graph, Result result) throws XmlMappingException, IOException;
}
----
@ -6317,7 +6180,7 @@ interface.
public interface Unmarshaller {
/**
* Unmarshals the given provided Source into an object graph.
* Unmarshal the given provided Source into an object graph.
*/
Object unmarshal(Source source) throws XmlMappingException, IOException;
}