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