jdk-sandbox: comparison src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/OperationGroup.java

equal deleted inserted replaced

-:4f7713e6a308
+:c9cbac2979fb
 /**
 * <p>
 * A set of {@link Operation}s that share certain properties, are managed as a
 * unit, and are executed as a unit. The {@link Operation}s created by an
-* {@link OperationGroup} and submitted are the member {@link Operation}s of
+* {@code OperationGroup} and submitted are the member {@link Operation}s of
-* that {@link OperationGroup}. An {@link OperationGroup} is not a transaction
+* that {@code OperationGroup}. An {@code OperationGroup} is not a transaction
 * and is not related to a transaction in any way.</p>
 *
 * <p>
-* An {@link OperationGroup} conceptually has a collection of member
+* An {@link OperationGroup} provides conditional execution, control of error
-* {@link Operation}s. When an {@link OperationGroup} is submitted it is placed
+* response, and control of execution order.</p>
-* in the collection of the {@link OperationGroup} of which it is a member. The
+*
-* member {@link OperationGroup} is executed according to the attributes of the
+* <p>
-* {@link OperationGroup} of which it is a member. The member {@link Operation}s
+* Execution of one or more {@link Operation}s may depend on the result of a
-* of an {@link OperationGroup} are executed according to the attributes of that
+* previous {@link Operation}. Depending on the result of that previous
-* {@link OperationGroup}.</p>
+* {@link Operation} some other {@link Operation}s perhaps should not be
-*
+* executed. For example consider an account withdrawal. If the amount to
-* <p>
+* withdraw exceeds the account balance the withdrawal {@link Operation}s should
-* How an {@link OperationGroup} is executed depends on its attributes.</p>
+* not be executed and an overdraft {@link Operation} should be executed
-*
+* instead. It would be possible for the user thread to wait for the balance
-* <p>
+* check {@link Operation} but that would block. Better would be to use the
-* If an {@link OperationGroup} has a condition and the value of that condition
+* {@link java.util.concurrent.CompletionStage} of the balance check
+* {@link Operation} and submit the appropriate {@link Operation} in a
+* subsequent stage. But this is a common pattern and it is better still to
+* encapsulate that pattern, which conditional {@link OperationGroup} does.</p>
+*
+* <p>
+* Not all {@link Operation}s need to be executed in the order submitted. The
+* most common example is a mass insert. The order in which the records are
+* inserted doesn’t matter. A parallel {@link OperationGroup} gives the
+* implementation the freedom to execute the {@link Operation}s in any order. If
+* some of the {@link Operation}s have
+* {@link java.util.concurrent.CompletionStage} parameters this can be
+* especially valuable.</p>
+*
+* <p>
+* {@link OperationGroup} also allows control of error response. By default if
+* one {@link Operation} fails all subsequent {@link Operation}s are skipped.
+* That’s not always right. Consider the mass insert case. Just because one
+* insert fails doesn’t mean they should all fail. An independent
+* {@link OperationGroup} does this; the failure of one {@link Operation} has no
+* impact on the execution of the rest.</p>
+*
+* <p>
+* As an {@link OperationGroup} is an {@link Operation} it must be submitted
+* before its member {@link Operation}s are executed. Submitting an {@link OperationGroup}
+* allows its member {@link Operation}s to be executed but does not prohibit more
+* member {@link Operation}s from being submitted. Member {@link Operation}s may be
+* submitted before and after the containing {@link OperationGroup} is submitted.</p>
+*
+* <p>
+* The result of an {@link OperationGroup} depends on the results of its member
+* {@link Operation}s. Therefore an {@link OperationGroup} must know when all
+* member {@link Operation}s have been submitted. It cannot generate a
+* result until all member {@link Operation}s are completed. Since member {@link Operation}s can be
+* submitted after the {@link OperationGroup} has been submitted (see previous
+* paragraph) submitting the containing {@link OperationGroup} is not sufficient to mark that all member
+* {@link Operation}s have been submitted. Calling {@link OperationGroup#close} signals
+* that all member Operations have been submitted. After close is called, no
+* more member Operations may be submitted and the OperationGroup will complete
+* when all member Operations are complete.</p>
+*
+* <p>
+* An {@code OperationGroup} conceptually has a collection of member
+* {@link Operation}s. When an {@code OperationGroup} is submitted it is placed
+* in the collection of the {@code OperationGroup} of which it is a member. The
+* member {@code OperationGroup} is executed according to the attributes of the
+* {@code OperationGroup} of which it is a member. The member {@link Operation}s
+* of an {@code OperationGroup} are executed according to the attributes of that
+* {@code OperationGroup}.</p>
+*
+* <p>
+* How an {@code OperationGroup} is executed depends on its attributes.</p>
+*
+* <p>
+* If an {@code OperationGroup} has a condition and the value of that condition
 * is {@link Boolean#TRUE} then execute the member {@link Operation}s as below.
-* If it is {@link Boolean#FALSE} then the {@link OperationGroup} is completed
+* If it is {@link Boolean#FALSE} then the {@code OperationGroup} is completed
 * with the value null. If the condition completed exceptionally then the
-* {@link OperationGroup} is completed exceptionally with a
+* {@code OperationGroup} is completed exceptionally with a
 * {@link SqlSkippedException} that has that exception as its cause.</p>
 *
 * <p>
-* If the {@link OperationGroup} is sequential the member {@link Operation}s are
+* If the {@code OperationGroup} is sequential the member {@link Operation}s are
 * executed in the order they were submitted. If it is parallel, they may be
 * executed in any order including simultaneously.</p>
 *
 * <p>
-* If an {@link OperationGroup} is dependent and a member {@link Operation}
+* If an {@code OperationGroup} is dependent and a member {@link Operation}
 * completes exceptionally the remaining member {@link Operation}s in the
 * collection are completed exceptionally with a {@link SqlSkippedException}
-* that has the initial {@link Exception} as its cause and the {@link OperationGroup}
+* that has the initial {@link Exception} as its cause and the
-* is completed exceptionally with the initial {@link Exception}. A member
+* {@code OperationGroup} is completed exceptionally with the initial
-* {@link Operation} in-flight may either complete normally or be completed
+* {@link Exception}. A member {@link Operation} in-flight may either complete
-* exceptionally but must complete one way or the other. [NOTE: Too strong?]</p>
+* normally or be completed exceptionally but must complete one way or the
-*
+* other. [NOTE: Too strong?]</p>
-* <p>
+*
-* After a call to {@link OperationGroup#submitHoldingForMoreMembers} the
+* <p>
-* {@link OperationGroup} is submitted and held. After a call to
+* The result of this {@code OperationGroup} is the result of collecting the
-* {@link OperationGroup#releaseProhibitingMoreMembers} the {@link OperationGroup}
+* results of its member {@link Operation}s. If the {@code OperationGroup} is
-* is no longer held and is still submitted. Holding permits member {@link Operation}s
-* to be executed at the same time additional member {@link Operation}s are
-* submitted. Collecting the member {@link Operation}s' results does not begin
-* until the {@link OperationGroup} is no longer held.</p>
-*
-* <p>
-* If an {@link OperationGroup} is held additional member {@link Operation}s may
-* be submitted. If an {@link OperationGroup} is not held, no additional member
-* {@link Operation}s  may be submitted after the {@link OperationGroup} is
-* submitted. If an {@link OperationGroup} is held it will be completed only after
-* it is released or if conditional and the condition is not {@link Boolean#TRUE}.
-* If a {@link OperationGroup} is dependent, held, one of its member
-* {@link Operation}s completed exceptionally, and its queue is empty then the
-* {@link OperationGroup} is released.</p>
-*
-* <p>
-* The result of this {@link OperationGroup} is the result of collecting the
-* results of its member {@link Operation}s. If the {@link OperationGroup} is
 * dependent and one of its member {@link Operation}s completes exceptionally,
-* the {@link OperationGroup} is completed exceptionally.</p>
+* the {@code OperationGroup} is completed exceptionally.</p>
 *
 * <p>
 * An implementation of this class must be thread safe as result and error
-* handlers running asynchronously may be accessing an {@link OperationGroup} in
+* handlers running asynchronously may be accessing an {@code OperationGroup} in
 * parallel with each other and with a user thread.</p>
+*
 * <p>
-* ISSUE: Currently no way to create a nested {@link OperationGroup}. That is an
+* ISSUE: Currently no way to create a nested {@code OperationGroup}. That is an
-* intentional limitation but may be a simplification we can live with. Or not.</p>
+* intentional limitation but may be a simplification we can live with. Or
+* not.</p>
 *
 * @param <S> The type of the result of the member {@link Operation}s
 * @param <T> The type of the collected results the member {@link Operation}s
 */
-public interface OperationGroup<S, T> extends Operation<T> {
+public interface OperationGroup<S, T> extends Operation<T>, AutoCloseable {
 /**
-* Mark this {@link OperationGroup} as parallel. If this method is not called
+* Mark this {@code OperationGroup} as parallel. If this method is not called
-* the {@link OperationGroup} is sequential. If an {@link OperationGroup} is
+* the {@code OperationGroup} is sequential. If an {@code OperationGroup} is
 * parallel, member {@link Operation}s may be executed in any order including
-* in parallel. If an {@link OperationGroup} is sequential, the default,
+* in parallel. If an {@code OperationGroup} is sequential, the default,
 * member {@link Operation}s are executed strictly in the order they are
 * submitted.
 *
-* Note: There is no covariant override of this method in {@link Session}
+* Note: There is no covariant override of this method in {@link Session} as
-* as there is only a small likelihood of needing it.
+* there is only a small likelihood of needing it.
 *
-* @return this {@link OperationGroup}
+* @return this {@code OperationGroup}
-* @throws IllegalStateException if this {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} has been
 * submitted, any member {@link Operation}s have been created, or this method
 * has been called previously
 */
 public OperationGroup<S, T> parallel();
 /**
-* Mark this {@link OperationGroup} as independent. If this method is not
+* Mark this {@code OperationGroup} as independent. If this method is not
-* called the {@link OperationGroup} is dependent, the default. If an
+* called the {@code OperationGroup} is dependent, the default. If an
-* {@link OperationGroup} is independent then failure of one member
+* {@code OperationGroup} is independent then failure of one member
 * {@link Operation} does not affect the execution of other member
-* {@link Operation}s. If an {@link OperationGroup} is dependent then failure
+* {@link Operation}s. If an {@code OperationGroup} is dependent then failure
 * of one member {@link Operation} will cause all member {@link Operation}s
 * remaining in the queue to be completed exceptionally with a
 * {@link SqlSkippedException} with the cause set to the original exception.
 *
-* The result of this {@link OperationGroup}'s execution is the result of collecting the
+* The result of this {@code OperationGroup}'s execution is the result of
-* results of the member {@link Operation}s that complete normally.
+* collecting the results of the member {@link Operation}s that complete
-*
+* normally.
-* Note: There is no covariant override of this method in {@link Session}
+*
-* as there is only a small likelihood of needing it.
+* Note: There is no covariant override of this method in {@link Session} as
-*
+* there is only a small likelihood of needing it.
-* @return this {@link OperationGroup}
+*
-* @throws IllegalStateException if this {@link OperationGroup} has been
+* @return this {@code OperationGroup}
+* @throws IllegalStateException if this {@code OperationGroup} has been
 * submitted, any member {@link Operation}s have been created, or this method
 * has been called previously
 */
 public OperationGroup<S, T> independent();
 /**
 * Define a condition that determines whether the member {@link Operation}s of
-* this {@link OperationGroup} are executed or not. If and when this
+* this {@code OperationGroup} are executed or not. If and when this
-* {@link OperationGroup} is executed then if the condition argument is
+* {@code OperationGroup} is executed then if the condition argument is
 * completed with {@link Boolean#TRUE} the member {@link Operation}s are
 * executed. If {@link Boolean#FALSE} or if it is completed exceptionally the
 * member {@link Operation}s are not executed but are removed from the queue.
 * After all member {@link Operation}s have been removed from the queue this
-* {@link OperationGroup} is completed with {@code null}.
+* {@code OperationGroup} is completed with {@code null}.
 *
-* Note: There is no covariant override of this method in Session as there
+* Note: There is no covariant override of this method in Session as there is
-* is only a small likelihood of needing it.
+* only a small likelihood of needing it.
 *
 * ISSUE: Should the member Operations be skipped or otherwise completed
 * exceptionally?
 *
 * @param condition a {@link CompletionStage} the value of which determines
-* whether this {@link OperationGroup} is executed or not
+* whether this {@code OperationGroup} is executed or not
 * @return this OperationGroup
-* @throws IllegalStateException if this {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} has been
 * submitted, any member {@link Operation}s have been created, or this method
 * has been called previously
 */
 public OperationGroup<S, T> conditional(CompletionStage<Boolean> condition);
 /**
-* Mark this {@link OperationGroup} as submitted and held. It can be executed but cannot be
-* completed. A {@link OperationGroup} that is held remains in the queue even
-* if all of its current member {@link Operation}s have completed. So long as
-* the {@link OperationGroup} is held new member {@link Operation}s can be
-* submitted. A {@link OperationGroup} that is held must be released before it
-* can be completed and removed from the queue.
-*
-* If the {@link OperationGroup} is dependent and one of its member {@link Operation}s
-* completes exceptionally and its queue is empty the {@link OperationGroup}
-* is completed.
-*
-* Note: There is no covariant override of this method in Session as there
-* is only a small likelihood of needing it.
-*
-* ISSUE: Need a better name.
-*
-* @return a Submission for this OperationGroup
-* @throws IllegalStateException if this {@link OperationGroup} has been
-* submitted
-*/
-public Submission<T> submitHoldingForMoreMembers();
-/**
-* Allow this {@link OperationGroup} to be completed and removed from the
-* queue once all of its member {@link Operation}s have been completed. After
-* this method is called no additional member {@link Operation}s can be
-* submitted. Once all member {@link Operation}s have been removed from the
-* queue this {@link OperationGroup} will be completed and removed from the
-* queue.
-*
-* Note: There is no covariant override of this method in Session as there
-* is only a small likelihood of needing it.
-*
-* ISSUE: Need a better name.
-*
-* @return the same Submission that was returned by {@link OperationGroup#submitHoldingForMoreMembers}
-* @throws IllegalStateException if this {@link OperationGroup} has been
-* completed or is not held.
-*/
-public Submission<T> releaseProhibitingMoreMembers();
-/**
 * Provides a {@link Collector} to reduce the results of the member
-* {@link Operation}s. The result of this {@link OperationGroup} is the result
+* {@link Operation}s. The result of this {@code OperationGroup} is the result
 * of calling finisher on the final accumulated result.If the
 * {@link Collector} is {@link Collector.Characteristics#UNORDERED} the member
 * {@link Operation} results may be accumulated out of order.If the
 * {@link Collector} is {@link Collector.Characteristics#CONCURRENT} then the
 * member {@link Operation} results may be split into subsets that are reduced
-* separately and then combined. If this {@link OperationGroup} is sequential,
+* separately and then combined. If this {@code OperationGroup} is sequential,
 * the characteristics of the {@link Collector} only affect how the results of
 * the member {@link Operation}s are collected; the member {@link Operation}s
-* are executed sequentially regardless. If this {@link OperationGroup} is
+* are executed sequentially regardless. If this {@code OperationGroup} is
 * parallel the characteristics of the {@link Collector} may influence the
 * execution order of the member {@link Operation}s.
 *
 * The default value is
 * {@code Collector.of(()->null, (a,t)->{}, (l,r)->null, a->null)}.
 *
 * @param c the Collector. Not null.
 * @return This OperationGroup
 * @throws IllegalStateException if called more than once or if this
-* {@link OperationGroup} has been submitted
+* {@code OperationGroup} has been submitted
 */
 public OperationGroup<S, T> collect(Collector<S, ?, T> c);
 /**
 * Return a new member {@link PrimitiveOperation} that is never skipped.
 * Skipping of member {@link Operation}s stops with a catchOperation and the
 * subsequent {@link Operation} is executed normally. The value of a
 * catchOperation is always null. Since a catchOperation is never completed
 * exceptionally, it has no error handler or timeout.
 *
 * @return an {@link PrimitiveOperation} that is never skipped;
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed
-* submitted and is not held or if the {@link OperationGroup} is parallel or
+* or if this {@code OperationGroup} is parallel or independent.
-* independent.
 */
 public PrimitiveOperation<S> catchOperation();
 /**
 * Creates and submits a catch Operation. Convenience method.
 *
 * @return this OperationGroup
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed
-* submitted and is not held or if the {@link OperationGroup} is parallel or
+* or if this {@code OperationGroup} is parallel or independent.
-* independent.
 */
 public default OperationGroup<S, T> catchErrors() {
 catchOperation().submit();
 return this;
 }
 * </code></pre>
 *
 * @param <R> the result type of the returned {@link ArrayRowCountOperation}
 * @param sql SQL to be executed. Must return an update count.
 * @return a new {@link ArrayRowCountOperation} that is a member of this
-* {@link OperationGroup}
+* {@code OperationGroup}
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed.
-* submitted and is not held
 */
 public <R extends S> ArrayRowCountOperation<R> arrayRowCountOperation(String sql);
 /**
 * Return a new {@link ParameterizedRowCountOperation}.
 *
 * @param <R> the result type of the returned {@link RowCountOperation}
 * @param sql SQL to be executed. Must return an update count.
-* @return an new {@link ParameterizedRowCountOperation} that is a member of this
+* @return an new {@link ParameterizedRowCountOperation} that is a member of
-* {@link OperationGroup}
+* this {@code OperationGroup}
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed.
-* submitted and is not held
 */
 public <R extends S> ParameterizedRowCountOperation<R> rowCountOperation(String sql);
 /**
 * 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.
 *
 * The result of the returned Operation must be Void but specifying that here
 * causes problems.
 *
 * @param sql SQL for the {@link Operation}.
 * @return a new {@link Operation} that is a member of this
-* {@link OperationGroup}
+* {@code OperationGroup}
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed.
-* submitted and is not held
 */
 public Operation<S> operation(String sql);
 /**
-* Return a new {@link OutOperation} that is a member {@link Operation} of this
+* Return a new {@link OutOperation} that is a member {@link Operation} of
-* {@link OperationGroup}. The SQL must return a set of zero or more out
+* this {@code OperationGroup}. The SQL must return a set of zero or more out
 * parameters or function results.
 *
 * @param <R> the result type of the returned {@link OutOperation}
 * @param sql SQL for the {@link Operation}. Must return zero or more out
 * parameters or function results.
 * @return a new {@link OutOperation} that is a member of this
-* {@link OperationGroup}
+* {@code OperationGroup}
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed.
-* submitted and is not held
 */
 public <R extends S> OutOperation<R> outOperation(String sql);
 /**
 * Return a new {@link ParameterizedRowOperation} that is a member
-* {@link Operation} of this {@link OperationGroup}.
+* {@link Operation} of this {@code OperationGroup}.
 *
 * @param <R> the type of the result of the returned
 * {@link ParameterizedRowOperation}
 * @param sql SQL for the {@link Operation}. Must return a row sequence.
 * @return a new {@link ParameterizedRowOperation} that is a member of this
-* {@link OperationGroup}
+* {@code OperationGroup}
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed.
-* submitted and is not held
 */
 public <R extends S> ParameterizedRowOperation<R> rowOperation(String sql);
 /**
 * Return a new {@link ParameterizedRowPublisherOperation} that is a member
-* {@link Operation} of this {@link OperationGroup}.
+* {@link Operation} of this {@code OperationGroup}.
 *
 * @param <R> the type of the result of the returned
 * {@link ParameterizedRowPublisherOperation}
 * @param sql SQL for the {@link Operation}. Must return a row sequence.
 * @return a new {@link ParameterizedRowPublisherOperation} that is a member
-* of this {@link OperationGroup}
+* of this {@code OperationGroup}
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed.
-* submitted and is not held
 */
 public <R extends S> ParameterizedRowPublisherOperation<R> rowPublisherOperation(String sql);
 /**
-* Return a new {@link MultiOperation} that is a member
+* Return a new {@link MultiOperation} that is a member {@link Operation} of
-* {@link Operation} of this {@link OperationGroup}.
+* this {@code OperationGroup}.
 *
-* @param <R> the type of the result of the returned
+* @param <R> the type of the result of the returned {@link MultiOperation}
-* {@link MultiOperation}
 * @param sql SQL for the {@link Operation}
 * @return a new {@link MultiOperation} that is a member of this
-* {@link OperationGroup}
+* {@code OperationGroup}
-* @throws IllegalStateException if the {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed.
-* submitted and is not held
 */
 public <R extends S> MultiOperation<R> multiOperation(String sql);
 /**
 * Return a new {@link Operation} that ends the database transaction. This
-* {@link Operation} is a member of the {@link OperationGroup}. The
+* {@link Operation} is a member of the {@code OperationGroup}. The
 * transaction is ended with a commit unless the {@link TransactionCompletion}
 * has been {@link TransactionCompletion#setRollbackOnly} in which case the
 * transaction is ended with a rollback.
 *
 * <p>
 * An endTransaction Operation may be skipped. To insure that it will not be
 * skipped it should immediately follow a catch Operation. All end transaction
 * convenience methods do so.</p>
 *
-* The type argument {@link S} of the containing {@link OperationGroup} must
+* The type argument {@link S} of the containing {@code OperationGroup} must
 * be a supertype of {@link TransactionOutcome}.
 *
-* @param trans the TransactionCompletion that determines whether the Operation does a
+* @param trans the TransactionCompletion that determines whether the
-database commit or a database rollback.
+* Operation does a database commit or a database rollback.
 * @return an {@link Operation} that will end the database transaction.
-* @throws IllegalStateException if this {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed
-* submitted and is not held or is parallel.
+* or is parallel.
 */
 public Operation<TransactionOutcome> endTransactionOperation(TransactionCompletion trans);
 /**
 * Convenience method that creates and submits a endTransaction
 * {@link Operation} that commits by default but can be set to rollback by
-* calling {@link TransactionCompletion#setRollbackOnly}. The endTransaction Operation
+* calling {@link TransactionCompletion#setRollbackOnly}. The endTransaction
-* is never skipped.
+* Operation is never skipped.
 *
-* @param trans the TransactionCompletion that determines whether the {@link Operation} is a
+* @param trans the TransactionCompletion that determines whether the
-* database commit or a database rollback.
+* {@link Operation} is a database commit or a database rollback.
 * @return a {@link CompletionStage} that is completed with the outcome of the
 * transaction
-* @throws IllegalStateException if this {@link OperationGroup} has been
+* @throws IllegalStateException if this {@code OperationGroup} is closed
-* submitted and is not held or is parallel.
+* or is parallel.
 */
 public default CompletionStage<TransactionOutcome> commitMaybeRollback(TransactionCompletion trans) {
 catchErrors();
 return this.endTransactionOperation(trans).submit().getCompletionStage();
 }
 /**
 * Return a new {@link LocalOperation} that is a member {@link Operation} of
-* this {@link OperationGroup}.
+* this {@code OperationGroup}.
 *
 * @param <R> value type of the returned local {@link Operation}
 * @return a LocalOperation
-* @throws IllegalStateException if this {@link OperationGroup} has been submitted and
+* @throws IllegalStateException if this {@code OperationGroup} is closed.
-* is not held
 */
 public <R extends S> LocalOperation<R> localOperation();
 /**
 * Supply a {@link Logger} for the implementation of this
-* {@link OperationGroup} to use to log significant events. Exactly what
+* {@code OperationGroup} to use to log significant events. Exactly what
 * events are logged, at what Level the events are logged and with what
 * parameters is implementation dependent. All member {@link Operation}s of
-* this {@link OperationGroup} will use the same {@link Logger} except a
+* this {@code OperationGroup} will use the same {@link Logger} except a
-* member {@link OperationGroup} that is supplied with a different
+* member {@code OperationGroup} that is supplied with a different
 * {@link Logger} uses that {@link Logger}.
 *
 * Supplying a {@link Logger} configured with a
 * {@link java.util.logging.MemoryHandler} with the
 * {@link java.util.logging.MemoryHandler#pushLevel} set to
 * {@link java.util.logging.Level#WARNING} will result in no log output in
 * normal operation. In the event of an error the actions leading up to the
 * error will be logged.
 *
 * Implementation Note: Implementations are encouraged to log the creation of
-* this {@link OperationGroup} set to {@link java.util.logging.Level#INFO},
+* this {@code OperationGroup} set to {@link java.util.logging.Level#INFO},
 * the creation of member {@link Operation}s at the
 * {@link java.util.logging.Level#CONFIG} level, and execution of member
 * {@link Operation}s at the {@link java.util.logging.Level#FINE} level.
 * Detailed information about the execution of member {@link Operation}s may
 * be logged at the {@link java.util.logging.Level#FINER} and
 * user code should be logged at the {@link java.util.logging.Level#WARNING}
 * Level. Errors in the implementation code should be logged at the
 * {@link java.util.logging.Level#SEVERE} Level.
 *
 * @param logger used by the implementation to log significant events
-* @return this {@link OperationGroup}
+* @return this {@code OperationGroup}
 */
 public OperationGroup<S, T> logger(Logger logger);
 /**
 * Returns a {@code String} enclosed in single quotes. Any occurrence of a
 *
 * </tbody>
 * </table>
 * </blockquote>
 *
-* @implNote JDBC driver implementations may need to provide their own
+* @implNote ADBA driver implementations may need to provide their own
 * implementation of this method in order to meet the requirements of the
 * underlying datasource.
 * @param val a character string. Not null
 * @return A string enclosed by single quotes with every single quote
 * converted to two single quotes. Not null
 * @param identifier a SQL identifier. Not null
 * @param alwaysQuote indicates if a simple SQL identifier should be returned
 * as a quoted identifier
 * @return A simple SQL identifier or a delimited identifier. Not null
 * @throws NullPointerException if identifier is {@code null}
 * @throws IllegalArgumentException if {@code identifier} can not be converted
 * to a valid identifier
 */
 default String enquoteIdentifier(String identifier, boolean alwaysQuote) {
 int len = identifier.length();
 if (len < 1 || len > 128) {
 */
 default String enquoteNCharLiteral(String val) {
 return "N'" + val.replace("'", "''") + "'";
 }
-// Covariant overrides
+/**
+* Allow this {@code OperationGroup} to be completed and removed from the
+* queue once all of its member {@link Operation}s have been completed. After
+* this method is called no additional member {@link Operation}s can be
+* submitted. Once all member {@link Operation}s have been removed from the
+* queue this {@code OperationGroup} will be completed and removed from the
+* queue.
+*
+* {@inheritDoc}
+*/
+@Override
+public void close();
+// Covariant overrides
+/**
+* {@inheritDoc}
+*
+* @return this {@code OperationGroup}
+*/
 @Override
 public OperationGroup<S, T> timeout(Duration minTime);
+/**
+* {@inheritDoc}
+*
+* @return this {@code OperationGroup}
+*/
 @Override
 public OperationGroup<S, T> onError(Consumer<Throwable> handler);
 }

branch	JDK-8188051-branch
changeset 56997	c9cbac2979fb
parent 56832	4f7713e6a308