RFR: 8178130: Minor update to the Connection javadocs

Lance Andersen lance.andersen at oracle.com
Fri Apr 7 22:45:38 UTC 2017


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

 <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 at oracle.com <mailto:Lance.Andersen at oracle.com>





More information about the core-libs-dev mailing list