Skip to content

Latest commit

 

History

History
142 lines (99 loc) · 5.79 KB

README.md

File metadata and controls

142 lines (99 loc) · 5.79 KB

Verify JAVA SDK Deploy JAVA SDK Gitpod ready-to-code

Serverless Workflow Specification - Java SDK

Provides the Java API for the Serverless Workflow Specification

With the SDK you can:

  • Read workflow JSON and YAML definitions
  • Write workflow definitions in JSON and YAML formats.
  • Test your workflow definitions using the reference implementation.

Status

Latest Releases Conformance to spec version
7.0.0.Final v1.0.0
5.0.0.Final v0.8
4.0.5.Final v0.8
3.0.0.Final v0.7
2.0.0.Final v0.6
1.0.3.Final v0.5

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

SDK Version JDK Version
7.0.0 and after 17
5.0.0 and after 11
4.0.x and before 8

Getting Started

Building SNAPSHOT locally

To build project and run tests locally:

git clone https://github.com/serverlessworkflow/sdk-java.git
mvn clean install

The project uses Google's code styleguide. Your changes should be automatically formatted during the build.

Maven projects:

Add the following dependencies to your pom.xml dependencies section:

<dependency>
    <groupId>io.serverlessworkflow</groupId>
    <artifactId>serverlessworkflow-api</artifactId>
    <version>7.0.0-SNAPSHOT</version>
</dependency>

Gradle projects:

Add the following dependencies to your build.gradle dependencies section:

implementation("io.serverlessworkflow:serverlessworkflow-api:7.0.0-SNAPSHOT")

How to Use

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.

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, 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:

document:
  dsl: 1.0.0-alpha1
  namespace: default
  name: implicit-sequence
do:
  setRed:
    set:
      colors: '${ .colors + [ "red" ] }'
  setGreen:
    set:
      colors: '${ .colors + [ "green" ] }'
  setBlue:
    set:
      colors: '${ .colors + [ "blue" ] }'

To parse it and get a Workflow instance you can do:

try (InputStream in = new FileInputStream("simple.yaml")) {
   Workflow workflow = WorkflowReader.readWorkflow (in, WorkflowFormat.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:

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 class.

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

try (OutputStream out = new FileOutputStream("simple.json")) {
    WorkflowWriter.writeWorkflow(out, workflow, WorkflowFormat.JSON);
}

For additional writing helper methods, check WorkflowWriter 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.