RFR: 8178130: Minor update to the Connection javadocs

[Brian Burkhalter]

Hi Lance,

Minor comments inline.

Brian

On Apr 7, 2017, at 2:11 PM, Lance Andersen <lance.andersen at 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