mirror of https://github.com/dapr/java-sdk.git
359 lines
14 KiB
Markdown
359 lines
14 KiB
Markdown
---
|
|
type: docs
|
|
title: "Dapr Java SDK"
|
|
linkTitle: "Java"
|
|
weight: 1000
|
|
description: Java SDK packages for developing Dapr applications
|
|
---
|
|
|
|
## Pre-requisites
|
|
|
|
- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
|
|
- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
|
|
- JDK 11 or above - the published jars are compatible with Java 8:
|
|
- [AdoptOpenJDK 11 - LTS](https://adoptopenjdk.net/)
|
|
- [Oracle's JDK 15](https://www.oracle.com/java/technologies/javase-downloads.html)
|
|
- [Oracle's JDK 11 - LTS](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html)
|
|
- [OpenJDK](https://openjdk.java.net/)
|
|
- 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/)
|
|
|
|
## Importing Dapr's Java SDK
|
|
|
|
For a Maven project, add the following to your `pom.xml` file:
|
|
```xml
|
|
<project>
|
|
...
|
|
<dependencies>
|
|
...
|
|
<!-- Dapr's core SDK with all features, except Actors. -->
|
|
<dependency>
|
|
<groupId>io.dapr</groupId>
|
|
<artifactId>dapr-sdk</artifactId>
|
|
<version>1.6.0</version>
|
|
</dependency>
|
|
<!-- Dapr's SDK for Actors (optional). -->
|
|
<dependency>
|
|
<groupId>io.dapr</groupId>
|
|
<artifactId>dapr-sdk-actors</artifactId>
|
|
<version>1.6.0</version>
|
|
</dependency>
|
|
<!-- Dapr's SDK integration with SpringBoot (optional). -->
|
|
<dependency>
|
|
<groupId>io.dapr</groupId>
|
|
<artifactId>dapr-sdk-springboot</artifactId>
|
|
<version>1.6.0</version>
|
|
</dependency>
|
|
...
|
|
</dependencies>
|
|
...
|
|
</project>
|
|
```
|
|
|
|
For a Gradle project, add the following to your `build.gradle` file:
|
|
|
|
```java
|
|
dependencies {
|
|
...
|
|
// Dapr's core SDK with all features, except Actors.
|
|
compile('io.dapr:dapr-sdk:1.6.0')
|
|
// Dapr's SDK for Actors (optional).
|
|
compile('io.dapr:dapr-sdk-actors:1.6.0')
|
|
// Dapr's SDK integration with SpringBoot (optional).
|
|
compile('io.dapr:dapr-sdk-springboot:1.6.0')
|
|
}
|
|
```
|
|
|
|
If you are also using Spring Boot, you may run into a common issue where the OkHttp version that the Dapr SDK uses conflicts with the one specified in the Spring Boot _Bill of Materials_.
|
|
You can fix this by specifying a compatible OkHttp version in your project to match the version that the Dapr SDK uses:
|
|
|
|
```xml
|
|
<dependency>
|
|
<groupId>com.squareup.okhttp3</groupId>
|
|
<artifactId>okhttp</artifactId>
|
|
<version>4.9.0</version>
|
|
</dependency>
|
|
```
|
|
|
|
## Building blocks
|
|
|
|
The Java SDK allows you to interface with all of the [Dapr building blocks]({{< ref building-blocks >}}).
|
|
|
|
### Invoke a service
|
|
|
|
```java
|
|
import io.dapr.client.DaprClient;
|
|
import io.dapr.client.DaprClientBuilder;
|
|
|
|
try (DaprClient client = (new DaprClientBuilder()).build()) {
|
|
// invoke a 'GET' method (HTTP) skipping serialization: \say with a Mono<byte[]> return type
|
|
// for gRPC set HttpExtension.NONE parameters below
|
|
response = client.invokeMethod(SERVICE_TO_INVOKE, METHOD_TO_INVOKE, "{\"name\":\"World!\"}", HttpExtension.GET, byte[].class).block();
|
|
|
|
// invoke a 'POST' method (HTTP) skipping serialization: to \say with a Mono<byte[]> return type
|
|
response = client.invokeMethod(SERVICE_TO_INVOKE, METHOD_TO_INVOKE, "{\"id\":\"100\", \"FirstName\":\"Value\", \"LastName\":\"Value\"}", HttpExtension.POST, byte[].class).block();
|
|
|
|
System.out.println(new String(response));
|
|
|
|
// invoke a 'POST' method (HTTP) with serialization: \employees with a Mono<Employee> return type
|
|
Employee newEmployee = new Employee("Nigel", "Guitarist");
|
|
Employee employeeResponse = client.invokeMethod(SERVICE_TO_INVOKE, "employees", newEmployee, HttpExtension.POST, Employee.class).block();
|
|
}
|
|
```
|
|
|
|
- For a full guide on service invocation visit [How-To: Invoke a service]({{< ref howto-invoke-discover-services.md >}}).
|
|
- Visit [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/invoke) for code samples and instructions to try out service invocation
|
|
|
|
### Save & get application state
|
|
|
|
```java
|
|
import io.dapr.client.DaprClient;
|
|
import io.dapr.client.DaprClientBuilder;
|
|
import io.dapr.client.domain.State;
|
|
import reactor.core.publisher.Mono;
|
|
|
|
try (DaprClient client = (new DaprClientBuilder()).build()) {
|
|
// Save state
|
|
client.saveState(STATE_STORE_NAME, FIRST_KEY_NAME, myClass).block();
|
|
|
|
// Get state
|
|
State<MyClass> retrievedMessage = client.getState(STATE_STORE_NAME, FIRST_KEY_NAME, MyClass.class).block();
|
|
|
|
// Delete state
|
|
client.deleteState(STATE_STORE_NAME, FIRST_KEY_NAME).block();
|
|
}
|
|
```
|
|
|
|
- For a full list of state operations visit [How-To: Get & save state]({{< ref howto-get-save-state.md >}}).
|
|
- Visit [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/state) for code samples and instructions to try out state management
|
|
|
|
### Publish & subscribe to messages
|
|
|
|
##### Publish messages
|
|
|
|
```java
|
|
import io.dapr.client.DaprClient;
|
|
import io.dapr.client.DaprClientBuilder;
|
|
import io.dapr.client.domain.Metadata;
|
|
import static java.util.Collections.singletonMap;
|
|
|
|
try (DaprClient client = (new DaprClientBuilder()).build()) {
|
|
client.publishEvent(PUBSUB_NAME, TOPIC_NAME, message, singletonMap(Metadata.TTL_IN_SECONDS, MESSAGE_TTL_IN_SECONDS)).block();
|
|
}
|
|
```
|
|
|
|
##### Subscribe to messages
|
|
|
|
```java
|
|
import com.fasterxml.jackson.databind.ObjectMapper;
|
|
import io.dapr.Topic;
|
|
import io.dapr.client.domain.CloudEvent;
|
|
import org.springframework.web.bind.annotation.PostMapping;
|
|
import org.springframework.web.bind.annotation.RequestBody;
|
|
import org.springframework.web.bind.annotation.RestController;
|
|
import reactor.core.publisher.Mono;
|
|
|
|
@RestController
|
|
public class SubscriberController {
|
|
|
|
private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
|
|
|
|
@Topic(name = "testingtopic", pubsubName = "${myAppProperty:messagebus}")
|
|
@PostMapping(path = "/testingtopic")
|
|
public Mono<Void> handleMessage(@RequestBody(required = false) CloudEvent<?> cloudEvent) {
|
|
return Mono.fromRunnable(() -> {
|
|
try {
|
|
System.out.println("Subscriber got: " + cloudEvent.getData());
|
|
System.out.println("Subscriber got: " + OBJECT_MAPPER.writeValueAsString(cloudEvent));
|
|
} catch (Exception e) {
|
|
throw new RuntimeException(e);
|
|
}
|
|
});
|
|
}
|
|
|
|
@Topic(name = "testingtopic", pubsubName = "${myAppProperty:messagebus}",
|
|
rule = @Rule(match = "event.type == 'myevent.v2'", priority = 1))
|
|
@PostMapping(path = "/testingtopicV2")
|
|
public Mono<Void> handleMessageV2(@RequestBody(required = false) CloudEvent envelope) {
|
|
return Mono.fromRunnable(() -> {
|
|
try {
|
|
System.out.println("Subscriber got: " + cloudEvent.getData());
|
|
System.out.println("Subscriber got: " + OBJECT_MAPPER.writeValueAsString(cloudEvent));
|
|
} catch (Exception e) {
|
|
throw new RuntimeException(e);
|
|
}
|
|
});
|
|
}
|
|
|
|
}
|
|
```
|
|
|
|
- For a full guide on publishing messages and subscribing to a topic [How-To: Publish & subscribe]({{< ref howto-publish-subscribe.md >}}).
|
|
- Visit [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/pubsub/http) for code samples and instructions to try out pub/sub
|
|
|
|
### Interact with output bindings
|
|
|
|
```java
|
|
import io.dapr.client.DaprClient;
|
|
import io.dapr.client.DaprClientBuilder;
|
|
|
|
try (DaprClient client = (new DaprClientBuilder()).build()) {
|
|
// sending a class with message; BINDING_OPERATION="create"
|
|
client.invokeBinding(BINDING_NAME, BINDING_OPERATION, myClass).block();
|
|
|
|
// sending a plain string
|
|
client.invokeBinding(BINDING_NAME, BINDING_OPERATION, message).block();
|
|
}
|
|
```
|
|
|
|
- For a full guide on output bindings visit [How-To: Use bindings]({{< ref howto-bindings.md >}}).
|
|
- Visit [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/bindings/http) for code samples and instructions to try out output bindings
|
|
|
|
### Retrieve secrets
|
|
|
|
```java
|
|
import com.fasterxml.jackson.databind.ObjectMapper;
|
|
import io.dapr.client.DaprClient;
|
|
import io.dapr.client.DaprClientBuilder;
|
|
import java.util.Map;
|
|
|
|
try (DaprClient client = (new DaprClientBuilder()).build()) {
|
|
Map<String, String> secret = client.getSecret(SECRET_STORE_NAME, secretKey).block();
|
|
System.out.println(JSON_SERIALIZER.writeValueAsString(secret));
|
|
}
|
|
```
|
|
|
|
- For a full guide on secrets visit [How-To: Retrieve secrets]({{< ref howto-secrets.md >}}).
|
|
- Visit [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/secrets) for code samples and instructions to try out retrieving secrets
|
|
|
|
### Actors
|
|
An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the [Virtual Actor pattern](https://www.microsoft.com/en-us/research/project/orleans-virtual-actors/), which provides a single-threaded programming model and where actors are garbage collected when not in use. With Dapr's implementaiton, you write your Dapr actors according to the Actor model, and Dapr leverages the scalability and reliability that the underlying platform provides.
|
|
|
|
```java
|
|
import io.dapr.actors.ActorMethod;
|
|
import io.dapr.actors.ActorType;
|
|
import reactor.core.publisher.Mono;
|
|
|
|
@ActorType(name = "DemoActor")
|
|
public interface DemoActor {
|
|
|
|
void registerReminder();
|
|
|
|
@ActorMethod(name = "echo_message")
|
|
String say(String something);
|
|
|
|
void clock(String message);
|
|
|
|
@ActorMethod(returns = Integer.class)
|
|
Mono<Integer> incrementAndGet(int delta);
|
|
}
|
|
```
|
|
|
|
- For a full guide on actors visit [How-To: Use virtual actors in Dapr]({{< ref howto-actors.md >}}).
|
|
- Visit [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/actors) for code samples and instructions to try actors
|
|
|
|
### Get & Subscribe to application configurations
|
|
|
|
> Note this is a preview API and thus will only be accessible via the DaprPreviewClient interface and not the normal DaprClient interface
|
|
|
|
```java
|
|
import io.dapr.client.DaprClientBuilder;
|
|
import io.dapr.client.DaprPreviewClient;
|
|
import io.dapr.client.domain.ConfigurationItem;
|
|
import io.dapr.client.domain.GetConfigurationRequest;
|
|
import io.dapr.client.domain.SubscribeConfigurationRequest;
|
|
import reactor.core.publisher.Flux;
|
|
import reactor.core.publisher.Mono;
|
|
|
|
try (DaprPreviewClient client = (new DaprClientBuilder()).buildPreviewClient()) {
|
|
// Get configuration for a single key
|
|
Mono<ConfigurationItem> item = client.getConfiguration(CONFIG_STORE_NAME, CONFIG_KEY).block();
|
|
|
|
// Get Configurations for multiple keys
|
|
Mono<List<ConfigurationItem>> items =
|
|
client.getConfiguration(CONFIG_STORE_NAME, CONFIG_KEY_1, CONFIG_KEY_2);
|
|
|
|
// Susbcribe to Confifuration changes
|
|
Flux<List<ConfigurationItem>> outFlux = client.subscribeToConfiguration(CONFIG_STORE_NAME, CONFIG_KEY_1, CONFIG_KEY_2);
|
|
outFlux.subscribe(configItems -> configItems.forEach(...));
|
|
}
|
|
```
|
|
|
|
- For a full list of configuration operations visit [How-To: Manage configuration from a store]({{< ref howto-manage-configuration.md >}}).
|
|
- Visit [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/configuration) for code samples and instructions to try out different configuration operations.
|
|
|
|
### Query saved state
|
|
|
|
> Note this is a preview API and thus will only be accessible via the DaprPreviewClient interface and not the normal DaprClient interface
|
|
|
|
```java
|
|
import io.dapr.client.DaprClient;
|
|
import io.dapr.client.DaprClientBuilder;
|
|
import io.dapr.client.DaprPreviewClient;
|
|
import io.dapr.client.domain.QueryStateItem;
|
|
import io.dapr.client.domain.QueryStateRequest;
|
|
import io.dapr.client.domain.QueryStateResponse;
|
|
import io.dapr.client.domain.query.Query;
|
|
import io.dapr.client.domain.query.Sorting;
|
|
import io.dapr.client.domain.query.filters.EqFilter;
|
|
|
|
try (DaprClient client = builder.build(); DaprPreviewClient previewClient = builder.buildPreviewClient()) {
|
|
String searchVal = args.length == 0 ? "searchValue" : args[0];
|
|
|
|
// Create JSON data
|
|
Listing first = new Listing();
|
|
first.setPropertyType("apartment");
|
|
first.setId("1000");
|
|
...
|
|
Listing second = new Listing();
|
|
second.setPropertyType("row-house");
|
|
second.setId("1002");
|
|
...
|
|
Listing third = new Listing();
|
|
third.setPropertyType("apartment");
|
|
third.setId("1003");
|
|
...
|
|
Listing fourth = new Listing();
|
|
fourth.setPropertyType("apartment");
|
|
fourth.setId("1001");
|
|
...
|
|
Map<String, String> meta = new HashMap<>();
|
|
meta.put("contentType", "application/json");
|
|
|
|
// Save state
|
|
SaveStateRequest request = new SaveStateRequest(STATE_STORE_NAME).setStates(
|
|
new State<>("1", first, null, meta, null),
|
|
new State<>("2", second, null, meta, null),
|
|
new State<>("3", third, null, meta, null),
|
|
new State<>("4", fourth, null, meta, null)
|
|
);
|
|
client.saveBulkState(request).block();
|
|
|
|
|
|
// Create query and query state request
|
|
|
|
Query query = new Query()
|
|
.setFilter(new EqFilter<>("propertyType", "apartment"))
|
|
.setSort(Arrays.asList(new Sorting("id", Sorting.Order.DESC)));
|
|
QueryStateRequest request = new QueryStateRequest(STATE_STORE_NAME)
|
|
.setQuery(query);
|
|
|
|
// Use preview client to call query state API
|
|
QueryStateResponse<MyData> result = previewClient.queryState(request, MyData.class).block();
|
|
|
|
// View Query state response
|
|
System.out.println("Found " + result.getResults().size() + " items.");
|
|
for (QueryStateItem<Listing> item : result.getResults()) {
|
|
System.out.println("Key: " + item.getKey());
|
|
System.out.println("Data: " + item.getValue());
|
|
}
|
|
}
|
|
|
|
```
|
|
- For a full list of configuration operations visit [How-To: Query state]({{< ref howto-state-query-api.md >}}).
|
|
- Visit [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/querystate) for complete code sample.
|
|
|
|
## Related links
|
|
- [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples)
|