Collapse All Expand All

.NET Framework Class Library
Members See Also

[TIBCO.EMS .NET client library 5.1 documentation]

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

Namespace: TIBCO.EMS
Assembly: TIBCO.EMS (in TIBCO.EMS.dll)

# Syntax

    public class EMSDTCSession : XASession

    Public Class EMSDTCSession _
    	Inherits XASession

    public ref class EMSDTCSession : public XASession

# Remarks

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 it's first message as part of a distributed transaction (started via the TransactionSope of via the CommittableTransaction) or a consumer consumes it's 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 cosumer is done with it's 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:

| Copy Code
--- | ---
                     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();
                     }

# Inheritance Hierarchy

System..::.Object
TIBCO.EMS..::.Session
TIBCO.EMS..::.XASession
TIBCO.EMS..::.EMSDTCSession

# See Also

EMSDTCSession Members
TIBCO.EMS Namespace