RFR: 8169495: Add a method to set an Authenticator on a HttpURLConnection.

[Daniel Fuchs]

Hi,

Please find below a patch for:

https://bugs.openjdk.java.net/browse/JDK-8169495
8169495: Add a method to set an Authenticator on a HttpURLConnection.

webrev:
http://cr.openjdk.java.net/~dfuchs/webrev_8169495/webrev.00

The public API changes are in java.net.HttpURLConnection and
java.net.Authenticator. For backward compatibility reason the
new HttpURLConnection::setAuthenticator method is not abstract,
but is instead implemented to throw UOE unless overridden.

Again for compatibility reasons, if no authenticator is explicitly
supplied to the connection then the behavior is unchanged: the
default authenticator will be invoked, if needed, at the time
credentials are requested through the HTTP protocol.

Here is the description of the new HttpURLConnection::setAuthenticator 
method:

      /**
+     * Supplies an {@link java.net.Authenticator Authenticator} to be used
+     * when authentication is requested through the HTTP protocol for
+     * this {@code HttpURLConnection}.
+     * If no authenticator is supplied, the
+     * {@linkplain Authenticator#setDefault(java.net.Authenticator) default
+     * authenticator} will be used.
+     *
+     * @implNote The default behavior of this method is to throw
+     *           {@link UnsupportedOperationException}. Concrete
+     *           implementations of {@code HttpURLConnection}
+     *           which support supplying an {@code Authenticator} for a
+     *           specific {@code HttpURLConnection} instance should
+     *           override this method to implement a different behavior.
+     *
+     * @implSpec Depending on authentication schemes, an implementation
+     *           may or may not need to use the provided authenticator
+     *           to obtain a password. For instance, an implementation that
+     *           relies on third-party security libraries may still 
invoke the
+     *           default authenticator if these libraries are configured
+     *           to do so.
+     *           Likewise, an implementation that supports transparent
+     *           NTLM authentication may let the system attempt
+     *           to connect using the system user credentials first,
+     *           before invoking the provided authenticator.
+     *           <br>
+     *           However, if an authenticator is specifically provided,
+     *           then the underlying connection may only be reused for
+     *           {@code HttpURLConnection} instances which share the same
+     *           {@code Authenticator} instance, and authentication 
information,
+     *           if cached, may only be reused for an {@code 
HttpURLConnection}
+     *           sharing that same {@code Authenticator}.
+     *
+     * @param auth The {@code Authenticator} that should be used by this
+     *           {@code HttpURLConnection}.
+     *
+     * @throws  UnsupportedOperationException if setting an 
Authenticator is
+     *          not supported by the underlying implementation.
+     * @throws  IllegalStateException if URLConnection is already 
connected.
+     * @throws  NullPointerException if the supplied {@code auth} is 
{@code null}.
+     * @since 9
+     */
+    public void setAuthenticator(Authenticator auth) {
+        throw new UnsupportedOperationException("Supplying an 
authenticator"
+                    + " is not supported by " + this.getClass());
+    }


best regards,

-- daniel