[GitHub] WillemJiang closed pull request #275: [SCB-864] add SQL component content into API document

[GitBox <gi...@apache.org>]

WillemJiang closed pull request #275: [SCB-864] add SQL component content into API document
URL: https://github.com/apache/incubator-servicecomb-saga/pull/275
 
 
   

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/docs/api/api.md b/docs/api/api.md
index e0a9e8fc..ef89c222 100755
--- a/docs/api/api.md
+++ b/docs/api/api.md
@@ -166,3 +166,115 @@ curl -XGET http://<docker.host.ip:saga.port>/events
 ####  Status codes
 -   **200** – no error
 
+### Invoke embedded Saga to execute SQL transaction
+
+In order to Invoke embedded saga, it is necessary to add dependencies to your applications.
+
+There are a `maven` example
+
+```
+<dependencies>
+
+    ...
+    
+    <dependency>
+        <groupId>org.apache.servicecomb.saga</groupId>
+        <artifactId>saga-core</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>org.apache.servicecomb.saga</groupId>
+        <artifactId>saga-format</artifactId>
+    </dependency>
+    
+    ...
+    
+</dependencies>
+```
+
+####  Description
+    
+1. Implement SQLTransport interface in your own applications.
+
+2. Instance `SagaExecutionComponent` and inject it into your own applications.
+
+3. Define requests in order and recovery policy by JSON format as below in your applications.
+
+```
+{
+  "policy": "",
+  "requests": [
+    {
+      "id": "",
+      "type": "",
+      "datasource": "",
+      "parents": [
+
+      ],
+      "transaction": {
+        "sql": "",
+        "params": [
+
+        ]
+      },
+      "compensation": {
+        "sql": "",
+        "params": [
+
+        ]
+      }
+    }
+  ]
+}
+```
+JSON parameters:
+- policy - support `BackwardRecovery` or `ForwardRecovery`.
+- requests - transactions array.
+  - id - request id. It should be unique among this collection of requests.
+  - type - support `sql` for now.
+  - datasource - user-defined datasource name.
+  - parents - request ids. It means this request is only executed after all requests in the parents field are completed.
+  - transaction - user-defined transaction that executed by the Saga.
+    - sql - user-defined, forward sql.
+    - params - parameters for forward sql.
+  - compensation - user-defined compensation that executed by the Saga.
+    - sql - user-defined, backward sql.
+    - params - parameters for backward sql.
+
+4. Invoke `SagaExecutionComponent.run(String json)` function to execute saga.
+
+#### Example Implement SQLTransport interface
+
+```
+public class ExampleSQLTransport implements SQLTransport {
+  @Override
+  public SagaResponse with(final String datasource, final String sql, final List<String> params) {
+    try {
+      // invoke your own code to execute sql.
+    } catch (Exception e) {
+      throw new TransportFailedException("execute SQL " + sql + " occur exception: ", e);
+    }
+    return new JsonSuccessfulSagaResponse("{}");
+  }
+}
+```
+
+#### Example Instance `SagaExecutionComponent`
+
+```
+  private final SQLTransport sqlTransport = new ExampleSQLTransport;
+
+  private final TransportFactory<SQLTransport> transportFactory = new TransportFactory<SQLTransport>() {
+    @Override
+    public SQLTransport getTransport() {
+      return sqlTransport;
+    }
+  };
+
+  private final SagaExecutionComponent coordinator = new SagaExecutionComponent(
+      new EmbeddedPersistentStore(),
+      new JacksonFromJsonFormat(transportFactory),
+      null,
+      new GraphBasedSagaFactory(500, eventStore, new ChildrenExtractor(), Executors.newFixedThreadPool(5))
+  );
+```
+


 

----------------------------------------------------------------
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:
users@infra.apache.org


With regards,
Apache Git Services