diff -r 69b384805d61 -r fb523d4d9185 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSource.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSource.java Wed Jun 20 15:12:52 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSource.java Wed Jun 20 15:38:40 2018 -0400 @@ -30,7 +30,7 @@ import java.util.function.Consumer; /** - * Uses the builder pattern to get a {@link Connection}. A {@link getConnection} + * Uses the builder pattern to get a {@link Connection}. A {@link DataSource#getConnection} * method is provided as a convenience. * * Implementations must be thread safe. @@ -42,6 +42,8 @@ * Instances of this type are used to build {@link DataSource}s. This type is * immutable once configured. No property can be set more than once. No * property can be set after {@link build} is called. + * + * ISSUE: Probably need property(DataSourceProperty prop, Object value). */ public interface Builder { @@ -135,6 +137,34 @@ } /** + * Provide a method that the built {@link DataSource} will call to control the + * rate of {@link DataSource#connectOperation} submissions. The built + * {@link DataSource} will call {@code request} with a positive argument + * when the {@link DataSource} is able to accept more + * {@link DataSource#connectOperation} submissions. The difference between + * the sum of all arguments passed to {@code request} and the number of + * calls to {@link DataSource#builder} is the + * demand. The demand must always be non-negative. If a call is made to + * {@link DataSource#builder} that would make the demand negative that call + * throws {@link IllegalStateException}. If {@code requestHook} is not called, + * the demand is defined to be infinite. + * + *
+ * An implementation may choose to delay detection of insufficient demand. + * Instead of checking when {@link DataSource#builder} is called an + * implementation may choose to check at some later point in Connection + * creation such as {@link Connection.Builder.build} or + * {@code Connection#connectOperation().submit()} or even later. In any case + * an implementation must throw IllegalStateException before allocating + * or waiting to allocate scarce resources if the demand is negative.
+ * + * @param request accepts calls to increase the demand. Not null. + * @return this {@link Builder} + * @throws IllegalStateException if this method has been called previously + */ + public Builder requestHook(Consumer