indeedeng / iwf-java-sdk

Java SDK for iwf workflow engine(simple & powerful workflow as code engine based on Cadence/Temporal)

iwf-java-sdk

Java SDK for iWF workflow engine

See samples for how to use this SDK to build your workflow.

Requirements

• Java 1.8+

How to use

Here is the link to all the versions available to use. Also the Java docs for the latest version. For the latest version, MVN Repository website may have 1~2 days delay to show up.

Gradle

// https://mvnrepository.com/artifact/io.iworkflow/iwf-java-sdk
implementation 'io.iworkflow:iwf-java-sdk:2.5.+'

Maven

<!-- https://mvnrepository.com/artifact/io.iworkflow/iwf-java-sdk -->
<dependency>
    <groupId>io.iworkflow</groupId>
    <artifactId>iwf-java-sdk</artifactId>
    <version>2.5.+</version>
    <type>pom</type>
</dependency>

Concepts

To implement a workflow, the two most core interfaces are

• Workflow interface defines the workflow definition

• WorkflowState interface defines the workflow states for workflow definitions

A workflow can contain any number of WorkflowStates.

See more in https://github.com/indeedeng/iwf#what-is-iwf

How to build & run

Using IntelliJ

1. Check out the idl submodule by running the command: git submodule update --init --recursive
2. In "Build, Execution, Deployment" -> "Gradle", choose "wrapper task in Gradle build script" for "Use gradle from".
3. Open Gradle tab, click "build" under "build" to build the project

Development Guide

Update IDL

Run the command git submodule update --remote --merge to update IDL to the latest commit

Repo structure

• .github/workflows/: the GithubActions workflows
• iwf-idl/: the idl submodule
• script/: some scripts for GithubActions and testing
• src/: Java source code
  • main/java/io/iworkflow/core/: SDK code
    • command/: the command implementation
    • communication/: the communication implementation
    • mapper/: the mapper with IDL
    • persistence/: the persistence implementation
    • validator/: some validators
    • Client.java: the client implemntation
    • ...java ...
  • test/java/io/iworkflow/: Java test code (currently only integ test)
    • spring/: the integ test setup of using Spring as REST controller
    • integ/: the integration tests
      • XyzTest.java: a file for test cases
      • xyz/: the iWF workflow implementation for the integration test cases

Development Plan

1.0

• Start workflow API
• Executing start/decide APIs and completing workflow
• Parallel execution of multiple states
• Timer command
• Signal command
• SearchAttribute
• DataAttribute
• StateExecutionLocal
• Signal workflow API
• Get workflow DataAttributes/SearchAttributes API
• Get workflow API
• Search workflow API
• Cancel workflow API
• Reset workflow API
• InternalChannel command
• AnyCommandCompleted Decider trigger type
• More workflow start options: IdReusePolicy, cron schedule, retry
• StateOption: WaitUntil/Execute API timeout and retry policy
• Reset workflow by stateId/StateExecutionId

1.1

• New search attribute types: Double, Bool, Datetime, Keyword array, Text
• Workflow start options: initial search attributes

1.2

• Skip timer API for testing/operation
• Decider trigger type: any command combination

1.3

• Support failing workflow with results
• Improve workflow uncompleted error return(canceled, failed, timeout, terminated)

1.4

• Support PROCEED_ON_FAILURE for WaitUntilApiFailurePolicy

2.0

• Renaming some concepts/APIs with breaking changes(see releaste notes)
• Support workflow RPC

2.1

• Support caching on persistence

2.2

• Support atomic conditional complete workflow by checking signal/internal channel emptiness

2.3

• Support dynamic data/search attributes and internal/signal channel definition
• Support state options overridden dynamically
• Support describe workflow API

2.4

• Support execute API failure policy
• Support RPC persistence locking policy

2.5

• Add waitForStateExecutionCompletion API

iwf-java-sdk's Issues

Add describeWorkflow API in Client

Expectation

input: workflowId, runId(optional)
output: status + currentRunId

How to implement

Use workflow/get API, and set needsResults to false: https://github.com/indeedeng/iwf-idl/blob/f63c1a67a111fd946ec477545a3c30e552a75965/iwf.yaml#L469 so that it won't return the workflow result

How to test

Use the basic integ test to test the API working

JacksonObjectEncoder: optional to pass encoding type and allow not valididate the matching by default

Remove unused state options in core state movement

It’s created by mistake

implement fail workflow decision

Check signal

1. Check if signal name have conflicts
2. Check if sending a valid signal

Rename signalMethod to singalChannel

Consider adding StateExecutionException to capture stacktrace info when error in user code

This will probably make it even easier for https://github.com/indeedeng/iwf-java-samples/blob/b444ff64f993a131fa7a55a5ff15476d1a4a13d4/src/main/java/io/iworkflow/controller/IwfWorkerApiController.java#L61

Support StateLocalAttribute

implement TODOs in CommandResults

Improve exception handling using pre-defined exception

For error that is caused by input, throw IllegalArgumentException.

For error that is caused by user workflow, throw WorkflowDefinitionException.java

For error that caused by SDK or Service, throw InternalServiceException.java

Get result should use a wrapper to include others like status

Rename untyped client to unregistered client

rename to iwf-java-sdk to be more clear

this will also help the maven library name(artifactId)

allow setting workflowType

by default it's the simple name but in some advanced use case, ppl want to set the value differently (e.g. DSL workflow)

Fix/refactor WorkflowOptions for client

Remove state options from it for client as it should be loaded from workflow state rather than from request, otherwise it will be confusing.
Remove minimum from method and let start api specify timeout
Also remove one overload to make it clear

Use map[string]Object as initial search attribute

unregistered client can use raw workflow state option instead

WorkflowOptions will be only for client and not for unregistered client

Define state local attributes in state interface

Add getWorkflowResultNoWait

Or getWorkflowResultNonBlocking
Or tryGettingWorkflowResult

Start decide api timeout- example to honor the timeout from server

Especially server has set timeout for the APIs

Let data converter can be configurable

bug: Allow passing empty commandId

Example to set timeout to call IWF server

Bug for using init state opt

iwf-java-sdk/src/main/java/io/iworkflow/core/Client.java

Line 169 in 7e1ce7f

if (stateDef.getWorkflowState().getStateOptions() != null) {

Add NPE check to throw a better exception for user error

E.g. in WorkflowService we should check if the workflow state is valid

Allow customize timeout and backoff retry for State Start/Decide APIs

Currently it's using
default start to close timeout from iwf-server:

10 s

default backoff retry from Temporal server:

		// The default RetryPolicy provided by the server specifies:
		// - InitialInterval of 1 second
		// - BackoffCoefficient of 2.0
		// - MaximumInterval of 100 x InitialInterval
		// - MaximumAttempts of 0 (unlimited)

Support SearchAttribute

Support QueryAttribute

Registry: provide addWorkflows API to add multiple workflows in a call

Search attributes

Add comments about how to register in ct

Not allowiing key conflicts for data objects with search attributes

Refactor: replace POJO classes like ActivityCommand with Java immutable

Use https://immutables.github.io/

improve StateDecision

remove library path

rename FAILING_WORKFLOW to FORCE_FAILING_WORKFLOW

RecordEvent API can accept var arg as input

This will be easier for multiple values

Fix comment for default timeout

iwf-java-sdk/src/main/java/io/iworkflow/core/WorkflowState.java

Line 69 in ac63cf3

* timeout:10s

it’s 30 s . Also need the same for go sdk

Refactoring interstatechannel to interState to be more generic for future extension

Provide default stateId using class name

so that the stateId doesn't have to be specified in StateDecision.nextState(..)

We should mark the old ones as deprecated

Don’t require starting state in client when starting workflow , and require workflow def only has exactly one starting state

User should still workaround by using unregistered client

check the input is assignable to start state input

Implement workflowState Start API

implement https://github.com/cadence-oss/iwf-java/blob/main/core/src/main/java/iwf/core/spring/controller/ApiController.java#L23

AC & steps (separate PRs):

1. Copy the SDK code from prototype
2. Copy a demo workflow as user code in test folder, and let it run with the SDK (with the spring controller)
3. Provide a workflowRegistry with register APIs to register workflow type(use workflow class short name)
4. On invoking workflowState.Start, find the workflow from workflowRegistry, and invoke the start API from user code, collect the command requests and return back to caller

Client method names start with lower case

Example to return stacktrace on error by default for debugging with workflow history

return not found exception instead of NPE when the state is not registered

when starting a workflow with starting state, or in StateDeicion.singleNextState and StateDeicion.multipleNextStates, we should check if the state are valid and registered for the workflow type

Combine workflow local attributes and interstate local to workflow local

Remove unused data class after moved to idl

carry over policy /type
persistence loading policy/type
SearchAttributeType

Use EncodedObject in ObjectEncoder interface

Do not upsert the attributes if value not changed

Maybe: Rename state local attribute to state local channel

May post fix the search attribute type in sdk after return from server

Eg only sdk knows if it’s keyword or text

Check next state input is valid type

comment out or throw error for all unsupported APIs

Consider remove UntypedClient and replace with the new pattern in GoSDK

When client is initiated without registry, then use as UntypedClient

add integ test for more search attribute types and searching