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 15709fe Docs: polish the java part (#23)
15709fe is described below
commit 15709fe6c0f22844dca64bbd5860f1c2ba1078fd
Author: Aaron Ai <[email protected]>
AuthorDate: Sun Jul 3 17:52:25 2022 +0800
Docs: polish the java part (#23)
* Docs: move java code example to an independent file
* Docs: polish the java part
---
java/README.md | 85 ++++++------------------------------------
java/{README.md => example.md} | 44 +++-------------------
2 files changed, 16 insertions(+), 113 deletions(-)
diff --git a/java/README.md b/java/README.md
index 206232d..927f035 100644
--- a/java/README.md
+++ b/java/README.md
@@ -1,15 +1,13 @@
-# RocketMQ Clients for Java
+# The Java Implementation
-[](https://github.com/apache/rocketmq-clients/actions/workflows/java_build.yml)
-
-The java client implementation of [Apache
RocketMQ](https://rocketmq.apache.org/).
+Here is the java implementation of the client for [Apache
RocketMQ](https://rocketmq.apache.org/).
## Prerequisites
-This project guarantees the same runtime compatibility with
[grpc-java](https://github.com/grpc/grpc-java).
-
-* Java 11 or higher is required to build this project.
-* The built artifacts can be used on Java 8 or higher.
+| Stage | Requirements |
+| ------- | ------------ |
+| Build | JDK 11+ |
+| Runtime | JRE 8+ |
## Getting Started
@@ -35,73 +33,12 @@ the no-shaded client.
</dependency>
```
-There is a provider based on the Java SPI mechanism, the provider here can
derive specific implementations.
+You can see more code examples [here](./example.md).
-```java
-// Find the implementation of APIs according to SPI mechanism.
-final ClientServiceProvider provider = ClientServiceProvider.loadService();
-StaticSessionCredentialsProvider staticSessionCredentialsProvider =
- new StaticSessionCredentialsProvider(accessKey, secretKey);
-ClientConfiguration clientConfiguration = ClientConfiguration.newBuilder()
- .setEndpoints(endpoints)
- .setCredentialProvider(staticSessionCredentialsProvider)
- .build();
-```
+## Logging System
-### Producer
-
-```java
-// Build your message.
-final Message message = provider.newMessageBuilder()
- .setTopic(topic)
- .setBody(body)
- .setTag(tag)
- .build();
-// Build your producer.
-Producer producer = provider.newProducerBuilder()
- .setClientConfiguration(clientConfiguration)
- .setTopics(topic)
- .build();
-for (int i = 0; i < 1024; i++) {
- final SendReceipt sendReceipt = producer.send(message);
-}
-// Close it when you don't need the producer any more.
-producer.close();
-```
+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.
-### PushConsumer
+To prevent the clash 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.
-```java
-// Build your push consumer.
-PushConsumer pushConsumer = provider.newPushConsumerBuilder()
- .setClientConfiguration(clientConfiguration)
- .setConsumerGroup(consumerGroup)
- .setSubscriptionExpressions(Collections.singletonMap(topic,
filterExpression))
- .setMessageListener(messageView -> {
- // Handle the received message and return the consume result.
- return ConsumeResult.SUCCESS;
- })
- .build();
-// Close it when you don't need the consumer any more.
-pushConsumer.close();
-```
-
-### SimpleConsumer
-
-```java
-// Build your simple consumer.
-SimpleConsumer simpleConsumer = provider.newSimpleConsumerBuilder()
- .setClientConfiguration(clientConfiguration)
- .setConsumerGroup(consumerGroup)
- .setAwaitDuration(awaitDuration)
- .setSubscriptionExpressions(Collections.singletonMap(topic,
filterExpression))
- .build();
-// Try to receive message from server.
-final List<MessageView> messageViews = simpleConsumer.receive(1,
invisibleDuration);
-for (MessageView messageView : messageViews) {
- // Ack or change invisible time according to your needs.
- simpleConsumer.ack(messageView);
-}
-// Close it when you don't need the consumer any more.
-simpleConsumer.close();
-```
+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.
diff --git a/java/README.md b/java/example.md
similarity index 63%
copy from java/README.md
copy to java/example.md
index 206232d..2254903 100644
--- a/java/README.md
+++ b/java/example.md
@@ -1,39 +1,6 @@
-# RocketMQ Clients for Java
+# Code Example
-[](https://github.com/apache/rocketmq-clients/actions/workflows/java_build.yml)
-
-The java client implementation of [Apache
RocketMQ](https://rocketmq.apache.org/).
-
-## Prerequisites
-
-This project guarantees the same runtime compatibility with
[grpc-java](https://github.com/grpc/grpc-java).
-
-* Java 11 or higher is required to build this project.
-* The built artifacts can be used on Java 8 or higher.
-
-## Getting Started
-
-Firstly, add the dependency to your `pom.xml`, and replace the
`${rocketmq.version}` with the latest version.
-
-```xml
-<dependency>
- <groupId>org.apache.rocketmq</groupId>
- <artifactId>rocketmq-client-java</artifactId>
- <version>${rocketmq.version}</version>
-</dependency>
-```
-
-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.
-
-```xml
-<dependency>
- <groupId>org.apache.rocketmq</groupId>
- <artifactId>rocketmq-client-java-noshade</artifactId>
- <version>${rocketmq.version}</version>
-</dependency>
-```
+## Provider
There is a provider based on the Java SPI mechanism, the provider here can
derive specific implementations.
@@ -47,8 +14,7 @@ ClientConfiguration clientConfiguration =
ClientConfiguration.newBuilder()
.setCredentialProvider(staticSessionCredentialsProvider)
.build();
```
-
-### Producer
+## Producer
```java
// Build your message.
@@ -69,7 +35,7 @@ for (int i = 0; i < 1024; i++) {
producer.close();
```
-### PushConsumer
+## PushConsumer
```java
// Build your push consumer.
@@ -86,7 +52,7 @@ PushConsumer pushConsumer = provider.newPushConsumerBuilder()
pushConsumer.close();
```
-### SimpleConsumer
+## SimpleConsumer
```java
// Build your simple consumer.
