mirror of https://github.com/dapr/java-sdk.git
Add dapr docs (#581)
* Add Dapr Docs * Added Java code examples for all building blocks * Fixed version numbers and comments * Fixed version numbers * Update java-contributing.md * PR review updates. - Reduce Dapr version to 1.1.0 - Correct code syntax - Describe Virtual Actors Pattern * Change version back to 1.1.0 * Add Dapr Docs * Added Java code examples for all building blocks * Fixed version numbers and comments * Fixed version numbers * Update java-contributing.md * PR review updates. - Reduce Dapr version to 1.1.0 - Correct code syntax - Describe Virtual Actors Pattern * Change version back to 1.1.0 * Reference shortcode for java sdk version * Update docs version script * Rever version of SDK to 1.1.0 Co-authored-by: Paul Yuknewicz <paulyuk@microsoft.com> Co-authored-by: Artur Souza <artursouza.ms@outlook.com>
This commit is contained in:
greenie-msft
GitHub
parent
50f80d8af5
commit
d3df194bad
|
|
@ -18,6 +18,7 @@ This is the Dapr SDK for Java, including the following features:
|
|||
|
||||
#### Pre-Requisites
|
||||
* 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-jdk15-downloads.html)
|
||||
* [Oracle's JDK 11 - LTS](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html)
|
||||
* [OpenJDK](https://openjdk.java.net/)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,25 @@
|
|||
# Dapr Java SDK documentation
|
||||
|
||||
This page covers how the documentation is structured for the Dapr Java SDK
|
||||
|
||||
## Dapr Docs
|
||||
|
||||
All Dapr documentation is hosted at [docs.dapr.io](https://docs.dapr.io), including the docs for the [Java SDK](https://docs.dapr.io/developing-applications/sdks/java/). Head over there if you want to read the docs.
|
||||
|
||||
### Java SDK docs source
|
||||
|
||||
Although the docs site code and content is in the [docs repo](https://github.com/dapr/docs), the Java SDK content and images are within the `content` and `static` directories, respectively.
|
||||
|
||||
This allows separation of roles and expertise between maintainers, and makes it easy to find the docs files you are looking for.
|
||||
|
||||
## Writing Java SDK docs
|
||||
|
||||
To get up and running to write Java SDK docs, visit the [docs repo](https://github.com/dapr/docs) to initialize your environment. It will clone both the docs repo and this repo, so you can make changes and see it rendered within the site instantly, as well as commit and PR into this repo.
|
||||
|
||||
Make sure to read the [docs contributing guide](https://docs.dapr.io/contributing/contributing-docs/) for information on style/semantics/etc.
|
||||
|
||||
## Docs architecture
|
||||
|
||||
The docs site is built on [Hugo](https://gohugo.io), which lives in the docs repo. This repo is setup as a git submodule so that when the repo is cloned and initialized, the java-sdk repo, along with the docs, are cloned as well.
|
||||
|
||||
Then, in the Hugo configuration file, the `daprdocs/content` and `daprdocs/static` directories are redirected to the `daprdocs/developing-applications/sdks/java` and `static/java` directories, respectively. Thus, all the content within this repo is folded into the main docs site.
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Contributing to the Java SDK"
|
||||
linkTitle: "Java SDK"
|
||||
weight: 3000
|
||||
description: Guidelines for contributing to the Dapr Java SDK
|
||||
---
|
||||
|
||||
When contributing to the [Java SDK](https://github.com/dapr/java-sdk) the following rules and best-practices should be followed.
|
||||
|
||||
## Examples
|
||||
|
||||
The `examples` directory contains code samples for users to run to try out specific functionality of the various Java SDK packages and extensions. When writing new and updated samples keep in mind:
|
||||
|
||||
- All examples should be runnable on Windows, Linux, and MacOS. While Java code is consistent among operating systems, any pre/post example commands should provide options through [codetabs]({{< ref "contributing-docs.md#tabbed-content" >}})
|
||||
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.
|
||||
|
||||
## Docs
|
||||
|
||||
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the documentation website is built, this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs, keep in mind:
|
||||
|
||||
- All rules in the [docs guide]({{< ref contributing-docs.md >}}) should be followed in addition to these.
|
||||
- All files and directories should be prefixed with `java-` to ensure all file/directory names are globally unique across all Dapr documentation.
|
||||
|
|
@ -0,0 +1,232 @@
|
|||
---
|
||||
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:
|
||||
```java
|
||||
<project>
|
||||
...
|
||||
<dependencies>
|
||||
...
|
||||
// Dapr's core SDK with all features, except Actors.
|
||||
<dependency>
|
||||
<groupId>io.dapr</groupId>
|
||||
<artifactId>dapr-sdk</artifacetId>
|
||||
<version>1.1.0</version>
|
||||
</dependency>
|
||||
// Dapr's SDK for Actors (optional).
|
||||
<dependency>
|
||||
<groupId>io.dapr</groupId>
|
||||
<artifactId>dapr-sdk-actors</artifactId>
|
||||
<version>1.1.0</version>>
|
||||
</dependency>
|
||||
// Dapr's SDK integration with SpringBoot (optional).
|
||||
<dependency>
|
||||
<groupId>io.dapr</groupId>
|
||||
<artifactId>dapr-sdk-springboot</artifactId>
|
||||
<version>1.1.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.1.0'))
|
||||
// Dapr's SDK for Actors (optional).
|
||||
compile('io.dapr:dapr-sdk-actors:1.1.0')
|
||||
// Dapr's SDK integration with SpringBoot (optional).
|
||||
compile('io.dapr:dapr-sdk-springboot:1.1.0')
|
||||
}
|
||||
```
|
||||
|
||||
## 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);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
- For a full list of state operations visit [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
|
||||
|
||||
## Related links
|
||||
- [Java SDK examples](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples)
|
||||
|
|
@ -7,10 +7,14 @@ DAPR_JAVA_SDK_VERSION=$1
|
|||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
sed -i bak "s/<version>.*<\/version>\$/<version>${DAPR_JAVA_SDK_VERSION}<\/version>/g" README.md
|
||||
sed -i bak "s/compile('io.dapr:\(.*\):.*')/compile('io.dapr:\\1:${DAPR_JAVA_SDK_VERSION}')/g" README.md
|
||||
sed -i bak "s/<version>.*<\/version>\$/<version>${DAPR_JAVA_SDK_VERSION}<\/version>/g" daprdocs/content/en/java-sdk-docs/_index.md
|
||||
sed -i bak "s/compile('io.dapr:\(.*\):.*')/compile('io.dapr:\\1:${DAPR_JAVA_SDK_VERSION}')/g" daprdocs/content/en/java-sdk-docs/_index.md
|
||||
rm README.mdbak
|
||||
else
|
||||
sed -i "s/<version>.*<\/version>\$/<version>${DAPR_JAVA_SDK_VERSION}<\/version>/g" README.md
|
||||
sed -i "s/compile('io.dapr:\(.*\):.*')/compile('io.dapr:\\1:${DAPR_JAVA_SDK_VERSION}')/g" README.md
|
||||
sed -i "s/<version>.*<\/version>\$/<version>${DAPR_JAVA_SDK_VERSION}<\/version>/g" daprdocs/content/en/java-sdk-docs/_index.md
|
||||
sed -i "s/compile('io.dapr:\(.*\):.*')/compile('io.dapr:\\1:${DAPR_JAVA_SDK_VERSION}')/g" daprdocs/content/en/java-sdk-docs/_index.md
|
||||
fi
|
||||
|
||||
rm -rf docs
|
||||
|
|
|
|||
Loading…
Reference in New Issue