Spring Framework 6.1.4 · org.springframework.orm.jpa.JpaDialect

Method Summary

Modifier and Type	Method and Description
public Object	Returns: an arbitrary object that holds transaction data, if any (to be passed into `cleanupTransaction`). May implement the `org.springframework.transaction.SavepointManager` interface. beginTransaction(EntityManager the EntityManager to begin a JPA transaction on entityManager, TransactionDefinition the Spring transaction definition that defines semantics definition) Begin the given JPA transaction, applying the semantics specified by the given Spring transaction definition (in particular, an isolation level and a timeout).
public void	cleanupTransaction(Object arbitrary object that holds transaction data, if any (as returned by beginTransaction or prepareTransaction) transactionData) Clean up the transaction via the given transaction data.
public ConnectionHandle	Returns: a handle for the Connection, to be passed into `releaseJdbcConnection`, or `null` if no JDBC Connection can be retrieved getJdbcConnection(EntityManager the current JPA EntityManager entityManager, boolean whether the Connection is only needed for read-only purposes readOnly) Retrieve the JDBC Connection that the given JPA EntityManager uses underneath, if accessing a relational database.
public Object	Returns: an arbitrary object that holds transaction data, if any (to be passed into cleanupTransaction) prepareTransaction(EntityManager the EntityManager to begin a JPA transaction on entityManager, boolean whether the transaction is supposed to be read-only readOnly, String the name of the transaction (if any) name) Prepare a JPA transaction, applying the specified semantics.
public void	releaseJdbcConnection(ConnectionHandle the JDBC Connection handle to release conHandle, EntityManager the current JPA EntityManager entityManager) Release the given JDBC Connection, which has originally been retrieved via `getJdbcConnection`.

Inherited from org.springframework.dao.support.PersistenceExceptionTranslator:: translateExceptionIfPossible

Method Detail

beginTransaction back to summary

beginTransaction	back to summary
public 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 `org.springframework.transaction.SavepointManager` interface. `JpaTransactionManager` will use this capability if needed. Parameters entityManager:EntityManager the EntityManager to begin a JPA transaction on definition:TransactionDefinition the Spring transaction definition that defines semantics Returns:Object an arbitrary object that holds transaction data, if any (to be passed into `cleanupTransaction`). May implement the `org.springframework.transaction.SavepointManager` interface. Annotations @Nullable Exceptions PersistenceException: if thrown by JPA methods SQLException: if thrown by JDBC methods TransactionException: in case of invalid arguments See Also `cleanupTransaction`, `jakarta.persistence.EntityTransaction#begin`, `org.springframework.jdbc.datasource.DataSourceUtils#prepareConnectionForTransaction`

public 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 org.springframework.transaction.SavepointManager interface. JpaTransactionManager will use this capability if needed.

Parameters

entityManager:EntityManager: the EntityManager to begin a JPA transaction on
definition:TransactionDefinition: the Spring transaction definition that defines semantics

Returns:Object

an arbitrary object that holds transaction data, if any (to be passed into cleanupTransaction). May implement the org.springframework.transaction.SavepointManager interface.

Annotations

@Nullable

Exceptions

PersistenceException:: if thrown by JPA methods
SQLException:: if thrown by JDBC methods
TransactionException:: in case of invalid arguments

cleanupTransaction back to summary

cleanupTransaction	back to summary
public 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:Object arbitrary object that holds transaction data, if any (as returned by beginTransaction or prepareTransaction) See Also `beginTransaction`, `org.springframework.jdbc.datasource.DataSourceUtils#resetConnectionAfterTransaction`

public 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:Object: arbitrary object that holds transaction data, if any (as returned by beginTransaction or prepareTransaction)

getJdbcConnection back to summary

getJdbcConnection	back to summary
public 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 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:EntityManager the current JPA EntityManager readOnly:boolean whether the Connection is only needed for read-only purposes Returns:ConnectionHandle a handle for the Connection, to be passed into `releaseJdbcConnection`, or `null` if no JDBC Connection can be retrieved Annotations @Nullable Exceptions PersistenceException: if thrown by JPA methods SQLException: if thrown by JDBC methods See Also `releaseJdbcConnection`, `org.springframework.jdbc.datasource.ConnectionHandle#getConnection`, `org.springframework.jdbc.datasource.SimpleConnectionHandle`, `JpaTransactionManager#setDataSource`

public 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 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:EntityManager: the current JPA EntityManager
readOnly:boolean: whether the Connection is only needed for read-only purposes

Returns:ConnectionHandle

a handle for the Connection, to be passed into releaseJdbcConnection, or null if no JDBC Connection can be retrieved

Annotations

@Nullable

Exceptions

PersistenceException:: if thrown by JPA methods
SQLException:: if thrown by JDBC methods

prepareTransaction back to summary

prepareTransaction	back to summary
public 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 or a locally joined transaction (e.g. after upgrading an unsynchronized EntityManager to a synchronized one). 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 to optimize for specific data access use cases (effectively using the current transaction name as use case identifier). Parameters entityManager:EntityManager the EntityManager to begin a JPA transaction on readOnly:boolean whether the transaction is supposed to be read-only name:String the name of the transaction (if any) Returns:Object an arbitrary object that holds transaction data, if any (to be passed into cleanupTransaction) Annotations @Nullable Exceptions PersistenceException: if thrown by JPA methods See Also `cleanupTransaction`

public 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 or a locally joined transaction (e.g. after upgrading an unsynchronized EntityManager to a synchronized one).

Implementations can also use the Spring transaction name to optimize for specific data access use cases (effectively using the current transaction name as use case identifier).

Parameters

entityManager:EntityManager: the EntityManager to begin a JPA transaction on
readOnly:boolean: whether the transaction is supposed to be read-only
name:String: the name of the transaction (if any)

Returns:Object

an arbitrary object that holds transaction data, if any (to be passed into cleanupTransaction)

Annotations

@Nullable

Exceptions

PersistenceException:: if thrown by JPA methods

See Also

cleanupTransaction

releaseJdbcConnection back to summary

releaseJdbcConnection	back to summary
public 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:ConnectionHandle the JDBC Connection handle to release entityManager:EntityManager the current JPA EntityManager Exceptions PersistenceException: if thrown by JPA methods SQLException: if thrown by JDBC methods See Also `getJdbcConnection`

public 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:ConnectionHandle: the JDBC Connection handle to release
entityManager:EntityManager: the current JPA EntityManager

Exceptions

PersistenceException:: if thrown by JPA methods
SQLException:: if thrown by JDBC methods

See Also

getJdbcConnection

public Interface JpaDialect

Method Summary

Method Detail