--- 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.
+ * <P>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.
--- 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 <S>
+ * @param <S> 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
--- 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);
}
/**
--- 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
*/
--- 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<T> onError(Consumer<Throwable> handler);
--- 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 <R>
+ * @param <R> 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
*/
--- 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<Boolean> 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,
--- 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<T> subscribe(Flow.Subscriber<Result.Row> rowSubscriber) {
--- 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);
--- 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 <T>
+ * @param <T> the type of SQL REF
*/
public interface SqlRef<T> {
@@ -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<Void> 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<Void> store(T value) {
--- 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);
--- 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();
}
--- 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 <T> The type of the result of this {@link Operation}
* @see DynamicMultiOperation
- * @author douglas.surber
*/
public interface StaticMultiOperation<T> extends OutOperation<T> {