The Spring Framework

## org.springframework.orm.toplink
Interface TopLinkCallback

All Known Implementing Classes:
  SessionReadCallback, UnitOfWorkCallback

    public interface TopLinkCallback

Callback interface for TopLink code. To be used with `TopLinkTemplate`'s execution methods, often as anonymous classes within a method implementation. A typical implementation will call TopLink Session CRUD to perform some operations on persistent objects.

The `Session` that gets passed into the `doInTopLink` method is usually a thread-safe `ClientSession`. Since this provides access to the TopLink shared cache, it is possible for implementations of this interface to return references to read-only objects from the shared cache. These objects must not be modified by application code outside of the DAO layer. If persistent objects need to be edited, they should be loaded from (or registered with) a TopLink UnitOfWork, or they should be explicitly copied and merged back into a `UnitOfWork` at a later point of time.

Users can access a `UnitOfWork` by using the `getActiveUnitOfWork` method on the `Session`. Normally, this will only be done when there is an active non-read-only transaction being managed by Spring's `TopLinkTransactionManager` or by an external transaction controller (usually a J2EE server's JTA provider, configured in TopLink). The `getActiveUnitOfWork` method will return `null` outside of a managed transaction.

Author:
  Juergen Hoeller, James Clark
See Also:
  `TopLinkTemplate`, `TopLinkTransactionManager`

Method Summary
`Object` `doInTopLink(oracle.toplink.sessions.Session session)` Gets called by `TopLinkTemplate.execute` with an active `Session`.

Method Detail

### doInTopLink

    Object doInTopLink(oracle.toplink.sessions.Session session)
                       throws oracle.toplink.exceptions.TopLinkException

  Gets called by `TopLinkTemplate.execute` with an active `Session`. Does not need to care about activating or closing the TopLink `Session`, or handling transactions.

  Note that write operations should usually be performed on the active `UnitOfWork` within an externally controlled transaction, through calling `getActiveUnitOfWork`. However, an implementation can also choose to use `acquireUnitOfWork` to create an independent `UnitOfWork`, which it needs to commit at the end of the operation.

  Allows for returning a result object created within the callback, i.e. a domain object or a collection of domain objects. A thrown custom RuntimeException is treated as an application exception: It gets propagated to the caller of the template.

  Parameters:
    `session` - active TopLink Session
  Returns:
    a result object, or `null` if none
  Throws:
    `oracle.toplink.exceptions.TopLinkException` - if thrown by the TopLink API
  See Also:
    `Session.getActiveUnitOfWork()`, `Session.acquireUnitOfWork()`, `TopLinkTemplate.execute(org.springframework.orm.toplink.TopLinkCallback)`, `TopLinkTemplate.executeFind(org.springframework.orm.toplink.TopLinkCallback)`

The Spring Framework

Copyright © 2002-2008 The Spring Framework.