Add Azure Core Http Netty javadoc (#38016)

sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClient.java

@@ -7,7 +7,6 @@
 import com.azure.core.http.HttpHeader;
 import com.azure.core.http.HttpRequest;
 import com.azure.core.http.HttpResponse;
-import com.azure.core.http.ProxyOptions;
 import com.azure.core.http.netty.implementation.AzureNettyHttpClientContext;
 import com.azure.core.http.netty.implementation.NettyAsyncHttpBufferedResponse;
 import com.azure.core.http.netty.implementation.NettyAsyncHttpResponse;
@@ -26,7 +25,6 @@
 import com.azure.core.util.logging.ClientLogger;
 import io.netty.buffer.ByteBuf;
 import io.netty.buffer.Unpooled;
-import io.netty.channel.EventLoopGroup;
 import io.netty.handler.codec.http.HttpHeaders;
 import io.netty.handler.codec.http.HttpMethod;
 import io.netty.handler.proxy.HttpProxyHandler;
@@ -56,14 +54,32 @@
 import java.util.function.BiFunction;
 
 /**
- * This class provides a Netty-based implementation for the {@link HttpClient} interface. Creating an instance of this
- * class can be achieved by using the {@link NettyAsyncHttpClientBuilder} class, which offers Netty-specific API for
- * features such as {@link NettyAsyncHttpClientBuilder#eventLoopGroup(EventLoopGroup) thread pooling},
- * {@link NettyAsyncHttpClientBuilder#wiretap(boolean) wiretapping},
- * {@link NettyAsyncHttpClientBuilder#proxy(ProxyOptions) setProxy configuration}, and much more.
+ * <p>The NettyAsyncHttpClient class is an implementation of the {@link HttpClient} interface using the
+ * Reactor Netty library. This class is designed to handle HTTP requests and responses asynchronously, leveraging
+ * the non-blocking and backpressure-ready nature of Reactor Netty.</p>
  *
- * @see HttpClient
+ * <p>This class is typically instantiated using the {@link NettyAsyncHttpClientBuilder} class, which provides a
+ * fluent API for configuring various aspects of the HTTP client, such as the port, whether to enable wiretapping, and
+ * proxy configuration.</p>
+ *
+ * <p><strong>Sample: Construct NettyAsyncHttpClient with Default Configuration</strong></p>
+ *
+ * <p>The following code sample demonstrates the creation of a Netty HttpClient that uses port 80 and has no proxy.</p>
+ *
+ * <!-- src_embed com.azure.core.http.netty.instantiation-simple -->
+ * <pre>
+ * HttpClient client = new NettyAsyncHttpClientBuilder&#40;&#41;
+ *     .port&#40;8080&#41;
+ *     .wiretap&#40;true&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.netty.instantiation-simple -->
+ *
+ * <p>For more ways to instantiate NettyAsyncHttpClient, refer to {@link NettyAsyncHttpClientBuilder}.</p>
+ *
+ * @see com.azure.core.http.netty
  * @see NettyAsyncHttpClientBuilder
+ * @see HttpClient
  */
 class NettyAsyncHttpClient implements HttpClient {
     private static final ClientLogger LOGGER = new ClientLogger(NettyAsyncHttpClient.class);

sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClientBuilder.java

@@ -46,10 +46,10 @@
 import static com.azure.core.util.CoreUtils.getDefaultTimeoutFromEnvironment;
 
 /**
- * Builder class responsible for creating instances of {@link com.azure.core.http.HttpClient} backed by Reactor Netty.
- * Please be aware that client built from this builder can support synchronously and asynchronously call of sending
- * request. Use {@link com.azure.core.http.HttpClient#sendSync(HttpRequest, Context)} to send the provided request
- * synchronously with contextual information.
+ * <p>Builder class responsible for creating instances of {@link com.azure.core.http.HttpClient} backed by Reactor Netty.
+ * The client built from this builder can support sending requests synchronously and asynchronously.
+ * Use {@link com.azure.core.http.HttpClient#sendSync(HttpRequest, Context)} to send the provided request
+ * synchronously with contextual information.</p>
  *
  * <p><strong>Building a new HttpClient instance</strong></p>
  *
@@ -62,7 +62,44 @@
  * </pre>
  * <!-- end com.azure.core.http.netty.instantiation-simple -->
  *
+ * <p><strong>Building a new HttpClient instance using http proxy.</strong></p>
+ *
+ * <p>Configuring the Netty client with a proxy is relevant when your application needs to communicate with Azure
+ * services through a proxy server.</p>
+ *
+ * <!-- src_embed com.azure.core.http.netty.instantiation-simple -->
+ * <pre>
+ * HttpClient client = new NettyAsyncHttpClientBuilder&#40;&#41;
+ *     .port&#40;8080&#41;
+ *     .wiretap&#40;true&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.netty.instantiation-simple -->
+ *
+ * <p><strong>Building a new HttpClient instance with HTTP/2 Support.</strong></p>
+ *
+ * <!-- src_embed com.azure.core.http.netty.instantiation-simple -->
+ * <pre>
+ * HttpClient client = new NettyAsyncHttpClientBuilder&#40;&#41;
+ *     .port&#40;8080&#41;
+ *     .wiretap&#40;true&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.netty.instantiation-simple -->
+ *
+ * <p>It is also possible to create a Netty HttpClient that only supports HTTP/2.</p>
+ *
+ * <!-- src_embed readme-sample-useHttp2OnlyWithConfiguredNettyClient -->
+ * <pre>
+ * &#47;&#47; Constructs an HttpClient that only supports HTTP&#47;2.
+ * HttpClient client = new NettyAsyncHttpClientBuilder&#40;reactor.netty.http.client.HttpClient.create&#40;&#41;
+ *     .protocol&#40;HttpProtocol.H2&#41;&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-useHttp2OnlyWithConfiguredNettyClient  -->
+ *
  * @see HttpClient
+ * @see NettyAsyncHttpClient
  */
 public class NettyAsyncHttpClientBuilder {
     private static final long MINIMUM_TIMEOUT = TimeUnit.MILLISECONDS.toMillis(1);

sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClientProvider.java

@@ -11,7 +11,13 @@
 import reactor.netty.resources.ConnectionProvider;
 
 /**
- * An {@link HttpClientProvider} that provides an implementation of HttpClient based on Netty.
+ * <p>The NettyAsyncHttpClientProvider class is an implementation of the HttpClientProvider interface that provides
+ * an instance of HttpClient based on Netty. Instances are either shared or a newly created based
+ * on the configuration.</p>
+ *
+ * @see com.azure.core.http.netty
+ * @see NettyAsyncHttpClient
+ * @see HttpClient
  */
 public final class NettyAsyncHttpClientProvider implements HttpClientProvider {
     private static final boolean AZURE_ENABLE_HTTP_CLIENT_SHARING =

sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/package-info.java

@@ -2,6 +2,96 @@
 // Licensed under the MIT License.
 
 /**
- * Package containing the types for instantiating and using the Netty HTTP client.
+ * <p><a href="https://learn.microsoft.com/java/api/overview/azure/core-http-netty-readme?view=azure-java-stable">
+ * Azure Core Http Netty</a> client library is a plugin for the azure-core HTTP client API. It allows you to use Netty as
+ * the underlying HTTP client for communicating with Azure services. It is the default HTTP client used in all
+ * Azure SDK for Java libraries, but you can also replace it with other implementations such as OkHttp or
+ * the JDK 11 HttpClient. You can also configure various aspects of the Netty client, such as proxy, protocol, or
+ * chunk size. For more details refer to our
+ * <a href="https://learn.microsoft.com/azure/developer/java/sdk/http-client-pipeline#http-clients">conceptual documentation</a>.</p>
+ *
+ * <p><strong>Sample: Construct NettyAsyncHttpClient with Default Configuration</strong></p>
+ *
+ * <p>The following code sample demonstrates the creation of a Netty HttpClient that uses port 80 and has no proxy.</p>
+ *
+ * <!-- src_embed readme-sample-createBasicClient -->
+ * <pre>
+ * HttpClient client = new NettyAsyncHttpClientBuilder&#40;&#41;.build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-createBasicClient  -->
+ *
+ * <hr>
+ *
+ * <h2><strong>Using NettyAsyncHttpClient with Http Proxy</strong></h2>
+ *
+ * <p>Configuring the Netty client with a proxy in the context of Azure Java SDK is relevant when your application needs
+ * to communicate with Azure services through a proxy server. For more details refer to our
+ * <a href="https://learn.microsoft.com/azure/developer/java/sdk/proxying#http-proxy-configuration">conceptual documentation</a>.</p>
+ *
+ * <p>The following code sample demonstrates the creation of a Netty HttpClient that is using a proxy.</p>
+ *
+ * <!-- src_embed readme-sample-createProxyClient -->
+ * <pre>
+ * HttpClient client = new NettyAsyncHttpClientBuilder&#40;&#41;
+ *     .proxy&#40;new ProxyOptions&#40;ProxyOptions.Type.HTTP, new InetSocketAddress&#40;&quot;&lt;proxy-host&gt;&quot;, 8888&#41;&#41;&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-createProxyClient  -->
+ *
+ * <hr>
+ *
+ * <h2><strong>Using NettyAsyncHttpClient with HTTP/2 Support</strong></h2>
+ *
+ * <p>The following code sample demonstrates the creation of a Netty HttpClient that supports both the HTTP/1.1 and
+ * HTTP/2 protocols, with HTTP/2 being the preferred protocol.</p>
+ *
+ * <!-- src_embed readme-sample-useHttp2WithConfiguredNettyClient -->
+ * <pre>
+ * &#47;&#47; Constructs an HttpClient that supports both HTTP&#47;1.1 and HTTP&#47;2 with HTTP&#47;2 being the preferred protocol.
+ * HttpClient client = new NettyAsyncHttpClientBuilder&#40;reactor.netty.http.client.HttpClient.create&#40;&#41;
+ *     .protocol&#40;HttpProtocol.HTTP11, HttpProtocol.H2&#41;&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-useHttp2WithConfiguredNettyClient  -->
+ *
+ * <p>It is also possible to create a Netty HttpClient that only supports HTTP/2.</p>
+ *
+ * <!-- src_embed readme-sample-useHttp2OnlyWithConfiguredNettyClient -->
+ * <pre>
+ * &#47;&#47; Constructs an HttpClient that only supports HTTP&#47;2.
+ * HttpClient client = new NettyAsyncHttpClientBuilder&#40;reactor.netty.http.client.HttpClient.create&#40;&#41;
+ *     .protocol&#40;HttpProtocol.H2&#41;&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-useHttp2OnlyWithConfiguredNettyClient  -->
+ *
+ * <hr>
+ *
+ * <h2>Using NettyAsyncHttpClient with Custom Max Chunk Size</h2>
+ *
+ * <p>The adjustment of the max chunk size involves the modification of the maximum size of ByteBufs returned by Netty,
+ * subsequently converted to {@code ByteBuffer}. Altering the chunk size can yield positive performance effects, particularly
+ * notable in APIs like the download to file methods within Azure Storage libraries such as azure-storage-blob,
+ * azure-storage-file-datalake, and azure-storage-file-shares. Notably, improvements in performance have been
+ * consistently observed in the range of 32KB to 64KB.</p>
+ *
+ * <p>The following code sample demonstrates the creation of a Netty HttpClient that uses a custom max chunk size.</p>
+ *
+ * <!-- src_embed readme-sample-customMaxChunkSize -->
+ * <pre>
+ * &#47;&#47; Constructs an HttpClient with a modified max chunk size.
+ * &#47;&#47; Max chunk size modifies the maximum size of ByteBufs returned by Netty &#40;later converted to ByteBuffer&#41;.
+ * &#47;&#47; Changing the chunk size can positively impact performance of APIs such as Storage's download to file methods
+ * &#47;&#47; provided in azure-storage-blob, azure-storage-file-datalake, and azure-storage-file-shares &#40;32KB - 64KB have
+ * &#47;&#47; shown the most consistent improvement&#41;.
+ * HttpClient httpClient = new NettyAsyncHttpClientBuilder&#40;reactor.netty.http.client.HttpClient.create&#40;&#41;
+ *     .httpResponseDecoder&#40;httpResponseDecoderSpec -&gt; httpResponseDecoderSpec.maxChunkSize&#40;64 * 1024&#41;&#41;&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-customMaxChunkSize  -->
+ *
+ * @see com.azure.core.http.netty.NettyAsyncHttpClient
+ * @see com.azure.core.http.netty.NettyAsyncHttpClientBuilder
+ * @see reactor.netty.http.client.HttpClient
  */
 package com.azure.core.http.netty;