On Fri, 28 Oct 2022 14:54:26 GMT, Daniel Fuchs <dfu...@openjdk.org> wrote:
>> Deprecate URL constructors. Developers are encouraged to use `java.net.URI`
>> to parse or construct any URL.
>>
>> The `java.net.URL` class does not itself encode or decode any URL components
>> according to the escaping mechanism defined in RFC2396. It is the
>> responsibility of the caller to encode any fields, which need to be escaped
>> prior to calling URL, and also to decode any escaped fields, that are
>> returned from URL.
>>
>> This has lead to many issues in the past. Indeed, if used improperly, there
>> is no guarantee that `URL::toString` or `URL::toExternalForm` will lead to a
>> URL string that can be parsed back into the same URL. This can lead to
>> constructing misleading URLs. Another issue is with `equals()` and
>> `hashCode()` which may have to perform a lookup, and do not take
>> encoding/escaping into account.
>>
>> In Java SE 1.4 a new class, `java.net.URI`, has been added to mitigate some
>> of the shortcoming of `java.net.URL`. Conversion methods to create a URL
>> from a URI were also added. However, it was left up to the developers to use
>> `java.net.URI`, or not. This RFE proposes to deprecate all public
>> constructors of `java.net.URL`, in order to provide a stronger warning about
>> their potential misuses. To construct a URL, using `URI::toURL` should be
>> preferred.
>>
>> In order to provide an alternative to the constructors that take a stream
>> handler as parameter, a new factory method `URL::fromURI(java.net.URI,
>> java.net.URLStreamHandler)` is provided as part of this change.
>>
>> Places in the JDK code base that were constructing `java.net.URL` have been
>> temporarily annotated with `@SuppressWarnings("deprecation")`. Some related
>> issues will be logged to revisit the calling code.
>>
>> The CSR can be reviewed here: https://bugs.openjdk.org/browse/JDK-8295949
>
> Daniel Fuchs has updated the pull request with a new target base due to a
> merge or a rebase. The incremental webrev excludes the unrelated changes
> brought in by the merge/rebase. The pull request contains four additional
> commits since the last revision:
>
> - Updated after review comments. In particular var tmp => var => _unused -
> and avoid var in java.xml
> - Merge branch 'master' into deprecate-url-ctor-8294241
> - Fix whitespace issues
> - 8294241
src/java.base/share/classes/java/net/URL.java line 133:
> 131: * specified. The optional fragment is not inherited.
> 132: *
> 133: * <h2><a id="constructor-deprecation"></a>Constructing instances of
> {@code URL}</h2>
Would it be better to move the anchor to line 164 (the line where it says that
the URL constructors are deprecated?
src/java.base/share/classes/java/net/URL.java line 157:
> 155: * The URL constructors are specified to throw
> 156: * {@link MalformedURLException} but the actual parsing/validation
> 157: * that are performed is implementation dependent. Some
> parsing/validation
"the ... are performed" -> "the ... is performed".
src/java.base/share/classes/java/net/URL.java line 166:
> 164: * The {@code java.net.URL} constructors are deprecated.
> 165: * Developers are encouraged to use {@link URI java.net.URI} to parse
> 166: * or construct any {@code URL}. In cases where an instance of {@code
"any URL" -> "a URL" or "all URLs".
src/java.base/share/classes/java/net/URL.java line 168:
> 166: * or construct any {@code URL}. In cases where an instance of {@code
> 167: * java.net.URL} is needed to open a connection, {@link URI} can be used
> 168: * to construct or parse the URL string, possibly calling {@link
I wonder if it might be clearer to say "url string", only to avoid anyone
thinking they call URL::toString.
src/java.base/share/classes/java/net/URL.java line 852:
> 850: * @since 20
> 851: */
> 852: public static URL of(URI uri, URLStreamHandler streamHandler)
The parameter is named "handler" rather than "streamHandler" in constructors so
we should probably keep it the same to avoid any confusion.
src/java.base/share/classes/java/net/URL.java line 885:
> 883:
> 884: @SuppressWarnings("deprecation")
> 885: var result = new URL("jrt", host, port, file, null);
The URL scheme for jrt does have a port so we should look at that some time.
-------------
PR: https://git.openjdk.org/jdk/pull/10874
