# HG changeset patch # User lancea # Date 1523048464 14400 # Node ID 729f80d0cf312ac8097a090b3cf6fda2772a58ca # Parent 9171771664eea415a8fd0949b509e982592a50c6 JDK-8188051-branch javadoc and minor updates diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/AdbaType.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/AdbaType.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/AdbaType.java Fri Apr 06 17:01:04 2018 -0400 @@ -26,227 +26,204 @@ package jdk.incubator.sql2; /** - * Remove dependence on java.sql. + *

Defines the constants that are used to identify generic + * SQL types, called JDBC types. + * + * @see SqlType + * @since 1.8 */ public enum AdbaType implements SqlType { - - /** - * - */ - ARRAY, - - /** - * - */ - BIGINT, - - /** - * - */ - BINARY, - - /** - * - */ - BIT, - - /** - * - */ - BOOLEAN, - - /** - * - */ - CHAR, - - /** - * - */ - CLOB, - - /** - * - */ - CURSOR, - - /** - * - */ - DATALINK, - - /** - * - */ - DATE, - - /** - * - */ - DECIMAL, - - /** - * - */ - DISTINCT, - - /** - * - */ - DOUBLE, - - /** - * - */ - FLOAT, - - /** - * - */ - INTEGER, - - /** - * - */ - JAVA_OBJECT, - - /** - * - */ - LONGNVARCHAR, - - /** - * - */ - LONGVARBINARY, - - /** - * - */ - LONGVARCHAR, + + /** + * Identifies the generic SQL type {@code BIT}. + */ + BIT, + /** + * Identifies the generic SQL type {@code TINYINT}. + */ + TINYINT, + /** + * Identifies the generic SQL type {@code SMALLINT}. + */ + SMALLINT, + /** + * Identifies the generic SQL type {@code INTEGER}. + */ + INTEGER, + /** + * Identifies the generic SQL type {@code BIGINT}. + */ + BIGINT, + /** + * Identifies the generic SQL type {@code FLOAT}. + */ + FLOAT, + /** + * Identifies the generic SQL type {@code REAL}. + */ + REAL, + /** + * Identifies the generic SQL type {@code DOUBLE}. + */ + DOUBLE, + /** + * Identifies the generic SQL type {@code NUMERIC}. + */ + NUMERIC, + /** + * Identifies the generic SQL type {@code DECIMAL}. + */ + DECIMAL, + /** + * Identifies the generic SQL type {@code CHAR}. + */ + CHAR, + /** + * Identifies the generic SQL type {@code VARCHAR}. + */ + VARCHAR, + /** + * Identifies the generic SQL type {@code LONGVARCHAR}. + */ + LONGVARCHAR, + /** + * Identifies the generic SQL type {@code DATE}. + */ + DATE, + /** + * Identifies the generic SQL type {@code TIME}. + */ + TIME, + /** + * Identifies the generic SQL type {@code TIMESTAMP}. + */ + TIMESTAMP, + /** + * Identifies the generic SQL type {@code BINARY}. + */ + BINARY, + /** + * Identifies the generic SQL type {@code VARBINARY}. + */ + VARBINARY, + /** + * Identifies the generic SQL type {@code LONGVARBINARY}. + */ + LONGVARBINARY, + /** + * Identifies the generic SQL value {@code NULL}. + */ + NULL, + /** + * Indicates that the SQL type + * is database-specific and gets mapped to a Java object that can be + * accessed via the methods getObject and setObject. + */ + OTHER, + /** + * Indicates that the SQL type + * is database-specific and gets mapped to a Java object that can be + * accessed via the methods getObject and setObject. + */ + JAVA_OBJECT, + /** + * Identifies the generic SQL type {@code DISTINCT}. + */ + DISTINCT, + /** + * Identifies the generic SQL type {@code STRUCT}. + */ + STRUCT, + /** + * Identifies the generic SQL type {@code ARRAY}. + */ + ARRAY, + /** + * Identifies the generic SQL type {@code BLOB}. + */ + BLOB, + /** + * Identifies the generic SQL type {@code CLOB}. + */ + CLOB, + /** + * Identifies the generic SQL type {@code REF}. + */ + REF, + /** + * Identifies the generic SQL type {@code DATALINK}. + */ + DATALINK, + /** + * Identifies the generic SQL type {@code BOOLEAN}. + */ + BOOLEAN, - /** - * - */ - NCHAR, - - /** - * - */ - NCLOB, - - /** - * - */ - NULL, - - /** - * - */ - NUMERIC, - - /** - * - */ - NVARCHAR, - - /** - * - */ - OTHER, - - /** - * - */ - REAL, - - /** - * - */ - REF, - - /** - * - */ - REF_CURSOR, - - /** - * - */ - ROWID, + /** + * Identifies the SQL type {@code ROWID}. + */ + ROWID, + /** + * Identifies the generic SQL type {@code NCHAR}. + */ + NCHAR, + /** + * Identifies the generic SQL type {@code NVARCHAR}. + */ + NVARCHAR, + /** + * Identifies the generic SQL type {@code LONGNVARCHAR}. + */ + LONGNVARCHAR, + /** + * Identifies the generic SQL type {@code NCLOB}. + */ + NCLOB, + /** + * Identifies the generic SQL type {@code SQLXML}. + */ + SQLXML, - /** - * - */ - SMALLINT, - - /** - * - */ - SQLXML, + /** + * Identifies the generic SQL type {@code REF_CURSOR}. + */ + REF_CURSOR, - /** - * - */ - STRUCT, - - /** - * - */ - TIME, - - /** - * - */ - TIMESTAMP, + /** + * Identifies the generic SQL type {@code TIME_WITH_TIMEZONE}. + */ + TIME_WITH_TIMEZONE, - /** - * - */ - TIME_WITH_TIME_ZONE, - - /** - * - */ - TIMESTAMP_WITH_TIME_ZONE, - - /** - * - */ - TINYINT, + /** + * Identifies the generic SQL type {@code TIMESTAMP_WITH_TIMEZONE}. + */ + TIMESTAMP_WITH_TIMEZONE; - /** - * - */ - VARBINARY, - - /** - * - */ - VARCHAR; - - /** - * - * @return - */ + + /** + *{@inheritDoc } + * @return The name of this {@code SQLType}. + */ @Override public String getName() { throw new UnsupportedOperationException("Not supported yet."); //To change body of generated methods, choose Tools | Templates. } - /** - * - * @return - */ + /** + * Returns the name of the vendor that supports this data type. + * @return The name of the vendor for this data type which is + * {@literal java.sql} for ABDAType. + */ @Override public String getVendor() { throw new UnsupportedOperationException("Not supported yet."); //To change body of generated methods, choose Tools | Templates. } - /** - * - * @return - */ + /** + * Returns the vendor specific type number for the data type. + * @return An Integer representing the data type. For {@code ABDAType}, + * the value will be the same value as in {@code Types} for the data type. + */ @Override public Integer getVendorTypeNumber() { throw new UnsupportedOperationException("Not supported yet."); //To change body of generated methods, choose Tools | Templates. diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/ConnectionProperty.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/ConnectionProperty.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/ConnectionProperty.java Fri Apr 06 17:01:04 2018 -0400 @@ -54,7 +54,7 @@ * {@code true} if {@code value} is valid and {@code false} otherwise. * * @param value a value for this {@link ConnectionProperty} - * @return {@code true} iff {@code value} is valid for this {@link ConnectionProperty} + * @return {@code true} if {@code value} is valid for this {@link ConnectionProperty} */ public default boolean validate(Object value) { return (value == null && this.range() == Void.class) || this.range().isInstance(value); @@ -74,7 +74,7 @@ * Returns true if this {@link ConnectionProperty} is contains sensitive information * such as a password or encryption key. * - * @return true iff this is sensitive + * @return true if this is sensitive */ public boolean isSensitive(); @@ -87,7 +87,7 @@ * in the {@link Connection.Builder#property} method. ConnectionProperties known to the implementation * may return {@code null} and rely on the implementation to do the right thing. * - * @param + * @param Operation Type * @param group an {@link OperationGroup} which will be the container of the returned * {@link Operation}, if any * @param value the value to which the property is to be set. May be null if diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSourceFactory.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSourceFactory.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DataSourceFactory.java Fri Apr 06 17:01:04 2018 -0400 @@ -24,7 +24,9 @@ */ package jdk.incubator.sql2; +import java.util.Objects; import java.util.ServiceLoader; +import java.util.ServiceLoader.Provider; /** * This interface supports injecting a {@link DataSourceFactory}. The SPI @@ -41,11 +43,17 @@ * @param name the name of the class that implements the factory * @return a {@link DataSourceFactory} for {@code name} or {@code null} if one * is not found + * @throws NullPointerException if name is {@code null} */ public static DataSourceFactory forName(String name) { - if (name == null) throw new IllegalArgumentException("DataSourceFactory name is null"); - return ServiceLoader.load(DataSourceFactory.class).stream() - .filter(p -> p.type().getName().equals(name)).findFirst().get().get(); + Objects.requireNonNull(name, "DataSourceFactory name is null"); + return ServiceLoader + .load(DataSourceFactory.class) + .stream() + .filter(p -> p.type().getName().equals(name)) + .findFirst() + .map(Provider::get) + .orElse(null); } /** diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DynamicMultiOperation.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DynamicMultiOperation.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/DynamicMultiOperation.java Fri Apr 06 17:01:04 2018 -0400 @@ -79,7 +79,7 @@ * * If this method is not called any row sequence result is ignored. * - * @param handler + * @param handler the error handler for this operation * @return This DynamicMultiOperation * @throws IllegalStateException if the RowOperation has not been submitted * when the call to the handler returns @@ -109,7 +109,7 @@ * handler returns the {@link Operation} is completed exceptionally with the * {@link Throwable}. * - * @param handler + * @param handler the error handler for this operation * @return this DynamicMultiOperation * @throws IllegalStateException if any onError method was called previously */ diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Operation.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Operation.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Operation.java Fri Apr 06 17:01:04 2018 -0400 @@ -46,7 +46,7 @@ * {@link Operation} results in an error, before the Operation is completed, * the handler is called with the {@link Throwable} as the argument. * - * @param handler + * @param handler the error handler for this operation * @return this {@link Operation} */ public Operation onError(Consumer handler); diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/OperationGroup.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/OperationGroup.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/OperationGroup.java Fri Apr 06 17:01:04 2018 -0400 @@ -399,7 +399,8 @@ * rather than passing it to onNext, the Submission returned by the submit * call will not be published. * - * @param + * @param the type of the result of the returned + * {@link Flow.Processor} * @return a Flow.Processor that accepts Operations and generates Submissions * @throws IllegalStateException if there is an active Processor */ diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Result.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Result.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Result.java Fri Apr 06 17:01:04 2018 -0400 @@ -25,8 +25,6 @@ package jdk.incubator.sql2; -import java.util.concurrent.CompletionStage; - /** * All or part of the result of a database operation (lower case). * @@ -50,7 +48,7 @@ /** * - * @return + * @return The number of rows returned */ public long getCount(); } @@ -122,17 +120,6 @@ public long rowNumber(); /** - * Is this the last {@link Row} of the row sequence. If true then the result of the - * call that was passed this {@link Row} is the result of the {@link Operation}. - * - * @return a {@link java.util.concurrent.CompletionStage} the value of which - * will be true iff this the last {@link Row} of a row sequence and false otherwise - * @throws IllegalStateException if the call that was passed this {@link Result} has - * ended - */ - public CompletionStage isLast(); - - /** * Terminate processing of the rows in this {@link RowOperation}. The result of the * call that was passed this {@link Row} will be the result of the {@link Operation}. No * further rows in the row sequence will be processed. All subsequent rows, diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/RowProcessorOperation.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/RowProcessorOperation.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/RowProcessorOperation.java Fri Apr 06 17:01:04 2018 -0400 @@ -89,7 +89,7 @@ * Subscribe to the stream of Rows returned by this Operation. The result of * this Operation is null. This is a convenience method. * - * @param rowSubscriber + * @param rowSubscriber subscribes to a stream of Result.Rows * @return this RowProcessorOperation */ public default RowProcessorOperation subscribe(Flow.Subscriber rowSubscriber) { diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlException.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlException.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlException.java Fri Apr 06 17:01:04 2018 -0400 @@ -79,12 +79,15 @@ /** * - * @param message - * @param cause - * @param sqlState - * @param vendorCode - * @param sql - * @param position + * @param message a description of the exception + * @param cause the underlying reason for this SqlException + * (which is saved for later retrieval by the getCause() method); + * may be null indicating the cause is non-existent or unknown. + * @param sqlState an XOPEN or SQL:2003 code identifying the exception + * @param vendorCode a database vendor-specific exception code + * @param sql the SQL string that was sent to the database + * @param position the index of the first character in SQL where an error is detected. Zero + * based */ public SqlException(String message, Throwable cause, String sqlState, int vendorCode, String sql, int position) { super(message, cause); diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlRef.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlRef.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlRef.java Fri Apr 06 17:01:04 2018 -0400 @@ -28,7 +28,7 @@ /** * - * @param + * @param the type of SQL REF */ public interface SqlRef { @@ -38,7 +38,7 @@ * ISSUE: Oracle Database JDBC driver may do a round trip for this. Is this * that heavy in other databases? * - * @return + * @return the fully-qualified SQL name of the referenced SQL structured type */ public String getReferentTypeName(); @@ -64,7 +64,8 @@ * Create and return an Operation that will set the value of the REF in the * database. * - * @param value + * @param value an Object representing the SQL structured type instance + * that this Ref object will reference * @return an Operation that will store the new referent into the REF */ public Operation storeOperation(T value); @@ -73,7 +74,8 @@ * Submit an Operation that will store the new value of the referent into * the REF in the database. * - * @param value + * @param value an Object representing the SQL structured type instance + * that this Ref object will reference * @return a Future that will complete when the submitted Operation completes. */ public default CompletionStage store(T value) { diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlSkippedException.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlSkippedException.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlSkippedException.java Fri Apr 06 17:01:04 2018 -0400 @@ -40,12 +40,15 @@ /** * - * @param message - * @param cause - * @param sqlState - * @param vendorCode - * @param sql - * @param position + * @param message a description of the exception + * @param cause the underlying reason for this SqlSkippedException + * (which is saved for later retrieval by the getCause() method); + * may be null indicating the cause is non-existent or unknown. + * @param sqlState an XOPEN or SQL:2003 code identifying the exception + * @param vendorCode a database vendor-specific exception code + * @param sql the SQL string that was sent to the database + * @param position the index of the first character in SQL where an error is detected. Zero + * based */ public SqlSkippedException(String message, Throwable cause, String sqlState, int vendorCode, String sql, int position) { super(message, cause, sqlState, vendorCode, sql, position); diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlType.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlType.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/SqlType.java Fri Apr 06 17:01:04 2018 -0400 @@ -26,25 +26,32 @@ package jdk.incubator.sql2; /** - * Remove dependence on java.sql. + * An object that is used to identify a generic SQL type, called a JDBC type or + * a vendor specific data type. + * + * @since 1.8 */ public interface SqlType { - /** - * - * @return - */ + /** + * Returns the {@code SQLType} name that represents a SQL data type. + * + * @return The name of this {@code SQLType}. + */ public String getName(); - /** - * - * @return - */ + /** + * Returns the name of the vendor that supports this data type. The value + * returned typically is the package name for this vendor. + * + * @return The name of the vendor for this data type + */ public String getVendor(); - /** - * - * @return - */ + /** + * Returns the vendor specific type number for the data type. + * + * @return An Integer representing the vendor specific data type + */ public Integer getVendorTypeNumber(); } diff -r 9171771664ee -r 729f80d0cf31 src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/StaticMultiOperation.java --- a/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/StaticMultiOperation.java Mon Apr 02 15:52:50 2018 -0400 +++ b/src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/StaticMultiOperation.java Fri Apr 06 17:01:04 2018 -0400 @@ -40,7 +40,6 @@ * * @param The type of the result of this {@link Operation} * @see DynamicMultiOperation - * @author douglas.surber */ public interface StaticMultiOperation extends OutOperation {