Merge 6b3be4b into 5412022

docs/faq/cn/how_to_use_mysql_as_alpha_backend_database.md

@@ -30,10 +30,13 @@
 4. 运行alpha。请确保MySQL在此前已成功启动。alpha的运行可通过docker或可执行文件的方式。
    * 通过docker
       ```bash
-      docker run -d -p 8090:8090 -e "JAVA_OPTS=-Dspring.profiles.active=mysql -Dspring.datasource.url=jdbc:mysql://${host_address}:3306/saga?useSSL=false" alpha-server:${saga_version}
+      docker run -d -p 8080:8080 -p 8090:8090 -e "JAVA_OPTS=-Dspring.profiles.active=mysql -Dspring.datasource.url=jdbc:mysql://${host_address}:3306/saga?useSSL=false" alpha-server:${saga_version}
       ```
    * 通过可执行文件
       ```bash
       java -Dspring.profiles.active=mysql -D"spring.datasource.url=jdbc:mysql://${host_address}:3306/saga?useSSL=false" -jar alpha-server-${saga_version}-exec.jar
       ```
    **注意**: 请在运行命令前将`${saga_version}`和`${host_address}`更改为实际值。
+
+   **注意**: 默认情况下，8080端口用于处理omega处发起的gRPC的请求，而8090端口用于处理查询存储在alpha处的事件信息。
+

docs/faq/en/how_to_use_mysql_as_alpha_backend_database.md

@@ -30,10 +30,14 @@
 4. Run alpha. Please make sure MySQL is up before this step. You can run alpha through docker or executable file.
    * via docker
       ```bash
-      docker run -d -p 8090:8090 -e "JAVA_OPTS=-Dspring.profiles.active=mysql -Dspring.datasource.url=jdbc:mysql://${host_address}:3306/saga?useSSL=false" alpha-server:${saga_version}
+      docker run -d -p 8080:8080 -p 8090:8090 -e "JAVA_OPTS=-Dspring.profiles.active=mysql -Dspring.datasource.url=jdbc:mysql://${host_address}:3306/saga?useSSL=false" alpha-server:${saga_version}
       ```
    * via executable file
       ```bash
       java -Dspring.profiles.active=mysql -D"spring.datasource.url=jdbc:mysql://${host_address}:3306/saga?useSSL=false" -jar alpha-server-${saga_version}-exec.jar
       ```
+
    **Notice**: Please change `${saga_version}` and `${host_address}` to the actual value before you execute the command.
+
+
+   **Note**: By default, port 8080 is used to serve omega's request via gRPC while port 8090 is used to query the events stored in alpha.

docs/user_guide.md

@@ -87,6 +87,9 @@ Take a transfer money application as an example:
      repo.addBalanceByUsername(from, amount);
    }
    ```
+
+   **Note** transactions and compensations implemented by services must be idempotent.
+
    **Note:** By default, timeout is disable.
 
    **Note:** If the starting point of global transaction and local transaction overlaps, both `@SagaStart` and `@Compensable` are needed.
@@ -102,14 +105,17 @@ Take a transfer money application as an example:
 2. run alpha. Before running alpha, please make sure postgreSQL is already up. You can run alpha through docker or executable file.
    * Run alpha through docker.
       ```bash
-      docker run -d -p 8090:8090 -e "JAVA_OPTS=-Dspring.profiles.active=prd -Dspring.datasource.url=jdbc:postgresql://${host_address}:5432/saga?useSSL=false" alpha-server:${saga_version}
+      docker run -d -p 8080:8080 -p 8090:8090 -e "JAVA_OPTS=-Dspring.profiles.active=prd -Dspring.datasource.url=jdbc:postgresql://${host_address}:5432/saga?useSSL=false" alpha-server:${saga_version}
       ```
    * Run alpha through executable file.
       ```bash
       java -Dspring.profiles.active=prd -D"spring.datasource.url=jdbc:postgresql://${host_address}:5432/saga?useSSL=false" -jar alpha-server-${saga_version}-exec.jar
       ```
+
    **Note**: Please change `${saga_version}` and `${host_address}` to the actual value before you execute the command.
 
+   **Note**: By default, port 8080 is used to serve omega's request via gRPC while port 8090 is used to query the events stored in alpha.
+
 3. setup omega. Configure the following values in `application.yaml`.
    ```yaml
    spring:

docs/user_guide_zh.md

@@ -87,6 +87,9 @@ Saga可通过以下任一方式进行构建：
      repo.addBalanceByUsername(from, amount);
    }
    ```
+
+   **注意:** 实现的服务和补偿必须满足幂等的条件。
+
    **注意:** 默认情况下，超时设置需要显式声明才生效。
 
    **注意:** 若全局事务起点与子事务起点重合，需同时声明 `@SagaStart` 和 `@Compensable` 的注解。
@@ -102,14 +105,19 @@ Saga可通过以下任一方式进行构建：
 2. 运行alpha。在运行alpha前，请确保postgreSQL已正常启动。可通过docker或可执行文件的方式来启动alpha。
    * 通过docker运行：
       ```bash
-      docker run -d -p 8090:8090 -e "JAVA_OPTS=-Dspring.profiles.active=prd -Dspring.datasource.url=jdbc:postgresql://${host_address}:5432/saga?useSSL=false" alpha-server:${saga_version}
+      docker run -d -p 8080:8080 -p 8090:8090 -e "JAVA_OPTS=-Dspring.profiles.active=prd -Dspring.datasource.url=jdbc:postgresql://${host_address}:5432/saga?useSSL=false" alpha-server:${saga_version}
       ```
    * 通过可执行文件运行：
       ```bash
       java -Dspring.profiles.active=prd -D"spring.datasource.url=jdbc:postgresql://${host_address}:5432/saga?useSSL=false" -jar alpha-server-${saga_version}-exec.jar
       ```
+
    **注意**: 请在执行命令前将`${saga_version}`和`${host_address}`更改为实际值。
 
+
+   **注意**: 默认情况下，8080端口用于处理omega处发起的gRPC的请求，而8090端口用于处理查询存储在alpha处的事件信息。
+
+
 3. 配置omega。在 `application.yaml` 添加下面的配置项：
    ```yaml
    spring:

saga-demo/booking/README.md

@@ -1,4 +1,4 @@
-# Pack Transaction Demo
+# Booking Demo
 This demo simulates a booking application including three services:
 * pack-booking
 * pack-car
@@ -17,12 +17,14 @@ You will need:
 [docker_compose]: https://docs.docker.com/compose/install/
 
 ## Running Demo
+You can run the demo using either docker compose or executable files.
+### via docker compose
 1. run the following command to create docker images in saga project root folder.
    ```
-   mvn package -DskipTests -Pdocker -Pdemo
+   mvn clean package -DskipTests -Pdocker -Pdemo
    ```
 
-2. start application up in `saga-demo/booking/` with the following command
+2. start application up
    ```
    docker-compose up
    ```
@@ -48,32 +50,56 @@ You will need:
       docker-compose -f docker-compose.yaml -f docker-compose.mysql.yaml up
       ```
 
+### via executable files
+1. run the following command to generate executable alpha server jar in `alpha/alpha-server/target/saga/alpha-server-${saga_version}-exec.jar`.
+   ```
+   mvn clean package -DskipTests -Pdemo
+   ```
+
+2. follow the instructions in the [How to run](https://github.com/apache/incubator-servicecomb-saga/blob/master/docs/user_guide.md#how-to-run) section in User Guide to run postgreSQL and alpha server.
+
+3. start application up
+   1. start hotel service. The executable jar file should be in `saga-demo/booking/hotel/target/saga`.
+   ```bash
+   java -Dserver.port=8081 -Dalpha.cluster.address=${alpha_address}:8080 -jar pack-hotel-${saga_version}-exec.jar
+   ```
+
+   2. start car service. The executable jar file should be in `saga-demo/booking/car/target/saga`.
+   ```bash
+   java -Dserver.port=8082 -Dalpha.cluster.address=${alpha_address}:8080 -jar pack-car-${saga_version}-exec.jar
+   ```
+
+   3. start booking service. The executable jar file should be in `saga-demo/booking/booking/target/saga`.
+   ```bash
+   java -Dserver.port=8083 -Dalpha.cluster.address=${alpha_address}:8080 -Dservices.car.address=${host_address}:8082 -Dservices.hotel.address=${host_address}:8081  -jar pack-booking-${saga_version}-exec.jar
+   ```
+
 ## User Requests
 1. Booking 2 rooms and 2 cars, this booking will be OK.
 ```
-curl -X POST http://{docker.host.ip}:8083/booking/test/2/2
+curl -X POST http://${host_address}:8083/booking/test/2/2
 ```
 Check the hotel booking status with
 ```
-curl http://{docker.host.ip}:8081/bookings
+curl http://${host_address}:8081/bookings
 ```
 Check the car booking status with
 ```
-curl http://{docker.host.ip}:8082/bookings
+curl http://${host_address}:8082/bookings
 
 ```
 
 2. Booking 3 rooms and 2 cars, this booking will case the hotel order failed and trigger the compansate operation with car booking.
 ```
-curl -X POST http://{docker.host.ip}:8083/booking/test/3/2
+curl -X POST http://${host_address}:8083/booking/test/3/2
 ```
 Check the hotel booking status with
 ```
-curl http://{docker.host.ip}:8081/bookings
+curl http://${host_address}:8081/bookings
 ```
 Check the car booking status with
 ```
-curl http://{docker.host.ip}:8082/bookings
+curl http://${host_address}:8082/bookings
 ```
 The second car booking will be marked with **cancel:true**
 

saga-demo/booking/booking/src/main/java/org/apache/servicecomb/saga/demo/pack/booking/BookingController.java

@@ -19,25 +19,33 @@
 
 import org.apache.servicecomb.saga.omega.context.annotations.SagaStart;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.client.RestTemplate;
 
 @RestController
 public class BookingController {
+
+  @Value("${services.car.address:'http://pack-car.servicecomb.io:8080'}")
+  private String carServiceUrl;
+
+  @Value("${services.hotel.address:'http://pack-hotel.servicecomb.io:8080'}")
+  private String hotelServiceUrl;
+
   @Autowired
   private RestTemplate template;
 
   @SagaStart
   @PostMapping("/booking/{name}/{rooms}/{cars}")
   public String order(@PathVariable String name,  @PathVariable Integer rooms, @PathVariable Integer cars) {
     template.postForEntity(
-        "http://pack-car.servicecomb.io:8080/order/{name}/{cars}",
+        carServiceUrl + "/order/{name}/{cars}",
         null, String.class, name, cars);
 
     template.postForEntity(
-        "http://pack-hotel.servicecomb.io:8080/order/{name}/{rooms}",
+        hotelServiceUrl + "/order/{name}/{rooms}",
         null, String.class, name, rooms);
 
     return name + " booking " + rooms + " rooms and " + cars + " cars OK";