001/*
002 * Copyright 2002-2014 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.orm.jpa;
018
019import java.sql.SQLException;
020import javax.persistence.EntityManager;
021import javax.persistence.PersistenceException;
022
023import org.springframework.dao.support.PersistenceExceptionTranslator;
024import org.springframework.jdbc.datasource.ConnectionHandle;
025import org.springframework.transaction.TransactionDefinition;
026import org.springframework.transaction.TransactionException;
027
028/**
029 * SPI strategy that encapsulates certain functionality that standard JPA 2.0 does
030 * not offer, such as access to the underlying JDBC Connection. This strategy is
031 * mainly intended for standalone usage of a JPA provider; most of its functionality
032 * is not relevant when running with JTA transactions.
033 *
034 * <p>In general, it is recommended to derive from {@link DefaultJpaDialect} instead
035 * of implementing this interface directly. This allows for inheriting common behavior
036 * (present and future) from DefaultJpaDialect, only overriding specific hooks to
037 * plug in concrete vendor-specific behavior.
038 *
039 * @author Juergen Hoeller
040 * @author Rod Johnson
041 * @since 2.0
042 * @see DefaultJpaDialect
043 * @see JpaTransactionManager#setJpaDialect
044 * @see JpaVendorAdapter#getJpaDialect()
045 * @see AbstractEntityManagerFactoryBean#setJpaDialect
046 * @see AbstractEntityManagerFactoryBean#setJpaVendorAdapter
047 */
048public interface JpaDialect extends PersistenceExceptionTranslator {
049
050        /**
051         * Begin the given JPA transaction, applying the semantics specified by the
052         * given Spring transaction definition (in particular, an isolation level
053         * and a timeout). Called by JpaTransactionManager on transaction begin.
054         * <p>An implementation can configure the JPA Transaction object and then
055         * invoke {@code begin}, or invoke a special begin method that takes,
056         * for example, an isolation level.
057         * <p>An implementation can apply the read-only flag as flush mode. In that case,
058         * a transaction data object can be returned that holds the previous flush mode
059         * (and possibly other data), to be reset in {@code cleanupTransaction}.
060         * It may also apply the read-only flag and isolation level to the underlying
061         * JDBC Connection before beginning the transaction.
062         * <p>Implementations can also use the Spring transaction name, as exposed by the
063         * passed-in TransactionDefinition, to optimize for specific data access use cases
064         * (effectively using the current transaction name as use case identifier).
065         * <p>This method also allows for exposing savepoint capabilities if supported by
066         * the persistence provider, through returning an Object that implements Spring's
067         * {@link org.springframework.transaction.SavepointManager} interface.
068         * {@link JpaTransactionManager} will use this capability if needed.
069         * @param entityManager the EntityManager to begin a JPA transaction on
070         * @param definition the Spring transaction definition that defines semantics
071         * @return an arbitrary object that holds transaction data, if any
072         * (to be passed into {@link #cleanupTransaction}). May implement the
073         * {@link org.springframework.transaction.SavepointManager} interface.
074         * @throws javax.persistence.PersistenceException if thrown by JPA methods
075         * @throws java.sql.SQLException if thrown by JDBC methods
076         * @throws org.springframework.transaction.TransactionException in case of invalid arguments
077         * @see #cleanupTransaction
078         * @see javax.persistence.EntityTransaction#begin
079         * @see org.springframework.jdbc.datasource.DataSourceUtils#prepareConnectionForTransaction
080         */
081        Object beginTransaction(EntityManager entityManager, TransactionDefinition definition)
082                        throws PersistenceException, SQLException, TransactionException;
083
084        /**
085         * Prepare a JPA transaction, applying the specified semantics. Called by
086         * EntityManagerFactoryUtils when enlisting an EntityManager in a JTA transaction
087         * or a locally joined transaction (e.g. after upgrading an unsynchronized
088         * EntityManager to a synchronized one).
089         * <p>An implementation can apply the read-only flag as flush mode. In that case,
090         * a transaction data object can be returned that holds the previous flush mode
091         * (and possibly other data), to be reset in {@code cleanupTransaction}.
092         * <p>Implementations can also use the Spring transaction name to optimize for
093         * specific data access use cases (effectively using the current transaction
094         * name as use case identifier).
095         * @param entityManager the EntityManager to begin a JPA transaction on
096         * @param readOnly whether the transaction is supposed to be read-only
097         * @param name the name of the transaction (if any)
098         * @return an arbitrary object that holds transaction data, if any
099         * (to be passed into cleanupTransaction)
100         * @throws javax.persistence.PersistenceException if thrown by JPA methods
101         * @see #cleanupTransaction
102         */
103        Object prepareTransaction(EntityManager entityManager, boolean readOnly, String name)
104                        throws PersistenceException;
105
106        /**
107         * Clean up the transaction via the given transaction data. Called by
108         * JpaTransactionManager and EntityManagerFactoryUtils on transaction cleanup.
109         * <p>An implementation can, for example, reset read-only flag and
110         * isolation level of the underlying JDBC Connection. Furthermore,
111         * an exposed data access use case can be reset here.
112         * @param transactionData arbitrary object that holds transaction data, if any
113         * (as returned by beginTransaction or prepareTransaction)
114         * @see #beginTransaction
115         * @see org.springframework.jdbc.datasource.DataSourceUtils#resetConnectionAfterTransaction
116         */
117        void cleanupTransaction(Object transactionData);
118
119        /**
120         * Retrieve the JDBC Connection that the given JPA EntityManager uses underneath,
121         * if accessing a relational database. This method will just get invoked if actually
122         * needing access to the underlying JDBC Connection, usually within an active JPA
123         * transaction (for example, by JpaTransactionManager). The returned handle will
124         * be passed into the {@code releaseJdbcConnection} method when not needed anymore.
125         * <p>This strategy is necessary as JPA does not provide a standard way to retrieve
126         * the underlying JDBC Connection (due to the fact that a JPA implementation might not
127         * work with a relational database at all).
128         * <p>Implementations are encouraged to return an unwrapped Connection object, i.e.
129         * the Connection as they got it from the connection pool. This makes it easier for
130         * application code to get at the underlying native JDBC Connection, like an
131         * OracleConnection, which is sometimes necessary for LOB handling etc. We assume
132         * that calling code knows how to properly handle the returned Connection object.
133         * <p>In a simple case where the returned Connection will be auto-closed with the
134         * EntityManager or can be released via the Connection object itself, an
135         * implementation can return a SimpleConnectionHandle that just contains the
136         * Connection. If some other object is needed in {@code releaseJdbcConnection},
137         * an implementation should use a special handle that references that other object.
138         * @param entityManager the current JPA EntityManager
139         * @param readOnly whether the Connection is only needed for read-only purposes
140         * @return a handle for the Connection, to be passed into {@code releaseJdbcConnection},
141         * or {@code null} if no JDBC Connection can be retrieved
142         * @throws javax.persistence.PersistenceException if thrown by JPA methods
143         * @throws java.sql.SQLException if thrown by JDBC methods
144         * @see #releaseJdbcConnection
145         * @see org.springframework.jdbc.datasource.ConnectionHandle#getConnection
146         * @see org.springframework.jdbc.datasource.SimpleConnectionHandle
147         * @see JpaTransactionManager#setDataSource
148         * @see org.springframework.jdbc.support.nativejdbc.NativeJdbcExtractor
149         */
150        ConnectionHandle getJdbcConnection(EntityManager entityManager, boolean readOnly)
151                        throws PersistenceException, SQLException;
152
153        /**
154         * Release the given JDBC Connection, which has originally been retrieved
155         * via {@code getJdbcConnection}. This should be invoked in any case,
156         * to allow for proper release of the retrieved Connection handle.
157         * <p>An implementation might simply do nothing, if the Connection returned
158         * by {@code getJdbcConnection} will be implicitly closed when the JPA
159         * transaction completes or when the EntityManager is closed.
160         * @param conHandle the JDBC Connection handle to release
161         * @param entityManager the current JPA EntityManager
162         * @throws javax.persistence.PersistenceException if thrown by JPA methods
163         * @throws java.sql.SQLException if thrown by JDBC methods
164         * @see #getJdbcConnection
165         */
166        void releaseJdbcConnection(ConnectionHandle conHandle, EntityManager entityManager)
167                        throws PersistenceException, SQLException;
168
169}