28 import java.util.LinkedList; |
28 import java.util.LinkedList; |
29 import java.util.List; |
29 import java.util.List; |
30 import java.util.function.Consumer; |
30 import java.util.function.Consumer; |
31 |
31 |
32 /** |
32 /** |
33 * Uses the builder pattern to get a {@link Connection}. A {@link getConnection} |
33 * Uses the builder pattern to get a {@link Connection}. A {@link DataSource#getConnection} |
34 * method is provided as a convenience. |
34 * method is provided as a convenience. |
35 * |
35 * |
36 * Implementations must be thread safe. |
36 * Implementations must be thread safe. |
37 */ |
37 */ |
38 public interface DataSource |
38 public interface DataSource |
40 |
40 |
41 /** |
41 /** |
42 * Instances of this type are used to build {@link DataSource}s. This type is |
42 * Instances of this type are used to build {@link DataSource}s. This type is |
43 * immutable once configured. No property can be set more than once. No |
43 * immutable once configured. No property can be set more than once. No |
44 * property can be set after {@link build} is called. |
44 * property can be set after {@link build} is called. |
|
45 * |
|
46 * ISSUE: Probably need property(DataSourceProperty prop, Object value). |
45 */ |
47 */ |
46 public interface Builder { |
48 public interface Builder { |
47 |
49 |
48 /** |
50 /** |
49 * A convenience method for setting the {@link AdbaConnectionProperty#URL}. |
51 * A convenience method for setting the {@link AdbaConnectionProperty#URL}. |
133 public default Builder registerConnectionProperty(ConnectionProperty property) { |
135 public default Builder registerConnectionProperty(ConnectionProperty property) { |
134 return defaultConnectionProperty(property, property.defaultValue()); |
136 return defaultConnectionProperty(property, property.defaultValue()); |
135 } |
137 } |
136 |
138 |
137 /** |
139 /** |
|
140 * Provide a method that the built {@link DataSource} will call to control the |
|
141 * rate of {@link DataSource#connectOperation} submissions. The built |
|
142 * {@link DataSource} will call {@code request} with a positive argument |
|
143 * when the {@link DataSource} is able to accept more |
|
144 * {@link DataSource#connectOperation} submissions. The difference between |
|
145 * the sum of all arguments passed to {@code request} and the number of |
|
146 * calls to {@link DataSource#builder} is the |
|
147 * <i>demand</i>. The demand must always be non-negative. If a call is made to |
|
148 * {@link DataSource#builder} that would make the demand negative that call |
|
149 * throws {@link IllegalStateException}. If {@code requestHook} is not called, |
|
150 * the demand is defined to be infinite. |
|
151 * |
|
152 * <p> |
|
153 * An implementation may choose to delay detection of insufficient demand. |
|
154 * Instead of checking when {@link DataSource#builder} is called an |
|
155 * implementation may choose to check at some later point in Connection |
|
156 * creation such as {@link Connection.Builder.build} or |
|
157 * {@code Connection#connectOperation().submit()} or even later. In any case |
|
158 * an implementation must throw IllegalStateException before allocating |
|
159 * or waiting to allocate scarce resources if the demand is negative.</p> |
|
160 * |
|
161 * @param request accepts calls to increase the demand. Not null. |
|
162 * @return this {@link Builder} |
|
163 * @throws IllegalStateException if this method has been called previously |
|
164 */ |
|
165 public Builder requestHook(Consumer<Long> request); |
|
166 |
|
167 /** |
138 * Return a DataSource configured as specified. |
168 * Return a DataSource configured as specified. |
139 * |
169 * |
140 * @return a configured {@link DataSource}. Not {@code null}. |
170 * @return a configured {@link DataSource}. Not {@code null}. |
141 * @throws IllegalArgumentException if unable to return a {@link DataSource} due to |
171 * @throws IllegalArgumentException if unable to return a {@link DataSource} due to |
142 * problems with the configuration such is missing or conflicting properties. |
172 * problems with the configuration such is missing or conflicting properties. |
149 * {@link Connection}s with the {@code ConnectionProperty}s specified when creating this |
179 * {@link Connection}s with the {@code ConnectionProperty}s specified when creating this |
150 * DataSource. Default and unspecified {@link ConnectionProperty}s can be set with |
180 * DataSource. Default and unspecified {@link ConnectionProperty}s can be set with |
151 * the returned builder. |
181 * the returned builder. |
152 * |
182 * |
153 * @return a new {@link Connection} builder. Not {@code null}. |
183 * @return a new {@link Connection} builder. Not {@code null}. |
|
184 * @throws IllegalStateException if this {@link DataSource} is closed |
154 */ |
185 */ |
155 public Connection.Builder builder(); |
186 public Connection.Builder builder(); |
156 |
187 |
157 /** |
188 /** |
158 * Returns a {@link Connection} that has a submitted connect {@link Operation}. Convenience |
189 * Returns a {@link Connection} that has a submitted connect {@link Operation}. Convenience |
159 * method for use with try with resources. |
190 * method for use with try with resources. |
160 * |
191 * |
161 * @return a {@link Connection} |
192 * @return a {@link Connection} |
|
193 * @throws IllegalStateException if this {@link DataSource} is closed |
162 */ |
194 */ |
163 public default Connection getConnection() { |
195 public default Connection getConnection() { |
164 return builder().build().connect(); |
196 return builder().build().connect(); |
165 } |
197 } |
166 |
198 |
169 * handler. Convenience method for use with try with resources. The error |
201 * handler. Convenience method for use with try with resources. The error |
170 * handle handles errors in the connect {@link Operation}. |
202 * handle handles errors in the connect {@link Operation}. |
171 * |
203 * |
172 * @param handler for errors in the connect {@link Operation} |
204 * @param handler for errors in the connect {@link Operation} |
173 * @return a {@link Connection} |
205 * @return a {@link Connection} |
|
206 * @throws IllegalStateException if this {@link DataSource} is closed |
174 */ |
207 */ |
175 public default Connection getConnection(Consumer<Throwable> handler) { |
208 public default Connection getConnection(Consumer<Throwable> handler) { |
176 return builder().build().connect(handler); |
209 return builder().build().connect(handler); |
177 } |
210 } |
178 |
211 |
186 * @param format not {@code null} |
219 * @param format not {@code null} |
187 * @param source SQL in the format specified by {@code format}. Not {@code null}. |
220 * @param source SQL in the format specified by {@code format}. Not {@code null}. |
188 * @return SQL in the format supported by this {@link DataSource}. Not {@code null}. |
221 * @return SQL in the format supported by this {@link DataSource}. Not {@code null}. |
189 * @throws IllegalArgumentException if the {@code format} is not supported or |
222 * @throws IllegalArgumentException if the {@code format} is not supported or |
190 * if the {@link DataSource} cannot translate the SQL |
223 * if the {@link DataSource} cannot translate the SQL |
|
224 * @throws IllegalStateException if this {@link DataSource} is closed |
191 */ |
225 */ |
192 public default String translateSql(String format, String source) throws SqlException { |
226 public default String translateSql(String format, String source) throws SqlException { |
193 throw new IllegalArgumentException("Unsupported format: \"" + format + "\""); |
227 throw new IllegalArgumentException("Unsupported format: \"" + format + "\""); |
194 } |
228 } |
195 |
229 |
197 * Return a list of the source formats accepted by the {@link translateSql} method. |
231 * Return a list of the source formats accepted by the {@link translateSql} method. |
198 * |
232 * |
199 * ISSUE: Just an idea |
233 * ISSUE: Just an idea |
200 * |
234 * |
201 * @return an array of Strings each of which identifies a supported format |
235 * @return an array of Strings each of which identifies a supported format |
|
236 * @throws IllegalStateException if this {@link DataSource} is closed |
202 */ |
237 */ |
203 public default List<String> supportedTranslateSqlFormats() { |
238 public default List<String> supportedTranslateSqlFormats() { |
204 return new LinkedList<>(); |
239 return new LinkedList<>(); |
205 } |
240 } |
206 |
241 |