### Property Configuration Example

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/ons-client.md

Example of setting up properties for ONS client configuration.

```java
Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.AccessKey, "your-access-key");
properties.setProperty(PropertyKeyConst.SecretKey, "your-secret-key");
properties.setProperty(PropertyKeyConst.NAMESRV_ADDR, "rmq-cn-abc.xx:8080");
properties.setProperty(PropertyKeyConst.GROUP_ID, "GID-my-group");
```

--------------------------------

### start Method

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-producer.md

Method to start the producer.

```java
producer.start();
```

--------------------------------

### application.yml Configuration Example

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/springboot-integration.md

Example configuration for AliwareMQ properties in application.yml.

```yaml
rocketmq:
  accessKey: your-access-key
  secretKey: your-secret-key
  nameSrvAddr: http://MQ_INST_xxx:8080
  topic: my-topic
  groupId: GID-my-group
  tag: "*"
  orderTopic: my-order-topic
  orderGroupId: GID-my-order-group
  orderTag: "*"

spring:
  application:
    name: mq-demo-app
```

--------------------------------

### Monitoring and Logging Examples

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

Provides examples of logging messages at different severity levels (info, warn, error) for monitoring producer operations.

```java
logger.info("Message sent, topic={}, msgId={}", topic, sendResult.getMessageId());
logger.warn("Message send failed, topic={}, retry_count={}", topic, retryCount);
logger.error("Fatal error occurred while sending message", exception);
```

--------------------------------

### start 方法示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-consumer.md

启动消费者的示例。

```java
consumer.start();
```

--------------------------------

### Producer Usage Example

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-producer.md

A complete example demonstrating the creation, configuration, sending, and shutdown of a DefaultMQProducer.

```java
// Create producer
DefaultMQProducer producer = new DefaultMQProducer("GID-xxx", getAclRPCHook(), true, null);
producer.setAccessChannel(AccessChannel.CLOUD);
producer.setNamesrvAddr("http://MQ_INST_1234:8080");
producer.start();

try {
    Message msg = new Message("topic", "tag", "Hello world".getBytes());
    SendResult sendResult = producer.send(msg);
    System.out.println("Message sent successfully, MsgId: " + sendResult.getMsgId());
} catch (MQClientException e) {
    System.out.println("Message sending failed");
    e.printStackTrace();
} finally {
    producer.shutdown();
}
```

--------------------------------

### RocketMQ 直连模块目录结构

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

This shows the directory structure for the RocketMQ direct connection module, including configuration, producer, and consumer examples.

```text
rocketmq-demo/
├── src/main/java/com/aliyun/openservices/demo/
│   ├── MqConfig.java                    # 配置常量
│   ├── producer/
│   │   ├── RocketMQProducer.java       # 普通生产者示例
│   │   ├── RocketMQOrderProducer.java  # 顺序生产者示例
│   │   ├── RocketMQTransactionProducer.java  # 事务生产者示例
│   │   └── LocalTransactionCheckerImpl.java  # 事务检查器
│   └── consumer/
│       ├── RocketMQConsumer.java       # 并发消费者示例
│       └── RocketMQOrderConsumer.java  # 顺序消费者示例
└── pom.xml                              # Maven 依赖配置
```

--------------------------------

### Spring 集成模块目录结构

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

This displays the directory structure for the Spring integration module, covering various examples like normal, order, batch, and transaction producers/consumers.

```text
spring-demo/
├── src/main/
│   ├── java/com/aliyun/openservices/spring/example/
│   │   ├── normal/
│   │   │   ├── ProducerClient.java      # Spring 生产者客户端
│   │   │   ├── ConsumerClient.java      # Spring 消费者客户端
│   │   │   ├── DemoMessageListener.java # 消息监听器
│   │   │   ├── AsyncProducerClient.java # 异步生产者
│   │   │   └── SqlProducerClient.java   # SQL 消息生产者
│   │   ├── order/
│   │   │   ├── OrderProducerClient.java
│   │   │   ├── OrderConsumerClient.java
│   │   │   └── OrderDemoMessageListener.java
│   │   ├── batch/
│   │   │   ├── BatchConsumerClient.java
│   │   │   └── BatchDemoMessageListener.java
│   │   └── transaction/
│   │       ├── TransactionProducerClient.java
│   │       └── DemoLocalTransactionChecker.java
│   └── resources/
│       ├── common.xml                   # 通用配置
│       ├── producer.xml                 # 生产者 Bean
│       ├── consumer.xml                 # 消费者 Bean
│       ├── order_producer.xml           # 顺序生产者 Bean
│       ├── order_consumer.xml           # 顺序消费者 Bean
│       ├── transaction_producer.xml     # 事务生产者 Bean
│       ├── batch_consumer.xml           # 批量消费者 Bean
│       └── sql_consumer.xml             # SQL 消费者 Bean
└── pom.xml
```

--------------------------------

### TCP 直连模块目录结构

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

This outlines the directory structure for the TCP direct connection module, detailing configuration, producer, and consumer examples.

```text
tcp-demo/
├── src/main/java/com/aliyun/openservices/tcp/example/
│   ├── MqConfig.java                    # 配置常量
│   ├── producer/
│   │   ├── SimpleMQProducer.java       # 普通生产者示例
│   │   ├── SimpleOrderProducer.java    # 顺序生产者示例
│   │   ├── SimpleTransactionProducer.java  # 事务生产者示例
│   │   └── LocalTransactionCheckerImpl.java # 事务检查器
│   └── consumer/
│       ├── SimpleMQConsumer.java       # 消费者示例
│       ├── SimpleOrderConsumer.java    # 顺序消费者示例
│       ├── MessageListenerImpl.java     # 消息监听器
│       └── TimedBatchMQConsumer.java   # 批量消费示例
└── pom.xml
```

--------------------------------

### MessageListener Implementation

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/spring-integration.md

Example implementation of a MessageListener interface in Java for Spring.

```java
package com.aliyun.openservices.spring.example.normal;

import com.aliyun.openservices.ons.api.Action;
import com.aliyun.openservices.ons.api.ConsumeContext;
import com.aliyun.openservices.ons.api.Message;
import com.aliyun.openservices.ons.api.MessageListener;

public class DemoMessageListener implements MessageListener {

    @Override
    public Action consume(Message message, ConsumeContext context) {
        System.out.println("Receive: " + message);
        try {
            // 处理消息
            return Action.ReconsumeLater;
        } catch (Exception e) {
            // 消费失败
            return Action.ReconsumeLater;
        }
    }
}
```

--------------------------------

### setNamesrvAddr Method Example

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-producer.md

Example of setting the Name Server address for the producer.

```java
producer.setNamesrvAddr("http://MQ_INST_1234:8080");
```

--------------------------------

### setAccessChannel Method Example

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-producer.md

Example of setting the cloud access channel for the producer.

```java
producer.setAccessChannel(AccessChannel.CLOUD);
```

--------------------------------

### send Method (Synchronous)

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-producer.md

Example of synchronously sending a message.

```java
Message msg = new Message("topic", "tag", "Hello".getBytes());
SendResult result = producer.send(msg);
```

--------------------------------

### RocketMQ 直连 - 生产者发送消息示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/README.md

Java code example for setting up a RocketMQ producer and sending a message using direct connection.

```java
// 设置配置
DefaultMQProducer producer = new DefaultMQProducer(
    "GID-xxx", new AclClientRPCHook(
        new SessionCredentials("access-key", "secret-key")));
producer.setNamesrvAddr("http://MQ_INST_xxx:8080");
producer.start();

// 发送消息
Message msg = new Message("topic", "tag", "Hello".getBytes());
SendResult result = producer.send(msg);
System.out.println("MsgId: " + result.getMessageId());

producer.shutdown();
```

--------------------------------

### send Method (with MessageQueueSelector)

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-producer.md

Example of synchronously sending a message to a specific queue using a MessageQueueSelector.

```java
SendResult result = producer.send(msg, new MessageQueueSelector() {
    @Override
    public MessageQueue select(List<MessageQueue> mqs, Message msg, Object arg) {
        Integer id = (Integer) arg;
        int index = id % mqs.size();
        return mqs.get(index);
    }
}, orderId);
```

--------------------------------

### ONS 客户端（TCP 接入） - 生产者发送消息示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/README.md

Java code example for creating an ONS producer and sending a message using TCP access.

```java
// 创建生产者
Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.AccessKey, "access-key");
properties.setProperty(PropertyKeyConst.SecretKey, "secret-key");
properties.setProperty(PropertyKeyConst.NAMESRV_ADDR, "http://xxx:8080");

Producer producer = ONSFactory.createProducer(properties);
producer.start();

// 发送消息
Message msg = new Message("topic", "tag", "data".getBytes());
SendResult result = producer.send(msg);

producer.shutdown();
```

--------------------------------

### Security Configuration - Using AclClientRPCHook

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

Implementing ACL authentication for RocketMQ producer using AclClientRPCHook.

```java
private static RPCHook getAclRPCHook() {
    return new AclClientRPCHook(
        new SessionCredentials(MqConfig.ACCESS_KEY, MqConfig.SECRET_KEY));
}

DefaultMQProducer producer = new DefaultMQProducer(
    MqConfig.GROUP_ID, getAclRPCHook());
```

--------------------------------

### MqConfig 常量类

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

对于直连 RocketMQ 客户端的配置，使用 MqConfig 配置类中的常量。

```java
public class MqConfig {
    public static final String TOPIC = "topic";
    public static final String GROUP_ID = "GID-xxx";
    public static final String ORDER_TOPIC = "XXX";
    public static final String ORDER_GROUP_ID = "XXX";
    public static final String ACCESS_KEY = "xxxxx";
    public static final String SECRET_KEY = "xxxxxxxxxxxxx";
    public static final String TAG = "mq_test_tag";
    public static final String NAMESRV_ADDR = "http://xxxxx:80";
}
```

--------------------------------

### 增加 JVM 内存示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

通过启动脚本增加 JVM 堆内存以解决内存不足问题。

```bash
java -Xmx2g -Xms2g -jar application.jar
```

--------------------------------

### ConsumeFromWhere Enum Definition

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/types.md

Definition of the ConsumeFromWhere enum, indicating where the consumer starts consuming messages.

```java
public enum ConsumeFromWhere {
    CONSUME_FROM_LAST_OFFSET,      // 从最后一条消息之后开始消费
    CONSUME_FROM_FIRST_OFFSET,     // 从第一条消息开始消费
    CONSUME_FROM_TIMESTAMP         // 从指定时间戳之后开始消费
}
```

--------------------------------

### MQClientException 异常类

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

Apache RocketMQ 客户端异常类定义。

```java
org.apache.rocketmq.client.exception.MQClientException extends Exception
```

--------------------------------

### consumeMessage Method

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-consumer.md

Example implementation of the consumeMessage method for orderly message consumption.

```java
public ConsumeOrderlyStatus consumeMessage(List<MessageExt> msgs, 
    ConsumeOrderlyContext context) {
    context.setAutoCommit(true);
    // 处理消息
    return ConsumeOrderlyStatus.SUCCESS;
}
```

--------------------------------

### Spring Boot 项目结构

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了 Spring Boot 集成 ONS/RocketMQ 的项目文件结构。

```tree
springboot-demo/
├── src/main/
│   ├── java/com/aliyun/openservices/springboot/example/
│   │   ├── Application.java             # Spring Boot 应用入口
│   │   ├── config/
│   │   │   └── MqConfig.java           # @ConfigurationProperties 配置
│   │   ├── normal/
│   │   │   ├── ProducerClient.java
│   │   │   ├── ConsumerClient.java
│   │   │   ├── DemoMessageListener.java
│   │   │   ├── AsyncProducerClient.java
│   │   │   └── SqlProducerClient.java
│   │   ├── order/
│   │   │   ├── OrderProducerClient.java
│   │   │   ├── OrderConsumerClient.java
│   │   │   └── OrderDemoMessageListener.java
│   │   ├── batch/
│   │   │   ├── BatchConsumerClient.java
│   │   │   └── BatchDemoMessageListener.java
│   │   └── transaction/
│   │       ├── TransactionProducerClient.java
│   │       └── DemoLocalTransactionChecker.java
│   └── resources/
│       ├── application.properties        # 主配置文件
│       └── application-dev.properties   # 开发环境配置
├── src/test/
│   ├── java/.../ApplicationTests.java
│   └── java/.../ConsumerTest.java 等
└── pom.xml
```

--------------------------------

### DefaultMQProducer Program Configuration

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

Configuring a DefaultMQProducer directly via Java code.

```java
DefaultMQProducer producer = new DefaultMQProducer("GID-xxx", getAclRPCHook());

// 设置名称服务器地址
producer.setNamesrvAddr("http://MQ_INST_xxx:8080");

// 设置接入方式（阿里云）
producer.setAccessChannel(AccessChannel.CLOUD);

// 启动生产者
producer.start();
```

--------------------------------

### TCP Direct Connection Configuration - Using Properties Object

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

Configuring TCP direct connection for RocketMQ producer using a Java Properties object.

```java
Properties producerProperties = new Properties();
producerProperties.setProperty(PropertyKeyConst.AccessKey, MqConfig.ACCESS_KEY);
producerProperties.setProperty(PropertyKeyConst.SecretKey, MqConfig.SECRET_KEY);
producerProperties.setProperty(PropertyKeyConst.NAMESRV_ADDR, MqConfig.NAMESRV_ADDR);

// RocketMQ 5.0+ 不要设置 INSTANCE_ID
// producerProperties.setProperty(PropertyKeyConst.INSTANCE_ID, "your-instance-id");

Producer producer = ONSFactory.createProducer(producerProperties);
```

--------------------------------

### Sending Messages in a Spring Boot Application

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/springboot-integration.md

Example of how to send messages using the ProducerBean within a Spring Boot application.

```java
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
public class MessageController {
    
    @Autowired
    private ProducerBean producer;
    
    @Autowired
    private MqConfig mqConfig;
    
    @PostMapping("/send")
    public String sendMessage(@RequestParam String body) {
        Message msg = new Message(mqConfig.getTopic(), "tag", body.getBytes());
        try {
            SendResult result = producer.send(msg);
            return "发送成功，MsgId: " + result.getMessageId();
        } catch (ONSClientException e) {
            return "发送失败: " + e.getMessage();
        }
    }
}
```

--------------------------------

### application.yml Configuration

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

Configuration for RocketMQ in application.yml, supporting both 4.0 and 5.0 series instances.

```yaml
rocketmq:
  # 4.0 系列实例使用 AccessKey/AccessKeySecret
  # 5.0 系列实例使用实例用户名/密码
  accessKey: your-access-key
  secretKey: your-secret-key
  
  # 名称服务器地址
  nameSrvAddr: http://MQ_INST_xxx:8080
  
  # 普通消息
  topic: your-topic
  groupId: GID-your-group
  tag: "*"
  
  # 顺序消息
  orderTopic: your-order-topic
  orderGroupId: GID-your-order-group
  orderTag: "*"
```

--------------------------------

### Spring Framework 配置传递链

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了 Spring Framework 中配置参数的传递过程。

```text
common.xml (PropertiesFactoryBean)
    ↓
占位符 ${AccessKey}, ${NAMESRV_ADDR} 等
    ↓
producer.xml / consumer.xml
    ↓
ProducerBean / ConsumerBean 属性
    ↓
Bean 初始化 (init-method="start")
    ↓
Bean 就绪可使用
```

--------------------------------

### 高层架构图

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

This diagram illustrates the high-level architecture of the MQ system, showing the layers from Application to Aliyun MQ Service.

```text
┌─────────────────────────────────────────────────────────────┐
│                    应用层 (Application)                      │
├─────────────────────────────────────────────────────────────┤
│  RocketMQ Direct  │  ONS Client  │  Spring  │  Spring Boot   │
│  (java-rocketmq)  │  (java-tcp)  │ (spring) │  (springboot)  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│              客户端库层 (Client Libraries)                   │
├─────────────────────────────────────────────────────────────┤
│         rocketmq-client 4.5.2  │  ons-client 1.8.8.5        │
│         rocketmq-acl 4.5.2     │                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│               通讯层 (Communication)                         │
├─────────────────────────────────────────────────────────────┤
│  NameServer (服务发现)  │  Broker (消息存储)  │  ACL (认证) │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│           阿里云消息队列服务 (Aliyun MQ Service)             │
└─────────────────────────────────────────────────────────────┘
```

--------------------------------

### Spring Boot 配置传递链

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了 Spring Boot 中配置参数的传递过程。

```text
application.properties
    rocketmq.accessKey=...
    rocketmq.nameSrvAddr=...
    ↓
MqConfig (@ConfigurationProperties)
    ↓
MqConfig.getMqPropertie() → Properties
    ↓
ProducerClient / ConsumerClient (@Bean)
    ↓
ProducerBean / ConsumerBean 属性
    ↓
@Bean(initMethod="start", destroyMethod="shutdown")
    ↓
Bean 生命周期管理
```

--------------------------------

### 模块间依赖关系

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了 rocketmq-client, ons-client, Spring Framework, 和 Spring Boot 之间的依赖关系。

```text
┌─ rocketmq-client
│  ├─ rocketmq-acl (ACL 认证)
│  ├─ netty-all (网络通讯)
│  └─ commons-* (工具库)
│
├─ ons-client
│  ├─ commons-* (工具库)
│  └─ aliyun-java-sdk-* (SDK)
│
├─ Spring Framework
│  ├─ spring-core
│  ├─ spring-context
│  └─ commons-* (工具库)
│
└─ Spring Boot
   ├─ spring-boot-starter-parent
   ├─ spring-boot-starter-web
   ├─ ons-client
   └─ commons-* (工具库)
```

--------------------------------

### application.properties 配置

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

Spring Boot 项目使用 application.properties 文件配置。

```properties
# RocketMQ 4.0 系列实例
# 请设置访问的阿里云账号的 AccessKeyId
rocketmq.accessKey=your-access-key

# 请设置访问的阿里云账号的 AccessKeySecret
rocketmq.secretKey=your-secret-key

# RocketMQ 5.0 系列实例
# 请设置实例详情页获取的实例用户名
# rocketmq.accessKey=instance-user

# 请设置实例详情页获取的实例密码
# rocketmq.secretKey=instance-password

# 名称服务器地址
# RocketMQ 4.0: http://MQ_INST_xxx:port (必须有 http)
# RocketMQ 5.0: rmq-cn-xxx.xx:port (不要加 http)
rocketmq.nameSrvAddr=http://MQ_INST_xxx:8080

# 普通消息配置
rocketmq.topic=your-topic
rocketmq.groupId=GID-your-group
rocketmq.tag=*

# 顺序消息配置
rocketmq.orderTopic=your-order-topic
rocketmq.orderGroupId=GID-your-order-group
rocketmq.orderTag=*

```

--------------------------------

### MQClientException 处理示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

处理生产者启动失败的 MQClientException。

```java
try {
    producer.start();
} catch (MQClientException e) {
    System.out.println("生产者启动失败: " + e.getMessage());
    e.printStackTrace();
}
```

--------------------------------

### common.xml 配置

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

Spring 框架使用 XML 配置文件定义 Bean 和属性。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
       http://www.springframework.org/schema/beans/spring-beans.xsd 
       http://www.springframework.org/schema/context 
       http://www.springframework.org/schema/context/spring-context.xsd">

    <context:property-placeholder properties-ref="commonProperties"/>
    
    <bean id="commonProperties" 
          class="org.springframework.beans.factory.config.PropertiesFactoryBean">
        <property name="properties">
            <props>
                <prop key="AccessKey">your-access-key</prop>
                <prop key="SecretKey">your-secret-key</prop>
                <prop key="GROUP_ID">your-group-id</prop>
                <prop key="Topic">your-topic</prop>
                <prop key="NAMESRV_ADDR">your-namesrv-addr</prop>
            </props>
        </property>
    </bean>

</beans>
```

--------------------------------

### DefaultMQPushConsumer Program Configuration

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

Configuring a DefaultMQPushConsumer directly via Java code.

```java
DefaultMQPushConsumer consumer = new DefaultMQPushConsumer(
    "GID-xxx", getAclRPCHook(), new AllocateMessageQueueAveragely());

// 设置名称服务器地址
consumer.setNamesrvAddr("http://MQ_INST_xxx:8080");

// 设置接入方式
consumer.setAccessChannel(AccessChannel.CLOUD);

// 订阅主题
consumer.subscribe("topic", "*");

// 设置消费起点
consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);

// 启动消费者
consumer.start();
```

--------------------------------

### Spring Framework 集成 - common.xml

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/README.md

Spring Framework 集成中 common.xml 文件的配置示例，用于定义公共属性。

```xml
<!-- common.xml -->
<bean id="commonProperties" 
      class="org.springframework.beans.factory.config.PropertiesFactoryBean">
    <property name="properties">
        <props>
            <prop key="AccessKey">your-key</prop>
            <prop key="NAMESRV_ADDR">http://xxx:8080</prop>
        </props>
    </property>
</bean>
```

--------------------------------

### TransactionMQProducer.start

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-transaction.md

启动事务生产者。

```java
transactionProducer.start();
```

--------------------------------

### Spring Framework 集成 - producer.xml

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/README.md

Spring Framework 集成中 producer.xml 文件的配置示例，用于定义生产者 Bean。

```xml
<!-- producer.xml -->
<bean id="producer" class="com.aliyun.openservices.ons.api.bean.ProducerBean" 
      init-method="start" destroy-method="shutdown">
    <property name="properties">
        <props>
            <prop key="GROUP_ID">GID-xxx</prop>
            <prop key="AccessKey">${AccessKey}</prop>
            <prop key="NAMESRV_ADDR">${NAMESRV_ADDR}</prop>
        </props>
    </property>
</bean>
```

--------------------------------

### Sequential Consumption Bean Configuration

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/spring-integration.md

Spring XML configuration for sequential message consumption using OrderConsumerBean.

```xml
<bean id="orderConsumer" 
      class="com.aliyun.openservices.ons.api.bean.OrderConsumerBean" 
      init-method="start" destroy-method="shutdown">
    <property name="properties">
        <props>
            <prop key="GROUP_ID">${ORDER_GROUP_ID}</prop>
            <prop key="AccessKey">${AccessKey}</prop>
            <prop key="SecretKey">${SecretKey}</prop>
            <prop key="NAMESRV_ADDR">${NAMESRV_ADDR}</prop>
        </props>
    </property>
    <property name="subscriptionTable">
        <map>
            <entry key="${ORDER_TOPIC}" value="*"/>
        </map>
    </property>
    <property name="messageListener" ref="orderMessageListener"/>
</bean>
```

--------------------------------

### Spring Boot 集成 - ProducerClient.java

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/README.md

Spring Boot 集成中 ProducerClient 类的 Java 代码示例，用于构建生产者 Bean。

```java
@Configuration
public class ProducerClient {
    @Autowired
    private MqConfig mqConfig;
    
    @Bean(initMethod = "start", destroyMethod = "shutdown")
    public ProducerBean buildProducer() {
        ProducerBean producer = new ProducerBean();
        producer.setProperties(mqConfig.getMqPropertie());
        return producer;
    }
}
```

--------------------------------

### Spring Boot 集成 - application.properties

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/README.md

Spring Boot 集成中 application.properties 文件的配置示例，用于设置 RocketMQ 相关属性。

```properties
# application.properties
rocketmq.accessKey=your-key
rocketmq.secretKey=your-secret
rocketmq.nameSrvAddr=http://xxx:8080
rocketmq.topic=my-topic
rocketmq.groupId=GID-xxx
```

--------------------------------

### 生产者数据流

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

描述了生产者发送消息的整个流程。

```text
1. 应用代码
     ↓
2. 创建 Producer/ProducerBean
     ↓
3. 创建 Message 对象
     ↓
4. 调用 producer.send(message)
     ↓
5. 客户端库编码消息
     ↓
6. 连接到 NameServer 获取 Broker 信息
     ↓
7. 连接到 Broker，发送消息
     ↓
8. Broker 存储消息，返回 SendResult
     ↓
9. 应用获得发送结果（MessageId、QueueId、Offset）
```

--------------------------------

### RocketMQ 直连配置传递链

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了 RocketMQ 直连模式下配置参数的传递过程。

```text
MqConfig (常量)
    ↓
main() 方法
    ↓
MqConfig.ACCESS_KEY/SECRET_KEY → SessionCredentials
    ↓
SessionCredentials → AclClientRPCHook
    ↓
AclClientRPCHook → DefaultMQProducer/DefaultMQPushConsumer
    ↓
MqConfig.NAMESRV_ADDR → setNamesrvAddr()
```

--------------------------------

### Registering Listener in Spring XML

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/spring-integration.md

Configuration for registering a message listener bean in Spring XML.

```xml
<bean id="messageListener" 
      class="com.aliyun.openservices.spring.example.normal.DemoMessageListener"/>

<bean id="consumer" class="com.aliyun.openservices.ons.api.bean.ConsumerBean" 
      init-method="start" destroy-method="shutdown">
    ...
    <property name="messageListener" ref="messageListener"/>
</bean>
```

--------------------------------

### ONSClientException 异常类

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

Aliyun ONS 客户端异常类定义。

```java
com.aliyun.openservices.ons.api.exception.ONSClientException extends RuntimeException
```

--------------------------------

### 使用已创建的主题示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

创建消息时使用已在 RocketMQ 控制台创建的主题。

```java
Message msg = new Message("existing-topic", "tag", "data".getBytes());
```

--------------------------------

### Spring Boot 集成 API 参考 - application.properties 配置示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/README.md

application.properties configuration for Spring Boot integration.

```properties
rocketmq.accessKey=your-key
rocketmq.secretKey=your-secret
rocketmq.nameSrvAddr=http://xxx:8080
rocketmq.topic=my-topic
```

--------------------------------

### 生产者生命周期

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了生产者从创建到关闭的生命周期流程。

```text
new Producer
    ↓
配置参数
    ↓
start()
    ↓
send() (重复)
    ↓
shutdown()
```

--------------------------------

### 消费者数据流

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

描述了消费者接收和处理消息的流程。

```text
1. 应用代码
     ↓
2. 创建 Consumer/ConsumerBean
     ↓
3. 调用 subscribe(topic, subExpression)
     ↓
4. 注册 MessageListener
     ↓
5. 调用 consumer.start()
     ↓
6. 连接到 NameServer 获取 Broker 信息
     ↓
7. 连接到 Broker，发起消息拉取请求
     ↓
8. Broker 返回消息列表
     ↓
9. 客户端库解码消息
     ↓
10. 调用 MessageListener.consume() 处理每条消息
     ↓
11. 监听器返回 Action (CommitMessage / ReconsumeLater)
     ↓
12. 客户端确认消费或标记重新投递
```

--------------------------------

### Producer Error Handling

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

Demonstrates how to handle exceptions during message production, including retries, local caching, and alerting.

```java
for (int i = 0; i < 100; i++) {
    Message msg = new Message("topic", "tag", "data".getBytes());
    
    try {
        SendResult result = producer.send(msg);
        System.out.println("发送成功，MsgId: " + result.getMessageId());
    } catch (ONSClientException e) {
        System.out.println("发送失败，进行重试或缓存");
        // 建议的处理方式：
        // 1. 重试发送
        // 2. 将消息写入本地数据库，稍后重新发送
        // 3. 发送告警
        e.printStackTrace();
    }
}
```

--------------------------------

### 生产者初始化流程

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了创建、配置、启动生产者实例以及建立连接和就绪状态的步骤。

```text
1. 创建 Producer 实例
   RocketMQ: new DefaultMQProducer(groupId, rpcHook)
   ONS: ONSFactory.createProducer(properties)

2. 配置参数
   RocketMQ: setNamesrvAddr(), setAccessChannel()
   ONS: Properties 对象包含所有配置

3. 启动
   RocketMQ: producer.start()
   ONS: producer.start()

4. 连接建立
   → 连接 NameServer 获取 Broker 列表
   → 连接 Broker
   → ACL 认证

5. 就绪
   → 可以发送消息
```

--------------------------------

### 消费者生命周期

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了消费者从创建到关闭的生命周期流程。

```text
new Consumer
    ↓
subscribe()
    ↓
start()
    ↓
consume() (持续执行，由 Broker 推送触发)
    ↓
shutdown()
```

--------------------------------

### Spring Boot @ConfigurationProperties Binding

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/configuration.md

Java class for binding RocketMQ configuration properties using Spring Boot's @ConfigurationProperties.

```java
@Configuration
@ConfigurationProperties(prefix = "rocketmq")
public class MqConfig {
    private String accessKey;        // rocketmq.accessKey
    private String secretKey;        // rocketmq.secretKey
    private String nameSrvAddr;      // rocketmq.nameSrvAddr
    private String topic;            // rocketmq.topic
    private String groupId;          // rocketmq.groupId
    private String tag;              // rocketmq.tag
    private String orderTopic;       // rocketmq.orderTopic
    private String orderGroupId;     // rocketmq.orderGroupId
    private String orderTag;         // rocketmq.orderTag
    // getter/setter 方法...
```

--------------------------------

### AclClientRPCHook Class Implementation

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/types.md

ACL implementation provided by Aliyun.

```java
public class AclClientRPCHook implements RPCHook {
    public AclClientRPCHook(SessionCredentials credentials) { }
}
```

--------------------------------

### LocalTransactionExecuter.executeLocalTransactionBranch

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-transaction.md

执行本地事务的方法。

```java
public LocalTransactionState executeLocalTransactionBranch(Message msg, Object arg) {
    // 执行本地数据库事务
    // 返回事务状态
    return LocalTransactionState.COMMIT_MESSAGE;
}
```

--------------------------------

### 生产者继承关系图

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了生产者相关的类继承关系。

```text
Object
    ↓
DefaultMQProducer (RocketMQ)
    │
    ├─ Producer (ONS 接口)
    │
    ├─ ProducerBean (Spring Bean)
    │
    └─ OrderProducerBean (Spring)
    
TransactionMQProducer (RocketMQ)
    │
    └─ TransactionProducerBean (Spring)
```

--------------------------------

### 消息发送超时重试示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

处理消息发送超时异常并进行重试。

```java
try {
    SendResult result = producer.send(msg);
    System.out.println("发送成功");
} catch (ONSClientException e) {
    System.out.println("发送超时，进行重试");
    // 重试逻辑
}
```

--------------------------------

### Transactional Message Bean Configuration

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/spring-integration.md

Spring XML configuration for transactional messaging using TransactionProducerBean.

```xml
<bean id="transactionProducer" 
      class="com.aliyun.openservices.ons.api.bean.TransactionProducerBean" 
      init-method="start" destroy-method="shutdown">
    <property name="properties">
        <props>
            <prop key="GROUP_ID">${GROUP_ID}</prop>
            <prop key="AccessKey">${AccessKey}</prop>
            <prop key="SecretKey">${SecretKey}</prop>
            <prop key="NAMESRV_ADDR">${NAMESRV_ADDR}</prop>
        </props>
    </property>
    <property name="localTransactionChecker" ref="localTransactionChecker"/>
</bean>

<bean id="localTransactionChecker" 
      class="com.aliyun.openservices.spring.example.transaction.DemoLocalTransactionChecker"/>
```

--------------------------------

### setConsumeFromWhere 方法示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/rocketmq-consumer.md

设置消费开始位置的示例。

```java
consumer.setConsumeFromWhere(ConsumeFromWhere.CONSUME_FROM_FIRST_OFFSET);
```

--------------------------------

### 队列选择器扩展

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

实现 MessageQueueSelector 来自定义顺序消息的队列选择逻辑。

```java
public class CustomQueueSelector implements MessageQueueSelector {
    public MessageQueue select(List<MessageQueue> mqs, Message msg, Object arg) {
        // 自定义选择逻辑
        return mqs.get(0);
    }
}
```

--------------------------------

### 消息序列化示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

演示如何正确序列化消息体为字节数组，并指定编码。

```java
// 确保消息体是有效的字节数组
String data = "Hello World";
byte[] body = data.getBytes("UTF-8");  // 指定编码
Message msg = new Message("topic", "tag", body);
```

--------------------------------

### 配置访问密钥示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

在 ONS 客户端中配置正确的 AccessKey 和 SecretKey。

```java
// 检查凭证
properties.setProperty(PropertyKeyConst.AccessKey, "your-correct-access-key");
properties.setProperty(PropertyKeyConst.SecretKey, "your-correct-secret-key");
```

--------------------------------

### 队列分配策略扩展

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

实现 AllocateMessageQueueStrategy 来自定义消费队列分配逻辑。

```java
public class CustomAllocateStrategy implements AllocateMessageQueueStrategy {
    public List<MessageQueue> allocate(...) {
        // 自定义分配逻辑
        return queues;
    }
}
```

--------------------------------

### DemoMessageListener Implementation

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/api-reference/springboot-integration.md

A sample implementation of a MessageListener for consuming messages.

```java
public class DemoMessageListener implements MessageListener {

    @Override
    public Action consume(Message message, ConsumeContext context) {
        System.out.println("Receive: " + message);
        try {
            // 处理消息
            return Action.ReconsumeLater;
        } catch (Exception e) {
            // 消费失败，消息重新投递
            return Action.ReconsumeLater;
        }
    }
}
```

--------------------------------

### 消息监听器扩展

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

实现 MessageListener 或 MessageListenerConcurrently 来自定义消息处理逻辑。

```java
public class CustomMessageListener implements MessageListener {
    public Action consume(Message message, ConsumeContext context) {
        // 自定义逻辑
        return Action.CommitMessage;
    }
}
```

--------------------------------

### 事务消息数据流

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

描述了事务消息的发送、执行和提交/回滚流程。

```text
1. 应用代码
     ↓
2. 创建 TransactionProducer/TransactionProducerBean
     ↓
3. 注册 LocalTransactionChecker
     ↓
4. 调用 producer.sendMessageInTransaction(message, executer)
     ↓
5. 客户端发送事务消息到 Broker（状态：待处理）
     ↓
6. Broker 返回成功
     ↓
7. 客户端调用 LocalTransactionExecuter 执行本地事务
     ↓
8. LocalTransactionExecuter 返回 LocalTransactionState
     ↓
9. 客户端根据状态向 Broker 发送最终决定
     ↓
10. Broker 根据决定：
     - COMMIT：消息对消费者可见
     - ROLLBACK：消息被删除
     - UNKNOWN：等待回查
     ↓
11. Broker 回查本地事务状态（如果UNKNOWN）
     ↓
12. 客户端调用 LocalTransactionChecker 检查本地事务
     ↓
13. Checker 返回 LocalTransactionState
     ↓
14. 根据最终状态提交或回滚消息
```

--------------------------------

### 启动生产者示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

演示如何正确启动生产者以发送消息。

```java
DefaultMQProducer producer = new DefaultMQProducer("GID-xxx");
producer.setNamesrvAddr("http://xxx:8080");
producer.start();  // 必须启动

// 现在可以发送消息
Message msg = new Message("topic", "tag", "data".getBytes());
producer.send(msg);
```

--------------------------------

### 事务消息检查器实现

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

实现 `TransactionCheckListener` 接口来检查本地事务状态，用于事务消息。

```java
public class LocalTransactionCheckerImpl implements TransactionCheckListener {
    @Override
    public LocalTransactionState checkLocalTransactionState(MessageExt msg) {
        // 查询本地事务状态
        boolean transactionSucceeded = checkTransaction(msg.getMsgId());
        
        if (transactionSucceeded) {
            return LocalTransactionState.COMMIT_MESSAGE;
        }
        
        return LocalTransactionState.ROLLBACK_MESSAGE;
    }
    
    private boolean checkTransaction(String msgId) {
        // 从数据库查询事务状态
        return true;
    }
}
```

--------------------------------

### Spring Framework 集成 API 参考 - ProducerBean XML 配置示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/README.md

XML configuration for a Spring Framework ProducerBean.

```xml
<bean id="producer" class="com.aliyun.openservices.ons.api.bean.ProducerBean" 
      init-method="start" destroy-method="shutdown">
    <property name="properties">...</property>
</bean>
```

--------------------------------

### ONSClientException 处理示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

处理消息发送失败的 ONSClientException。

```java
try {
    Message msg = new Message("topic", "tag", "data".getBytes());
    SendResult result = producer.send(msg);
    System.out.println("发送成功，MsgId: " + result.getMessageId());
} catch (ONSClientException e) {
    System.out.println("消息发送失败: " + e.getMessage());
    // 建议进行重试或持久化处理
    e.printStackTrace();
}
```

--------------------------------

### 消息监听器继承关系图

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了消息监听器相关的类继承关系。

```text
MessageListener (ONS 接口)
    ├─ DemoMessageListener (普通消费)
    ├─ OrderDemoMessageListener (顺序消费)
    └─ BatchDemoMessageListener (批量消费)

MessageListenerConcurrently (RocketMQ)
    └─ RocketMQConsumer 中的匿名实现

MessageListenerOrderly (RocketMQ)
    └─ RocketMQOrderConsumer 中的匿名实现
```

--------------------------------

### 启动消费者示例

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

演示如何正确启动消费者以接收消息。

```java
DefaultMQPushConsumer consumer = new DefaultMQPushConsumer("GID-xxx");
consumer.setNamesrvAddr("http://xxx:8080");
consumer.subscribe("topic", "*");
consumer.start();  // 必须启动

System.out.println("消费者已启动");
```

--------------------------------

### 事务检查器扩展

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

实现 LocalTransactionChecker 来自定义事务状态检查逻辑。

```java
public class CustomTransactionChecker implements LocalTransactionChecker {
    public TransactionStatus check(Message msg) {
        // 查询本地事务状态
        return TransactionStatus.CommitTransaction;
    }
}
```

--------------------------------

### Consumer Error Handling

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/errors.md

Illustrates error handling within a consumer's message listener, returning Action.CommitMessage on success and Action.ReconsumeLater on failure.

```java
consumer.registerMessageListener(new MessageListener() {
    @Override
    public Action consume(Message message, ConsumeContext context) {
        try {
            // 处理消息
            processMessage(message);
            return Action.CommitMessage;  // 消费成功
        } catch (Exception e) {
            System.out.println("消息处理失败: " + e.getMessage());
            // 记录错误日志
            logger.error("Failed to process message", e);
            // 返回失败，消息将被重新投递
            return Action.ReconsumeLater;
        }
    }
});
```

--------------------------------

### 消费者初始化流程

Source: https://github.com/aliwaremq/mq-demo/blob/master/_autodocs/ARCHITECTURE.md

展示了创建、配置、注册监听器、启动消费者实例以及建立连接和就绪状态的步骤。

```text
1. 创建 Consumer 实例
   RocketMQ: new DefaultMQPushConsumer(groupId, rpcHook)
   ONS: ONSFactory.createConsumer(properties)

2. 配置参数
   RocketMQ: setNamesrvAddr(), subscribe(), setConsumeFromWhere()
   ONS: subscribe(topic, subExpression, listener)

3. 注册监听器
   RocketMQ: registerMessageListener()
   ONS: 在 subscribe() 中提供

4. 启动
   RocketMQ: consumer.start()
   ONS: consumer.start()

5. 连接建立
   → 连接 NameServer 获取 Broker 列表
   → 加入消费者组
   → 队列分配和rebalance
   → 连接 Broker 发起拉取请求
   → ACL 认证

6. 就绪
   → 开始接收消息
   → Broker 推送消息到客户端
   → 触发消息监听器
```