Align Java API with other languages

[mcruzdev]

Description

This pull request aims to align the Java SDK Workflow API woth other languages (Python, C#, etc.)

What this pull request does:

• Deprecate waitForInstanceStart, getInstanceState and waitForInstanceCompletion.
• Change the documentation to use the new methods (waitForWorkflowStart, getWorkflowState and waitForWorkflowCompletion)
• Change test to use the new methods.

Issue reference

Closes #1554

Please reference the issue this PR will close: #[issue number]

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

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

[siri-varma]

@mcruzdev The patch coverage is failing. Looks like some more unit tests are needed.

[siri-varma]

LGTM. Can be merged once the patch succeedes

[artur-ciocanu]

@mcruzdev thanks a lot for looking into this.

I would like to request changes and suggest some improvements:

• There is another method in the DaprWorkflowClient which uses instance purgeInstance I think it should be renamed to purgeWorkflow to stay consistent with other API changes.
• We should add a new interface named WorkflowState that should be similar to WorkflowInstanceStatus and we should ensure that instead of getInstanceId we use getWorkflowId
• Once you have the new interface you should adjust the implementation to ensure that the new methods use the new interface.
• You will also have to add an implementation similar to DefaultWorkflowInstanceStatus but for WorkflowState something like DefaultWorkflowState.
• One more thing I think we should adjust Java Docs to use workflowId instead of instanceId so we have a more clean API description.

I know it is a little bit more work, but I think it is totally worth it if we want to align with other SDKs.

Thank you 🙇

CC: @salaboy @cicoyle

[codecov]

Codecov Report

❌ Patch coverage is 78.78788% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.41%. Comparing base (d759c53) to head (f35e2d0).
⚠️ Report is 228 commits behind head on master.

Files with missing lines	Patch %	Lines
...a/io/dapr/workflows/client/DaprWorkflowClient.java	50.00%	1 Missing and 4 partials ⚠️
...o/dapr/workflows/runtime/DefaultWorkflowState.java	91.30%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #1560      +/-   ##
============================================
+ Coverage     76.91%   78.41%   +1.49%     
- Complexity     1592     1928     +336     
============================================
  Files           145      216      +71     
  Lines          4843     5860    +1017     
  Branches        562      656      +94     
============================================
+ Hits           3725     4595     +870     
- Misses          821      927     +106     
- Partials        297      338      +41     

☔ 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.

[mcruzdev]

Hi @artur-ciocanu, I applied all requested changes, let me know if we have something wrong :)

[artur-ciocanu]

@mcruzdev love it ❤️ ! I have left a tiny comment related to docs. You should make sure that those are aligned with your changes.

Also we need to make sure the build is 🟢.

[artur-ciocanu]

We should change the example to use WorkflowState

[artur-ciocanu]

We should change the example to use WorkflowState

[artur-ciocanu]

We should change the example to use WorkflowState

[artur-ciocanu]

We should change the example to use WorkflowState

[artur-ciocanu]

@mcruzdev could you please check the test you added. I see these details in the build logs:

05:40:09.322 [main] INFO  i.d.i.t.workflows.DaprWorkflowsIIT - Starting DaprWorkflowsIIT using Java 17.0.16 with PID 19986 (started by runner in /home/runner/work/java-sdk/java-sdk/sdk-tests)

And then we have a long list of these:

time="2025-10-03T05:40:09.623842519Z" level=debug msg="Error for operation DaprBuiltInActorNotFoundRetries was: failed to lookup actor: api error: code = FailedPrecondition desc = did not find address for actor" app_id=workflow-dapr-app instance=7def0498f830 scope=dapr.runtime type=log ver=1.16.0-rc.5

05:40:14.099 [Thread-443] INFO  io.dapr.durabletask - The sidecar at address 127.0.0.1:32941 is unavailable. Will continue retrying.
05:40:14.099 [Thread-441] INFO  io.dapr.durabletask - The sidecar at address 127.0.0.1:32941 is unavailable. Will continue retrying.
05:40:14.099 [Thread-442] INFO  io.dapr.durabletask - The sidecar at address 127.0.0.1:32941 is unavailable. Will continue retrying.
05:40:14.099 [Thread-444] INFO  io.dapr.durabletask - The sidecar at address 127.0.0.1:32941 is unavailable. Will continue retrying.
05:40:14.619 [Thread-462] INFO  io.dapr.durabletask - The sidecar at address 127.0.0.1:32941 is unavailable. Will continue retrying.
time="2025-10-03T05:40:15.627565918Z" level=warning msg="Error processing operation DaprBuiltInActorNotFoundRetries. Retrying in 1s…" app_id=workflow-dapr-app instance=7def0498f830 scope=dapr.runtime type=log ver=1.16.0-rc.5

And eventually the task timeouts.