dapr/java-sdk

Dapr SDK for Java

Any language, any framework, anywhere

Dapr is a portable, serverless, event-driven runtime that makes it easy for developers to build resilient, stateless and stateful microservices that run on the cloud and edge and embraces the diversity of languages and developer frameworks.

Dapr codifies the best practices for building microservice applications into open, independent, building blocks that enable you to build portable applications with the language and framework of your choice. Each building block is independent and you can use one, some, or all of them in your application.

We are a Cloud Native Computing Foundation (CNCF) incubation project.

Goals

• Enable developers using any language or framework to write distributed applications
• Solve the hard problems developers face building microservice applications by providing best practice building blocks
• Be community driven, open and vendor neutral
• Gain new contributors
• Provide consistency and portability through open APIs
• Be platform agnostic across cloud and edge
• Embrace extensibility and provide pluggable components without vendor lock-in
• Enable IoT and edge scenarios by being highly performant and lightweight
• Be incrementally adoptable from existing code, with no runtime dependency

How it works

Dapr injects a side-car (container or process) to each compute unit. The side-car interacts with event triggers and communicates with the compute unit via standard HTTP or gRPC protocols. This enables Dapr to support all existing and future programming languages without requiring you to import frameworks or libraries.

Dapr offers built-in state management, reliable messaging (at least once delivery), triggers and bindings through standard HTTP verbs or gRPC interfaces. This allows you to write stateless, stateful and actor-like services following the same programming paradigm. You can freely choose consistency model, threading model and message delivery patterns.

Dapr runs natively on Kubernetes, as a self hosted binary on your machine, on an IoT device, or as a container that can be injected into any system, in the cloud or on-premises.

Dapr uses pluggable component state stores and message buses such as Redis as well as gRPC to offer a wide range of communication methods, including direct dapr-to-dapr using gRPC and async Pub-Sub with guaranteed delivery and at-least-once semantics.

Why Dapr?

Writing highly performant, scalable and reliable distributed application is hard. Dapr brings proven patterns and practices to you. It unifies event-driven and actors semantics into a simple, consistent programming model. It supports all programming languages without framework lock-in. You are not exposed to low-level primitives such as threading, concurrency control, partitioning and scaling. Instead, you can write your code by implementing a simple web server using familiar web frameworks of your choice.

Dapr is flexible in threading and state consistency models. You can leverage multi-threading if you choose to, and you can choose among different consistency models. This flexibility enables you to implement advanced scenarios without artificial constraints. Dapr is unique because you can transition seamlessly between platforms and underlying implementations without rewriting your code.

Features

• Event-driven Pub-Sub system with pluggable providers and at-least-once semantics
• Input and output bindings with pluggable providers
• State management with pluggable data stores
• Consistent service-to-service discovery and invocation
• Opt-in stateful models: Strong/Eventual consistency, First-write/Last-write wins
• Cross platform virtual actors
• Secret management to retrieve secrets from secure key vaults
• Rate limiting
• Built-in Observability support
• Runs natively on Kubernetes using a dedicated Operator and CRDs
• Supports all programming languages via HTTP and gRPC
• Multi-Cloud, open components (bindings, pub-sub, state) from Azure, AWS, GCP
• Runs anywhere, as a process or containerized
• Lightweight (58MB binary, 4MB physical memory)
• Runs as a sidecar - removes the need for special SDKs or libraries
• Dedicated CLI - developer friendly experience with easy debugging
• Clients for Java, .NET Core, Go, Javascript, Python, Rust and C++

Get Started using Dapr

See our Getting Started guide over in our docs.

Quickstarts and Samples

• See the quickstarts repository for code examples that can help you get started with Dapr.
• Explore additional samples in the Dapr samples repository.

Community

We want your contributions and suggestions! One of the easiest ways to contribute is to participate in discussions on the mailing list, chat on IM or the bi-weekly community calls. For more information on the community engagement, developer and contributing guidelines and more, head over to the Dapr community repo.

Contact Us

Reach out with any questions you may have and we'll make sure to answer them as soon as possible!

Platform	Link
💬 Instant Message Chat (preferred)
📧 Mailing List	https://groups.google.com/forum/#!forum/dapr-dev
🐤 Twitter	@daprdev

Community Call

Every two weeks we host a community call to showcase new features, review upcoming milestones, and engage in a Q&A. All are welcome!

📞 Visit https://aka.ms/dapr-community-call for upcoming dates and the meeting link.

Videos and Podcasts

We have a variety of keynotes, podcasts, and presentations available to reference and learn from.

📺 Visit https://docs.dapr.io/contributing/presentations/ for previous talks and slide decks.

Contributing to Dapr

See the Development Guide to get started with building and developing.

Repositories

Repo	Description
Dapr	The main repository that you are currently in. Contains the Dapr runtime code and overview documentation.
CLI	The Dapr CLI allows you to setup Dapr on your local dev machine or on a Kubernetes cluster, provides debugging support, launches and manages Dapr instances.
Docs	The documentation for Dapr.
Quickstarts	This repository contains a series of simple code samples that highlight the main Dapr capabilities.
Samples	This repository holds community maintained samples for various Dapr use cases.
Components-contrib	The purpose of components contrib is to provide open, community driven reusable components for building distributed applications.
Dashboard	General purpose dashboard for Dapr
Go-sdk	Dapr SDK for Go
Java-sdk	Dapr SDK for Java
JS-sdk	Dapr SDK for JavaScript
Python-sdk	Dapr SDK for Python
Dotnet-sdk	Dapr SDK for .NET
Rust-sdk	Dapr SDK for Rust
Cpp-sdk	Dapr SDK for C++
PHP-sdk	Dapr SDK for PHP

Code of Conduct

Please refer to our Dapr Community Code of Conduct

java-sdk's Issues

[java-sdk] New jar to allow Dapr's callback API in SpringBoot

A SpringBoot Application can easily depend on this jar and have Dapr's callback API running with a simple configuration change and implementing a base class/interface.

As an alternative to a base class, annotations can also be used, similar to how the .Net SDK does with ASP.Net.

[java-sdk] Adds checkstyle and bug finder

• Adds a checkstyle to Java SDK and make build fail due to style violations.
• Adds SpotBugs and make build fail due to violations.
• Fixes existing violations.
• Generated code should be excluded from static analysis.

Revisit locking in the sdk

There were discussions earlier about what areas need locks and which do not, because of turn-based concurrency. I believe the conceptual discussions were resolved. This issue is just a reminder to revisit locking in the code to ensure we are not locking where we do not need to.

Set up GitHub Actions workflow for java-sdk build and publish

Describe the proposal

Set up GitHub Actions for java-sdk build and publish

• Create workflow for build
• Create workflow for publish

[java-sdk] Create ActorProxy

1. Create the ActorProxy methods on the Java SDK, modeling it after the Dotnet proxy. It should only implement non remoting invocation methods, basically all InvokeAsync. Non remoting invocation is explained here

Hide actor APIs from DaprClient

DaprClient exposes actor APIs even though they are not for direct consumption. Move the APIs into internal classes in the Actor SDK.

Is there a sample which uses the actor pattern?

I wish I had a sample that uses the actor pattern.

[java-sdk] Java Actor runtime

Creating the Java Actor runtime classes, similar to the one in the Dotnet sdk.

Implementing the API endpoints for the SDK. The business logic should be (preferably) identical to the one in the Dotnet SDK.

Following are some of the few classes in C# SDK;

ActorRuntime: This is the actor runtime in SDK and contains information about registered types. It contains a mapping of ActorType and ActorManager. Actor types are registered with ActorRuntime.

ActorManager: It manages actors instances for an actor type, activates, deactivates them and make method calls to them.

ActorStateManager: Abstracts state management for Actors, provides a cache for Actor states, so that states which have already been worked on are not fetched again from Dapr for an active actor.

Actor: Base class for Actors. (In Java it can be called DaprActor)

DaprStateProvide: ActorStateManager uses it to interact with Dapr for state management.

RouterBuilderExtensions: This is for registering routes with aspnetcore, it registers the required routes (urls) on which Dapr runtime will call into user service code.

Document the process for uploading Maven package to repository/

This can be added to the wiki for the repo.

Is there a way to subscribe to topic and get data

Ask your question here

An example here shows how to publish event, but provides no information on how to subscribe and receive events?
I can see Node and Python examples at https://github.com/dapr/samples/tree/master/4.pub-sub,
But they are not easily transferable to java

Use Object instead of generics for Serialization

Serialize() methods don't need to use generics, just receive an Object.

Steps to regenerate Protobuf classes

Describe the proposal

What were the steps followed to generate the protobuf classes?

[java-sdk] Create example for Dapr PubSub

One example app for Dapr PubSub using Http.
One example app for Dapr PubSub using Grpc.
Documentation as README.md

[java-sdk] Create examples for Bindings in Http and Grpc

One example app for Dapr Bindings using Http.
One example app for Dapr Bindings using Grpc.
Documentation as README.md

Reach parity with Dapr features

Describe the proposal

Missing functionality that needs to be addressed:

1. Subscribe to topics
2. Bindings callbacks
3. Service invocation callback

I assume this is likely to be implemented in DaprClient

create the actor and related classes according the documentation as base for the java client sdk

What to do?

The actor as a basic principle of the concept needs to be created for the java-sdk. According to documentation and existing implementation in C#.

Class names, methods, types ... should be named similarly to avoid confusion.

Work on a plan and discuss with the maintainer.

Integration tests for method invocation

Validate method invocation in Java SDK.

Unit tests for stateless actors

Cover unit tests for the following scenarios for stateless actors:

Inheritance	Input Type	Output Type	State management (CRUD operations)	Exception in Actor's methods	Exception in Actor's runtime	Custom Serializer
No	String	String	No	No	No	No
No	String	Boolean	No	No	Yes	No
No	String	void	No	Yes	No	No
No	Class	Class	No	No	No	No
Yes	int	int	No	No	No	No
Yes	int	int	No	No	Yes	No
Yes	int	int	No	Yes	No	No

Validations for all scenario (when applicable):

• Output is as expected
• Exception is as expected
• Methods are invoked in the Actor class: onActivate(), onDeactivate(), onPreActorMethod(), onPostActorMethod()
• Timer is invoked()
• Reminder is invoked()

[WONTFIX] Use Gradle instead of Maven as build tool

Move to Gradle for build

I used Maven and Gradle in the past (not recent, though). I see Gradle has some benefits over Maven:

• Faster build for same tasks.
• Syntax in Groovy instead of XML.
• UX is command-line first instead of IDE first.
• Better dependency conflict resolution.

https://gradle.org/maven-vs-gradle/

[java-sdk e2e] Actor features tests

Implement E2E tests for Java-SDK following requirements as per dapr/dapr#821

Applicable scenarios:
Test 1: Actor Reminder
Test 2: Actor Timer
Test 3: Turn based concurrency when calling the same method from same actor ID
Test 4: Turn based concurrency when calling the same method from different actor IDs
Test 5: Actor - user service failover from 1 node to another

[java-sdk E2E] Create E2E foundation for Java-SDK

Create a E2E test foundation, so dapr's SDK can be tested with Dapr:

1. E2E tests run in standalone mode.
2. E2E tests can be kicked-off from PR comment (similar do dapr/dapr E2E).
3. All E2E code is written in Java, including sample apps.
4. Implement one hello-world test case, showcasing E2E tests for Java-SDK.

[Java SDK] Create example for method invocation

Create one example showing how to invoke a service method.
Provide documentation via README.md

Integration test for PubSub

[java-sdk E2E] Actor activation/deactivation test

Implement tests for java-sdk following same requirements as dapr/dapr#820:

Dapr config should be changed to support configuration and allow short time out (5s).
Implement a fake application listening to dapr.
app should implement actor related controller methods.
app should implement an extra method to return a "log" of events.

Add logic to add log entries for this test.
After actor is activated, add record to log array.
After actor method is invoked, add record to log array.
After actor is deactivated, add record to log array.

In test code:
Use ActorProxyImpl to invoke a method in the actor.
Sleep 5 seconds.
Make an API call to retrieve the log entries.
Validate the log entries contain: activate, deactivate and method invocation.

Review all 3rd party dependencies

Expected Behavior

Dapr's java-sdk has 3rd party dependencies.

Actual Behavior

Move them to an approved version/alternative when possible and identify exceptions.

Approved libraries should be in one of the references below:
https://azure.github.io/azure-sdk/java_implementation.html#dependencies
https://github.com/Azure/azure-sdk-for-java
https://github.com/Azure/azure-cosmosdb-java
(any other official Azure SDK)

Steps to Reproduce the Problem

Look at all our direct dependencies.

[java-sdk] Add builder classes for Dapr's Client

Implement Builder class for:

• Create Client on top of HTTP generated code.
• Create Client on top of GRPC generated code.

New example using Invoke over Grpc

Create a new example using Invoke over Grpc
Add README.md with instructions.

[java-sdk] define release process and set up CD to Nexus repo

This is to set up cd pipeline to deploy java sdk to GitHub Package for master branch.

• Release process: https://github.com/dapr/java-sdk/wiki/Release-Process
• Cert Rotation: https://github.com/dapr/java-sdk/wiki/Manage-OSSRH

Split Actor features in a separate jar

Remove all Actor-related features out of dapr-sdk.jar into dapr-sdk-actors.jar and make it an optional dependency.

[java-sdk] Sample app using SpringBoot

Create a sample app with SpringBoot using the SpringBoot specific jar from Issue #30 .

Provide support for custom serializer

Allows users to plug-in their own serializer, still offering a default implementation when null.

What should be the minimum Java version supported by Dapr SDK?

** What should be the minimum Java version supported by Dapr SDK?

I recommend Java 8 since it is the previous LTS version and still the most used version. Java 11 is the latest LTS version.

https://www.jetbrains.com/lp/devecosystem-2019/java/

Use byte[] for customer data and serialization/deserialization

In some places of the code we refer to Object, byte[] or String, including in the deserialization. Be consistent and always use byte[].

--Feedback from design review

Enable gRPC port for ClientBuilder

The ClientBuilder always looks for the Dapr HTTP env port, regardless if the the Client itself is HTTP or gRPC based.

[java-sdk] Doc how Dapr Java applications can be run/debug locally

Add to Java-SDK documentations instructions on how to debug a Java app using Dapr. It does not need to use the next version SDK, existing Grpc or "raw" HTTP calls is enough to showcase debugging.

[java-sdk] Code coverage

• Check for code coverage in Java SDK and output current line and branch coverage.

• Fail build if line or branch coverage is < 80% (examples excluded)

• Keep coverage threshold under 80% for this issue. We will switch to 80% in the end.

Unit tests for stateful actors

Cover unit tests for the following scenarios for stateful actors:

Inheritance	Input Type	Output Type	State management (CRUD operations)	Exception in Actor's methods	Exception in Actor's runtime	Custom Serializer
No	String	String	Yes	No	No	No
No	String	String	Yes	No	Yes	No
No	String	String	Yes	Yes	No	No
No	Class	Class	Yes	No	No	No
No	Class	Class	Yes	No	No	Yes
Yes	int	int	Yes	No	No	No
Yes	int	int	Yes	No	Yes	No
Yes	int	int	Yes	Yes	No	No

Validations for all scenario (when applicable):

• Output is as expected
• Exception is as expected
• State is saved as expected.
• Methods are invoked in the Actor class: onActivate(), onDeactivate(), onPreActorMethod(), onPostActorMethod()
• Timer is invoked()
• Reminder is invoked()

[sample] Add sample for Actors

Create a sample (in dapr/java-sdk) showing all features of Actors in Java:

1. Once all features for Actors in Dapr’s Java SDK are available, implement a sample showing how to use all Actor features. Sample using the SDK will be in this repo.
2. Add documentation, so users can execute in Windows, Linux and MacOS.
3. Add the original files used to generate any image, so external contributors can update documentation in the future.

java.util.concurrent.ExecutionException: io.grpc.StatusRuntimeException: UNIMPLEMENTED: Method not found: dapr.Dapr/PublishEvent

I use java-sdk create a demo for grpc publish event,and this demo host a grpc server ,but i get error as title .

dapr version:0.3.0

[java-sdk] Create Dapr's HTTP Client

NEW SCOPE:
Manually create http client for Dapr's APIs.

OLD SCOPE:

• Auto-generate http client from Dapr's OpenAPI definition (https://swagger.io/specification/)
• If needed, create OpenAPI definition in Dapr/dapr to seed auto-generation for any language.

Move DaprRuntime to test only + add CloudEvent serializer

DaprRuntime and related classes in io.dapr.runtime are not supposed to be exported as part of the SDK yet. Customer feedback is needed before we can offer a prescriptive solution like that.

On the other hand, offer a way for user to deserialize CloudEventEnvelope to process PubSub messages.

Move method logic inside Mono for GRPC Adapter

Expected Behavior

There should be no state or API call outside Mono.

Actual Behavior

Code in GRPC Adapter is making API call outside Mono.

Steps to Reproduce the Problem

As example, create an unit test for publishEvent() method doing the following:

1. Have a futureClient mock and create the GRPC adapter instance.
2. Call publishEvent() to get the Mono object but do NOT call block() on it.
3. Validate there was NO call to the futureClient mock.
4. block() on the mono object.
5. Validate there WAS call to the futueClient mock.

See code below as example of problem vs solution:

  @Override
  public <T> Mono<Void> publishEvent(String topic, T event, Map<String, String> metadata) {
    try {
      byte[] byteEvent = objectSerializer.serialize(event);
      Any data = Any.newBuilder().setValue(ByteString.copyFrom(byteEvent)).build();
      // TODO: handle metadata.

      DaprProtos.PublishEventEnvelope envelope = DaprProtos.PublishEventEnvelope.newBuilder()
          .setTopic(topic).setData(data).build();
      ListenableFuture<Empty> futureEmpty = client.publishEvent(envelope);
      return Mono.just(futureEmpty).flatMap(f -> {
        try {
          f.get();
        } catch (Exception ex) {
          return Mono.error(ex);
        }
        return Mono.empty();
      });
    } catch (Exception ex) {
      return Mono.error(ex);
    }
  }

Possible solution:

  @Override
  public <T> Mono<Void> publishEvent(String topic, T event, Map<String, String> metadata) {
  return Mono.fromSupplier(() -> {
      byte[] byteEvent = objectSerializer.serialize(event);
      Any data = Any.newBuilder().setValue(ByteString.copyFrom(byteEvent)).build();
      // TODO: handle metadata.

      DaprProtos.PublishEventEnvelope envelope = DaprProtos.PublishEventEnvelope.newBuilder()
          .setTopic(topic).setData(data).build();
      return envelope;
    }).map(envelope -> client.publishEvent(envelope))
      .map(future -> {
        try {
          future.get();
        } catch (Exception ex) {
          throw new RuntimeException(e);
        }
      });
  }

Integration test for state

Validate state store features in Java-SDK.

[java-sdk] Dapr's base Client

• Define interface for the Dapr's Client - wrapper on top of the auto-generated code.
• Implement Adapter for GRPC.
• Implement Adapter for HTTP.

Detail below:

Interface DaprClient { // customer will use this interface.
// methods defined as part of this work.
// actor APIs re defined here too.
}

Class GrpcDapClient implements DaprClient { // customers don’t talk to this one directly
DaprGrpc grpcClient;
// implements methods from interface
// throws exceptions for all actor APIs since actors are http only for now.
}

Class HttpDaprClient implements DaprClient { // customers don’t talk to this directly.
DaprHttpClient httpClient;
// implements methods from interface
// implements actors APIs as well
}

[java-sdk] Dapr HTTP Client for Actors

Create a Dapr client to make http calls directly (without using auto-gen client).
Implement all APIs needed to support Actors.

This overlaps with #22. While issue #22 will create a complete version of the Dapr client for Java, this one will unblock Actors work first, making HTTP calls directly.

Simplify Serializer

Change default serializer to be straight JSON and not have a custom logic to handle primitive types.

Change DaprClient generic classes with correct Dapr API structures

The current DaprClient doesn't expose or conform to the Dapr API.

The generic classes that are currently used require the user to hand-craft the payload sent to Dapr.
An SDK should encapsulate the Dapr API surface into strongly-typed classes for ease of use and understanding.

A partial list of the features that need to be exposed by the DaprClient:

1. State consistency
2. State concurrency
3. State metadata
4. Pub/Sub metadata
5. Service invocation metadata
6. Bindings metadata

This can be remedied by including custom classes instead of generic classes, similar to the gRPC auto-generated classes (envelopes).

[java-sdk] Set up CI to build and test

This issue is to set up github actions CI to build and test java-sdk.

• Create GitHub actions to build and test
• Add PR build policy

[java-sdk] Repackaging proposal to support Actors

Repackage the project into different projects (jars) and add support for Actors.

Proposed packages with corresponding jar name and java packages.

1. dapr-sdk-version.jar

Single project that clients can depend on to use Dapr in Java. There should be minimal (or none) use of 3rd party dependencies.

Java Packages:
io.dapr.client -> core interfaces and classes to communicate to Dapr's API
io.dapr.actors -> interfaces and classes for actors shared between actors' client and server side.
io.dapr.actors.common -> utility classes and interfaces shared between actor's client and server side.
io.dapr.actors.client-> interfaces and classes for actors' client side.
io.dapr.actors.runtime -> interfaces and classes for actors' server side.

Examples of possible interfaces in this jar:
io.dapr.client.HttpClient
io.dapr.client.GrpcClient

io.dapr.actors.Actor
io.dapr.actors.ActorId
io.dapr.actors.ActorService

io.dapr.actors.client.ActorProxy

io.dapr.actors.common.Utility

io.dapr.actors.runtime.ActorManager
io.dapr.actors.runtime.ActorReminder
io.dapr.actors.runtime.ActorTimer
io.dapr.actors.runtime.Remindable

2. dapr-sdk-callback-framework-version.jar

Multiple projects that clients can integrate with to easily create a callback API for Dapr to call to, for example: SpringBoot, Play, Netty, Spark (http://sparkjava.com/, not Apache Spark).

If we need to support different major versions of the same 3rd party framework, it should be handled as separate jars mainly due to avoid dependency conflicts.

Examples:
dapr-sdk-callback-springboot-2.jar
dapr-sdk-callback-play-1.jar
dapr-sdk-callback-play-2.jar

Java packages:
io.dapr.callback.framework -> one parent Java package per project.

Examples of possible classes in this jar:
io.dapr.callback.springboot.DaprController.java
io.dapr.callback.netty.DaprController.java

3. dapr-examples-version.jar

Samples that users can look into to understand how to use the API. There cannot be examples for multiple versions of the same 3rd party framework since there will be conflicting dependencies.

Java packages:
io.dapr.examples -> basic examples
io.dapr.examples.bindings -> examples using bindings
io.dapr.examples.pubsub -> examples using pubsub
io.dapr.examples.invoke-> examples using invoke
io.dapr.examples.actors-> examples using actors

Examples of possible classes in this package:
io.dapr.examples.HelloWorld.java
io.dapr.examples.actors.MyFirstActor.java

Integration test for bindings

Validate bindings e2e in java sdk.