org.springframework.orm.jdo
Interface JdoDialect

All Known Implementing Classes:

DefaultJdoDialect

public interface JdoDialect

SPI strategy that encapsulates certain functionality that standard JDO 1.0 does not offer despite being relevant in the context of O/R mapping, like access to the underlying JDBC Connection and explicit flushing of changes to the database.

To be implemented for specific JDO implementations like Kodo, Lido, or JPOX. Almost every O/R-based JDO implementation offers proprietary means to access the underlying JDBC Connection and to explicitly flush changes. JDO 2.0 respectively JDO/R 2.0 are likely to define standard ways for these: If applicable, a JdoDialect implementation for JDO 2.0 will be provided to leverage them with Spring's JDO support.

Since:

02.11.2003

Author:

Juergen Hoeller

See Also:

JdoTransactionManager.setJdoDialect(org.springframework.orm.jdo.JdoDialect), JdoAccessor.setJdoDialect(org.springframework.orm.jdo.JdoDialect)

Method Summary

void	applyQueryTimeout(javax.jdo.Query query, int timeout) Apply the given timeout to the given JDO query object.
java.lang.Object	beginTransaction(javax.jdo.Transaction transaction, TransactionDefinition definition) Begin the given JDO transaction, applying the semantics specified by the given Spring transaction definition (in particular, an isolation level and a timeout).
void	cleanupTransaction(java.lang.Object transactionData) Clean up the transaction via the given transaction data.
void	flush(javax.jdo.PersistenceManager pm) Flush the given PersistenceManager, i.e. flush all changes (that have been applied to persistent objects) to the underlying database.
ConnectionHandle	getJdbcConnection(javax.jdo.PersistenceManager pm, boolean readOnly) Retrieve the JDBC Connection that the given JDO PersistenceManager uses underneath, if accessing a relational database.
void	releaseJdbcConnection(ConnectionHandle conHandle, javax.jdo.PersistenceManager pm) Release the given JDBC Connection, which has originally been retrieved via getJdbcConnection.
DataAccessException	translateException(javax.jdo.JDOException ex) Translate the given JDOException to a corresponding exception from Spring's generic DataAccessException hierarchy.

Method Detail

beginTransaction

public java.lang.Object beginTransaction(javax.jdo.Transaction transaction,
                                         TransactionDefinition definition)
                                  throws javax.jdo.JDOException,
                                         java.sql.SQLException,
                                         TransactionException

Begin the given JDO transaction, applying the semantics specified by the given Spring transaction definition (in particular, an isolation level and a timeout). Invoked by JdoTransactionManager on transaction begin.

An implementation can configure the JDO Transaction object and then invoke begin, or invoke a special begin method that takes, for example, an isolation level.

An implementation can also apply read-only flag and isolation level to the underlying JDBC Connection before beginning the transaction. In that case, a transaction data object can be returned that holds the previous isolation level (and possibly other data), to be reset in cleanupTransaction.

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

java.sql.SQLException - if thrown by JDBC methods

TransactionException - in case of invalid arguments

See Also:

cleanupTransaction(java.lang.Object), Transaction.begin(), DataSourceUtils.prepareConnectionForTransaction(java.sql.Connection, org.springframework.transaction.TransactionDefinition)

cleanupTransaction

public void cleanupTransaction(java.lang.Object transactionData)

Clean up the transaction via the given transaction data. Invoked by JdoTransactionManager on transaction cleanup.

An implementation can, for example, reset read-only flag and isolation level of the underlying JDBC Connection.

Parameters:

transactionData - arbitrary object that holds transaction data, if any (as returned by beginTransaction)

See Also:

beginTransaction(javax.jdo.Transaction, org.springframework.transaction.TransactionDefinition), DataSourceUtils.resetConnectionAfterTransaction(java.sql.Connection, java.lang.Integer)

getJdbcConnection

public ConnectionHandle getJdbcConnection(javax.jdo.PersistenceManager pm,
                                          boolean readOnly)
                                   throws javax.jdo.JDOException,
                                          java.sql.SQLException

Retrieve the JDBC Connection that the given JDO PersistenceManager uses underneath, if accessing a relational database. This method will just get invoked if actually needing access to the underlying JDBC Connection, usually within an active JDO transaction (for example, by JdoTransactionManager). The returned handle will be passed into the releaseJdbcConnection method when not needed anymore.

This strategy is necessary as JDO 1.0 does not provide a standard way to retrieve the underlying JDBC Connection (due to the fact that a JDO implementation might not work with a relational database at all).

Implementations are encouraged to return an unwrapped Connection object, i.e. the Connection as they got it from the connection pool. This makes it easier for application code to get at the underlying native JDBC Connection, like an OracleConnection, which is sometimes necessary for LOB handling etc. We assume that calling code knows how to properly handle the returned Connection object.

In a simple case where the returned Connection will be auto-closed with the PersistenceManager or can be released via the Connection object itself, an implementation can return a SimpleConnectionHandle that just contains the Connection. If some other object is needed in releaseJdbcConnection, an implementation should use a special handle that references that other object.

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

java.sql.SQLException - if thrown by JDBC methods

See Also:

releaseJdbcConnection(org.springframework.jdbc.datasource.ConnectionHandle, javax.jdo.PersistenceManager), ConnectionHandle.getConnection(), SimpleConnectionHandle, JdoTransactionManager.setDataSource(javax.sql.DataSource), NativeJdbcExtractor

releaseJdbcConnection

public void releaseJdbcConnection(ConnectionHandle conHandle,
                                  javax.jdo.PersistenceManager pm)
                           throws javax.jdo.JDOException,
                                  java.sql.SQLException

Release the given JDBC Connection, which has originally been retrieved via getJdbcConnection. This should be invoked in any case, to allow for proper release of the retrieved Connection handle.

An implementation might simply do nothing, if the Connection returned by getJdbcConnection will be implicitly closed when the JDO transaction completes respectively when the PersistenceManager is closed.

Parameters:

conHandle - the JDBC Connection handle to release

pm - the current JDO PersistenceManager

Throws:

javax.jdo.JDOException - if thrown by JDO methods

java.sql.SQLException - if thrown by JDBC methods

See Also:

getJdbcConnection(javax.jdo.PersistenceManager, boolean)

applyQueryTimeout

public void applyQueryTimeout(javax.jdo.Query query,
                              int timeout)
                       throws javax.jdo.JDOException

Apply the given timeout to the given JDO query object.

Invoked by JdoTemplate with the remaining time of a specified transaction timeout, if any.

Parameters:

query - the JDO query object to apply the timeout to

timeout - the timeout value to apply

Throws:

javax.jdo.JDOException - if thrown by JDO methods

See Also:

JdoTemplate.prepareQuery(javax.jdo.Query)

flush

public void flush(javax.jdo.PersistenceManager pm)
           throws javax.jdo.JDOException

Flush the given PersistenceManager, i.e. flush all changes (that have been applied to persistent objects) to the underlying database. This method will just get invoked when eager flushing is actually necessary, for example when JDBC access code needs to see changes within the same transaction.

Parameters:

pm - the current JDO PersistenceManager

Throws:

javax.jdo.JDOException - in case of errors

See Also:

JdoAccessor.setFlushEager(boolean)

translateException

public DataAccessException translateException(javax.jdo.JDOException ex)

Translate the given JDOException to a corresponding exception from Spring's generic DataAccessException hierarchy. An implementation should apply PersistenceManagerFactoryUtils' standard exception translation if can't do anything more specific.

Of particular importance is the correct translation to DataIntegrityViolationException, for example on constraint violation. Unfortunately, standard JDO does not allow for portable detection of this.

Can use a SQLExceptionTranslator for translating underlying SQLExceptions in a database-specific fashion.

Parameters:

ex - the JDOException thrown

Returns:

the corresponding DataAccessException (must not be null)

See Also:

JdoAccessor.convertJdoAccessException(javax.jdo.JDOException), JdoTransactionManager.convertJdoAccessException(javax.jdo.JDOException), PersistenceManagerFactoryUtils.convertJdoAccessException(javax.jdo.JDOException), DataIntegrityViolationException, SQLExceptionTranslator