Add javadoc

Author: arturobernalg

httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/H2OverH2TunnelSupport.java

@@ -62,6 +62,18 @@ public final class H2OverH2TunnelSupport {
     private H2OverH2TunnelSupport() {
     }
 
+    /**
+     * Establishes a CONNECT tunnel and returns the resulting {@link ProtocolIOSession}
+     * via the callback. The tunnel session supports optional TLS upgrade.
+     *
+     * @param proxySession   the HTTP/2 session to the proxy
+     * @param target         the target endpoint for the CONNECT request authority
+     * @param connectTimeout timeout for the CONNECT handshake
+     * @param secure         whether to upgrade the tunnel to TLS after establishment
+     * @param tlsStrategy    TLS strategy for the upgrade (required when {@code secure} is true)
+     * @param callback       completion callback receiving the tunnel session
+     * @since 5.7
+     */
     public static void establish(
             final IOSession proxySession,
             final NamedEndpoint target,
@@ -72,6 +84,19 @@ public static void establish(
         establishInternal(proxySession, target, connectTimeout, secure, tlsStrategy, null, null, callback);
     }
 
+    /**
+     * Establishes a CONNECT tunnel with a request interceptor for injecting
+     * headers (e.g. proxy authentication) into the CONNECT request.
+     *
+     * @param proxySession               the HTTP/2 session to the proxy
+     * @param target                     the target endpoint for the CONNECT request authority
+     * @param connectTimeout             timeout for the CONNECT handshake
+     * @param secure                     whether to upgrade the tunnel to TLS after establishment
+     * @param tlsStrategy                TLS strategy for the upgrade (required when {@code secure} is true)
+     * @param connectRequestInterceptor  interceptor applied to the CONNECT request before sending
+     * @param callback                   completion callback receiving the tunnel session
+     * @since 5.7
+     */
     public static void establish(
             final IOSession proxySession,
             final NamedEndpoint target,
@@ -83,6 +108,20 @@ public static void establish(
         establishInternal(proxySession, target, connectTimeout, secure, tlsStrategy, connectRequestInterceptor, null, callback);
     }
 
+    /**
+     * Establishes a CONNECT tunnel and starts a protocol handler inside it.
+     * The protocol starter factory creates an {@link org.apache.hc.core5.reactor.IOEventHandler}
+     * that is connected to the tunnel session immediately after establishment.
+     *
+     * @param proxySession    the HTTP/2 session to the proxy
+     * @param target          the target endpoint for the CONNECT request authority
+     * @param connectTimeout  timeout for the CONNECT handshake
+     * @param secure          whether to upgrade the tunnel to TLS after establishment
+     * @param tlsStrategy     TLS strategy for the upgrade (required when {@code secure} is true)
+     * @param protocolStarter factory for the protocol handler to run inside the tunnel
+     * @param callback        completion callback receiving the tunnel session
+     * @since 5.7
+     */
     public static void establish(
             final IOSession proxySession,
             final NamedEndpoint target,
@@ -94,6 +133,21 @@ public static void establish(
         establish(proxySession, target, connectTimeout, secure, tlsStrategy, null, protocolStarter, callback);
     }
 
+    /**
+     * Establishes a CONNECT tunnel with both a request interceptor and a protocol starter.
+     * This is the most general overload combining proxy authentication support with
+     * automatic protocol initialization inside the tunnel.
+     *
+     * @param proxySession               the HTTP/2 session to the proxy
+     * @param target                     the target endpoint for the CONNECT request authority
+     * @param connectTimeout             timeout for the CONNECT handshake
+     * @param secure                     whether to upgrade the tunnel to TLS after establishment
+     * @param tlsStrategy                TLS strategy for the upgrade (required when {@code secure} is true)
+     * @param connectRequestInterceptor  interceptor applied to the CONNECT request before sending
+     * @param protocolStarter            factory for the protocol handler to run inside the tunnel
+     * @param callback                   completion callback receiving the tunnel session
+     * @since 5.7
+     */
     public static void establish(
             final IOSession proxySession,
             final NamedEndpoint target,

httpclient5/src/main/java/org/apache/hc/client5/http/impl/async/TunnelRefusedException.java

@@ -44,15 +44,33 @@ public final class TunnelRefusedException extends HttpException {
 
     private final HttpResponse response;
 
+    /**
+     * Creates a new exception from the proxy response that refused the tunnel.
+     *
+     * @param response the non-2xx CONNECT response from the proxy
+     * @since 5.7
+     */
     public TunnelRefusedException(final HttpResponse response) {
         super("Tunnel refused: " + new StatusLine(Args.notNull(response, "Response")));
         this.response = copy(response);
     }
 
+    /**
+     * Returns a defensive copy of the proxy response that refused the tunnel.
+     *
+     * @return the proxy response
+     * @since 5.7
+     */
     public HttpResponse getResponse() {
         return response;
     }
 
+    /**
+     * Returns the HTTP status code of the proxy response.
+     *
+     * @return the status code (e.g. 407 for proxy authentication required)
+     * @since 5.7
+     */
     public int getStatusCode() {
         return response.getCode();
     }