Hi Lance,
Minor comments inline.
Brian
On Apr 7, 2017, at 2:11 PM, Lance Andersen <lance.ander...@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
