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.