Hi Brian, Thank you for your input. Here is the revised version: ——————— hg diff diff -r 45b226ad2e05 src/java.sql/share/classes/java/sql/Connection.java --- a/src/java.sql/share/classes/java/sql/Connection.java Thu Mar 16 16:56:29 2017 -0400 +++ b/src/java.sql/share/classes/java/sql/Connection.java Fri Apr 07 18:42:20 2017 -0400 @@ -1535,8 +1535,9 @@ * <li>The connection pool caches {@code PooledConnection} objects</li> * <li>Returns a logical connection handle when {@code getConnection} is * called by the application</li> - * <li>The pool manager calls {@code Connection.close} on the logical connection handle - * prior to returning the {@code PooledConnection} back to the cache</li> + * <li>The logical {@code Connection} is closed by calling + * {@code Connection.close} prior to returning the {@code PooledConnection} + * to the cache.</li> * </ul> * @throws SQLException if an error occurs * @since 9 @@ -1577,8 +1578,9 @@ * <li>The connection pool caches {@code PooledConnection} objects</li> * <li>Returns a logical connection handle when {@code getConnection} is * called by the application</li> - * <li>The pool manager calls {@code Connection.close} on the logical connection handle - * prior to returning the {@code PooledConnection} back to the cache</li> + * <li>The logical {@code Connection} is closed by calling + * {@code Connection.close} prior to returning the {@code PooledConnection} + * to the cache.</li> * </ul> * @throws SQLException if an error occurs * @since 9 @@ -1590,7 +1592,10 @@ } /** - * Sets and validates the sharding keys for this connection. + * Sets and validates the sharding keys for this connection. A {@code null} + * value may be specified for the sharding Key. The validity + * of a {@code null} sharding key is vendor-specific. Consult your vendor's + * documentation for additional information. * @implSpec * The default implementation will throw a * {@code SQLFeatureNotSupportedException}. @@ -1600,7 +1605,8 @@ * {@code Connection}. The timeout value indicates how long the driver * should wait for the {@code Connection} to verify that the sharding key * is valid before {@code setShardingKeyIfValid} returns false. - * @param shardingKey the sharding key to be validated against this connection + * @param shardingKey the sharding key to be validated against this connection. + * The sharding key may be {@code null} * @param superShardingKey the super sharding key to be validated against this * connection. The super sharding key may be {@code null}. * @param timeout time in seconds before which the validation process is expected to @@ -1610,10 +1616,10 @@ * and set on this connection; false if the sharding keys are not valid or * the timeout period expires before the operation completes. * @throws SQLException if an error occurs while performing this validation; - * the {@code shardingkey} is {@code null}; a {@code superSharedingKey} is specified + * a {@code superSharedingKey} is specified * without a {@code shardingKey}; * this method is called on a closed {@code connection}; or - * the {@code timeout} value is less than 0. + * the {@code timeout} value is negative. * @throws SQLFeatureNotSupportedException if the driver does not support sharding * @since 9 * @see ShardingKey @@ -1626,7 +1632,10 @@ } /** - * Sets and validates the sharding key for this connection. + * Sets and validates the sharding key for this connection. A {@code null} + * value may be specified for the sharding Key. The validity + * of a {@code null} sharding key is vendor-specific. Consult your vendor's + * documentation for additional information. * @implSpec * The default implementation will throw a * {@code SQLFeatureNotSupportedException}. @@ -1635,7 +1644,8 @@ * {@code Connection}. The timeout value indicates how long the driver * should wait for the {@code Connection} to verify that the sharding key * is valid before {@code setShardingKeyIfValid} returns false. - * @param shardingKey the sharding key to be validated against this connection + * @param shardingKey the sharding key to be validated against this connection. + * The sharding key may be {@code null} * @param timeout time in seconds before which the validation process is expected to * be completed,else the validation process is aborted. A value of 0 indicates * the validation process will not time out. @@ -1643,8 +1653,8 @@ * set on this connection; false if the sharding key is not valid or * the timeout period expires before the operation completes. * @throws SQLException if there is an error while performing this validation; - * this method is called on a closed {@code connection}; the {@code shardingkey} - * is {@code null}; or the {@code timeout} value is less than 0. + * this method is called on a closed {@code connection}; + * or the {@code timeout} value is negative. * @throws SQLFeatureNotSupportedException if the driver does not support sharding * @since 9 * @see ShardingKey @@ -1664,12 +1674,12 @@ * This method sets the specified sharding keys but does not require a * round trip to the database to validate that the sharding keys are valid * for the {@code Connection}. - * @param shardingKey the sharding key to set on this connection. + * @param shardingKey the sharding key to set on this connection. The sharding + * key may be {@code null} * @param superShardingKey the super sharding key to set on this connection. * The super sharding key may be {@code null} * @throws SQLException if an error occurs setting the sharding keys; - * this method is called on a closed {@code connection}; - * the {@code shardingkey} is {@code null}; or + * this method is called on a closed {@code connection}; or * a {@code superSharedingKey} is specified without a {@code shardingKey} * @throws SQLFeatureNotSupportedException if the driver does not support sharding * @since 9 @@ -1690,10 +1700,10 @@ * This method sets the specified sharding key but does not require a * round trip to the database to validate that the sharding key is valid * for the {@code Connection}. - * @param shardingKey the sharding key to set on this connection. - * @throws SQLException if an error occurs setting the sharding key; - * this method is called on a closed {@code connection}; or the - * {@code shardkingKey} is {@code null} + * @param shardingKey the sharding key to set on this connection. The sharding + * key may be {@code null} + * @throws SQLException if an error occurs setting the sharding key; or + * this method is called on a closed {@code connection} * @throws SQLFeatureNotSupportedException if the driver does not support sharding * @since 9 * @see ShardingKey ljanders-mac:sql ljanders$ —————————— Best Lance
On Apr 7, 2017, at 6:24 PM, Brian Burkhalter <brian.burkhalter@oracle.com> wrote:
Hi Lance,
Minor comments inline.
Brian
On Apr 7, 2017, at 2:11 PM, Lance Andersen <lance.andersen@oracle.com <mailto:lance.andersen@oracle.com>> wrote:
Please review the following minor update to the Connection javadocs. The CCC has been approved.
—————————— $ hg diff diff -r 45b226ad2e05 src/java.sql/share/classes/java/sql/Connection.java --- a/src/java.sql/share/classes/java/sql/Connection.java Thu Mar 16 16:56:29 2017 -0400 +++ b/src/java.sql/share/classes/java/sql/Connection.java Fri Apr 07 15:12:08 2017 -0400 @@ -1535,8 +1535,9 @@ * <li>The connection pool caches {@code PooledConnection} objects</li> * <li>Returns a logical connection handle when {@code getConnection} is * called by the application</li> - * <li>The pool manager calls {@code Connection.close} on the logical connection handle - * prior to returning the {@code PooledConnection} back to the cache</li> + * <li>The logical {@code Connection} is closed by calling + * {@code Connection.close} prior to returning the {@code PooledConnection} + * back to the cache.</li>
I would delete “back” in the previous line.
* </ul> * @throws SQLException if an error occurs * @since 9 @@ -1577,8 +1578,9 @@ * <li>The connection pool caches {@code PooledConnection} objects</li> * <li>Returns a logical connection handle when {@code getConnection} is * called by the application</li> - * <li>The pool manager calls {@code Connection.close} on the logical connection handle - * prior to returning the {@code PooledConnection} back to the cache</li> + * <li>The logical {@code Connection} is closed by calling + * {@code Connection.close} prior to returning the {@code PooledConnection} + * back to the cache.</li>
Same here.
* </ul> * @throws SQLException if an error occurs * @since 9 @@ -1590,7 +1592,10 @@ }
/** - * Sets and validates the sharding keys for this connection. + * Sets and validates the sharding keys for this connection. A {@code null} + * value may be specified for the sharding Key. The validity + * of a {@code null} sharding key is vendor specific. Consult your vendors
I would hyphenate “vendor-specific” and change “vendors” to “vendor’s"
+ * documentation for additional information. * @implSpec * The default implementation will throw a * {@code SQLFeatureNotSupportedException}. @@ -1600,7 +1605,8 @@ * {@code Connection}. The timeout value indicates how long the driver * should wait for the {@code Connection} to verify that the sharding key * is valid before {@code setShardingKeyIfValid} returns false. - * @param shardingKey the sharding key to be validated against this connection + * @param shardingKey the sharding key to be validated against this connection. + * The sharding key may be {@code null} * @param superShardingKey the super sharding key to be validated against this * connection. The super sharding key may be {@code null}. * @param timeout time in seconds before which the validation process is expected to @@ -1610,7 +1616,7 @@ * and set on this connection; false if the sharding keys are not valid or * the timeout period expires before the operation completes. * @throws SQLException if an error occurs while performing this validation; - * the {@code shardingkey} is {@code null}; a {@code superSharedingKey} is specified + * a {@code superSharedingKey} is specified * without a {@code shardingKey}; * this method is called on a closed {@code connection}; or * the {@code timeout} value is less than 0.
“less than 0” could be simple “negative."
@@ -1626,7 +1632,10 @@ }
/** - * Sets and validates the sharding key for this connection. + * Sets and validates the sharding key for this connection. A {@code null} + * value may be specified for the sharding Key. The validity + * of a {@code null} sharding key is vendor specific. Consult your vendors
Again I would hyphenate “vendor-specific” and change “vendors” to “vendor’s"
+ * documentation for additional information. * @implSpec * The default implementation will throw a * {@code SQLFeatureNotSupportedException}. @@ -1635,7 +1644,8 @@ * {@code Connection}. The timeout value indicates how long the driver * should wait for the {@code Connection} to verify that the sharding key * is valid before {@code setShardingKeyIfValid} returns false. - * @param shardingKey the sharding key to be validated against this connection + * @param shardingKey the sharding key to be validated against this connection. + * The sharding key may be {@code null} * @param timeout time in seconds before which the validation process is expected to * be completed,else the validation process is aborted. A value of 0 indicates * the validation process will not time out. @@ -1643,8 +1653,8 @@ * set on this connection; false if the sharding key is not valid or * the timeout period expires before the operation completes. * @throws SQLException if there is an error while performing this validation; - * this method is called on a closed {@code connection}; the {@code shardingkey} - * is {@code null}; or the {@code timeout} value is less than 0. + * this method is called on a closed {@code connection}; + * or the {@code timeout} value is less than 0.
Again “less than 0” could be simple “negative."
* @throws SQLFeatureNotSupportedException if the driver does not support sharding * @since 9 * @see ShardingKey @@ -1664,12 +1674,12 @@ * This method sets the specified sharding keys but does not require a * round trip to the database to validate that the sharding keys are valid * for the {@code Connection}. - * @param shardingKey the sharding key to set on this connection. + * @param shardingKey the sharding key to set on this connection. The sharding + * key may be {@code null} * @param superShardingKey the super sharding key to set on this connection. * The super sharding key may be {@code null} * @throws SQLException if an error occurs setting the sharding keys; - * this method is called on a closed {@code connection}; - * the {@code shardingkey} is {@code null}; or + * this method is called on a closed {@code connection}; or * a {@code superSharedingKey} is specified without a {@code shardingKey} * @throws SQLFeatureNotSupportedException if the driver does not support sharding * @since 9 @@ -1690,10 +1700,10 @@ * This method sets the specified sharding key but does not require a * round trip to the database to validate that the sharding key is valid * for the {@code Connection}. - * @param shardingKey the sharding key to set on this connection. - * @throws SQLException if an error occurs setting the sharding key; - * this method is called on a closed {@code connection}; or the - * {@code shardkingKey} is {@code null} + * @param shardingKey the sharding key to set on this connection. The sharding + * key may be {@code null} + * @throws SQLException if an error occurs setting the sharding key; or + * this method is called on a closed {@code connection} * @throws SQLFeatureNotSupportedException if the driver does not support sharding * @since 9 * @see ShardingKey
<http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037 Oracle Java Engineering 1 Network Drive Burlington, MA 01803 Lance.Andersen@oracle.com <mailto:Lance.Andersen@oracle.com>