ApsaraMQ for RocketMQ provides multiple SDK versions using different protocols. Choose the SDK that matches your instance type and workload.
For new projects, use the RocketMQ 5.x gRPC SDK. It supports the most languages, receives all new features, and works with 5.x series instances. If you need features exclusive to older SDKs, such as broadcast consumption or stream consumption, use the corresponding SDK instead.
SDK versions
The following table compares the protocol, instance compatibility, and recommendation for each SDK version.
| Protocol | gRPC protocol v2 | Remoting protocol | Remoting protocol | Remoting protocol | gRPC protocol v1 | HTTP protocol |
| Accessible instances | 5.x series instances | 5.x series instances, 4.x series instances | 5.x series instances, 4.x series instances | 5.x series instances, 4.x series instances | 4.x series instances | 4.x series instances |
| Recommendation | Recommended. Supports multiple languages. All new features and optimizations target this SDK. If some features of the 5.x gRPC SDK do not meet your requirements, you can use the 5.x Remoting SDK. | Existing applications can continue using these SDK versions. 5.x series instances are compatible. | Existing applications can continue using these SDK versions. 5.x series instances are compatible. | Existing applications can continue using these SDK versions. 5.x series instances are compatible. | Do not use clients of these versions. No new features or optimizations. Only 4.x series instances are accessible. | Do not use clients of these versions. No new features or optimizations. Only 4.x series instances are accessible. |
Feature comparison across SDK versions
In the following table, a check mark indicates support and an X indicates no support.
Feature |
5.x gRPC |
5.x Remoting |
4.x/3.x |
ONS TCP 1.x |
ONS TCP 2.x |
ONS HTTP |
| Send normal, ordered, transactional, and scheduled messages | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Lightweight topic-based model | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Concurrent consumption | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Ordered consumption of messages | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Concurrency optimization for ordered consumption of messages | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Broadcasting consumption | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Stream consumption (connecting to Flink, etc.) | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
| Message trace | ✅ | ✅ | Supported in versions 4.5.2 and later | ✅ | ✅ | ❌ |
| Producer and consumer client metrics data | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Graceful shutdown | ✅ | Supported only for 5.x series instances | ❌ | ❌ | ❌ | ❌ |
| Batch sending | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
| Priority message | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Priority message lets you assign priority levels to messages so that higher-priority messages are consumed before lower-priority ones. This feature is exclusive to the RocketMQ 5.x gRPC SDK.
Limits
-
Different consumers in the same consumer group must use clients that support the same protocol.
-
When you perform a grayscale upgrade from a Remoting protocol SDK to a gRPC protocol SDK for the same consumer group:
-
Consumer groups that deliver messages in order do not support this upgrade.
-
Consumer groups that deliver messages concurrently support smooth upgrades. A small number of messages may be duplicated during the upgrade.
-
-
To send messages to the same ordered topic, all producer clients must use the same protocol. The protocol must be either the Remoting protocol or the gRPC protocol.
-
For a consumer group that delivers messages in order, the consumer offset may roll back if the following sequence occurs:
-
The consumer group first uses a Remoting protocol SDK.
-
The SDK is upgraded to a gRPC protocol SDK.
-
The SDK is rolled back to the Remoting protocol SDK.
-
-
The RocketMQ ONS TCP 2.x SDK is available only in some regions. For more information, see Limits.
RocketMQ 5.x gRPC SDK
The 5.x gRPC SDK supports Java, C#, Go, Python, and C++. All languages use gRPC protocol v2.
Language |
References |
| Java SDK | Version Guide | Prepare the environment | Sample code |
| C# SDK | Version Guide | Prepare the environment | Sample code |
| Go SDK | Version Guide | Prepare the environment | Sample code |
| Python SDK | Version Guide | Prepare the environment | Sample code |
| C++ SDK | Version Guide | Prepare the environment | Sample code |
RocketMQ 5.x Remoting SDK
The 5.x Remoting SDK is available for Java only and uses the Remoting protocol.
Language |
References |
| Java SDK | Version Guide | Prepare the environment | Sample code |
RocketMQ 4.x/3.x SDK
The 4.x/3.x SDK is available for Java and C++ and uses the Remoting protocol.
Language |
References |
| Java SDK | Version Guide | Prepare the environment | Sample code |
| C++ SDK | Version Guide | Prepare the environment | Sample code |
RocketMQ ONS TCP 1.x SDK
The ONS TCP 1.x SDK is available for Java, C++, and .NET and uses the Remoting protocol.
Language |
References |
| Java SDK | Version Guide | Prepare the environment | Sample code |
| C++ SDK | Version Guide | Prepare the environment | Sample code |
| .NET SDK | Version Guide | Prepare the environment | Sample code |