The Spring Framework

org.springframework.orm.jdo
Class DefaultJdoDialect

java.lang.Object
  extended by org.springframework.orm.jdo.DefaultJdoDialect
All Implemented Interfaces:
PersistenceExceptionTranslator, JdoDialect

public class DefaultJdoDialect
extends Object
implements JdoDialect, PersistenceExceptionTranslator

Default implementation of the JdoDialect interface. Updated to leverage the JDO 2.0 API when available, as of Spring 1.2. Used as default dialect by JdoAccessor and JdoTransactionManager.

Simply begins a standard JDO transaction in beginTransaction. Returns a handle for a JDO2 DataStoreConnection on getJdbcConnection. Calls the corresponding JDO2 operations on detachCopy(All), attachCopy(All), flush and newNamedQuery. Ignores a given query timeout in applyQueryTimeout. Uses a Spring SQLExceptionTranslator for exception translation, if applicable.

Note that, even with JDO2, vendor-specific subclasses are still necessary for special transaction semantics and more sophisticated exception translation. Furthermore, vendor-specific subclasses are encouraged to expose the native JDBC Connection on getJdbcConnection, rather than JDO2's wrapper handle.

This class also implements the PersistenceExceptionTranslator interface, as autodetected by Spring's PersistenceExceptionTranslationPostProcessor, for AOP-based translation of native exceptions to Spring DataAccessExceptions. Hence, the presence of a standard DefaultJdoDialect bean automatically enables a PersistenceExceptionTranslationPostProcessor to translate JDO exceptions.

Since:
1.1
Author:
Juergen Hoeller
See Also:
setJdbcExceptionTranslator(org.springframework.jdbc.support.SQLExceptionTranslator), JdoAccessor.setJdoDialect(org.springframework.orm.jdo.JdoDialect), JdoTransactionManager.setJdoDialect(org.springframework.orm.jdo.JdoDialect), PersistenceExceptionTranslationPostProcessor

Field Summary
protected  Log logger
           
 
Constructor Summary
DefaultJdoDialect()
          Create a new DefaultJdoDialect.
 
Method Summary
 void applyQueryTimeout(javax.jdo.Query query, int remainingTimeInSeconds)
          This implementation logs a warning that it cannot apply a query timeout.
 Object attachCopy(javax.jdo.PersistenceManager pm, Object detachedEntity)
          This implementation delegates to JDO 2.0's makePersistent method, which also serves as facility for reattaching objects as of JDO 2.0 final draft.
 Collection attachCopyAll(javax.jdo.PersistenceManager pm, Collection detachedEntities)
          This implementation delegates to JDO 2.0's makePersistentAll method, which also serves as facility for reattaching objects as of JDO 2.0 final draft.
 Object beginTransaction(javax.jdo.Transaction transaction, TransactionDefinition definition)
          This implementation invokes the standard JDO Transaction.begin method.
 void cleanupTransaction(Object transactionData)
          This implementation does nothing, as the default beginTransaction implementation does not require any cleanup.
 Object detachCopy(javax.jdo.PersistenceManager pm, Object entity)
          This implementation delegates to JDO 2.0's detachCopy method.
 Collection detachCopyAll(javax.jdo.PersistenceManager pm, Collection entities)
          This implementation delegates to JDO 2.0's detachCopyAll method.
protected  String extractSqlStringFromException(javax.jdo.JDOException ex)
          Template method for extracting a SQL String from the given exception.
 void flush(javax.jdo.PersistenceManager pm)
          This implementation delegates to JDO 2.0's flush method.
 ConnectionHandle getJdbcConnection(javax.jdo.PersistenceManager pm, boolean readOnly)
          This implementation returns a DataStoreConnectionHandle for JDO2, which will also work on JDO1 until actually accessing the JDBC Connection.
 SQLExceptionTranslator getJdbcExceptionTranslator()
          Return the JDBC exception translator for this dialect, if any.
 javax.jdo.Query newNamedQuery(javax.jdo.PersistenceManager pm, Class entityClass, String queryName)
          This implementation delegates to JDO 2.0's newNamedQuery method.
 void releaseJdbcConnection(ConnectionHandle conHandle, javax.jdo.PersistenceManager pm)
          This implementation does nothing, assuming that the Connection will implicitly be closed with the PersistenceManager.
 void setJdbcExceptionTranslator(SQLExceptionTranslator jdbcExceptionTranslator)
          Set the JDBC exception translator for this dialect.
 DataAccessException translateException(javax.jdo.JDOException ex)
          This implementation delegates to PersistenceManagerFactoryUtils.
 DataAccessException translateExceptionIfPossible(RuntimeException ex)
          Implementation of the PersistenceExceptionTranslator interface, as autodetected by Spring's PersistenceExceptionTranslationPostProcessor.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected final Log logger
Constructor Detail

DefaultJdoDialect

public DefaultJdoDialect()
Create a new DefaultJdoDialect.

Method Detail

setJdbcExceptionTranslator

public void setJdbcExceptionTranslator(SQLExceptionTranslator jdbcExceptionTranslator)
Set the JDBC exception translator for this dialect.

Applied to any SQLException root cause of a JDOException, if specified. The default is to rely on the JDO provider's native exception translation.

Parameters:
jdbcExceptionTranslator - exception translator
See Also:
SQLException, JDOException.getCause(), SQLErrorCodeSQLExceptionTranslator, SQLStateSQLExceptionTranslator

getJdbcExceptionTranslator

public SQLExceptionTranslator getJdbcExceptionTranslator()
Return the JDBC exception translator for this dialect, if any.


beginTransaction

public Object beginTransaction(javax.jdo.Transaction transaction,
                               TransactionDefinition definition)
                        throws javax.jdo.JDOException,
                               SQLException,
                               TransactionException
This implementation invokes the standard JDO Transaction.begin method. Throws an InvalidIsolationLevelException if a non-default isolation level is set.

Specified by:
beginTransaction in interface JdoDialect
Parameters:
transaction - the JDO transaction to begin
definition - the Spring transaction definition that defines semantics
Returns:
an arbitrary object that holds transaction data, if any (to be passed into cleanupTransaction)
Throws:
javax.jdo.JDOException - if thrown by JDO methods
SQLException - if thrown by JDBC methods
TransactionException - in case of invalid arguments
See Also:
Transaction.begin(), InvalidIsolationLevelException

cleanupTransaction

public void cleanupTransaction(Object transactionData)
This implementation does nothing, as the default beginTransaction implementation does not require any cleanup.

Specified by:
cleanupTransaction in interface JdoDialect
Parameters:
transactionData - arbitrary object that holds transaction data, if any (as returned by beginTransaction)
See Also:
beginTransaction(javax.jdo.Transaction, org.springframework.transaction.TransactionDefinition)

getJdbcConnection

public ConnectionHandle getJdbcConnection(javax.jdo.PersistenceManager pm,
                                          boolean readOnly)
                                   throws javax.jdo.JDOException,
                                          SQLException
This implementation returns a DataStoreConnectionHandle for JDO2, which will also work on JDO1 until actually accessing the JDBC Connection.

For pre-JDO2 implementations, override this method to return the Connection through the corresponding vendor-specific mechanism, or null if the Connection is not retrievable.

NOTE: A JDO2 DataStoreConnection is always a wrapper, never the native JDBC Connection. If you need access to the native JDBC Connection (or the connection pool handle, to be unwrapped via a Spring NativeJdbcExtractor), override this method to return the native Connection through the corresponding vendor-specific mechanism.

A JDO2 DataStoreConnection is only "borrowed" from the PersistenceManager: it needs to be returned as early as possible. Effectively, JDO2 requires the fetched Connection to be closed before continuing PersistenceManager work. For this reason, the exposed ConnectionHandle eagerly releases its JDBC Connection at the end of each JDBC data access operation (that is, on DataSourceUtils.releaseConnection).

Specified by:
getJdbcConnection in interface JdoDialect
Parameters:
pm - the current JDO PersistenceManager
Returns:
a handle for the JDBC Connection, to be passed into releaseJdbcConnection, or null if no JDBC Connection can be retrieved
Throws:
javax.jdo.JDOException - if thrown by JDO methods
SQLException - if thrown by JDBC methods
See Also:
PersistenceManager.getDataStoreConnection(), NativeJdbcExtractor, DataSourceUtils.releaseConnection(java.sql.Connection, javax.sql.DataSource)

releaseJdbcConnection

public void releaseJdbcConnection(ConnectionHandle conHandle,
                                  javax.jdo.PersistenceManager pm)
                           throws javax.jdo.JDOException,
                                  SQLException
This implementation does nothing, assuming that the Connection will implicitly be closed with the PersistenceManager.

If the JDO provider returns a Connection handle that it expects the application to close, the dialect needs to invoke Connection.close here.

Specified by:
releaseJdbcConnection in interface JdoDialect
Parameters:
conHandle - the JDBC Connection handle to release
pm - the current JDO PersistenceManager
Throws:
javax.jdo.JDOException - if thrown by JDO methods
SQLException - if thrown by JDBC methods
See Also:
Connection.close()

detachCopy

public Object detachCopy(javax.jdo.PersistenceManager pm,
                         Object entity)
                  throws javax.jdo.JDOException
This implementation delegates to JDO 2.0's detachCopy method.

To be overridden for pre-JDO2 implementations, using the corresponding vendor-specific mechanism there.

Specified by:
detachCopy in interface JdoDialect
Parameters:
pm - the current JDO PersistenceManager
entity - the persistent instance to detach
Throws:
javax.jdo.JDOException - in case of errors
See Also:
PersistenceManager.detachCopy(Object)

detachCopyAll

public Collection detachCopyAll(javax.jdo.PersistenceManager pm,
                                Collection entities)
                         throws javax.jdo.JDOException
This implementation delegates to JDO 2.0's detachCopyAll method.

To be overridden for pre-JDO2 implementations, using the corresponding vendor-specific mechanism there.

Specified by:
detachCopyAll in interface JdoDialect
Parameters:
pm - the current JDO PersistenceManager
entities - the persistent instances to detach
Throws:
javax.jdo.JDOException - in case of errors
See Also:
PersistenceManager.detachCopyAll(java.util.Collection)

attachCopy

public Object attachCopy(javax.jdo.PersistenceManager pm,
                         Object detachedEntity)
                  throws javax.jdo.JDOException
This implementation delegates to JDO 2.0's makePersistent method, which also serves as facility for reattaching objects as of JDO 2.0 final draft.

To be overridden for pre-JDO2 implementations, using the corresponding vendor-specific mechanism there.

Note that previous JDO 2.0 drafts specified a dedicated attachCopy method for this purpose, which Spring's DefaultJdoDialect used to delegate to. As of Spring 2.0, this has been adapted to the final JDO 2.0 API. You can still create a custom JdoDialect that uses the pre-final API methods, of course.

Specified by:
attachCopy in interface JdoDialect
Parameters:
pm - the current JDO PersistenceManager
detachedEntity - the detached instance to attach
Returns:
the corresponding persistent instance
Throws:
javax.jdo.JDOException - in case of errors
See Also:
PersistenceManager.makePersistent(Object)

attachCopyAll

public Collection attachCopyAll(javax.jdo.PersistenceManager pm,
                                Collection detachedEntities)
                         throws javax.jdo.JDOException
This implementation delegates to JDO 2.0's makePersistentAll method, which also serves as facility for reattaching objects as of JDO 2.0 final draft.

To be overridden for pre-JDO2 implementations, using the corresponding vendor-specific mechanism there.

Note that previous JDO 2.0 drafts specified a dedicated attachCopy method for this purpose, which Spring's DefaultJdoDialect used to delegate to. As of Spring 2.0, this has been adapted to the final JDO 2.0 API. You can still create a custom JdoDialect that uses the pre-final API methods, of course.

Specified by:
attachCopyAll in interface JdoDialect
Parameters:
pm - the current JDO PersistenceManager
detachedEntities - the detached instances to reattach
Returns:
the corresponding persistent instances
Throws:
javax.jdo.JDOException - in case of errors
See Also:
PersistenceManager.makePersistentAll(java.util.Collection)

flush

public void flush(javax.jdo.PersistenceManager pm)
           throws javax.jdo.JDOException
This implementation delegates to JDO 2.0's flush method.

To be overridden for pre-JDO2 implementations, using the corresponding vendor-specific mechanism there.

Specified by:
flush in interface JdoDialect
Parameters:
pm - the current JDO PersistenceManager
Throws:
javax.jdo.JDOException - in case of errors
See Also:
PersistenceManager.flush()

newNamedQuery

public javax.jdo.Query newNamedQuery(javax.jdo.PersistenceManager pm,
                                     Class entityClass,
                                     String queryName)
                              throws javax.jdo.JDOException
This implementation delegates to JDO 2.0's newNamedQuery method.

To be overridden for pre-JDO2 implementations, using the corresponding vendor-specific mechanism there.

Specified by:
newNamedQuery in interface JdoDialect
Parameters:
pm - the current JDO PersistenceManager
entityClass - a persistent class
queryName - the name of the query
Returns:
the Query object
Throws:
javax.jdo.JDOException - in case of errors
See Also:
PersistenceManager.newNamedQuery(Class, String)

applyQueryTimeout

public void applyQueryTimeout(javax.jdo.Query query,
                              int remainingTimeInSeconds)
                       throws javax.jdo.JDOException
This implementation logs a warning that it cannot apply a query timeout.

Specified by:
applyQueryTimeout in interface JdoDialect
Parameters:
query - the JDO query object to apply the timeout to
remainingTimeInSeconds - the timeout value to apply
Throws:
javax.jdo.JDOException - if thrown by JDO methods
See Also:
JdoTemplate.prepareQuery(javax.jdo.Query)

translateExceptionIfPossible

public DataAccessException translateExceptionIfPossible(RuntimeException ex)
Implementation of the PersistenceExceptionTranslator interface, as autodetected by Spring's PersistenceExceptionTranslationPostProcessor.

Converts the exception if it is a JDOException, using this JdoDialect. Else returns null to indicate an unknown exception.

Specified by:
translateExceptionIfPossible in interface PersistenceExceptionTranslator
Parameters:
ex - a RuntimeException thrown
Returns:
the corresponding DataAccessException (or null if the exception could not be translated, as in this case it may result from user code rather than an actual persistence problem)
See Also:
PersistenceExceptionTranslationPostProcessor, translateException(javax.jdo.JDOException)

translateException

public DataAccessException translateException(javax.jdo.JDOException ex)
This implementation delegates to PersistenceManagerFactoryUtils.

Specified by:
translateException in interface JdoDialect
Parameters:
ex - the JDOException thrown
Returns:
the corresponding DataAccessException (must not be null)
See Also:
PersistenceManagerFactoryUtils.convertJdoAccessException(javax.jdo.JDOException)

extractSqlStringFromException

protected String extractSqlStringFromException(javax.jdo.JDOException ex)
Template method for extracting a SQL String from the given exception.

Default implementation always returns null. Can be overridden in subclasses to extract SQL Strings for vendor-specific exception classes.

Parameters:
ex - the JDOException, containing a SQLException
Returns:
the SQL String, or null if none found

The Spring Framework

Copyright © 2002-2007 The Spring Framework.