feat: add async api

[olavloite]

Adds an async API to the Spanner client library. Most notable changes:

All calls to the session pool are now non-blocking

This also applies to the current API, which means that the following statements will always be non-blocking, regardless whether a session was already available in the session pool or not:

Database client = spanner.getDatabaseClient(...);
ResultSet rs = client.singleUse().executeQuery(Statement.Of("SELECT 1"));

Instead, the first call to ResultSet#next() will be blocking:

1. It will potentially block until a session could be returned from the pool.
2. It will block until the executeStreamingSql call has returned the first results.

Adds Async methods to ReadContext

The ReadContext interface is extended with the following methods:

• readAsync(...)
• readUsingIndexAsync(...)
• executeQueryAsync(...)
• readRowAsync(...)
• readRowUsingIndexAsync(...)

The first three of the above methods return an AsyncResultSet. AsyncResultSet is an extension of the existing ResultSet interface that allows the user to register a callback that will be called asynchronously for each row in the result set.

The latter two methods return instances of ApiFuture<Struct>.

Point for discussion:
It would also be possible to add the setCallback(...) method to the existing ResultSet interface instead of creating an additional AsyncResultSet interface. That would mean that we would not need to add the -Async methods above. Instead, all ResultSets could be consumed asynchronously by calling the setCallback(...) method.

Adds AsyncRunner

The method DatabaseClient#runAsync() is added which returns an AsyncRunner. This runner can be used to execute a read/write transaction asynchronously.

[olavloite]

@elefeint I've processed all your review comments, and now also added support for an AsyncTransactionManager. This again will be used to create async support for the connection API. I suggest we do that in a separate PR, as this PR is already huge.

[skuruppu]

Thanks very much for the review @elefeint and @dzou. @olavloite please merge this in when you're ready.

[pravsingh]

how do we set asyncExecutorProvider?

[olavloite]

It's currently not configurable, and it will automatically use the default provided here:

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/SpannerOptions.java

Line 514 in b2a56c6

static CloseableExecutorProvider createDefaultAsyncExecutorProvider() {

[pravsingh]

thanks for the quick reply Knut Olav .
Is there a plan to make it configurable?

[olavloite]

There's no concrete plan for it, but this feels like an omission to me. Would you mind submitting a feature request here: https://github.com/googleapis/java-spanner/issues/new?assignees=&labels=&template=feature_request.md

[pravsingh]

thanks so much.
just created this issue