TIBCO.EMS.EMSDTCSession Class Reference

The EMSDTCSession class represents a session of the client within the server. Only EMSDTCSession's are allowed to participate in MSDTC distributed transactions. More...

Inherits XASession.

Public Member Functions
new Session	GetSession ()
	Returns this session, that would allow to create producers and consumers More...
override void	Commit ()
	Not valid for EMSDTCSession, throws InvalidOperationException More...
override void	Rollback ()
	Not valid for EMSDTCSession, throws InvalidOperationException More...

Detailed Description

The EMSDTCSession class represents a session of the client within the server. Only EMSDTCSession's are allowed to participate in MSDTC distributed transactions.

EMSDTCSession is a single-threaded context for producing and consuming messages. Typically applications create EMSDTCSessions and then producers and consumers on the EMSDTCSession. Message Producers and consumers that are then created within this session can produce and consume as long as they are done within an ambient transaction (Created via the System.Transactions.TransactionScope or System.Transactions.CommittableTransaction).

General:

When a message producer publishes its first message as part of a distributed transaction (started via the TransactionSope of via the CommittableTransaction) or a consumer consumes its first message as part of a distributed transaction. The EMS .NET client library registers an EnlistmentNotification object with MSDTC for this session. When the producer or the consumer is done with its unit of work, it commits the distributed transaction. The act of commiting this distributed transaction will then result in Microsoft DTC calling back ino the EnlistmentNotification object to complete the transaction. On a successful commit or rollback of the distributed transaction, the session is now free to have more work done in another transaction.

Recovery:

If during the transaction commit process, the resource manager fails (i.e after a successful prepare, but before the Microsoft DTC had the chance to commit the transaction) then the client will have to close the connection and create it again in order for the prepared transactions to be completed (that happens internally via a re-enlistment processs and the MSDTC either issuing a commit or a rollback based on other participants in the distributed transaction). For more information on the re-enlistment process please see the documentation on System.Transactions.TransactionManager.Reenlist.

Exceptions:

Following will result in IllegalStateException:

• It's Illegal to NOT have an ambient transaction and produce or consume messages via message producers and message consumers created on an EMSDTCSession
• It's Illegal to call commit/rollback on an EMSDTCSession
• It's Illegal to have nested transactions that are using a session and the session is already part of another ambient transaction.
• It's Illegal to create asynchronous message consumers on EMSDTCSession's. An IllegalStateException is thrown when MessageListener is being set.

A typical application produces or consumes messages as part of a transaction scope. In the example below, If the producer's EMSDTCSession is not already enlisted for the current ambient transaction, the first publish will result in an automatic enlistment.

Example:

EMSDTCConnectionFactory fc = new EMSDTCConnectionFactory("tcp://localhost:7222");
fc.ClientID                = "test-clientId";
EMSDTConnection dtcConn    = fc.CreateEMSDTCConnection();
EMSDTCSession   dtcSess    = dtcConn.CreateEMSDTCSession();
Queue           queue      = dtcSess.CreteQueue("queue.sample");
MessageProducer prod       = dtcSess.CreateProducer(dest);

using(TransactionScope scope = new TransactionScope(TransactionScopeOption.RequiresNew))
{
    // publish couple of msgs to a queue on this %EMS server.

    TextMessage msg = dtcSess.CreateTextMessage("hello world: 1");
    prod.Publish(msg);

    TextMessage msg2 = dtcSess.CreateTextMessage("hello world: 2");
    prod.Publish(msg2);

    // do work on another Resource Manager.

    scope.Complete();
}

Member Function Documentation

override void TIBCO.EMS.EMSDTCSession.Commit ( )

inline

Not valid for EMSDTCSession, throws InvalidOperationException

new Session TIBCO.EMS.EMSDTCSession.GetSession ( )

inline

Returns this session, that would allow to create producers and consumers

override void TIBCO.EMS.EMSDTCSession.Rollback ( )

inline

Not valid for EMSDTCSession, throws InvalidOperationException