stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8294948: Document IllegalArgumentException and NullPointerException thrown by URLStreamHandler::parseURL and URLStreamHandler::setURL

Browse Source 
Reviewed-by: jpai, aefimov, alanb, michaelm
This commit is contained in:
Daniel Fuchs 2022-10-20 08:54:45 +00:00
parent dcd46501e6
commit 9d0cfd1130
2 changed files with 52 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
src/java.base/share/classes/java/net/URL.java
View File

@ -170,6 +170,18 @@ import sun.security.action.GetPropertyAction;
* the recommendations advised in <a * the recommendations advised in <a
* href="https://tools.ietf.org/html/rfc3986#section-7">RFC3986, * href="https://tools.ietf.org/html/rfc3986#section-7">RFC3986,
* Section 7, Security Considerations</a>. * Section 7, Security Considerations</a>.
* <p>
* All {@code URL} constructors may throw {@link MalformedURLException}.
* In particular, if the underlying {@link URLStreamHandler}
* implementation rejects, or is known to reject, any of the parameters,
* {@link MalformedURLException} may be thrown.
* Typically, a constructor that calls the stream handler's {@linkplain
* URLStreamHandler#parseURL(URL, String, int, int) parseURL method} may
* throw {@code MalformedURLException} if the underlying stream handler
* implementation of that method throws {@code IllegalArgumentException}.
* However, which checks are performed, or not, by the stream handlers
* is implementation dependent, and callers should not rely on such
* checks for full URL validation.
* *
* @author James Gosling * @author James Gosling
* @since 1.0 * @since 1.0
@ -352,7 +364,9 @@ public final class URL implements java.io.Serializable {
* @param port the port number on the host. * @param port the port number on the host.
* @param file the file on the host * @param file the file on the host
* @throws MalformedURLException if an unknown protocol or the port * @throws MalformedURLException if an unknown protocol or the port
* is a negative number other than -1 * is a negative number other than -1, or if the
* underlying stream handler implementation rejects,
* or is known to reject, the {@code URL}
* @see java.lang.System#getProperty(java.lang.String) * @see java.lang.System#getProperty(java.lang.String)
* @see java.net.URL#setURLStreamHandlerFactory( * @see java.net.URL#setURLStreamHandlerFactory(
* java.net.URLStreamHandlerFactory) * java.net.URLStreamHandlerFactory)
@ -380,7 +394,9 @@ public final class URL implements java.io.Serializable {
* @param protocol the name of the protocol to use. * @param protocol the name of the protocol to use.
* @param host the name of the host. * @param host the name of the host.
* @param file the file on the host. * @param file the file on the host.
* @throws MalformedURLException if an unknown protocol is specified. * @throws MalformedURLException if an unknown protocol is specified,
* or if the underlying stream handler implementation
* rejects, or is known to reject, the {@code URL}
* @see java.net.URL#URL(java.lang.String, java.lang.String, * @see java.net.URL#URL(java.lang.String, java.lang.String,
* int, java.lang.String) * int, java.lang.String)
*/ */
@ -415,7 +431,9 @@ public final class URL implements java.io.Serializable {
* @param file the file on the host * @param file the file on the host
* @param handler the stream handler for the URL. * @param handler the stream handler for the URL.
* @throws MalformedURLException if an unknown protocol or the port * @throws MalformedURLException if an unknown protocol or the port
* is a negative number other than -1 * is a negative number other than -1,
* or if the underlying stream handler implementation
* rejects, or is known to reject, the {@code URL}
* @throws SecurityException * @throws SecurityException
* if a security manager exists and its * if a security manager exists and its
* {@code checkPermission} method doesn't allow * {@code checkPermission} method doesn't allow
@ -510,7 +528,10 @@ public final class URL implements java.io.Serializable {
* @throws MalformedURLException if no protocol is specified, or an * @throws MalformedURLException if no protocol is specified, or an
* unknown protocol is found, or {@code spec} is {@code null}, * unknown protocol is found, or {@code spec} is {@code null},
* or the parsed URL fails to comply with the specific syntax * or the parsed URL fails to comply with the specific syntax
* of the associated protocol. * of the associated protocol, or the
* underlying stream handler's {@linkplain
* URLStreamHandler#parseURL parseURL method} throws
* {@code IllegalArgumentException}
* @see java.net.URL#URL(java.net.URL, java.lang.String) * @see java.net.URL#URL(java.net.URL, java.lang.String)
*/ */
public URL(String spec) throws MalformedURLException { public URL(String spec) throws MalformedURLException {
@ -522,7 +543,7 @@ public final class URL implements java.io.Serializable {
* *
* The new URL is created from the given context URL and the spec * The new URL is created from the given context URL and the spec
* argument as described in * argument as described in
* RFC2396 &quot;Uniform Resource Identifiers : Generic * Syntax&quot; : * RFC2396 &quot;Uniform Resource Identifiers : Generic Syntax&quot; :
* <blockquote><pre> * <blockquote><pre>
* &lt;scheme&gt;://&lt;authority&gt;&lt;path&gt;?&lt;query&gt;#&lt;fragment&gt; * &lt;scheme&gt;://&lt;authority&gt;&lt;path&gt;?&lt;query&gt;#&lt;fragment&gt;
* </pre></blockquote> * </pre></blockquote>
@ -554,12 +575,19 @@ public final class URL implements java.io.Serializable {
* <p> * <p>
* For a more detailed description of URL parsing, refer to RFC2396. * For a more detailed description of URL parsing, refer to RFC2396.
* *
* @implSpec Parsing the URL includes calling the {@link
* URLStreamHandler#parseURL(URL, String, int, int) parseURL} method on the
* selected handler.
*
* @param context the context in which to parse the specification. * @param context the context in which to parse the specification.
* @param spec the {@code String} to parse as a URL. * @param spec the {@code String} to parse as a URL.
* @throws MalformedURLException if no protocol is specified, or an * @throws MalformedURLException if no protocol is specified, or an
* unknown protocol is found, or {@code spec} is {@code null}, * unknown protocol is found, or {@code spec} is {@code null},
* or the parsed URL fails to comply with the specific syntax * or the parsed URL fails to comply with the specific syntax
* of the associated protocol. * of the associated protocol, or the
* underlying stream handler's {@linkplain
* URLStreamHandler#parseURL parseURL method} throws
* {@code IllegalArgumentException}
* @see java.net.URL#URL(java.lang.String, java.lang.String, * @see java.net.URL#URL(java.lang.String, java.lang.String,
* int, java.lang.String) * int, java.lang.String)
* @see java.net.URLStreamHandler * @see java.net.URLStreamHandler
@ -575,13 +603,20 @@ public final class URL implements java.io.Serializable {
* within a specified context. If the handler is null, the parsing * within a specified context. If the handler is null, the parsing
* occurs as with the two argument constructor. * occurs as with the two argument constructor.
* *
* @implSpec Parsing the URL includes calling the {@link
* URLStreamHandler#parseURL(URL, String, int, int) parseURL} method on the
* selected handler.
*
* @param context the context in which to parse the specification. * @param context the context in which to parse the specification.
* @param spec the {@code String} to parse as a URL. * @param spec the {@code String} to parse as a URL.
* @param handler the stream handler for the URL. * @param handler the stream handler for the URL.
* @throws MalformedURLException if no protocol is specified, or an * @throws MalformedURLException if no protocol is specified, or an
* unknown protocol is found, or {@code spec} is {@code null}, * unknown protocol is found, or {@code spec} is {@code null},
* or the parsed URL fails to comply with the specific syntax * or the parsed URL fails to comply with the specific syntax
* of the associated protocol. * of the associated protocol, or the
* underlying stream handler's {@linkplain
* URLStreamHandler#parseURL(URL, String, int, int)
* parseURL method} throws {@code IllegalArgumentException}
* @throws SecurityException * @throws SecurityException
* if a security manager exists and its * if a security manager exists and its
* {@code checkPermission} method doesn't allow * {@code checkPermission} method doesn't allow

10
src/java.base/share/classes/java/net/URLStreamHandler.java
View File

@ -129,6 +129,10 @@ public abstract class URLStreamHandler {
* end of the string or the position of the * end of the string or the position of the
* "{@code #}" character, if present. All information * "{@code #}" character, if present. All information
* after the sharp sign indicates an anchor. * after the sharp sign indicates an anchor.
* @throws IllegalArgumentException if the implementation of the protocol
* handler rejects any of the given parameters
* @throws NullPointerException if {@code u} is {@code null},
* or if {@code start < limit} and {@code spec} is {@code null}
*/ */
protected void parseURL(URL u, String spec, int start, int limit) { protected void parseURL(URL u, String spec, int start, int limit) {
// These fields may receive context content if this was relative URL // These fields may receive context content if this was relative URL
@ -497,6 +501,9 @@ public abstract class URLStreamHandler {
* @param ref the reference. * @param ref the reference.
* @throws SecurityException if the protocol handler of the URL is * @throws SecurityException if the protocol handler of the URL is
* different from this one * different from this one
* @throws IllegalArgumentException if the implementation of the protocol
* handler rejects any of the given parameters
* @throws NullPointerException if {@code u} is {@code null}
* @since 1.3 * @since 1.3
*/ */
protected void setURL(URL u, String protocol, String host, int port, protected void setURL(URL u, String protocol, String host, int port,
@ -539,6 +546,9 @@ public abstract class URLStreamHandler {
* @param ref the reference. * @param ref the reference.
* @throws SecurityException if the protocol handler of the URL is * @throws SecurityException if the protocol handler of the URL is
* different from this one * different from this one
* @throws IllegalArgumentException if the implementation of the protocol
* handler rejects any of the given parameters
* @throws NullPointerException if {@code u} is {@code null}
* @deprecated Use setURL(URL, String, String, int, String, String, String, * @deprecated Use setURL(URL, String, String, int, String, String, String,
* String); * String);
*/ */