Summary

Add a new java.net.http.HttpResponse::connectionLabel method which returns an opaque connection identifier that users can leverage to associate a response with the connection it is carried on from. This is useful to determine whether two requests were carried on on the same connection or on different connections. This can be used to facilitate troubleshooting.

Problem

While troubleshooting an HttpClient-related problem, it is often desirable to figure out whether two request/responses were carried on on the same connection or on different connections. Currently there doesn't exist a public API to obtain this information on the client side.

Note that being able to identify the connection on which a request/response was carried on will also be useful in the context of the HTTP/3 protocol where server pushes can be shared by different stream on the same connection.

Solution

A new java.net.http.HttpResponse::connectionLabel method of return type Optional<String> is added. If present, the label uniquely identify the connection on which the request/response was carried on in the scope of the HttpClient instance.

Specification

src/java.net.http/share/classes/java/net/http/HttpResponse.java:

+    /**
+     * {@return if present, a label identifying the connection on which the
+     * response was received}
+     * <p>
+     * The format of the string is opaque, but the value is fixed and unique
+     * for any connection in the scope of the associated {@link HttpClient}
+     * instance.
+     *
+     * @implSpec
+     * The default implementation of this method returns
+     * {@link Optional#empty() Optional.empty()}.
+     *
+     * @implNote
+     * Instances of {@code HttpResponse} returned by the JDK built-in
+     * implementation of {@code HttpClient} always return a non-empty value.
+     *
+     * @since 25
+     */
+    default Optional<String> connectionLabel() {
+        return Optional.empty();
+    }