8294241: Deprecate URL public constructors

Reviewed-by: joehw, prr, alanb, aefimov, michaelm
This commit is contained in:
Daniel Fuchs 2022-11-03 17:18:14 +00:00
parent 68209adfa7
commit 4338f527aa
82 changed files with 848 additions and 146 deletions

View file

@ -129,6 +129,26 @@ import sun.security.action.GetPropertyAction;
* the protocol, host name, or port number is missing, the value is
* inherited from the fully specified URL. The file component must be
* specified. The optional fragment is not inherited.
*
* <h2><a id="constructor-deprecation"></a>Constructing instances of {@code URL}</h2>
*
* The {@code java.net.URL} constructors are deprecated.
* Developers are encouraged to use {@link URI java.net.URI} to parse
* or construct a {@code URL}. In cases where an instance of {@code
* java.net.URL} is needed to open a connection, {@link URI} can be used
* to construct or parse the URL string, possibly calling {@link
* URI#parseServerAuthority()} to validate that the authority component
* can be parsed as a server-based authority, and then calling
* {@link URI#toURL()} to create the {@code URL} instance.
* <p>
* The URL constructors are specified to throw
* {@link MalformedURLException} but the actual parsing/validation
* that is performed is implementation dependent. Some parsing/validation
* may be delayed until later, when the underlying {@linkplain
* URLStreamHandler stream handler's implementation} is called.
* Being able to construct an instance of {@code URL} doesn't
* provide any guarantee about its conformance to the URL
* syntax specification.
* <p>
* The URL class does not itself encode or decode any URL components
* according to the escaping mechanism defined in RFC2396. It is the
@ -152,6 +172,7 @@ import sun.security.action.GetPropertyAction;
*
* @apiNote
*
* <a id="integrity"></a>
* Applications working with file paths and file URIs should take great
* care to use the appropriate methods to convert between the two.
* The {@link Path#of(URI)} factory method and the {@link File#File(URI)}
@ -164,6 +185,11 @@ import sun.security.action.GetPropertyAction;
* from the direct string representation of a {@code File} or {@code Path}
* instance.
* <p>
* Before constructing a {@code URL} from a {@code URI}, and depending
* on the protocol involved, applications should consider validating
* whether the URI authority {@linkplain URI#parseServerAuthority()
* can be parsed as server-based}.
* <p>
* Some components of a URL or URI, such as <i>userinfo</i>, may
* be abused to construct misleading URLs or URIs. Applications
* that deal with URLs or URIs should take into account
@ -373,7 +399,11 @@ public final class URL implements java.io.Serializable {
* @see java.net.URLStreamHandler
* @see java.net.URLStreamHandlerFactory#createURLStreamHandler(
* java.lang.String)
* @deprecated Use {@link URI#toURL()} to construct an instance of URL. See the note on
* <a href="#constructor-deprecation">constructor deprecation</a> for more
* details.
*/
@Deprecated(since = "20")
public URL(String protocol, String host, int port, String file)
throws MalformedURLException
{
@ -399,7 +429,11 @@ public final class URL implements java.io.Serializable {
* rejects, or is known to reject, the {@code URL}
* @see java.net.URL#URL(java.lang.String, java.lang.String,
* int, java.lang.String)
* @deprecated Use {@link URI#toURL()} to construct an instance of URL. See the note on
* <a href="#constructor-deprecation">constructor deprecation</a> for more
* details.
*/
@Deprecated(since = "20")
public URL(String protocol, String host, String file)
throws MalformedURLException {
this(protocol, host, -1, file);
@ -446,7 +480,13 @@ public final class URL implements java.io.Serializable {
* java.lang.String)
* @see SecurityManager#checkPermission
* @see java.net.NetPermission
* @deprecated
* Use {@link #of(URI, URLStreamHandler)} to construct an instance of URL
* associated with a custom protocol handler.
* See the note on <a href="#constructor-deprecation">constructor deprecation</a>
* for more details.
*/
@Deprecated(since = "20")
public URL(String protocol, String host, int port, String file,
URLStreamHandler handler) throws MalformedURLException {
if (handler != null) {
@ -533,7 +573,11 @@ public final class URL implements java.io.Serializable {
* URLStreamHandler#parseURL parseURL method} throws
* {@code IllegalArgumentException}
* @see java.net.URL#URL(java.net.URL, java.lang.String)
* @deprecated Use {@link URI#toURL()} to construct an instance of URL. See the note on
* <a href="#constructor-deprecation">constructor deprecation</a> for more
* details.
*/
@Deprecated(since = "20")
public URL(String spec) throws MalformedURLException {
this(null, spec);
}
@ -593,7 +637,11 @@ public final class URL implements java.io.Serializable {
* @see java.net.URLStreamHandler
* @see java.net.URLStreamHandler#parseURL(java.net.URL,
* java.lang.String, int, int)
* @deprecated Use {@link URI#toURL()} to construct an instance of URL. See the note on
* <a href="#constructor-deprecation">constructor deprecation</a> for more
* details.
*/
@Deprecated(since = "20")
public URL(URL context, String spec) throws MalformedURLException {
this(context, spec, null);
}
@ -626,7 +674,13 @@ public final class URL implements java.io.Serializable {
* @see java.net.URLStreamHandler
* @see java.net.URLStreamHandler#parseURL(java.net.URL,
* java.lang.String, int, int)
* @deprecated
* Use {@link #of(URI, URLStreamHandler)} to construct an instance of URL
* associated with a custom protocol handler.
* See the note on <a href="#constructor-deprecation">constructor deprecation</a>
* for more details.
*/
@Deprecated(since = "20")
public URL(URL context, String spec, URLStreamHandler handler)
throws MalformedURLException
{
@ -748,23 +802,70 @@ public final class URL implements java.io.Serializable {
}
/**
* Creates a URL from a URI, as if by invoking {@code uri.toURL()}.
* Creates a URL from a URI, as if by invoking {@code uri.toURL()}, but
* associating it with the given {@code URLStreamHandler}, if allowed.
*
* @apiNote
* Applications should consider performing additional integrity
* checks before constructing a {@code URL} and opening a connection.
* See the <a href=#integrity>API note</a> in the class level API
* documentation.
*
* @implSpec The implementation of this method includes calling the {@link
* URLStreamHandler#parseURL(URL, String, int, int) parseURL} method on the
* selected handler.
*
* @param uri the {@code URI} from which the returned {@code URL} should
* be built
* @param handler a custom protocol stream handler for
* the returned {@code URL}. Can be {@code null},
* in which case the default stream handler for
* the protocol if any, will be used.
*
* @return a new {@code URL} instance created from the given {@code URI}
* and associated with the given {@code URLStreamHandler}, if any
*
* @throws NullPointerException if {@code uri} is {@code null}
*
* @throws IllegalArgumentException if no protocol is specified
* (the {@linkplain URI#getScheme() uri scheme} is {@code null}), or
* if the {@code URLStreamHandler} is not {@code null} and can not be
* set for the given protocol
*
* @throws MalformedURLException if an unknown protocol is found,
* or the given URI fails to comply with the specific
* syntax of the associated protocol, or the
* underlying stream handler's {@linkplain
* URLStreamHandler#parseURL(URL, String, int, int)
* parseURL method} throws {@code IllegalArgumentException}
*
* @throws SecurityException
* if a security manager exists and its
* {@code checkPermission} method doesn't allow
* specifying a stream handler
*
* @see java.net.URI#toURL()
*
* @since 20
*/
static URL fromURI(URI uri) throws MalformedURLException {
public static URL of(URI uri, URLStreamHandler handler)
throws MalformedURLException {
if (!uri.isAbsolute()) {
throw new IllegalArgumentException("URI is not absolute");
}
String protocol = uri.getScheme();
// fast path for canonical jrt:/... URLs
//
// In general we need to go via Handler.parseURL, but for the jrt
// protocol we enforce that the Handler is not overridable and can
// optimize URI to URL conversion.
//
// Case-sensitive comparison for performance; malformed protocols will
// be handled correctly by the slow path.
if (protocol.equals("jrt") && !uri.isOpaque()
if (handler == null && protocol.equals("jrt") && !uri.isOpaque()
&& uri.getRawAuthority() == null
&& uri.getRawFragment() == null) {
String query = uri.getRawQuery();
@ -780,9 +881,28 @@ public final class URL implements java.io.Serializable {
int port = uri.getPort();
return new URL("jrt", host, port, file, null);
} else {
return new URL((URL)null, uri.toString(), null);
}
// slow path (will work for non-canonical forms of jrt: too)
if ("url".equalsIgnoreCase(protocol)) {;
String uristr = uri.toString();
try {
URI inner = new URI(uristr.substring(4));
if (inner.isAbsolute()) {
protocol = inner.getScheme();
}
} catch (URISyntaxException use) {
throw new MalformedURLException(use.getMessage());
}
}
if (handler != null && !isOverrideable(protocol)) {
throw new IllegalArgumentException("Can't override URLStreamHandler for protocol "
+ protocol);
}
return new URL((URL)null, uri.toString(), handler);
}
/*