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)