ApsaraMQ for RocketMQ:Scheduled messages and delayed messages

Use cases

• Order timeout handling: When a user creates an order in an e-commerce checkout flow, send a delayed message with a 30-minute delay. After 30 minutes, the consumer checks whether payment is complete. If not, it cancels the order. If payment succeeded, it ignores the message.

• Timed notifications: Send a scheduled message set to a specific time -- for example, 9:00 AM the next day -- to trigger a push notification or reminder.

Set the delivery time

Both message types use the same parameter: msg.setStartDeliverTime, which accepts a millisecond-precision Unix timestamp.

• Scheduled message: pass the absolute timestamp of the target delivery time.

• Delayed message: pass System.currentTimeMillis() + delayMillis, where delayMillis is the delay duration in milliseconds.

// Calculate the delivery timestamp: current time + 10 minutes
long deliverTime = System.currentTimeMillis() + 10L * 60 * 1000;
msg.setStartDeliverTime(deliverTime);

// Schedule delivery for 2024-06-15 14:30:00 (UTC+8)
// Millisecond Unix timestamp: 1718433000000
long deliverTime = 1718433000000L;
msg.setStartDeliverTime(deliverTime);

Rules and limits

Delivery precision

Scheduled and delayed messages are not guaranteed to arrive at the exact specified time due to the following factors:

• Baseline latency: expect 1 to 2 seconds of delivery latency.

• Message backlog: if accumulated messages exist in the queue, scheduled and delayed messages are queued behind them and may arrive later than the target time.

• Clock skew: the StartDeliverTime value is evaluated against the broker clock. If the client clock differs from the broker clock, the actual delivery time may not match the timestamp set by the producer.

Sample code

For complete producer and consumer examples, see the following guides organized by protocol and language.