# HG changeset patch # User lancea # Date 1531423393 14400 # Node ID 4f7713e6a308c2db4828eafccaa0d6e3413fdb11 # Parent 21443aec7aa7e3a51f8da3b6f608f2dc30d3d2bf JDK-8188051-branch javadoc updates diff -r 21443aec7aa7 -r 4f7713e6a308 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSourceProperty.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSourceProperty.java Thu Jul 12 15:21:13 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSourceProperty.java Thu Jul 12 15:23:13 2018 -0400 @@ -81,7 +81,7 @@ public boolean isSensitive(); /** - * Configure the {@link DataSource as appropriate for the given {@code value} + * Configure the {@link DataSource} as appropriate for the given {@code value} * of this {@link DataSourceProperty}. This is primarily for the use of user * defined properties. * diff -r 21443aec7aa7 -r 4f7713e6a308 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Examples.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Examples.java Thu Jul 12 15:21:13 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Examples.java Thu Jul 12 15:23:13 2018 -0400 @@ -34,6 +34,7 @@ import java.util.concurrent.Flow; import java.util.concurrent.ForkJoinPool; import java.util.concurrent.Semaphore; +import java.util.concurrent.atomic.AtomicLong; import java.util.stream.Collector; import java.util.stream.Collectors; @@ -256,32 +257,6 @@ } } - // Control Operation Submission Rate - - public CompletionStage insertRecords(DataSource ds, DataInputStream in) { - String insert = "insert into tab values (@record)"; - try (Session session = ds.getSession()) { - OperationGroup group = session.operationGroup() - .independent() - .collect(Collectors.summingLong(c -> c)); - group.submitHoldingForMoreMembers(); - Semaphore demand = new Semaphore(0); - session.requestHook( n -> demand.release((int)n) ); - while (in.available() > 0) { - demand.acquire(1); // user thread blocked by Semaphore, not by ADBA - group.rowCountOperation(insert) - .set("record", in.readUTF(), AdbaType.VARCHAR) - .apply(c -> c.getCount()) - .submit(); - } - return group.releaseProhibitingMoreMembers() - .getCompletionStage(); - } - catch (IOException | InterruptedException ex) { - throw new SqlException(ex); - } - } - // ArrayRowCountOperation public CompletionStage arrayInsert(DataSource ds, @@ -336,6 +311,47 @@ // LocalOperation + // Control Operation Submission Rate + + public CompletionStage insertRecords(DataSource ds, DataInputStream in) { + String insert = "insert into tab values (@record)"; + try (Session session = ds.getSession()) { + OperationGroup group = session.operationGroup() + .independent() + .collect(Collectors.summingLong(c -> c)); + group.submitHoldingForMoreMembers(); + Semaphore demand = new Semaphore(0); + session.requestHook( n -> demand.release((int)n) ); + while (in.available() > 0) { + demand.acquire(1); // user thread blocked by Semaphore, not by ADBA + group.rowCountOperation(insert) + .set("record", in.readUTF(), AdbaType.VARCHAR) + .apply(c -> c.getCount()) + .submit(); + } + return group.releaseProhibitingMoreMembers() + .getCompletionStage(); + } + catch (IOException | InterruptedException ex) { + throw new SqlException(ex); + } + } + + // Controlling Session creation rate + + public void ingest(DataInputStream in) throws Exception { + DataSourceFactory factory = DataSourceFactory.newFactory("com.oracle.adbaoverjdbc.DataSourceFactory"); + Semaphore demand = new Semaphore(0); + DataSource ds = factory.builder() + .requestHook( n -> demand.release((int)n) ) + .build(); + AtomicLong total = new AtomicLong(0L); + do { + demand.acquire(1); + insertRecords(ds, in).thenAccept(total::addAndGet); + } while (true); + } + // SessionProperty public enum ExampleSessionProperty implements SessionProperty { LANGUAGE; @@ -367,6 +383,14 @@ } + public DataSource getDataSource(DataSourceFactory factory) { + return factory.builder() + .registerSessionProperty(ExampleSessionProperty.LANGUAGE) + // or .defaultSessionProperty(ExampleSessionProperty.LANGUAGE, "AMERICAN_AMERICA") + // or .sessionProperty(ExampleSessionProperty.LANGUAGE, "FRENCHCANADIAN_CANADA") + .build(); + } + public Session getSession(DataSource ds) { return ds.builder() .property(ExampleSessionProperty.LANGUAGE, "FRENCH_FRANCE") diff -r 21443aec7aa7 -r 4f7713e6a308 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/OperationGroup.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/OperationGroup.java Thu Jul 12 15:21:13 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/OperationGroup.java Thu Jul 12 15:23:13 2018 -0400 @@ -296,7 +296,7 @@ /** * Return a new {@link ParameterizedRowCountOperation}. * - * @param the result type of the returned {@link CountOperation} + * @param 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 * {@link OperationGroup} @@ -378,11 +378,11 @@ public MultiOperation multiOperation(String sql); /** - * Return a new {@link Operation} that ends the database transaction. This + * Return a new {@link Operation} that ends the database transaction. This * {@link Operation} is a member of the {@link OperationGroup}. The - * transaction is ended with a commit unless the {@link Transaction} has been - * {@link Transaction#setRollbackOnly} in which case the transaction is ended - * with a rollback. + * 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. * *

* An endTransaction Operation may be skipped. To insure that it will not be @@ -508,14 +508,13 @@ * If {@code identifier} is not a simple SQL identifier, {@code identifier} * will be enclosed in double quotes if not already present. If the datasource * does not support double quotes for delimited identifiers, the identifier - * should be enclosed by the string returned from - * {@link DatabaseMetaData#getIdentifierQuoteString}. If the datasource does - * not support delimited identifiers, a - * {@code SQLFeatureNotSupportedException} should be thrown. + * should be enquoted by whatever mechanism the data source supports. If the + * datasource does not support delimited identifiers, an + * {@code IllegalArgumentException} should be thrown. *

- * A {@code SQLException} will be thrown if {@code identifier} contains any - * characters invalid in a delimited identifier or the identifier length is - * invalid for the datasource. + * A {@code IllegalArgumentException} will be thrown if {@code identifier} + * contains any characters invalid in a delimited identifier or the identifier + * length is invalid for the datasource. * * @implSpec The default implementation uses the following criteria to * determine a valid simple SQL identifier: @@ -577,17 +576,17 @@ * * Hello"World * false - * SQLException + * IllegalArgumentException * * * "Hello"World" * false - * SQLException + * IllegalArgumentException * * * * - * @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 identifier a SQL identifier. Not null @@ -668,7 +667,7 @@ * * * - * @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 identifier a SQL identifier. Not null @@ -708,7 +707,7 @@ * * * - * @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. An implementation of enquoteNCharLiteral may accept * a different set of characters than that accepted by the same drivers diff -r 21443aec7aa7 -r 4f7713e6a308 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/RowCountOperation.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/RowCountOperation.java Thu Jul 12 15:21:13 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/RowCountOperation.java Thu Jul 12 15:23:13 2018 -0400 @@ -32,7 +32,7 @@ * An {@link Operation} that returns a count. * * @param the type of the result of the {@link Operation} - * @see ParameterizedCountOperation + * @see ParameterizedRowCountOperation */ public interface RowCountOperation extends Operation { diff -r 21443aec7aa7 -r 4f7713e6a308 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Session.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Session.java Thu Jul 12 15:21:13 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Session.java Thu Jul 12 15:23:13 2018 -0400 @@ -40,7 +40,7 @@ *

* A {@link Session} is independent of any particular data source. Any data * source that meets the specifications set by the {@link Session.Builder} can - * be used to execute the {@link Operation}s submitted to the {@link Session]. + * be used to execute the {@link Operation}s submitted to the {@link Session}. * An application is expected to create, use, and close {@link Session}s as * needed. An application should hold a {@link Session} only when required by * data source semantics. An implementation should cache and reused data source diff -r 21443aec7aa7 -r 4f7713e6a308 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SessionProperty.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SessionProperty.java Thu Jul 12 15:21:13 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SessionProperty.java Thu Jul 12 15:23:13 2018 -0400 @@ -73,7 +73,7 @@ public Object defaultValue(); /** - * Returns true if this {@link SessionProperty} is contains sensitive information + * Returns true if this {@link SessionProperty} contains sensitive information * such as a password or encryption key. * * @return true iff this is sensitive diff -r 21443aec7aa7 -r 4f7713e6a308 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlColumns.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlColumns.java Thu Jul 12 15:21:13 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlColumns.java Thu Jul 12 15:23:13 2018 -0400 @@ -34,13 +34,13 @@ /** * Identifies a constructor or static factory method that can be used to construct - * an instance of the containing type when the type is passed to {@link Result.ResultMap#get}. + * an instance of the containing type when the type is passed to {@link Result.Column#get}. * The method or constructor must be public. * * An instance of this type will be constructed by calling the factory method or * constructor. Each element in the value of this annotation is used as a column * identifier. The value of that column is passed to the corresponding parameter - * of the annotated method or constructor. The id argument to {@link Result.ResultMap#get} is + * of the annotated method or constructor. The id argument to {@link Result.Column#get} is * prefixed to the column identifiers. * * The following pseudo-code describes how an instance is constructed. @@ -50,7 +50,7 @@ * String[] columns = methodOrConstructor.getAnnotation(SqlColumns.class).value(); * Object[] args = new Object[columns.length]; * for (String columnName : columns) - * args[i] = resultMap.get(prefix + columnName, parameterTypes[i++]; + * args[i] = colum.at(prefix + columnName).get(parameterTypes[i++]); * instance = methodOrConstructor.invoke(null, args);} * */ diff -r 21443aec7aa7 -r 4f7713e6a308 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/package-info.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/package-info.java Thu Jul 12 15:21:13 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/package-info.java Thu Jul 12 15:23:13 2018 -0400 @@ -103,8 +103,8 @@ * *

* A single context in a data source is represented by a {@link Session}. A - * {@link Session} is somewhat analogous to a logical {@link java.sql.Connection}. - * A physical {@link java.sql.Connection} has no representation in this API; if + * {@link Session} is somewhat analogous to a logical {@code java.sql.Connection}. + * A physical {@code java.sql.Connection} has no representation in this API; if * such an entity exists at all it is strictly internal to an implementation. * Within this spec this entity is referred to as a "data source resource". *

@@ -368,7 +368,7 @@ * FooSession.Builder. build must return a FooSession *
  • FooDataSource must override getSession to return FooSession
    • *
  • FooSession must extend FooOperationGroup
    • - *
  • FooOperationGroup> must override rowCountOperation to return FooRowCountOperation
    • + *
  • FooOperationGroup must override rowCountOperation to return FooRowCountOperation
    • *
  • FooRowCountOperation must override apply and onError to return FooRowCountOperation
    • * *