HERE Android SDK Developer's Guide

MapLoader

The class MapLoader is a member of com.here.android.mpa.odml .

Class Summary

public final class MapLoader

extends java.lang.Object

Facilitates the use of offline map data.

[For complete information, see the section Class Details]

Nested Class Summary

Table 1. Nested Classes in MapLoader
Nested Classes

public static abstract interface MapLoader.Listener

Represents a listener interface for receiving notifications from the MapLoader.

public static abstract interface MapLoader.MapPackageAtCoordinateListener

Represents a listener interface with a callback which gets invoked upon package retrieval.

public static final enumeration MapLoader.ResultCode

Represents values describing the status of a MapLoader operation.

Method Summary

Table 2. Methods in MapLoader
Methods

public void addListener (Listener listener)

Adds a MapLoader.Listener for the MapLoader .

public void addMapPackageAtCoordinateListener (MapPackageAtCoordinateListener listener)

Adds a MapLoader.MapPackageAtCoordinateListener for the MapLoader .

public boolean cancelCurrentOperation ()

Cancels the current MapLoader operation.

public boolean checkForMapDataUpdate ()

Checks for the availability of an updated version of map data.

public static MapLoader getInstance ()

Gets the MapLoader shared instance.

public boolean getMapPackageAtCoordinate (GeoCoordinate coordinate)

This method will try to find a map package based on a map location.

public boolean getMapPackages ()

Returns the list of available MapPackage hierarchies.

public boolean installMapPackages (List packageIdList)

Installs the MapPackage hierarchies whose IDs are contained within the specified List of Integer objects.

public boolean performMapDataUpdate ()

Updates the version of map data if an update is available.

public void removeListener (Listener listener)

Removes a MapLoader.Listener for the MapLoader .

public void removeMapPackageAtCoordinateListener (MapPackageAtCoordinateListener listener)

Removes a MapLoader.MapPackageAtCoordinateListener for the MapLoader .

public boolean uninstallMapPackages (List packageIdList)

Uninstalls the MapPackage hierarchies whose IDs are contained within the specified List of Integer objects.

Class Details

Facilitates the use of offline map data.

MapLoader is a singleton which must be obtained by calling getInstance(). Method calls are asynchronous, returning results by way of the MapLoader.Listener interface.

All operations of a MapLoader are mutually exclusive. If, for example, method XYZ is called before the callback for method ABC has returned a result, method XYZ will return false to indicate that the MapLoader is busy with another operation.

MapLoader requires an internet connection to perform operations. If a MapLoader operation is attempted when no internet connection is available, NO_CONNECTIVITY will be returned.

Incremental Updates

MapLoader exposes the ability to update the version of the map and provide the user with the freshest map data available. The map version applies not only to map data pre-installed using the MapLoader , but also to data which are retrieved dynamically by browsing the map in areas where map data has not been pre-installed.

The map version is consistent for all map data, downloaded or not, across the entire system. It is not possible to have some data from one map version and other data from another map version concurrent in the database. It is important, therefore, to keep the map version of the system up to date, which fortunately does not require re-downloading everything. Only incremental changes need to be downloaded, making typical updates small and quick. Map version updating is exposed through the checkForMapDataUpdate() and performMapDataUpdate() methods.

Method Details

public void addListener (Listener listener)

Adds a MapLoader.Listener for the MapLoader .

Parameters:

  • listener

    A MapLoader.Listener for returning results from MapLoader operations

public void addMapPackageAtCoordinateListener (MapPackageAtCoordinateListener listener)

Adds a MapLoader.MapPackageAtCoordinateListener for the MapLoader .

Parameters:

  • listener

    A MapLoader.MapPackageAtCoordinateListener for returning results from MapLoader operations

public boolean cancelCurrentOperation ()

Cancels the current MapLoader operation.

Note: cancellation is deemed complete once the onComplete callback for the current operation has been made. If false is returned from this method, no callback will be made.

Returns:

True if the request has been made successfully (an operation was requested to cancel), false if there is no ongoing MapLoader operation to cancel.

public boolean checkForMapDataUpdate ()

Checks for the availability of an updated version of map data. The result is obtained by way of the MapLoader.Listener.onCheckForUpdateComplete(boolean, String, String, ResultCode) callback.

For more information about updating map data versions, refer to the Incremental Updates section of the detailed description for this interface.

Returns:

True if the request has been made successfully, false if the MapLoader is busy processing another request

public static MapLoader getInstance ()

Gets the MapLoader shared instance.

Returns:

The shared MapLoader

public boolean getMapPackageAtCoordinate (GeoCoordinate coordinate)

This method will try to find a map package based on a map location. If it can be identified, the smallest package containing the point is returned. For some input coordinates a larger package will be returned, but it should never be higher than country level (i.e. continental packages will not be returned).

Parameters:

  • coordinate

    The coordinates used to locate the package.

Returns:

True if the request has been made successfully, false if the MapLoader is busy processing another request or given coordinate was not valid.

public boolean getMapPackages ()

Returns the list of available MapPackage hierarchies. The list of available packages is returned in the MapLoader.Listener.onGetMapPackagesComplete(MapPackage, ResultCode) callback.

Note: the returned list of MapPackage hierarchies only represents a snapshot of the current map data state. State information is not updated dynamically for a MapPackage instance, so any operation which modifies the map data (install/uninstall/update) will invalidate pre-existing MapPackage instances.

Returns:

True if the request has been made successfully, false if the MapLoader is busy processing another request

public boolean installMapPackages (List packageIdList)

Installs the MapPackage hierarchies whose IDs are contained within the specified List of Integer objects.

Notes on installing map packages:

  • When installation starts, a summary of package sizes can be obtained through the onInstallationSize(long, long) callback.
  • During installation, progress can be monitored via onProgress(int) callbacks.
  • When installation is complete, notification will be sent by way of the onInstallMapPackagesComplete(MapPackage, ResultCode) callback.
  • If device connectivity is lost during installation, installation will halt and resume once connectivity is restored. No callback will be produced until installation has finished.

Parameters:

  • packageIdList

    A List of MapPackage IDs to install (if an invalid ID value is contained within the list, or the list is empty, or null is passed, INVALID_PARAMETERS will be returned in the callback)

Returns:

True if the request has been made successfully, false if the MapLoader is busy processing another request

See also:

getId()

public boolean performMapDataUpdate ()

Updates the version of map data if an update is available. An application might check first for available updates by calling checkForMapDataUpdate().

Notes on updating map data:

  • When the update starts, a summary of the update's size can be obtained through the onInstallationSize(long, long) callback.
  • During the update, progress can be monitored via onProgress(int) callbacks.
  • When the update is complete, notification will be sent by way of the onPerformMapDataUpdateComplete(MapPackage, ResultCode) callback.
  • If device connectivity is lost while updating, updating will halt and resume once connectivity is restored. No callback will be produced until updating has finished.

For more information about updating map data versions, refer to the Incremental Updates section of the detailed description for this interface.

Returns:

True if the request has been made successfully, false if the MapLoader is busy processing another request

public void removeListener (Listener listener)

Removes a MapLoader.Listener for the MapLoader .

Parameters:

  • listener

    A MapLoader.Listener to be removed

public void removeMapPackageAtCoordinateListener (MapPackageAtCoordinateListener listener)

Removes a MapLoader.MapPackageAtCoordinateListener for the MapLoader .

Parameters:

  • listener

    A MapLoader.MapPackageAtCoordinateListener to be removed

public boolean uninstallMapPackages (List packageIdList)

Uninstalls the MapPackage hierarchies whose IDs are contained within the specified List of Integer objects.

Notes on uninstalling map packages:

Parameters:

  • packageIdList

    A List of MapPackage IDs to uninstall (if an invalid ID value is contained within the list, or the list is empty, or null is passed, INVALID_PARAMETERS will be returned in the callback)

Returns:

True if the request has been made successfully, false if the MapLoader is busy processing another request

See also:

getId()

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.