com.sap.transaction

Interface ITxManager

public interface ITxManager

This interface specifies the functionality that TxManager implementations shouls support in order to wrap the JTA transaction manager as specified by the new SAP transaction specification.

Method Summary

void	commitLevel(TransactionTicket txticket) Commmits the transaction level associated with the given transaction ticket.
Synchronization	getRegisteredSynchronization(String SID) Gets the Synchronization object previously registered with the current transaction under the given synchronization id (SID).
int	getStatus() Gets the status of the current transaction
boolean	isTxActive() Checks whether the transaction associated with the current thread is active.
boolean	isTxMarkedRollback() Checks whether the transaction associated with the current thread is marked for rollback.
void	leaveLevel(TransactionTicket txticket) Finishes and leaves the transaction level associated with the given transaction ticket.
void	registerSynchronization(String SID, Synchronization sync) Registers the given Synchronization object with the current transaction.
TransactionTicket	required() Requires a new JTA transaction to be started or an already open transaction to be joined.
TransactionTicket	requiresNew() Requires a new transaction to be started.
void	setRollbackOnly() Marks the current JTA transaction for rollback.

Method Detail

required

TransactionTicket required()
                           throws TxException,
                                  TxRollbackException

Requires a new JTA transaction to be started or an already open transaction to be joined. If there is already an open transaction associated with the current thread, this transaction is joined. Otherwise, if no transaction exists, a new transaction is started and associated with the current thread.

The method returns a transaction ticket as a unique identifier for this transaction level. Later on, this ticket has to be passed as an argument to the methods commitLevel() and leaveLevel(), in order to associate them with the transaction level opened by this call.

Returns:

a transaction ticket.

Throws:

TxException - thrown if the transaction manager encounters an unexpected error situation.

TxRollbackException - thrown if there is already a transaction associated with the current thread and this transaction is marked for rollback only, for example, as a result of a setRollbackOnly() call.

requiresNew

TransactionTicket requiresNew()
                              throws TxException

Requires a new transaction to be started. If there is already an open transaction associated with the current thread, this transaction will be suspended and the new transaction will be associated with the thread. The suspended transaction will be resumed, when this transaction is completed (either committed or rolled back).

The method returns a transaction ticket as a unique identifier for this transaction level. Later on, this ticket has to be passed as an argument to the methods commitLevel() and leaveLevel(), in order to associate them with the transaction level opened by this call.

Returns:

a transaction ticket.

Throws:

TxException - thrown if the transaction manager encounters an unexpected error situation.

setRollbackOnly

void setRollbackOnly()
                     throws TxException,
                            TxDemarcationException

Marks the current JTA transaction for rollback. The rollback is performed when the commitLevel() method is called on the transaction level that has started the JTA transaction.

Throws:

TxDemarcationException - thrown if no transaction is associated with the current thread.

TxException - thrown if the transaction manager encounters an unexpected error situation.

getStatus

int getStatus()
              throws TxException

Gets the status of the current transaction

Throws:

TxException - thrown if the transaction manager encounters an unexpected error situation.

commitLevel

void commitLevel(TransactionTicket txticket)
                 throws TxException,
                        TxDemarcationException,
                        TxRollbackException

Commmits the transaction level associated with the given transaction ticket.

If no JTA transaction has been started on the this transaction level, then this method has no effect.

A TxRollbackException is thrown if the transaction was rolled back rather than committed.

Parameters:

ticket - a transaction ticket.

Throws:

TxRollbackException - thrown to indicate that the transaction has been rolled back rather than committed.

TxDemarcationException - thrown if the belance of the transaction demarcation calls has been violated.

TxException - thrown if the transaction manager encounters an unexpected error situation.

leaveLevel

void leaveLevel(TransactionTicket txticket)
                throws TxException,
                       TxDemarcationException,
                       TxRollbackException

Finishes and leaves the transaction level associated with the given transaction ticket.

If the commitLevel() method has already been called on the transaction level identified by this ticket, this method has no further effect than finishing the current transaction level. Otherwise, if the commitLevel() method has not yet been called on this transaction level, the following two cases must be distinguished:

• If a JTA transaction was started on this transaction level, then it will be rolled back. This also means that the afterCompletion() methods of the registered Synchronization objects are called immediately after the rollback operation was executed.
• Otherwise, if no JTA transaction was started on this transaction level, then the joined JTA transaction will be marked for rollback only.

In both cases, a TxRollbackException is thrown in order to indicate that the current JTA transaction has been rolled back or has been marked for rollback only.

Finally, if a JTA transaction has been suspended on this transaction level because a new one was started, then this suspended transaction will be resumed before this method is left.

Parameters:

ticket - a transaction ticket.

Throws:

TxRollbackException - thrown to indicate that the transaction has been rolled back rather than committed.

TxDemarcationException - thrown if the belance of the transaction demarcation calls has been violated.

TxException - thrown if the transaction manager encounters an unexpected error situation.

registerSynchronization

void registerSynchronization(String SID,
                             Synchronization sync)
                             throws TxException,
                                    TxDemarcationException,
                                    TxRollbackException,
                                    TxDuplicateOIDRegistrationException

Registers the given Synchronization object with the current transaction. The specified synchronization id (SID) is used to define an order on the registered synchronization objects, thus reducing the probability of database deadlocks.

Parameters:

sid - a synchronization identifier

sync - a Synchronization object implementing the beforeCompletion() and afterCompletion() callbacks.

Throws:

TxSynchronizationException - thrown if the given synchronization object conflicts with a another synchronization object that has already been registered under the same synchronization id before.

TxDemarcationException - thrown if no transaction is associated with the current thread.

TxRollbackException - thrown if the transaction associated with the current thread is marked for "rollback only".

TxException - thrown if the transaction manager encounters an unexpected error situation.

TxDuplicateOIDRegistrationException

getRegisteredSynchronization

Synchronization getRegisteredSynchronization(String SID)
                                             throws TxException,
                                                    TxDemarcationException

Gets the Synchronization object previously registered with the current transaction under the given synchronization id (SID).

Parameters:

sid - a synchronization identifier

Returns:

the Synchronization object registered with the specified SID, null if no Synchronization object has been registered under the given SID.

Throws:

TxDemarcationException - thrown if no transaction is associated with the current thread.

TxException - thrown if the transaction manager encounters an unexpected error situation.

isTxActive

boolean isTxActive()
                   throws TxException

Checks whether the transaction associated with the current thread is active.

Throws:

TxException - thrown if the transaction manager encounters an unexpected error situation.

isTxMarkedRollback

boolean isTxMarkedRollback()
                           throws TxException

Checks whether the transaction associated with the current thread is marked for rollback.

Throws:

TxException - thrown if the transaction manager encounters an unexpected error situation.

Access Rights

This class can be accessed from:

SC	DC
[sap.com] ENGFACADE	[sap.com] tc/je/txmanager/api