From 2cc1cfe83df1d2b28bcb11aca6bbeaa194ba1502 Mon Sep 17 00:00:00 2001 From: Willem Jiang Date: Wed, 2 Jan 2019 17:10:09 +0800 Subject: [PATCH] SCB-1100 Updated the user guilde for migration from saga 0.2.x --- docs/user_guide.md | 25 ++++++++++++++++++++++++- docs/user_guide_zh.md | 24 ++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/user_guide.md b/docs/user_guide.md index ef2f19863..ce832511c 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -51,13 +51,23 @@ After executing either one of the above command, you will find alpha server's ex ${pack.version} ``` -**Note**: Please change the `${pack.version}` to the actual version. Since 0.3.0 we update the package name of +**Note**: Please change the `${pack.version}` to the actual version. + +**Migration Note**:Since 0.3.0 we rename the project repository name from saga to pack. Please update the group id and package name if you migrate your application from saga 0.2.x to pack 0.3.0. + +| name | 0.2.x | 0.3.x | +| ---- | ---- | ---- | +| groupId | org.apache.servicecomb.saga | org.apache.servicecomb.pack | +| Package Name | org.apache.servicecomb.saga | org.apache.servicecomb.pack | ### Saga Support 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 + import org.apache.servicecomb.pack.omega.spring.EnableOmega; + import org.springframework.boot.autoconfigure.SpringBootApplication; + @SpringBootApplication @EnableOmega public class Application { @@ -69,6 +79,8 @@ Take a transfer money application as an example: 2. add `@SagaStart` at the starting point of the global transaction ```java + import org.apache.servicecomb.pack.omega.context.annotations.SagaStart; + @SagaStart(timeout=10) public boolean transferMoney(String from, String to, int amount) { transferOut(from, amount); @@ -79,6 +91,9 @@ Take a transfer money application as an example: 3. add `@Compensable` at the sub-transaction and specify its corresponding compensation method ```java + import javax.transaction.Transactional; + import org.apache.servicecomb.pack.omega.transaction.annotations.Compensable; + @Compensable(timeout=5, compensationMethod="cancel") @Transactional public boolean transferOut(String from, int amount) { @@ -107,6 +122,9 @@ Add TCC annotations and corresponding confirm and cancel methods Take a transfer money application as an example: 1. add `@EnableOmega` at application entry to initialize omega configurations and connect to alpha ```java + import org.apache.servicecomb.pack.omega.spring.EnableOmega; + import org.springframework.boot.autoconfigure.SpringBootApplication; + @SpringBootApplication @EnableOmega public class Application { @@ -118,6 +136,8 @@ Add TCC annotations and corresponding confirm and cancel methods 2. add `@TccStart` at the starting point of the global transaction ```java + import org.apache.servicecomb.pack.omega.context.annotations.TccStart; + @TccStart public boolean transferMoney(String from, String to, int amount) { transferOut(from, amount); @@ -128,6 +148,9 @@ Add TCC annotations and corresponding confirm and cancel methods 3. add `@Participate` at the sub-transaction and specify its corresponding compensation method ```java + import javax.transaction.Transactional; + import org.apache.servicecomb.pack.omega.transaction.annotations.Participate; + @Participate(confirmMethod = "confirm", cancelMethod = "cancel") @Transactional public void transferOut(String from, int amount) { diff --git a/docs/user_guide_zh.md b/docs/user_guide_zh.md index c9724f0fb..2b13f796c 100644 --- a/docs/user_guide_zh.md +++ b/docs/user_guide_zh.md @@ -52,12 +52,23 @@ Saga可通过以下任一方式进行构建： ``` **注意**: 请将`${pack.version}`更改为实际的版本号。 +**版本迁移提示**: 从0.3.0 开始，整个项目的代码库名由servicecomb-saga改名为servicecomb-pack, 与此同时我们也更新了对应发布包的组名以及相关包名。 +如果你的项目是从saga 0.2.x 迁移过来，请按照下表所示进行修改。 + +| name | 0.2.x | 0.3.x | +| ---- | ---- | ---- | +| groupId | org.apache.servicecomb.saga | org.apache.servicecomb.pack | +| Package Name | org.apache.servicecomb.saga | org.apache.servicecomb.pack | + ### Saga 支持 添加Saga的注解及相应的补偿方法 以一个转账应用为例： 1. 在应用入口添加 `@EnableOmega` 的注解来初始化omega的配置并与alpha建立连接。 ```java + import org.apache.servicecomb.pack.omega.spring.EnableOmega; + import org.springframework.boot.autoconfigure.SpringBootApplication; + @SpringBootApplication @EnableOmega public class Application { @@ -69,6 +80,8 @@ Saga可通过以下任一方式进行构建： 2. 在全局事务的起点添加 `@SagaStart` 的注解。 ```java + import org.apache.servicecomb.pack.omega.context.annotations.SagaStart; + @SagaStart(timeout=10) public boolean transferMoney(String from, String to, int amount) { transferOut(from, amount); @@ -79,6 +92,9 @@ Saga可通过以下任一方式进行构建： 3. 在子事务处添加 `@Compensable` 的注解并指明其对应的补偿方法。 ```java + import javax.transaction.Transactional; + import org.apache.servicecomb.pack.omega.transaction.annotations.Compensable; + @Compensable(timeout=5, compensationMethod="cancel") @Transactional public boolean transferOut(String from, int amount) { @@ -106,6 +122,9 @@ Saga可通过以下任一方式进行构建： 以一个转账应用为例： 1. 在应用入口添加 `@EnableOmega` 的注解来初始化omega的配置并与alpha建立连接。 ```java + import org.apache.servicecomb.pack.omega.spring.EnableOmega; + import org.springframework.boot.autoconfigure.SpringBootApplication; + @SpringBootApplication @EnableOmega public class Application { @@ -117,6 +136,8 @@ Saga可通过以下任一方式进行构建： 2. 在全局事务的起点添加 `@TccStart` 的注解。 ```java + import org.apache.servicecomb.pack.omega.context.annotations.TccStart; + @TccStart public boolean transferMoney(String from, String to, int amount) { transferOut(from, amount); @@ -127,6 +148,9 @@ Saga可通过以下任一方式进行构建： 3. 在子事务尝试方法处添加 `@Participate` 的注解并指明其对应的执行以及补偿方法名, ```java + import javax.transaction.Transactional; + import org.apache.servicecomb.pack.omega.transaction.annotations.Participate; + @Participate(confirmMethod = "confirm", cancelMethod = "cancel") @Transactional public void transferOut(String from, int amount) {