You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by "chenzlalvin (via GitHub)" <gi...@apache.org> on 2023/05/12 03:39:12 UTC
[GitHub] [rocketmq-site] chenzlalvin opened a new pull request, #553: to issue#552 add client sdk overview for 5.0 docs
chenzlalvin opened a new pull request, #553:
URL: https://github.com/apache/rocketmq-site/pull/553
Please do not create a Pull Request without creating an issue first.
## What is the purpose of the change
refer to #552
## Brief changelog
XX
## Verifying this change
XXXX
Follow this checklist to help us incorporate your contribution quickly and easily:
- [x] Make sure there is a Github issue filed for the change (usually before you start working on it). Trivial changes like typos do not require a Github issue. Your pull request should address just this issue, without pulling in other changes - one PR resolves one issue.
- [ ] Format the pull request title like `[ISSUE #123] Fix UnknownException when host config not exist`. Each commit in the pull request should have a meaningful subject line and body.
- [ ] Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
- [ ] Write necessary unit-test to verify your logic correction, more mock a little better when cross module dependency exist. If the new feature or significant change is committed, please remember to add integration-test in [test module](https://github.com/apache/rocketmq/tree/master/test).
- [ ] Run `mvn -B clean apache-rat:check findbugs:findbugs checkstyle:checkstyle` to make sure basic checks pass. Run `mvn clean install -DskipITs` to make sure unit-test pass. Run `mvn clean test-compile failsafe:integration-test` to make sure integration-test pass.
- [ ] If this contribution is large, please file an [Apache Individual Contributor License Agreement](http://www.apache.org/licenses/#clas).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@rocketmq.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [rocketmq-site] chenzlalvin merged pull request #553: to issue#552 add client sdk overview for 5.0 docs
Posted by "chenzlalvin (via GitHub)" <gi...@apache.org>.
chenzlalvin merged PR #553:
URL: https://github.com/apache/rocketmq-site/pull/553
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@rocketmq.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [rocketmq-site] aaron-ai commented on a diff in pull request #553: to issue#552 add client sdk overview for 5.0 docs
Posted by "aaron-ai (via GitHub)" <gi...@apache.org>.
aaron-ai commented on code in PR #553:
URL: https://github.com/apache/rocketmq-site/pull/553#discussion_r1191899504
##########
i18n/en/docusaurus-plugin-content-docs/version-5.0/13-sdk/01overview.md:
##########
@@ -0,0 +1,94 @@
+# Overview
+
+This section introduces the evolution history, selection comparison, and best practices of the Apache RocketMQ 5.x client SDK.
+
+## History and Choice
+
+Since its inception, the Apache RocketMQ project has evolved to the current version 5.x. Currently, rocketmq mainly supporting two series of client SDKs based on differences in underlying communication protocols, namely the Remoting protocol and the gRPC protocol.
+
+As the default communication protocol between early components, the Remoting protocol has an embedded client SDK that has been evolving and iterating in sync with the main repository. The Remoting protocol SDK has always been bound with the server code version iteration and mainly supports Java-based languages.
+
+The gRPC protocol was newly introduced in version 5.0, aimed at evolving a more lightweight, standardized, and easily extensible client-server communication protocol with mainstream cloud native technologies. The gRPC protocol SDK evolves as an independent repository [ RocketMQ Clients ](https://github.com/apache/rocketmq-clients), supporting languages such as Java/C++/.NET/Go/Rust. There is a relatively decoupled relationship between the client and the server, following the RocketMQ API protocol interface agreement.
+
+:::tip
+
+How to quickly distinguish whether the SDK used is the Remoting protocol or the gRPC protocol?
+
+Method 1: Check the repository coordinates
+- For Java language: If the repository coordinate is rocketmq-client, it is the Remoting protocol. If it is rocketmq-client-java, it is the gRPC protocol.
+- For other languages: Other gRPC languages are also named in the format of rocketmq-client-{language}.
+
+Method 2: Check the keywords
+- If the code package or classpath contains the keyword 'remoting', it is the Remoting protocol. Otherwise, it is the gRPC protocol SDK.
+
+:::
+
+The comparison between the Remoting protocol SDK and the gRPC protocol SDK, please refer to the following:
+
+| **Contrast term** | **Remoting SDK** | **gRPC SDK** |
+|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Multi-language support | Java/Go | Java/C/C++/.NET/Go/Rust <br></br>Details for [Link](https://github.com/apache/rocketmq-clients) |
+| Feature and Interface |Producer<br/>PushConsumer<br></br>PullConsumer<br></br>LitePullConsumer<br></br>Admin | Producer<br/>PushConsumer（Only Java）<br></br>SimpleConsumer<br></br>PullConsumer（working） |
+| Compatible version | Support 4.x and 5.x server | Only support server versions 5.0 |
+| Evolution | The Remoting protocol is mainly used for communication evolution of internal components within the server |The gRPC protocol is the preferred lightweight multi-language client, and subsequent promotion will gradually fill in all capabilities
+
+
+## Remoting SDK
+
+The Remoting protocol SDK, as the initial SDK evolution of Apache RocketMQ, uses the Remoting communication protocol of internal components of RocketMQ. It's used for communication of internal components of services and also supports API communication for client message sending and control operations.
+
+### SDK Info
+
+The currently supported programming languages and code repositories are as follows:
+
+| **Language** |**ReleaseNote** |**SDK Repo** |
+|---------|---------|---------|
+|Java|[ReleaseNote from main repo](https://github.com/apache/rocketmq/releases)|[Main repo](https://github.com/apache/rocketmq)|
+|Go|[ReleaseNote from main repo](https://github.com/apache/rocketmq-client-go/releases)|[Main repo](https://github.com/apache/rocketmq-client-go)|
+
+### Features
+Waiting updates.
+
+
+## gRPC SDK
+The gRPC protocol SDK, introduced in Apache RocketMQ version 5.0, aims to provide a cloud-native, robust client solution for all major programming languages, including Java, C++, C#, Golang, JavaScript, and Rust. The gRPC SDK adheres to the [rocketmq-apis](https://github.com/apache/rocketmq-apis) constraints and uses Protocol Buffers and gRPC to replace the old protocol in version 4.x.
+
+The gRPC SDK has the following advantages over the earlier Remoting protocol SDK:
+- More concise interface design, easier to understand and less prone to error.
+- Better interface design with clear parameters and exception types.
+- Immutable interface design to avoid business exceptions caused by parameter and information leakage.
+- Better support for multiple languages, as the gRPC protocol has the advantage of supporting multiple languages and enables lower cost evolution to achieve consistent behavior in multiple language SDKs.
+
+Want the detailed design thinking and evolutionary direction, refer to [RIP-37: New and Unified APIs](https://shimo.im/docs/m5kv92OeRRU8olqX) and [RIP-39: Support gRPC protocol](https://shimo.im/docs/gXqmeEPYgdUw5bqo).
+
+### SDK Info
+
+The currently supported programming languages and code repositories are as follows:
+
+| **Language** |**ReleaseNote** |**SDK Repo** |
+|---------|---------|---------|
+|Java|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
+|C++|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
+|.NET|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
+|Go|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
+|Rust|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
Review Comment:
Rust SDK has not been released yet, but the release process will be handled recently.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@rocketmq.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [rocketmq-site] aaron-ai commented on a diff in pull request #553: to issue#552 add client sdk overview for 5.0 docs
Posted by "aaron-ai (via GitHub)" <gi...@apache.org>.
aaron-ai commented on code in PR #553:
URL: https://github.com/apache/rocketmq-site/pull/553#discussion_r1191899504
##########
i18n/en/docusaurus-plugin-content-docs/version-5.0/13-sdk/01overview.md:
##########
@@ -0,0 +1,94 @@
+# Overview
+
+This section introduces the evolution history, selection comparison, and best practices of the Apache RocketMQ 5.x client SDK.
+
+## History and Choice
+
+Since its inception, the Apache RocketMQ project has evolved to the current version 5.x. Currently, rocketmq mainly supporting two series of client SDKs based on differences in underlying communication protocols, namely the Remoting protocol and the gRPC protocol.
+
+As the default communication protocol between early components, the Remoting protocol has an embedded client SDK that has been evolving and iterating in sync with the main repository. The Remoting protocol SDK has always been bound with the server code version iteration and mainly supports Java-based languages.
+
+The gRPC protocol was newly introduced in version 5.0, aimed at evolving a more lightweight, standardized, and easily extensible client-server communication protocol with mainstream cloud native technologies. The gRPC protocol SDK evolves as an independent repository [ RocketMQ Clients ](https://github.com/apache/rocketmq-clients), supporting languages such as Java/C++/.NET/Go/Rust. There is a relatively decoupled relationship between the client and the server, following the RocketMQ API protocol interface agreement.
+
+:::tip
+
+How to quickly distinguish whether the SDK used is the Remoting protocol or the gRPC protocol?
+
+Method 1: Check the repository coordinates
+- For Java language: If the repository coordinate is rocketmq-client, it is the Remoting protocol. If it is rocketmq-client-java, it is the gRPC protocol.
+- For other languages: Other gRPC languages are also named in the format of rocketmq-client-{language}.
+
+Method 2: Check the keywords
+- If the code package or classpath contains the keyword 'remoting', it is the Remoting protocol. Otherwise, it is the gRPC protocol SDK.
+
+:::
+
+The comparison between the Remoting protocol SDK and the gRPC protocol SDK, please refer to the following:
+
+| **Contrast term** | **Remoting SDK** | **gRPC SDK** |
+|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Multi-language support | Java/Go | Java/C/C++/.NET/Go/Rust <br></br>Details for [Link](https://github.com/apache/rocketmq-clients) |
+| Feature and Interface |Producer<br/>PushConsumer<br></br>PullConsumer<br></br>LitePullConsumer<br></br>Admin | Producer<br/>PushConsumer（Only Java）<br></br>SimpleConsumer<br></br>PullConsumer（working） |
+| Compatible version | Support 4.x and 5.x server | Only support server versions 5.0 |
+| Evolution | The Remoting protocol is mainly used for communication evolution of internal components within the server |The gRPC protocol is the preferred lightweight multi-language client, and subsequent promotion will gradually fill in all capabilities
+
+
+## Remoting SDK
+
+The Remoting protocol SDK, as the initial SDK evolution of Apache RocketMQ, uses the Remoting communication protocol of internal components of RocketMQ. It's used for communication of internal components of services and also supports API communication for client message sending and control operations.
+
+### SDK Info
+
+The currently supported programming languages and code repositories are as follows:
+
+| **Language** |**ReleaseNote** |**SDK Repo** |
+|---------|---------|---------|
+|Java|[ReleaseNote from main repo](https://github.com/apache/rocketmq/releases)|[Main repo](https://github.com/apache/rocketmq)|
+|Go|[ReleaseNote from main repo](https://github.com/apache/rocketmq-client-go/releases)|[Main repo](https://github.com/apache/rocketmq-client-go)|
+
+### Features
+Waiting updates.
+
+
+## gRPC SDK
+The gRPC protocol SDK, introduced in Apache RocketMQ version 5.0, aims to provide a cloud-native, robust client solution for all major programming languages, including Java, C++, C#, Golang, JavaScript, and Rust. The gRPC SDK adheres to the [rocketmq-apis](https://github.com/apache/rocketmq-apis) constraints and uses Protocol Buffers and gRPC to replace the old protocol in version 4.x.
+
+The gRPC SDK has the following advantages over the earlier Remoting protocol SDK:
+- More concise interface design, easier to understand and less prone to error.
+- Better interface design with clear parameters and exception types.
+- Immutable interface design to avoid business exceptions caused by parameter and information leakage.
+- Better support for multiple languages, as the gRPC protocol has the advantage of supporting multiple languages and enables lower cost evolution to achieve consistent behavior in multiple language SDKs.
+
+Want the detailed design thinking and evolutionary direction, refer to [RIP-37: New and Unified APIs](https://shimo.im/docs/m5kv92OeRRU8olqX) and [RIP-39: Support gRPC protocol](https://shimo.im/docs/gXqmeEPYgdUw5bqo).
+
+### SDK Info
+
+The currently supported programming languages and code repositories are as follows:
+
+| **Language** |**ReleaseNote** |**SDK Repo** |
+|---------|---------|---------|
+|Java|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
+|C++|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
+|.NET|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
+|Go|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
+|Rust|[ReleaseNote from main repo](https://github.com/apache/rocketmq-clients/releases)|[Main repo](https://github.com/apache/rocketmq-clients)|
Review Comment:
Rust SDK has not been released yet, but the release process will be handled recently.
By the way, could we just reuse the existing table in the ["Features and Status" section of rocketmq-clients](https://github.com/apache/rocketmq-clients#features-and-status)?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@rocketmq.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org