Help Center/ Distributed Message Service for RocketMQ/ Developer Guide/ Python (TCP)/ Sending and Receiving Transactional Messages
Updated on 2024-12-17 GMT+08:00

Sending and Receiving Transactional Messages

DMS for RocketMQ ensures transaction consistency between the service logic and message transmission, and implements transaction support in two phases. Figure 1 illustrates the interaction of transactional messages.

Figure 1 Transactional message interaction

The producer sends a half message and then executes the local transaction. If the execution is successful, the transaction is committed. If the execution fails, the transaction is rolled back. If the server does not receive any commit or rollback request after a period of time, it initiates a check. After receiving the check request, the producer resends a transaction commit or rollback request. The message is delivered to the consumer only after being committed. The consumer is unaware of the rollback.

Before sending and receiving transactional messages, collect RocketMQ connection information by referring to Collecting Connection Information.

Notes and Constraints

To receive and send transactional messages, ensure the topic message type is Transactional before connecting a client to a RocketMQ instance of v5.x.

Sending Transactional Messages

The following code is an example. Replace the information in bold with the actual values.

import time

from rocketmq.client import Message, TransactionMQProducer, TransactionStatus

topic = 'TopicTest'
gid = 'test'
name_srv = '192.168.0.1:8100'


def create_message():
    msg = Message(topic)
    msg.set_keys('XXX')
    msg.set_tags('XXX')
    msg.set_property('property', 'test')
    msg.set_body('message body')
    return msg


def check_callback(msg):
    print('check: ' + msg.body.decode('utf-8'))
    return TransactionStatus.COMMIT


def local_execute(msg, user_args):
    print('local:   ' + msg.body.decode('utf-8'))
    return TransactionStatus.UNKNOWN


def send_transaction_message(count):
    producer = TransactionMQProducer(gid, check_callback)
    producer.set_name_server_address(name_srv)
    producer.start()
    for n in range(count):
        msg = create_message()
        ret = producer.send_message_in_transaction(msg, local_execute, None)
        print('send message status: ' + str(ret.status) + ' msgId: ' + ret.msg_id)
    print('send transaction message done')

    while True:
        time.sleep(3600)


if __name__ == '__main__':
    send_transaction_message(10)

The parameters in the example code are described as follows. For details about how to obtain the parameter values, see Collecting Connection Information.

  • topic: topic name.
  • gid: producer group name. Enter a name as required.
  • name_srv: instance address and port.

The producer needs to implement two callback functions. The local_execute callback function is called after the half message is sent (see step 3 in the diagram). The check_callback callback function is called after the check request is received (see step 6 in the diagram). The two callback functions can return three transaction states:

  • TransactionStatus.COMMIT: Transaction committed. The consumer can retrieve the message.
  • TransactionStatus.ROLLBACK: Transaction rolled back. The message will be discarded and cannot be retrieved.
  • TransactionStatus.UNKNOWN: The status cannot be determined and the server is expected to check the message status from the producer again.

Subscribing to Transactional Messages

The code for subscribing to transactional messages is the same as that for subscribing to normal messages.