Skip to content

Commit

Permalink
Merge branch 'release/0.0.1'
Browse files Browse the repository at this point in the history
  • Loading branch information
zambrovski committed May 15, 2024
2 parents a101975 + 4d291e3 commit 1c1d648
Show file tree
Hide file tree
Showing 229 changed files with 103,706 additions and 91 deletions.
26 changes: 15 additions & 11 deletions .github/workflows/development.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,16 @@ name: Development branches
on:
push:
branches:
- '*' # matches every branch that doesn't contain a '/'
- '*/*' # matches every branch containing a single '/'
- '**' # matches every branch
- '!master'
pull_request:
branches:
- '*' # matches every branch that doesn't contain a '/'
- '*/*' # matches every branch containing a single '/'
- '**' # matches every branch
- '!master'

jobs:
build:
Expand All @@ -13,14 +21,14 @@ jobs:
steps:
# Checkout the code
- name: Checkout code
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Expose branch name
run: echo ${{ github.ref }}

# Setup JDK and Maven
- name: Set up JDK
uses: actions/setup-java@v3
uses: actions/setup-java@v4
with:
java-version: 17
distribution: 'zulu'
Expand All @@ -34,12 +42,8 @@ jobs:
- name: Build with Maven
run: ./mvnw clean verify -U -B -ntp -T4

# itest
- name: Run itest
run: ./mvnw integration-test failsafe:verify -Pitest -ntp -U -B -T4

# - name: Upload coverage to Codecov
# if: github.event_name == 'push' && github.actor != 'dependabot[bot]'
# uses: codecov/[email protected]
# with:
# token: ${{secrets.CODECOV_TOKEN}}
- name: Upload coverage to Codecov
if: github.event_name == 'push' && github.actor != 'dependabot[bot]'
uses: codecov/[email protected]
with:
token: ${{secrets.CODECOV_TOKEN}}
62 changes: 62 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
name: Build the docs

on:
push:
branches:
- develop
tags:
- '*'

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: 3.9
cache: pip

- name: Upgrade pip
run: |
# install pip=>20.1 to use "pip cache dir"
python3 -m pip install --upgrade pip
- name: Install dependencies
run: python3 -m pip install -r ./docs/requirements.txt

- name: Set git username and email
run: |
#
git config --global user.email "${GH_USERNAME}@users.noreply.github.com"
git config --global user.name "${GH_USERNAME}"
env:
GH_USERNAME: ${{ github.actor }}

- name: Pre-fetch the gh-pages branch
run: git fetch --depth=1

- name: Build docs with MkDocs
run: mkdocs build

- name: Read the tag name
id: get_tag_name
if: startsWith(github.ref, 'refs/tags/')
run: echo ::set-output name=TAG_NAME::${GITHUB_REF/refs\/tags\//}

# This is for a tagged version
- name: Create a new version of documentation and push to GH pages.
if: startsWith(github.ref, 'refs/tags/')
run: mike deploy ${{ steps.get_tag_name.outputs.TAG_NAME }} stable --push --update-aliases

- name: Make stable to default.
if: startsWith(github.ref, 'refs/tags/')
run: mike set-default stable --push

# This is for develop
- name: Deploy latest develop snapshot docs to GH pages.
if: github.ref == 'refs/heads/develop'
run: mike deploy snapshot --push --update-aliases
14 changes: 7 additions & 7 deletions .github/workflows/master.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,16 @@ jobs:
name: Build and run tests
steps:
- name: Checkout code
uses: actions/checkout@v3
uses: actions/checkout@v4

# Setup JDK and .m2/settings.xml
- name: Set up JDK
uses: actions/setup-java@v3
uses: actions/setup-java@v4
with:
java-version: 17
server-id: ossrh
distribution: 'zulu'
cache: maven
server-id: ossrh
server-username: OSS_CENTRAL_USERNAME # env variable for Maven Central
server-password: OSS_CENTRAL_PASSWORD # env variable for Maven Central

Expand All @@ -46,7 +46,7 @@ jobs:
OSS_CENTRAL_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
OSS_CENTRAL_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}

# - name: Upload coverage information
# uses: codecov/codecov-action@v2
# with:
# token: ${{ secrets.CODECOV_TOKEN }}
- name: Upload coverage information
uses: codecov/codecov-action@v2
with:
token: ${{ secrets.CODECOV_TOKEN }}
2 changes: 1 addition & 1 deletion .mvn/wrapper/maven-wrapper.properties
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,5 @@
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.5/apache-maven-3.9.5-bin.zip
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip
wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@

END OF TERMS AND CONDITIONS

Copyright 2021 Holisticon AG
Copyright 2024 Holisticon AG

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand Down
68 changes: 68 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,71 @@
[![Development branches](https://github.com/bpm-crafters/process-engine-api/actions/workflows/development.yml/badge.svg)](https://github.com/bpm-crafters/process-engine-api/actions/workflows/development.yml)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.bpm-crafters.process-engine-api/process-engine-api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.bpm-crafters.process-engine-api/process-engine-api)

## Purpose of the library

This library provides a modern engine-agnostic API which can be used to implement process applications. By providing a set
of adapters to relevant process engines (Camunda Platform 7, Camunda Platform 8, etc...) the library enforces separation of
the integration of process engine from the selection of the used engine. This approach fosters an easy migration between engines
and tries to achieve to support migrations with minimal (or even no) code modifications.

## Anatomy

The library contains of the following Maven modules:

- `process-engine-api`: pure API written in Kotlin (100% Java-compatible)
- `process-engine-api-adapter-commons`: commons for adapter implementation, which are independent of the selected engine
- `process-engine-api-adapter-camunda-platform-7-embedded-core`: core implementation classes for Camunda 7 Platform embedded without additional dependencies
- `process-engine-api-adapter-camunda-platform-7-embedded-spring-boot-starter`: SpringBoot starter for usage of Camunda 7 embedded Platform adapter
- `process-engine-api-adapter-camunda-platform-7-remote-core`: core implementation classes for Camunda 7 Platform remote without additional dependencies
- `process-engine-api-adapter-camunda-platform-7-remote-spring-boot-starter`: SpringBoot starter for usage of Camunda 7 Platform remote adapter
- `process-engine-api-adapter-camunda-platform-8-core`: core implementation classes for Camunda 8 Platform without additional dependencies
- `process-engine-api-adapter-camunda-platform-8-spring-boot-starter`: SpringBoot starter for usage of Camunda 8 Platform adapter
- `examples/java-common-fixture`: A project that is used independent of selected process engine adapter
- `examples/java-c7`: Project with embedded C7 engine and a simple process scenario
- `examples/java-c7-remote`: Project with C7 as remote engine engine and a simple process scenario
- `examples/java-c8`: Project with configuration of SaaS C8 engine and a simple process scenario

## API

The API consists of different parts independent of each other.

### Process API

The Process API provides functionality, required to control the lifecycle of the processes. It allows to start a new process instance.
It is intended to be used in outbound adapters of the port/adapter architecture in order to control the process engine from your application.

### Correlation API

The Correlation API provides functionality to correlate messages and signals with running process instances.
It is intended to be used in outbound adapters of the port/adapter architecture in order to control the process engine from your application.

### Signal API

The Correlation API provides functionality to correlate messages and signals with running process instances.
It is intended to be used in outbound adapters of the port/adapter architecture in order to control the process engine from your application.


### Task API

The Task API provides functionality to deal with tasks. The task handlers can be registered and get invoked when tasks
appear in the process engine. Since the Task API allows asynchronous processing, we provide a special API to complete tasks.

## Usage

If you want to try the library with Camunda 7, please add the following dependency to your Maven `pom.xml`.

```xml
<dependency>
<groupId>dev.bpm-crafters.process-engine-api</groupId>
<artifactId>process-engine-api-adapter-camunda-platform-c7-embedded-spring-boot-starter</artifactId>
</dependency>
```

If you want to try the library with Camunda 8, please add the following dependency to your Maven `pom.xml`.

```xml
<dependency>
<groupId>dev.bpm-crafters.process-engine-api</groupId>
<artifactId>process-engine-api-adapter-camunda-platform-c8-spring-boot-starter</artifactId>
</dependency>
```
8 changes: 3 additions & 5 deletions api/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,11 @@
<parent>
<groupId>dev.bpm-crafters.process-engine-api</groupId>
<artifactId>process-engine-api-root</artifactId>
<version>0.0.1-SNAPSHOT</version>
<version>0.0.1</version>
</parent>

<artifactId>process-engine-api</artifactId>

<dependencies>

</dependencies>
<name>API: ${project.artifactId}</name>
<description>Java API for engine-independent process functionality.</description>

</project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
package dev.bpmcrafters.processengineapi

/**
* Helper to build restrictions for subscriptions or correlations.
* @since 0.0.1
*/
object CommonRestrictions {

/**
* FIXME: consider to remove restriction names to adapters.
*/

const val ACTIVITY_ID = "activityId"
const val BUSINESS_KEY = "businessKey"
const val CORRELATION_KEY = "correlationKey"
const val PROCESS_DEFINITION_KEY = "processDefinitionKey"
const val PROCESS_INSTANCE_ID = "processInstanceId"
const val PROCESS_DEFINITION_ID = "processDefinitionId"
const val PROCESS_DEFINITION_VERSION_TAG = "processDefinitionVersionTag"
const val TASK_DEFINITION_KEY = "taskDefinitionKey"
const val TENANT_ID = "tenantId"
const val WITHOUT_TENANT_ID = "withoutTenantId"
const val MESSAGE_ID = "messageId"
const val MESSAGE_TTL = "messageTTL"
const val EXECUTION_ID = "executionId"

/**
* Creates a helper restrictions builder.
*/
@JvmStatic
fun builder(): RestrictionsBuilder = RestrictionsBuilder()

class RestrictionsBuilder internal constructor() {

private val restrictions = mutableMapOf<String, String>()

fun withProcessDefinitionKey(processDefinitionKey: String) = this.apply {
restrictions[PROCESS_DEFINITION_KEY] = processDefinitionKey
}

fun withTaskDefinitionKey(taskDefinitionKey: String) = this.apply {
restrictions[TASK_DEFINITION_KEY] = taskDefinitionKey
}

fun withTenantId(tenantId: String) = this.apply {
restrictions[TENANT_ID] = tenantId
}

fun withInstanceId(instanceId: String) = this.apply {
restrictions[PROCESS_INSTANCE_ID] = instanceId
}

fun withActivityId(activityId: String) = this.apply {
restrictions[ACTIVITY_ID] = activityId
}

fun withBusinessKey(businessKey: String) = this.apply {
restrictions[BUSINESS_KEY] = businessKey
}

fun withCorrelationKey(correlationKey: String) = this.apply {
restrictions[CORRELATION_KEY] = correlationKey
}

fun withRestriction(restriction: String, value: String) = this.apply {
restrictions[restriction] = value
}

fun build(): Map<String, String> = restrictions.toMap()
}
}
11 changes: 11 additions & 0 deletions api/src/main/kotlin/dev/bpmcrafters/processengineapi/Empty.kt
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
package dev.bpmcrafters.processengineapi

/**
* Special empty marker, to be able to deliver the Void / Unit, independent of Java / Kotlin.
*/
object Empty {
/**
* Comply with hashcode contract in Java.
*/
override fun hashCode(): Int = 1983210398
}
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
package dev.bpmcrafters.processengineapi

/**
* Meta info to express capability of an API.
* @since 0.0.1
*/
interface MetaInfo
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
package dev.bpmcrafters.processengineapi

/**
* APIs capable to describe a meta-aware instance.
* @since 0.0.1
*/
interface MetaInfoAware {
/**
* Provides meta information based on passed instance.
* @param instance to provide info for.
* @return meta info.
*/
fun meta(instance: MetaInfoAware): MetaInfo
}
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
package dev.bpmcrafters.processengineapi

interface PayloadSupplier {
fun payload(): () -> Map<String, Any>
}
import java.util.function.Supplier

/**
* Supplier for the payload.
* @since 0.0.1
*/
fun interface PayloadSupplier : Supplier<Map<String, Any>>
Loading

0 comments on commit 1c1d648

Please sign in to comment.