Merge pull request #523 from fjtirado/Fix_#520

[Fix #520] Updating readme

Author: fjtirado

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 definitions in JSON and YAML formats. 
+* 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,18 @@ 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 |
 | :---: | :---: |
+| 7.0.0 and after | 17 |
 | 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 +48,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 +60,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 in-memory representation consists 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 +103,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 +112,31 @@ 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: 
+
+``` 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
+}
+```
 
-#### Writing a workflow
+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. 
 
-Given a workflow definition, you can store it using JSON or YAML format. 
+### Writing workflow definition to a JSON/YAML target
+
+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
+
+The reference implementation provides a ready-to-use runtime that supports the Serverless Workflow Specification. It includes a workflow execution engine, validation utilities, and illustrative examples to help you quickly test and deploy your workflows. For details on usage, configuration, and supported features, see [readme](impl/README.md). 
+

examples/events/pom.xml

@@ -0,0 +1,19 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>io.serverlessworkflow</groupId>
+    <artifactId>serverlessworkflow-examples</artifactId>
+    <version>7.0.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>events</artifactId>
+  <dependencies>
+  <dependency>
+      <groupId>io.serverlessworkflow</groupId>
+      <artifactId>serverlessworkflow-impl-core</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-simple</artifactId>
+    </dependency>
+  </dependencies>
+</project>

examples/events/src/main/java/events/EventExample.java

@@ -0,0 +1,50 @@
+/*
+ * 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 events;
+
+import io.serverlessworkflow.api.WorkflowReader;
+import io.serverlessworkflow.impl.WorkflowApplication;
+import io.serverlessworkflow.impl.WorkflowDefinition;
+import io.serverlessworkflow.impl.WorkflowInstance;
+import java.io.IOException;
+import java.util.Map;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class EventExample {
+
+  private static final Logger logger = LoggerFactory.getLogger(EventExample.class);
+
+  public static void main(String[] args) throws IOException {
+    try (WorkflowApplication appl = WorkflowApplication.builder().build()) {
+      WorkflowDefinition listenDefinition =
+          appl.workflowDefinition(WorkflowReader.readWorkflowFromClasspath("listen.yaml"));
+      WorkflowDefinition emitDefinition =
+          appl.workflowDefinition(WorkflowReader.readWorkflowFromClasspath("emit.yaml"));
+      WorkflowInstance waitingInstance = listenDefinition.instance(Map.of());
+      waitingInstance
+          .start()
+          .thenAccept(node -> logger.info("Waiting instance completed with result {}", node));
+      logger.info("Listen instance waiting for proper event, Status {}", waitingInstance.status());
+      logger.info("Publishing event with temperature 35");
+      emitDefinition.instance(Map.of("temperature", 35)).start().join();
+      logger.info(
+          "Listen instance still waiting for proper event, Status {}", waitingInstance.status());
+      logger.info("Publishing event with temperature 39");
+      emitDefinition.instance(Map.of("temperature", 39)).start().join();
+    }
+  }
+}

examples/events/src/main/resources/emit.yaml

@@ -0,0 +1,14 @@
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: test
+  name: emit
+  version: '0.1.0'
+do:
+  - emitEvent:
+      emit:
+        event:
+          with:
+            source: https://hospital.com
+            type: com.fake-hospital.vitals.measurements.temperature
+            data:
+              temperature: ${.temperature}

examples/events/src/main/resources/listen.yaml

@@ -0,0 +1,13 @@
+document:
+  dsl: '1.0.0-alpha5'
+  namespace: examples
+  name: listen
+  version: '0.1.0'
+do:
+  - callDoctor:
+      listen:
+        to:
+          one:
+            with:
+              type: com.fake-hospital.vitals.measurements.temperature
+              data: ${ .temperature > 38 }

examples/pom.xml

@@ -0,0 +1,33 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>io.serverlessworkflow</groupId>
+    <artifactId>serverlessworkflow-parent</artifactId>
+    <version>7.0.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>serverlessworkflow-examples</artifactId>
+  <packaging>pom</packaging>
+  <dependencyManagement>
+    <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>
+  </dependencyManagement>
+  <modules>
+    <module>simpleGet</module>
+    <module>events</module>
+  </modules>
+</project>

impl/bom/pom.xml renamed to examples/simpleGet/pom.xml

@@ -2,11 +2,10 @@
   <modelVersion>4.0.0</modelVersion>
   <parent>
     <groupId>io.serverlessworkflow</groupId>
-    <artifactId>serverlessworkflow-impl</artifactId>
+    <artifactId>serverlessworkflow-examples</artifactId>
     <version>7.0.0-SNAPSHOT</version>
   </parent>
-  <artifactId>serverlessworkflow-impl-bom</artifactId>
-  <packaging>pom</packaging>
+  <artifactId>simpleGet</artifactId>
   <dependencies>
     <dependency>
       <groupId>io.serverlessworkflow</groupId>
@@ -16,5 +15,9 @@
       <groupId>io.serverlessworkflow</groupId>
       <artifactId>serverlessworkflow-impl-http</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-simple</artifactId>
+    </dependency>
   </dependencies>
 </project>

examples/simpleGet/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("get.yaml"))
+              .instance(Map.of("petId", 10))
+              .start()
+              .join());
+    }
+  }
+}

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

@@ -0,0 +1,37 @@
+/*
+ * 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("get.yaml"))
+          .instance(Map.of("petId", 10))
+          .start()
+          .thenAccept(node -> logger.info("Workflow output is {}", node));
+      logger.info("The request has been sent, this thread might continue doing stuff");
+    }
+  }
+}

examples/simpleGet/src/main/resources/get.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}