IT_Bus::TransactionManager Class Reference

#include <it_bus/transaction_manager.h>

Inheritance diagram for IT_Bus::TransactionManager:

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 27 of file transaction_manager.h.

Public Member Functions
virtual TransactionIdentifier *	detach_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 TransactionIdentifier *	get_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 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 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 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::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 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.

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 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::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 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::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.

---