com.mapbox.mapboxsdk.offline

Class OfflineManager

java.lang.Object

com.mapbox.mapboxsdk.offline.OfflineManager

@UiThread
public class OfflineManager
extends java.lang.Object

The offline manager is the main entry point for offline-related functionality.

It'll help you list and create offline regions.

See Also:

Offline Maps Information/

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	OfflineManager.CreateOfflineRegionCallback This callback receives an asynchronous response containing the newly created OfflineRegion in the database or an error message otherwise.
static interface	OfflineManager.FileSourceCallback This callback receives an asynchronous response indicating if an operation has succeeded or failed.
static interface	OfflineManager.ListOfflineRegionsCallback This callback receives an asynchronous response containing a list of all OfflineRegion in the database or an error message otherwise.
static interface	OfflineManager.MergeOfflineRegionsCallback This callback receives an asynchronous response containing a list of all OfflineRegion added to the database during the merge.
static interface	OfflineManager.PrefetchAmbientCacheCallback This callback receives an asynchronous response containing a the request ID of the prefetch ambient cache request.

Method Summary

Modifier and Type	Method and Description
void	cancelPrefetchAmbientCacheRequest(long requestId) Cancel the prefetch ambient cache request.
void	clearAmbientCache(OfflineManager.FileSourceCallback callback) Erase resources from the ambient cache, freeing storage space.
void	createOfflineRegion(OfflineRegionDefinition definition, byte[] metadata, OfflineManager.CreateOfflineRegionCallback callback) Creates an offline region in the database by downloading the resources needed to use the given region offline.
protected void	finalize()
static OfflineManager	getInstance(android.content.Context context) Get the single instance of offline manager.
void	invalidateAmbientCache(OfflineManager.FileSourceCallback callback) Forces re-validation of the ambient cache.
void	listOfflineRegions(OfflineManager.ListOfflineRegionsCallback callback) Retrieve all regions in the offline database.
void	mergeOfflineRegions(java.lang.String path, OfflineManager.MergeOfflineRegionsCallback callback) Merge offline regions from a secondary database into the main offline database.
void	packDatabase(OfflineManager.FileSourceCallback callback) Packs the existing database file into a minimal amount of disk space.
long	prefetchAmbientCache(CacheAreaDefinition definition, OfflineManager.PrefetchAmbientCacheCallback callback) Pre-fetch resources from network and populates the ambient cache.
void	putResourceWithUrl(java.lang.String url, byte[] data, long modified, long expires, java.lang.String etag, boolean mustRevalidate) Insert the provided resource into the ambient cache This method mimics the caching that would take place if the equivalent resource were requested in the process of map rendering.
void	resetDatabase(OfflineManager.FileSourceCallback callback) Delete existing database and re-initialize.
void	runPackDatabaseAutomatically(boolean autopack) Sets whether database file packing occurs automatically.
void	setMaximumAmbientCacheSize(long size, OfflineManager.FileSourceCallback callback) Sets the maximum size in bytes for the ambient cache.
void	setOfflineMapboxTileCountLimit(long limit) Sets the maximum number of Mapbox-hosted tiles that may be downloaded and stored on the current device.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static OfflineManager getInstance(@NonNull
                                         android.content.Context context)

Get the single instance of offline manager.

Parameters:

context - the context used to host the offline manager

Returns:

the single instance of offline manager

listOfflineRegions

public void listOfflineRegions(@NonNull
                               OfflineManager.ListOfflineRegionsCallback callback)

Retrieve all regions in the offline database.

The query will be executed asynchronously and the results passed to the given callback on the main thread.

Parameters:

callback - the callback to be invoked

mergeOfflineRegions

public void mergeOfflineRegions(@NonNull
                                java.lang.String path,
                                @NonNull
                                OfflineManager.MergeOfflineRegionsCallback callback)

Merge offline regions from a secondary database into the main offline database.

When the merge is completed, or fails, the OfflineManager.MergeOfflineRegionsCallback will be invoked on the main thread. The callback reference is strongly kept throughout the process, so it needs to be wrapped in a weak reference or released on the client side if necessary.

The secondary database may need to be upgraded to the latest schema. This is done in-place and requires write-access to the provided path. If the app's process doesn't have write-access to the provided path, the file will be copied to the temporary, internal directory for the duration of the merge.

Only resources and tiles that belong to a region will be copied over. Identical regions will be flattened into a single new region in the main database.

The operation will be aborted and OfflineManager.MergeOfflineRegionsCallback.onError(String) with an appropriate message will be invoked if the merge would result in the offline tile count limit being exceeded.

Merged regions may not be in a completed status if the secondary database does not contain all the tiles or resources required by the region definition.

Parameters:

path - secondary database writable path

callback - completion/error callback

resetDatabase

public void resetDatabase(@Nullable
                          OfflineManager.FileSourceCallback callback)

Delete existing database and re-initialize.

When the operation is complete or encounters an error, the given callback will be executed on the database thread; it is the responsibility of the SDK bindings to re-execute a user-provided callback on the main thread.

Parameters:

callback - the callback to be invoked when the database was reset or when the operation erred.

packDatabase

public void packDatabase(@Nullable
                         OfflineManager.FileSourceCallback callback)

Packs the existing database file into a minimal amount of disk space.

This operation has a performance impact as it will vacuum the database, forcing it to move pages on the filesystem.

When the operation is complete or encounters an error, the given callback will be executed on the database thread; it is the responsibility of the SDK bindings to re-execute a user-provided callback on the main thread.

Parameters:

callback - the callback to be invoked when the database was reset or when the operation erred.

invalidateAmbientCache

public void invalidateAmbientCache(@Nullable
                                   OfflineManager.FileSourceCallback callback)

Forces re-validation of the ambient cache.

Forces Mapbox GL Native to revalidate resources stored in the ambient cache with the tile server before using them, making sure they are the latest version. This is more efficient than cleaning the cache because if the resource is considered valid after the server lookup, it will not get downloaded again.

Resources overlapping with offline regions will not be affected by this call.

Parameters:

callback - the callback to be invoked when the ambient cache was invalidated or when the operation erred.

clearAmbientCache

public void clearAmbientCache(@Nullable
                              OfflineManager.FileSourceCallback callback)

Erase resources from the ambient cache, freeing storage space.

Erases the ambient cache, freeing resources. Note that this operation can be potentially slow if packing the database occurs automatically (runPackDatabaseAutomatically(boolean)).

Resources overlapping with offline regions will not be affected by this call.

Parameters:

callback - the callback to be invoked when the ambient cache was cleared or when the operation erred.

setMaximumAmbientCacheSize

public void setMaximumAmbientCacheSize(long size,
                                       @Nullable
                                       OfflineManager.FileSourceCallback callback)

Sets the maximum size in bytes for the ambient cache.

This call is potentially expensive because it will try to trim the data in case the database is larger than the size defined. The size of offline regions are not affected by this settings, but the ambient cache will always try to not exceed the maximum size defined, taking into account the current size for the offline regions.

Note that if you use the SDK's offline functionality, your ability to set the ambient cache size will be limited. Space that offline regions take up detract from the space available for ambient caching, and the ambient cache size does not block offline downloads. For example: if the maximum cache size is set to 50 MB and 40 MB are already used by offline regions, the ambient cache size will effectively be 10 MB.

Setting the size to 0 will disable the cache if there is no offline region on the database.

<[

This method should always be called at the start of an app, before setting the style and loading a map. Otherwise, the map will instantiate with the default cache size of 50 MB.

Parameters:

size - the maximum size of the ambient cache

callback - the callback to be invoked when the the maximum size has been set or when the operation erred.

createOfflineRegion

public void createOfflineRegion(@NonNull
                                OfflineRegionDefinition definition,
                                @NonNull
                                byte[] metadata,
                                @NonNull
                                OfflineManager.CreateOfflineRegionCallback callback)

Creates an offline region in the database by downloading the resources needed to use the given region offline.

As of version 8.3.0 of the Maps SDK for Android, offline tile requests are no longer exempt from billing on mobile. Developers are subject to separate Vector Tile or Raster Tile API pricing for offline use. See our pricing page for more information.

When the initial database queries have completed, the provided callback will be executed on the main thread.

Note that the resulting region will be in an inactive download state; to begin downloading resources, call `OfflineRegion.setDownloadState(DownloadState.STATE_ACTIVE)`, optionally registering an `OfflineRegionObserver` beforehand.

Parameters:

definition - the offline region definition

metadata - the metadata in bytes

callback - the callback to be invoked

prefetchAmbientCache

public long prefetchAmbientCache(@NonNull
                                 CacheAreaDefinition definition,
                                 @NonNull
                                 OfflineManager.PrefetchAmbientCacheCallback callback)

Pre-fetch resources from network and populates the ambient cache.

Parameters:

definition - the cache area definition

callback - the callback to be invoked

Returns:

request id of the prefetch ambient cache request

cancelPrefetchAmbientCacheRequest

public void cancelPrefetchAmbientCacheRequest(long requestId)

Cancel the prefetch ambient cache request.

Parameters:

requestId - the id of the prefetch ambient cache request

setOfflineMapboxTileCountLimit

public void setOfflineMapboxTileCountLimit(long limit)

Sets the maximum number of Mapbox-hosted tiles that may be downloaded and stored on the current device. By default, the limit is set to 6,000.

Once this limit is reached, OfflineRegion.OfflineRegionObserver.mapboxTileCountLimitExceeded(long) fires every additional attempt to download additional tiles until already downloaded tiles are removed by calling OfflineRegion.delete(OfflineRegion.OfflineRegionDeleteCallback).

Parameters:

limit - the maximum number of tiles allowed to be downloaded

runPackDatabaseAutomatically

public void runPackDatabaseAutomatically(boolean autopack)

Sets whether database file packing occurs automatically. By default, the automatic database file packing is enabled.

If packing is enabled, database file packing occurs automatically after an offline region is deleted by calling OfflineRegion.delete(OfflineRegion.OfflineRegionDeleteCallback) or the ambient cache is cleared by calling OfflineManager#clearAmbientCache().

If packing is disabled, disk space will not be freed after resources are removed unless OfflineManager#packDatabase() is explicitly called.

Parameters:

autopack - flag setting the automatic database file packing.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

putResourceWithUrl

public void putResourceWithUrl(java.lang.String url,
                               byte[] data,
                               long modified,
                               long expires,
                               java.lang.String etag,
                               boolean mustRevalidate)

Insert the provided resource into the ambient cache This method mimics the caching that would take place if the equivalent resource were requested in the process of map rendering. Use this method to pre-warm the cache with resources you know will be requested.

This call is asynchronous: the data may not be immediately available for in-progress requests, although subsequent requests should have access to the cached data.

Parameters:

url - The URL of the resource to insert

data - Response data to store for this resource. Data is expected to be uncompressed; internally, the cache will compress data as necessary.

modified - Optional "modified" response header, in seconds since 1970, or 0 if not set

expires - Optional "expires" response header, in seconds since 1970, or 0 if not set

etag - Optional "entity tag" response header

mustRevalidate - Indicates whether response can be used after it's stale