ADBA Early Thoughts/Notes

[Chad Retz]

Hi. I wrote https://github.com/cretz/pgnio and am toying with
implementing the latest ADBA interfaces and using the AoJ
code as kind of a reference. Some of the early code can be seen in
that repo. I haven't even gotten to a completed row
operation yet, but I have had other unrelated items come up so I'm
deprioritizing the work. But I jotted down some early
notes and figured I'd share them. They are numbered for easy response,
take 'em or leave 'em.

1. What is DataSource.close expected to do?

2. Inconsistent parameter naming wrt DataSource.Builder.*Property and
Connection.Builder.property

3. Should the implementers ignore unknown connection properties? Do
they have to still return them from
   Connection.getProperties even if they have ignored them?

4. Why is AdbaConnectionProperty.CONNECT_TIMEOUT a duration but
AdbaConnectionProperty.NETWORK_TIMEOUT an int? What is
   the unit of that int?

5. If connect timeout isn't present, is network timeout used or is
there no connect timeout?

6. Per-operation timeouts are probably not going to be easy to
implement for most implementers. Should they be optional?
   Otherwise, for things like Postgres, an entirely new connection has
to be opened to "cancel" which would be
   considered surprising behavior for the user. We can use the future
timeout features in Java, but the connection is
   still hung. Just curious what is expected of drivers here.

7. What if I call Operation.onError multiple times? Chained or
replaced? AoJ doesn't allow even changing it which
   seems limiting but fine if specified by the Javadoc.

8. Not clear which methods are thread safe. Assume none of them are
unless otherwise mentioned like most docs? One might
   expect Submission.cancel to be able to be called concurrently with
other things on the connection.

9. Why does SqlSkippedException need all of those values? Can it be
specified in the docs what can be set to null and -1
   and what not?

10. Are there any complete impls of this spec? I think this should be
a requirement before even submitting it for review
    because so many things are found during impl phase. Maybe a
closed-source Oracle one somewhere? Just trying to get
    an idea of whether every method has been implemented somewhere
even if not open source.

11. How can a caller tell whether an operation group is parallel or
not, dependent or not, has a condition, etc? Or is
    it the caller's responsibility to know whether they have set those
values previously?

12. For OperationGroup.independent, what does "f (sic) this {@link
OperationGroup} blocks errors" means? (also, fix typo
    there and typo on "iif" on the next method)

13. Any chance on using a more public and friendly code review
platform so I can just point out all the typos instead of
    having to make lists of little things? There are so many little
documentation inconsistencies. Not only typos.
    Sometimes there isn't a space after punctuation. Sometimes javadoc
refs aren't even to anything (e.g.
    "{@link close()}" instead of "{@link #close()}"). Sometimes <p>
used, sometimes not. Obviously none of them matter
    really.

14. If OperationGroup.conditional is called multiple times, are the
conditions chained or overridden? Assuming the
    latter is the intent, the docs should say so.

15. Class-level Javadoc for OperationGroup needs to explain what
"held" means and its purpose. Wasn't immediately clear,
    it just jumped into what to do when something is held.

16. Need more docs on what happens, e.g., if
OperationGroup.releaseProhibitingMoreMembers is called when not held.

17. What about protocols like Postgres that don't support multiplexing
the socket for parallel operations? Parallel
    essentially becomes a noop? Just looking for recommendations.

18. Why does the ArrayCountOperation interface re-define submit when
there are no additional docs or covariant types?

19. In SqlException, why do the fields have default values and why not
marked final?

20. Connection.connectOperation says it must be in NEW or NEW_INACTIVE
when the op starts or it's a SqlException, but
    then says it throws an IllegalStateException only if it isn't NEW.
Which is it? Or is it both (check NEW on method
    start and throw IllegalStateException, then NEW or NEW_INACTIVE on
execution and throw SqlException)? What about
    after the operation completes, should I check the lifecycle again
before altering it?

21. Should an invalid connection on Connection.validationOperation
throw a SqlException or an IllegalStateException or
    is it up to me to throw any exception type I want even beyond those two?

22. Why does the connection have to be active to register a lifecycle listener?

I would surely have a gazillion more notes as I actually got into
implementing operations but I'll stop there (again,
moving off the project a while). I will say overall the interfaces are
more complex that I was expecting. I was
expecting a more simple implementation around just async executing
things and possibly returning responses instead of
worrying about queuing, submission, etc. But either way, a target for
async DB clients to target is very welcome.

Chad