minor feedback on OperationGroup.operation()

[Douglas Surber]

I recall I had an argument with the type inferencer when I declared that as Operation<Void>. I don’t recall the details. I’ll look at it again.

The JavaDoc for connectOperation is correct as written. It may not be sufficiently clear as you are the second person to ask this question. The difference is the the method throws if the connection is in any state other than NEW. Execution of the connect Operation fails if the connection is in any state other than NEW or NEW_INACTIVE. Execution of the connect Operation occurs some time after the method call.

This is one of the complications of this API. There are two execution timelines to consider. One is the execution of the methods to construct and submit Operations. This is non-blocking and is executed by a user thread. The other is the execution of the operations and result processing. These happen in the database and in other threads, not the user thread.  I have worked hard to distinguish these where appropriate and this is one of those cases.

Douglas

> On May 23, 2018, at 10:54 AM, Alexander Kjäll <alexander.kjall at gmail.com> wrote:
> 
> Hi
> 
> The javadoc on this function states:
> 
> * Return a new {@link Operation} for a SQL that doesn't return any result,
> * for example DDL. The result of this Operation is always null.
> 
> But the signature is
> 
> public Operation<S> operation(String sql);
> 
> Is there any reason that it's Operation<S> instead of Operation<Void>?
> 
> And another small thing, the javadoc bread text for connectOperation() says:
> 
> The lifecycle must be {@link Lifecycle#NEW} or
> {@link Lifecycle#NEW_INACTIVE} when the {@link Operation} is executed.
> Otherwise the {@link Operation} will complete exceptionally with
> {@link SqlException}.
> 
> but the @throws clause says:
> 
> @throws IllegalStateException if this {@link Connection} is in a lifecycle
> state other than {@link Lifecycle#NEW}.
> 
> Is it only NEW or both NEW and NEW_INACTIVE?
> 
> best regards
> Alexander Kjäll