[KOGITO-9454] Documenting java flow library (#585)

* [KOGITO-9454] Documenting java flow library * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <[email protected]> * [KOGITO-9454] Minor correction * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Dominik Hanák <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Dominik Hanák <[email protected]> * [KOGITO-9454] Dominik comments * [KOGITO-9454] Update example reference --------- Co-authored-by: Kalyani Desai <[email protected]> Co-authored-by: Dominik Hanák <[email protected]>
apache · Mar 21, 2024 · 381da7c · 381da7c
1 parent b07a8ce
commit 381da7c
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 0 deletions.
diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml
@@ -135,3 +135,4 @@ asciidoc:
     workflow_instance: workflow instance
     workflow_instances: workflow instances
     sonataflow_devmode_devui_url: /q/dev/org.kie.kogito.kogito-quarkus-serverless-workflow-devui/
+    swf_executor_core_maven_repo: https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-core
diff --git a/serverlessworkflow/modules/ROOT/nav.adoc b/serverlessworkflow/modules/ROOT/nav.adoc
@@ -23,6 +23,7 @@
 * Getting Started
 ** xref:getting-started/getting-familiar-with-our-tooling.adoc[]
 ** xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[]
+** xref:getting-started/java-embedded-workflows.adoc[]
 * Core Concepts
 ** xref:core/cncf-serverless-workflow-specification-support.adoc[]
 ** xref:core/handling-events-on-workflows.adoc[Events]

diff --git a/serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc b/serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc
@@ -0,0 +1,91 @@
+= Workflow embedded execution in Java 
+
+This guide uses a standard Java virtual machine and a small set of Maven dependencies to execute a link:{spec_doc_url}[CNCF Serverless Workflow] definition. Therefore, it is assumed you are fluent both in Java and Maven. 
+The workflow definition to be executed can be read from a `.json` or `.yaml` file or programmatically defined using the {product_name} fluent API. 
+.Prerequisites
+. Install https://openjdk.org/[OpenJDK] {java_min_version} 
+. Install https://maven.apache.org/index.html[Apache Maven] {maven_min_version}.
+
+[[embedded-file-quick-start]]
+== Hello world (using existing definition file)
+
+The first step is to set up an empty Maven project that includes link:{swf_executor_core_maven_repo}[Workflow executor core] dependency.
+
+This guide also uses [slf4j dependency](https://mvnrepository.com/artifact/org.slf4j/slf4j-simple) to avoid using `System.out.println`
+
+Let's assume you already have a workflow definition written in a JSON file in your project root directory. For example, link:{kogito_sw_examples_url}/serverless-workflow-hello-world/src/main/resources/hello.sw.json[Hello World] definition. To execute it, you must write the following main Java class (standard Java imports and package declaration are intentionally skipped for briefness)
+
+[source,java]
+----
+import org.kie.kogito.serverless.workflow.executor.StaticWorkflowApplication;
+import org.kie.kogito.serverless.workflow.models.JsonNodeModel;
+import org.kie.kogito.serverless.workflow.utils.ServerlessWorkflowUtils;
+import org.kie.kogito.serverless.workflow.utils.WorkflowFormat;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import io.serverlessworkflow.api.Workflow;
+
+public class DefinitionFileExecutor {
+    private static final Logger logger = LoggerFactory.getLogger(DefinitionFileExecutor.class);
+
+    public static void main(String[] args) throws IOException {
+        try (Reader reader = new FileReader("hello.sw.json"); <1>
+                StaticWorkflowApplication application = StaticWorkflowApplication.create()) { <2>
+            Workflow workflow = ServerlessWorkflowUtils.getWorkflow(reader, WorkflowFormat.JSON); <3>
+            JsonNodeModel result = application.execute(workflow, Collections.emptyMap()); <4>
+            logger.info("Workflow execution result is {}", result.getWorkflowdata()); <5>
+        }
+    }
+}
+----
+<1> Reads the workflow file definition from the project root directory
+<2> Creates a static workflow application object. It is done within the try block since the instance is `Closeable`. This is the reference that allow you to execute workflow definitions.
+<3> Reads the Serverless Workflow Java SDK `Workflow` object from the file. 
+<4> Execute the workflow, passing `Workflow` reference and no parameters (an empty Map). The result of the workflow execution: process instance id and workflow output model, can accessed using `result` variable. 
+<5> Prints the workflow model in the configured standard output. 
+
+If you compile and execute this Java class, you will see the following log in your configured standard output:
+----
+Workflow execution result is {"greeting":"Hello World","mantra":"Serverless Workflow is awesome!"}
+----
+
+[[embedded-fluent-quick-start]]
+== Hello world (using fluent API)
+
+Using the same Maven setup as in the previous section, you can programmatically generate that workflow definition rather than loading it from a file definition by using the link:{kogito_runtimes_url}/kogito-serverless-workflow/kogito-serverless-workflow-fluent/src/main/java/org/kie/kogito/serverless/workflow/fluent[fluent API]
+
+Therefore, you can modify the previous example to generate the same output when it is executed, but rather than creating a `FileReader` that reads the `Workflow` object, we create the `Workflow` object using Java statements. The resulting modified main method is the following
+
+[source,java]
+----
+      try (StaticWorkflowApplication application = StaticWorkflowApplication.create()) {
+            Workflow workflow = workflow("HelloWorld"). <1>
+            		start( <2>
+            				inject( <3>
+            						jsonObject().put("greeting", "Hello World").put("mantra","Serverless Workflow is awesome!"))) <4>
+            		.end() <5>
+            		.build(); <6>
+            logger.info("Workflow execution result is {}",application.execute(workflow, Collections.emptyMap()).getWorkflowdata());  <7>
+        }
+----
+<1> Creates a workflow which name is `HelloWorld`
+<2> Indicate that you are going to specify the start state
+<3> A Inject state is the start state
+<4> Inject state accepts static json, therefore this line creates the JSON data
+<5> End the workflow definition 
+<6> Build the workflow definition
+<7> Execute and print as in previous example
+
+
+== Further reading
+
+You can find additional and commented examples of fluent API usage (including jq expression evaluation and orchestration of rest services) link:{{kogito_sw_examples_url}/sonataflow-fluent[here]
+
+== Additional resources
+
+include::../../pages/_common-content/report-issue.adoc[]
+
+ifeval::["{kogito_version_redhat}" != ""]
+include::../../pages/_common-content/downstream-project-setup-instructions.adoc[]
+endif::[]
diff --git a/serverlessworkflow/modules/ROOT/pages/index.adoc b/serverlessworkflow/modules/ROOT/pages/index.adoc
@@ -54,6 +54,14 @@ xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.a
 An all-in-one starting guide. Learn how to create, run & deploy your first {product_name} project on your local environment.
 --
 
+[.card]
+--
+[.card-title]
+xref:getting-started/java-embedded-workflows.adoc[]
+[.card-description]
+Learn about how to executed your workflows (existing files or define them programatically) using Java and Maven.
+--
+
 [.card-section]
 == Core Concepts