Navigation SDK is currently available only to select customers. Contact sales to learn more.

ExternalCache

public interface ExternalCache

Defines an interface for an external cache that can be used to lookup base map tiles and associated image resources (poi icons, road shields, etc.) when offline.

If an external cache is provided to the SDK via GoogleMap#setExternalCache the external cache is queried after the regular memory and on-disk caches.

The external cache is not expected to be pre-warmed, and may retrieve cache entries from disk, but should limit disk access to a minimum and aim to return the result as soon as possible. For example, by keeping an in-memory index to decide quickly if the requested data is available and then doing a single disk read to retrieve the resource if available.

The external cache implementation is responsible for expiring and refreshing the data it serves. The SDK may cache data retrieved from the external cache in it's memory cache for performance reasons, but such caching will be short-lived (on the order of hours).

Public Method Summary

abstract String
getApiOptions()
Returns the API options that this cache was built with.
abstract ResourceDescriptor
getResource(String url)
Retrieve an image resource from the external cache by its URL.
abstract TileDescriptor
getTile(int x, int y, int zoom)
Retrieves a base map tile from the cache by its coordinates and zoom level.

Public Methods

public abstract String getApiOptions ()

Returns the API options that this cache was built with. This can be used to determine if the external cache is compatible with API options being used to fetch new tiles.

Returns
  • API options defined in manifest with API_OPTIONS_METADATA_KEY, or null if not defined.

public abstract ResourceDescriptor getResource (String url)

Retrieve an image resource from the external cache by its URL. If no entry for the given URL exists, this method returns null.

The implementation must be thread safe. First, although the SDK synchronizes access to the external cache, the code still must protect against internal race conditions. Second, because this is a callback from an unknown thread, the code cannot call back into the SDK.

Although a fully qualified URL will be passed in by the SDK the implementation could strip the host part because it does not matter from which server the resource is loaded.

Parameters
url URL for the image resource to get
Returns
  • ResourceDescriptor with cached resource data.

public abstract TileDescriptor getTile (int x, int y, int zoom)

Retrieves a base map tile from the cache by its coordinates and zoom level. If no entry for the given coordinates exists, this method returns null.

The implementation must be thread safe. First, although the SDK synchronizes access to the external cache, the code still must protect against internal race conditions. Second, because this is a callback from an unknown thread, the code cannot call back into the SDK.

Parameters
x X-coordinate of tile
y Y-coordinate of tile
zoom Zoom level
Returns
  • TileDescriptor with cached tile header and tile data.