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