You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@rocketmq.apache.org by aa...@apache.org on 2022/12/28 05:06:19 UTC
[rocketmq-clients] branch master updated: Polish docs (#327)
This is an automated email from the ASF dual-hosted git repository.
aaronai pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/rocketmq-clients.git
The following commit(s) were added to refs/heads/master by this push:
new 0464fe95 Polish docs (#327)
0464fe95 is described below
commit 0464fe95595b17b74dba6bff2e1862d7bcd18313
Author: Aaron Ai <ya...@gmail.com>
AuthorDate: Wed Dec 28 13:06:13 2022 +0800
Polish docs (#327)
---
java/README-CN.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
java/README.md | 42 +++++++++++++++++++++++++------------
2 files changed, 91 insertions(+), 13 deletions(-)
diff --git a/java/README-CN.md b/java/README-CN.md
new file mode 100644
index 00000000..64821cae
--- /dev/null
+++ b/java/README-CN.md
@@ -0,0 +1,62 @@
+# Java 客户端
+
+[English](README.md) | 简体中文
+
+不同于[基于 RemotingCommand 协议的客户端](https://github.com/apache/rocketmq/tree/develop/client)，当前的客户端是基于 RocektMQ 5.0 存算分离架构，是 RocketMQ 社区目前推荐的接入方式，也是未来客户端演进的主方向。
+
+在开始客户端的部分之前，可能需要的一些前期准备工作：
+
+1. Java 8 是确保客户端运行的最小版本，Java 11 是确保客户端编译的最小版本；
+2. 提前部署好 namesrv，broker 以及 [proxy](https://github.com/apache/rocketmq/tree/develop/proxy) 组件。
+
+## 快速开始
+
+根据构建系统增加对应的客户端依赖，并将 `${rocketmq.version}` 替换成中央仓库中[最新的版本](https://search.maven.org/search?q=g:org.apache.rocketmq%20AND%20a:rocketmq-client-java)。
+
+```xml
+<!-- For Apache Maven -->
+<dependency>
+ <groupId>org.apache.rocketmq</groupId>
+ <artifactId>rocketmq-client-java</artifactId>
+ <version>${rocketmq.version}</version>
+</dependency>
+
+<!-- Groovy Kotlin DSL for Gradle -->
+implementation("org.apache.rocketmq:rocketmq-client-java:${rocketmq.version}")
+
+<!-- Groovy DSL for Gradle -->
+implementation 'org.apache.rocketmq:rocketmq-client-java:${rocketmq.version}'
+```
+
+`rocketmq-client-java` 是一个经过 shade 之后的版本，这意味着它本身的依赖是不能被手动替换的。通常情况下，shade 是规避多个类库之间依赖冲突的有效方式。对于一些特殊场景，我们仍然提供了未经 shade 的版本。
+
+```xml
+<!-- For Apache Maven -->
+<dependency>
+ <groupId>org.apache.rocketmq</groupId>
+ <artifactId>rocketmq-client-java-noshade</artifactId>
+ <version>${rocketmq.version}</version>
+</dependency>
+
+<!-- Groovy Kotlin DSL for Gradle -->
+implementation("org.apache.rocketmq:rocketmq-client-java-noshade:${rocketmq.version}")
+
+<!-- Groovy DSL for Gradle -->
+implementation 'org.apache.rocketmq:rocketmq-client-java-noshade:${rocketmq.version}'
+```
+
+如果不确定是否应该使用哪个版本，那么请使用 shade 之后的版本，即 `rocketmq-client-java`。
+
+我们在这里提供了[代码示例](./client/src/main/java/org/apache/rocketmq/client/java/example)来帮助使用不同的客户端和不同的消息类型。
+
+## 日志
+
+我们使用 [Logback](https://logback.qos.ch/) 来作为日志实现，为了保证日志能够始终被有效地持久化，我们将 Logback 集成到了内部。`rocketmq-client-java` 中使用了一个 shade 之后的 Logback，并会使用单独的配置文件。
+
+在满足日志被有效持久化的前提下，以下是一些可以灵活配置的日志参数，所有参数均支持 JVM 系统参数（e.g. `java -Drocketmq.log.level=INFO -jar foobar.jar`）或环境变量进行指定。
+
+* `rocketmq.log.level`: 日志输出级别，默认为 INFO。
+* `rocketmq.log.root`: 日志输出根目录，默认为当前用户的 HOME 目录。
+* `rocketmq.log.file.maxIndex`: 日志文件最大保留个数，默认为 10（单个日志文件大小限制为 64 MB，暂不支持调整）。
+
+特别地，如果有调试的需求，可以通过把 `mq.consoleAppender.enabled` 设置成 `true` 将客户端的日志同时输出到控制台。
diff --git a/java/README.md b/java/README.md
index 68e5a23f..6e479da4 100644
--- a/java/README.md
+++ b/java/README.md
@@ -1,44 +1,60 @@
# The Java Implementation of Apache RocketMQ Client
-Here is the java implementation of the client for [Apache RocketMQ](https://rocketmq.apache.org/).
+English | [简体中文](README-CN.md)
-## Prerequisites
+Here is the java implementation of the client for [Apache RocketMQ](https://rocketmq.apache.org/). Different from the [remoting-based client](https://github.com/apache/rocketmq/tree/develop/client), the current implementation is based on separating architecture for computing and storage, which is the more recommended way to access the RocketMQ service.
-| Stage | Requirements |
-| ------- | ------------ |
-| Build | JDK 11+ |
-| Runtime | JRE 8+ |
+Here are some preparations you may need to know.
+
+1. Java 8+ for runtime, Java 11+ for the build;
+2. Setup namesrv, broker, and [proxy](https://github.com/apache/rocketmq/tree/develop/proxy).
## Getting Started
-Firstly, add the dependency to your `pom.xml`, and replace the `${rocketmq.version}` with the latest version.
+Dependencies must be included in accordance with your build automation tools, and replace the `${rocketmq.version}` with the [latest version]((https://search.maven.org/search?q=g:org.apache.rocketmq%20AND%20a:rocketmq-client-java)).
```xml
+<!-- For Apache Maven -->
<dependency>
<groupId>org.apache.rocketmq</groupId>
<artifactId>rocketmq-client-java</artifactId>
<version>${rocketmq.version}</version>
</dependency>
+
+<!-- Groovy Kotlin DSL for Gradle -->
+implementation("org.apache.rocketmq:rocketmq-client-java:${rocketmq.version}")
+
+<!-- Groovy DSL for Gradle -->
+implementation 'org.apache.rocketmq:rocketmq-client-java:${rocketmq.version}'
```
-Note: `rocketmq-client-java` is a shaded jar, which means you could not substitute its dependencies.
-From the perspective of avoiding dependency conflicts, you may need a shaded client in most cases, but we also provided
-the no-shaded client.
+The `rocketmq-client-java` is a shaded jar, which means its dependencies can not be manually changed. While we still offer the no-shaded jar for exceptional situations, use the shaded one if you are unsure which version to use. In the majority of cases, this is a good technique for dealing with library dependencies that clash with one another.
```xml
+<!-- For Apache Maven -->
<dependency>
<groupId>org.apache.rocketmq</groupId>
<artifactId>rocketmq-client-java-noshade</artifactId>
<version>${rocketmq.version}</version>
</dependency>
+
+<!-- Groovy Kotlin DSL for Gradle -->
+implementation("org.apache.rocketmq:rocketmq-client-java-noshade:${rocketmq.version}")
+
+<!-- Groovy DSL for Gradle -->
+implementation 'org.apache.rocketmq:rocketmq-client-java-noshade:${rocketmq.version}'
```
You can see more code examples [here](./client/src/main/java/org/apache/rocketmq/client/java/example).
## Logging System
-We use [logback](https://logback.qos.ch/) as our logging system and redirect the log of gRPC to [SLF4j](https://www.slf4j.org/) as well.
+We picked [Logback](https://logback.qos.ch/) and shaded it into the client implementation to guarantee that logging is reliably persistent. Because RocketMQ utilizes a distinct configuration file, you shouldn't be concerned that the Logback configuration file will clash with yours.
+
+The following logging parameters are all supported for specification by JVM system parameters (for example, "java -Drocketmq.log.level=INFO -jar foobar.jar") or environment variables.
-To prevent the conflict of configuration file while both of rocketmq client and standard logback is introduced in the same project, we shaded a new logback using `rocketmq.logback.xml/rocketmq.logback-test.xml/rocketmq.logback.groovy` instead of `logback.xml/logback-test.xml/logback.groovy` as its configuration file in the shaded jar.
+* `rocketmq.log.level`: log output level, default is INFO.
+* `rocketmq.log.root`: the root directory of the log output, default is the current user's HOME directory.
+* `rocketmq.log.file.maxIndex`: the maximum number of log files to keep, default is 10 (the size of a single log file is limited to 64 MB, no adjustment is supported now).
-You can adjust the log level by the environment parameter or the java system property - `rocketmq.log.level`. See [here](https://logback.qos.ch/manual/architecture.html#effectiveLevel) for more details about logback log level.
+Specifically, by setting `mq.consoleAppender.enabled` to 'true,' you can output client logs to the console simultaneously if you need debugging.