The ApsaraMQ for MQTT cloud SDK for Java provides three interfaces for server-side integration: sendMessage for publishing messages, subscribeTopic for consuming messages, and subscribeStatus for tracking client connection events.
Prerequisites
Before you begin, make sure that you have:
An ApsaraMQ for MQTT instance created in the ApsaraMQ for MQTT console
An AccessKey pair for authentication. For details, see Obtain an AccessKey pair
The cloud SDK for Java downloaded and added to your project. For download links, see Release notes
Connection parameters
Configure connection parameters in ChannelConfig.class, located at server-sdk-{SDK Version}\com\alibaba\mqtt\server\config. Replace {SDK Version} with the version of the cloud SDK for Java in your project.
Required parameters
| Parameter | Type | Description |
|---|---|---|
domain | String | Endpoint of your ApsaraMQ for MQTT instance. See Endpoint formats. |
port | Integer | Port used by the cloud SDK. The protocol and port must match. Set to 5672. |
instanceId | String | ID of the ApsaraMQ for MQTT instance. Find it on the Instance Details page in the ApsaraMQ for MQTT console. |
accessKey | String | AccessKey ID created in the Resource Access Management (RAM) console for authentication. See Obtain an AccessKey pair. |
secretKey | String | AccessKey secret created in the RAM console. Required only for signature authentication. See Obtain an AccessKey pair. |
Endpoint formats
Choose the endpoint format based on your network access method:
| Access method | Endpoint format |
|---|---|
| Public | <instance-id>-server-internet.mqtt.aliyuncs.com |
| VPC | <instance-id>-server-internal.mqtt.aliyuncs.com |
Replace <instance-id> with the ID of your ApsaraMQ for MQTT instance, listed in the Basic Information section of the Instance Details page in the ApsaraMQ for MQTT console.
Not all regions support cloud SDK access. For supported regions, see SDK access regions.
Network parameters
In most cases, the default values work without modification. Adjust these parameters only if network conditions require it.
| Parameter | Type | Description | Unit | Default |
|---|---|---|---|---|
networkRecoveryInterval | Integer | Time before a TCP connection is automatically recovered. | Milliseconds | 5000 |
connectionTimeout | Integer | Maximum wait time to establish a TCP connection. If the connection is not established within this period, an error is returned. | Milliseconds | 60000 |
handshakeTimeout | Integer | Maximum wait time for a TCP handshake. If the handshake does not complete within this period, an error is returned. | Milliseconds | 10000 |
requestedHeartbeat | Integer | Interval between heartbeat signals. If no heartbeat is sent within this interval, an error is returned. | Seconds | 60 |
shutdownTimeout | Integer | Grace period for a consumer to finish processing messages after the TCP connection closes. Set to 0 to allow indefinite processing. | Milliseconds | 10000 |
sendMessage
Publish a message to an MQTT topic.
Class:
com.alibaba.mqtt.server.ServerProducer
| Parameter | Type | Description |
|---|---|---|
mqttTopic | String | MQTT topic to publish to. Specify either a parent topic or a subtopic. Create parent topics in the ApsaraMQ for MQTT console first. Subtopics can be specified directly in code without console creation. For details on topic hierarchy, see Basic terms. |
payload | byte[] | Message body. |
sendCallback | SendCallback | Callback invoked after the message is sent. Handle the send result in this callback. |
If the specified topic does not exist or the client lacks permissions on it, authentication fails and the client is disconnected from the ApsaraMQ for MQTT broker.
subscribeTopic
Subscribe to messages on a parent topic.
Class:
com.alibaba.mqtt.server.ServerConsumer
| Parameter | Type | Description |
|---|---|---|
firstTopic | String | Parent topic created in the ApsaraMQ for MQTT console. For details, see Basic terms. |
messageListener | MessageListener | Callback invoked when a message arrives. Process received messages in this callback. |
If the specified topic does not exist or the client lacks permissions on it, authentication fails and the client is disconnected from the ApsaraMQ for MQTT broker.
The cloud SDK does not support subtopic subscriptions. It is designed for backend applications that collect and analyze all messages on a parent topic.
subscribeStatus
Subscribe to client status notifications for a specific group.
Class:
com.alibaba.mqtt.server.ServerConsumer
| Parameter | Type | Description |
|---|---|---|
mqttGroupId | String | Group ID created in the ApsaraMQ for MQTT console. For details, see Basic terms. |
statusListener | StatusListener | Callback invoked when a client status notification arrives. Process status events in this callback. |
Related topics
Basic terms -- Topic hierarchy, groups, and other core concepts
Release notes -- SDK versions and download links
SDK access regions -- Regions that support cloud SDK access