Custom HTTP Clients

Introduction

Azure SDKs for Java offers the capability to plug-in your own custom networking layer to allow for handling of specialized scenarios or when you don't want to use Netty or OkHttp. Providing a custom HttpClient requires a few interfaces/classes to be implemented along with registering your implementation with Java's service provider interface.

Implementation Overview

Interfaces and Abstract Classes

The following interfaces and abstract classes will need to be implemented in your custom HTTP client.

• HttpClient handles sending request and receiving responses.
• HttpResponse contains response information and APIs to interact with it.
• HttpClientProvider handles creating instances of the HttpClient agnostic to the underlying implementation.

Target Version of Azure Core

A specific version of Azure Core will need to be targeted when implementing a custom HTTP client. This version should be based on which version of Azure Core is being used by the other Azure SDK client libraries your application is depending on, for example if you have a dependency on Azure Storage Blobs that uses Azure Core 1.2.0 you'll want your custom HTTP client to use that as it's dependency.

Service Provider Interface (SPI)

Once the custom HTTP client has been implemented it needs to be registered with Java's service provider interface. In the module that contains the custom HTTP client the resource folder will need the following.

src
|
+--main
   |
   +--java
   +--resources
      |
      +--META-INF.services
         |
         +--com.azure.core.http.HttpClientProvider

The only contents of com.azure.core.http.HttpClientProvider file should be the fully qualified name of the class that implements HttpClientProvider. For example, in the Netty implementation that is offered the implementing class is com.azure.core.http.netty.implementation.ReactorNettyClientProvider, so the only value in this file is com.azure.core.http.netty.implementation.ReactorNettyClientProvider.

Example

This is a high-level example of a custom HTTP client implementation built on top of org.apache.httpcomponents.httpclient and using Azure Core 1.2.0. This example hasn't be verified for correctness or scalability but serves as a general example of how to roll your own HTTP client.

ApacheHttpClient

package apachehttp;

import com.azure.core.http.HttpClient;
import com.azure.core.http.HttpHeaders;
import com.azure.core.http.HttpMethod;
import com.azure.core.http.HttpRequest;
import com.azure.core.http.HttpResponse;
import com.azure.core.util.FluxUtil;
import org.apache.http.client.methods.HttpEntityEnclosingRequestBase;
import org.apache.http.entity.ByteArrayEntity;
import org.apache.http.impl.client.HttpClientBuilder;
import reactor.core.publisher.Mono;

import java.io.IOException;
import java.net.URISyntaxException;
import java.net.URL;

public final class ApacheHttpClient implements HttpClient {
    private final org.apache.http.client.HttpClient httpClient;

    public ApacheHttpClient() {
        this.httpClient = HttpClientBuilder.create().build();
    }

    public Mono<HttpResponse> send(final HttpRequest azureRequest) {
        try {
            ApacheHttpRequest apacheRequest = new ApacheHttpRequest(azureRequest.getHttpMethod(), azureRequest.getUrl(),
                azureRequest.getHeaders());

            Mono<byte[]> bodyMono = (azureRequest.getBody() != null)
                ? FluxUtil.collectBytesInByteBufferStream(azureRequest.getBody())
                : Mono.just(new byte[0]);

            return bodyMono.flatMap(bodyBytes -> {
                apacheRequest.setEntity(new ByteArrayEntity(bodyBytes));
                try {
                    return Mono.just(new ApacheHttpResponse(azureRequest, httpClient.execute(apacheRequest)));
                } catch (IOException ex) {
                    return Mono.error(ex);
                }
            });
        } catch (URISyntaxException e) {
            return Mono.error(e);
        }
    }

    private static final class ApacheHttpRequest extends HttpEntityEnclosingRequestBase {
        private final String method;

        private ApacheHttpRequest(HttpMethod method, URL url, HttpHeaders headers) throws URISyntaxException {
            this.method = method.name();
            setURI(url.toURI());
            headers.stream().forEach(header -> addHeader(header.getName(), header.getValue()));
        }

        @Override
        public String getMethod() {
            return method;
        }
    }
}

ApacheHttpResponse

package apachehttp;

import com.azure.core.http.HttpHeaders;
import com.azure.core.http.HttpRequest;
import com.azure.core.http.HttpResponse;
import org.apache.http.HttpEntity;
import org.apache.http.util.EntityUtils;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.charset.Charset;
import java.util.Arrays;

final class ApacheHttpResponse extends HttpResponse {
    private final int statusCode;
    private final HttpHeaders headers;
    private final HttpEntity entity;

    protected ApacheHttpResponse(HttpRequest request, org.apache.http.HttpResponse apacheResponse) {
        super(request);
        this.statusCode = apacheResponse.getStatusLine().getStatusCode();
        this.headers = new HttpHeaders();
        Arrays.stream(apacheResponse.getAllHeaders())
            .forEach(header -> headers.put(header.getName(), header.getValue()));
        this.entity = apacheResponse.getEntity();
    }

    public int getStatusCode() {
        return statusCode;
    }

    public String getHeaderValue(String s) {
        return headers.getValue(s);
    }

    public HttpHeaders getHeaders() {
        return headers;
    }

    public Flux<ByteBuffer> getBody() {
        return getBodyAsByteArray().map(ByteBuffer::wrap).flux();
    }

    public Mono<byte[]> getBodyAsByteArray() {
        try {
            return Mono.just(EntityUtils.toByteArray(entity));
        } catch (IOException e) {
            return Mono.error(e);
        }
    }

    public Mono<String> getBodyAsString() {
        return getBodyAsByteArray().map(String::new);
    }

    public Mono<String> getBodyAsString(Charset charset) {
        return getBodyAsByteArray().map(bytes -> new String(bytes, charset));
    }
}

ApacheHttpClientProvider

package apachehttp;

import com.azure.core.http.HttpClient;
import com.azure.core.http.HttpClientProvider;

public final class ApacheHttpClientProvider implements HttpClientProvider {
    public HttpClient createInstance() {
        return new ApacheHttpClient();
    }
}

com.azure.core.http.HttpClientProvider

apachehttp.ApacheHttpClientProvider