Update triple docs (#1371)
diff --git a/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/migration.md b/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/migration.md
new file mode 100644
index 0000000..84d2c2b
--- /dev/null
+++ b/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/migration.md
@@ -0,0 +1,84 @@
+---
+type: docs
+title: "Dubbo2 协议迁移"
+linkTitle: "Dubbo2 协议迁移"
+weight: 10
+---
+
+## Dubbo2 协议迁移流程
+
+Dubbo2 的用户使用 dubbo 协议 + 自定义序列化，如 hessian2 完成远程调用。
+
+而 Grpc 的默认仅支持 Protobuf 序列化，对于 Java 语言中的多参数以及方法重载也无法支持。
+
+Dubbo3的之初就有一条目标是完美兼容 Dubbo2，所以为了 Dubbo2 能够平滑升级， Dubbo 框架侧做了很多工作来保证升级的无感，目前默认的序列化和 Dubbo2 保持一致为`hessian2`。
+
+所以，如果决定要升级到 Dubbo3 的 `Triple` 协议，只需要修改配置中的协议名称为 `tri` (注意: 不是triple)即可。
+
+接下来我们我们以一个使用 Dubbo2 协议的[工程](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration) 来举例，如何一步一步安全的升级。
+
+1. 仅使用 `dubbo` 协议启动 `provider` 和 `consumer`，并完成调用。
+2. 使用 `dubbo` 和 `tri` 协议 启动`provider`，以 `dubbo` 协议启动 `consumer`，并完成调用。
+3. 仅使用 `tri` 协议 启动 `provider`和 `consumer`，并完成调用。
+
+### 定义服务
+
+1. 定义接口
+```java
+public interface IWrapperGreeter {
+
+ //...
+
+ /**
+ * 这是一个普通接口，没有使用 pb 序列化
+ */
+ String sayHello(String request);
+
+}
+```
+
+2. 实现类如下
+```java
+public class IGreeter2Impl implements IWrapperGreeter {
+
+ @Override
+ public String sayHello(String request) {
+ return "hello," + request;
+ }
+}
+```
+
+### 仅使用 dubbo 协议
+
+为保证兼容性，我们先将部分 provider 升级到 `dubbo3` 版本并使用 `dubbo` 协议。
+
+使用 `dubbo` 协议启动一个 [`Provider`](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboProvider.java) 和 [`Consumer`](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationDubboConsumer.java) ,完成调用，输出如下:
+
+
+### 同时使用 dubbo 和 triple 协议
+
+对于线上服务的升级，不可能一蹴而就同时完成 provider 和 consumer 升级, 需要按步操作，保证业务稳定。
+第二步, provider 提供双协议的方式同时支持 dubbo + tri 两种协议的客户端。
+
+结构如图所示:
+
+
+> 按照推荐升级步骤，provider 已经支持了tri协议，所以 dubbo3的 consumer 可以直接使用 tri 协议
+
+使用`dubbo`协议和`triple`协议启动[`Provider`](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothProvider.java)和[`Consumer`](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationBothConsumer.java),完成调用，输出如下:
+
+
+
+
+### 仅使用 triple 协议
+
+当所有的 consuemr 都升级至支持 `Triple` 协议的版本后，provider 可切换至仅使用 `Triple` 协议启动
+
+结构如图所示:
+
+
+[Provider](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriProvider.java)
+和 [Consumer](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/migration/ApiMigrationTriConsumer.java) 完成调用，输出如下:
+
+
+
diff --git a/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/overview.md b/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/overview.md
index 64fa02b..d3200d9 100644
--- a/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/overview.md
+++ b/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/overview.md
@@ -22,3 +22,18 @@
需要新增对接 Grpc 服务的 Dubbo 用户，可以直接使用 Triple 协议来实现打通，不需要单独引入 grpc client 来完成，不仅能保留已有的 Dubbo 易用性，也能降低程序的复杂度和开发运维成本，不需要额外进行适配和开发即可接入现有生态。
对于需要网关接入的 Dubbo 用户，Triple 协议提供了更加原生的方式，让网关开发或者使用开源的 grpc 网关组件更加简单。网关可以选择不解析 payload ，在性能上也有很大提高。在使用 Dubbo 协议时，语言相关的序列化方式是网关的一个很大痛点，而传统的 HTTP 转 Dubbo 的方式对于跨语言序列化几乎是无能为力的。同时，由于 Triple 的协议元数据都存储在请求头中，网关可以轻松的实现定制需求，如路由和限流等功能。
+
+
+### 常见问题
+
+1. protobuf 类找不到
+
+由于 Triple 协议底层需要依赖 protobuf 协议进行传输，即使定义的服务接口不使用 protobuf 也需要在环境中引入 protobuf 的依赖。
+
+```xml
+ <dependency>
+ <groupId>com.google.protobuf</groupId>
+ <artifactId>protobuf-java</artifactId>
+ <version>3.19.4</version>
+ </dependency>
+```
\ No newline at end of file
diff --git a/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/pojo.md b/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/pojo.md
index 75ded6b..f5608f5 100644
--- a/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/pojo.md
+++ b/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/pojo.md
@@ -6,7 +6,40 @@
---
这篇教程会通过从零构建一个简单的工程来演示如何基于 POJO 方式使用 Dubbo Triple, 在应用不改变已有接口定义的同时升级到 Triple 协议。
-POJO on Triple 原理请参考POJO on Triple(TBD)
+
+
+### 实现原理
+
+通过上面介绍的升级过程，我们可以很简单的通过修改协议类型来完成升级。框架是怎么帮我们做到这些的呢？
+
+通过对 `Triple` 协议的介绍，我们知道Dubbo3的 `Triple` 的数据类型是 `protobuf` 对象，那为什么非 `protobuf` 的 java 对象也可以被正常传输呢。
+
+这里 Dubbo3 使用了一个巧妙的设计，首先判断参数类型是否为 `protobuf` 对象，如果不是。用一个 `protobuf` 对象将 `request` 和 `response` 进行 wrapper，这样就屏蔽了其他各种序列化带来的复杂度。在 `wrapper` 对象内部声明序列化类型，来支持序列化的扩展。
+
+wrapper 的`protobuf`的 IDL如下:
+```proto
+syntax = "proto3";
+
+package org.apache.dubbo.triple;
+
+message TripleRequestWrapper {
+ // hessian4
+ // json
+ string serializeType = 1;
+ repeated bytes args = 2;
+ repeated string argTypes = 3;
+}
+
+message TripleResponseWrapper {
+ string serializeType = 1;
+ bytes data = 2;
+ string type = 3;
+}
+```
+
+对于请求，使用`TripleRequestWrapper`进行包装，对于响应使用`TripleResponseWrapper`进行包装。
+
+> 对于请求参数，可以看到 args 被`repeated`修饰，这是因为需要支持 java 方法的多个参数。当然，序列化只能是一种。序列化的实现沿用 Dubbo2 实现的 spi
### 前置条件
- [JDK](https://jdk.java.net/) 版本 >= 8
diff --git a/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/streaming.md b/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/streaming.md
new file mode 100644
index 0000000..8568ec2
--- /dev/null
+++ b/content/zh/docs3-v2/java-sdk/reference-manual/protocol/triple/streaming.md
@@ -0,0 +1,154 @@
+---
+type: docs
+title: "Streaming 通信"
+linkTitle: "Streaming 通信"
+weight: 10
+---
+
+## 开启 Triple 新特性 —— Stream (流)
+Stream 是 Dubbo3 新提供的一种调用类型，在以下场景时建议使用流的方式:
+
+- 接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送
+- 流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的
+- 推送类场景，多个消息在同一个调用的上下文中被发送和处理
+
+Stream 分为以下三种:
+- SERVER_STREAM(服务端流)
+ 
+- CLIENT_STREAM(客户端流)
+ 
+- BIDIRECTIONAL_STREAM(双向流)
+ 
+
+> 由于 `java` 语言的限制，BIDIRECTIONAL_STREAM 和 CLIENT_STREAM 的实现是一样的。
+
+在 Dubbo3 中，流式接口以 `SteamObserver` 声明和使用，用户可以通过使用和实现这个接口来发送和处理流的数据、异常和结束。
+
+> 对于 Dubbo2 用户来说，可能会对StreamObserver感到陌生，这是Dubbo3定义的一种流类型，Dubbo2 中并不存在 Stream 的类型，所以对于迁移场景没有任何影响。
+
+流的语义保证
+- 提供消息边界，可以方便地对消息单独处理
+- 严格有序，发送端的顺序和接收端顺序一致
+- 全双工，发送不需要等待
+- 支持取消和超时
+
+### 非 PB 序列化的流
+1. api
+```java
+public interface IWrapperGreeter {
+
+ StreamObserver<String> sayHelloStream(StreamObserver<String> response);
+
+ void sayHelloServerStream(String request, StreamObserver<String> response);
+}
+```
+
+> Stream 方法的方法入参和返回值是严格约定的，为防止写错而导致问题，Dubbo3 框架侧做了对参数的检查, 如果出错则会抛出异常。
+> 对于 `双向流(BIDIRECTIONAL_STREAM)`, 需要注意参数中的 `StreamObserver` 是响应流，返回参数中的 `StreamObserver` 为请求流。
+
+2. 实现类
+```java
+public class WrapGreeterImpl implements WrapGreeter {
+
+ //...
+
+ @Override
+ public StreamObserver<String> sayHelloStream(StreamObserver<String> response) {
+ return new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ response.onNext("hello,"+data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ response.onCompleted();
+ }
+ };
+ }
+
+ @Override
+ public void sayHelloServerStream(String request, StreamObserver<String> response) {
+ for (int i = 0; i < 10; i++) {
+ response.onNext("hello," + request);
+ }
+ response.onCompleted();
+ }
+}
+```
+
+3. 调用方式
+```java
+delegate.sayHelloServerStream("server stream", new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ }
+});
+
+
+StreamObserver<String> request = delegate.sayHelloStream(new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ }
+});
+for (int i = 0; i < n; i++) {
+ request.onNext("stream request" + i);
+}
+request.onCompleted();
+```
+
+## 使用 Protobuf 序列化的流
+
+对于 `Protobuf` 序列化方式，推荐编写 `IDL` 使用 `compiler` 插件进行编译生成。生成的代码大致如下:
+```java
+public interface PbGreeter {
+
+ static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
+ static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
+
+ static final boolean inited = PbGreeterDubbo.init();
+
+ //...
+
+ void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
+
+ org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterRequest> greetStream(org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
+}
+```
+
+### 流的实现原理
+
+`Triple`协议的流模式是怎么支持的呢？
+
+- 从协议层来说，`Triple` 是建立在 `HTTP2` 基础上的，所以直接拥有所有 `HTTP2` 的能力，故拥有了分 `stream` 和全双工的能力。
+
+- 框架层来说，`StreamObserver` 作为流的接口提供给用户，用于入参和出参提供流式处理。框架在收发 stream data 时进行相应的接口调用, 从而保证流的生命周期完整。
diff --git a/content/zh/overview/tasks/triple/_index.md b/content/zh/overview/tasks/triple/_index.md
index f52021d..43f1c11 100755
--- a/content/zh/overview/tasks/triple/_index.md
+++ b/content/zh/overview/tasks/triple/_index.md
@@ -26,9 +26,9 @@
<div class="h-100 card shadow" href="#">
<div class="card-body">
<h4 class="card-title">
- <a href='{{< relref "./wrap/" >}}'>Wrapped 序列化兼容模式</a>
+ <a href='{{< relref "./wrap/" >}}'>Pojo 序列化兼容模式</a>
</h4>
- <p>Wrapped 序列化兼容模式</p>
+ <p>Pojo 序列化兼容模式</p>
</div>
</div>
</div>
@@ -42,16 +42,6 @@
</div>
</div>
</div>
- <div class="col-sm col-md-6 mb-4 mb-md-0">
- <div class="h-100 card shadow" href="#">
- <div class="card-body">
- <h4 class="card-title">
- <a href='{{< relref "./grpc/" >}}'>Triple 与 gRPC 通信</a>
- </h4>
- <p>Triple 与 gRPC 通信</p>
- </div>
- </div>
- </div>
</div>
<hr>
</div>
diff --git a/content/zh/overview/tasks/triple/grpc.md b/content/zh/overview/tasks/triple/grpc.md
deleted file mode 100644
index cecc662..0000000
--- a/content/zh/overview/tasks/triple/grpc.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-type: docs
-title: "Triple 与 gRPC 通信"
-linkTitle: "Triple 与 gRPC 通信"
-weight: 4
-description: ""
----
-
-TBD
\ No newline at end of file
diff --git a/content/zh/overview/tasks/triple/idl.md b/content/zh/overview/tasks/triple/idl.md
index 4936e3a..a1a38a8 100644
--- a/content/zh/overview/tasks/triple/idl.md
+++ b/content/zh/overview/tasks/triple/idl.md
@@ -11,6 +11,8 @@
下面从定义服务、编译服务、配置并加载服务三个方面说明如何快速的开发 Dubbo 服务。
+具体用例可以参考：[dubbo-samples-triple/stub](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/stub);
+
## 定义服务
Dubbo3 推荐使用 IDL 定义跨语言服务，如您更习惯使用特定语言的服务定义方式，请移步[多语言 SDK](/zh/docs3-v2/)查看。
@@ -51,6 +53,42 @@
根据当前采用的语言，配置相应的 Protobuf 插件，编译后将生产语言相关的服务定义 stub。
### Java
+
+Java compiler 配置参考：
+```xml
+<plugin>
+ <groupId>org.xolstice.maven.plugins</groupId>
+ <artifactId>protobuf-maven-plugin</artifactId>
+ <version>0.6.1</version>
+ <configuration>
+ <protocArtifact>com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier}
+ </protocArtifact>
+ <pluginId>grpc-java</pluginId>
+ <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}
+ </pluginArtifact>
+ <protocPlugins>
+ <protocPlugin>
+ <id>dubbo</id>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-compiler</artifactId>
+ <version>3.0.10</version>
+ <mainClass>org.apache.dubbo.gen.tri.Dubbo3TripleGenerator</mainClass>
+ </protocPlugin>
+ </protocPlugins>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>compile</goal>
+ <goal>test-compile</goal>
+ <goal>compile-custom</goal>
+ <goal>test-compile-custom</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+```
+
Java 语言生成的 stub 如下，核心是一个接口定义
```java
@javax.annotation.Generated(
@@ -114,9 +152,9 @@
public HelloReply sayHello(HelloRequest request) {
logger.info("Hello " + request.getName() + ", request from consumer: " + RpcContext.getContext().getRemoteAddress());
return HelloReply.newBuilder()
- .setMessage("Hello " + request.getName() + ", response from provider: "
- + RpcContext.getContext().getLocalAddress())
- .build();
+ .setMessage("Hello " + request.getName() + ", response from provider: "
+ + RpcContext.getContext().getLocalAddress())
+ .build();
}
@Override
diff --git a/content/zh/overview/tasks/triple/streaming.md b/content/zh/overview/tasks/triple/streaming.md
index 93d4c1a..f6da6da 100644
--- a/content/zh/overview/tasks/triple/streaming.md
+++ b/content/zh/overview/tasks/triple/streaming.md
@@ -6,4 +6,292 @@
description: ""
---
-TBD
\ No newline at end of file
+具体用例可以参考：[dubbo-samples-triple/pojo](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/pojo);
+
+## 开启 Triple 新特性 —— Stream (流)
+Stream 是 Dubbo3 新提供的一种调用类型，在以下场景时建议使用流的方式:
+
+- 接口需要发送大量数据，这些数据无法被放在一个 RPC 的请求或响应中，需要分批发送，但应用层如果按照传统的多次 RPC 方式无法解决顺序和性能的问题，如果需要保证有序，则只能串行发送
+- 流式场景，数据需要按照发送顺序处理, 数据本身是没有确定边界的
+- 推送类场景，多个消息在同一个调用的上下文中被发送和处理
+
+Stream 分为以下三种:
+- SERVER_STREAM(服务端流)
+ 
+- CLIENT_STREAM(客户端流)
+ 
+- BIDIRECTIONAL_STREAM(双向流)
+ 
+
+> 由于 `java` 语言的限制，BIDIRECTIONAL_STREAM 和 CLIENT_STREAM 的实现是一样的。
+
+在 Dubbo3 中，流式接口以 `SteamObserver` 声明和使用，用户可以通过使用和实现这个接口来发送和处理流的数据、异常和结束。
+
+> 对于 Dubbo2 用户来说，可能会对StreamObserver感到陌生，这是Dubbo3定义的一种流类型，Dubbo2 中并不存在 Stream 的类型，所以对于迁移场景没有任何影响。
+
+流的语义保证
+- 提供消息边界，可以方便地对消息单独处理
+- 严格有序，发送端的顺序和接收端顺序一致
+- 全双工，发送不需要等待
+- 支持取消和超时
+
+### 非 PB 序列化的流
+1. api
+```java
+public interface IWrapperGreeter {
+
+ StreamObserver<String> sayHelloStream(StreamObserver<String> response);
+
+ void sayHelloServerStream(String request, StreamObserver<String> response);
+}
+```
+
+> Stream 方法的方法入参和返回值是严格约定的，为防止写错而导致问题，Dubbo3 框架侧做了对参数的检查, 如果出错则会抛出异常。
+> 对于 `双向流(BIDIRECTIONAL_STREAM)`, 需要注意参数中的 `StreamObserver` 是响应流，返回参数中的 `StreamObserver` 为请求流。
+
+2. 实现类
+```java
+public class WrapGreeterImpl implements WrapGreeter {
+
+ //...
+
+ @Override
+ public StreamObserver<String> sayHelloStream(StreamObserver<String> response) {
+ return new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ response.onNext("hello,"+data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ response.onCompleted();
+ }
+ };
+ }
+
+ @Override
+ public void sayHelloServerStream(String request, StreamObserver<String> response) {
+ for (int i = 0; i < 10; i++) {
+ response.onNext("hello," + request);
+ }
+ response.onCompleted();
+ }
+}
+```
+
+3. 调用方式
+```java
+delegate.sayHelloServerStream("server stream", new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ }
+});
+
+
+StreamObserver<String> request = delegate.sayHelloStream(new StreamObserver<String>() {
+ @Override
+ public void onNext(String data) {
+ System.out.println(data);
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ throwable.printStackTrace();
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ }
+});
+for (int i = 0; i < n; i++) {
+ request.onNext("stream request" + i);
+}
+request.onCompleted();
+```
+
+## 使用 Protobuf 序列化的流
+
+对于 `Protobuf` 序列化方式，推荐编写 `IDL` 使用 `compiler` 插件进行编译生成。生成的代码大致如下:
+```java
+public interface PbGreeter {
+
+ static final String JAVA_SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
+ static final String SERVICE_NAME = "org.apache.dubbo.sample.tri.PbGreeter";
+
+ static final boolean inited = PbGreeterDubbo.init();
+
+ //...
+
+ void greetServerStream(org.apache.dubbo.sample.tri.GreeterRequest request, org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
+
+ org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterRequest> greetStream(org.apache.dubbo.common.stream.StreamObserver<org.apache.dubbo.sample.tri.GreeterReply> responseObserver);
+}
+```
+
+### 完整用例
+
+1. 编写 Java 接口
+ ```java
+ import org.apache.dubbo.common.stream.StreamObserver;
+ import org.apache.dubbo.hello.HelloReply;
+ import org.apache.dubbo.hello.HelloRequest;
+
+ public interface IGreeter {
+ /**
+ * <pre>
+ * Sends greeting by stream
+ * </pre>
+ */
+ StreamObserver<HelloRequest> sayHello(StreamObserver<HelloReply> replyObserver);
+
+ }
+ ```
+
+2. 编写实现类
+ ```java
+ public class IStreamGreeterImpl implements IStreamGreeter {
+
+ @Override
+ public StreamObserver<HelloRequest> sayHello(StreamObserver<HelloReply> replyObserver) {
+
+ return new StreamObserver<HelloRequest>() {
+ private List<HelloReply> replyList = new ArrayList<>();
+
+ @Override
+ public void onNext(HelloRequest helloRequest) {
+ System.out.println("onNext receive request name:" + helloRequest.getName());
+ replyList.add(HelloReply.newBuilder()
+ .setMessage("receive name:" + helloRequest.getName())
+ .build());
+ }
+
+ @Override
+ public void onError(Throwable cause) {
+ System.out.println("onError");
+ replyObserver.onError(cause);
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onComplete receive request size:" + replyList.size());
+ for (HelloReply reply : replyList) {
+ replyObserver.onNext(reply);
+ }
+ replyObserver.onCompleted();
+ }
+ };
+ }
+ }
+ ```
+
+3. 创建 Provider
+
+ ```java
+ public class StreamProvider {
+ public static void main(String[] args) throws InterruptedException {
+ ServiceConfig<IStreamGreeter> service = new ServiceConfig<>();
+ service.setInterface(IStreamGreeter.class);
+ service.setRef(new IStreamGreeterImpl());
+ service.setProtocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051));
+ service.setApplication(new ApplicationConfig("stream-provider"));
+ service.setRegistry(new RegistryConfig("zookeeper://127.0.0.1:2181"));
+ service.export();
+ System.out.println("dubbo service started");
+ new CountDownLatch(1).await();
+ }
+ }
+ ```
+
+4. 创建 Consumer
+
+ ```java
+ public class StreamConsumer {
+ public static void main(String[] args) throws InterruptedException, IOException {
+ ReferenceConfig<IStreamGreeter> ref = new ReferenceConfig<>();
+ ref.setInterface(IStreamGreeter.class);
+ ref.setCheck(false);
+ ref.setProtocol(CommonConstants.TRIPLE);
+ ref.setLazy(true);
+ ref.setTimeout(100000);
+ ref.setApplication(new ApplicationConfig("stream-consumer"));
+ ref.setRegistry(new RegistryConfig("zookeeper://mse-6e9fda00-p.zk.mse.aliyuncs.com:2181"));
+ final IStreamGreeter iStreamGreeter = ref.get();
+
+ System.out.println("dubbo ref started");
+ try {
+
+ StreamObserver<HelloRequest> streamObserver = iStreamGreeter.sayHello(new StreamObserver<HelloReply>() {
+ @Override
+ public void onNext(HelloReply reply) {
+ System.out.println("onNext");
+ System.out.println(reply.getMessage());
+ }
+
+ @Override
+ public void onError(Throwable throwable) {
+ System.out.println("onError:" + throwable.getMessage());
+ }
+
+ @Override
+ public void onCompleted() {
+ System.out.println("onCompleted");
+ }
+ });
+
+ streamObserver.onNext(HelloRequest.newBuilder()
+ .setName("tony")
+ .build());
+
+ streamObserver.onNext(HelloRequest.newBuilder()
+ .setName("nick")
+ .build());
+
+ streamObserver.onCompleted();
+ } catch (Throwable t) {
+ t.printStackTrace();
+ }
+ System.in.read();
+ }
+ }
+ ```
+
+5. 运行 Provider 和 Consumer ,可以看到请求正常返回了
+ > onNext\
+ > receive name:tony\
+ > onNext\
+ > receive name:nick\
+ > onCompleted
+
+### 常见问题
+
+1. protobuf 类找不到
+
+由于 Triple 协议底层需要依赖 protobuf 协议进行传输，即使定义的服务接口不使用 protobuf 也需要在环境中引入 protobuf 的依赖。
+
+```xml
+ <dependency>
+ <groupId>com.google.protobuf</groupId>
+ <artifactId>protobuf-java</artifactId>
+ <version>3.19.4</version>
+ </dependency>
+```
\ No newline at end of file
diff --git a/content/zh/overview/tasks/triple/wrap.md b/content/zh/overview/tasks/triple/wrap.md
index 130a1f4..0dd8b51 100644
--- a/content/zh/overview/tasks/triple/wrap.md
+++ b/content/zh/overview/tasks/triple/wrap.md
@@ -1,9 +1,171 @@
---
type: docs
-title: "Wrapped 序列化兼容模式"
-linkTitle: "Wrapped 序列化兼容模式"
+title: "Pojo 序列化兼容模式"
+linkTitle: "Pojo 序列化兼容模式"
weight: 2
description: ""
---
-TBD
\ No newline at end of file
+这篇教程会通过从零构建一个简单的工程来演示如何基于 POJO 方式使用 Dubbo Triple, 在应用不改变已有接口定义的同时升级到 Triple 协议。**此模式下 Triple 使用方式与 Dubbo 协议一样。**
+
+具体用例可以参考：[dubbo-samples-triple/pojo](https://github.com/apache/dubbo-samples/tree/master/dubbo-samples-triple/src/main/java/org/apache/dubbo/sample/tri/pojo);
+
+### 前置条件
+- [JDK](https://jdk.java.net/) 版本 >= 8
+- 已安装 [Maven](https://maven.apache.org/)
+- 已安装并启动 [Zookeeper](https://zookeeper.apache.org/)
+
+### 创建工程
+1. 首先创建一个空的 maven 工程
+ ```
+ $ mvn archetype:generate \
+ -DgroupId=org.apache.dubbo \
+ -DartifactId=tri-pojo-demo \
+ -DarchetypeArtifactId=maven-archetype-quickstart \
+ -DarchetypeVersion=1.4 \
+ -DarchetypeGroupId=org.apache.maven.archetypes \
+ -Dversion=1.0-SNAPSHOT
+ ```
+2. 切换到工程目录
+ ```
+ $ cd tri-pojo-demo
+ ```
+3. 在 `pom.xml` 中设置 JDK 版本，添加 Dubbo 依赖和插件
+ ```xml
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <maven.compiler.source>1.8</maven.compiler.source>
+ <maven.compiler.target>1.8</maven.compiler.target>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.13</version>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo</artifactId>
+ <version>3.0.8</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-dependencies-zookeeper-curator5</artifactId>
+ <type>pom</type>
+ <version>3.0.8</version>
+ </dependency>
+ <dependency>
+ <groupId>com.google.protobuf</groupId>
+ <artifactId>protobuf-java</artifactId>
+ <version>3.19.4</version>
+ </dependency>
+ </dependencies>
+ ```
+4. 添加接口定义`src/main/java/org/apache/dubbo/Greeter.java`
+ ```java
+ package org.apache.dubbo;
+
+ public interface Greeter {
+ String sayHello(String name);
+ }
+ ```
+5. 添加服务端接口实现`src/main/java/org/apache/dubbo/GreeterImpl.java`
+ ```java
+ package org.apache.dubbo;
+
+ public class GreeterImpl implements Greeter {
+ @Override
+ public String sayHello(String name) {
+ return "Hello," + name + "!";
+ }
+ }
+ ```
+6. 添加服务端启动类 `src/main/java/org/apache/dubbo/MyDubboServer.java`
+ ```java
+ package org.apache.dubbo;
+
+ import org.apache.dubbo.common.constants.CommonConstants;
+ import org.apache.dubbo.config.ApplicationConfig;
+ import org.apache.dubbo.config.ProtocolConfig;
+ import org.apache.dubbo.config.RegistryConfig;
+ import org.apache.dubbo.config.ServiceConfig;
+ import org.apache.dubbo.config.bootstrap.DubboBootstrap;
+
+ import java.io.IOException;
+
+ public class MyDubboServer {
+
+ public static void main(String[] args) throws IOException {
+ ServiceConfig<Greeter> service = new ServiceConfig<>();
+ service.setInterface(Greeter.class);
+ service.setRef(new GreeterImpl());
+
+ DubboBootstrap bootstrap = DubboBootstrap.getInstance();
+ bootstrap.application(new ApplicationConfig("tri-pojo-server"))
+ .registry(new RegistryConfig("zookeeper://127.0.0.1:2181"))
+ .protocol(new ProtocolConfig(CommonConstants.TRIPLE, 50051))
+ .service(service)
+ .start();
+ System.out.println("Dubbo triple pojo server started");
+ System.in.read();
+ }
+ }
+ ```
+
+7. 添加客户端启动类`src/main/java/org/apache/dubbo/MyDubboClient.java`
+ ```java
+ package org.apache.dubbo;
+
+ import org.apache.dubbo.common.constants.CommonConstants;
+ import org.apache.dubbo.config.ApplicationConfig;
+ import org.apache.dubbo.config.ReferenceConfig;
+ import org.apache.dubbo.config.RegistryConfig;
+ import org.apache.dubbo.config.bootstrap.DubboBootstrap;
+
+ public class MyDubboClient {
+ public static void main(String[] args) {
+ DubboBootstrap bootstrap = DubboBootstrap.getInstance();
+ ReferenceConfig<Greeter> ref = new ReferenceConfig<>();
+ ref.setInterface(Greeter.class);
+ ref.setProtocol(CommonConstants.TRIPLE);
+ ref.setTimeout(3000);
+ bootstrap.application(new ApplicationConfig("tri-pojo-client"))
+ .registry(new RegistryConfig("zookeeper://127.0.0.1:2181"))
+ .reference(ref)
+ .start();
+
+ Greeter greeter = ref.get();
+ String reply = greeter.sayHello("pojo");
+ System.out.println("Received reply:" + reply);
+ }
+ }
+ ```
+8. 编译代码
+ ```
+ $ mvn clean install
+ ```
+9. 启动服务端
+ ```
+ $ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboServer"
+ Dubbo triple pojo server started
+ ```
+10. 打开新的终端，启动客户端
+ ```
+ $ mvn org.codehaus.mojo:exec-maven-plugin:3.0.0:java -Dexec.mainClass="org.apache.dubbo.MyDubboClient"
+ Received reply:message: "Hello,Demo!"
+ ```
+### 常见问题
+
+1. protobuf 类找不到
+
+由于 Triple 协议底层需要依赖 protobuf 协议进行传输，即使定义的服务接口不使用 protobuf 也需要在环境中引入 protobuf 的依赖。
+
+```xml
+ <dependency>
+ <groupId>com.google.protobuf</groupId>
+ <artifactId>protobuf-java</artifactId>
+ <version>3.19.4</version>
+ </dependency>
+```
\ No newline at end of file
