Download a Binary File Using OkHttp

1. Overview

This tutorial will give a practical example of how to download a binary file using the OkHttp library.

2. Maven Dependencies

We’ll start by adding the base library okhttp dependency:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>5.0.0-alpha.12</version>
</dependency>

Then, if we want to write an integration test for the module implemented with the OkHttp library, we can use the mockwebserver library. This library has the tools to mock a server and its responses:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>mockwebserver</artifactId>
    <version>5.0.0-alpha.12</version>
    <scope>test</scope>
</dependency>

3. Requesting a Binary File

We’ll first implement a class that receives as a parameter a URL from where to download the file and creates and executes an HTTP request for that URL.

To make the class testable, we’ll inject the OkHttpClient and the writer in the constructor:

public class BinaryFileDownloader implements AutoCloseable {

    private final OkHttpClient client;
    private final BinaryFileWriter writer;

    public BinaryFileDownloader(OkHttpClient client, BinaryFileWriter writer) {
        this.client = client;
        this.writer = writer;
    }
}

Next, we’ll implement the method that downloads the file from the URL:

public long download(String url) throws IOException {
    Request request = new Request.Builder().url(url).build();
    Response response = client.newCall(request).execute();
    ResponseBody responseBody = response.body();
    if (responseBody == null) {
        throw new IllegalStateException("Response doesn't contain a file");
    }
    double length = Double.parseDouble(Objects.requireNonNull(response.header(CONTENT_LENGTH, "1")));
    return writer.write(responseBody.byteStream(), length);
}

The process of downloading the file has four steps. Create the request using the URL. Execute the request and receive a response. Get the body of the response, or fail if it’s null. Write the bytes of the body of the response to a file.

4. Writing the Response to a Local File

To write the received bytes from the response to a local file, we’ll implement a BinaryFileWriter class which takes as an input an InputStream and an OutputStream and copies the contents from the InputStream to the OutputStream.

The OutputStream will be injected into the constructor so that the class can be testable:

public class BinaryFileWriter implements AutoCloseable {

    private final OutputStream outputStream;

    public BinaryFileWriter(OutputStream outputStream) {
        this.outputStream = outputStream;
    }
}

We’ll now implement the method that copies the contents from the InputStream to the OutputStream. The method first wraps the InputStream with a BufferedInputStream so that we can read more bytes at once. Then we prepare a data buffer in which we temporarily store the bytes from the InputStream.

Finally, we’ll write the buffered data to the OutputStream. We do this as long as the InputStream has data to be read:

public long write(InputStream inputStream) throws IOException {
    try (BufferedInputStream input = new BufferedInputStream(inputStream)) {
        byte[] dataBuffer = new byte[CHUNK_SIZE];
        int readBytes;
        long totalBytes = 0;
        while ((readBytes = input.read(dataBuffer)) != -1) {
            totalBytes += readBytes;
            outputStream.write(dataBuffer, 0, readBytes);
        }
        return totalBytes;
    }
}

5. Getting the File Download Progress

In some cases, we might want to tell the user the progress of a file download.

We’ll first need to create a functional interface:

public interface ProgressCallback {
    void onProgress(double progress);
}

Then, we’ll use it in the BinaryFileWriter class. This will give us at every step the total bytes that the downloader wrote so far.

First, we’ll add the ProgressCallback as a field to the writer class. Then, we’ll update the write method to receive as a parameter the length of the response. This will help us calculate the progress.

Then, we’ll call the onProgress method with the calculated progress from the totalBytes written so far and the length:

public class BinaryFileWriter implements AutoCloseable {
    private final ProgressCallback progressCallback;
    public long write(InputStream inputStream, double length) {
        //...
        progressCallback.onProgress(totalBytes / length * 100.0);
    }
}

Finally, we’ll update the BinaryFileDownloader class to call the write method with the total response length. We’ll get the response length from the Content-Length header, then pass it to the write method:

public class BinaryFileDownloader {
    public long download(String url) {
        double length = getResponseLength(response);
        return write(responseBody, length);
    }
    private double getResponseLength(Response response) {
        return Double.parseDouble(Objects.requireNonNull(response.header(CONTENT_LENGTH, "1")));
    }
}

6. Conclusion

In this article, we implemented a simple yet practical example of downloading a binary file from a URL using the OkHttp library.