Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| The Spring Framework
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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, such as access to the underlying JDBC Connection and explicit flushing of changes to the database. Also defines various further hooks that even go beyond standard JDO 2.0.

To be implemented for specific JDO providers such as JPOX, Kodo, Lido, Versant Open Access. Almost every O/R-based JDO provider offers proprietary means to access the underlying JDBC Connection and to explicitly flush changes; hence, this would be the minimum functionality level that should be supported.

JDO 2.0 defines standard ways for most of the functionality covered here. Hence, Spring's DefaultJdoDialect uses the corresponding JDO 2.0 methods by default, to be overridden in a vendor-specific fashion if necessary. Vendor-specific subclasses of DefaultJdoDialect are still required for special transaction semantics and more sophisticated exception translation (if needed).

In general, it is recommended to derive from DefaultJdoDialect instead of implementing this interface directly. This allows for inheriting common behavior (present and future) from DefaultJdoDialect, only overriding specific hooks to plug in concrete vendor-specific behavior.

Since:
  02.11.2003
Author:
  Juergen Hoeller
See Also:
  `JdoTransactionManager.setJdoDialect(org.springframework.orm.jdo.JdoDialect)`, `JdoAccessor.setJdoDialect(org.springframework.orm.jdo.JdoDialect)`, `DefaultJdoDialect`

Method Summary
`void` | `applyQueryTimeout(javax.jdo.Query query, int timeout)` Apply the given timeout to the given JDO query object.
`Object` | `attachCopy(javax.jdo.PersistenceManager pm, Object detachedEntity)` Reattach the given detached instance (for example, a web form object) with the current JDO transaction, merging its changes into the current persistence instance that represents the corresponding entity.
`Collection` | `attachCopyAll(javax.jdo.PersistenceManager pm, Collection detachedEntities)` Reattach the given detached instances (for example, web form objects) with the current JDO transaction, merging their changes into the current persistence instances that represent the corresponding entities.
`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(Object transactionData)` Clean up the transaction via the given transaction data.
`Object` | `detachCopy(javax.jdo.PersistenceManager pm, Object entity)` Detach a copy of the given persistent instance from the current JDO transaction, for use outside a JDO transaction (for example, as web form object).
`Collection` | `detachCopyAll(javax.jdo.PersistenceManager pm, Collection entities)` Detach copies of the given persistent instances from the current JDO transaction, for use outside a JDO transaction (for example, as web form objects).
`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.
`javax.jdo.Query` | `newNamedQuery(javax.jdo.PersistenceManager pm, Class entityClass, String queryName)` Create a new Query object for the given named query.
`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

    Object beginTransaction(javax.jdo.Transaction transaction,
                            TransactionDefinition definition)
                            throws javax.jdo.JDOException,
                                   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`.

  Implementations can also use the Spring transaction name, as exposed by the passed-in TransactionDefinition, to optimize for specific data access use cases (effectively using the current transaction name as use case identifier).

  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:
    `cleanupTransaction(java.lang.Object)`, `Transaction.begin()`, `DataSourceUtils.prepareConnectionForTransaction(java.sql.Connection, org.springframework.transaction.TransactionDefinition)`

### cleanupTransaction

    void cleanupTransaction(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. Furthermore, an exposed data access use case can be reset here.

  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

    ConnectionHandle getJdbcConnection(javax.jdo.PersistenceManager pm,
                                       boolean readOnly)
                                       throws javax.jdo.JDOException,
                                              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 provider 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
    `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:
    `releaseJdbcConnection(org.springframework.jdbc.datasource.ConnectionHandle, javax.jdo.PersistenceManager)`, `ConnectionHandle.getConnection()`, `SimpleConnectionHandle`, `JdoTransactionManager.setDataSource(javax.sql.DataSource)`, `NativeJdbcExtractor`

### releaseJdbcConnection

    void releaseJdbcConnection(ConnectionHandle conHandle,
                               javax.jdo.PersistenceManager pm)
                               throws javax.jdo.JDOException,
                                      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 or 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
    `SQLException` - if thrown by JDBC methods
  See Also:
    `getJdbcConnection(javax.jdo.PersistenceManager, boolean)`

### detachCopy

    Object detachCopy(javax.jdo.PersistenceManager pm,
                      Object entity)
                      throws javax.jdo.JDOException

  Detach a copy of the given persistent instance from the current JDO transaction, for use outside a JDO transaction (for example, as web form object).

  Parameters:
    `pm` - the current JDO PersistenceManager
    `entity` - the persistent instance to detach
  Returns:
    the corresponding detached instance
  Throws:
    `javax.jdo.JDOException` - in case of errors
  See Also:
    `PersistenceManager.detachCopy(Object)`

### detachCopyAll

    Collection detachCopyAll(javax.jdo.PersistenceManager pm,
                             Collection entities)
                             throws javax.jdo.JDOException

  Detach copies of the given persistent instances from the current JDO transaction, for use outside a JDO transaction (for example, as web form objects).

  Parameters:
    `pm` - the current JDO PersistenceManager
    `entities` - the persistent instances to detach
  Returns:
    the corresponding detached instances
  Throws:
    `javax.jdo.JDOException` - in case of errors
  See Also:
    `PersistenceManager.detachCopyAll(java.util.Collection)`

### attachCopy

    Object attachCopy(javax.jdo.PersistenceManager pm,
                      Object detachedEntity)
                      throws javax.jdo.JDOException

  Reattach the given detached instance (for example, a web form object) with the current JDO transaction, merging its changes into the current persistence instance that represents the corresponding entity.

  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

    Collection attachCopyAll(javax.jdo.PersistenceManager pm,
                             Collection detachedEntities)
                             throws javax.jdo.JDOException

  Reattach the given detached instances (for example, web form objects) with the current JDO transaction, merging their changes into the current persistence instances that represent the corresponding entities.

  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

    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)`

### newNamedQuery

    javax.jdo.Query newNamedQuery(javax.jdo.PersistenceManager pm,
                                  Class entityClass,
                                  String queryName)
                                  throws javax.jdo.JDOException

  Create a new Query object for the given named query.

  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

    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)`

### translateException

    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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| The Spring Framework
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2007 The Spring Framework.