Summary

Document IllegalArgumentException and NullPointerException thrown by methods in URLStreamHandler, and improve the documentation of MalformedURLException thrown by URL constructors.

Problem

Some method in URLStreamHandler may throw an IllegalArgumentException, or NullPointerException where those exceptions are not documented in the method's API documentation.

An IllegalArgumentException is typically caught by the URL constructor that calls the method, and transformed into a MalformedURLException. In addition, some URL constructors may perform additional checks when specific protocols, or specific handler implementations, are detected. The @throws MalformedURLException clause of these constructor does not always make it clear that some additional implementation specific checks may be performed.

Solution

• In URLStreamHandler add an @throws IllegalArgumentException and an @throws NullPointerException clause to the methods of URLStreamHandler that may throw IllegalArgumentException or NullPointerException.
• In URL, clarify that an implementation of a specific protocol may cause any additional checks to be performed, possibly resulting in additional cases where MalformedURLException will be thrown. Make it clear that which additional checks are performed is implementation dependent.

Specification

In URLStreamHandler:

for the protected URLStreamHandler::parseURL method, add

+      * @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) {
          // These fields may receive context content if this was relative URL

for the two protected URLStreamHandler::setURL methods, add

+      * @throws IllegalArgumentException if the implementation of the protocol
+      *                    handler rejects any of the given parameters
+      * @throws NullPointerException if {@code u} is {@code null}

In URL, add a paragraph to the @apiNote in the class level documentation to clarify that an implementation may make additional checks that can result in MalformedURLException being thrown:

+  * <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.

For the constructors that take a spec string and call the handler's parseURL method, add the following clarification:

+      * @implSpec Parsing the URL includes calling the {@link
+      * URLStreamHandler#parseURL(URL, String, int, int) parseURL} method on the
+      * selected handler.
+      *

For the three constructors that directly or indirectly call the handler's parseURL method, extend the description of the @throws MalformedURLException clause with the following text:

       * @throws     MalformedURLException if [...]
       *               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}

In addition, extend the description of the @throws MalformedURLException clause in the other constructors, to say:

-      * @throws     MalformedURLException if [...]
+      * @throws     MalformedURLException if [...]
+      *                        or if the underlying stream handler implementation
+      *                        rejects, or is known to reject, the {@code URL}

The attached webrev contains docs-only changes and shows the full proposed API changes, in their context.