April 2017 - core-libs-dev

RFR: 8178130: Minor update to the Connection javadocs
by Lance Andersen 07 Apr '17

07 Apr '17

Hi all, 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> * </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> * </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 + * 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. @@ -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 + * 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. * @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 —————————————— Best, Lance <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(a)oracle.com <mailto:Lance.Andersen@oracle.com>

2 3

JDK 9 RFR(s): 8173152: Wrong wording in Comparator.compare() method spec
by Stuart Marks 07 Apr '17

07 Apr '17

Hi all, Please review this small javadoc fix to correct the wording in Comparator.compare(). There's a sentence defining the sgn() notation, that says "In the foregoing description" but it occurs *before* the actual use of sgn(). I've moved this to the end of the method spec. This also makes the Comparator.compare() method spec very similar to the Comparable.compareTo() method spec. Thanks, s'marks # HG changeset patch # User smarks # Date 1491530800 25200 # Thu Apr 06 19:06:40 2017 -0700 # Node ID 1f08b6bc20078e07f7264e449a334234906d46e5 # Parent 7c72114a555820da956c81364ae7ba30698aa799 8173152: Wrong wording in Comparator.compare() method spec Reviewed-by: XXX diff -r 7c72114a5558 -r 1f08b6bc2007 src/java.base/share/classes/java/util/Comparator.java --- a/src/java.base/share/classes/java/util/Comparator.java Fri Mar 31 14:21:21 2017 -0700 +++ b/src/java.base/share/classes/java/util/Comparator.java Thu Apr 06 19:06:40 2017 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -112,12 +112,6 @@ * zero, or a positive integer as the first argument is less than, equal * to, or greater than the second. * - * In the foregoing description, the notation - * {@code sgn(}expression{@code )} designates the mathematical - * signum function, which is defined to return one of {@code -1}, - * {@code 0}, or {@code 1} according to whether the value of - * expression is negative, zero or positive. - * * The implementor must ensure that {@code sgn(compare(x, y)) == * -sgn(compare(y, x))} for all {@code x} and {@code y}. (This * implies that {@code compare(x, y)} must throw an exception if and only @@ -135,7 +129,13 @@ * {@code (compare(x, y)==0) == (x.equals(y))}. Generally speaking, * any comparator that violates this condition should clearly indicate * this fact. The recommended language is "Note: this comparator - * imposes orderings that are inconsistent with equals." + * imposes orderings that are inconsistent with equals." + * + * In the foregoing description, the notation + * {@code sgn(}expression{@code )} designates the mathematical + * signum function, which is defined to return one of {@code -1}, + * {@code 0}, or {@code 1} according to whether the value of + * expression is negative, zero or positive. * * @param o1 the first object to be compared. * @param o2 the second object to be compared.

2 3

RFR 8178323: Add negative tests for bind services Jlink feature
by Andrey Nazarov 07 Apr '17

07 Apr '17

Hi, Please review 3 negative tests for Jlink which tests new bind-services/suggest-providers feature. JBS: https://bugs.openjdk.java.net/browse/JDK-8178323 webrev: http://cr.openjdk.java.net/~anazarov/8178323/webrev.00/webrev/ <http://cr.openjdk.java.net/~anazarov/8178323/webrev.00/webrev/> —Andrey

1 0

ProcessHandle::getPid
by mark.reinhold＠oracle.com 07 Apr '17

07 Apr '17

Playing around with the `ProcessHandle` API the other day, I noticed that it uses non-Beans accessor names (good!) -- except for `getPid()`. Is there a reason why that method isn't just `pid()`? - Mark

2 2

[8u] RFR: 8177776: Create an equivalent test case for JDK9's SupplementalJapaneseEraTest
by Naoto Sato 06 Apr '17

06 Apr '17

Hello, Please review the changes to the following issue: https://bugs.openjdk.java.net/browse/JDK-8177776 The proposed change is located at: http://cr.openjdk.java.net/~naoto/8177776/webrev.00/ This is for backporting fixes for JapaneseEra related issues (8054214, 8173423). The original fixes in JDK9 included a test case, SupplementalJapaneseEraTest which is intended for the system property testing. The above proposed fix intends to adapt that test case into JDK8, where calendars.properties file is used instead of the system property. The test is pretty much identical to JDK9's. The difference is to deal with the calendars.properties file and removed some non-applicable cases in JDK8. Naoto

3 5

9 RFR: 8178139: Minor typo in API documentation of java.util.logging.Logger
by Daniel Fuchs 06 Apr '17

06 Apr '17

Hi, Please find below a trivial change to fix 8178139: Minor typo in API documentation of java.util.logging.Logger https://bugs.openjdk.java.net/browse/JDK-8178139 will configured => will be configured (appears twice) This is a minor typo doc fix so AFAIU RDP2 approval is not needed. best regards, -- daniel diff --git a/src/java.logging/share/classes/java/util/logging/Logger.java b/src/java.logging/share/classes/java/util/logging/Logger.java --- a/src/java.logging/share/classes/java/util/logging/Logger.java +++ b/src/java.logging/share/classes/java/util/logging/Logger.java @@ -664,7 +664,7 @@ * a new logger is created. * * If a new logger is created its log level will be configured - * based on the LogManager configuration and it will configured + * based on the LogManager configuration and it will be configured * to also send logging output to its parent's Handlers. It will * be registered in the LogManager global namespace. * @@ -726,7 +726,7 @@ * * * If a new logger is created its log level will be configured - * based on the LogManager and it will configured to also send logging + * based on the LogManager and it will be configured to also send logging * output to its parent's Handlers. It will be registered in * the LogManager global namespace. *

2 2

JDK 9 RFR(m): 8177788 migrate collections docs into jdk doc-files
by Stuart Marks 06 Apr '17

06 Apr '17

Hi all, Here's another step in the docs cleanup: migration of the collections technotes/guides into the JDK's javadoc doc-files. This is a webrev containing two changesets: JDK-8177787 copy collections technotes/guides html files into jdk doc-files JDK-8177788 fix links, minor editing, add Java SE 9 changes to collections docs The main way to reach these pages will now be a link from the java.util package documentation. There are a bunch of places around the javadoc that point to the obsolete location of the collections docs. These are typically within sentences of the form "This class is a member of the Java Collections Framework." The next step will be to change all those links to point to the docs in their new location. Here's the webrev: http://cr.openjdk.java.net/~smarks/reviews/8177788/webrev.0/ Thanks, s'marks

2 2

JDK 9 RFR(s): JDK-8065825: Make the java -help consistent with the man page
by Kumar Srinivasan 05 Apr '17

05 Apr '17

Hello, Please review: http://cr.openjdk.java.net/~ksrini/8065825/webrev.00/ This adds a few things to the java -help and some minor cleanup. Thanks Kumar

2 3

Java 9 and IntSummaryStatistics et al.
by Chris Dennis 05 Apr '17

05 Apr '17

Hi All, I’m currently working on a project thats attempting to do a lot of heavy lifting work with Java Streams (implementing, extending, adapting, etc). One issue we ran in to is the inflexibility around unmarshalling the IntSummaryStatistics class (and it’s other primitive variations). I had originally decided to not push on this since it had already been filed as a enhancement request and dismissed (JDK-8043747) and since in Java 8 and earlier it wasn’t a huge problem for us as we could use reflection to force the initialization of one of these objects without much issue (modulo SecurityManager usage). In Java 9 this starts to get much more unpalatable. I’m left with having to open up parts of the java.base module in order to get to what I need (in classpath mode this looks particularly ugly since I have to open up to ALL-UNNAMED). What I’m trying to do here is get a roadmap in place for how to approach these kinds of problems in a Java ecosystem which is (presumably) moving towards a gradually more strict position on strong encapsulation. Right now code that treats a stream pipeline as anything more complex than a ‘literal’ pipeline of operations through which events are pushed is going to hit this problem - a simple example would be any kind of calculation being performed in advance of stream creation. Right now the lack of interface decoupling here means I have no choice but to ‘brute-force’ all these calculations. Thanks, Chris Dennis

5 12

JDK 9 RFR of JDK-8177640: jdk/internal/util/jar/TestVersionedStream.java fails on Windows
by Amy Lu 05 Apr '17

05 Apr '17

Please review this test-only change. jdk/internal/util/jar/TestVersionedStream.java This test fails on Windows platforms. Test tries to create and write something to the files (in test preparation method 'createFiles') for later comparison (in test method 'test'). The content write to the new created file contains path and line separator,but test does not take into account the platform difference. bug: https://bugs.openjdk.java.net/browse/JDK-8177640 webrev: http://cr.openjdk.java.net/~amlu/8177640/webrev.00/ Thanks, Amy

2 1