From 376a49ac176128fe843583c4160f10d769360870 Mon Sep 17 00:00:00 2001 From: siri-varma Date: Wed, 23 Apr 2025 14:42:59 -0700 Subject: [PATCH 1/2] Add doc for jobs Signed-off-by: siri-varma --- .../en/java-sdk-docs/java-jobs/_index.md | 7 + .../java-jobs/java-jobs-howto.md | 159 ++++++++++++++++++ .../io/dapr/examples/jobs/JobsController.java | 2 +- 3 files changed, 167 insertions(+), 1 deletion(-) create mode 100644 daprdocs/content/en/java-sdk-docs/java-jobs/_index.md create mode 100644 daprdocs/content/en/java-sdk-docs/java-jobs/java-jobs-howto.md diff --git a/daprdocs/content/en/java-sdk-docs/java-jobs/_index.md b/daprdocs/content/en/java-sdk-docs/java-jobs/_index.md new file mode 100644 index 000000000..b9cb903a3 --- /dev/null +++ b/daprdocs/content/en/java-sdk-docs/java-jobs/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Jobs" +linkTitle: "Jobs" +weight: 3000 +description: With the Dapr Job package, you can interact with the Dapr Job APIs from a Java application to trigger future operations to run according to a predefined schedule with an optional payload. To get started, walk through the [Dapr Jobs]({{< ref java-jobs-howto.md >}}) how-to guide. +--- diff --git a/daprdocs/content/en/java-sdk-docs/java-jobs/java-jobs-howto.md b/daprdocs/content/en/java-sdk-docs/java-jobs/java-jobs-howto.md new file mode 100644 index 000000000..d237f2359 --- /dev/null +++ b/daprdocs/content/en/java-sdk-docs/java-jobs/java-jobs-howto.md @@ -0,0 +1,159 @@ +--- +type: docs +title: "How to: Author and manage Dapr Jobs in the Java SDK" +linkTitle: "How to: Author and manage Jobs" +weight: 20000 +description: How to get up and running with Jobs using the Dapr Java SDK +--- + +As part of this demonstration we will schedule a Dapr Job. The scheduled job will trigger an endpoint registered in the +same app. With the [provided jobs example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/jobs), you will: + +- Register an endpoint for the Jobs runtime to invoke as part of the schedule [Endpoint Registration](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/jobs/DemoJobsSpringApplication.java) +- Schedule a Job [Job scheduling example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/jobs/DemoJobsClient.java) + +This example uses the default configuration from `dapr init` in [self-hosted mode](https://github.com/dapr/cli#install-dapr-on-your-local-machine-self-hosted). + +## Prerequisites + +- [Dapr CLI and initialized environment](https://docs.dapr.io/getting-started). +- Java JDK 11 (or greater): + - [Oracle JDK](https://www.oracle.com/java/technologies/downloads), or + - OpenJDK +- [Apache Maven](https://maven.apache.org/install.html), version 3.x. +- [Docker Desktop](https://www.docker.com/products/docker-desktop) + +## Set up the environment + +Clone the Java SDK repo and navigate into it. + +```bash +git clone https://github.com/dapr/java-sdk.git +cd java-sdk +``` + +Run the following command to install the requirements for running this jobs sample with the Dapr Java SDK. + +```bash +mvn clean install -DskipTests +``` + +From the Java SDK root directory, navigate to the Dapr Workflow example. + +```bash +cd examples +``` + +We'll run a command that starts the Dapr sidecar. + +```sh +dapr run --app-id jobsapp --dapr-grpc-port 51439 --dapr-http-port 3500 --app-port 8080 +``` + +> Dapr listens for HTTP requests at `http://localhost:3500` and internal Jobs gRPC requests at `http://localhost:51439`. + +## Register a job and gets its details + +```java +public class DemoJobsClient { + + /** + * The main method of this app to register and fetch jobs. + */ + public static void main(String[] args) throws Exception { + Map, String> overrides = Map.of( + Properties.HTTP_PORT, "3500", + Properties.GRPC_PORT, "51439" + ); + + try (DaprPreviewClient client = new DaprClientBuilder().withPropertyOverrides(overrides).buildPreviewClient()) { + + // Schedule a job. + System.out.println("**** Scheduling a Job with name dapr-jobs-1 *****"); + ScheduleJobRequest scheduleJobRequest = new ScheduleJobRequest("dapr-job-1", + JobSchedule.fromString("* * * * * *")).setData("Hello World!".getBytes()); + client.scheduleJob(scheduleJobRequest).block(); + + System.out.println("**** Scheduling job dapr-jobs-1 completed *****"); + + // Get a job. + System.out.println("**** Retrieving a Job with name dapr-jobs-1 *****"); + GetJobResponse getJobResponse = client.getJob(new GetJobRequest("dapr-job-1")).block(); + } + } +} +``` + +```sh +java -jar target/dapr-java-sdk-examples-exec.jar io.dapr.examples.jobs.DemoJobsClient +``` + +### Sample output +``` +**** Scheduling a Job with name dapr-jobs-1 ***** +**** Scheduling job dapr-jobs-1 completed ***** +**** Retrieving a Job with name dapr-jobs-1 ***** +``` + +## Set up an endpoint to be invoked when the job is triggered + +The `DemoJobsSpringApplication` class starts a Spring Boot application that registers the endpoints specified in the `JobsController` +This endpoint acts like a callback for the scheduled job requests. + +```java +@RestController +public class JobsController { + + /** + * Handles jobs callback from Dapr. + * + * @param jobName name of the job. + * @param payload data from the job if payload exists. + * @return Empty Mono. + */ + @PostMapping("/job/{jobName}") + public Mono handleJob(@PathVariable("jobName") String jobName, + @RequestBody(required = false) byte[] payload) { + System.out.println("Job Name: " + jobName); + System.out.println("Job Payload: " + new String(payload)); + + return Mono.empty(); + } +} +``` + +Parameters: + +* `jobName`: The name of the job that triggered the callback. +* `payload`: Optional payload data associated with the job (as a byte array). + +Command to run the Spring boot app: + +```sh +java -jar target/dapr-java-sdk-examples-exec.jar io.dapr.examples.jobs.DemoJobsSpringApplication +``` + +### Sample output +``` +Job Name: dapr-job-1 +Job Payload: Hello World! +``` + +## Delete a scheduled job + +```java +public class DemoJobsClient { + + /** + * The main method of this app to register and fetch jobs. + */ + public static void main(String[] args) throws Exception { + try (DaprPreviewClient client = new DaprClientBuilder().buildPreviewClient()) { + + // Get a job. + System.out.println("**** Delete a Job with name dapr-jobs-1 *****"); + client.deleteJob(new DeleteJobRequest("dapr-job-1")).block(); + } + } +} +``` \ No newline at end of file diff --git a/examples/src/main/java/io/dapr/examples/jobs/JobsController.java b/examples/src/main/java/io/dapr/examples/jobs/JobsController.java index 48548f974..5d73beede 100644 --- a/examples/src/main/java/io/dapr/examples/jobs/JobsController.java +++ b/examples/src/main/java/io/dapr/examples/jobs/JobsController.java @@ -23,7 +23,7 @@ * SpringBoot Controller to handle jobs callback. */ @RestController -public class JobsController { +public class JobsController { /** * Handles jobs callback from Dapr. From cfa4e98c145694d54abfbc8c4cd6dfba2fd35f20 Mon Sep 17 00:00:00 2001 From: siri-varma Date: Wed, 23 Apr 2025 15:31:49 -0700 Subject: [PATCH 2/2] Add docs for Jobs Signed-off-by: siri-varma --- .../java-jobs/java-jobs-howto.md | 33 +++++++++++-------- .../io/dapr/examples/jobs/JobsController.java | 2 +- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/daprdocs/content/en/java-sdk-docs/java-jobs/java-jobs-howto.md b/daprdocs/content/en/java-sdk-docs/java-jobs/java-jobs-howto.md index d237f2359..e116deff0 100644 --- a/daprdocs/content/en/java-sdk-docs/java-jobs/java-jobs-howto.md +++ b/daprdocs/content/en/java-sdk-docs/java-jobs/java-jobs-howto.md @@ -9,8 +9,8 @@ description: How to get up and running with Jobs using the Dapr Java SDK As part of this demonstration we will schedule a Dapr Job. The scheduled job will trigger an endpoint registered in the same app. With the [provided jobs example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/jobs), you will: -- Register an endpoint for the Jobs runtime to invoke as part of the schedule [Endpoint Registration](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/jobs/DemoJobsSpringApplication.java) - Schedule a Job [Job scheduling example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/jobs/DemoJobsClient.java) +- Register an endpoint for the Jobs runtime to invoke as part of the schedule [Endpoint Registration](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/jobs/DemoJobsSpringApplication.java) This example uses the default configuration from `dapr init` in [self-hosted mode](https://github.com/dapr/cli#install-dapr-on-your-local-machine-self-hosted). @@ -25,7 +25,7 @@ This example uses the default configuration from `dapr init` in [self-hosted mod ## Set up the environment -Clone the Java SDK repo and navigate into it. +Clone the [Java SDK repo](https://github.com/dapr/java-sdk) and navigate into it. ```bash git clone https://github.com/dapr/java-sdk.git @@ -50,9 +50,12 @@ We'll run a command that starts the Dapr sidecar. dapr run --app-id jobsapp --dapr-grpc-port 51439 --dapr-http-port 3500 --app-port 8080 ``` -> Dapr listens for HTTP requests at `http://localhost:3500` and internal Jobs gRPC requests at `http://localhost:51439`. +> Now, Dapr is listening for HTTP requests at `http://localhost:3500` and internal Jobs gRPC requests at `http://localhost:51439`. + +## Register a job and Get its details -## Register a job and gets its details +In the `DemoJobsClient` there are steps to Register a Job. Calling the `scheduleJob` on the `DaprPreviewClient` +will schedule a job with the Dapr Runtime. ```java public class DemoJobsClient { @@ -61,11 +64,6 @@ public class DemoJobsClient { * The main method of this app to register and fetch jobs. */ public static void main(String[] args) throws Exception { - Map, String> overrides = Map.of( - Properties.HTTP_PORT, "3500", - Properties.GRPC_PORT, "51439" - ); - try (DaprPreviewClient client = new DaprClientBuilder().withPropertyOverrides(overrides).buildPreviewClient()) { // Schedule a job. @@ -75,15 +73,18 @@ public class DemoJobsClient { client.scheduleJob(scheduleJobRequest).block(); System.out.println("**** Scheduling job dapr-jobs-1 completed *****"); - - // Get a job. - System.out.println("**** Retrieving a Job with name dapr-jobs-1 *****"); - GetJobResponse getJobResponse = client.getJob(new GetJobRequest("dapr-job-1")).block(); } } } ``` +and calling a getJob retrieves the created job details +``` +client.getJob(new GetJobRequest("dapr-job-1")).block() +``` + +Command to run the `DemoJobsClient` + ```sh java -jar target/dapr-java-sdk-examples-exec.jar io.dapr.examples.jobs.DemoJobsClient ``` @@ -156,4 +157,8 @@ public class DemoJobsClient { } } } -``` \ No newline at end of file +``` + +## Next steps +- [Learn more about Jobs]({{< ref jobs-overview.md >}}) +- [Jobs API reference]({{< ref jobs_api.md >}}) \ No newline at end of file diff --git a/examples/src/main/java/io/dapr/examples/jobs/JobsController.java b/examples/src/main/java/io/dapr/examples/jobs/JobsController.java index 5d73beede..48548f974 100644 --- a/examples/src/main/java/io/dapr/examples/jobs/JobsController.java +++ b/examples/src/main/java/io/dapr/examples/jobs/JobsController.java @@ -23,7 +23,7 @@ * SpringBoot Controller to handle jobs callback. */ @RestController -public class JobsController { +public class JobsController { /** * Handles jobs callback from Dapr.