[8.x] Explain that @Transactional doesn't cover asynchronous database work

[mkurz]

• Backport of Explain that @Transactional doesn't cover asynchronous database work #916 to 8.x.

@Transactional runs the action in DB.executeCall, so its transaction gets committed as soon as the action returns its result, not when that result completes. Ebean binds the transaction to the current thread, so:

• database operations that run on another thread don't run in the transaction, even if they start before the action returns
• the same goes for the action method, if an action composed between @Transactional and the method calls it asynchronously
• if the action throws an exception, the transaction gets rolled back; if it returns a CompletionStage that fails instead, even one that failed already, the transaction gets committed

This documents that limitation in the Javadoc of @Transactional and in the "Transactional actions" section of the Ebean docs. It also shows how to run asynchronous database operations in a transaction: with DB.executeCall inside the asynchronous task, on a CustomExecutionContext for blocking database calls, together with the configuration of its dispatcher. The new snippets compile and run as part of the docs tests.

This documentation change leaves the behaviour of @Transactional unchanged.

The snippets use javax.inject instead of jakarta.inject, as Play 3.0 does.

[mergify]

This pull request does not currently match the merge queue conditions, so it cannot be queued from here. The box comes back if it matches again.