Using Local Transactions in the PubSub+ JCSMP API

This section describes how to use transacted sessions in the PubSub+ JCSMP API to publish and/or receive a series of Guaranteed messages in a single atomic unit known as a local transaction. Local transactions only rely on a single resource (the PubSub+ event broker) to provide messaging clients with service.

A transacted session enables a client application to group multiple Guaranteed message send and/or receive operations together as a single, atomic unit known as a transaction. Only Guaranteed messages (that is, messages with a Persistent or Non‑Persistent delivery mode) can be published or received through transactions; Direct messages cannot be used in transactions.

To publish and/or consume messages in a transaction, a client application must create a transacted session within a session. Then in that transacted session the client application can establish a producer flow (that is, a publisher flow) to publish messages in a transaction, and/or establish a consumer flow (that is, a subscriber flow) to receive messages in a transaction. Although an administrator can modify this value, by default, a client can publish and/or consume up to a combined maximum of 256 Guaranteed messages in a single transaction. For more information, see Configuring the Max Number of Messages Per Transaction.

Messages that are published and received in a transaction are staged on the event broker. To complete all of the message send and receive operations in a transaction, the transaction must be committed. Alternatively, a transaction can also be rolled back so that all of its publish and receive operations are canceled. Once a transaction is completed, another transaction automatically begins.

The following figure shows how a client can use both a producer and a consumer in a single transacted session. In this case, when the client commits the transaction, spooled message A is received by the consumer from the endpoint and messages B and C are published to that same destination endpoint.

Transactions and Commits

For an example of how to use local transactions, refer to the Transactions sample in the Solace Developer Hub.

Threading Considerations

Transacted sessions are only supported for single thread use (with the exception that any application thread can call close() or destroy() to close the transacted session). All producer and consumer flows which are part of a transacted session must be accessed serially by the same thread.

Synchronous Consumers

When using synchronous message consumers, send and receive operations are done by a single application thread, and this thread must either commit or rollback the transaction. The application thread serializes access to the producers and consumers of the transacted session.

Asynchronous Consumers

When using asynchronous message consumers, an API-owned thread delivers messages to registered message listeners. This thread is used to send messages, and this same thread must either commit or rollback the transaction. The API thread serializes access to the producers and consumers of the transacted session.