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

[Chris Hegarty]

On 10/11/16 15:12, Daniel Fuchs wrote:
> 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.

Thank you Daniel. This addresses a long standing request to
have a per-instance Authenticator.

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

We exchanged a few mails off-line, and I am happy with what
is in the latest webrev.

-Chris.

> 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