Asynchronous repository methods and integration with Jakarta Concurrency

[njr-11]

Description

As a:

• [ ] Application user/user of the configuration itself
• [x] API user (application developer)
• [ ] SPI user (container or runtime developer)
• [ ] Specification implementer

...I need to be able to:

write repository methods that run asynchronously

...which enables me to:

avoid tying up the requesting thread waiting for queries to finish so that I can complete other work in the mean time.

Note: This issue does not cover reactive programming models like Flow. That is a separate discussion.

The preference would be to rely on the data access provider's own async support, but Jakarta Persistence/JPA (which are JDBC based) doesn't have async support. Lacking that, Jakarta Concurrency @Asynchronous could provide what we need in this area and fit quite well with just some minor language added to the Jakarta Data spec to make it possible.

If we specify that repository methods can have return types of CompletionStage and CompletableFuture (as some implementations already do), then based on the data access provider's level of support for async:

• If the data access provider has its own async support, use that and the stage/future just gets completed with the result upon completion.
• Otherwise, Jakarta Data could state that if a repository interface method is annotated with Concurrency @Asynchronous then that same @Asynchronous annotation is also applied to the bean instance. Doing that will automatically trigger the Concurrency 3.0 interceptor. Then all the implementation needs to do is return an already-completed future, relying on the Concurrency @Asynchronous interceptor to cover making it async.

@Asynchronous
CompletionStage<List<Customer>> findByNumOrdersGreaterThan(int threshold);

...
findByNumOrdersGreaterThan(2).thenAccept(this::sendLastestSalesPromotion);

Other benefits of this will be that if the data access provider, such as based on a Jakarta Persistence/JPA implementation, requires the async thread to have services of the Jakarta EE platform available, such as performing a java:comp/env lookup of a data source, or to be able to run under a transaction, or to have the same security credentials on the thread for performing the database operation, the Jakarta Concurrency spec will have taken care of all of that for us.

[keilw]

Note: This issue does not cover reactive programming models like Flow. That is a separate discussion.

@njr-11 Have you seen and read #17? It is if you want part of that "separate discussion". Unfortunately the JDK threw everything into "async" or "concurrent" even if it's branded "reactive" by some other projects and players.

Whether or not to separate the basic repository types like DataRepository or CrudRepository from others like an AsyncRepository, AsyncCrudRepository or similar (like several existing implementations do) is probably yet another discussion, but based on what the JDK offers (the API shall not have external dependencies IMO like Reactive Streams etc. that's up to implementations) we should probably support both CompletableFuture and Flow.

[njr-11]

@njr-11 Have you seen and read #17? It is if you want part of that "separate discussion". Unfortunately the JDK threw everything into "async" or "concurrent" even if it's branded "reactive" by some other projects and players.

Whether or not to separate the basic repository types like DataRepository or CrudRepository from others like an AsyncRepository, AsyncCrudRepository or similar (like several existing implementations do) is probably yet another discussion, but based on what the JDK offers (the API shall not have external dependencies IMO like Reactive Streams etc. that's up to implementations) we should probably support both CompletableFuture and Flow.

Yes, I've seen issue #17, although I missed that you had mentioned CompletableFuture there and thought it was only about fully reactive patterns. Thanks for opening that, it will be important to have that discussion. Issue 19 with the idea for potential integration with Jakarta Concurrency Asynchronous was meant to be an entirely separate and unrelated proposal of its own because it is independent of the repository type, meant for custom repository methods in general, and for the most part just relies on what is already in another Jakarta spec. The idea to allow CompletableFuture as a return type is an overlap with 17 though, so sorry that I missed that aspect.

[otaviojava]

The concurrency/reactive will be the one that we'll spend more time on, especially on the discussion.

Perhaps, start with the easy ones: CrudRepository and the paginating then go to reactive

[gavinking]

I would like to point to my comment here: https://github.com/jakartaee/data/issues/17#issuecomment-1959454837, which is also relevant to this issue.

Long story short: we essentially already have this feature.

[njr-11]

Long story short: we essentially already have this feature.

Yes, we are really close to already having it. We should keep this issue open, and I'll assign it to Future to look into next release, because it would be nice to standardize the additional return types that can be used to make this work rather than the user needing to rely on vendor-specific extensions/documentation to say that the additional return types are allowed.

[gavinking]

Yes, of course, agreed.