Java Doc for HibernateTransactionManager.java in  » J2EE » spring-framework-2.0.6 » org » springframework » orm » hibernate3 » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Supports custom isolation levels, and timeouts that get applied as Hibernate transaction timeouts (on Hibernate 3.1+) or as appropriate query timeouts (on Hibernate 3.0, when using HibernateTemplate ).

This transaction manager is appropriate for applications that use a single Hibernate SessionFactory for transactional data access, but it also supports direct DataSource access within a transaction (i.e. plain JDBC code working with the same DataSource). This allows for mixing services which access Hibernate and services which use plain JDBC (without being aware of Hibernate)! Application code needs to stick to the same simple Connection lookup pattern as with org.springframework.jdbc.datasource.DataSourceTransactionManager (i.e. org.springframework.jdbc.datasource.DataSourceUtils.getConnection or going through a org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy ).

Note: To be able to register a DataSource's Connection for plain JDBC code, this instance needs to be aware of the DataSource ( HibernateTransactionManager.setDataSource ). The given DataSource should obviously match the one used by the given SessionFactory. To achieve this, configure both to the same JNDI DataSource, or preferably create the SessionFactory with LocalSessionFactoryBean and a local DataSource (which will be autodetected by this transaction manager).

JTA (usually through org.springframework.transaction.jta.JtaTransactionManager ) is necessary for accessing multiple transactional resources within the same transaction. The DataSource that Hibernate uses needs to be JTA-enabled in such a scenario (see container setup). Normally, JTA setup for Hibernate is somewhat container-specific due to the JTA TransactionManager lookup, required for proper transactional handling of the SessionFactory-level read-write cache.

Fortunately, there is an easier way with Spring: SessionFactoryUtils (and thus HibernateTemplate ) registers synchronizations with Spring's org.springframework.transaction.support.TransactionSynchronizationManager (as used by org.springframework.transaction.jta.JtaTransactionManager ), for proper after-completion callbacks. Therefore, as long as Spring's JtaTransactionManager drives the JTA transactions, Hibernate does not require any special configuration for proper JTA participation. Note that there are special restrictions with EJB CMT and restrictive JTA subsystems: See org.springframework.transaction.jta.JtaTransactionManager 's javadoc for details.

On JDBC 3.0, this transaction manager supports nested transactions via JDBC 3.0 Savepoints. The HibernateTransactionManager.setNestedTransactionAllowed "nestedTransactionAllowed"} flag defaults to "false", though, as nested transactions will just apply to the JDBC Connection, not to the Hibernate Session and its cached objects. You can manually set the flag to "true" if you want to use nested transactions for JDBC access code which participates in Hibernate transactions (provided that your JDBC driver supports Savepoints). Note that Hibernate itself does not support nested transactions! Hence, do not expect Hibernate access code to semantically participate in a nested transaction.

Requires Hibernate 3.0.3 or later. As of Spring 2.0, this transaction manager autodetects Hibernate 3.1 and uses its advanced timeout functionality, while remaining compatible with Hibernate 3.0 as well. Running against Hibernate 3.1.3+ is recommended, unless you need to remain compatible with JDK 1.3. (Note that Hibernate 3.1+ only runs on JDK 1.4+!)
author:
   Juergen Hoeller
since:
   1.2
See Also:   HibernateTransactionManager.setSessionFactory
See Also:   HibernateTransactionManager.setDataSource
See Also:   LocalSessionFactoryBean
See Also:   SessionFactoryUtils.getSession
See Also:   SessionFactoryUtils.applyTransactionTimeout
See Also:   SessionFactoryUtils.releaseSession
See Also:   HibernateTemplate
See Also:   org.hibernate.SessionFactory.getCurrentSession
See Also:   org.springframework.jdbc.datasource.DataSourceUtils.getConnection
See Also:   org.springframework.jdbc.datasource.DataSourceUtils.applyTransactionTimeout
See Also:   org.springframework.jdbc.datasource.DataSourceUtils.releaseConnection
See Also:   org.springframework.jdbc.core.JdbcTemplate
See Also:   org.springframework.jdbc.datasource.DataSourceTransactionManager
See Also:   org.springframework.transaction.jta.JtaTransactionManager

If the SessionFactory was configured with LocalDataSourceConnectionProvider, i.e.

Such an interceptor can either be set at the SessionFactory level, i.e.

Requires the bean factory to be known, to be able to resolve the bean name to an interceptor instance on session creation.

Default is "true".

Will automatically apply a specified SQLExceptionTranslator to a Hibernate JDBCException, else rely on Hibernate's default translation.
Parameters:
  ex - HibernateException that occured a corresponding DataAccessException
See Also:   SessionFactoryUtils.convertHibernateAccessException
See Also:   HibernateTransactionManager.setJdbcExceptionTranslator

Creates a default org.springframework.jdbc.support.SQLErrorCodeSQLExceptionTranslator for the SessionFactory's underlying DataSource.

Default implementation checks the Session's connection release mode to be "on_close". Unfortunately, this requires casting to SessionImpl, as of Hibernate 3.0/3.1. If that cast doesn't work, we'll simply assume we're safe and return true.
Parameters:
  session - the Hibernate Session to check
See Also:   org.hibernate.impl.SessionImpl.getConnectionReleaseMode
See Also:   org.hibernate.ConnectionReleaseMode.ON_CLOSE

Can be turned off to deliberately ignore an available DataSource, to not expose Hibernate transactions as JDBC transactions for that DataSource.
See Also:   HibernateTransactionManager.setDataSource
See Also:   LocalSessionFactoryBean.setDataSource

If the SessionFactory was configured with LocalDataSourceConnectionProvider, i.e. by Spring's LocalSessionFactoryBean with a specified "dataSource", the DataSource will be auto-detected: You can still explictly specify the DataSource, but you don't need to in this case.

A transactional JDBC Connection for this DataSource will be provided to application code accessing this DataSource directly via DataSourceUtils or JdbcTemplate. The Connection will be taken from the Hibernate Session.

The DataSource specified here should be the target DataSource to manage transactions for, not a TransactionAwareDataSourceProxy. Only data access code may work with TransactionAwareDataSourceProxy, while the transaction manager needs to work on the underlying target DataSource. If there's nevertheless a TransactionAwareDataSourceProxy passed in, it will be unwrapped to extract its target DataSource.
See Also:   HibernateTransactionManager.setAutodetectDataSource
See Also:   LocalDataSourceConnectionProvider
See Also:   LocalSessionFactoryBean.setDataSource
See Also:   org.springframework.jdbc.datasource.TransactionAwareDataSourceProxy
See Also:   org.springframework.jdbc.datasource.DataSourceUtils
See Also:   org.springframework.jdbc.core.JdbcTemplate

Such an interceptor can either be set at the SessionFactory level, i.e. on LocalSessionFactoryBean, or at the Session level, i.e. on HibernateTemplate, HibernateInterceptor, and HibernateTransactionManager. It's preferable to set it on LocalSessionFactoryBean or HibernateTransactionManager to avoid repeated configuration and guarantee consistent behavior in transactions.
See Also:   LocalSessionFactoryBean.setEntityInterceptor
See Also:   HibernateTemplate.setEntityInterceptor
See Also:   HibernateInterceptor.setEntityInterceptor

Requires the bean factory to be known, to be able to resolve the bean name to an interceptor instance on session creation. Typically used for prototype interceptors, i.e. a new interceptor instance per session.

Can also be used for shared interceptor instances, but it is recommended to set the interceptor reference directly in such a scenario.
Parameters:
  entityInterceptorBeanName - the name of the entity interceptor inthe bean factory
See Also:   HibernateTransactionManager.setBeanFactory
See Also:   HibernateTransactionManager.setEntityInterceptor

Applied to any SQLException root cause of a Hibernate JDBCException that is thrown on flush, overriding Hibernate's default SQLException translation (which is based on Hibernate's Dialect for a specific target database).
Parameters:
  jdbcExceptionTranslator - the exception translator
See Also:   java.sql.SQLException
See Also:   org.hibernate.JDBCException
See Also:   org.springframework.jdbc.support.SQLErrorCodeSQLExceptionTranslator
See Also:   org.springframework.jdbc.support.SQLStateSQLExceptionTranslator

Default is "true". If you turn this flag off, the transaction manager will not support per-transaction isolation levels anymore. It will not call Connection.setReadOnly(true) for read-only transactions anymore either. If this flag is turned off, no cleanup of a JDBC Connection is required after a transaction, since no Connection settings will get modified.

It is recommended to turn this flag off if running against Hibernate 3.1 and a connection pool that does not reset connection settings (for example, Jakarta Commons DBCP). To keep this flag turned on, you can set the "hibernate.connection.release_mode" property to "on_close" instead, or consider using a smarter connection pool (for example, C3P0).
See Also:   java.sql.Connection.setTransactionIsolation
See Also:   java.sql.Connection.setReadOnly