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

org.springframework.orm.jpa

## Interface JpaDialect

- All Superinterfaces:
    PersistenceExceptionTranslator
  All Known Implementing Classes:
    DefaultJpaDialect, EclipseLinkJpaDialect, HibernateJpaDialect, OpenJpaDialect, TopLinkJpaDialect

      public interface JpaDialect
      extends PersistenceExceptionTranslator

  SPI strategy that encapsulates certain functionality that standard JPA 1.0 does not offer, such as access to the underlying JDBC Connection. This strategy is mainly intended for standalone usage of a JPA provider; most of its functionality is not relevant when running with JTA transactions.

  Also allows for the provision of value-added methods for portable yet more capable EntityManager and EntityManagerFactory subinterfaces offered by Spring.

  In general, it is recommended to derive from DefaultJpaDialect instead of implementing this interface directly. This allows for inheriting common behavior (present and future) from DefaultJpaDialect, only overriding specific hooks to plug in concrete vendor-specific behavior.

  Since:
    2.0
  Author:
    Juergen Hoeller, Rod Johnson
  See Also:
    `DefaultJpaDialect`, `JpaAccessor.setJpaDialect(org.springframework.orm.jpa.JpaDialect)`, `JpaTransactionManager.setJpaDialect(org.springframework.orm.jpa.JpaDialect)`, `JpaVendorAdapter.getJpaDialect()`, `AbstractEntityManagerFactoryBean.setJpaDialect(org.springframework.orm.jpa.JpaDialect)`, `AbstractEntityManagerFactoryBean.setJpaVendorAdapter(org.springframework.orm.jpa.JpaVendorAdapter)`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `beginTransaction(EntityManager entityManager, TransactionDefinition definition)` Begin the given JPA transaction, applying the semantics specified by the given Spring transaction definition (in particular, an isolation level and a timeout).
    `void` | `cleanupTransaction(Object transactionData)` Clean up the transaction via the given transaction data.
    `EntityManagerFactoryPlusOperations` | `getEntityManagerFactoryPlusOperations(EntityManagerFactory rawEntityManager)` Return an EntityManagerFactoryPlusOperations implementation for the given raw EntityManagerFactory.
    `EntityManagerPlusOperations` | `getEntityManagerPlusOperations(EntityManager rawEntityManager)` Return an EntityManagerPlusOperations implementation for the given raw EntityManager.
    `ConnectionHandle` | `getJdbcConnection(EntityManager entityManager, boolean readOnly)` Retrieve the JDBC Connection that the given JPA EntityManager uses underneath, if accessing a relational database.
    `Object` | `prepareTransaction(EntityManager entityManager, boolean readOnly, String name)` Prepare a JPA transaction, applying the specified semantics.
    `void` | `releaseJdbcConnection(ConnectionHandle conHandle, EntityManager entityManager)` Release the given JDBC Connection, which has originally been retrieved via `getJdbcConnection`.
    `boolean` | `supportsEntityManagerFactoryPlusOperations()` Return whether the EntityManagerFactoryPlus(Operations) interface is supported by this provider.
    `boolean` | `supportsEntityManagerPlusOperations()` Return whether the EntityManagerPlus(Operations) interface is supported by this provider.

    - ### Methods inherited from interface org.springframework.dao.support.PersistenceExceptionTranslator

      `translateExceptionIfPossible`

- - ### Method Detail

    - #### supportsEntityManagerFactoryPlusOperations

          boolean supportsEntityManagerFactoryPlusOperations()

      Return whether the EntityManagerFactoryPlus(Operations) interface is supported by this provider.
      See Also:
        `EntityManagerFactoryPlusOperations`, `EntityManagerFactoryPlus`

    - #### supportsEntityManagerPlusOperations

          boolean supportsEntityManagerPlusOperations()

      Return whether the EntityManagerPlus(Operations) interface is supported by this provider.
      See Also:
        `EntityManagerPlusOperations`, `EntityManagerPlus`

    - #### getEntityManagerFactoryPlusOperations

          EntityManagerFactoryPlusOperations getEntityManagerFactoryPlusOperations(EntityManagerFactory rawEntityManager)

      Return an EntityManagerFactoryPlusOperations implementation for the given raw EntityManagerFactory. This operations object can be used to serve the additional operations behind a proxy that implements the EntityManagerFactoryPlus interface.
      Parameters:
        `rawEntityManager` - the raw provider-specific EntityManagerFactory
      Returns:
        the EntityManagerFactoryPlusOperations implementation

    - #### getEntityManagerPlusOperations

          EntityManagerPlusOperations getEntityManagerPlusOperations(EntityManager rawEntityManager)

      Return an EntityManagerPlusOperations implementation for the given raw EntityManager. This operations object can be used to serve the additional operations behind a proxy that implements the EntityManagerPlus interface.
      Parameters:
        `rawEntityManager` - the raw provider-specific EntityManagerFactory
      Returns:
        the EntityManagerFactoryPlusOperations implementation

    - #### beginTransaction

          Object beginTransaction(EntityManager entityManager,
                                TransactionDefinition definition)
                                  throws PersistenceException,
                                         SQLException,
                                         TransactionException

      Begin the given JPA transaction, applying the semantics specified by the given Spring transaction definition (in particular, an isolation level and a timeout). Called by JpaTransactionManager on transaction begin.

      An implementation can configure the JPA Transaction object and then invoke `begin`, or invoke a special begin method that takes, for example, an isolation level.

      An implementation can apply the read-only flag as flush mode. In that case, a transaction data object can be returned that holds the previous flush mode (and possibly other data), to be reset in `cleanupTransaction`. It may also apply the read-only flag and isolation level to the underlying JDBC Connection before beginning the transaction.

      Implementations can also use the Spring transaction name, as exposed by the passed-in TransactionDefinition, to optimize for specific data access use cases (effectively using the current transaction name as use case identifier).

      This method also allows for exposing savepoint capabilities if supported by the persistence provider, through returning an Object that implements Spring's `SavepointManager` interface. `JpaTransactionManager` will use this capability if needed.

      Parameters:
        `entityManager` - the EntityManager to begin a JPA transaction on
        `definition` - the Spring transaction definition that defines semantics
      Returns:
        an arbitrary object that holds transaction data, if any (to be passed into `cleanupTransaction(java.lang.Object)`). May implement the `SavepointManager` interface.
      Throws:
        `PersistenceException` - if thrown by JPA methods
        `SQLException` - if thrown by JDBC methods
        `TransactionException` - in case of invalid arguments
      See Also:
        `cleanupTransaction(java.lang.Object)`, `EntityTransaction.begin()`, `DataSourceUtils.prepareConnectionForTransaction(java.sql.Connection, org.springframework.transaction.TransactionDefinition)`

    - #### prepareTransaction

          Object prepareTransaction(EntityManager entityManager,
                                  boolean readOnly,
                                  String name)
                                    throws PersistenceException

      Prepare a JPA transaction, applying the specified semantics. Called by EntityManagerFactoryUtils when enlisting an EntityManager in a JTA transaction.

      An implementation can apply the read-only flag as flush mode. In that case, a transaction data object can be returned that holds the previous flush mode (and possibly other data), to be reset in `cleanupTransaction`.

      Implementations can also use the Spring transaction name, as exposed by the passed-in TransactionDefinition, to optimize for specific data access use cases (effectively using the current transaction name as use case identifier).

      Parameters:
        `entityManager` - the EntityManager to begin a JPA transaction on
        `readOnly` - whether the transaction is supposed to be read-only
        `name` - the name of the transaction (if any)
      Returns:
        an arbitrary object that holds transaction data, if any (to be passed into cleanupTransaction)
      Throws:
        `PersistenceException` - if thrown by JPA methods
      See Also:
        `cleanupTransaction(java.lang.Object)`

    - #### cleanupTransaction

          void cleanupTransaction(Object transactionData)

      Clean up the transaction via the given transaction data. Called by JpaTransactionManager and EntityManagerFactoryUtils on transaction cleanup.

      An implementation can, for example, reset read-only flag and isolation level of the underlying JDBC Connection. Furthermore, an exposed data access use case can be reset here.

      Parameters:
        `transactionData` - arbitrary object that holds transaction data, if any (as returned by beginTransaction or prepareTransaction)
      See Also:
        `beginTransaction(javax.persistence.EntityManager, org.springframework.transaction.TransactionDefinition)`, `DataSourceUtils.resetConnectionAfterTransaction(java.sql.Connection, java.lang.Integer)`

    - #### getJdbcConnection

          ConnectionHandle getJdbcConnection(EntityManager entityManager,
                                           boolean readOnly)
                                             throws PersistenceException,
                                                    SQLException

      Retrieve the JDBC Connection that the given JPA EntityManager uses underneath, if accessing a relational database. This method will just get invoked if actually needing access to the underlying JDBC Connection, usually within an active JPA transaction (for example, by JpaTransactionManager). The returned handle will be passed into the `releaseJdbcConnection` method when not needed anymore.

      This strategy is necessary as JPA 1.0 does not provide a standard way to retrieve the underlying JDBC Connection (due to the fact that a JPA implementation might not work with a relational database at all).

      Implementations are encouraged to return an unwrapped Connection object, i.e. the Connection as they got it from the connection pool. This makes it easier for application code to get at the underlying native JDBC Connection, like an OracleConnection, which is sometimes necessary for LOB handling etc. We assume that calling code knows how to properly handle the returned Connection object.

      In a simple case where the returned Connection will be auto-closed with the EntityManager or can be released via the Connection object itself, an implementation can return a SimpleConnectionHandle that just contains the Connection. If some other object is needed in `releaseJdbcConnection`, an implementation should use a special handle that references that other object.

      Parameters:
        `entityManager` - the current JPA EntityManager
        `readOnly` - whether the Connection is only needed for read-only purposes
      Returns:
        a handle for the JDBC Connection, to be passed into `releaseJdbcConnection`, or `null` if no JDBC Connection can be retrieved
      Throws:
        `PersistenceException` - if thrown by JPA methods
        `SQLException` - if thrown by JDBC methods
      See Also:
        `releaseJdbcConnection(org.springframework.jdbc.datasource.ConnectionHandle, javax.persistence.EntityManager)`, `ConnectionHandle.getConnection()`, `SimpleConnectionHandle`, `JpaTransactionManager.setDataSource(javax.sql.DataSource)`, `NativeJdbcExtractor`

    - #### releaseJdbcConnection

          void releaseJdbcConnection(ConnectionHandle conHandle,
                                   EntityManager entityManager)
                                     throws PersistenceException,
                                            SQLException

      Release the given JDBC Connection, which has originally been retrieved via `getJdbcConnection`. This should be invoked in any case, to allow for proper release of the retrieved Connection handle.

      An implementation might simply do nothing, if the Connection returned by `getJdbcConnection` will be implicitly closed when the JPA transaction completes or when the EntityManager is closed.

      Parameters:
        `conHandle` - the JDBC Connection handle to release
        `entityManager` - the current JPA EntityManager
      Throws:
        `PersistenceException` - if thrown by JPA methods
        `SQLException` - if thrown by JDBC methods
      See Also:
        `getJdbcConnection(javax.persistence.EntityManager, boolean)`