You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@eventmesh.apache.org by ch...@apache.org on 2022/05/30 03:11:19 UTC
[incubator-eventmesh] branch master updated: issue-579 Guide of EventMesh Java SDK
This is an automated email from the ASF dual-hosted git repository.
chenguangsheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-eventmesh.git
The following commit(s) were added to refs/heads/master by this push:
new 74960d51 issue-579 Guide of EventMesh Java SDK
new 9c3cb15a Merge pull request #899 from HoffmanZheng/issue-579
74960d51 is described below
commit 74960d518901db90e8058634ac2894f7fcc3f3fe
Author: Hoffman Zheng <ho...@goat.com>
AuthorDate: Sat May 28 19:47:56 2022 +0800
issue-579 Guide of EventMesh Java SDK
---
docs/en/sdk-java/03-tcp.md | 2 +-
docs/zh/sdk-java/01-introduction.md | 29 ++++++
docs/zh/sdk-java/02-http.md | 94 +++++++++++++++++++
docs/{en => zh}/sdk-java/03-tcp.md | 22 ++---
docs/zh/sdk-java/04-grpc.md | 174 ++++++++++++++++++++++++++++++++++++
docs/zh/sdk-java/_category_.json | 4 +
6 files changed, 313 insertions(+), 12 deletions(-)
diff --git a/docs/en/sdk-java/03-tcp.md b/docs/en/sdk-java/03-tcp.md
index be6f9e31..1643a41d 100644
--- a/docs/en/sdk-java/03-tcp.md
+++ b/docs/en/sdk-java/03-tcp.md
@@ -1,6 +1,6 @@
# TCP Protocol
-EventMesh SDK for Java implements the TCP producer and consumer of synchronous, asynchronous, and broadcast messages. Both the producer and consumer require an instance of `EventMeshTCPClientConfig` class that specifies the configuration of EventMesh gRPC client. The `host` and `port` fields should match the `eventmesh.properties` file of EventMesh runtime.
+EventMesh SDK for Java implements the TCP producer and consumer of synchronous, asynchronous, and broadcast messages. Both the producer and consumer require an instance of `EventMeshTCPClientConfig` class that specifies the configuration of EventMesh TCP client. The `host` and `port` fields should match the `eventmesh.properties` file of EventMesh runtime.
```java
import org.apache.eventmesh.client.tcp.conf.EventMeshTCPClientConfig;
diff --git a/docs/zh/sdk-java/01-introduction.md b/docs/zh/sdk-java/01-introduction.md
new file mode 100644
index 00000000..cb4b8764
--- /dev/null
+++ b/docs/zh/sdk-java/01-introduction.md
@@ -0,0 +1,29 @@
+# 安装
+
+[](https://maven-badges.herokuapp.com/maven-central/org.apache.eventmesh/eventmesh-sdk-java)
+
+EventMesh Java SDK 是在一个 Java 应用中集成 Eventmesh 所需的 Java 组件集合。SDK 支持使用 TCP、HTTP 和 gRPC 协议来发送和接收同步消息、异步消息和广播消息。SDK 实现了 EventMesh 消息、CloudEvents 和 OpenMessaging 形式。您可以在 [`eventmesh-example`](https://github.com/apache/incubator-eventmesh/tree/master/eventmesh-examples) 模块中查看示例项目。
+
+## Gradle
+
+使用 Gradle 安装 EventMesh Java SDK，您需要在模块的 `build.gradle` 文件的依赖块中将 `org.apache.eventmesh:eventmesh-sdk-java` 声明为 `implementation`。
+
+```groovy
+dependencies {
+ implementation 'org.apache.eventmesh:eventmesh-sdk-java:1.4.0'
+}
+```
+
+## Maven
+
+使用 Maven 安装 EventMesh Java SDK，您需要在项目 `pom.xml` 文件的依赖块中声明 `org.apache.eventmesh:eventmesh-sdk-java`。
+
+```xml
+<dependencies>
+ <dependency>
+ <groupId>org.apache.eventmesh</groupId>
+ <artifactId>eventmesh-sdk-java</artifactId>
+ <version>1.4.0</version>
+ </dependency>
+</dependencies>
+```
\ No newline at end of file
diff --git a/docs/zh/sdk-java/02-http.md b/docs/zh/sdk-java/02-http.md
new file mode 100644
index 00000000..32182fea
--- /dev/null
+++ b/docs/zh/sdk-java/02-http.md
@@ -0,0 +1,94 @@
+# HTTP 协议
+
+EventMesh Java SDK 实现了 HTTP 异步消息的生产者和消费者。二者都需要一个 `EventMeshHttpClientConfig` 类实例来指定 EventMesh HTTP 客户端的配置信息。其中的 `liteEventMeshAddr`、`userName` 和 `password` 字段需要和 EventMesh runtime `eventmesh.properties` 文件中的相匹配。
+
+```java
+import org.apache.eventmesh.client.http.conf.EventMeshHttpClientConfig;
+import org.apache.eventmesh.common.utils.IPUtils;
+import org.apache.eventmesh.common.utils.ThreadUtils;
+
+public class HTTP {
+ public static void main(String[] args) throws Exception {
+ EventMeshHttpClientConfig eventMeshClientConfig = EventMeshHttpClientConfig.builder()
+ .liteEventMeshAddr("localhost:10105")
+ .producerGroup("TEST_PRODUCER_GROUP")
+ .env("env")
+ .idc("idc")
+ .ip(IPUtils.getLocalAddress())
+ .sys("1234")
+ .pid(String.valueOf(ThreadUtils.getPID()))
+ .userName("eventmesh")
+ .password("password")
+ .build();
+ /* ... */
+ }
+}
+```
+
+## HTTP 消费者
+
+类 `EventMeshHttpConsumer` 实现了 `heartbeat`、`subscribe` 和 `unsubscribe` 方法。`subscribe` 方法接收一个 `SubscriptionItem` 对象的列表，其中定义了要订阅的话题和回调的 URL 地址。
+
+```java
+import org.apache.eventmesh.client.http.consumer.EventMeshHttpConsumer;
+import org.apache.eventmesh.common.protocol.SubscriptionItem;
+import org.apache.eventmesh.common.protocol.SubscriptionMode;
+import org.apache.eventmesh.common.protocol.SubscriptionType;
+import com.google.common.collect.Lists;
+
+public class HTTP {
+ final String url = "http://localhost:8080/callback";
+ final List<SubscriptionItem> topicList = Lists.newArrayList(
+ new SubscriptionItem("eventmesh-async-topic", SubscriptionMode.CLUSTERING, SubscriptionType.ASYNC)
+ );
+
+ public static void main(String[] args) throws Exception {
+ /* ... */
+ eventMeshHttpConsumer = new EventMeshHttpConsumer(eventMeshClientConfig);
+ eventMeshHttpConsumer.heartBeat(topicList, url);
+ eventMeshHttpConsumer.subscribe(topicList, url);
+ /* ... */
+ eventMeshHttpConsumer.unsubscribe(topicList, url);
+ }
+}
+```
+
+EventMesh runtime 将发送一个包含 [CloudEvents 格式](https://github.com/cloudevents/spec) 信息的 POST 请求到这个回调的 URL 地址。类 [SubController.java](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-examples/src/main/java/org/apache/eventmesh/http/demo/sub/controller/SubController.java) 实现了 Spring Boot controller，它将接收并解析回调信息。
+
+## HTTP 生产者
+
+类 `EventMeshHttpProducer` 实现了 `publish` 方法。`publish` 方法接收将被发布的消息和一个可选的 timeout 值。消息应是下列类的一个实例：
+
+- `org.apache.eventmesh.common.EventMeshMessage`
+- `io.cloudevents.CloudEvent`
+- `io.openmessaging.api.Message`
+
+```java
+import org.apache.eventmesh.client.http.producer.EventMeshHttpProducer;
+import org.apache.eventmesh.client.tcp.common.EventMeshCommon;
+import org.apache.eventmesh.common.Constants;
+import org.apache.eventmesh.common.utils.JsonUtils;
+
+import io.cloudevents.CloudEvent;
+import io.cloudevents.core.builder.CloudEventBuilder;
+
+public class HTTP {
+ public static void main(String[] args) throws Exception {
+ /* ... */
+ EventMeshHttpProducer eventMeshHttpProducer = new EventMeshHttpProducer(eventMeshClientConfig);
+ Map<String, String> content = new HashMap<>();
+ content.put("content", "testAsyncMessage");
+
+ CloudEvent event = CloudEventBuilder.v1()
+ .withId(UUID.randomUUID().toString())
+ .withSubject("eventmesh-async-topic")
+ .withSource(URI.create("/"))
+ .withDataContentType("application/cloudevents+json")
+ .withType(EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME)
+ .withData(JsonUtils.serialize(content).getBytes(StandardCharsets.UTF_8))
+ .withExtension(Constants.EVENTMESH_MESSAGE_CONST_TTL, String.valueOf(4 * 1000))
+ .build();
+ eventMeshHttpProducer.publish(event);
+ }
+}
+```
\ No newline at end of file
diff --git a/docs/en/sdk-java/03-tcp.md b/docs/zh/sdk-java/03-tcp.md
similarity index 68%
copy from docs/en/sdk-java/03-tcp.md
copy to docs/zh/sdk-java/03-tcp.md
index be6f9e31..54f5eca5 100644
--- a/docs/en/sdk-java/03-tcp.md
+++ b/docs/zh/sdk-java/03-tcp.md
@@ -1,6 +1,6 @@
-# TCP Protocol
+# TCP 协议
-EventMesh SDK for Java implements the TCP producer and consumer of synchronous, asynchronous, and broadcast messages. Both the producer and consumer require an instance of `EventMeshTCPClientConfig` class that specifies the configuration of EventMesh gRPC client. The `host` and `port` fields should match the `eventmesh.properties` file of EventMesh runtime.
+EventMesh Java SDK 实现了同步、异步和广播 TCP 消息的生产者和消费者。 二者都需要一个 `EventMeshHttpClientConfig` 类实例来指定 EventMesh TCP 客户端的配置信息。其中的 `host` 和 `port` 字段需要和 EventMesh runtime `eventmesh.properties` 文件中的相匹配。
```java
import org.apache.eventmesh.client.tcp.conf.EventMeshTCPClientConfig;
@@ -19,9 +19,9 @@ public class AsyncSubscribe implements ReceiveMsgHook<CloudEvent> {
}
```
-## TCP Consumer
+## TCP 消费者
-The consumer should implement the `ReceiveMsgHook` class, which is defined in [`ReceiveMsgHook.java`](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-sdk-java/src/main/java/org/apache/eventmesh/client/tcp/common/ReceiveMsgHook.java).
+消费者应该实现 `ReceiveMsgHook` 类，其被定义在 [ReceiveMsgHook.java](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-sdk-java/src/main/java/org/apache/eventmesh/client/tcp/common/ReceiveMsgHook.java)。
```java
public interface ReceiveMsgHook<ProtocolMessage> {
@@ -29,7 +29,7 @@ public interface ReceiveMsgHook<ProtocolMessage> {
}
```
-The `EventMeshTCPClient` class implements the `subscribe` method. The `subscribe` method accepts the topic, the `SubscriptionMode`, and the `SubscriptionType`. The `handle` method will be invoked when the consumer receives a message from the topic it subscribes. If the `SubscriptionType` is `SYNC`, the return value of `handle` will be sent back to the producer.
+类 `EventMeshTCPClient` 实现了 `subscribe` 方法。该方法接收话题、`SubscriptionMode` 和 `SubscriptionType`。`handle` 方法将会在消费者从订阅的话题中收到消息时被调用。如果 `SubscriptionType` 是 `SYNC`，`handle` 的返回值将被发送回生产者。
```java
import org.apache.eventmesh.client.tcp.EventMeshTCPClient;
@@ -68,11 +68,11 @@ public class TCPConsumer implements ReceiveMsgHook<CloudEvent> {
}
```
-## TCP Producer
+## TCP 生产者
-### Asynchronous Producer
+### 异步生产者
-The `EventMeshTCPClient` class implements the `publish` method. The `publish` method accepts the message to be published and an optional timeout value and returns the response message from the consumer.
+类 `EventMeshTCPClient` 实现了 `public` 方法。该方法接收将被发布的消息和一个可选的 timeout 值，并返回来自消费者的响应消息。
```java
/* ... */
@@ -91,9 +91,9 @@ CloudEvent event = CloudEventBuilder.v1()
client.publish(event, 1000);
```
-### Synchronous Producer
+### 同步生产者
-The `EventMeshTCPClient` class implements the `rr` method. The `rr` method accepts the message to be published and an optional timeout value and returns the response message from the consumer.
+类 `EventMeshTCPClient` 实现了 `rr` 方法。该方法接收将被发布的消息和一个可选的 timeout 值，并返回来自消费者的响应消息。
```java
/* ... */
@@ -115,4 +115,4 @@ CloudEvent replyEvent = EventFormatProvider
.getInstance()
.resolveFormat(JsonFormat.CONTENT_TYPE)
.deserialize(response.getBody().toString().getBytes(StandardCharsets.UTF_8));
-```
+```
\ No newline at end of file
diff --git a/docs/zh/sdk-java/04-grpc.md b/docs/zh/sdk-java/04-grpc.md
new file mode 100644
index 00000000..b0781870
--- /dev/null
+++ b/docs/zh/sdk-java/04-grpc.md
@@ -0,0 +1,174 @@
+# gRPC 协议
+
+EventMesh Java SDK 实现了 gRPC 同步、异步和广播消息的生产者和消费者。二者都需要一个 `EventMeshHttpClientConfig` 类实例来指定 EventMesh gRPC 客户端的配置信息。其中的 `liteEventMeshAddr`、`userName` 和 `password` 字段需要和 EventMesh runtime `eventmesh.properties` 文件中的相匹配。
+
+```java
+import org.apache.eventmesh.client.grpc.config.EventMeshGrpcClientConfig;
+import org.apache.eventmesh.client.grpc.consumer.ReceiveMsgHook;
+import io.cloudevents.CloudEvent;
+
+public class CloudEventsAsyncSubscribe implements ReceiveMsgHook<CloudEvent> {
+ public static void main(String[] args) throws InterruptedException {
+ EventMeshGrpcClientConfig eventMeshClientConfig = EventMeshGrpcClientConfig.builder()
+ .serverAddr("localhost")
+ .serverPort(10205)
+ .consumerGroup(ExampleConstants.DEFAULT_EVENTMESH_TEST_CONSUMER_GROUP)
+ .env("env").idc("idc")
+ .sys("1234").build();
+ /* ... */
+ }
+}
+```
+
+## gRPC 消费者
+
+### 流消费者
+
+EventMesh runtime 会将来自生产者的信息作为一系列事件流向流消费者发送。消费者应实现 `ReceiveHook` 类，其被定义在 [ReceiveMsgHook.java](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-sdk-java/src/main/java/org/apache/eventmesh/client/grpc/consumer/ReceiveMsgHook.java)。
+
+```java
+public interface ReceiveMsgHook<T> {
+ Optional<T> handle(T msg) throws Throwable;
+ String getProtocolType();
+}
+```
+
+类 `EventMeshGrpcConsumer` 实现了 `registerListener`、`subscribe` 和 `unsubscribe` 方法。`subscribe` 方法接收一个 `SubscriptionItem` 对象的列表，其中定义了要订阅的话题。`registerListener` 接收一个实现了 `ReceiveMsgHook` 的实例。`handle` 方法将会在消费者收到订阅的主题消息时被调用。如果 `SubscriptionType` 是 `SYNC`，`handle` 的返回值将被发送回生产者。
+
+```java
+import org.apache.eventmesh.client.grpc.consumer.EventMeshGrpcConsumer;
+import org.apache.eventmesh.client.grpc.consumer.ReceiveMsgHook;
+import org.apache.eventmesh.client.tcp.common.EventMeshCommon;
+import org.apache.eventmesh.common.protocol.SubscriptionItem;
+import org.apache.eventmesh.common.protocol.SubscriptionMode;
+import org.apache.eventmesh.common.protocol.SubscriptionType;
+import io.cloudevents.CloudEvent;
+
+public class CloudEventsAsyncSubscribe implements ReceiveMsgHook<CloudEvent> {
+ public static CloudEventsAsyncSubscribe handler = new CloudEventsAsyncSubscribe();
+ public static void main(String[] args) throws InterruptedException {
+ /* ... */
+ SubscriptionItem subscriptionItem = new SubscriptionItem(
+ "eventmesh-async-topic",
+ SubscriptionMode.CLUSTERING,
+ SubscriptionType.ASYNC
+ );
+ EventMeshGrpcConsumer eventMeshGrpcConsumer = new EventMeshGrpcConsumer(eventMeshClientConfig);
+
+ eventMeshGrpcConsumer.init();
+ eventMeshGrpcConsumer.registerListener(handler);
+ eventMeshGrpcConsumer.subscribe(Collections.singletonList(subscriptionItem));
+ /* ... */
+ eventMeshGrpcConsumer.unsubscribe(Collections.singletonList(subscriptionItem));
+ }
+
+ @Override
+ public Optional<CloudEvent> handle(CloudEvent message) {
+ log.info("Messaged received: {}", message);
+ return Optional.empty();
+ }
+
+ @Override
+ public String getProtocolType() {
+ return EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME;
+ }
+}
+```
+
+### Webhook 消费者
+
+类 `EventMeshGrpcConsumer` 的 `subscribe` 方法接收一个 `SubscriptionItem` 对象的列表，其中定义了要订阅的主题和一个可选的 timeout 值。如果提供了回调 URL，EventMesh runtime 将向回调 URL 地址发送一个包含 [CloudEvents 格式](https://github.com/cloudevents/spec) 消息的 POST 请求。[SubController.java](https://github.com/apache/incubator-eventmesh/blob/master/eventmesh-examples/src/main/java/org/apache/eventmesh/grpc/sub/app/controller/SubController.java) 实现了一个接收并解析回调信息的 Spring Boot controller。
+
+```java
+import org.apache.eventmesh.client.grpc.consumer.EventMeshGrpcConsumer;
+import org.apache.eventmesh.client.grpc.consumer.ReceiveMsgHook;
+import org.apache.eventmesh.client.tcp.common.EventMeshCommon;
+import org.apache.eventmesh.common.protocol.SubscriptionItem;
+import org.apache.eventmesh.common.protocol.SubscriptionMode;
+import org.apache.eventmesh.common.protocol.SubscriptionType;
+
+@Component
+public class SubService implements InitializingBean {
+ final String url = "http://localhost:8080/callback";
+
+ public void afterPropertiesSet() throws Exception {
+ /* ... */
+ eventMeshGrpcConsumer = new EventMeshGrpcConsumer(eventMeshClientConfig);
+ eventMeshGrpcConsumer.init();
+
+ SubscriptionItem subscriptionItem = new SubscriptionItem(
+ "eventmesh-async-topic",
+ SubscriptionMode.CLUSTERING,
+ SubscriptionType.ASYNC
+ );
+
+ eventMeshGrpcConsumer.subscribe(Collections.singletonList(subscriptionItem), url);
+ /* ... */
+ eventMeshGrpcConsumer.unsubscribe(Collections.singletonList(subscriptionItem), url);
+ }
+}
+```
+
+## gRPC 生产者
+
+### 异步生产者
+
+类 `EventMeshGrpcProducer` 实现了 `publish` 方法。`publish` 方法接收将被发布的消息和一个可选的 timeout 值。消息应是下列类的一个实例：
+
+- `org.apache.eventmesh.common.EventMeshMessage`
+- `io.cloudevents.CloudEvent`
+
+```java
+/* ... */
+EventMeshGrpcProducer eventMeshGrpcProducer = new EventMeshGrpcProducer(eventMeshClientConfig);
+eventMeshGrpcProducer.init();
+
+Map<String, String> content = new HashMap<>();
+content.put("content", "testAsyncMessage");
+
+CloudEvent event = CloudEventBuilder.v1()
+ .withId(UUID.randomUUID().toString())
+ .withSubject(ExampleConstants.EVENTMESH_GRPC_ASYNC_TEST_TOPIC)
+ .withSource(URI.create("/"))
+ .withDataContentType(ExampleConstants.CLOUDEVENT_CONTENT_TYPE)
+ .withType(EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME)
+ .withData(JsonUtils.serialize(content).getBytes(StandardCharsets.UTF_8))
+ .withExtension(Constants.EVENTMESH_MESSAGE_CONST_TTL, String.valueOf(4 * 1000))
+ .build();
+eventMeshGrpcProducer.publish(event);
+```
+
+### 同步生产者
+
+类 `EventMeshGrpcProducer` 实现了 `requestReply` 方法。`requestReply` 方法接收将被发布的消息和一个可选的 timeout 值。方法会返回消费者返回的消息。消息应是下列类的一个实例：
+
+- `org.apache.eventmesh.common.EventMeshMessage`
+- `io.cloudevents.CloudEvent`
+
+### 批量生产者
+
+类 `EventMeshGrpcProducer` 重写了 `publish` 方法，该方法接收一个将被发布的消息列表和一个可选的 timeout 值。列表中的消息应是下列类的一个实例：
+
+- `org.apache.eventmesh.common.EventMeshMessage`
+- `io.cloudevents.CloudEvent`
+
+```java
+/* ... */
+List<CloudEvent> cloudEventList = new ArrayList<>();
+for (int i = 0; i < 5; i++) {
+ CloudEvent event = CloudEventBuilder.v1()
+ .withId(UUID.randomUUID().toString())
+ .withSubject(ExampleConstants.EVENTMESH_GRPC_ASYNC_TEST_TOPIC)
+ .withSource(URI.create("/"))
+ .withDataContentType(ExampleConstants.CLOUDEVENT_CONTENT_TYPE)
+ .withType(EventMeshCommon.CLOUD_EVENTS_PROTOCOL_NAME)
+ .withData(JsonUtils.serialize(content).getBytes(StandardCharsets.UTF_8))
+ .withExtension(Constants.EVENTMESH_MESSAGE_CONST_TTL, String.valueOf(4 * 1000))
+ .build();
+
+ cloudEventList.add(event);
+}
+
+eventMeshGrpcProducer.publish(cloudEventList);
+/* ... */
+```
\ No newline at end of file
diff --git a/docs/zh/sdk-java/_category_.json b/docs/zh/sdk-java/_category_.json
new file mode 100644
index 00000000..9d0a27c5
--- /dev/null
+++ b/docs/zh/sdk-java/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "EventMesh SDK for Java",
+ "collapsed": false
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@eventmesh.apache.org
For additional commands, e-mail: commits-help@eventmesh.apache.org