This is an automated email from the ASF dual-hosted git repository.
ningjiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-saga.git
commit 249d1d76276b4ca6f904dff0e9477be9bbf326ef
Author: Eric Lee <dagang...@huawei.com>
AuthorDate: Fri Feb 9 17:35:21 2018 +0800
SCB-330 add user guide for saga pack
---
README.md | 3 ++
README_ZH.md | 3 ++
docs/user_guide.md | 101 ++++++++++++++++++++++++++++++++++++
docs/user_guide_zh.md | 100 +++++++++++++++++++++++++++++++++++
saga-demo/pack-demo/booking/pom.xml | 6 +--
5 files changed, 210 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md
index f9a81e3..aa9b840 100644
--- a/README.md
+++ b/README.md
@@ -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)
diff --git a/README_ZH.md b/README_ZH.md
index a7ac6ac..2ea467b 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -22,6 +22,9 @@ Saga是由 **alpha** 和 **omega**组成，其中：
## 快速入门
详情可浏览[出行预订示例](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)
diff --git a/docs/user_guide.md b/docs/user_guide.md
new file mode 100644
index 0000000..bd9733d
--- /dev/null
+++ b/docs/user_guide.md
@@ -0,0 +1,101 @@
+# Saga 用户指南
+[](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 0000000..25a8ff2
--- /dev/null
+++ b/docs/user_guide_zh.md
@@ -0,0 +1,100 @@
+# Saga User Guide
+[](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/saga-demo/pack-demo/booking/pom.xml
b/saga-demo/pack-demo/booking/pom.xml
index 47a8f9e..1f88668 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>
--
To stop receiving notification emails like this one, please contact
ningji...@apache.org.
