From 381da7c5d217995839afccb987c961bcfc606945 Mon Sep 17 00:00:00 2001 From: Francisco Javier Tirado Sarti <65240126+fjtirado@users.noreply.github.com> Date: Thu, 21 Mar 2024 15:35:26 +0100 Subject: [PATCH] [KOGITO-9454] Documenting java flow library (#585) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [KOGITO-9454] Documenting java flow library * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> * [KOGITO-9454] Minor correction * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Dominik Hanák * Update serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc Co-authored-by: Dominik Hanák * [KOGITO-9454] Dominik comments * [KOGITO-9454] Update example reference --------- Co-authored-by: Kalyani Desai <43639538+kaldesai@users.noreply.github.com> Co-authored-by: Dominik Hanák --- serverlessworkflow/antora.yml | 1 + serverlessworkflow/modules/ROOT/nav.adoc | 1 + .../java-embedded-workflows.adoc | 91 +++++++++++++++++++ .../modules/ROOT/pages/index.adoc | 8 ++ 4 files changed, 101 insertions(+) create mode 100644 serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml index a92f79b68..0aff48584 100644 --- 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 index 0daa1601b..4bf331243 100644 --- 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 new file mode 100644 index 000000000..575b289c9 --- /dev/null +++ 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::[] \ No newline at end of file diff --git a/serverlessworkflow/modules/ROOT/pages/index.adoc b/serverlessworkflow/modules/ROOT/pages/index.adoc index dd64217f4..2797c1ff4 100644 --- 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