JdoDialect


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.jdo;
18  
19  import java.sql.SQLException  ;
20  import java.util.Collection  ;
21  
22  import javax.jdo.JDOException;
23  import javax.jdo.PersistenceManager;
24  import javax.jdo.Query;
25  import javax.jdo.Transaction;
26  
27  import org.springframework.dao.DataAccessException;
28  import org.springframework.jdbc.datasource.ConnectionHandle;
29  import org.springframework.transaction.TransactionDefinition;
30  import org.springframework.transaction.TransactionException;
31  
32  /**
33   * SPI strategy that encapsulates certain functionality that standard JDO 1.0 does
34   * not offer despite being relevant in the context of O/R mapping, such as access to
35   * the underlying JDBC Connection and explicit flushing of changes to the database.
36   * Also defines various further hooks that even go beyond standard JDO 2.0.
37   *
38   * <p>To be implemented for specific JDO providers such as JPOX, Kodo, Lido,
39   * Versant Open Access. Almost every O/R-based JDO provider offers proprietary
40   * means to access the underlying JDBC Connection and to explicitly flush changes;
41   * hence, this would be the minimum functionality level that should be supported.
42   *
43   * <p>JDO 2.0 defines standard ways for most of the functionality covered here.
44   * Hence, Spring's DefaultJdoDialect uses the corresponding JDO 2.0 methods
45   * by default, to be overridden in a vendor-specific fashion if necessary.
46   * Vendor-specific subclasses of DefaultJdoDialect are still required for special
47   * transaction semantics and more sophisticated exception translation (if needed).
48   *
49   * <p>In general, it is recommended to derive from DefaultJdoDialect instead of
50   * implementing this interface directly. This allows for inheriting common
51   * behavior (present and future) from DefaultJdoDialect, only overriding
52   * specific hooks to plug in concrete vendor-specific behavior.
53   *
54   * @author Juergen Hoeller
55   * @since 02.11.2003
56   * @see JdoTransactionManager#setJdoDialect
57   * @see JdoAccessor#setJdoDialect
58   * @see DefaultJdoDialect
59   */
60  public interface JdoDialect {
61  
62      //-------------------------------------------------------------------------
63      // Hooks for transaction management (used by JdoTransactionManager)
64      //-------------------------------------------------------------------------
65  
66      /**
67       * Begin the given JDO transaction, applying the semantics specified by the
68       * given Spring transaction definition (in particular, an isolation level
69       * and a timeout). Invoked by JdoTransactionManager on transaction begin.
70       * <p>An implementation can configure the JDO Transaction object and then
71       * invoke <code>begin</code>, or invoke a special begin method that takes,
72       * for example, an isolation level.
73       * <p>An implementation can also apply read-only flag and isolation level to the
74       * underlying JDBC Connection before beginning the transaction. In that case,
75       * a transaction data object can be returned that holds the previous isolation
76       * level (and possibly other data), to be reset in <code>cleanupTransaction</code>.
77       * <p>Implementations can also use the Spring transaction name, as exposed by the
78       * passed-in TransactionDefinition, to optimize for specific data access use cases
79       * (effectively using the current transaction name as use case identifier).
80       * @param transaction the JDO transaction to begin
81       * @param definition the Spring transaction definition that defines semantics
82       * @return an arbitrary object that holds transaction data, if any
83       * (to be passed into cleanupTransaction)
84       * @throws JDOException if thrown by JDO methods
85       * @throws SQLException if thrown by JDBC methods
86       * @throws TransactionException in case of invalid arguments
87       * @see #cleanupTransaction
88       * @see javax.jdo.Transaction#begin
89       * @see org.springframework.jdbc.datasource.DataSourceUtils#prepareConnectionForTransaction
90       */
91      Object   beginTransaction(Transaction transaction, TransactionDefinition definition)
92              throws JDOException, SQLException  , TransactionException;
93  
94      /**
95       * Clean up the transaction via the given transaction data.
96       * Invoked by JdoTransactionManager on transaction cleanup.
97       * <p>An implementation can, for example, reset read-only flag and
98       * isolation level of the underlying JDBC Connection. Furthermore,
99       * an exposed data access use case can be reset here.
100      * @param transactionData arbitrary object that holds transaction data, if any
101      * (as returned by beginTransaction)
102      * @see #beginTransaction
103      * @see org.springframework.jdbc.datasource.DataSourceUtils#resetConnectionAfterTransaction
104      */
105     void cleanupTransaction(Object   transactionData);
106 
107     /**
108      * Retrieve the JDBC Connection that the given JDO PersistenceManager uses underneath,
109      * if accessing a relational database. This method will just get invoked if actually
110      * needing access to the underlying JDBC Connection, usually within an active JDO
111      * transaction (for example, by JdoTransactionManager). The returned handle will
112      * be passed into the <code>releaseJdbcConnection</code> method when not needed anymore.
113      * <p>This strategy is necessary as JDO 1.0 does not provide a standard way to retrieve
114      * the underlying JDBC Connection (due to the fact that a JDO provider might not work
115      * with a relational database at all).
116      * <p>Implementations are encouraged to return an unwrapped Connection object, i.e.
117      * the Connection as they got it from the connection pool. This makes it easier for
118      * application code to get at the underlying native JDBC Connection, like an
119      * OracleConnection, which is sometimes necessary for LOB handling etc. We assume
120      * that calling code knows how to properly handle the returned Connection object.
121      * <p>In a simple case where the returned Connection will be auto-closed with the
122      * PersistenceManager or can be released via the Connection object itself, an
123      * implementation can return a SimpleConnectionHandle that just contains the
124      * Connection. If some other object is needed in <code>releaseJdbcConnection</code>,
125      * an implementation should use a special handle that references that other object.
126      * @param pm the current JDO PersistenceManager
127      * @return a handle for the JDBC Connection, to be passed into
128      * <code>releaseJdbcConnection</code>, or <code>null</code>
129      * if no JDBC Connection can be retrieved
130      * @throws JDOException if thrown by JDO methods
131      * @throws SQLException if thrown by JDBC methods
132      * @see #releaseJdbcConnection
133      * @see org.springframework.jdbc.datasource.ConnectionHandle#getConnection
134      * @see org.springframework.jdbc.datasource.SimpleConnectionHandle
135      * @see JdoTransactionManager#setDataSource
136      * @see org.springframework.jdbc.support.nativejdbc.NativeJdbcExtractor
137      */
138     ConnectionHandle getJdbcConnection(PersistenceManager pm, boolean readOnly)
139             throws JDOException, SQLException  ;
140 
141     /**
142      * Release the given JDBC Connection, which has originally been retrieved
143      * via <code>getJdbcConnection</code>. This should be invoked in any case,
144      * to allow for proper release of the retrieved Connection handle.
145      * <p>An implementation might simply do nothing, if the Connection returned
146      * by <code>getJdbcConnection</code> will be implicitly closed when the JDO
147      * transaction completes or when the PersistenceManager is closed.
148      * @param conHandle the JDBC Connection handle to release
149      * @param pm the current JDO PersistenceManager
150      * @throws JDOException if thrown by JDO methods
151      * @throws SQLException if thrown by JDBC methods
152      * @see #getJdbcConnection
153      */
154     void releaseJdbcConnection(ConnectionHandle conHandle, PersistenceManager pm)
155             throws JDOException, SQLException  ;
156 
157 
158     //-------------------------------------------------------------------------
159     // Hooks for special data access operations (used by JdoTemplate)
160     //-------------------------------------------------------------------------
161 
162     /**
163      * Detach a copy of the given persistent instance from the current JDO transaction,
164      * for use outside a JDO transaction (for example, as web form object).
165      * @param pm the current JDO PersistenceManager
166      * @param entity the persistent instance to detach
167      * @throws JDOException in case of errors
168      * @see javax.jdo.PersistenceManager#detachCopy(Object)
169      */
170     Object   detachCopy(PersistenceManager pm, Object   entity) throws JDOException;
171 
172     /**
173      * Detach copies of the given persistent instances from the current JDO transaction,
174      * for use outside a JDO transaction (for example, as web form objects).
175      * @param pm the current JDO PersistenceManager
176      * @param entities the persistent instances to detach
177      * @throws JDOException in case of errors
178      * @see javax.jdo.PersistenceManager#detachCopyAll(java.util.Collection)
179      */
180     Collection   detachCopyAll(PersistenceManager pm, Collection   entities) throws JDOException;
181 
182     /**
183      * Reattach the given detached instance (for example, a web form object) with
184      * the current JDO transaction, merging its changes into the current persistence
185      * instance that represents the corresponding entity.
186      * @param pm the current JDO PersistenceManager
187      * @param detachedEntity the detached instance to attach
188      * @return the corresponding persistent instance
189      * @throws JDOException in case of errors
190      * @see javax.jdo.PersistenceManager#makePersistent(Object)
191      */
192     Object   attachCopy(PersistenceManager pm, Object   detachedEntity) throws JDOException;
193 
194     /**
195      * Reattach the given detached instances (for example, web form objects) with
196      * the current JDO transaction, merging their changes into the current persistence
197      * instances that represent the corresponding entities.
198      * @param pm the current JDO PersistenceManager
199      * @param detachedEntities the detached instances to reattach
200      * @return the corresponding persistent instances
201      * @throws JDOException in case of errors
202      * @see javax.jdo.PersistenceManager#makePersistentAll(java.util.Collection)
203      */
204     Collection   attachCopyAll(PersistenceManager pm, Collection   detachedEntities) throws JDOException;
205 
206     /**
207      * Flush the given PersistenceManager, i.e. flush all changes (that have been
208      * applied to persistent objects) to the underlying database. This method will
209      * just get invoked when eager flushing is actually necessary, for example when
210      * JDBC access code needs to see changes within the same transaction.
211      * @param pm the current JDO PersistenceManager
212      * @throws JDOException in case of errors
213      * @see JdoAccessor#setFlushEager
214      */
215     void flush(PersistenceManager pm) throws JDOException;
216 
217     /**
218      * Create a new Query object for the given named query.
219      * @param pm the current JDO PersistenceManager
220      * @param entityClass a persistent class
221      * @param queryName the name of the query
222      * @return the Query object
223      * @throws JDOException in case of errors
224      * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
225      */
226     Query newNamedQuery(PersistenceManager pm, Class   entityClass, String   queryName) throws JDOException;
227 
228     /**
229      * Apply the given timeout to the given JDO query object.
230      * <p>Invoked by JdoTemplate with the remaining time of a specified
231      * transaction timeout, if any.
232      * @param query the JDO query object to apply the timeout to
233      * @param timeout the timeout value to apply
234      * @throws JDOException if thrown by JDO methods
235      * @see JdoTemplate#prepareQuery
236      */
237     void applyQueryTimeout(Query query, int timeout) throws JDOException;
238 
239 
240     //-----------------------------------------------------------------------------------
241     // Hook for exception translation (used by JdoTransactionManager and JdoTemplate)
242     //-----------------------------------------------------------------------------------
243 
244     /**
245      * Translate the given JDOException to a corresponding exception from Spring's
246      * generic DataAccessException hierarchy. An implementation should apply
247      * PersistenceManagerFactoryUtils' standard exception translation if can't do
248      * anything more specific.
249      * <p>Of particular importance is the correct translation to
250      * DataIntegrityViolationException, for example on constraint violation.
251      * Unfortunately, standard JDO does not allow for portable detection of this.
252      * <p>Can use a SQLExceptionTranslator for translating underlying SQLExceptions
253      * in a database-specific fashion.
254      * @param ex the JDOException thrown
255      * @return the corresponding DataAccessException (must not be <code>null</code>)
256      * @see JdoAccessor#convertJdoAccessException
257      * @see JdoTransactionManager#convertJdoAccessException
258      * @see PersistenceManagerFactoryUtils#convertJdoAccessException
259      * @see org.springframework.dao.DataIntegrityViolationException
260      * @see org.springframework.jdbc.support.SQLExceptionTranslator
261      */
262     DataAccessException translateException(JDOException ex);
263 
264 }
265
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags