From a9eff454e4e193affcd814e26cd252649a0db3de Mon Sep 17 00:00:00 2001 From: Vinay Gera Date: Fri, 2 Feb 2024 09:43:34 -0800 Subject: [PATCH] Add Azure Core Http Netty javadoc (#38016) --- .../core/http/netty/NettyAsyncHttpClient.java | 32 +++++-- .../netty/NettyAsyncHttpClientBuilder.java | 45 ++++++++- .../netty/NettyAsyncHttpClientProvider.java | 8 +- .../azure/core/http/netty/package-info.java | 92 ++++++++++++++++++- 4 files changed, 163 insertions(+), 14 deletions(-) diff --git a/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClient.java b/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClient.java index 69a1cff6bbf59..2e672c9db4409 100644 --- a/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClient.java +++ b/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. + *

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.

* - * @see HttpClient + *

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.

+ * + *

Sample: Construct NettyAsyncHttpClient with Default Configuration

+ * + *

The following code sample demonstrates the creation of a Netty HttpClient that uses port 80 and has no proxy.

+ * + * + * 
+ * HttpClient client = new NettyAsyncHttpClientBuilder()
+ *     .port(8080)
+ *     .wiretap(true)
+ *     .build();
+ *
+ * + * + *

For more ways to instantiate NettyAsyncHttpClient, refer to {@link NettyAsyncHttpClientBuilder}.

+ * + * @see com.azure.core.http.netty * @see NettyAsyncHttpClientBuilder + * @see HttpClient */ class NettyAsyncHttpClient implements HttpClient { private static final ClientLogger LOGGER = new ClientLogger(NettyAsyncHttpClient.class); diff --git a/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClientBuilder.java b/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClientBuilder.java index 80f46130e32e9..b6242831e4cb1 100644 --- a/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClientBuilder.java +++ b/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. + *

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.

* *

Building a new HttpClient instance

* @@ -62,7 +62,44 @@ * * * + *

Building a new HttpClient instance using http proxy.

+ * + *

Configuring the Netty client with a proxy is relevant when your application needs to communicate with Azure + * services through a proxy server.

+ * + * + * 
+ * HttpClient client = new NettyAsyncHttpClientBuilder()
+ *     .port(8080)
+ *     .wiretap(true)
+ *     .build();
+ *
+ * + * + *

Building a new HttpClient instance with HTTP/2 Support.

+ * + * + * 
+ * HttpClient client = new NettyAsyncHttpClientBuilder()
+ *     .port(8080)
+ *     .wiretap(true)
+ *     .build();
+ *
+ * + * + *

It is also possible to create a Netty HttpClient that only supports HTTP/2.

+ * + * + * 
+ * // Constructs an HttpClient that only supports HTTP/2.
+ * HttpClient client = new NettyAsyncHttpClientBuilder(reactor.netty.http.client.HttpClient.create()
+ *     .protocol(HttpProtocol.H2))
+ *     .build();
+ *
+ * + * * @see HttpClient + * @see NettyAsyncHttpClient */ public class NettyAsyncHttpClientBuilder { private static final long MINIMUM_TIMEOUT = TimeUnit.MILLISECONDS.toMillis(1); diff --git a/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClientProvider.java b/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClientProvider.java index 8e1a570e1dea0..c9b1e2ca32128 100644 --- a/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/NettyAsyncHttpClientProvider.java +++ b/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. + *

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.

+ * + * @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 = diff --git a/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/package-info.java b/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/package-info.java index 5bfbe324584b9..ce32d9773dac1 100644 --- a/sdk/core/azure-core-http-netty/src/main/java/com/azure/core/http/netty/package-info.java +++ b/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. + *

+ * Azure Core Http Netty 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 + * conceptual documentation.

+ * + *

Sample: Construct NettyAsyncHttpClient with Default Configuration

+ * + *

The following code sample demonstrates the creation of a Netty HttpClient that uses port 80 and has no proxy.

+ * + * + * 
+ * HttpClient client = new NettyAsyncHttpClientBuilder().build();
+ *
+ * + * + *
+ * + *

Using NettyAsyncHttpClient with Http Proxy

+ * + *

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 + * conceptual documentation.

+ * + *

The following code sample demonstrates the creation of a Netty HttpClient that is using a proxy.

+ * + * + * 
+ * HttpClient client = new NettyAsyncHttpClientBuilder()
+ *     .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("<proxy-host>", 8888)))
+ *     .build();
+ *
+ * + * + *
+ * + *

Using NettyAsyncHttpClient with HTTP/2 Support

+ * + *

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.

+ * + * + * 
+ * // Constructs an HttpClient that supports both HTTP/1.1 and HTTP/2 with HTTP/2 being the preferred protocol.
+ * HttpClient client = new NettyAsyncHttpClientBuilder(reactor.netty.http.client.HttpClient.create()
+ *     .protocol(HttpProtocol.HTTP11, HttpProtocol.H2))
+ *     .build();
+ *
+ * + * + *

It is also possible to create a Netty HttpClient that only supports HTTP/2.

+ * + * + * 
+ * // Constructs an HttpClient that only supports HTTP/2.
+ * HttpClient client = new NettyAsyncHttpClientBuilder(reactor.netty.http.client.HttpClient.create()
+ *     .protocol(HttpProtocol.H2))
+ *     .build();
+ *
+ * + * + *
+ * + *

Using NettyAsyncHttpClient with Custom Max Chunk Size

+ * + *

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.

+ * + *

The following code sample demonstrates the creation of a Netty HttpClient that uses a custom max chunk size.

+ * + * + * 
+ * // Constructs an HttpClient with a modified max chunk size.
+ * // Max chunk size modifies the maximum size of ByteBufs returned by Netty (later converted to ByteBuffer).
+ * // Changing the chunk size can positively impact performance of APIs such as Storage's download to file methods
+ * // provided in azure-storage-blob, azure-storage-file-datalake, and azure-storage-file-shares (32KB - 64KB have
+ * // shown the most consistent improvement).
+ * HttpClient httpClient = new NettyAsyncHttpClientBuilder(reactor.netty.http.client.HttpClient.create()
+ *     .httpResponseDecoder(httpResponseDecoderSpec -> httpResponseDecoderSpec.maxChunkSize(64 * 1024)))
+ *     .build();
+ *
+ * + * + * @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;