Skip to content

mq-events-guide.md

Latest commit

 

History

History
109 lines (74 loc) · 5.22 KB

mq-events-guide.md

File metadata and controls

109 lines (74 loc) · 5.22 KB
Raw

RocketMQ Message Integration

Language: English | 简体中文

Station OpenAPI publishes four message types on the fixed httpRemote topic. Spring Boot applications should use RocketMQ Starter and delegate message parsing and dispatch to the SDK's RemoteMessageRouter.

1. Prerequisites

Contact your assigned technical support representative to confirm:

  • The RocketMQ NameServer address for the target environment;
  • The httpRemote topic is available;
  • The application is permitted to consume the messages;
  • The application host can reach both the NameServer and the Broker addresses and ports returned by it;
  • If the platform requires consumer groups to be created in advance, the group name that may be used.

A NameServer normally uses host:port format. It is not the Station HTTP endpoint.

2. Enable Starter MQ in the Sample

MQ is disabled by default in the main Sample. Open:

samples/station-openapi-spring-boot-sample/
  station-openapi-sample-spring-boot/
    src/main/resources/application.yml

Set the actual values supplied or approved by technical support:

station:
  openapi:
    mq:
      enabled: true
      consumer-group: station-openapi-sample

rocketmq:
  name-server: mq-nameserver.example.com:9876

Run StationOpenApiSampleApplication in IDEA. HTTP authentication still follows the Sample README. Enabling MQ does not replace the endpoint and Token/signature configuration.

After the consumer starts, trigger a new platform message. End-to-end delivery is confirmed only when the corresponding Handler writes a business summary log.

3. Integrate with a Spring Boot Application

See Source and Dependency Integration for source and dependency preparation. Use these POMs as the reference Starter dependency combination:

The following commented examples show the recommended structure:

The Listener must not parse JSON itself or log the raw message body. The SDK Router converts each supported Tag into the corresponding model.

4. Supported Messages

Fixed topic: httpRemote.

Tag SDK model Purpose
uploadHttpRemoteTaskStatus TaskStatusMessage Task status and progress
uploadHttpRemoteResult TaskResultMessage Inspection point results and files
uploadHttpRemoteAlarm DogAlarmMessage Quadruped robot alarms
uploadHttpRemoteRoute RouteMessage Task inspection route

uploadHttpRemoteDevicePos is not part of the message scope supported by the SDK. Query real-time position through client.dog().getPosition(...).

5. Consumer Groups

  • Instances of the same application in the same environment use the same group, allowing RocketMQ to distribute messages among them.
  • Different applications that each need the complete message stream must use different groups.
  • The Starter Sample and native MQ Sample must use different groups when run at the same time.
  • Do not generate a random group on every startup.
  • If a group must be created in advance, ask technical support to confirm it before starting the application.

6. Message Handling

RocketMQ messages may be delivered more than once. Business handlers must be thread-safe and safely process duplicates:

  • Locate a task result by taskExecuteCode + devicePointCode;
  • Merge file lists by fileType + filePath;
  • Return normally after successful processing;
  • Throw an exception when processing fails so RocketMQ can redeliver the message;
  • Log only the Tag and necessary business identifiers, never the raw message body.

7. Native Subscriber Sample

Use station-openapi-sample-native-mq only when RocketMQ Starter is not used.

Set these values in that module's application.yml:

station:
  openapi:
    native-mq:
      enabled: true
      name-server: mq-nameserver.example.com:9876
      consumer-group: station-openapi-native-sample

Then run NativeMqSampleApplication in IDEA.

The native module demonstrates MQ consumption only. It does not create an HTTP Client and does not require Token or signature credentials. See NativeMqConfiguration.java for lifecycle management and registration of all four handlers.