Skip to content

docs: lead the README with durable workflows and trim prerequisites #1887

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dapr-bot merged 1 commit into from
Nov 2, 2026
Merged

docs: lead the README with durable workflows and trim prerequisites #1887

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 44 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,18 @@

[![Maven Central](https://img.shields.io/maven-central/v/io.dapr/dapr-sdk.svg?label=Maven%20Central&style=flat)](https://central.sonatype.com/artifact/io.dapr/dapr-sdk) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/dapr/java-sdk/.github%2Fworkflows%2Fbuild.yml?branch=master&label=Build&logo=github)](https://github.com/dapr/java-sdk/actions/workflows/build.yml) [![codecov](https://codecov.io/gh/dapr/java-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/dapr/java-sdk) [![GitHub License](https://img.shields.io/github/license/dapr/java-sdk?style=flat&label=License&logo=github)](https://github.com/dapr/java-sdk/blob/master/LICENSE) [![FOSSA Status](https://app.fossa.com/api/projects/custom%2B162%2Fgithub.com%2Fdapr%2Fjava-sdk.svg?type=shield)](https://app.fossa.com/projects/custom%2B162%2Fgithub.com%2Fdapr%2Fjava-sdk?ref=badge_shield) [![GitHub issue custom search in repo](https://img.shields.io/github/issues-search/dapr/java-sdk?query=type%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22&label=Good%20first%20issues&style=flat&logo=github)](https://github.com/dapr/java-sdk/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) [![Discord](https://img.shields.io/discord/778680217417809931?label=Discord&style=flat&logo=discord)](http://bit.ly/dapr-discord) [![YouTube Channel Views](https://img.shields.io/youtube/channel/views/UCtpSQ9BLB_3EXdWAUQYwnRA?style=flat&label=YouTube%20views&logo=youtube)](https://youtube.com/@daprdev) [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/daprdev?logo=x&style=flat)](https://twitter.com/daprdev)

This is the Dapr SDK for Java, including the following features:
The Java SDK for [Dapr](https://dapr.io): durable workflows, actors, pub/sub, state, service invocation, bindings and Spring Boot integration.

* PubSub
* Service Invocation
* Binding
* State Store
* Actors
* Workflows
* **Docs:** [Java SDK documentation](https://docs.dapr.io/developing-applications/sdks/java/)
* **API reference:** [Javadoc](https://dapr.github.io/java-sdk/)

## Workflows

Write durable workflows in plain Java with `dapr-sdk-workflows`. Workflow state is persisted by Dapr, so a workflow picks up where it left off after a crash or restart.

* [Workflow overview](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/)
* [Java SDK documentation](https://docs.dapr.io/developing-applications/sdks/java/)
* [Workflow examples](./examples/src/main/java/io/dapr/examples/workflows/)

## Getting Started

Expand All @@ -33,30 +37,12 @@ flowchart LR
For the full list of available APIs, see the [Dapr API reference](https://docs.dapr.io/reference/api/)

### Pre-Requisites
* SDKMAN! installed (recommended):
* [SDKMAN!](https://sdkman.io)
* Java IDE installed:
* [IntelliJ](https://www.jetbrains.com/idea/download/)
* [Eclipse](https://www.eclipse.org/downloads/)
* [Apache NetBeans](https://netbeans.apache.org/download/index.html)
* [Visual Studio Code](https://code.visualstudio.com/Download)
* Any other IDE for Java that you prefer.
* Install one of the following build tools for Java:
* [Maven 3.x](https://maven.apache.org/install.html)
* [Gradle 6.x](https://gradle.org/install/)
* If needed, install the corresponding plugin for the build tool in your IDE, for example:
* [Maven in IntelliJ](https://www.jetbrains.com/help/idea/maven.html)
* [Gradle in IntelliJ](https://www.jetbrains.com/help/idea/gradle-settings.html)
* [Maven in Eclipse with m2e](https://projects.eclipse.org/projects/technology.m2e)
* [Gradle in Eclipse with Buildship](https://projects.eclipse.org/projects/tools.buildship)
* An existing Java Maven or Gradle project. You may also start a new project via one of the options below:
* [New Maven project in IntelliJ](https://www.jetbrains.com/help/idea/maven-support.html#create_new_maven_project)
* [Maven in 5 minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html)
* [Install toxiproxy-server binary](https://github.com/Shopify/toxiproxy/releases)
* JDK 17 or later
* [Maven 3.x](https://maven.apache.org/install.html) or [Gradle](https://gradle.org/install/)
* An existing Java Maven or Gradle project. To start a new one, see [Maven in 5 minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html).
* The [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/), to run your application with a Dapr sidecar locally

### Install JDK

If using [SDKMAN!](https://sdkman.io), execute `sdk env install` to install the required JDK.
IDE setup and the tools needed to work on the SDK itself are under [Development](#development).

### Importing Dapr's Java SDK

Expand All @@ -69,7 +55,9 @@ Two BOMs are published:
- **`io.dapr:dapr-sdk-bom`** — core SDK modules (`dapr-sdk`, `dapr-sdk-actors`, `dapr-sdk-workflows`, `dapr-sdk-autogen`, `durabletask-client`, `testcontainers-dapr`) plus security-patched transitive dependencies (Netty, Jackson, commons-compress, commons-codec).
- **`io.dapr.spring:dapr-spring-bom`** — Spring-specific modules (`dapr-sdk-springboot`, `dapr-spring-*`). Imports `dapr-sdk-bom` transitively, so Spring users only need this single BOM.

Pick the one that matches your project. Importing a BOM ensures you inherit security fixes for transitive dependencies like the Netty CVEs.
`durabletask-client` is the gRPC client and worker for the Durable Task engine that runs Dapr workflows; `dapr-sdk-workflows` pulls it in, so you do not add it yourself.

Pick the one that matches your project. Importing a BOM ensures you inherit security fixes for transitive dependencies like the Netty CVEs. With a BOM imported, the version is set once on the BOM and left off each Dapr dependency.

##### Core (non-Spring) projects

Expand All @@ -90,23 +78,20 @@ For Maven:
</dependencyManagement>

<dependencies>
<!-- Dapr's core SDK with all features, except Actors. -->
<!-- Dapr's core SDK with all features, except Actors and Workflows. -->
<dependency>
<groupId>io.dapr</groupId>
<artifactId>dapr-sdk</artifactId>
<version>1.19.0</version>
</dependency>
<!-- Dapr's SDK for Actors (optional). -->
<!-- Dapr's SDK for Workflows (optional). -->
<dependency>
<groupId>io.dapr</groupId>
<artifactId>dapr-sdk-actors</artifactId>
<version>1.19.0</version>
<artifactId>dapr-sdk-workflows</artifactId>
</dependency>
<!-- Dapr's SDK integration with SpringBoot (optional). -->
<!-- Dapr's SDK for Actors (optional). -->
<dependency>
<groupId>io.dapr</groupId>
<artifactId>dapr-sdk-springboot</artifactId>
<version>1.19.0</version>
<artifactId>dapr-sdk-actors</artifactId>
</dependency>
...
</dependencies>
Expand All @@ -119,8 +104,10 @@ For Gradle:
dependencies {
implementation platform('io.dapr:dapr-sdk-bom:1.19.0')

// Dapr's core SDK with all features, except Actors.
compile('io.dapr:dapr-sdk:1.19.0')
// Dapr's core SDK with all features, except Actors and Workflows.
implementation 'io.dapr:dapr-sdk'
// Dapr's SDK for Workflows (optional).
implementation 'io.dapr:dapr-sdk-workflows'
// Dapr's SDK for Actors (optional).
implementation 'io.dapr:dapr-sdk-actors'
}
Expand Down Expand Up @@ -204,9 +191,11 @@ For Maven:
For Gradle:
```groovy
dependencies {
implementation 'io.dapr:dapr-sdk:1.19.0'
implementation 'io.dapr:dapr-sdk-actors:1.19.0'
implementation 'io.dapr:dapr-sdk-springboot:1.19.0'
def daprVersion = '1.19.0'

implementation "io.dapr:dapr-sdk:${daprVersion}"
implementation "io.dapr:dapr-sdk-actors:${daprVersion}"
implementation "io.dapr:dapr-sdk-springboot:${daprVersion}"
}
```

Expand Down Expand Up @@ -248,7 +237,7 @@ You can find a [step-by-step tutorial showing this integration here](./spring-bo

### API Documentation

Please, refer to our [Javadoc](https://dapr.github.io/java-sdk/) website.
See the [Javadoc](https://dapr.github.io/java-sdk/) for the API reference, and the [Java SDK documentation](https://docs.dapr.io/developing-applications/sdks/java/) for guides.

### Reactor API

Expand Down Expand Up @@ -325,6 +314,14 @@ Most exceptions thrown from the SDK are instances of `DaprException`. `DaprExcep

## Development

### Tools

* JDK 17. With [SDKMAN!](https://sdkman.io), run `sdk env install` in the repo root to install the JDK pinned in `.sdkmanrc`.
* Maven is not needed: use the wrapper, `./mvnw`.
* A Java IDE, for example [IntelliJ](https://www.jetbrains.com/idea/download/), [Eclipse](https://www.eclipse.org/downloads/), [Apache NetBeans](https://netbeans.apache.org/download/index.html) or [Visual Studio Code](https://code.visualstudio.com/Download), with Maven support if it needs a plugin:
* [Maven in IntelliJ](https://www.jetbrains.com/help/idea/maven.html)
* [Maven in Eclipse with m2e](https://projects.eclipse.org/projects/technology.m2e)

### Update URL to fetch proto files

Change the `dapr.proto.baseurl` property below in [pom.xml](./pom.xml) to point to the URL for the desired commit hash in Git if you need to target a proto file that is not been merged into master yet.
Expand All @@ -349,7 +346,7 @@ Note: You may need to run `./mvnw clean` after changing this setting to remove a
### Running Integration Tests (ITs)

#### Pre-Requisites
* [Pre-Requisites for the SDK](#pre-requisites)
* The [development tools](#tools)
* Docker installed and running
* [Docker Desktop](https://www.docker.com/products/docker-desktop)
* Bash shell
Expand All @@ -365,7 +362,7 @@ As a starting point for running the Integration Tests, first run `./mvnw clean i

#### Backing services (managed automatically by Testcontainers)

The integration tests use [Testcontainers](https://testcontainers.com/) to start and manage every backing service they depend on — Redis, Zipkin, MongoDB, Kafka, and the Dapr control plane (`placement` and `scheduler`) — automatically at test runtime.
The integration tests use [Testcontainers](https://testcontainers.com/) to start and manage every backing service they depend on — Redis, Zipkin, MongoDB, Kafka, [Toxiproxy](https://github.com/Shopify/toxiproxy) for the resiliency tests, and the Dapr control plane (`placement` and `scheduler`) — automatically at test runtime.

There is no separate step to bring these services up: you only need a running Docker daemon. Testcontainers pulls the required images and starts/stops the containers as the tests run.

Expand Down
Loading