2. Tutorials
  3. Retrofit 2 — How to Download Files from Server

Retrofit 2 — How to Download Files from Server

In this blog post of our Retrofit launch sequence we'll show you one of the most requested topics: how to download files. We'll give you all the insight and snippets you need to use Retrofit to download everything, from tiny .png's to large .zip files.

If this is your first Retrofit post on futurestud.io, feel free to browse our other Retrofit posts:

Retrofit Series Overview

  1. Getting Started and Creating an Android Client
  2. Basics of API Description
  3. Creating a Sustainable Android Client
  4. URL Handling, Resolution and Parsing
  5. How to Change API Base Url at Runtime
  6. Multiple Server Environments (Develop, Staging, Production)
  7. Share OkHttp Client and Converters between Retrofit Instances
  8. Upgrade Guide from 1.9
  9. Beyond Android: Retrofit for Java Projects
  10. How to use OkHttp 3 with Retrofit 1
  1. Synchronous and Asynchronous Requests
  2. Send Objects in Request Body
  3. Add Custom Request Header
  4. Manage Request Headers in OkHttp Interceptor
  5. Dynamic Request Headers with @HeaderMap
  6. Multiple Query Parameters of Same Name
  7. Optional Query Parameters
  8. Send Data Form-Urlencoded
  9. Send Data Form-Urlencoded Using FieldMap
  10. How to Add Query Parameters to Every Request
  11. Add Multiple Query Parameter With QueryMap
  12. How to Use Dynamic Urls for Requests
  13. Constant, Default and Logic Values for POST and PUT Requests
  14. Cancel Requests
  15. Reuse and Analyze Requests
  16. Optional Path Parameters
  17. How to Send Plain Text Request Body
  18. Customize Network Timeouts
  19. How to Trust Unsafe SSL certificates (Self-signed, Expired)
  20. Dynamic Endpoint-Dependent Interceptor Actions
  21. How to Update Objects on the Server (PUT vs. PATCH)
  22. How to Delete Objects on the Server
  1. Ignore Response Payload with Call<Void>
  2. Receive Plain-String Responses
  3. Crawl HTML Responses with jspoon (Wikipedia Example)
  4. Loading Data into RecyclerView and CardView
  1. Introduction to (Multiple) Converters
  2. Adding & Customizing the Gson Converter
  3. Implementing Custom Converters
  4. How to Integrate XML Converter
  5. Access Mapped Objects and Raw Response Payload
  6. Supporting JSON and XML Responses Concurrently
  7. Handling of Empty Server Responses with Custom Converter
  8. Send JSON Requests and Receive XML Responses (or vice versa)
  9. Unwrapping Envelope Responses with Custom Converter
  10. Wrapping Requests in Envelope with Custom Converter
  11. Define a Custom Response Converter
  1. Simple Error Handling
  2. Error Handling for Synchronous Requests
  3. Catch Server Errors Globally with Response Interceptor
  4. How to Detect Network and Conversion Errors in onFailure
  1. Log Requests and Responses
  2. Enable Logging for Development Builds Only
  3. Log Network Traffic with Stetho and Chrome Developer Tools
  4. Using the Log Level to Debug Requests
  5. Analyze Network Traffic with Android Studio Profiler
  6. Debug and Compare Requests with RequestBin
  1. Introduction to Call Adapters
  2. Custom Call Adapter to Separate OnResponse Callback
  3. How to Integrate RxJava 1.x Call Adapter
  4. How to Integrate RxJava 2.x Call Adapter
  5. How to Integrate Guava Call Adapter
  6. Custom Call Adapter to Separate Network and Gson Errors
  1. Pagination Using Query Parameter
  2. Pagination Using Link Header and Dynamic Urls (Like GitHub)
  3. Pagination Using Range Header Fields (Like Heroku)
  1. Basic Authentication on Android
  2. Token Authentication on Android
  3. OAuth on Android
  4. Hawk Authentication on Android
  5. How to Refresh an Access Token
  1. Activate Response Caching (Etag, Last-Modified)
  2. Check Response Origin (Network, Cache, or Both)
  3. Force Server Cache Support with Response Interceptor
  4. Support App Offline Mode by Accessing Response Caches
  5. Analyze Cache Files
  1. Basics of Mocking Server Responses
  2. Customizing Network Behavior of Mocked Server Responses
  3. Mock APIs with JsonServer
  1. Callbacks
  2. Annotations
  3. Fluent Interface with Builders

How to Specify the Retrofit Request

If you're reading this and you haven't written code for any Retrofit requests yet, please check our previous blog posts to get started. For all you Retrofit experts: the request declaration for downloading files looks almost like any other request:

// option 1: a resource relative to your base URL
@GET("/resource/example.zip")
Call<ResponseBody> downloadFileWithFixedUrl();

// option 2: using a dynamic URL
@GET
Call<ResponseBody> downloadFileWithDynamicUrlSync(@Url String fileUrl);

If the file you want to download is a static resource (always at the same spot on the server) and on the server your base URL refers to, you can use option 1. As you can see, it looks like a regular Retrofit 2 request declaration. Please note, that we're specifying ResponseBody as return type. You should not use anything else here, otherwise Retrofit will try to parse and convert it, which doesn't make sense when you're downloading a file.

The second option is new to Retrofit 2. You can now easily pass a dynamic value as full URL to the request call. This can be especially helpful when downloading files, which are dependent of a parameter, user or time. You can build the URL during runtime and request the exact file without any hacks. If you haven't worked with dynamic URLs yet, feel free to head over to our blog post for that topic: dynamic urls in Retrofit 2

Pick what kind of option is useful to you and move on to the next section.

How to Call the Request

After declaring our request, we need to actually call it:

FileDownloadService downloadService = ServiceGenerator.create(FileDownloadService.class);

Call<ResponseBody> call = downloadService.downloadFileWithDynamicUrlSync(fileUrl);

call.enqueue(new Callback<ResponseBody>() {  
    @Override
    public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {
        if (response.isSuccess()) {
            Log.d(TAG, "server contacted and has file");

            boolean writtenToDisk = writeResponseBodyToDisk(response.body());

            Log.d(TAG, "file download was a success? " + writtenToDisk);
        } else {
            Log.d(TAG, "server contact failed");
        }
    }

    @Override
    public void onFailure(Call<ResponseBody> call, Throwable t) {
        Log.e(TAG, "error");
    }
});

If you're confused by the ServiceGenerator.create(), head over to our first blog post to get started. Once we've created the service, we'll make the request just like any other Retrofit call!

There is just one thing left, which currently hides behind the function writeResponseBodyToDisk(): writing the file to the disk!

How to Save the File

The writeResponseBodyToDisk() method takes the ResponseBody object and reads and writes the byte values of it to the disk. The code looks much more difficult than it actually is:

private boolean writeResponseBodyToDisk(ResponseBody body) {  
    try {
        // todo change the file location/name according to your needs
        File futureStudioIconFile = new File(getExternalFilesDir(null) + File.separator + "Future Studio Icon.png");

        InputStream inputStream = null;
        OutputStream outputStream = null;

        try {
            byte[] fileReader = new byte[4096];

            long fileSize = body.contentLength();
            long fileSizeDownloaded = 0;

            inputStream = body.byteStream();
            outputStream = new FileOutputStream(futureStudioIconFile);

            while (true) {
                int read = inputStream.read(fileReader);

                if (read == -1) {
                    break;
                }

                outputStream.write(fileReader, 0, read);

                fileSizeDownloaded += read;

                Log.d(TAG, "file download: " + fileSizeDownloaded + " of " + fileSize);
            }

            outputStream.flush();

            return true;
        } catch (IOException e) {
            return false;
        } finally {
            if (inputStream != null) {
                inputStream.close();
            }

            if (outputStream != null) {
                outputStream.close();
            }
        }
    } catch (IOException e) {
        return false;
    }
}

Most of it is just regular Java I/O boilerplate. You might need to adjust the first line on where and with what name your file is being saved. When you have done that, you're ready to download files with Retrofit!

But we're not completely ready for all files yet. There is one major issue: by default, Retrofit puts the entire server response into memory before processing the result. This works fine for some JSON or XML responses, but large files can easily cause Out-of-Memory-Errors.

If your app needs to download even slightly larger files, we strongly recommend reading the next section.

Beware with Large Files: Use @Streaming!

If you’re downloading a large file, Retrofit would try to move the entire file into memory. In order to avoid that, we've to add a special annotation to the request declaration:

@Streaming
@GET
Call<ResponseBody> downloadFileWithDynamicUrlAsync(@Url String fileUrl);

The @Streaming declaration doesn't mean you're watching a Netflix file. It means that instead of moving the entire file into memory, it'll pass along the bytes right away. But be careful, if you're adding the @Streaming declaration and continue to use the code above, Android will trigger a android.os.NetworkOnMainThreadException.

Thus, the final step is to wrap the call into a separate thread, for example with a lovely ASyncTask:

final FileDownloadService downloadService =  
        ServiceGenerator.createService(FileDownloadService.class);

Call<ResponseBody> call = downloadService.downloadFileWithDynamicUrlSync(fileUrl);  
call.enqueue(new Callback<ResponseBody>() {  
    @Override
    public void onResponse(Call<ResponseBody> call, final Response<ResponseBody> response) {
        if (response.isSuccessful()) {
            Log.d(TAG, "server contacted and has file");

            new AsyncTask<Void, Void, Void>() {
                @Override
                protected Void doInBackground(Void... voids) {
                    boolean writtenToDisk = writeResponseBodyToDisk(FileDownloadActivity.this, response.body(), null);

                    Log.d(TAG, "file download was a success? " + writtenToDisk);
                    return null;
                }
            }.execute();
        }
        else {
            Log.d(TAG, "server contact failed");
        }
    }

    @Override
    public void onFailure(Call<ResponseBody> call, Throwable t) {
        Log.e(TAG, "error");
    }
});

You can still use the same writeResponseBodyToDisk() method. If you remember the @Streaming declaration and this snippet, you can download even large files with Retrofit efficiently.

Next: Download Files with Progress Updates

If you download files in the foreground and they are not small, you might want to inform the user on your actions. Ideally, you would display progress updates how much you've downloaded already. We've another tutorial on how to download files with progress updates.

Summary

In this tutorial you've seen how to download files with Retrofit efficiently. This is everything you need to know to download files with Retrofit.

If you've any questions, let us know in the comments or on twitter.

Norman Peitek

android & node.js dev

https://twitter.com/peitek

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous