Overview

Cache management

When a map is loaded and viewed on a device, the tiles are placed in the device's ambient cache. The ambient cache stores tiles that have already been visited by an end user so that the next time the user returns, the map loads nearly instantaneously. The map loads quickly because the device doesn't have to communicate with a server to request and receive information to render the map.

The Maps SDK for Android has several different methods for managing the device cache. These methods can modify the ambient cache, offline cache, or the entire database that houses the offline and ambient cache.

Cache specificity
The cache manangement methods operate at the map tile level, rather than at the map resource level. For example, the methods do not delete specific LatLngBounds, map layers, or GeoJSON Features from the cache.

There are three options for implementing any of the following cache management methods. You can build a user interface for the end user, a cloud notification system, or a remote configuration system. The option you choose will depend in part on whether you want end users to trigger the changes to the cache.

If end users are going to trigger these methods, then build an interface that users can interact with. This could be an option to clear the cache in an app's Settings page or a button near the Mapbox map.

If end users are not going to trigger these methods, then set up a backend cloud-based server to send instructions to the device to manipulate the cache. One option is using a notification system such as Firebase Cloud Messaging, Amazon’s Simple Notification Service, SendBird, OneSignal, or Urban Airship.

The other backend cloud option is setting up a remote configuration system, also known as feature flagging. Firebase's remote configuration system is a popular choice for Android developers. Other systems that manage A/B testing and feature flagging include Apptimize and LaunchDarkly. The remote configuration system will determine how and when a device should call a cache management method at runtime.

Management methods

invalidateAmbientCache()

Forces a revalidation of the tiles in the ambient cache and downloads a fresh version of the tiles from the tile server. This is the recommend method for clearing the cache. This is the most efficient method because tiles in the ambient cache are re-downloaded to remove outdated data from a device. It does not erase resources from the ambient cache or delete the database, which can be computationally expensive operations that may carry unintended side effects.

Note: Ambient cache tiles that overlap with offline regions will not be affected by this call.

OfflineManager fileSource = OfflineManager.getInstance(this);
fileSource.invalidateAmbientCache(new OfflineManager.FileSourceCallback() {
@Override
public void onSuccess() {
}
@Override
public void onError(@NonNull String message) {
}
});

clearAmbientCache()

Erases resources from the ambient cache. This method clears the cache and decreases the amount of space that map resources take up on the device. However, this reduction in space is not permanent unless the size of the ambient cache is decreased (see setMaximumAmbientCacheSize()), because a device's ambient cache will fill up again as an end user uses the map. This method can be computationally expensive and may result in unintended side effects. We do not recommend this method unless you are sure it is necessary for your use case.

OfflineManager fileSource = OfflineManager.getInstance(this);
fileSource.clearAmbientCache(new OfflineManager.FileSourceCallback() {
@Override
public void onSuccess() {
}
@Override
public void onError(@NonNull String message) {
}
});

setMaximumAmbientCacheSize()

Sets the maximum size of the ambient cache in bytes. Disables the ambient cache if set to 0.

This method may be computationally expensive because it will erase resources from the ambient cache if its size is decreased.

Note that offline regions detract from the space available for ambient caching, but setMaximumAmbientCacheSize() does not block offline downloads. For example, if the maximum ambient cache size is 50 MB and 40 MB are already used by offline regions, the ambient cache size will be 10 MB.

OfflineManager fileSource = OfflineManager.getInstance(this);
long DESIRED_AMBIENT_CACHE_SIZE = 5000000;
fileSource.setMaximumAmbientCacheSize(DESIRED_AMBIENT_CACHE_SIZE, new OfflineManager.FileSourceCallback() {
@Override
public void onSuccess() {
}
@Override
public void onError(@NonNull String message) {
}
});

resetDatabase

Deletes the existing database that houses the ambient and offline cache, and reinitializes the database. This method may result in unintended side effects. We do not recommend this method unless you are sure it is necessary for your use case.

OfflineManager fileSource = OfflineManager.getInstance(this);
fileSource.resetDatabase(new OfflineManager.FileSourceCallback() {
@Override
public void onSuccess() {
}
@Override
public void onError(@NonNull String message) {
}
});
Was this page helpful?