This is an automated email from the ASF dual-hosted git repository.
chenzlalvin pushed a commit to branch new-official-website
in repository https://gitbox.apache.org/repos/asf/rocketmq-site.git
The following commit(s) were added to refs/heads/new-official-website by this
push:
new f4996dc64 to issue#548 add messageType demo for topic concept docs
new cbd146ce6 Merge pull request #549 from
chenzlalvin/issue548_messageTypes
f4996dc64 is described below
commit f4996dc64ff29c814bd4efbeab291a8e31928428
Author: Zhongliang.Chen <[email protected]>
AuthorDate: Tue May 9 09:08:47 2023 +0800
to issue#548 add messageType demo for topic concept docs
---
.../version-5.0/01-introduction/02concepts.md | 5 +++++
.../version-5.0/03-domainModel/02topic.md | 14 +++++++++++++-
.../04-featureBehavior/01normalmessage.md | 10 ++++++++++
.../04-featureBehavior/02delaymessage.md | 10 ++++++++++
.../version-5.0/04-featureBehavior/03fifomessage.md | 10 ++++++++++
.../04-featureBehavior/04transactionmessage.md | 10 ++++++++++
.../version-5.0/01-introduction/02concepts.md | 6 ++++++
.../version-5.0/03-domainModel/02topic.md | 21 ++++++++++++++++++---
.../04-featureBehavior/01normalmessage.md | 9 +++++++++
.../04-featureBehavior/02delaymessage.md | 10 ++++++++++
.../version-5.0/04-featureBehavior/03fifomessage.md | 10 ++++++++++
.../04-featureBehavior/04transactionmessage.md | 10 ++++++++++
12 files changed, 121 insertions(+), 4 deletions(-)
diff --git
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/01-introduction/02concepts.md
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/01-introduction/02concepts.md
index 47318b16a..097631593 100644
---
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/01-introduction/02concepts.md
+++
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/01-introduction/02concepts.md
@@ -9,6 +9,11 @@ A topic is a top-level container that is used in Apache
RocketMQ to transfer and
## MessageType
Categories defined by message transfer characteristics for type management and
security verification. Apache RocketMQ support NORMAL,FIFO,TRANSACTION and
DELAY message type.
+:::info
+
+Starting from version 5.0, Apache RocketMQ supports enforcing the validation
of message types, that is, each topic only allows messages of a single type to
be sent. This can better facilitate operation and management of production
systems and avoid confusion. However, to ensure backward compatibility with
version 4.x, the validation feature is disabled by default. It is recommended
to enable it manually through the server parameter
"enableTopicMessageTypeCheck".
+:::
+
## MessageQueue
MessageQueue is a container that is used to store and transmit messages in
Apache RocketMQ. MessageQueue is the smallest unit of storage for Apache
RocketMQ messages. Learn more
[MessageQueue](../03-domainModel/03messagequeue.md).
diff --git
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/03-domainModel/02topic.md
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/03-domainModel/02topic.md
index 3115deb5e..e9da97248 100644
---
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/03-domainModel/02topic.md
+++
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/03-domainModel/02topic.md
@@ -59,7 +59,7 @@ A topic contains one or more queues. Message storage and
scalability are impleme
* Transaction: [Transaction
messages](../04-featureBehavior/04transactionmessage.md). Apache RocketMQ
supports distributed transaction messages and ensures transaction consistency
of database updates and message calls.
-* Constraint: A topic supports only one message type.
+* Constraint: Starting from version 5.0, Apache RocketMQ supports enforcing
the validation of message types, that is, each topic only allows messages of a
single type to be sent. This can better facilitate operation and management of
production systems and avoid confusion. However, to ensure backward
compatibility with version 4.x, the validation feature is disabled by default.
It is recommended to enable it manually through the server parameter
"enableTopicMessageTypeCheck".
## Behavior constraints
@@ -72,6 +72,11 @@ Apache RocketMQ version 5.x allows you to specify a message
type for a topic. Th
* Only one type of messages sent to a topicThe messages that you want to send
to a topic must use the same message type. Only one message type can be
specified for a topic.
+:::info
+
+To ensure backward compatibility with version 4.x, the above validation
feature is disabled by default. It is recommended to enable the validation by
using the server parameter "enableTopicMessageTypeCheck".
+
+:::
**Examples of common usage errors**
@@ -87,6 +92,13 @@ Forced message type verification is available only in Apache
RocketMQ version 5.
We recommend that you use Apache RocketMQ version 5.x.
+## Usage Example
+For creating topics in Apache RocketMQ 5.0, it is recommended to use the
mqadmin tool. However, it is worth noting that message type needs to be added
as a property parameter. The following is an example:
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=<message_type>
+```
+Among these, the message_type parameter can be set as
Normal/FIFO/Delay/Transaction based on the message type. If it is not
specified, it defaults to the Normal type.
+
## Usage notes
**Plan topics based on your business requirements**
diff --git
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/01normalmessage.md
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/01normalmessage.md
index 437efc8dd..a249844e2 100644
---
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/01normalmessage.md
+++
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/01normalmessage.md
@@ -45,6 +45,16 @@ Normal messages support only topics whose MessageType is
Normal.
## Example
+**Create topic**
+
+For creating topics in Apache RocketMQ 5.0, it is recommended to use the
mqadmin tool. However, it is worth noting that message type needs to be added
as a property parameter. Here is an example:
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=Normal
+```
+
+**Send messages**
+
You can set index keys and filter tags to filter or search for normal
messages. The following sample code shows how to send and receive normal
messages in Java:
```java
// Send a normal message.
diff --git
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/02delaymessage.md
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/02delaymessage.md
index a1121eadd..e7454726d 100644
---
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/02delaymessage.md
+++
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/02delaymessage.md
@@ -92,6 +92,16 @@ The status of delay messages in Apache RocketMQ can be
persistently stored. If t
## Example
+**Create topic**
+
+For creating topics in Apache RocketMQ 5.0, it is recommended to use the
mqadmin tool. However, it is worth noting that message type needs to be added
as a property parameter. Here is an example:
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=Delay
+```
+
+**Send messages**
+
Unlike normal messages, delay messages must have a delivery timestamp
specified for them.
The following code provides Java examples of delivery and consumption of delay
messages:
diff --git
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/03fifomessage.md
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/03fifomessage.md
index 4dc893010..1f3e22e8d 100644
---
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/03fifomessage.md
+++
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/03fifomessage.md
@@ -114,6 +114,16 @@ Ordered messages support only topics whose MessageType is
FIFO.
## Example
+**Create topic**
+
+For creating topics in Apache RocketMQ 5.0, it is recommended to use the
mqadmin tool. However, it is worth noting that message type needs to be added
as a property parameter. Here is an example:
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=FIFO
+```
+
+**Send messages**
+
Compared with normal messages, ordered messages must have message groups
configured for them. We recommend that you configure message groups at a
fine-grained level based on your business requirements to allow for workload
decoupling and concurrency scaling.
The following sample code provides an example on how to send and receive
ordered messages in Java:
diff --git
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/04transactionmessage.md
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/04transactionmessage.md
index 5c0603aa6..4a1ceed02 100644
---
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/04transactionmessage.md
+++
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/04-featureBehavior/04transactionmessage.md
@@ -117,6 +117,16 @@ Apache RocketMQ implements a timeout mechanism for
transactional messages. Upon
## Example
+**Create topic**
+
+For creating topics in Apache RocketMQ 5.0, it is recommended to use the
mqadmin tool. However, it is worth noting that message type needs to be added
as a property parameter. Here is an example:
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=Transaction
+```
+
+**Send messages**
+
Sending transactional messages is different from sending normal messages in
the following aspects:
* Before sending transactional messages, you must enable the transaction
checker and associate it with local transaction execution.
diff --git a/versioned_docs/version-5.0/01-introduction/02concepts.md
b/versioned_docs/version-5.0/01-introduction/02concepts.md
index f9cd13d72..d0dcecd2b 100644
--- a/versioned_docs/version-5.0/01-introduction/02concepts.md
+++ b/versioned_docs/version-5.0/01-introduction/02concepts.md
@@ -8,6 +8,12 @@ Apache RocketMQ 中消息传输和存储的顶层容器，用于标识同一类
## 消息类型（MessageType）
Apache RocketMQ 中按照消息传输特性的不同而定义的分类，用于类型管理和安全校验。 Apache RocketMQ
支持的消息类型有普通消息、顺序消息、事务消息和定时/延时消息。
+:::info
+
+Apache RocketMQ
从5.0版本开始，支持强制校验消息类型，即每个主题Topic只允许发送一种消息类型的消息，这样可以更好的运维和管理生产系统，避免混乱。但同时保证向下兼容4.x版本行为，强制校验功能默认关闭，推荐通过服务端参数
enableTopicMessageTypeCheck 手动开启校验。
+
+:::
+
## 消息队列（MessageQueue）
队列是 Apache RocketMQ 中消息存储和传输的实际容器，也是消息的最小存储单元。 Apache RocketMQ
的所有主题都是由多个队列组成，以此实现队列数量的水平拆分和队列内部的流式存储。队列通过QueueId来做唯一标识和区分。更多信息，请参见[队列（MessageQueue）](../03-domainModel/03messagequeue.md)。
diff --git a/versioned_docs/version-5.0/03-domainModel/02topic.md
b/versioned_docs/version-5.0/03-domainModel/02topic.md
index f832f8c76..90d38e3e4 100644
--- a/versioned_docs/version-5.0/03-domainModel/02topic.md
+++ b/versioned_docs/version-5.0/03-domainModel/02topic.md
@@ -59,7 +59,8 @@
* Transaction：[事务消息](../04-featureBehavior/04transactionmessage.md)，Apache
RocketMQ 支持分布式事务消息，支持应用数据库更新和消息调用的事务一致性保障。
-* 约束：每个主题只支持一种消息类型。
+* 约束：Apache RocketMQ
从5.0版本开始，支持强制校验消息类型，即每个主题只允许发送一种消息类型的消息，这样可以更好的运维和管理生产系统，避免混乱。为保证向下兼容4.x版本行为，强制校验功能默认关闭，推荐通过服务端参数
enableTopicMessageTypeCheck 开启校验。
+
@@ -68,12 +69,18 @@
**消息类型强制校验**
-Apache RocketMQ
5.x版本将消息类型拆分到主题中进行独立运维和处理，因此系统会对发送的消息类型和主题定的消息类型进行强制校验，若校验不通过，则消息发送请求会被拒绝，并返回类型不匹配异常。校验原则如下：
+Apache RocketMQ
5.x版本支持将消息类型拆分到主题中进行独立运维和处理，因此系统会对发送的消息类型和主题定的消息类型进行强制校验，若校验不通过，则消息发送请求会被拒绝，并返回类型不匹配异常。校验原则如下：
* 消息类型必须一致发送的消息的类型，必须和目标主题定义的消息类型一致。
* 主题类型必须单一每个主题只支持一种消息类型，不允许将多种类型的消息发送到同一个主题中。
+:::info
+
+为保证向下兼容4.x版本行为，上述强制校验功能默认关闭，推荐通过服务端参数 enableTopicMessageTypeCheck 开启校验。
+
+:::
+
**常见错误使用场景**
* 发送的消息类型不匹配例如，创建主题时消息类型定义为顺序消息，发送消息时发送事务消息到该主题中，此时消息发送请求会被拒绝，并返回类型不匹配异常。
@@ -84,9 +91,17 @@ Apache RocketMQ 5.x版本将消息类型拆分到主题中进行独立运维和
## 版本兼容性
-消息类型的强制校验，仅针对 Apache RocketMQ 服务端5.x版本生效。 Apache RocketMQ
服务端4.x和3.x历史版本的SDK不支持强制校验，您需要自己保证消息类型一致。 如果您使用的服务端版本为历史版本，建议您升级到
+消息类型的强制校验，仅 Apache RocketMQ 服务端5.x版本支持，且默认关闭，推荐部署时打开配置。 Apache RocketMQ
服务端4.x和3.x历史版本的SDK不支持强制校验，您需要自己保证消息类型一致。 如果您使用的服务端版本为历史版本，建议您升级到
Apache RocketMQ 服务端5.x版本。
+## 使用示例
+Apache RocketMQ 5.0版本下创建主题操作，推荐使用mqadmin工具，需要注意的是，对于消息类型需要通过属性参数添加。示例如下：
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=<message_type>
+```
+其中message_type根据消息类型设置成Normal/FIFO/Delay/Transaction。如果不设置，默认为Normal类型。
+
## 使用建议
**按照业务分类合理拆分主题**
diff --git a/versioned_docs/version-5.0/04-featureBehavior/01normalmessage.md
b/versioned_docs/version-5.0/04-featureBehavior/01normalmessage.md
index 7ef444ce5..0e7889ddd 100644
--- a/versioned_docs/version-5.0/04-featureBehavior/01normalmessage.md
+++ b/versioned_docs/version-5.0/04-featureBehavior/01normalmessage.md
@@ -41,6 +41,15 @@
## 使用示例
+**创建主题**
+
+Apache RocketMQ 5.0版本下创建主题操作，推荐使用mqadmin工具，需要注意的是，对于消息类型需要通过属性参数添加。示例如下：
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=Normal
+```
+
+**发送消息**
普通消息支持设置消息索引键、消息过滤标签等信息，用于消息过滤和搜索查找。以Java语言为例，收发普通消息的示例代码如下：
```java
diff --git a/versioned_docs/version-5.0/04-featureBehavior/02delaymessage.md
b/versioned_docs/version-5.0/04-featureBehavior/02delaymessage.md
index 865375fda..d3f6951a3 100644
--- a/versioned_docs/version-5.0/04-featureBehavior/02delaymessage.md
+++ b/versioned_docs/version-5.0/04-featureBehavior/02delaymessage.md
@@ -83,6 +83,16 @@ Apache RocketMQ 定时消息的状态支持持久化存储，系统由于故障
## 使用示例
+**创建主题**
+
+Apache RocketMQ 5.0版本下创建主题操作，推荐使用mqadmin工具，需要注意的是，对于消息类型需要通过属性参数添加。示例如下：
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=Delay
+```
+
+**发送消息**
+
和普通消息相比，定时消费发送时，必须设置定时触发的目标时间戳。
以Java语言为例，使用定时消息示例参考如下：
diff --git a/versioned_docs/version-5.0/04-featureBehavior/03fifomessage.md
b/versioned_docs/version-5.0/04-featureBehavior/03fifomessage.md
index 24413bd3e..8b08ac552 100644
--- a/versioned_docs/version-5.0/04-featureBehavior/03fifomessage.md
+++ b/versioned_docs/version-5.0/04-featureBehavior/03fifomessage.md
@@ -121,6 +121,16 @@ Apache RocketMQ 的消息的顺序性分为两部分，生产顺序性和消费
## 使用示例
+**创建主题**
+
+Apache RocketMQ 5.0版本下创建主题操作，推荐使用mqadmin工具，需要注意的是，对于消息类型需要通过属性参数添加。示例如下：
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=FIFO
+```
+
+**发送消息**
+
和普通消息发送相比，顺序消息发送必须要设置消息组。消息组的粒度建议按照业务场景，尽可能细粒度设计，以便实现业务拆分和并发扩展。
以Java语言为例，收发顺序消息的示例代码如下：
diff --git
a/versioned_docs/version-5.0/04-featureBehavior/04transactionmessage.md
b/versioned_docs/version-5.0/04-featureBehavior/04transactionmessage.md
index 283834376..215c367b7 100644
--- a/versioned_docs/version-5.0/04-featureBehavior/04transactionmessage.md
+++ b/versioned_docs/version-5.0/04-featureBehavior/04transactionmessage.md
@@ -112,6 +112,16 @@ Apache RocketMQ 事务消息的命周期存在超时机制，即半事务消息
## 使用示例
+**创建主题**
+
+Apache RocketMQ 5.0版本下创建主题操作，推荐使用mqadmin工具，需要注意的是，对于消息类型需要通过属性参数添加。示例如下：
+
+```shell
+sh mqadmin updateTopic -n <nameserver_address> -t <topic_name> -c
<cluster_name> -a +message.type=Transaction
+```
+
+**发送消息**
+
事务消息相比普通消息发送时需要修改以下几点：
* 发送事务消息前，需要开启事务并关联本地的事务执行。
