feat: Add Async support

[oscerd]

This should fix #127

[oscerd]

@edeandrea @ThomasVitale

[github-actions]

:java_duke: JaCoCo coverage report

Overall Project	42.01%	🔴

There is no coverage information present for the Files changed

[github-actions]

	Tests	Passed ✅	Skipped	Failed
Gradle Test Results (all modules & JDKs)	633 ran	633 passed	0 skipped	0 failed

Test	Result
No test annotations available

• View Gradle Test Results (all modules & JDKs)

[github-actions]

HTML test reports are available as workflow artifacts (zipped HTML).

• Download: Artifacts for this run

[oscerd]

No worries. Enjoy the weekend!

[edeandrea]

I've made a few general comments about how I envisioned the async to work. I was thinking that we would return CompletableFuture objects in the async operations. This would solve a number of issues, but the biggest is that the current implementation polls on the same thread that that it executes the task from. This could lead to deadlock in systems that are not thread-per-request.

Plus other downstream implementors may want to use virtual threads or some other threading mechanism.

Sticking to CompletableFuture allows more more customization by downstream frameworks.

@ThomasVitale thoughts?

[oscerd]

I proposed a new solution with CompletableFuture. If it works for all I'll change to Duration the missing field and add the section to whats new.

[edeandrea]

See my comments on the DoclingServeConvertApi

I think we only need a single method:

CompletableFuture<ConvertDocumentResponse> convertSource(ConvertDocumentRequest request);

The implementation of that method would handle all the necessary polling to return the completed future once its complete.

At least that was my vision. Thoughts @ThomasVitale ?

[github-actions]

HTML test reports are available as workflow artifacts (zipped HTML).

• Download: Artifacts for this run

[oscerd]

I guess I'll need to tackle this from scratch again. I was porting the logic coming from Camel, so I could have miss some parts of the API on this side. I'll rework on this next week.

[edeandrea]

I think it's actually simpler than you realize. All the polling apis are already there, plus you already have the logic for polling based on a duration. It's just providing a method which ties everything together.

[oscerd]

It should be better now. I spent an hour or so looking at the API a bit deeper.

[github-actions]

HTML test reports are available as workflow artifacts (zipped HTML).

• Download: Artifacts for this run

[edeandrea]

Looks good! I hope you don't mind but I made a few tweaks. CompletableFuture has built-in polling capabilities, so you don't need to create your own polling executor. (see f5033ac)

I also added the polling properties to the DoclingServeApi builder so it can be configured by any client implementing the api.

@oscerd @ThomasVitale Have a look and let me know what you think.

[oscerd]

Looks good! I hope you don't mind but I made a few tweaks. CompletableFuture has built-in polling capabilities, so you don't need to create your own polling executor. (see f5033ac)

I also added the polling properties to the DoclingServeApi builder so it can be configured by any client implementing the api.

@oscerd @ThomasVitale Have a look and let me know what you think.

Looks really better know. I think I should revisit a bit the Async API for Java, it's been a while.. thanks for completing the PR. +1 from my side.

[edeandrea]

I think I should revisit a bit the Async API for Java, it's been a while.

Its been a while for me too, at least with "vanilla" Java (I'm so used to Mutiny/etc). Was a good learning exercise for me too!

[github-actions]

HTML test reports are available as workflow artifacts (zipped HTML).

• Download: Artifacts for this run

[ThomasVitale]

I'll review the new changes later today

[github-actions]

HTML test reports are available as workflow artifacts (zipped HTML).

• Download: Artifacts for this run

[ThomasVitale]

Perhaps we should remove this final sentence as it's up to the framework/client to configure how the polling happens (platform thread, virtual thread, some other mechanism provided by Mutiny/Reactor). Thoughts?

[ThomasVitale]

Looks good to me! Just left a couple of comments about the docs. I like the clean API returning CompletableFuture and allowing clients/frameworks to adapt it to different asynchronous setups.