[Fix serverlessworkflow#520] Updating readme

Signed-off-by: Francisco Javier Tirado Sarti <[email protected]>

README.md

@@ -8,11 +8,11 @@ Provides the Java API for the [Serverless Workflow Specification](https://github
 With the SDK you can:
 
 * Read workflow JSON and YAML definitions
-* Write workflow in JSON and YAML format. 
+* Write workflow definition in JSON and YAML format. 
+* Test your workflow definitions using the reference implementation. 
 
-Serverless Workflow Java SDK is **not** a workflow runtime implementation but can be used by Java runtime implementations to parse workflow definitions.
 
-### Status
+## Status
 
 | Latest Releases | Conformance to spec version |
 | :---: | :---: |
@@ -25,17 +25,17 @@ Serverless Workflow Java SDK is **not** a workflow runtime implementation but ca
 
 Note that 6.0.0.Final, which will be the one for specification version 0.9, is skipped intentionally in case someone want to work on it. 
 
-### JDK Version
+## JDK Version
 
 | SDK Version | JDK Version |
 | :---: | :---: |
 | 5.0.0 and after | 11 |
 | 4.0.x and before | 8 | 
 
-### Getting Started
+## Getting Started
 
 
-#### Building SNAPSHOT locally
+### Building SNAPSHOT locally
 
 To build project and run tests locally:
 
@@ -47,7 +47,7 @@ mvn clean install
 The project uses [Google's code styleguide](https://google.github.io/styleguide/javaguide.html).
 Your changes should be automatically formatted during the build.
 
-#### Maven projects:
+### Maven projects:
 
 Add the following dependencies to your pom.xml `dependencies` section:
 
@@ -59,19 +59,28 @@ Add the following dependencies to your pom.xml `dependencies` section:
 </dependency>
 ```
 
-#### Gradle projects:
+### Gradle projects:
 
  Add the following dependencies to your build.gradle `dependencies` section:
 
 ```text
 implementation("io.serverlessworkflow:serverlessworkflow-api:7.0.0-SNAPSHOT")
 ```
 
-### How to Use 
+## How to Use 
 
-#### Creating from JSON/YAML source
+There are, roughly speaking, two kind of users of this SDK:
+ * Those ones interested on implementing their own runtime using Java.
+ * Those ones interested on using the provided runtime reference implementation. 
 
-You can create a Workflow instance from JSON/YAML source:
+### Implementing your own runtime 
+
+For those ones interested on implementing their own runtime, this SDK provides an easy way to load an in memory representation of a given workflow definition.
+This memory representation consist of a hierarchy of POJOS directly generated from the Serverless Workflow specification [schema](api/src/main/resources/schema/workflow.yaml), which ensures the internal representation is aligned with the specification schema. The root of the hierarchy is `io.serverlessworkflow.api.types.Workflow` class
+
+#### Reading workflow definition from JSON/YAML source
+
+You can read a Workflow definition from JSON/YAML source:
 
 Let's say you have a simple YAML based workflow definition in a file name `simple.yaml` located in your working dir:
 
@@ -93,7 +102,7 @@ do:
 
 ```
 
-To parse it and create a Workflow instance you can do:
+To parse it and get a Workflow instance you can do:
 
 ``` java
 
@@ -102,15 +111,30 @@ try (InputStream in = new FileInputStream("simple.yaml")) {
    // Once you have the Workflow instance you can use its API to inspect it
 }
 ```
+By default, Workflows are not validated against the schema (performance being the priority). If you want to enable validation, you can do that by using: 
 
-#### Writing a workflow
+``` java
+try (InputStream in = new FileInputStream("simple.yaml")) {
+   Workflow workflow = WorkflowReader.validation().readWorkflow (in, WorkflowFormat.YAML);
+   // Once you have the Workflow instance you can use its API to inspect it
+}
+```
+
+For additional reading helper methods, including the one to read a workflow definition from classpath, check [WorkflowReader](api/src/main/java/io/serverlessworkflow/api/WorkflowReader.java) class. 
+
+#### Writing workflow definition to a a JSON/YAML target
 
-Given a workflow definition, you can store it using JSON or YAML format. 
+Given a Workflow instance, you can store it using JSON or YAML format. 
 For example, to store a workflow using json format in a file called `simple.json`, you write
 
 ``` java
 try (OutputStream out = new FileOutputStream("simple.json")) {
     WorkflowWriter.writeWorkflow(out, workflow, WorkflowFormat.JSON);
 }
 
-```
+```
+For additional writing helper methods, check [WorkflowWriter](api/src/main/java/io/serverlessworkflow/api/WorkflowWriter.java) class. 
+
+### Reference implementation
+See Reference implementation [readme](impl/README.md). 
+

impl/bom/pom.xml → examples/pom.xml

@@ -2,19 +2,25 @@
   <modelVersion>4.0.0</modelVersion>
   <parent>
     <groupId>io.serverlessworkflow</groupId>
-    <artifactId>serverlessworkflow-impl</artifactId>
+    <artifactId>serverlessworkflow-parent</artifactId>
     <version>7.0.0-SNAPSHOT</version>
   </parent>
-  <artifactId>serverlessworkflow-impl-bom</artifactId>
-  <packaging>pom</packaging>
+  <artifactId>examples</artifactId>
   <dependencies>
     <dependency>
       <groupId>io.serverlessworkflow</groupId>
       <artifactId>serverlessworkflow-impl-core</artifactId>
+      <version>${project.version}</version>
     </dependency>
     <dependency>
       <groupId>io.serverlessworkflow</groupId>
       <artifactId>serverlessworkflow-impl-http</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-simple</artifactId>
+      <version>2.0.16</version>
     </dependency>
   </dependencies>
 </project>

examples/src/main/java/io/serverlessworkflow/impl/BlockingExample.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.serverlessworkflow.impl;
+
+import io.serverlessworkflow.api.WorkflowReader;
+import java.io.IOException;
+import java.util.Map;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class BlockingExample {
+
+  private static final Logger logger = LoggerFactory.getLogger(BlockingExample.class);
+
+  public static void main(String[] args) throws IOException {
+    try (WorkflowApplication appl = WorkflowApplication.builder().build()) {
+      logger.info(
+          "Workflow output is {}",
+          appl.workflowDefinition(WorkflowReader.readWorkflowFromClasspath("do-single.yaml"))
+              .instance(Map.of("petId", 10))
+              .start()
+              .join());
+    }
+  }
+}

examples/src/main/java/io/serverlessworkflow/impl/NotBlockingExample.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.serverlessworkflow.impl;
+
+import io.serverlessworkflow.api.WorkflowReader;
+import java.io.IOException;
+import java.util.Map;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class NotBlockingExample {
+
+  private static final Logger logger = LoggerFactory.getLogger(NotBlockingExample.class);
+
+  public static void main(String[] args) throws IOException {
+    try (WorkflowApplication appl = WorkflowApplication.builder().build()) {
+      appl.workflowDefinition(WorkflowReader.readWorkflowFromClasspath("do-single.yaml"))
+          .instance(Map.of("petId", 10))
+          .start()
+          .thenAccept(node -> logger.info("Workflow output is {}", node));
+    }
+  }
+}

examples/src/main/resources/do-single.yaml

@@ -0,0 +1,11 @@
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: examples
+  name: call-http-shorthand-endpoint
+  version: '0.1.0'
+do:
+  - getPet:
+      call: http
+      with:
+        method: get
+        endpoint: https://petstore.swagger.io/v2/pet/{petId}

impl/README.md

@@ -0,0 +1,120 @@
+![Verify JAVA SDK](https://github.com/serverlessworkflow/sdk-java/workflows/Verify%20JAVA%20SDK/badge.svg)
+![Deploy JAVA SDK](https://github.com/serverlessworkflow/sdk-java/workflows/Deploy%20JAVA%20SDK/badge.svg) [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/serverlessworkflow/sdk-java)
+
+# Serverless Workflow Specification - Java SDK- Reference Implementation
+
+Welcome to Java SDK runtime reference implementation, a lightweight implementation of the Serverless Workflow specification which provides a simple, non blocking, reactive API for workflow execution. 
+
+Although initially conceived mainly for testing purposes, it was designed to be easily expanded, so it can eventually become production ready. 
+
+## Status. 
+
+This reference implementation is currently capable of running workflows consisting of:
+
+
+* Switch 
+* Set
+* Do
+* Raise
+* Listen
+* Emit
+* Fork
+* For
+* Try
+* Wait
+* Call
+  * HTTP
+* Input and output schema validation.
+* Input, output and export filters. 
+* Runtime expression special keyword
+* Error definitions
+
+
+## Setup
+
+### JDK Version
+
+Reference implementation requires [Java 17](https://openjdk.org/projects/jdk/17/) or newer versions. 
+
+### Maven projects:
+
+Add the following dependencies to your pom.xml `dependencies` section:
+
+```xml
+<dependency>
+      <groupId>io.serverlessworkflow</groupId>
+      <artifactId>serverlessworkflow-impl-core</artifactId>
+      <version>7.0.0-SNAPSHOT</version>
+</dependency>
+<dependency>
+      <groupId>io.serverlessworkflow</groupId>
+      <artifactId>serverlessworkflow-impl-http</artifactId>
+      <version>7.0.0-SNAPSHOT</version>
+ </dependency>
+```
+
+### Gradle projects:
+
+ Add the following dependencies to your build.gradle `dependencies` section:
+
+```text
+implementation("io.serverlessworkflow:serverlessworkflow-impl-core:7.0.0-SNAPSHOT")
+implementation("io.serverlessworkflow:serverlessworkflow-impl-http:7.0.0-SNAPSHOT")
+```
+
+## How to use
+
+This section is split in two. 
+Quick version is intended for impatient users that want to try something as soon as possible.
+Detailed version is more suitable for those users interested on a more thoughtful discussion of the API
+Full code of the examples is available [here](/examples)
+
+### Quick version
+
+Assuming you have a  workflow definition stored in a file called "do-single.yaml" available in your classpath 
+
+```yaml 
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: examples
+  name: call-http-shorthand-endpoint
+  version: '0.1.0'
+do:
+  - getPet:
+      call: http
+      with:
+        method: get
+        endpoint: https://petstore.swagger.io/v2/pet/{petId}
+```
+
+In order to execute it, blocking the thread till the http request is completed, you should write
+
+``` java 
+try (WorkflowApplication appl = WorkflowApplication.builder().build()) {
+      logger.info(
+          "Workflow output is {}",
+          appl.workflowDefinition(WorkflowReader.readWorkflowFromClasspath("do-single.yaml"))
+              .instance(Map.of("petId", 10))
+              .start()
+              .join());
+    }
+```
+
+In order to execute it, without blocking the calling thread till the http request is completed, you should write
+
+``` java 
+  try (WorkflowApplication appl = WorkflowApplication.builder().build()) {
+      appl.workflowDefinition(WorkflowReader.readWorkflowFromClasspath("do-single.yaml"))
+          .instance(Map.of("petId", 10))
+          .start()
+          .thenAccept(node -> logger.info("Workflow output is {}", node));
+    }
+```
+When the http request is done, both examples will print a similar output
+
+`Workflow output is {"id":10,"category":{"id":10,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":10,"name":"string"}],"status":"string"}`
+
+
+### Detailed version
+
+TBD

impl/core/src/main/java/io/serverlessworkflow/impl/WorkflowApplication.java

@@ -193,7 +193,7 @@ public WorkflowDefinition workflowDefinition(Workflow workflow) {
   }
 
   @Override
-  public void close() throws Exception {
+  public void close() {
     for (WorkflowDefinition definition : definitions.values()) {
       definition.close();
     }