Summary
-------

Introduce an API on `java.net.http.HttpClient.Builder` interface to allow users to specify a particular local address to bind to.

Problem
-------
Applications use `java.net.http.HttpClient`, typically built using a `HttpClient.newBuilder()` to issue HTTP requests. Such requests internally create instance(s) of `java.nio.channels.SocketChannel` to communicate with the target server(s). The sockets of such `SocketChannel` instances currently bind to automatically assigned socket address. Applications do not have control over which address will be chosen to bind to on multi-homed systems. This enhancement proposes to allow applications to optionally choose which address to bind to.


Solution
--------
A new API is introduced on `HttpClient.Builder`:

           public interface Builder {
              ...
     
    +        /**
    +         * Binds the socket to this local address when creating
    +         * connections for sending requests.
    +         *
    +         * <p> If no local address is set or {@code null} is passed
    +         * to this method then sockets created by the
    +         * HTTP client will be bound to an automatically
    +         * assigned socket address.
    +         *
    +         * <p> Common usages of the {@code HttpClient} do not require
    +         * this method to be called. Setting a local address, through this
    +         * method, is only for advanced usages where users of the {@code HttpClient}
    +         * require specific control on which network interface gets used
    +         * for the HTTP communication. Callers of this method are expected to
    +         * be aware of the networking configurations of the system where the
    +         * {@code HttpClient} will be used and care should be taken to ensure the
    +         * correct {@code localAddr} is passed. Failure to do so can result in
    +         * requests sent through the {@code HttpClient} to fail.
    +         *
    +         * @implSpec The default implementation of this method throws
    +         * {@code UnsupportedOperationException}. {@code Builder}s obtained
    +         * through {@link HttpClient#newBuilder()} provide an implementation
    +         * of this method that allows setting the local address.
    +         *
    +         * @param localAddr The local address of the socket. Can be null.
    +         * @return this builder
    +         * @throws UnsupportedOperationException if this builder doesn't support
    +         *         configuring a local address or if the passed {@code localAddr}
    +         *         is not supported by this {@code HttpClient} implementation.
    +         * @since 19
    +         */
    +        default Builder localAddress(InetAddress localAddr) {
    +            throw new UnsupportedOperationException();
    +        }
    +
             /**
              * Returns a new {@link HttpClient} built from the current state of this
              * builder.
              *
    +         * @implSpec If the {@link #localAddress(InetAddress) local address} is
    +         * a non-null address and a security manager is installed, then
    +         * this method calls {@link SecurityManager#checkListen checkListen} to 
    +         * check that the caller has necessary permission to bind to that local address.
    +         *
              * @return a new {@code HttpClient}
              *
              * @throws UncheckedIOException may be thrown if underlying IO resources
              * required by the implementation cannot be allocated. For instance,
              * if the implementation requires a {@link Selector}, and opening
              * one fails due to {@linkplain Selector#open() lack of necessary resources}.
    +         * @throws SecurityException If a security manager has been installed and the
    +         *         security manager's {@link SecurityManager#checkListen checkListen}
    +         *         method disallows binding to the given address.
              */
             public HttpClient build();

Specification
-------------
See solution section also the auto-generated webrev for this enhancement, details the exact changes https://openjdk.github.io/cr/?repo=jdk&pr=6690&range=18#udiff-1-src/java.net.http/share/classes/java/net/http/HttpClient.java