EntityManagerFactoryUtils (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.orm.jpa

## Class EntityManagerFactoryUtils

- java.lang.Object
- - org.springframework.orm.jpa.EntityManagerFactoryUtils

-     public abstract class EntityManagerFactoryUtils
      extends Object

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

  Mainly intended for internal use within the framework.

  Since:
    2.0
  Author:
    Juergen Hoeller

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ENTITY_MANAGER_SYNCHRONIZATION_ORDER` Order value for TransactionSynchronization objects that clean up JPA EntityManagers.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EntityManagerFactoryUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `applyTransactionTimeout(Query query, EntityManagerFactory emf)` Apply the current transaction timeout, if any, to the given JPA Query object.
    `static void` | `closeEntityManager(EntityManager em)` Close the given JPA EntityManager, catching and logging any cleanup exceptions thrown.
    `static DataAccessException` | `convertJpaAccessExceptionIfPossible(RuntimeException ex)` Convert the given runtime exception to an appropriate exception from the `org.springframework.dao` hierarchy.
    `static EntityManager` | `doGetTransactionalEntityManager(EntityManagerFactory emf, Map properties)` Obtain a JPA EntityManager from the given factory.
    `static EntityManagerFactory` | `findEntityManagerFactory(ListableBeanFactory beanFactory, String unitName)` Find an EntityManagerFactory with the given name in the given Spring application context (represented as ListableBeanFactory).
    `static EntityManager` | `getTransactionalEntityManager(EntityManagerFactory emf)` Obtain a JPA EntityManager from the given factory.
    `static EntityManager` | `getTransactionalEntityManager(EntityManagerFactory emf, Map properties)` Obtain a JPA EntityManager from the given factory.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### ENTITY_MANAGER_SYNCHRONIZATION_ORDER

          public static final int ENTITY_MANAGER_SYNCHRONIZATION_ORDER

      Order value for TransactionSynchronization objects that clean up JPA EntityManagers. Return DataSourceUtils.CONNECTION_SYNCHRONIZATION_ORDER - 100 to execute EntityManager cleanup before JDBC Connection cleanup, if any.
      See Also:
        `DataSourceUtils.CONNECTION_SYNCHRONIZATION_ORDER`, Constant Field Values

  - ### Constructor Detail

    - #### EntityManagerFactoryUtils

          public EntityManagerFactoryUtils()

  - ### Method Detail

    - #### findEntityManagerFactory

          public static EntityManagerFactory findEntityManagerFactory(ListableBeanFactory beanFactory,
                                                      String unitName)
                                                               throws NoSuchBeanDefinitionException

      Find an EntityManagerFactory with the given name in the given Spring application context (represented as ListableBeanFactory).

      The specified unit name will be matched against the configured persistence unit, provided that a discovered EntityManagerFactory implements the `EntityManagerFactoryInfo` interface. If not, the persistence unit name will be matched against the Spring bean name, assuming that the EntityManagerFactory bean names follow that convention.

      If no unit name has been given, this method will search for a default EntityManagerFactory through `BeanFactory.getBean(Class)`.

      Parameters:
        `beanFactory` - the ListableBeanFactory to search
        `unitName` - the name of the persistence unit (may be `null` or empty, in which case a single bean of type EntityManagerFactory will be searched for)
      Returns:
        the EntityManagerFactory
      Throws:
        `NoSuchBeanDefinitionException` - if there is no such EntityManagerFactory in the context
      See Also:
        `EntityManagerFactoryInfo.getPersistenceUnitName()`

    - #### getTransactionalEntityManager

          public static EntityManager getTransactionalEntityManager(EntityManagerFactory emf)
                                                             throws DataAccessResourceFailureException

      Obtain a JPA EntityManager from the given factory. Is aware of a corresponding EntityManager bound to the current thread, for example when using JpaTransactionManager.

      Note: Will return `null` if no thread-bound EntityManager found!

      Parameters:
        `emf` - EntityManagerFactory to create the EntityManager with
      Returns:
        the EntityManager, or `null` if none found
      Throws:
        `DataAccessResourceFailureException` - if the EntityManager couldn't be obtained
      See Also:
        `JpaTransactionManager`

    - #### getTransactionalEntityManager

          public static EntityManager getTransactionalEntityManager(EntityManagerFactory emf,
                                                    Map properties)
                                                             throws DataAccessResourceFailureException

      Obtain a JPA EntityManager from the given factory. Is aware of a corresponding EntityManager bound to the current thread, for example when using JpaTransactionManager.

      Note: Will return `null` if no thread-bound EntityManager found!

      Parameters:
        `emf` - EntityManagerFactory to create the EntityManager with
        `properties` - the properties to be passed into the `createEntityManager` call (may be `null`)
      Returns:
        the EntityManager, or `null` if none found
      Throws:
        `DataAccessResourceFailureException` - if the EntityManager couldn't be obtained
      See Also:
        `JpaTransactionManager`

    - #### doGetTransactionalEntityManager

          public static EntityManager doGetTransactionalEntityManager(EntityManagerFactory emf,
                                                      Map properties)
                                                               throws PersistenceException

      Obtain a JPA EntityManager from the given factory. Is aware of a corresponding EntityManager bound to the current thread, for example when using JpaTransactionManager.

      Same as `getEntityManager`, but throwing the original PersistenceException.

      Parameters:
        `emf` - EntityManagerFactory to create the EntityManager with
        `properties` - the properties to be passed into the `createEntityManager` call (may be `null`)
      Returns:
        the EntityManager, or `null` if none found
      Throws:
        `PersistenceException` - if the EntityManager couldn't be created
      See Also:
        `getTransactionalEntityManager(javax.persistence.EntityManagerFactory)`, `JpaTransactionManager`

    - #### applyTransactionTimeout

          public static void applyTransactionTimeout(Query query,
                                     EntityManagerFactory emf)

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

      This method sets the JPA 2.0 query hint "javax.persistence.query.timeout" accordingly.

      Parameters:
        `query` - the JPA Query object
        `emf` - JPA EntityManagerFactory that the Query was created for

    - #### convertJpaAccessExceptionIfPossible

          public static DataAccessException convertJpaAccessExceptionIfPossible(RuntimeException ex)

      Convert the given runtime exception to an appropriate exception from the `org.springframework.dao` hierarchy. Return null if no translation is appropriate: any other exception may have resulted from user code, and should not be translated.

      The most important cases like object not found or optimistic locking failure are covered here. For more fine-granular conversion, JpaTransactionManager etc support sophisticated translation of exceptions via a JpaDialect.

      Parameters:
        `ex` - runtime exception that occurred
      Returns:
        the corresponding DataAccessException instance, or `null` if the exception should not be translated

    - #### closeEntityManager

          public static void closeEntityManager(EntityManager em)

      Close the given JPA EntityManager, catching and logging any cleanup exceptions thrown.
      Parameters:
        `em` - the JPA EntityManager to close (may be `null`)
      See Also:
        `EntityManager.close()`