Add the Jobs SDK

[siri-varma]

PR Overview: Jobs SDK Integration

This PR introduces the Jobs SDK with three main APIs: Schedule, Get, and Delete Job. The implementation is divided into the following categories:

• Core Logic
• Models
• Tests (Unit and Integration)

---

Core Logic

The core logic is implemented in two key classes, as detailed below:

Class	Description	Details
CronExpressionBuilder	Builds Cron expressions compliant with Dapr sidecar expectations.	- Supports valid Cron syntax (*, /, and other ranges). - References: Jobs API and .NET SDK.
DaprJobsClient	Manages the ScheduleJob, Get, and DeleteJob APIs. Handles validations and async calls.	- Schedules, retrieves, and deletes jobs. - Validates inputs and performs async operations for job management.

---

API Contracts

The following are the method signatures for the key APIs:

1. Schedule Job

This API schedules a job based on the provided request.

public Mono<Void> scheduleJob(ScheduleJobRequest createJobRequest);

• Input: createJobRequest — Contains the necessary parameters to schedule the job.
• Output: Returns a Mono<Void> to signify the completion of the scheduling operation.

2. Get Job

This API retrieves a job's status or details based on the given request.

public Mono<GetJobResponse> getJob(GetJobRequest getJobRequest);

• Input: getJobRequest — Contains the parameters needed to retrieve a job.
• Output: Returns a Mono<GetJobResponse>, which includes the job details or status.

3. Delete Job

This API deletes a job based on the provided request.

public Mono<Void> deleteJob(DeleteJobRequest deleteJobRequest);

• Input: deleteJobRequest — Contains the necessary parameters to delete a job.
• Output: Returns a Mono<Void> to signify the deletion operation has been completed.

---

Models

The rest of the classes in this SDK are models that are constructed using the getter/setter pattern,

---

Tests

The testing section includes:

• Unit Tests: Focus on validating the functionality of individual components.
• Integration Tests: Ensure the system's interaction with external dependencies (e.g., the Dapr sidecar) works as expected.

---

Issue Reference

We strive to ensure that all PRs are opened based on a relevant issue, where the problem or feature has been discussed prior to implementation.

This PR addresses and closes the following issue: #1101, #1300

---

Checklist

Please make sure you've completed the relevant tasks for this PR:

• Code compiles correctly
• Created/updated tests
• Extended the documentation

---

[salaboy]

@siri-varma can you take a look at my comments? @artur-ciocanu I am curious about your feedback here too.

[artur-ciocanu]

@siri-varma thanks for all your work! I have reviewed the PR and I wanted to share a few general observations/recommendations:

• As far as I saw different maintainers decided to approach modularity differently. In Dotnet SDK we have separate DLLs for different functionality, in Python everything is in a single client, but the APIs are suffixed with alpha1. In Java SDK we have a special interface called DaprPreviewClient that should host all the alpha APIs. I would recommend having a single client and keep everything in sdk module and use DaprPreviewClient for alpha APIs like Jobs API and Conversation API
• Similar to above, let's push everything to sdk module, so we avoid creating additional Maven modules
• Since Jobs API is still alpha, I think it is too early to commit to creating our own CRON expression builder. As far as I can tell a lot of code in this PR is dedicated to CRON expressions. For now I think it is enough to just use CRON expressions as string value. The only thing that we should make sure is that the CRON expression is valid, although I think if it is not, the Dapr sidecar will complain.
• In the Jobs API that have been added there is a lot of repetition regarding validating model fields like something is not null etc, I would suggest extracting all those validations to separate methods like:
  • validateScheduleJobRequest(...) - to validate ScheduleJobRequest
  • validateGetJobRequest(...) - to validate GetJobRequest
  • validateDeleteJobRequest(...) - to validate DeleteJobRequest
    This way we will have clean separation between data validation and GRPC method invocation.
• You might want to look into other APIs to make sure that you use the right interceptors to ensure tracing data is properly propagated. Although we could address this later, as well.

CC: @salaboy @cicoyle

[artur-ciocanu]

@siri-varma please check my comment and let me know your thoughts.

[siri-varma]

Had a discussion with @artur-ciocanu regarding the comments and this is what we were thinking

You might want to look into other APIs to make sure that you use the right interceptors to ensure tracing data is properly propagated. Although we could address this later, as well.
The only thing that we should make sure is that the CRON expression is valid

Will address the above in a different PR

Will also move CronExpressionBuilder to a different PR for two reasons

• Because of the amount of logic present in the builder
• We also want to discuss how the SDK should support such a builder while considering both plain Java and Spring implementations.

cc: @salaboy / @cicoyle

[siri-varma]

@artur-ciocanu Addressed all the comments

[siri-varma]

@siri-varma thanks for all your work! I have reviewed the PR and I wanted to share a few general observations/recommendations:

• As far as I saw different maintainers decided to approach modularity differently. In Dotnet SDK we have separate DLLs for different functionality, in Python everything is in a single client, but the APIs are suffixed with alpha1. In Java SDK we have a special interface called DaprPreviewClient that should host all the alpha APIs. I would recommend having a single client and keep everything in sdk module and use DaprPreviewClient for alpha APIs like Jobs API and Conversation API

• Similar to above, let's push everything to sdk module, so we avoid creating additional Maven modules

• Since Jobs API is still alpha, I think it is too early to commit to creating our own CRON expression builder. As far as I can tell a lot of code in this PR is dedicated to CRON expressions. For now I think it is enough to just use CRON expressions as string value. The only thing that we should make sure is that the CRON expression is valid, although I think if it is not, the Dapr sidecar will complain.

• In the Jobs API that have been added there is a lot of repetition regarding validating model fields like something is not null etc, I would suggest extracting all those validations to separate methods like:

  • validateScheduleJobRequest(...) - to validate ScheduleJobRequest
  • validateGetJobRequest(...) - to validate GetJobRequest
  • validateDeleteJobRequest(...) - to validate DeleteJobRequest
    This way we will have clean separation between data validation and GRPC method invocation.

• You might want to look into other APIs to make sure that you use the right interceptors to ensure tracing data is properly propagated. Although we could address this later, as well.

CC: @salaboy @cicoyle

Addressed the comments

[siri-varma]

/assign

[artur-ciocanu]

@siri-varma I have left some comments. Could you please take a look and let me know your thoughts.

Thank you.

[artur-ciocanu]

@siri-varma could you please take a look at the tests, it seems that the scheduler container is not working as expected. Also I am wondering if we could avoid using latest tag in containers images, so we have more control when Dapr container group is upgraded.

[artur-ciocanu]

@siri-varma I see the following errors for IT tests:

DaprComponentTest.containerConfigurationTest:42 » ContainerLaunch Container startup failed for image daprio/scheduler:latest

And

Container startup failed for image daprio/daprd:1.14.4

Could you please make sure you use the latest Dapr container 1.15.3 and ensure that the same image tag is used for all the other Dapr containers that are started behind the scenes, like scheduler or placement container.

[siri-varma]

@artur-ciocanu I am traveling and will be back in couple of days. Will update the pr by Friday

[siri-varma]

@artur-ciocanu Addressed all the comments, fixed integration tests

[siri-varma]

The 1.14.4 is coming from actors. I will update it in a separate pr. Will create an issue

[salaboy]

This PR looks good to me.. @siri-varma did you wanted to make more changes? Is there something still not address from @artur-ciocanu comments?

[siri-varma]

@salaboy Thanks for the review and nope, I don't have anything else to address

[siri-varma]

#1296

Created an issue and a PR to address the dapr runtime version consistency

[artur-ciocanu]

@siri-varma could you please make sure that you do not accidentally replace fully qualified imports with *. Please make sure you configure your IDE do not collapse multiple imports into a single *.

Also I think it would be cleaner to wait for your PR #1299 and then fix the conflicts in this PR and then merge.

[siri-varma]

@cicoyle I have added the Jobs sdk example with markdown in this commit 17429d6

Please take a look. Thank you

[siri-varma]

@artur-ciocanu Please look at this commit to 68568c5. I have reduced the spaces from 4 to 2

[artur-ciocanu]

Great work!

[artur-ciocanu]

@cicoyle this PR looks good to be merged, please take a look and let's get it in. Thank you.

[siri-varma]

@cicoyle let me know if I need to do anything else for merging the pr

[codecov]

Codecov Report

Attention: Patch coverage is 90.50279% with 17 lines in your changes missing coverage. Please review.

Project coverage is 75.88%. Comparing base (d759c53) to head (d18bad6).
Report is 128 commits behind head on master.

Files with missing lines	Patch %	Lines
...ain/java/io/dapr/testcontainers/DaprContainer.java	62.50%	5 Missing and 1 partial ⚠️
...io/dapr/testcontainers/DaprSchedulerContainer.java	73.68%	5 Missing ⚠️
...k/src/main/java/io/dapr/client/DaprClientImpl.java	97.18%	1 Missing and 1 partial ⚠️
...ain/java/io/dapr/client/domain/GetJobResponse.java	91.66%	2 Missing ⚠️
...java/io/dapr/client/domain/ScheduleJobRequest.java	91.66%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #1255      +/-   ##
============================================
- Coverage     76.91%   75.88%   -1.03%     
- Complexity     1592     1684      +92     
============================================
  Files           145      200      +55     
  Lines          4843     5267     +424     
  Branches        562      574      +12     
============================================
+ Hits           3725     3997     +272     
- Misses          821      949     +128     
- Partials        297      321      +24     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cicoyle]

Thank you for getting the Jobs API over the line @siri-varma 🙌🏻