JpaDialect


1   /*
2    * Copyright 2002-2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.orm.jpa;
18  
19  import java.sql.SQLException  ;
20  
21  import javax.persistence.EntityManager;
22  import javax.persistence.EntityManagerFactory;
23  import javax.persistence.PersistenceException;
24  
25  import org.springframework.dao.support.PersistenceExceptionTranslator;
26  import org.springframework.jdbc.datasource.ConnectionHandle;
27  import org.springframework.transaction.TransactionDefinition;
28  import org.springframework.transaction.TransactionException;
29  
30  /**
31   * SPI strategy that encapsulates certain functionality that standard JPA 1.0
32   * does not offer, such as access to the underlying JDBC Connection. This
33   * strategy is mainly intended for standalone usage of a JPA provider; most
34   * of its functionality is not relevant when running with JTA transactions.
35   * 
36   * <p>Also allows for the provision of value-added methods for portable yet
37   * more capable EntityManager and EntityManagerFactory subinterfaces offered
38   * by Spring.
39   *
40   * <p>In general, it is recommended to derive from DefaultJpaDialect instead of
41   * implementing this interface directly. This allows for inheriting common
42   * behavior (present and future) from DefaultJpaDialect, only overriding
43   * specific hooks to plug in concrete vendor-specific behavior.
44   *
45   * @author Juergen Hoeller
46   * @author Rod Johnson
47   * @since 2.0
48   * @see DefaultJpaDialect
49   * @see JpaAccessor#setJpaDialect
50   * @see JpaTransactionManager#setJpaDialect
51   * @see JpaVendorAdapter#getJpaDialect()
52   * @see AbstractEntityManagerFactoryBean#setJpaDialect
53   * @see AbstractEntityManagerFactoryBean#setJpaVendorAdapter
54   */
55  public interface JpaDialect extends PersistenceExceptionTranslator {
56  
57      //-----------------------------------------------------------------------------------
58      // Hooks for non-standard persistence operations (used by EntityManagerFactory beans)
59      //-----------------------------------------------------------------------------------
60  
61      /**
62       * Return whether the EntityManagerFactoryPlus(Operations) interface is
63       * supported by this provider.
64       * @see EntityManagerFactoryPlusOperations
65       * @see EntityManagerFactoryPlus
66       */
67      boolean supportsEntityManagerFactoryPlusOperations();
68  
69      /**
70       * Return whether the EntityManagerPlus(Operations) interface is
71       * supported by this provider.
72       * @see EntityManagerPlusOperations
73       * @see EntityManagerPlus
74       */
75      boolean supportsEntityManagerPlusOperations();
76  
77      /**
78       * Return an EntityManagerFactoryPlusOperations implementation for
79       * the given raw EntityManagerFactory. This operations object can be
80       * used to serve the additional operations behind a proxy that
81       * implements the EntityManagerFactoryPlus interface.
82       * @param rawEntityManager the raw provider-specific EntityManagerFactory
83       * @return the EntityManagerFactoryPlusOperations implementation
84       */
85      EntityManagerFactoryPlusOperations getEntityManagerFactoryPlusOperations(EntityManagerFactory rawEntityManager);
86  
87      /**
88       * Return an EntityManagerPlusOperations implementation for
89       * the given raw EntityManager. This operations object can be
90       * used to serve the additional operations behind a proxy that
91       * implements the EntityManagerPlus interface.
92       * @param rawEntityManager the raw provider-specific EntityManagerFactory
93       * @return the EntityManagerFactoryPlusOperations implementation
94       */
95      EntityManagerPlusOperations getEntityManagerPlusOperations(EntityManager rawEntityManager);
96  
97  
98      //-------------------------------------------------------------------------
99      // Hooks for transaction management (used by JpaTransactionManager)
100     //-------------------------------------------------------------------------
101 
102     /**
103      * Begin the given JPA transaction, applying the semantics specified by the
104      * given Spring transaction definition (in particular, an isolation level
105      * and a timeout). Invoked by JpaTransactionManager on transaction begin.
106      * <p>An implementation can configure the JPA Transaction object and then
107      * invoke <code>begin</code>, or invoke a special begin method that takes,
108      * for example, an isolation level.
109      * <p>An implementation can also apply read-only flag and isolation level to the
110      * underlying JDBC Connection before beginning the transaction. In that case,
111      * a transaction data object can be returned that holds the previous isolation
112      * level (and possibly other data), to be reset in <code>cleanupTransaction</code>.
113      * <p>Implementations can also use the Spring transaction name, as exposed by the
114      * passed-in TransactionDefinition, to optimize for specific data access use cases
115      * (effectively using the current transaction name as use case identifier).
116      * @param entityManager the EntityManager to begin a JPA transaction on
117      * @param definition the Spring transaction definition that defines semantics
118      * @return an arbitrary object that holds transaction data, if any
119      * (to be passed into cleanupTransaction)
120      * @throws javax.persistence.PersistenceException if thrown by JPA methods
121      * @throws java.sql.SQLException if thrown by JDBC methods
122      * @throws org.springframework.transaction.TransactionException in case of invalid arguments
123      * @see #cleanupTransaction
124      * @see javax.persistence.EntityTransaction#begin
125      * @see org.springframework.jdbc.datasource.DataSourceUtils#prepareConnectionForTransaction
126      */
127     Object   beginTransaction(EntityManager entityManager, TransactionDefinition definition)
128             throws PersistenceException, SQLException  , TransactionException;
129 
130     /**
131      * Clean up the transaction via the given transaction data.
132      * Invoked by JpaTransactionManager on transaction cleanup.
133      * <p>An implementation can, for example, reset read-only flag and
134      * isolation level of the underlying JDBC Connection. Furthermore,
135      * an exposed data access use case can be reset here.
136      * @param transactionData arbitrary object that holds transaction data, if any
137      * (as returned by beginTransaction)
138      * @see #beginTransaction
139      * @see org.springframework.jdbc.datasource.DataSourceUtils#resetConnectionAfterTransaction
140      */
141     void cleanupTransaction(Object   transactionData);
142 
143     /**
144      * Retrieve the JDBC Connection that the given JPA EntityManager uses underneath,
145      * if accessing a relational database. This method will just get invoked if actually
146      * needing access to the underlying JDBC Connection, usually within an active JPA
147      * transaction (for example, by JpaTransactionManager). The returned handle will
148      * be passed into the <code>releaseJdbcConnection</code> method when not needed anymore.
149      * <p>This strategy is necessary as JPA 1.0 does not provide a standard way to retrieve
150      * the underlying JDBC Connection (due to the fact that a JPA implementation might not
151      * work with a relational database at all).
152      * <p>Implementations are encouraged to return an unwrapped Connection object, i.e.
153      * the Connection as they got it from the connection pool. This makes it easier for
154      * application code to get at the underlying native JDBC Connection, like an
155      * OracleConnection, which is sometimes necessary for LOB handling etc. We assume
156      * that calling code knows how to properly handle the returned Connection object.
157      * <p>In a simple case where the returned Connection will be auto-closed with the
158      * EntityManager or can be released via the Connection object itself, an
159      * implementation can return a SimpleConnectionHandle that just contains the
160      * Connection. If some other object is needed in <code>releaseJdbcConnection</code>,
161      * an implementation should use a special handle that references that other object.
162      * @param entityManager the current JPA EntityManager
163      * @return a handle for the JDBC Connection, to be passed into
164      * <code>releaseJdbcConnection</code>, or <code>null</code>
165      * if no JDBC Connection can be retrieved
166      * @throws javax.persistence.PersistenceException if thrown by JPA methods
167      * @throws java.sql.SQLException if thrown by JDBC methods
168      * @see #releaseJdbcConnection
169      * @see org.springframework.jdbc.datasource.ConnectionHandle#getConnection
170      * @see org.springframework.jdbc.datasource.SimpleConnectionHandle
171      * @see JpaTransactionManager#setDataSource
172      * @see org.springframework.jdbc.support.nativejdbc.NativeJdbcExtractor
173      */
174     ConnectionHandle getJdbcConnection(EntityManager entityManager, boolean readOnly)
175             throws PersistenceException, SQLException  ;
176 
177     /**
178      * Release the given JDBC Connection, which has originally been retrieved
179      * via <code>getJdbcConnection</code>. This should be invoked in any case,
180      * to allow for proper release of the retrieved Connection handle.
181      * <p>An implementation might simply do nothing, if the Connection returned
182      * by <code>getJdbcConnection</code> will be implicitly closed when the JPA
183      * transaction completes or when the EntityManager is closed.
184      * @param conHandle the JDBC Connection handle to release
185      * @param entityManager the current JPA EntityManager
186      * @throws javax.persistence.PersistenceException if thrown by JPA methods
187      * @throws java.sql.SQLException if thrown by JDBC methods
188      * @see #getJdbcConnection
189      */
190     void releaseJdbcConnection(ConnectionHandle conHandle, EntityManager entityManager)
191             throws PersistenceException, SQLException  ;
192 
193 }
194
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags