com.ibm.websphere.objectgrid.plugins
Interface TransactionCallback

All Known Subinterfaces:

TransactionCallback.BeforeCommit

All Known Implementing Classes:

JPATxCallback, WebSphereTransactionCallback

public interface TransactionCallback

Calling methods on a Session will send corresponding events to the TransactionCallback. An ObjectGrid can have zero or one TransactionCallback. BackingMaps defined on an ObjectGrid with a TransactionCallback should have corresponding Loaders.

A TransactionCallback works with Loaders and place transaction specific objects in slots on the TxID object that Loaders can obtain. Examples are database connections, prepared statement caches, etc. The TransactionCallback should reserve slots in the TxID by calling ObjectGrid.reserveSlot(String) using the name TxID.SLOT_NAME. The TransactionCallback can then put an object at that index in the TxID. A Loader can retrieve the index used by the TransactionCallback by calling an internal method on the TransactionCallback's implementation. A reference to the configured TransactionCallback can be found using the TxID.getSession().getObjectGrid().getTransactionCallback() code sequence.

A TransactionCallback implementation that also implements the ObjectGridLifecycleListener interface will be automatically added as an EventListener on the ObjectGrid when the callback is set on the object grid.

A TransactionCallback may implement the ObjectGridPlugin interface in order to receive enhanced ObjectGrid plug-in lifecycle method calls. The plug-in is also required to correctly implement each of the bean methods related to introspection of its state (for example isInitialized(), isDestroyed(), etc).

Since:

WAS XD 6.0, XC10

See Also:

Loader, ObjectGrid.addEventListener(EventListener), ObjectGrid.getTransactionCallback(), ObjectGrid.reserveSlot(String), ObjectGrid.setTransactionCallback(TransactionCallback), Session.getObjectGrid(), TxID.putSlot(int, Object), TxID.getSlot(int), TxID.getSession()

Nested Class Summary

static interface

TransactionCallback.BeforeCommit The BeforeCommit optional mix-in interface for the TransactionCallback plug-in interface allows plug-ins to be notified at the beginning of a Session.commit().

Method Summary

void	begin(TxID id) Invoked when starting a Session transaction.
void	commit(TxID id) Invoked when committing a Session transaction.
void	initialize(ObjectGrid objectGrid) Invoked when an ObjectGrid is initialized.
boolean	isExternalTransactionActive(Session session) Called when an application attempts to use a Session with no transaction active.
void	rollback(TxID id) Invoked when rolling back a Session transaction.

Method Detail

initialize

void initialize(ObjectGrid objectGrid)
                throws TransactionCallbackException

Invoked when an ObjectGrid is initialized.

This method is called so this object can do any implementation specific intialization.

Parameters:

objectGrid - A reference to the ObjectGrid.

Throws:

TransactionCallbackException - if an error occurs during processing

See Also:

ObjectGrid.reserveSlot(String)

begin

void begin(TxID id)
           throws TransactionCallbackException

Invoked when starting a Session transaction.

A TransactionCallback can communicate the begin processing (along with the TxID) to the appropriate BackingMap and/or Loader. The Loader may use this signal to start a corresponding transaction on the underlying connection to a database.

Parameters:

id - transaction identifer (TxID)

Throws:

TransactionCallbackException - if an error occurs during processing

See Also:

Session.begin(), Session.beginNoWriteThrough(), TxID

commit

void commit(TxID id)
            throws TransactionCallbackException

Invoked when committing a Session transaction.

This method should be used to commit any underlying transaction and return any underlying connection back to the pool. The TxID is provided to determine which transaction is being committed

Parameters:

id - transaction identifier (TxID)

Throws:

TransactionCallbackException - if an error occurs during processing

See Also:

begin(TxID), Session.commit(), TxID

rollback

void rollback(TxID id)
              throws TransactionCallbackException

Invoked when rolling back a Session transaction.

This method should be used to roll back any underlying transaction and return any underlying connection back to the pool. The TxID is provided to determine which transaction is being committed

Parameters:

id - transaction identifier (TxID)

Throws:

TransactionCallbackException - if an error occurs during processing

See Also:

begin(TxID), Session.rollback(), TxID

isExternalTransactionActive

boolean isExternalTransactionActive(Session session)

Called when an application attempts to use a Session with no transaction active.

The callback could return true in which case an auto Session.begin() is executed. If false is returned, an application exception is thrown indicating no transaction is active. This event is usually used when integrating with a J2EE environment such as WebSphere Application Server.

Parameters:

session - the session which the application is using

Returns:

true if an auto begin should be done, false if this is not the case

See Also:

Session