DefaultJdoDialect (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.orm.jdo

## Class DefaultJdoDialect

- java.lang.Object
- - 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 build on JDO 2.0 or higher, as of Spring 2.5. 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 PersistenceManager operation on `flush` 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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultJdoDialect()` Create a new DefaultJdoDialect.
    `DefaultJdoDialect(Object connectionFactory)` Create a new DefaultJdoDialect.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `applyQueryTimeout(javax.jdo.Query query, int remainingTimeInSeconds)` This implementation applies a JDO 3.0 query timeout, if available.
    `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.
    `protected String` | `extractSqlStringFromException(javax.jdo.JDOException ex)` Template method for extracting a SQL String from the given exception.
    `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.
    `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.

    - #### DefaultJdoDialect

          public DefaultJdoDialect(Object connectionFactory)

      Create a new DefaultJdoDialect.
      Parameters:
        `connectionFactory` - the connection factory of the JDO PersistenceManagerFactory, which is used to initialize the default JDBC exception translator
      See Also:
        `PersistenceManagerFactory.getConnectionFactory()`, `PersistenceManagerFactoryUtils.newJdbcExceptionTranslator(Object)`

  - ### 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
        `readOnly` - whether the Connection is only needed for read-only purposes
      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()`

    - #### applyQueryTimeout

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

      This implementation applies a JDO 3.0 query timeout, if available. Otherwise, it sets the JPA 2.0 query hints "javax.persistence.lock.timeout" and "javax.persistence.query.timeout", assuming that JDO providers are often JPA providers as well.
      Specified by:
        `applyQueryTimeout` in interface `JdoDialect`
      Parameters:
        `query` - the JDO query object to apply the timeout to
        `remainingTimeInSeconds` - the timeout value (seconds) 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