IT_Bus::TransactionManager Class Reference

#include <it_bus/transaction_manager.h>

Inheritance diagram for IT_Bus::TransactionManager:

IT_Bus::RefCountedBase IT_Bus::OTSTransactionManager IT_Bus::TransactionManagerFacade IT_Bus::WSATTransactionManager IT_Bus::XATransactionManager List of all members.

Detailed Description

The Interface used to conduct non-demarcation related actions on a transaction instance within Artix.

This interface is used to perform actions such as thread attachment/detachment, transaction expiry/timeout specification, transaction participant/notification enlistment etc.

As with the TransactionSystem interface, where appropiate calls made to a TransactionManager operate on the transaction associated with the calling thread.

Definition at line 31 of file transaction_manager.h.

Public Member Functions

virtual TransactionIdentifierdetach_thread ()=0
 Break the association between the calling thread and its current transaction.
virtual Boolean attach_thread (TransactionIdentifier *tx_identifier)=0
 Make an association between the calling thread and the transaction identified by the 'tx_identifier' parameter.
virtual String get_transaction_type ()=0
 Get the underlying transaction type.
virtual TransactionIdentifierget_tx_identifier ()=0
 An identifier for the transaction associated with the calling thread.
virtual void set_transaction_timeout (UInt seconds)=0 throw ((Exception))
 Set the timeout within which transactions must be completed.
virtual UInt get_transaction_timeout ()=0 throw ((Exception))
 Get the timeout within which transactions must be completed.
virtual Boolean enlist (TransactionParticipant *tx_participant, Boolean is_durable)=0
 Enlist a participant in the transaction associated with the current thread.
virtual Boolean enlist_for_notification (TransactionNotificationHandler *completion_handler)=0 throw ((Exception))
 Enlist a participant for notification events.
virtual Boolean commit_transaction (Boolean report_heuristics)=0 throw ((Exception))
 Marks the successful end of a transactional unit of work.
virtual void rollback_transaction ()=0 throw ((Exception))
 Marks the unsuccessful end of a transaction unit of work.
virtual void include_tx_identifier (TransactionIdentifierMap &tx_map)=0
 Add the transaction identifier for this specific transaction system to the supplied identifier Map.
virtual Boolean recreate_transaction (String &encoded_transaction_state)=0
 Recreate a pre-existing transaction based on its encoded state.
virtual String get_encoded_transaction_state ()=0
 Obtain an encoded form of the transaction currently associated with the current thread.


Member Function Documentation

virtual TransactionIdentifier* IT_Bus::TransactionManager::detach_thread (  )  [pure virtual]

Break the association between the calling thread and its current transaction.

This means that the transaction context will not be propagated on subsequent operation calls made by the calling thread.

Normal transaction processing such as termination may still proceed on other threads. To re-attach the calling thread to this transaction the attach_thread() operation should be used.

A transaction may be detached from one thread, and later attached to a different thread.

Returns:
TransactionIdentifier. This identifier can be used to later restore a thread affinity with this transaction via a call to IT_Bus::TransactionManager::attach_thread(). The caller is responsible for the lifecycle of the returned object instance. If no transaction is associated with the current thread, this operation returns a null value. When non-null, the returned object must be released via a call to the _remove_ref() operation or may be auto-released by assigning it to an instance of the IT_Bus::TransactionIdentifier_var data type.

virtual Boolean IT_Bus::TransactionManager::attach_thread ( TransactionIdentifier tx_identifier  )  [pure virtual]

Make an association between the calling thread and the transaction identified by the 'tx_identifier' parameter.

This operation may be used to associate multiple threads with a newly created or pre-existing transaction.

Parameters:
tx_identifier A transaction identifier that has been obtained by calling IT_Bus::TransactionManager::detach_thread() or IT_Bus::TransactionManager::get_tx_identifier() operations.
Returns:
true If the calling thread has been successfully associated with the transaction.

virtual String IT_Bus::TransactionManager::get_transaction_type (  )  [pure virtual]

Get the underlying transaction type.

Returns:
a string representing the underlying transaction type. This string may be used to determine the downcast type to be used when accessing a more transaction provider specific interface. For example, an OTSTransactionManager, an XATransactionManager or an WSAtomicTransactionManager.

virtual TransactionIdentifier* IT_Bus::TransactionManager::get_tx_identifier (  )  [pure virtual]

An identifier for the transaction associated with the calling thread.

This identifier may be used to create an affinity between another thread and this transaction instance. That is, more than one thread can be making calls in the context of the same transaction.

If there are multiple transaction systems active on this thread, then the returned Identifier will include details of those transactions as well.

Returns:
TransactionIdentifier_ptr. An identifier for the transaction associated with the calling thread. The caller is responsible for the lifecycle of the returned object instance. If no transaction is associated with the current thread, this operation returns a null value. When non-null, the returned object must be released via a call to the _remove_ref() operation or may be auto-released by assigning it to an instance of the IT_Bus::TransactionIdentifier_var data type.

virtual void IT_Bus::TransactionManager::set_transaction_timeout ( UInt  seconds  )  throw ((Exception)) [pure virtual]

Set the timeout within which transactions must be completed.

If the timeout expires, the transaction is automatically aborted. This operation should be called before a transaction is initiated.

Parameters:
UInt The lifetime in seconds of a transaction.

virtual UInt IT_Bus::TransactionManager::get_transaction_timeout (  )  throw ((Exception)) [pure virtual]

Get the timeout within which transactions must be completed.

Returns:
UInt The lifetime in seconds of this transaction.

virtual Boolean IT_Bus::TransactionManager::enlist ( TransactionParticipant tx_participant,
Boolean  is_durable 
) [pure virtual]

Enlist a participant in the transaction associated with the current thread.

If there is no transactions associated with the current thread, then this participant will be enlisted as soon as a transaction is associated with this thread.

Parameters:
tx_participant The participant to enlist.
is_durable Indicates that the participant is durable. In a two phase commit protocol, a durable participant will be involved in both the prepare and commit phases. A value of 'false' for this parameter indicates that this participant is only interested in being involved in the prepare phase of a two phase commit protocol.
Returns:
Boolean true is the participant was success fully enlisted.

virtual Boolean IT_Bus::TransactionManager::enlist_for_notification ( TransactionNotificationHandler completion_handler  )  throw ((Exception)) [pure virtual]

Enlist a participant for notification events.

Whenever a transactional event occurs, registered handlers will receive the appropriate notification.

Parameters:
tx_participant The participant to enlist.

virtual Boolean IT_Bus::TransactionManager::commit_transaction ( Boolean  report_heuristics  )  throw ((Exception)) [pure virtual]

Marks the successful end of a transactional unit of work.

This operates on the transaction associated with the calling thread. Any enlisted transaction participants will be requested to commit. Any enlisted notification participants will be informed of the outcome of the commit action.

Parameters:
report_heuristics If supported by the underlying transaction provider, specifies whether heuristic decisions should be reported during the commit protocol.
Returns:
'true' if the transaction was committed successfully, 'false' if the transaction could not be committed successfully.

virtual void IT_Bus::TransactionManager::rollback_transaction (  )  throw ((Exception)) [pure virtual]

Marks the unsuccessful end of a transaction unit of work.

This operates on the transaction associated with the calling thread. This operation causes the entire transaction to be aborted, Any enlisted transaction participants will be instructed to rollback their state to a pre-transaction position. Any enlisted notification participants will be informed that the transaction has been aborted.

virtual void IT_Bus::TransactionManager::include_tx_identifier ( TransactionIdentifierMap tx_map  )  [pure virtual]

Add the transaction identifier for this specific transaction system to the supplied identifier Map.

If an identifier for this transaction system is already present in this map, then do nothing.

Parameters:
TransactionIdentifierMap A map of transaction Identifiers keyed by the appropiate transaction system identifier string.

virtual Boolean IT_Bus::TransactionManager::recreate_transaction ( String encoded_transaction_state  )  [pure virtual]

Recreate a pre-existing transaction based on its encoded state.

If there isd already a transaction active on the current thread then this operation does nothing and returns 'false'.

If there is no transaction active on the current thread, then the thread is associated with the newly recreated transaction whoose state is encapsulated in the String input parameter.

Parameters:
String The encoded transaction state
Returns:
Boolean 'true' if the transaction was successfully recreated and associated with the current thread. 'false' otherwise.

virtual String IT_Bus::TransactionManager::get_encoded_transaction_state (  )  [pure virtual]

Obtain an encoded form of the transaction currently associated with the current thread.

If there is no transaction associated with the current thread then an empty String is returned.

Returns:
String If the current thread is associated with a transaction, an encoded recreatable state is returned. Otherwise an empty string is returned. transaction.


Generated on Tue Mar 20 15:28:08 2007 for Artix by  doxygen 1.5.1-p1