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 execute method, assumably often as anonymous classes within a method implementation. The typical implementation will call TopLink Session CRUD to perform some operations on persistent objects.

The Session that is 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, then 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 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). getActiveUnitOfWork will return null outside a 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 or release 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 RuntimeException is treated as 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 - in case of TopLink errors

See Also:

Session.getActiveUnitOfWork(), Session.acquireUnitOfWork(), TopLinkTemplate.execute(org.springframework.orm.toplink.TopLinkCallback), TopLinkTransactionManager