Package com.here.sdk.maploader

Class MapUpdater

java.lang.Object
com.here.NativeBase
com.here.sdk.maploader.MapUpdater
public final class MapUpdater extends NativeBase

A class for updating regions previously downloaded using the MapDownloader. First, updates for the regions are downloaded. Once the download is complete, the update process begins, installing the new content. It is recommended to regularly call retrieveCatalogsUpdateInfo(com.here.sdk.maploader.CatalogsUpdateInfoCallback) to check for available updates for any downloaded regions.

If updates are available, regions can be updated asynchronously using updateCatalog(com.here.sdk.maploader.CatalogUpdateInfo, com.here.sdk.maploader.CatalogUpdateProgressListener). The MapUpdateProgressListener provides update progress for each region.

Incremental map updates are supported, by default: Instead of downloading an entire region, only the parts that have changed will be installed. This results in a faster update process. MapUpdater also aligns previously downloaded content with LayerConfiguration changes made via SDKOptions.

Note that patching (also called "incremental updates") is only supported for up to 8 versions. For example, if an update started with version x.y.0 then it will be supported till x.y.8 and stopped starting with x.y.9. Usually, OCM updates are released weekly. Incremental updates will stop after 2 months and a full update is performed instead.

In case of an error, the previous map data remains available for use. It is only replaced after new map data has been successfully downloaded. Regions that fail to update must be retried in a new call. Paused updates can be resumed later.

During the update process, MapUpdater internally retries failed downloads until a timeout occurs. If this happens, it is reported via MapUpdateProgressListener.

If the user cancels the update process during the update phase, it is ignored. The update phase begins after all content has been downloaded, then the HERE SDK installs and replaces the existing regions. Cancellation is only possible during the download phase, and a successful cancellation is indicated via MapUpdateProgressListener.onComplete(com.here.sdk.maploader.MapLoaderError).

Note that a MapLoaderError.NOT_READY occurs when the MapDownloader is used in parallel. In general, background updates are not supported explicitly, as the OS can abort background processes. In addition, the OfflineSearchEngine and the OfflineRoutingEngine cannot be used while a map update is in progress and it will be indicated by a MapLoaderError.

  • Method Details

    • fromEngineAsync

      public static void fromEngineAsync(@NonNull SDKNativeEngine sdkEngine, @NonNull MapUpdaterConstructionCallback mapUpdaterConstructionCallback)

      Gets a single instance of this class per provided SDKNativeEngine.

      Parameters:
      sdkEngine -

      An instance of the SDKNativeEngine

      mapUpdaterConstructionCallback -

      A callback that will receive the result of construction

    • getCurrentMapVersion

      @NonNull public MapVersionHandle getCurrentMapVersion() throws MapLoaderException

      Returns a handle that contains the map version of the already downloaded and installed regions. This information is only needed for debugging purposes.

      Returns:

      A handle to get the map version.

      Throws:
      MapLoaderException -

      Specifies reason, why current map version is not returned.

    • updateCatalog

      @NonNull public CatalogUpdateTask updateCatalog(@NonNull CatalogUpdateInfo catalogInfo, @NonNull CatalogUpdateProgressListener callback)

      Performs an asynchronous request for each catalog to update map data to the latest available version. This applies to all previously installed Region map data and any incomplete downloads in a pending state.

      If no regions are downloaded, this method updates only the map version. The map cache and persisted regions are always bound to the same map version.

      If no updates are available, CatalogsUpdateInfoCallback from retrieveCatalogsUpdateInfo(com.here.sdk.maploader.CatalogsUpdateInfoCallback) returns an empty list. In this case, MapUpdateProgressListener.onComplete(com.here.sdk.maploader.MapLoaderError) is called immediately.

      To check for available updates, use retrieveCatalogsUpdateInfo(com.here.sdk.maploader.CatalogsUpdateInfoCallback) to retrieve catalogs with newer versions. Individual catalogs can then be updated using this method. Ensure that the device has enough free disk space to perform a catalog update. Information about the required disk space is available in CatalogUpdateInfo.diskSizeInBytes.

      If there is not enough space to perform the catalog update with the default MapUpdater.MapUpdateVersionCommitPolicy.ON_COMPLETE, try using MapUpdater.MapUpdateVersionCommitPolicy.ON_FIRST_REGION. This option requires less space but follows a different strategy for handling errors during the map update.

      If indexing is enabled through OfflineSearchEngine.setIndexOptions, the index is rebuilt after the map is updated. The index helps OfflineSearchEngine provide better search results.

      Note: Indexing is a beta feature and may have bugs or unexpected behavior.

      Parameters:
      catalogInfo -

      catalog to update. CatalogUpdateInfo should be get from retrieveCatalogsUpdateInfo(com.here.sdk.maploader.CatalogsUpdateInfoCallback)

      callback -

      Callback which receives the result on the main thread.

      Returns:

      A handle that will be used to manipulate the execution of the task, for example, to cancel an ongoing request.

    • retrieveCatalogsUpdateInfo

      @NonNull public TaskHandle retrieveCatalogsUpdateInfo(@NonNull CatalogsUpdateInfoCallback callback)

      Retrieves information of all catalogs that have newer version available. This method can also be used to query catalog information like HRN, current installed version and newer available version on server. An empty list in CatalogsUpdateInfoCallback represent no map updates.

      Parameters:
      callback -

      Callback which receives the result on the main thread.

      Returns:

      A handle to cancel a pending operation.

    • setVersionCommitPolicy

      public void setVersionCommitPolicy(@NonNull MapUpdater.MapUpdateVersionCommitPolicy versionCommitPolicy)

      Sets the map update version policy. Defaults to MapUpdater.MapUpdateVersionCommitPolicy.ON_COMPLETE.

      Parameters:
      versionCommitPolicy -

      to choose from MapUpdater.MapUpdateVersionCommitPolicy

    • getTaskCount

      public long getTaskCount()

      Gets the number of concurrent tasks for downloading a map.

      A valid task count is between 1 to 64. When the value set is outside the valid range, then it is clamped to a valid range:

      • when passed in value is 0 or less, then task count is set to 1;
      • when passed in value is 65 or more, then task count is set to 64.
      Returns:

      The number of concurrent tasks for downloading a map.

    • setTaskCount

      public void setTaskCount(long value)

      Sets the number of concurrent tasks for downloading a map.

      A valid task count is between 1 to 64. When the value set is outside the valid range, then it is clamped to a valid range:

      • when passed in value is 0 or less, then task count is set to 1;
      • when passed in value is 65 or more, then task count is set to 64.
      Parameters:
      value -

      The number of concurrent tasks for downloading a map.

    • getUpdateStatistics

      @NonNull public UpdateStatistics getUpdateStatistics()

      Map update statistics for the ongoing session of the current application.

      In the event of binary updates, patches are downloaded and applied. This property helps to determine the success or failure rate of applied patches.

      Returns:

      Map update statistics for the current application session.