[GitHub] [servicecomb-pack] zhfeng commented on a change in pull request #510: [SCB-1389] write docs for explicit passing transaction context

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

zhfeng commented on a change in pull request #510: [SCB-1389] write docs for explicit passing transaction context
URL: https://github.com/apache/servicecomb-pack/pull/510#discussion_r306151569
 
 

 ##########
 File path: docs/user_guide.md
 ##########
 @@ -111,7 +111,108 @@ Take a transfer money application as an example:
 
 5. Since pack-0.3.0,  you can access the [OmegaContext](https://github.com/apache/servicecomb-pack/blob/master/omega/omega-context/src/main/java/org/apache/servicecomb/pack/omega/context/OmegaContext.java) for the gloableTxId and localTxId in the @Compensable annotated method or the cancel method.
 
+#### Passing transaction context explicitly
+
+In most cases, Omega passing the transaction context for you transparently (see [Inter-Service Communication](design.md#comm) for details). Transaction context passing is implemented in a way of injecting transaction context information on the sender side and extracting it on the receiver side. Below is an example to illustrate this process:
+
+Service A:
+
+```java
+@SagaStart
+public void foo() {
+  restTemplate.postForEntity("http://service-b/bar", ...);
+}
+```
+
+Service B:
+
+```java
+@GetMapping("/bar")
+@Compensable
+public void bar() {
+  ...
+}
+```
+
+Here is how Omega does:
+
+1. Service A's `foo` method opens a new global transaction.
+2. `TransactionClientHttpRequestInterceptor` injects transaction context into request headers when `RestTemplate` request Service B.
+3. When Service B receive the request, `TransactionHandlerInterceptor` extract context info from request headers.
+
+Omega supports following implicity transaction context passing:
+
+1. omega-transport-{dubbo,feign,resttemplate,servicecomb}.
+2. Method call in the same thread (based on `OmegaContext` thread local fields).
+3. `java.util.concurrent.Executor{Service}` annotated by `@OmegaContextAware`.
+
+So here comes a problem: what if implicit transaction context passing can't work? For example, Service A invokes Service B via some RPC library and no extension can be made to injecting or extracting transaction context information. In this situation you need explicit transaction context passing. Omega provides two classes to achieve that.
+
+##### TransactionContext
+
+Service A:
+
+```java
+@SagaStart
+public void foo(BarCommand cmd) {
+  TransactionContext txContext = omegaContext.getTransactionContext();
+  someRpc.send(cmd, txContext);
+}
+```
+
+Service B:
+
+```java
+public void listen(BarCommand cmd, TransactionContext parentTxContext) {
+  bar(cmd, txContext);
+}
+@Compensable
+public void bar(BarCommand cmd, TransactionContext parentTxContext) {
+  ...
+  // TransactionContext childTxContext = omegaContext.getTransactionContext();
+}
+```
+
+Notice that `bar` method got parent transaction context in parameter list, and got child transaction context from `OmegaContext` in method body. So if you want to passing transaction context to another service, you should pass child transaction context.
+
 
 Review comment:
   The pack does not support the nested transaction right now. see [SCB-836](https://issues.apache.org/jira/browse/SCB-836) and I raised the https://github.com/apache/servicecomb-pack/pull/432 but it did not finish. So I think we could add a note here and reference to the SCB-836.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to 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