[KOGITO-9454] Documenting java flow library

serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc

@@ -0,0 +1,105 @@
+= Workflow embedded execution in Java 
+
+This guide show cases how to execute a link:{spec_doc_url}[CNCF Serverless Workflow] definition using a standard java virtual machine and a small set of Maven dependencies. 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 programatically defined using the {product_name} fluent API. 
+
+[[embedded-file-quick-start]]
+== Hello world (using existing definition file)
+
+First step is to setup an empty Maven project with the following dependency
+
+[source,xml]
+----
+<dependency>
+  <groupId>org.kie.kogito</groupId>
+  <artifactId>kogito-serverless-workflow-executor</artifactId>
+  <version>RELEASE</version>
+  <type>pom</type>
+</dependency>
+----
+
+Also, you might optionally add `simple logger for java` dependency to avoid using `system.out.println`
+
+[source,xml]
+----
+ <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-simple</artifactId>
+      <version>1.7.36</version>
+  </dependency>
+----
+
+Lets assume you already have a workflow definition written in a JSON file in your project root. For example, link:{kogito_sw_examples_url}/serverless-workflow-hello-world/src/main/resources/hello.sw.json[Hello World] definition. In order to execute it, you need to write the following main java class (standard imports and java package declaration are intentionally skipped for brevity)
+
+[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 than in the previous section, you can programatically generate that workflow definition rather than loading it from a file definition by using 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 in a way that generates exactly the same output when it is executed, but rather 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
+
+
+== Additional resources
+
+You can find additional and commented examples of fluent API usage (including jq expression evaluation and orchestation of rest services) link:https://github.com/fjtirado/java-flow/tree/main/java-flow-example/src/main/java/org/kie/kogito/serverless/workflow/examples[here]
+
+include::../../pages/_common-content/report-issue.adoc[]
+
+ifeval::["{kogito_version_redhat}" != ""]
+include::../../pages/_common-content/downstream-project-setup-instructions.adoc[]
+endif::[]

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