Merge pull request #3662 from hhunter-ms/issue_3567

[docs] Workflow docs for Java SDK
dapr · Sep 25, 2023 · 4d57fbe · 4d57fbe
2 parents 87ee428 + c905d41
commit 4d57fbe
Show file tree

Hide file tree

Showing 10 changed files with 1,219 additions and 503 deletions.
diff --git a/daprdocs/content/en/concepts/building-blocks-concept.md b/daprdocs/content/en/concepts/building-blocks-concept.md
@@ -28,5 +28,5 @@ Dapr provides the following building blocks:
 | [**Secrets**]({{< ref "secrets-overview.md" >}}) | `/v1.0/secrets` | Dapr provides a secrets building block API and integrates with secret stores such as public cloud stores, local stores and Kubernetes to store the secrets. Services can call the secrets API to retrieve secrets, for example to get a connection string to a database.
 | [**Configuration**]({{< ref "configuration-api-overview.md" >}}) | `/v1.0/configuration` | The Configuration API enables you to retrieve and subscribe to application configuration items for supported configuration stores. This enables an application to retrieve specific configuration information, for example, at start up or when configuration changes are made in the store. 
 | [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}}) | `/v1.0-alpha1/lock` | The distributed lock API enables you to take a lock on a resource so that multiple instances of an application can access the resource without conflicts and provide consistency guarantees.  
-| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-alpha1/workflow` | The Workflow API enables you to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components. The Workflow API can be combined with other Dapr API building blocks. For example, a workflow can call another service with service invocation or retrieve secrets, providing flexibility and portability. 
+| [**Workflows**]({{< ref "workflow-overview.md" >}}) | `/v1.0-beta1/workflow` | The Workflow API enables you to define long running, persistent processes or data flows that span multiple microservices using Dapr workflows or workflow components. The Workflow API can be combined with other Dapr API building blocks. For example, a workflow can call another service with service invocation or retrieve secrets, providing flexibility and portability. 
 | [**Cryptography**]({{< ref "cryptography-overview.md" >}}) | `/v1.0-alpha1/crypto` | The Cryptography API enables you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your application.
diff --git a/...nt/en/developing-applications/building-blocks/workflow/howto-author-workflow.md b/...nt/en/developing-applications/building-blocks/workflow/howto-author-workflow.md
@@ -6,6 +6,10 @@ weight: 5000
 description: "Learn how to develop and author workflows"
 ---
 
+{{% alert title="Note" color="primary" %}}
+Dapr Workflow is currently in beta. [See known limitations for {{% dapr-latest-version cli="true" %}}]({{< ref "workflow-overview.md#limitations" >}}).
+{{% /alert %}}
+
 This article provides a high-level overview of how to author workflows that are executed by the Dapr Workflow engine.
 
 {{% alert title="Note" color="primary" %}}
@@ -30,7 +34,25 @@ The Dapr sidecar doesn’t load any workflow definitions. Rather, the sidecar si
 
 [Workflow activities]({{< ref "workflow-features-concepts.md#workflow-activites" >}}) are the basic unit of work in a workflow and are the tasks that get orchestrated in the business process.
 
-{{< tabs ".NET" Python >}}
+{{< tabs Python ".NET" Java >}}
+
+{{% codetab %}}
+
+<!--python-->
+
+Define the workflow activities you'd like your workflow to perform. Activities are a function definition and can take inputs and outputs. The following example creates a counter (activity) called `hello_act` that notifies users of the current counter value. `hello_act` is a function derived from a class called `WorkflowActivityContext`.
+
+```python
+def hello_act(ctx: WorkflowActivityContext, input):
+    global counter
+    counter += input
+    print(f'New counter value is: {counter}!', flush=True)
+```
+
+[See the `hello_act` workflow activity in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL40C1-L43C59)
+
+
+{{% /codetab %}}
 
 {{% codetab %}}
 
@@ -102,29 +124,76 @@ public class ProcessPaymentActivity : WorkflowActivity<PaymentRequest, object>
 
 {{% codetab %}}
 
-<!--python-->
+<!--java-->
 
-Define the workflow activities you'd like your workflow to perform. Activities are a function definition and can take inputs and outputs. The following example creates a counter (activity) called `hello_act` that notifies users of the current counter value. `hello_act` is a function derived from a class called `WorkflowActivityContext`.
+Define the workflow activities you'd like your workflow to perform. Activities are wrapped in the public `DemoWorkflowActivity` class, which implements the workflow activities. 
 
-```python
-def hello_act(ctx: WorkflowActivityContext, input):
-    global counter
-    counter += input
-    print(f'New counter value is: {counter}!', flush=True)
-```
+```java
+@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY)
+public class DemoWorkflowActivity implements WorkflowActivity {
 
-[See the `hello_act` workflow activity in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL40C1-L43C59)
+  @Override
+  public DemoActivityOutput run(WorkflowActivityContext ctx) {
+    Logger logger = LoggerFactory.getLogger(DemoWorkflowActivity.class);
+    logger.info("Starting Activity: " + ctx.getName());
 
+    var message = ctx.getInput(DemoActivityInput.class).getMessage();
+    var newMessage = message + " World!, from Activity";
+    logger.info("Message Received from input: " + message);
+    logger.info("Sending message to output: " + newMessage);
+
+    logger.info("Sleeping for 5 seconds to simulate long running operation...");
+
+    try {
+      TimeUnit.SECONDS.sleep(5);
+    } catch (InterruptedException e) {
+      throw new RuntimeException(e);
+    }
+
+
+    logger.info("Activity finished");
+
+    var output = new DemoActivityOutput(message, newMessage);
+    logger.info("Activity returned: " + output);
+
+    return output;
+  }
+}
+```
+
+[See the Java SDK workflow activity example in context.](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflowActivity.java)
 
 {{% /codetab %}}
 
+
 {{< /tabs >}}
 
 ## Write the workflow
 
 Next, register and call the activites in a workflow. 
 
-{{< tabs ".NET" Python >}}
+{{< tabs Python ".NET" Java >}}
+
+{{% codetab %}}
+
+<!--python-->
+
+The `hello_world_wf` function is derived from a class called `DaprWorkflowContext` with input and output parameter types. It also includes a `yield` statement that does the heavy lifting of the workflow and calls the workflow activities. 
+
+```python
+def hello_world_wf(ctx: DaprWorkflowContext, input):
+    print(f'{input}')
+    yield ctx.call_activity(hello_act, input=1)
+    yield ctx.call_activity(hello_act, input=10)
+    yield ctx.wait_for_external_event("event1")
+    yield ctx.call_activity(hello_act, input=100)
+    yield ctx.call_activity(hello_act, input=1000)
+```
+
+[See the `hello_world_wf` workflow in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL32C1-L38C51)
+
+
+{{% /codetab %}}
 
 {{% codetab %}}
 
@@ -171,103 +240,42 @@ The `OrderProcessingWorkflow` class is derived from a base class called `Workflo
 
 {{% codetab %}}
 
-<!--python-->
-
-The `hello_world_wf` function is derived from a class called `DaprWorkflowContext` with input and output parameter types. It also includes a `yield` statement that does the heavy lifting of the workflow and calls the workflow activities. 
-
-```python
-def hello_world_wf(ctx: DaprWorkflowContext, input):
-    print(f'{input}')
-    yield ctx.call_activity(hello_act, input=1)
-    yield ctx.call_activity(hello_act, input=10)
-    yield ctx.wait_for_external_event("event1")
-    yield ctx.call_activity(hello_act, input=100)
-    yield ctx.call_activity(hello_act, input=1000)
-```
-
-[See the `hello_world_wf` workflow in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL32C1-L38C51)
-
-
-{{% /codetab %}}
+<!--java-->
 
-{{< /tabs >}}
+Next, register the workflow with the `WorkflowRuntimeBuilder` and start the workflow runtime.
 
-## Write the application
+```java
+public class DemoWorkflowWorker {
 
-Finally, compose the application using the workflow.
+  public static void main(String[] args) throws Exception {
 
-{{< tabs ".NET" Python >}}
+    // Register the Workflow with the builder.
+    WorkflowRuntimeBuilder builder = new WorkflowRuntimeBuilder().registerWorkflow(DemoWorkflow.class);
+    builder.registerActivity(DemoWorkflowActivity.class);
 
-{{% codetab %}}
-
-<!--csharp-->
-
-[In the following `Program.cs` example](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Program.cs), for a basic ASP.NET order processing application using the .NET SDK, your project code would include:
-
-- A NuGet package called `Dapr.Workflow` to receive the .NET SDK capabilities
-- A builder with an extension method called `AddDaprWorkflow`
-  - This will allow you to register workflows and workflow activities (tasks that workflows can schedule)
-- HTTP API calls
-  - One for submitting a new order
-  - One for checking the status of an existing order
-
-```csharp
-using Dapr.Workflow;
-//...
+    // Build and then start the workflow runtime pulling and executing tasks
+    try (WorkflowRuntime runtime = builder.build()) {
+      System.out.println("Start workflow runtime");
+      runtime.start();
+    }
 
-// Dapr Workflows are registered as part of the service configuration
-builder.Services.AddDaprWorkflow(options =>
-{
-    // Note that it's also possible to register a lambda function as the workflow
-    // or activity implementation instead of a class.
-    options.RegisterWorkflow<OrderProcessingWorkflow>();
+    System.exit(0);
+  }
+}
+```
 
-    // These are the activities that get invoked by the workflow(s).
-    options.RegisterActivity<NotifyActivity>();
-    options.RegisterActivity<ReserveInventoryActivity>();
-    options.RegisterActivity<ProcessPaymentActivity>();
-});
+[See the Java SDK workflow in context.](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflowWorker.java)
 
-WebApplication app = builder.Build();
 
-// POST starts new order workflow instance
-app.MapPost("/orders", async (WorkflowEngineClient client, [FromBody] OrderPayload orderInfo) =>
-{
-    if (orderInfo?.Name == null)
-    {
-        return Results.BadRequest(new
-        {
-            message = "Order data was missing from the request",
-            example = new OrderPayload("Paperclips", 99.95),
-        });
-    }
-
-//...
-});
-
-// GET fetches state for order workflow to report status
-app.MapGet("/orders/{orderId}", async (string orderId, WorkflowEngineClient client) =>
-{
-    WorkflowState state = await client.GetWorkflowStateAsync(orderId, true);
-    if (!state.Exists)
-    {
-        return Results.NotFound($"No order with ID = '{orderId}' was found.");
-    }
+{{% /codetab %}}
 
-    var httpResponsePayload = new
-    {
-        details = state.ReadInputAs<OrderPayload>(),
-        status = state.RuntimeStatus.ToString(),
-        result = state.ReadOutputAs<OrderResult>(),
-    };
+{{< /tabs >}}
 
-//...
-}).WithName("GetOrderInfoEndpoint");
+## Write the application
 
-app.Run();
-```
+Finally, compose the application using the workflow.
 
-{{% /codetab %}}
+{{< tabs Python ".NET" Java >}}
 
 {{% codetab %}}
 
@@ -356,6 +364,124 @@ if __name__ == '__main__':
 ```
 
 
+{{% /codetab %}}
+
+{{% codetab %}}
+
+<!--csharp-->
+
+[In the following `Program.cs` example](https://github.com/dapr/dotnet-sdk/blob/master/examples/Workflow/WorkflowConsoleApp/Program.cs), for a basic ASP.NET order processing application using the .NET SDK, your project code would include:
+
+- A NuGet package called `Dapr.Workflow` to receive the .NET SDK capabilities
+- A builder with an extension method called `AddDaprWorkflow`
+  - This will allow you to register workflows and workflow activities (tasks that workflows can schedule)
+- HTTP API calls
+  - One for submitting a new order
+  - One for checking the status of an existing order
+
+```csharp
+using Dapr.Workflow;
+//...
+
+// Dapr Workflows are registered as part of the service configuration
+builder.Services.AddDaprWorkflow(options =>
+{
+    // Note that it's also possible to register a lambda function as the workflow
+    // or activity implementation instead of a class.
+    options.RegisterWorkflow<OrderProcessingWorkflow>();
+
+    // These are the activities that get invoked by the workflow(s).
+    options.RegisterActivity<NotifyActivity>();
+    options.RegisterActivity<ReserveInventoryActivity>();
+    options.RegisterActivity<ProcessPaymentActivity>();
+});
+
+WebApplication app = builder.Build();
+
+// POST starts new order workflow instance
+app.MapPost("/orders", async (WorkflowEngineClient client, [FromBody] OrderPayload orderInfo) =>
+{
+    if (orderInfo?.Name == null)
+    {
+        return Results.BadRequest(new
+        {
+            message = "Order data was missing from the request",
+            example = new OrderPayload("Paperclips", 99.95),
+        });
+    }
+
+//...
+});
+
+// GET fetches state for order workflow to report status
+app.MapGet("/orders/{orderId}", async (string orderId, WorkflowEngineClient client) =>
+{
+    WorkflowState state = await client.GetWorkflowStateAsync(orderId, true);
+    if (!state.Exists)
+    {
+        return Results.NotFound($"No order with ID = '{orderId}' was found.");
+    }
+
+    var httpResponsePayload = new
+    {
+        details = state.ReadInputAs<OrderPayload>(),
+        status = state.RuntimeStatus.ToString(),
+        result = state.ReadOutputAs<OrderResult>(),
+    };
+
+//...
+}).WithName("GetOrderInfoEndpoint");
+
+app.Run();
+```
+
+{{% /codetab %}}
+
+{{% codetab %}}
+
+<!--java-->
+
+[As in the following example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflow.java), a hello-world application using the Java SDK and Dapr Workflow would include:
+
+- A Java package called `io.dapr.workflows.client` to receive the Java SDK client capabilities.
+- An import of `io.dapr.workflows.Workflow`
+- The `DemoWorkflow` class which extends `Workflow`
+- Creating the workflow with input and output.
+- API calls. In the example below, these calls start and call the workflow activities.
+
+```java
+package io.dapr.examples.workflows;
+
+import com.microsoft.durabletask.CompositeTaskFailedException;
+import com.microsoft.durabletask.Task;
+import com.microsoft.durabletask.TaskCanceledException;
+import io.dapr.workflows.Workflow;
+import io.dapr.workflows.WorkflowStub;
+
+import java.time.Duration;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Implementation of the DemoWorkflow for the server side.
+ */
+public class DemoWorkflow extends Workflow {
+  @Override
+  public WorkflowStub create() {
+    return ctx -> {
+      ctx.getLogger().info("Starting Workflow: " + ctx.getName());
+      // ...
+      ctx.getLogger().info("Calling Activity...");
+      var input = new DemoActivityInput("Hello Activity!");
+      var output = ctx.callActivity(DemoWorkflowActivity.class.getName(), input, DemoActivityOutput.class).await();
+      // ...
+    };
+  }
+}
+```
+
+[See the full Java SDK workflow example in context.](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/workflows/DemoWorkflow.java)
+
 {{% /codetab %}}
 
 
@@ -377,5 +503,6 @@ Now that you've authored a workflow, learn how to manage it.
 - [Workflow overview]({{< ref workflow-overview.md >}})
 - [Workflow API reference]({{< ref workflow_api.md >}})
 - Try out the full SDK examples:
-  - [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
   - [Python example](https://github.com/dapr/python-sdk/tree/master/examples/demo_workflow)
+  - [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
+  - [Java example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows)