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

org.springframework.orm.jdo

## Class PersistenceManagerFactoryUtils

- java.lang.Object
- - org.springframework.orm.jdo.PersistenceManagerFactoryUtils

-     public abstract class PersistenceManagerFactoryUtils
      extends Object

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

  Used internally by `JdoTemplate`, `JdoInterceptor` and `JdoTransactionManager`. Can also be used directly in application code.

  Since:
    03.06.2003
  Author:
    Juergen Hoeller
  See Also:
    `JdoTransactionManager`, `JtaTransactionManager`, `TransactionSynchronizationManager`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `PERSISTENCE_MANAGER_SYNCHRONIZATION_ORDER` Order value for TransactionSynchronization objects that clean up JDO PersistenceManagers.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PersistenceManagerFactoryUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `applyTransactionTimeout(javax.jdo.Query query, javax.jdo.PersistenceManagerFactory pmf, JdoDialect jdoDialect)` Apply the current transaction timeout, if any, to the given JDO Query object.
    `static DataAccessException` | `convertJdoAccessException(javax.jdo.JDOException ex)` Convert the given JDOException to an appropriate exception from the `org.springframework.dao` hierarchy.
    `static javax.jdo.PersistenceManager` | `doGetPersistenceManager(javax.jdo.PersistenceManagerFactory pmf, boolean allowCreate)` Obtain a JDO PersistenceManager via the given factory.
    `static void` | `doReleasePersistenceManager(javax.jdo.PersistenceManager pm, javax.jdo.PersistenceManagerFactory pmf)` Actually release a PersistenceManager for the given factory.
    `static javax.jdo.PersistenceManager` | `getPersistenceManager(javax.jdo.PersistenceManagerFactory pmf, boolean allowCreate)` Obtain a JDO PersistenceManager via the given factory.
    `static boolean` | `isPersistenceManagerTransactional(javax.jdo.PersistenceManager pm, javax.jdo.PersistenceManagerFactory pmf)` Return whether the given JDO PersistenceManager is transactional, that is, bound to the current thread by Spring's transaction facilities.
    `static void` | `releasePersistenceManager(javax.jdo.PersistenceManager pm, javax.jdo.PersistenceManagerFactory pmf)` Close the given PersistenceManager, created via the given factory, if it is not managed externally (i.e.

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

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

- - ### Field Detail

    - #### PERSISTENCE_MANAGER_SYNCHRONIZATION_ORDER

          public static final int PERSISTENCE_MANAGER_SYNCHRONIZATION_ORDER

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

  - ### Constructor Detail

    - #### PersistenceManagerFactoryUtils

          public PersistenceManagerFactoryUtils()

  - ### Method Detail

    - #### getPersistenceManager

          public static javax.jdo.PersistenceManager getPersistenceManager(javax.jdo.PersistenceManagerFactory pmf,
                                                           boolean allowCreate)
                                                                    throws DataAccessResourceFailureException,
                                                                           IllegalStateException

      Obtain a JDO PersistenceManager via the given factory. Is aware of a corresponding PersistenceManager bound to the current thread, for example when using JdoTransactionManager. Will create a new PersistenceManager else, if "allowCreate" is `true`.
      Parameters:
        `pmf` - PersistenceManagerFactory to create the PersistenceManager with
        `allowCreate` - if a non-transactional PersistenceManager should be created when no transactional PersistenceManager can be found for the current thread
      Returns:
        the PersistenceManager
      Throws:
        `DataAccessResourceFailureException` - if the PersistenceManager couldn't be obtained
        `IllegalStateException` - if no thread-bound PersistenceManager found and "allowCreate" is `false`
      See Also:
        `JdoTransactionManager`

    - #### doGetPersistenceManager

          public static javax.jdo.PersistenceManager doGetPersistenceManager(javax.jdo.PersistenceManagerFactory pmf,
                                                             boolean allowCreate)
                                                                      throws javax.jdo.JDOException,
                                                                             IllegalStateException

      Obtain a JDO PersistenceManager via the given factory. Is aware of a corresponding PersistenceManager bound to the current thread, for example when using JdoTransactionManager. Will create a new PersistenceManager else, if "allowCreate" is `true`.

      Same as `getPersistenceManager`, but throwing the original JDOException.

      Parameters:
        `pmf` - PersistenceManagerFactory to create the PersistenceManager with
        `allowCreate` - if a non-transactional PersistenceManager should be created when no transactional PersistenceManager can be found for the current thread
      Returns:
        the PersistenceManager
      Throws:
        `javax.jdo.JDOException` - if the PersistenceManager couldn't be created
        `IllegalStateException` - if no thread-bound PersistenceManager found and "allowCreate" is `false`
      See Also:
        `getPersistenceManager(javax.jdo.PersistenceManagerFactory, boolean)`, `JdoTransactionManager`

    - #### isPersistenceManagerTransactional

          public static boolean isPersistenceManagerTransactional(javax.jdo.PersistenceManager pm,
                                                  javax.jdo.PersistenceManagerFactory pmf)

      Return whether the given JDO PersistenceManager is transactional, that is, bound to the current thread by Spring's transaction facilities.
      Parameters:
        `pm` - the JDO PersistenceManager to check
        `pmf` - JDO PersistenceManagerFactory that the PersistenceManager was created with (can be `null`)
      Returns:
        whether the PersistenceManager is transactional

    - #### applyTransactionTimeout

          public static void applyTransactionTimeout(javax.jdo.Query query,
                                     javax.jdo.PersistenceManagerFactory pmf,
                                     JdoDialect jdoDialect)
                                              throws javax.jdo.JDOException

      Apply the current transaction timeout, if any, to the given JDO Query object.
      Parameters:
        `query` - the JDO Query object
        `pmf` - JDO PersistenceManagerFactory that the Query was created for
        `jdoDialect` - the JdoDialect to use for applying a query timeout (must not be `null`)
      Throws:
        `javax.jdo.JDOException` - if thrown by JDO methods
      See Also:
        `JdoDialect.applyQueryTimeout(javax.jdo.Query, int)`

    - #### convertJdoAccessException

          public static DataAccessException convertJdoAccessException(javax.jdo.JDOException ex)

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

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

      Parameters:
        `ex` - JDOException that occured
      Returns:
        the corresponding DataAccessException instance
      See Also:
        `JdoAccessor.convertJdoAccessException(javax.jdo.JDOException)`, `JdoTransactionManager.convertJdoAccessException(javax.jdo.JDOException)`, `JdoDialect.translateException(javax.jdo.JDOException)`

    - #### releasePersistenceManager

          public static void releasePersistenceManager(javax.jdo.PersistenceManager pm,
                                       javax.jdo.PersistenceManagerFactory pmf)

      Close the given PersistenceManager, created via the given factory, if it is not managed externally (i.e. not bound to the thread).
      Parameters:
        `pm` - PersistenceManager to close
        `pmf` - PersistenceManagerFactory that the PersistenceManager was created with (can be `null`)

    - #### doReleasePersistenceManager

          public static void doReleasePersistenceManager(javax.jdo.PersistenceManager pm,
                                         javax.jdo.PersistenceManagerFactory pmf)
                                                  throws javax.jdo.JDOException

      Actually release a PersistenceManager for the given factory. Same as `releasePersistenceManager`, but throwing the original JDOException.
      Parameters:
        `pm` - PersistenceManager to close
        `pmf` - PersistenceManagerFactory that the PersistenceManager was created with (can be `null`)
      Throws:
        `javax.jdo.JDOException` - if thrown by JDO methods