Example of a Flow-based JDBC API

[Douglas Surber]

The target app is a large scale app running many instances in parallel against a large database system, probably geographically distributed. Maximum throughput with low and stable latency.

The goals for the implementation are

 - vendor neutral
 - avoid features that reduce scalability
 - every feature must balance user benefit vs performance cost
 - every feature must balance user benefit vs code to implement

The goals for the user API are

 - asynchronous. No user thread blocks
 - plays well with Java SE
 - minimal. Every feature must be important to the target app. 80/20 rule
 - consistent. No special cases
 - transparent. Principle of least surprise 
 - ready by Java 10/19.x
 - independent of java.sql and javax.sql

We haven’t discussed TCK or testing.

We made the following design choices. They aren’t requirements. But having made those choices consistency requires that we be rigorous in abiding by them.

 - Rigorous use of types
 - Builder pattern
 - Fluent API
 - Immutable after initialization
 - One way to do something is enough
 - Avoid SQL processing
 - Avoid callback hell 

As we started work we looked at existing async database access APIs both in Java and other languages. We looked at reactive streams but did not follow that path because there was no support in Java SE. We looked at java.util.stream but that blocks and cannot/will not be made non-blocking. The Core Library Team encouraged us to build around CompletableFuture. CompletableFuture seems too low level so this API provides a higher level abstraction, well defined execution of Operations, to support the most common use cases while still making use of CompletableFuture. (As noted elsewhere replacing CompletableFuture with CompletionStage would be reasonable.)

Douglas


> On Oct 14, 2017, at 6:07 AM, Viktor Klang <v at lightbend.com> wrote:
> 
> What would help me, is to learn what the requirements for success is for the following aspects:
> 
> * Implementor SPI—ergonomics, performance, scalability
> * User API—ergonomics, performance, scalability
> * Verification of implementations—TCK for implementations
> * Verification of usage—how to write tests for JDBC 2
>