From 4bf009f029dc329d9089dbc98e23dd93b5cfb6bc Mon Sep 17 00:00:00 2001 From: Samantha Coyle Date: Thu, 29 Oct 2026 17:57:14 -0500 Subject: [PATCH] docs: lead the README with durable workflows and trim prerequisites Signed-off-by: Samantha Coyle --- README.md | 91 +++++++++++++++++++++++++++---------------------------- 1 file changed, 44 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 06816f255b..32b97a4f62 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 @@ -90,23 +78,20 @@ For Maven: - + io.dapr dapr-sdk - 1.19.0 - + io.dapr - dapr-sdk-actors - 1.19.0 + dapr-sdk-workflows - + io.dapr - dapr-sdk-springboot - 1.19.0 + dapr-sdk-actors ... @@ -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' } @@ -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}" } ``` @@ -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 @@ -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. @@ -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 @@ -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.