Merge pull request #7 from tsurdilo/addvalid

Add Workflow validation

Author: Tihomir Surdilovic

README.md

@@ -3,17 +3,15 @@
 
 # Serverless Workflow Specification - Java SDK
 
-Provides the Java API/SPI for the [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification)
+Provides the Java API/SPI and Model Validation for the [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification)
 
-Allows you to parse Workflow types from JSON/YAML sources, as well as programmatically build your workflows using 
-the provided builder API.
+With the SDK you can:
+* Parse workflow JSON and YAML definitions
+* Programmatically build workflow definitions
+* Validate workflow definitions (both schema and workflow integrity validation)
 
-The SDK focus is to allow to quickly go from the workflow definition (JSON or YAML) to instances 
-of Workflow type, as well as to provide a builder API to easily create a workflow programmatically.
-
-Future versions will also include validation functionality.
-
-This is **not** a workflow runtime implementation.
+Serverless Workflow Java SDK is **not** a workflow runtime implementation but can be used by Java runtime implementations
+to parse and validate workflow definitions.
 
 ### Status
 
@@ -54,6 +52,16 @@ Then to use it in your project pom.xml add:
 </dependency>
 ```
 
+* Validation dependency
+
+```xml
+<dependency>
+    <groupId>io.serverlessworkflow</groupId>
+    <artifactId>serverlessworkflow-validation</artifactId>
+    <version>0.2-SNAPSHOT</version>
+</dependency>
+```
+
 #### Get dependencies from Nexus
 
 Our SNAPSHOT versions are published to the Sonatype repositories.
@@ -83,8 +91,6 @@ And use the dependencies:
 </dependency>
 ```
 
-and
-
 ```xml
 <dependency>
   <groupId>io.serverlessworkflow</groupId>
@@ -93,6 +99,14 @@ and
 </dependency>
 ```
 
+```xml
+<dependency>
+  <groupId>io.serverlessworkflow</groupId>
+  <artifactId>serverlessworkflow-validation</artifactId>
+  <version>0.2-SNAPSHOT</version>
+</dependency>
+```
+
 ### How to Use 
 
 #### Creating from JSON/YAML source
@@ -170,7 +184,7 @@ Workflow testWorkflow = new Workflow().withId("test-workflow").withName("test-wo
                         new EventDefinition().withName("testEvent").withSource("testSource").withType("testType"))
                 )
                 .withFunctions(Arrays.asList(
-                        new Function().withName("testFunction").withResource("testResource").withType("testType"))
+                        new FunctionDefinition().withName("testFunction").withResource("testResource").withType("testType"))
                 )
                 .withStates(Arrays.asList(
                         new DelayState().withName("delayState").withType(DELAY)
@@ -193,3 +207,44 @@ You can use the workflow instance to get its JSON/YAML definition as well:
 assertNotNull(Workflow.toJson(testWorkflow));
 assertNotNull(Workflow.toYaml(testWorkflow));
 ```
+
+#### Using Workflow Validation
+
+Validation allows you to performe Json Schema validation against the JSON/YAML workflow definitions.
+Once you have a `Workflow` instance, you can also run integrity checks.
+
+You can validate a Workflow JSON/YAML definition to get validation errors:
+
+``` java
+WorkflowValidator workflowValidator = new WorkflowValidatorImpl();
+List<ValidationError> validationErrors = workflowValidator.setSource("WORKFLOW_MODEL_JSON/YAML").validate();
+```
+
+Where `WORKFLOW_MODEL_JSON/YAML` is the actual workflow model JSON or YAML definition.
+
+Or you can just check if it is valid (without getting specific errors):
+
+``` java
+WorkflowValidator workflowValidator = new WorkflowValidatorImpl();
+boolean isValidWorkflow = workflowValidator.setSource("WORKFLOW_MODEL_JSON/YAML").isValid();
+```
+
+If you build your Workflow programmatically, you can validate it as well:
+
+``` java
+Workflow workflow = new Workflow().withId("test-workflow").withVersion("1.0")
+.withStates(Arrays.asList(
+        new DelayState().withName("delayState").withType(DELAY)
+                .withStart(
+                        new Start().withKind(Start.Kind.DEFAULT)
+                )
+                .withEnd(
+                        new End().withKind(End.Kind.DEFAULT)
+                )
+                .withTimeDelay("PT1M")
+        )
+);
+
+WorkflowValidator workflowValidator = new WorkflowValidatorImpl();
+List<ValidationError> validationErrors = workflowValidator.setWorkflow(workflow).validate();
+```

api/pom.xml

@@ -34,6 +34,14 @@
             <groupId>javax.validation</groupId>
             <artifactId>validation-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.json</groupId>
+            <artifactId>json</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.github.everit-org.json-schema</groupId>
+            <artifactId>org.everit.json.schema</artifactId>
+        </dependency>
 
         <!-- test -->
         <dependency>

api/src/main/java/io/serverlessworkflow/api/interfaces/ExpressionEvaluator.java

@@ -16,21 +16,22 @@
  */
 package io.serverlessworkflow.api.interfaces;
 
-public interface WorkflowValidator {
+import io.serverlessworkflow.api.Workflow;
+import io.serverlessworkflow.api.validation.ValidationError;
 
-    WorkflowValidator setWorkflowManager(WorkflowManager workflowManager);
+import java.util.List;
 
-    void setJson(String json);
+public interface WorkflowValidator {
 
-    void setYaml(String yaml);
+    WorkflowValidator setWorkflow(Workflow workflow);
 
-    boolean isValid();
+    WorkflowValidator setSource(String source);
 
-    void setEnabled(boolean enabled);
+    List<ValidationError> validate();
 
-    void setSchemaValidationEnabled(boolean schemaValidationEnabled);
+    boolean isValid();
 
-    void setStrictValidationEnabled(boolean strictValidationEnabled);
+    WorkflowValidator setSchemaValidationEnabled(boolean schemaValidationEnabled);
 
-    void reset();
+    WorkflowValidator reset();
 }

api/src/main/java/io/serverlessworkflow/api/interfaces/WorkflowManager.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ * <p>
+ * 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
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * 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.api.schemaclient;
+
+import org.everit.json.schema.loader.SchemaClient;
+
+import java.io.InputStream;
+import java.util.Objects;
+
+public class ResourceSchemaClient implements SchemaClient {
+
+    private final SchemaClient fallbackClient;
+    private final String baseResourcePath = "/schema/";
+
+    public ResourceSchemaClient(SchemaClient fallbackClient) {
+        this.fallbackClient = Objects.requireNonNull(fallbackClient,
+                "fallbackClient cannot be null");
+    }
+
+    public InputStream get(String path) {
+        path = path.substring("https://wg-serverless.org/".length());
+        return this.getClass().getResourceAsStream(baseResourcePath + path);
+    }
+}

api/src/main/java/io/serverlessworkflow/api/interfaces/WorkflowValidator.java

@@ -21,7 +21,7 @@
 import com.fasterxml.jackson.databind.ser.std.StdSerializer;
 import io.serverlessworkflow.api.Workflow;
 import io.serverlessworkflow.api.events.EventDefinition;
-import io.serverlessworkflow.api.functions.Function;
+import io.serverlessworkflow.api.functions.FunctionDefinition;
 import io.serverlessworkflow.api.interfaces.Extension;
 import io.serverlessworkflow.api.interfaces.State;
 
@@ -102,7 +102,7 @@ public void serialize(Workflow workflow,
 
         if (workflow.getFunctions() != null && !workflow.getFunctions().isEmpty()) {
             gen.writeArrayFieldStart("functions");
-            for (Function function : workflow.getFunctions()) {
+            for (FunctionDefinition function : workflow.getFunctions()) {
                 gen.writeObject(function);
             }
             gen.writeEndArray();

api/src/main/java/io/serverlessworkflow/api/schemaclient/ResourceSchemaClient.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ * <p>
+ * 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
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * 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.api.validation;
+
+public class ValidationError {
+    private static final String MSG_FORMAT = "%s:%s";
+    public static final String SCHEMA_VALIDATION = "schemavalidation";
+    public static final String WORKFLOW_VALIDATION = "workflowvalidation";
+
+    private String message;
+    private String type;
+
+    public String getMessage() {
+        return message;
+    }
+
+    public void setMessage(String message) {
+        this.message = message;
+    }
+
+    public String getType() {
+        return type;
+    }
+
+    public void setType(String type) {
+        this.type = type;
+    }
+
+    @Override
+    public String toString() {
+        return String.format(MSG_FORMAT,
+                type,
+                message);
+    }
+}

api/src/main/java/io/serverlessworkflow/api/serializers/WorkflowSerializer.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ * <p>
+ * 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
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * 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.api.validation;
+
+import io.serverlessworkflow.api.schemaclient.ResourceSchemaClient;
+import org.everit.json.schema.Schema;
+import org.everit.json.schema.loader.SchemaLoader;
+import org.everit.json.schema.loader.internal.DefaultSchemaClient;
+import org.json.JSONObject;
+import org.json.JSONTokener;
+
+public class WorkflowSchemaLoader {
+    private static final JSONObject workflowSchema = new JSONObject(new JSONTokener(
+            WorkflowSchemaLoader.class.getResourceAsStream("/schema/workflow.json")));
+
+    public static Schema getWorkflowSchema() {
+        SchemaLoader schemaLoader = SchemaLoader.builder()
+                .schemaClient(new ResourceSchemaClient(new DefaultSchemaClient()))
+                .schemaJson(workflowSchema)
+                .resolutionScope("classpath:schema")
+                .draftV7Support()
+                .build();
+        return schemaLoader.load().build();
+    }
+}