[ 
https://issues.apache.org/jira/browse/SCB-330?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16361945#comment-16361945
 ] 

ASF GitHub Bot commented on SCB-330:
------------------------------------

WillemJiang closed pull request #135: SCB-330 add user guide and Chinese 
version of docs
URL: https://github.com/apache/incubator-servicecomb-saga/pull/135
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/README.md b/README.md
index e8e62a21..aa9b8400 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Saga [![Build 
Status](https://travis-ci.org/apache/incubator-servicecomb-saga.svg?branch=master)](https://travis-ci.org/apache/incubator-servicecomb-saga?branch=master)
 [![Coverage 
Status](https://coveralls.io/repos/github/apache/incubator-servicecomb-saga/badge.svg?branch=master)](https://coveralls.io/github/apache/incubator-servicecomb-saga?branch=master)
 
[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
+# Saga | [中文](README_ZH.md) [![Build 
Status](https://travis-ci.org/apache/incubator-servicecomb-saga.svg?branch=master)](https://travis-ci.org/apache/incubator-servicecomb-saga?branch=master)
 [![Coverage 
Status](https://coveralls.io/repos/github/apache/incubator-servicecomb-saga/badge.svg?branch=master)](https://coveralls.io/github/apache/incubator-servicecomb-saga?branch=master)
 
[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
 Apache ServiceComb (incubating) Saga is an eventually data consistency 
solution for micro-service applications. Transactions are commited directly in 
the try phase and compensated in reverse order in the rollback phase comparing 
to [TCC](http://design.inf.usi.ch/sites/default/files/biblio/rest-tcc.pdf). 
 
 ## Features
@@ -22,6 +22,9 @@ See [Saga Pack Design](docs/design.md) for details. If you 
are interested in our
 ## Get Started
 See [Booking Demo](saga-demo/pack-demo/README.md) for details.
 
+## User Guide
+See [User Guide](docs/user_guide.md) for details.
+
 ## Contact Us
 * [issues](https://issues.apache.org/jira/browse/SCB)
 * [gitter](https://gitter.im/ServiceCombUsers/Lobby)
@@ -31,4 +34,4 @@ See [Booking Demo](saga-demo/pack-demo/README.md) for details.
 See [Pull Request 
Guide](http://servicecomb.incubator.apache.org/developers/submit-codes/) for 
details.
 
 ## License
-Licensed under an [Apache 
2.0](https://github.com/apache/incubator-servicecomb-saga/blob/master/LICENSE) 
license.
+Licensed under an [Apache 2.0 
license](https://github.com/apache/incubator-servicecomb-saga/blob/master/LICENSE).
diff --git a/README_ZH.md b/README_ZH.md
new file mode 100644
index 00000000..2ea467be
--- /dev/null
+++ b/README_ZH.md
@@ -0,0 +1,37 @@
+# Saga | [English](README.md) [![Build 
Status](https://travis-ci.org/apache/incubator-servicecomb-saga.svg?branch=master)](https://travis-ci.org/apache/incubator-servicecomb-saga?branch=master)
 [![Coverage 
Status](https://coveralls.io/repos/github/apache/incubator-servicecomb-saga/badge.svg?branch=master)](https://coveralls.io/github/apache/incubator-servicecomb-saga?branch=master)
 
[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
+Apache ServiceComb (incubating) Saga 
是一个微服务应用的数据最终一致性解决方案。相对于[TCC](http://design.inf.usi.ch/sites/default/files/biblio/rest-tcc.pdf)而言,在try阶段,Saga会直接提交事务,后续rollback阶段则通过反向的补偿操作来完成。
+
+## 特性
+* 高可用。支持集群模式。
+* 高可靠。所有的事务事件都持久存储在数据库中。
+* 高性能。事务事件是通过gRPC来上报的,且事务的请求信息是通过Kyro进行序列化和反序列化的。
+* 低侵入。仅需2-3个注解和编写对应的补偿方法即可进行分布式事务。
+* 部署简单。可通过Docker快速部署。
+* 支持前向恢复(重试)及后向恢复(补偿)。
+
+## 架构
+Saga是由 **alpha** 和 **omega**组成,其中:
+* alpha充当协调者的角色,主要负责对事务进行管理和协调。
+* omega是微服务中内嵌的一个agent,负责对网络请求进行拦截并向alpha上报事务事件。
+
+下图展示了alpha, omega以及微服务三者的关系:
+![Saga Pack 架构](docs/static_files/pack.png)
+
+详情可浏览[Saga Pack 设计文档](docs/design_zh.md). 
如果您对Saga的上一代架构感兴趣,可移步至[上一代Saga文档](docs/old_saga.md)了解详情。
+
+## 快速入门
+详情可浏览[出行预订示例](saga-demo/pack-demo/README.md)。
+
+## 用户指南
+详情可浏览[用户指南](docs/user_guide_zh.md)。
+
+## 联系我们
+* [提交issues](https://issues.apache.org/jira/browse/SCB)
+* [gitter聊天室](https://gitter.im/ServiceCombUsers/Lobby)
+* 邮件列表: [订阅](mailto:dev-subscr...@servicecomb.incubator.apache.org) 
[浏览](https://lists.apache.org/list.html?d...@servicecomb.apache.org)
+
+## 贡献
+详情可浏览[代码提交指南](http://servicecomb.incubator.apache.org/cn/developers/submit-codes/)。
+
+## License
+[Apache 2.0 
license](https://github.com/apache/incubator-servicecomb-saga/blob/master/LICENSE)。
diff --git 
a/alpha/alpha-server/src/test/java/org/apache/servicecomb/saga/alpha/server/AlphaIntegrationTest.java
 
b/alpha/alpha-server/src/test/java/org/apache/servicecomb/saga/alpha/server/AlphaIntegrationTest.java
index 497c2443..8b2672ce 100644
--- 
a/alpha/alpha-server/src/test/java/org/apache/servicecomb/saga/alpha/server/AlphaIntegrationTest.java
+++ 
b/alpha/alpha-server/src/test/java/org/apache/servicecomb/saga/alpha/server/AlphaIntegrationTest.java
@@ -389,6 +389,8 @@ public void abortTimeoutSagaStartedEvent() {
     assertThat(events.get(1).type(), is(TxAbortedEvent.name()));
     assertThat(events.get(2).type(), is(SagaEndedEvent.name()));
 
+    await().atMost(2, SECONDS).until(this::waitTillTimeoutDone);
+
     assertThat(timeoutEntityRepository.count(), is(1L));
     Iterable<TxTimeout> timeouts = timeoutEntityRepository.findAll();
     timeouts.forEach(timeout -> {
@@ -416,6 +418,8 @@ public void abortTimeoutTxStartedEvent() {
     assertThat(events.get(3).type(), is(TxCompensatedEvent.name()));
     assertThat(events.get(4).type(), is(SagaEndedEvent.name()));
 
+    await().atMost(2, SECONDS).until(this::waitTillTimeoutDone);
+
     assertThat(timeoutEntityRepository.count(), is(1L));
     Iterable<TxTimeout> timeouts = timeoutEntityRepository.findAll();
     timeouts.forEach(timeout -> {
@@ -425,6 +429,15 @@ public void abortTimeoutTxStartedEvent() {
     });
   }
 
+  private boolean waitTillTimeoutDone() {
+    for (TxTimeout txTimeout : timeoutEntityRepository.findAll()) {
+      if (txTimeout.status().equals(DONE.name())) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   private GrpcAck onCompensation(GrpcCompensateCommand command) {
     return blockingStub.onTxEvent(
         eventOf(TxCompensatedEvent,
diff --git a/docs/design.md b/docs/design.md
index d976d1ad..7329b021 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -1,4 +1,5 @@
 # Saga Pack Design
+[![ZH doc](https://img.shields.io/badge/document-中文-blue.svg)](design_zh.md)
 ## Overview
 Pack contains two components: *alpha* and *omega*. Alpha is the pack leader 
and backed by database to make sure transaction events stored permanently while 
omega is the pack worker and embedded inside services to intercept transaction 
invocation and report events to alpha.
 
diff --git a/docs/design_zh.md b/docs/design_zh.md
new file mode 100644
index 00000000..072565ae
--- /dev/null
+++ b/docs/design_zh.md
@@ -0,0 +1,34 @@
+# Saga Pack 设计文档
+[![EN doc](https://img.shields.io/badge/document-English-blue.svg)](design.md)
+## 概览
+Pack中包含两个组件,即 **alpha** 和 **omega**。
+* alpha充当协调者的角色,主要负责对事务的事件进行持久化存储以及协调子事务的状态,使其得以最终与全局事务的状态保持一致。
+* omega是微服务中内嵌的一个agent,负责对网络请求进行拦截并向alpha上报事务事件,并在异常情况下根据alpha下发的指令执行相应的补偿操作。
+
+![Pack Architecture](static_files/pack.png)
+
+## Omega内部运行机制
+omega是微服务中内嵌的一个agent。当服务收到请求时,omega会将其拦截并从中提取请求信息中的全局事务id作为其自身的全局事务id(即Saga事件id),并提取本地事务id作为其父事务id。在预处理阶段,alpha会记录事务开始的事件;在后处理阶段,alpha会记录事务结束的事件。因此,每个成功的子事务都有一一对应的开始及结束事件。
+
+![Omega Internal](static_files/omega_internal.png)
+
+## 服务间通信流程
+服务间通信的流程与[Zipkin](https://github.com/openzipkin/zipkin)的类似。在服务生产方,omega会拦截请求中事务相关的id来提取事务的上下文。在服务消费方,omega会在请求中注入事务相关的id来传递事务的上下文。通过服务提供方和服务消费方的这种协作处理,子事务能连接起来形成一个完整的全局事务。
+
+![Inter-Service Communication](static_files/inter-service_communication.png)
+
+## 具体处理流程
+### 成功场景
+成功场景下,每个开始的事件都会有对应的结束事件。
+
+![Successful Scenario](static_files/successful_scenario.png)
+
+### 异常场景
+异常场景下,omega会向alpha上报中断事件,然后alpha会向该全局事务的其它已完成的子事务发送补偿指令,确保最终所有的子事务要么都成功,要么都回滚。
+
+![Exception Scenario](static_files/exception_scenario.png)
+
+### 超时场景
+超时场景下,已超时的事件会被alpha的定期扫描器检测出来,与此同时,该超时事务对应的全局事务也会被中断。
+
+![Timeout Scenario](static_files/timeout_scenario.png)
diff --git a/docs/user_guide.md b/docs/user_guide.md
new file mode 100644
index 00000000..a0d9db5d
--- /dev/null
+++ b/docs/user_guide.md
@@ -0,0 +1,101 @@
+# Saga User Guide
+[![ZH 
doc](https://img.shields.io/badge/document-中文-blue.svg)](user_guide_zh.md)
+
+## Prerequisites
+You will need:
+1. [JDK 1.8][jdk]
+2. [Maven 3.x][maven]
+3. [Docker][docker]
+
+[jdk]: 
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
+[maven]: https://maven.apache.org/install.html
+[docker]: https://www.docker.com/get-docker
+
+## Build
+To build:
+```bash
+$ git clone https://github.com/apache/incubator-servicecomb-saga.git
+$ cd incubator-servicecomb-saga
+$ mvn clean install -DskipTests -Pdocker
+```
+
+## How to use
+### Add saga dependencies
+```xml
+    <dependency>
+      <groupId>org.apache.servicecomb.saga</groupId>
+      <artifactId>omega-spring-starter</artifactId>
+      <version>0.0.3-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.servicecomb.saga</groupId>
+      <artifactId>omega-transport-resttemplate</artifactId>
+      <version>0.0.3-SNAPSHOT</version>
+    </dependency>
+```
+
+### Add saga annotations and corresponding compensation methods
+Take a transfer money application as an example:
+1. add `@EnableOmega` at application entry to initialize omega configurations 
and connect to alpha
+   ```java
+   @SpringBootApplication
+   @EnableOmega
+   public class Application {
+     public static void main(String[] args) {
+       SpringApplication.run(Application.class, args);
+     }
+   }
+   ```
+   
+2. add `@SagaStart` at the starting point of the global transaction
+   ```java
+   @SagaStart(timeout=10)
+   public boolean transferMoney(String from, String to, int amount) {
+     transferOut(from, amount);
+     transferIn(to, amount);
+   }
+   ```
+   **Note:** By default, timeout is disable.
+
+3. add `@Compensable` at the sub-transaction and specify its corresponding 
compensation method
+   ```java
+   @Compensable(timeout=5, compensationMethod="cancel")
+   public boolean transferOut(String from, int amount) {
+     repo.reduceBalanceByUsername(from, amount);
+   }
+ 
+   public boolean cancel(String from, int amount) {
+     repo.addBalanceByUsername(from, amount);
+   }
+   ```
+   **Note:** By default, timeout is disable.
+
+   **Note:** If the starting point of global transaction and local transaction 
overlaps, both `@SagaStart` and `@Compensable` are needed.
+
+4. Repeat step 3 for the `transferIn` service.
+
+## How to run
+1. run postgreSQL.
+   ```bash
+   docker run -d -e "POSTGRES_DB=saga" -e "POSTGRES_USER=saga" -e 
"POSTGRES_PASSWORD=password" -p 5432:5432 postgres
+   ```
+
+2. run alpha. Before running alpha, please make sure postgreSQL is already up.
+   ```bash
+   docker run -d -p 8090:8090 \
+     -e "JAVA_OPTS=-Dspring.profiles.active=prd" \
+     -e 
"spring.datasource.url=jdbc:postgresql://{docker.host.address}:5432/saga?useSSL=false"
 \
+     alpha-server:0.0.3-SNAPSHOT
+   ```
+
+3. setup omega. Configure the following values in `application.yaml`.
+   ```yaml
+   spring:
+     application:
+       name: {application.name}
+   alpha:
+     cluster:
+       address: {alpha.cluster.addresses}
+   ```
+
+Then you can start your micro-services.
diff --git a/docs/user_guide_zh.md b/docs/user_guide_zh.md
new file mode 100644
index 00000000..6b8ce473
--- /dev/null
+++ b/docs/user_guide_zh.md
@@ -0,0 +1,100 @@
+# Saga 用户指南
+[![EN 
doc](https://img.shields.io/badge/document-English-blue.svg)](user_guide.md)
+
+## 准备环境
+1. 安装[JDK 1.8][jdk]
+2. 安装[Maven 3.x][maven]
+3. 安装[Docker][docker]
+
+[jdk]: 
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
+[maven]: https://maven.apache.org/install.html
+[docker]: https://www.docker.com/get-docker
+
+## 编译
+编译Saga,只需以下几步:
+```bash
+$ git clone https://github.com/apache/incubator-servicecomb-saga.git
+$ cd incubator-servicecomb-saga
+$ mvn clean install -DskipTests -Pdocker
+```
+
+## 如何使用
+### 引入Saga的依赖
+```xml
+    <dependency>
+      <groupId>org.apache.servicecomb.saga</groupId>
+      <artifactId>omega-spring-starter</artifactId>
+      <version>0.0.3-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.servicecomb.saga</groupId>
+      <artifactId>omega-transport-resttemplate</artifactId>
+      <version>0.0.3-SNAPSHOT</version>
+    </dependency>
+```
+
+### 添加Saga的注解及相应的补偿方法
+以一个转账应用为例:
+1. 在应用入口添加 `@EnableOmega` 的注解来初始化omega的配置并与alpha建立连接。
+   ```java
+   @SpringBootApplication
+   @EnableOmega
+   public class Application {
+     public static void main(String[] args) {
+       SpringApplication.run(Application.class, args);
+     }
+   }
+   ```
+
+2. 在全局事务的起点添加 `@SagaStart` 的注解。
+   ```java
+   @SagaStart(timeout=10)
+   public boolean transferMoney(String from, String to, int amount) {
+     transferOut(from, amount);
+     transferIn(to, amount);
+   }
+   ```
+   **注意:** 默认情况下,超时设置需要显式声明才生效。
+
+3. 在子事务处添加 `@Compensable` 的注解并指明其对应的补偿方法。
+   ```java
+   @Compensable(timeout=5, compensationMethod="cancel")
+   public boolean transferOut(String from, int amount) {
+     repo.reduceBalanceByUsername(from, amount);
+   }
+ 
+   public boolean cancel(String from, int amount) {
+     repo.addBalanceByUsername(from, amount);
+   }
+   ```
+   **注意:** 默认情况下,超时设置需要显式声明才生效。
+
+   **注意:** 若全局事务起点与子事务起点重合,需同时声明 `@SagaStart` 和 `@Compensable` 的注解。
+
+4. 对转入服务重复第三步即可。
+
+## 如何运行
+1. 运行postgreSQL
+   ```bash
+   docker run -d -e "POSTGRES_DB=saga" -e "POSTGRES_USER=saga" -e 
"POSTGRES_PASSWORD=password" -p 5432:5432 postgres
+   ```
+
+2. 运行alpha。在运行alpha前,请确保postgreSQL已正常启动。
+   ```bash
+   docker run -d -p 8090:8090 \
+     -e "JAVA_OPTS=-Dspring.profiles.active=prd" \
+     -e 
"spring.datasource.url=jdbc:postgresql://{docker.host.address}:5432/saga?useSSL=false"
 \
+     alpha-server:0.0.3-SNAPSHOT
+   ```
+
+3. 配置omega。在 `application.yaml` 添加下面的配置项:
+   ```yaml
+   spring:
+     application:
+       name: {application.name}
+   alpha:
+     cluster:
+       address: {alpha.cluster.addresses}
+   ```
+
+然后就可以运行相关的微服务了。
diff --git 
a/omega/omega-connector/omega-connector-grpc/src/test/java/org/apache/servicecomb/saga/omega/connector/grpc/LoadBalancedClusterMessageSenderTest.java
 
b/omega/omega-connector/omega-connector-grpc/src/test/java/org/apache/servicecomb/saga/omega/connector/grpc/LoadBalancedClusterMessageSenderTest.java
index bb24c5cb..fce9c0b6 100644
--- 
a/omega/omega-connector/omega-connector-grpc/src/test/java/org/apache/servicecomb/saga/omega/connector/grpc/LoadBalancedClusterMessageSenderTest.java
+++ 
b/omega/omega-connector/omega-connector-grpc/src/test/java/org/apache/servicecomb/saga/omega/connector/grpc/LoadBalancedClusterMessageSenderTest.java
@@ -176,7 +176,7 @@ public void resetLatencyOnReconnection() throws Exception {
     messageSender.send(event);
 
     startServerOnPort(deadPort);
-    await().atMost(2, SECONDS).until(() -> connected.get(deadPort).size() == 
3);
+    await().atMost(3, SECONDS).until(() -> connected.get(deadPort).size() == 
3);
 
     TxEvent abortedEvent = new TxAbortedEvent(globalTxId, localTxId, 
parentTxId, compensationMethod, new RuntimeException("oops"));
     messageSender.send(abortedEvent);
diff --git a/saga-demo/pack-demo/booking/pom.xml 
b/saga-demo/pack-demo/booking/pom.xml
index 47a8f9e7..1f88668c 100644
--- a/saga-demo/pack-demo/booking/pom.xml
+++ b/saga-demo/pack-demo/booking/pom.xml
@@ -41,9 +41,9 @@
       <artifactId>omega-spring-starter</artifactId>
     </dependency>
     <dependency>
-       <groupId>org.apache.servicecomb.saga</groupId>
-       <artifactId>omega-transport-resttemplate</artifactId>
-     </dependency>
+      <groupId>org.apache.servicecomb.saga</groupId>
+      <artifactId>omega-transport-resttemplate</artifactId>
+    </dependency>
   </dependencies>
 
   <build>


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


> [pack] update documents of saga pack
> ------------------------------------
>
>                 Key: SCB-330
>                 URL: https://issues.apache.org/jira/browse/SCB-330
>             Project: Apache ServiceComb
>          Issue Type: Improvement
>          Components: Saga
>    Affects Versions: saga-0.1.0
>            Reporter: Eric Lee
>            Assignee: Eric Lee
>            Priority: Major
>             Fix For: saga-0.1.0
>
>
> As a dev, I want to know how to use the Saga's new architecture pack. 
> Documents including README and quick start should contain details of its 
> usages, features and architecture.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

Reply via email to