The Spring Framework

## org.springframework.orm.hibernate3
Class SessionFactoryUtils

    java.lang.Object
      org.springframework.orm.hibernate3.SessionFactoryUtils

    public abstract class SessionFactoryUtils

extends Object

Helper class featuring methods for Hibernate Session handling, allowing for reuse of Hibernate Session instances within transactions. Also provides support for exception translation.

Supports synchronization with both Spring-managed JTA transactions (see `JtaTransactionManager`) and non-Spring JTA transactions (i.e. plain JTA or EJB CMT), transparently providing transaction-scoped Hibernate Sessions. Note that for non-Spring JTA transactions, a JTA TransactionManagerLookup has to be specified in the Hibernate configuration.

Used internally by `HibernateTemplate`, `HibernateInterceptor` and `HibernateTransactionManager`. Can also be used directly in application code.

Since:
  1.2
Author:
  Juergen Hoeller
See Also:
  `getSession(org.hibernate.SessionFactory, boolean)`, `releaseSession(org.hibernate.Session, org.hibernate.SessionFactory)`, `HibernateTransactionManager`, `JtaTransactionManager`, `TransactionSynchronizationManager`

Field Summary
`static int` `SESSION_SYNCHRONIZATION_ORDER` Order value for TransactionSynchronization objects that clean up Hibernate Sessions.

Constructor Summary
`SessionFactoryUtils()`

Method Summary
`static void` `applyTransactionTimeout(Criteria criteria, SessionFactory sessionFactory)` Apply the current transaction timeout, if any, to the given Hibernate Criteria object.
`static void` `applyTransactionTimeout(Query query, SessionFactory sessionFactory)` Apply the current transaction timeout, if any, to the given Hibernate Query object.
`static void` `closeSession(Session session)` Perform actual closing of the Hibernate Session, catching and logging any cleanup exceptions thrown.
`static DataAccessException` `convertHibernateAccessException(HibernateException ex)` Convert the given HibernateException to an appropriate exception from the `org.springframework.dao` hierarchy.
`static Session` `doGetSession(SessionFactory sessionFactory, boolean allowCreate)` Get a Hibernate Session for the given SessionFactory.
`static DataSource` `getDataSource(SessionFactory sessionFactory)` Determine the DataSource of the given SessionFactory.
`static TransactionManager` `getJtaTransactionManager(SessionFactory sessionFactory, Session session)` Try to retrieve the JTA TransactionManager from the given SessionFactory and/or Session.
`static Session` `getNewSession(SessionFactory sessionFactory)` Get a new Hibernate Session from the given SessionFactory.
`static Session` `getNewSession(SessionFactory sessionFactory, Interceptor entityInterceptor)` Get a new Hibernate Session from the given SessionFactory.
`static Session` `getSession(SessionFactory sessionFactory, boolean allowCreate)` Get a Hibernate Session for the given SessionFactory.
`static Session` `getSession(SessionFactory sessionFactory, Interceptor entityInterceptor, SQLExceptionTranslator jdbcExceptionTranslator)` Get a Hibernate Session for the given SessionFactory.
`static void` `initDeferredClose(SessionFactory sessionFactory)` Initialize deferred close for the current thread and the given SessionFactory.
`static boolean` `isDeferredCloseActive(SessionFactory sessionFactory)` Determine whether deferred close is active for the current thread and the given SessionFactory.
`static boolean` `isSessionTransactional(Session session, SessionFactory sessionFactory)` Return whether the given Hibernate Session is transactional, that is, bound to the current thread by Spring's transaction facilities.
`static SQLExceptionTranslator` `newJdbcExceptionTranslator(SessionFactory sessionFactory)` Create an appropriate SQLExceptionTranslator for the given SessionFactory.
`static void` `processDeferredClose(SessionFactory sessionFactory)` Process all Hibernate Sessions that have been registered for deferred close for the given SessionFactory.
`static void` `releaseSession(Session session, SessionFactory sessionFactory)` Close the given Session, created via the given factory, if it is not managed externally (i.e. not bound to the thread).
`static String` `toString(Session session)` Stringify the given Session for debug logging.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### SESSION_SYNCHRONIZATION_ORDER

    public static final int SESSION_SYNCHRONIZATION_ORDER

  Order value for TransactionSynchronization objects that clean up Hibernate Sessions. Returns `DataSourceUtils.CONNECTION_SYNCHRONIZATION_ORDER - 100` to execute Session cleanup before JDBC Connection cleanup, if any.

  See Also:
    `DataSourceUtils.CONNECTION_SYNCHRONIZATION_ORDER`, Constant Field Values

Constructor Detail

### SessionFactoryUtils

    public SessionFactoryUtils()

Method Detail

### getDataSource

    public static DataSource getDataSource(SessionFactory sessionFactory)

  Determine the DataSource of the given SessionFactory.

  Parameters:
    `sessionFactory` - the SessionFactory to check
  Returns:
    the DataSource, or `null` if none found
  See Also:
    `SessionFactoryImplementor.getConnectionProvider()`, `LocalDataSourceConnectionProvider`

### newJdbcExceptionTranslator

    public static SQLExceptionTranslator newJdbcExceptionTranslator(SessionFactory sessionFactory)

  Create an appropriate SQLExceptionTranslator for the given SessionFactory. If a DataSource is found, a SQLErrorCodeSQLExceptionTranslator for the DataSource is created; else, a SQLStateSQLExceptionTranslator as fallback.

  Parameters:
    `sessionFactory` - the SessionFactory to create the translator for
  Returns:
    the SQLExceptionTranslator
  See Also:
    `getDataSource(org.hibernate.SessionFactory)`, `SQLErrorCodeSQLExceptionTranslator`, `SQLStateSQLExceptionTranslator`

### getJtaTransactionManager

    public static TransactionManager getJtaTransactionManager(SessionFactory sessionFactory,
                                                              Session session)

  Try to retrieve the JTA TransactionManager from the given SessionFactory and/or Session. Check the passed-in SessionFactory for implementing SessionFactoryImplementor (the usual case), falling back to the SessionFactory reference that the Session itself carries.

  Parameters:
    `sessionFactory` - Hibernate SessionFactory
    `session` - Hibernate Session (can also be `null`)
  Returns:
    the JTA TransactionManager, if any
  See Also:
    `TransactionManager`, `SessionFactoryImplementor.getTransactionManager()`, `Session.getSessionFactory()`, `SessionFactoryImpl`

### getSession

    public static Session getSession(SessionFactory sessionFactory,
                                     boolean allowCreate)
                              throws DataAccessResourceFailureException,
                                     IllegalStateException

  Get a Hibernate Session for the given SessionFactory. Is aware of and will return any existing corresponding Session bound to the current thread, for example when using `HibernateTransactionManager`. Will create a new Session otherwise, if "allowCreate" is `true`.

  This is the `getSession` method used by typical data access code, in combination with `releaseSession` called when done with the Session. Note that HibernateTemplate allows to write data access code without caring about such resource handling.

  Parameters:
    `sessionFactory` - Hibernate SessionFactory to create the session with
    `allowCreate` - whether a non-transactional Session should be created when no transactional Session can be found for the current thread
  Returns:
    the Hibernate Session
  Throws:
    `DataAccessResourceFailureException` - if the Session couldn't be created
    `IllegalStateException` - if no thread-bound Session found and "allowCreate" is `false`
  See Also:
    `getSession(SessionFactory, Interceptor, SQLExceptionTranslator)`, `releaseSession(org.hibernate.Session, org.hibernate.SessionFactory)`, `HibernateTemplate`

### getSession

    public static Session getSession(SessionFactory sessionFactory,
                                     Interceptor entityInterceptor,
                                     SQLExceptionTranslator jdbcExceptionTranslator)
                              throws DataAccessResourceFailureException

  Get a Hibernate Session for the given SessionFactory. Is aware of and will return any existing corresponding Session bound to the current thread, for example when using `HibernateTransactionManager`. Will always create a new Session otherwise.

  Supports setting a Session-level Hibernate entity interceptor that allows to inspect and change property values before writing to and reading from the database. Such an interceptor can also be set at the SessionFactory level (i.e. on LocalSessionFactoryBean), on HibernateTransactionManager, or on HibernateInterceptor/HibernateTemplate.

  Parameters:
    `sessionFactory` - Hibernate SessionFactory to create the session with
    `entityInterceptor` - Hibernate entity interceptor, or `null` if none
    `jdbcExceptionTranslator` - SQLExcepionTranslator to use for flushing the Session on transaction synchronization (may be `null`; only used when actually registering a transaction synchronization)
  Returns:
    the Hibernate Session
  Throws:
    `DataAccessResourceFailureException` - if the Session couldn't be created
  See Also:
    `LocalSessionFactoryBean.setEntityInterceptor(org.hibernate.Interceptor)`, `HibernateAccessor.setEntityInterceptor(org.hibernate.Interceptor)`, `HibernateAccessor.setEntityInterceptor(org.hibernate.Interceptor)`

### doGetSession

    public static Session doGetSession(SessionFactory sessionFactory,
                                       boolean allowCreate)
                                throws HibernateException,
                                       IllegalStateException

  Get a Hibernate Session for the given SessionFactory. Is aware of and will return any existing corresponding Session bound to the current thread, for example when using `HibernateTransactionManager`. Will create a new Session otherwise, if "allowCreate" is `true`.

  Throws the original HibernateException, in contrast to `getSession(org.hibernate.SessionFactory, boolean)`.

  Parameters:
    `sessionFactory` - Hibernate SessionFactory to create the session with
    `allowCreate` - whether a non-transactional Session should be created when no transactional Session can be found for the current thread
  Returns:
    the Hibernate Session
  Throws:
    `HibernateException` - if the Session couldn't be created
    `IllegalStateException` - if no thread-bound Session found and allowCreate false

### getNewSession

    public static Session getNewSession(SessionFactory sessionFactory)

  Get a new Hibernate Session from the given SessionFactory. Will return a new Session even if there already is a pre-bound Session for the given SessionFactory.

  Within a transaction, this method will create a new Session that shares the transaction's JDBC Connection. More specifically, it will use the same JDBC Connection as the pre-bound Hibernate Session.

  Parameters:
    `sessionFactory` - Hibernate SessionFactory to create the session with
  Returns:
    the new Session

### getNewSession

    public static Session getNewSession(SessionFactory sessionFactory,
                                        Interceptor entityInterceptor)

  Get a new Hibernate Session from the given SessionFactory. Will return a new Session even if there already is a pre-bound Session for the given SessionFactory.

  Within a transaction, this method will create a new Session that shares the transaction's JDBC Connection. More specifically, it will use the same JDBC Connection as the pre-bound Hibernate Session.

  Parameters:
    `sessionFactory` - Hibernate SessionFactory to create the session with
    `entityInterceptor` - Hibernate entity interceptor, or `null` if none
  Returns:
    the new Session

### toString

    public static String toString(Session session)

  Stringify the given Session for debug logging. Returns output equivalent to `Object.toString()`: the fully qualified class name + "@" + the identity hash code.

  The sole reason why this is necessary is because Hibernate3's `Session.toString()` implementation is broken (and won't be fixed): it logs the toString representation of all persistent objects in the Session, which might lead to ConcurrentModificationExceptions if the persistent objects in turn refer to the Session (for example, for lazy loading).

  Parameters:
    `session` - the Hibernate Session to stringify
  Returns:
    the String representation of the given Session

### isSessionTransactional

    public static boolean isSessionTransactional(Session session,
                                                 SessionFactory sessionFactory)

  Return whether the given Hibernate Session is transactional, that is, bound to the current thread by Spring's transaction facilities.

  Parameters:
    `session` - the Hibernate Session to check
    `sessionFactory` - Hibernate SessionFactory that the Session was created with (may be `null`)
  Returns:
    whether the Session is transactional

### applyTransactionTimeout

    public static void applyTransactionTimeout(Query query,
                                               SessionFactory sessionFactory)

  Apply the current transaction timeout, if any, to the given Hibernate Query object.

  Parameters:
    `query` - the Hibernate Query object
    `sessionFactory` - Hibernate SessionFactory that the Query was created for (may be `null`)
  See Also:
    `Query.setTimeout(int)`

### applyTransactionTimeout

    public static void applyTransactionTimeout(Criteria criteria,
                                               SessionFactory sessionFactory)

  Apply the current transaction timeout, if any, to the given Hibernate Criteria object.

  Parameters:
    `criteria` - the Hibernate Criteria object
    `sessionFactory` - Hibernate SessionFactory that the Criteria was created for
  See Also:
    `Criteria.setTimeout(int)`

### convertHibernateAccessException

    public static DataAccessException convertHibernateAccessException(HibernateException ex)

  Convert the given HibernateException to an appropriate exception from the `org.springframework.dao` hierarchy.

  Parameters:
    `ex` - HibernateException that occured
  Returns:
    the corresponding DataAccessException instance
  See Also:
    `HibernateAccessor.convertHibernateAccessException(org.hibernate.HibernateException)`, `HibernateTransactionManager.convertHibernateAccessException(org.hibernate.HibernateException)`

### isDeferredCloseActive

    public static boolean isDeferredCloseActive(SessionFactory sessionFactory)

  Determine whether deferred close is active for the current thread and the given SessionFactory.

  Parameters:
    `sessionFactory` - the Hibernate SessionFactory to check
  Returns:
    whether deferred close is active

### initDeferredClose

    public static void initDeferredClose(SessionFactory sessionFactory)

  Initialize deferred close for the current thread and the given SessionFactory. Sessions will not be actually closed on close calls then, but rather at a `processDeferredClose(org.hibernate.SessionFactory)` call at a finishing point (like request completion).

  Used by `OpenSessionInViewFilter` and `OpenSessionInViewInterceptor` when not configured for a single session.

  Parameters:
    `sessionFactory` - the Hibernate SessionFactory to initialize deferred close for
  See Also:
    `processDeferredClose(org.hibernate.SessionFactory)`, `releaseSession(org.hibernate.Session, org.hibernate.SessionFactory)`, `OpenSessionInViewFilter.setSingleSession(boolean)`, `OpenSessionInViewInterceptor.setSingleSession(boolean)`

### processDeferredClose

    public static void processDeferredClose(SessionFactory sessionFactory)

  Process all Hibernate Sessions that have been registered for deferred close for the given SessionFactory.

  Parameters:
    `sessionFactory` - the Hibernate SessionFactory to process deferred close for
  See Also:
    `initDeferredClose(org.hibernate.SessionFactory)`, `releaseSession(org.hibernate.Session, org.hibernate.SessionFactory)`

### releaseSession

    public static void releaseSession(Session session,
                                      SessionFactory sessionFactory)

  Close the given Session, created via the given factory, if it is not managed externally (i.e. not bound to the thread).

  Parameters:
    `session` - the Hibernate Session to close (may be `null`)
    `sessionFactory` - Hibernate SessionFactory that the Session was created with (may be `null`)

### closeSession

    public static void closeSession(Session session)

  Perform actual closing of the Hibernate Session, catching and logging any cleanup exceptions thrown.

  Parameters:
    `session` - the Hibernate Session to close (may be `null`)
  See Also:
    `Session.close()`

The Spring Framework

Copyright © 2002-2008 The Spring Framework.