From 0cb6766869c5ca666098fa79e348a3b9bef5b39b Mon Sep 17 00:00:00 2001
From: MregXN <mregxn@gmail.com>
Date: Wed, 22 Nov 2023 23:11:35 +0800
Subject: [PATCH] add description of workflow sample

Signed-off-by: MregXN <mregxn@gmail.com>
---
 .../java/io/dapr/examples/workflows/README.md | 69 ++++++++++++++++++-
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/examples/src/main/java/io/dapr/examples/workflows/README.md b/examples/src/main/java/io/dapr/examples/workflows/README.md
index d24d3f74a9..8c268c6141 100644
--- a/examples/src/main/java/io/dapr/examples/workflows/README.md
+++ b/examples/src/main/java/io/dapr/examples/workflows/README.md
@@ -46,7 +46,7 @@ Run `dapr init` to initialize Dapr in Self-Hosted Mode if it's not already initi
 
 ### Running the demo Workflow worker
 
-The first Java class to consider is `DemoWorkflowWorker`. It's job is to register an implementation of `DemoWorkflow` in Dapr's workflow runtime engine. In the `DemoWorkflowWorker.java` file, you will find the `DemoWorkflowWorker` class and the `main` method. See the code snippet below:
+The first Java class to consider is `DemoWorkflowWorker`. Its job is to register an implementation of `DemoWorkflow` in Dapr's workflow runtime engine. In the `DemoWorkflowWorker.java` file, you will find the `DemoWorkflowWorker` class and the `main` method. See the code snippet below:
 
 ```java
 public class DemoWorkflowWorker {
@@ -65,6 +65,71 @@ This application uses `WorkflowRuntime.getInstance().registerWorkflow()` in orde
 
 The `WorkflowRuntime.getInstance().start()` method will build and start the engine within the Dapr workflow runtime.
 
+The Workflow class `DemoWorkflow` extends from `Workflow` and is responsible for implementing the logic for creating and running workflows.
+
+```java
+public abstract class Workflow {
+  public Workflow(){
+  }
+
+  /**
+   * Executes the workflow logic.
+   *
+   * @return A WorkflowStub.
+   */
+  public abstract WorkflowStub create();
+
+  /**
+   * Executes the workflow logic.
+   *
+   * @param ctx provides access to methods for scheduling durable tasks and getting information about the current
+   *            workflow instance.
+   */
+  public void run(WorkflowContext ctx) {
+    this.create().run(ctx);
+  }
+}
+
+```
+The running logic of the `DemoWorkflow` is to run its create method. And the `create()` method can devide into six parts:
+- wait for `TimedOutEvent`
+- wait for `TestEvent`
+- wait for external event and all tasks to finish
+- wait for external event and any task to finish
+- call activity `DemoWorkflowActivity` which is registered in `DemoWorkflowWorker`
+- wait for `restartEvent` (if not received it will call child workflow and return)
+
+The Activity class `DemoWorkflowActivity` is an implementation of `WorkflowActivity` interface, which contains a `run` method. This activity modify the input message, sleeps 5 seconds and then passes the new message as output.
+
+```java
+@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY)
+public class DemoWorkflowActivity implements WorkflowActivity {
+
+  @Override
+  public DemoActivityOutput run(WorkflowActivityContext ctx) {
+	...
+
+    var message = ctx.getInput(DemoActivityInput.class).getMessage();
+    var newMessage = message + " World!, from Activity";
+	...
+
+    try {
+      TimeUnit.SECONDS.sleep(5);
+    } catch (InterruptedException e) {
+      throw new RuntimeException(e);
+    }
+
+	...
+    var output = new DemoActivityOutput(message, newMessage);
+	...
+
+    return output;
+  }
+}
+```
+
+The `DemoSubWorkflow` class is a child workflow that prints some metadata and its input message.
+
 Now, execute the following script in order to run DemoWorkflowWorker:
 ```sh
 dapr run --app-id demoworkflowworker --resources-path ./components/workflows --dapr-grpc-port 50001 -- java -jar target/dapr-java-sdk-examples-exec.jar io.dapr.examples.workflows.DemoWorkflowWorker
@@ -72,7 +137,7 @@ dapr run --app-id demoworkflowworker --resources-path ./components/workflows --d
 
 ### Running the Workflow client
 
-The `DemoWorkflowClient` starts instances of workflows that have been registered with Dapr.
+A DaprWorkflowClient can manage Dapr workflow instances. The `DemoWorkflowClient` starts instances of workflows that have been registered with Dapr, raises events the workflow are waiting and finally terminates the instances.
 
 With the DemoWorkflowWorker running, use the follow command to start the workflow with the DemoWorkflowClient: