Loading images from a server is an error-prone process. The server can be down, the user can be on a slow mobile connection, or completely lose Internet connection. By default, Glide has some timeouts set for you to balance between waiting long enough for the image to be loaded and showing an error early enough for the user.

Unfortunately, Glide's default network stack does not allow a customization of the default timeout values. In this tutorial, you'll combine the knowledge from integrating a custom OkHttp network stack and how to customize OkHttp's timeout settings. At the end of this tutorial, you'll be able to configure Glide's network timeout behavior to the specific needs of your app.

Glide Series Overview

Integrating Custom OkHttp Instance

To customize Glide's network timeout behavior, we'll use a custom instance of OkHttp. If OkHttp isn't part of your Gradle dependencies yet, add it to the build.gradle:

dependencies {  
    // Glide, and other dependencies
    // ...

    // new: OkHttp, if you don't have it yet
    implementation 'com.squareup.okhttp3:okhttp:3.12.0'
}

Next, you need to configure Glide to use OkHttp as a network stack. You can follow our unsafe OkHttp tutorial if you're interested in the details on how this works.

If you know how to use OkHttp as a network client, you can create a new GlideModule:

@GlideModule
public class CustomTimeOutOkHttpGlideModule extends LibraryGlideModule {

    @Override
    public void registerComponents(Context context, Glide glide, Registry registry) {
        OkHttpClient.Builder builder = new OkHttpClient.Builder();

        // customize connection timeouts here
        // ...

        OkHttpClient okHttpClient = builder.build();

        registry.replace(GlideUrl.class, InputStream.class,
                new OkHttpUrlLoader.Factory(okHttpClient));
    }

}

As you know, the @GlideModule annotation makes sure that Glide will read this configuration class. In the registerComponents method, you can create an instance of OkHttp via the builder. On the builder, you'll customize the timeouts. Finally, you'll set the custom OkHttp instance as the network stack with the registry.replace() method.

Customizing Timeouts

So far, you've set a custom OkHttp instance as Glide's network stack. This was the preparation, because you've not actually customized the timeouts yet. Let's get started on that now!

By default, OkHttp uses the following timeouts:

• Connection timeout: 10 seconds
• Read timeout: 10 seconds
• Write timeout: 10 seconds

We'll explain what these mean in detail in a later section.

How to Configure Timeout Settings via OkHttp

As already mentioned, the customization of network connection timeouts with Glide can't be done directly. Instead, you have to configure OkHttp as a network layer to customize the connection timeouts:

@GlideModule
public class CustomTimeOutOkHttpGlideModule extends LibraryGlideModule {

    @Override
    public void registerComponents(Context context, Glide glide, Registry registry) {
        OkHttpClient.Builder builder = new OkHttpClient.Builder();

        builder
                .connectTimeout(15, TimeUnit.SECONDS)
                .readTimeout(20, TimeUnit.SECONDS);

        OkHttpClient okHttpClient = builder.build();

        registry.replace(GlideUrl.class, InputStream.class,
                new OkHttpUrlLoader.Factory(okHttpClient));
    }

}

The code above sets the connection timeout to 15 seconds, the read timeout to 20 seconds, and leaves the write timeout to the default of 10 seconds. As you can see above, you don't have to change all three at the same time and can modify whatever subset you want to modify. Let's look at each timeout in more detail.

Connection Timeout

The connection timeout is likely the most interesting timeout. It's the time that lasts from starting the request to a completed TCP handshake with the server. In other words, if OkHttp couldn't establish a connection to the server within the set connection timeout limit, it'll count the request as failed. Glide will then trigger the error callback (e.g., display the error placeholder).

For example, increasing the default timeout of ten seconds to a higher value could make sense, if you know your users are in conditions with a slow Internet connection.

Read Timeout

The read timeout starts to pay attention once the connection is established and then watches how fast (or slow) every byte gets transferred. If the time between two bytes gets larger than the read timeout, it'll count the request as failed.

But be beware, the counter resets after every incoming byte! Thus, if your response has 120 bytes and it takes five seconds between each byte, the read timeout will not be triggered and the response will take ten minutes to be completed.

Again, this is not only limited to the server. Slow read times can be caused by the Internet connection as well.

Write Timeout

Finally, the write timeout is the opposite direction of the read timeout. It checks how fast you can send bytes to the server. Of course, it also gets reset after every successful byte. However, if sending a single byte takes longer than the configured write timeout limit, OkHttp will count the request as failed.

The write timeout should not be that interesting for Glide's use cases. The connection and the read timeout are the two settings you should customize, for example with the used values of 15 and 20 seconds from this tutorial.

Summary

In this tutorial you've learned how you can change Glide's network stack to a custom OkHttp instance. Furthermore, you've learned what kind of network timeouts OkHttp offers. You've also seen what they actually mean and how you can customize those timeout values.

Do you have further questions on this topic or about Glide in general? Let us know on Twitter @futurestud_io or leave a comment below.

Enjoy coding & make it rock!