com.here.android.mpa.common

Class MapEngine

java.lang.Object

com.here.android.mpa.common.MapEngine

public final class MapEngine
extends java.lang.Object

MapEngine manages all mapping resources and services provided in this SDK.

MapEngine must be initialized before any of the services can be used. For more information, see MapEngine.init(ApplicationContext, OnEngineInitListener).

Users can maintain reference count through the use of MapEngine.onPause() and MapEngine.onResume() thus control when to relinquish MapEngine services.

MapEngine also allows users to subscribe to data download notifications to provide extra information.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MapEngine.MapVariant Represents supported map variants.
static interface	MapEngine.OnMapDownloadListener Represents a listener to provide notification upon the start and completion of a data download event.

Method Summary

Modifier and Type	Method and Description
void	addMapDataDownloadListener(MapEngine.OnMapDownloadListener listener) Adds a OnMapDownloadListener to listen for map data download events.
static void	enableTrafficInOfflineMode(boolean enable) Allows to use online traffic when MapEngine is set to OFFLINE.
static MapEngine	getInstance() Returns the MapEngine singleton, if one has already been created.
java.lang.String	getMapApprovalCode(java.util.Locale locale) Gets map approval code for specific country.
java.lang.String	getProviderCopyrightStatement(java.util.Locale locale) Gets provider copyright statement for specific country.
int	getResourceReferenceCount() Get the current reference count of map resource usage for this application.
void	init(ApplicationContext context, OnEngineInitListener listener) Asynchronously initialize the MapEngine.
static boolean	isInitialized() Gets the initialization state of MapEngine.
static boolean	isOnlineEnabled() Gets the online configuration state of MapEngine.
void	onPause() Decrements the reference count of map resource usage.
void	onResume() Increments the reference count of map resource usage.
void	removeMapDataDownloadListener(MapEngine.OnMapDownloadListener listener) Removes an existing MapDataDownloadListener.
static void	setOnline(boolean online) Alter the data connectivity mode of the MapEngine.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static MapEngine getInstance()

Returns the MapEngine singleton, if one has already been created.

Once the MapEngine instance is available, it must be initialized through one of the following methods before it can be used:

• AndroidXMapFragment.init(OnEngineInitListener)
• AndroidXMapFragment.init(ApplicationContext, OnEngineInitListener)

Returns:

MapEngine instance

init

public void init(ApplicationContext context,
                 OnEngineInitListener listener)

Asynchronously initialize the MapEngine. MapEngine cannot be used until it has been initialized successfully.

This method is particularly useful for users of headless APIs as the MapEngine is being automatically initialized as part of the setup process of AndroidXMapFragments.

This method will initialize MapEngine with ApplicationContext to be used during initialization.

Users interested in SDK functions such as navigation without initializing a com.here.android.mpa.mapping.AndroidXMapFragment are responsible for manually calling MapEngine.onResume() or MapEngine.onPause() to put the MapEngine in an active state or inactive state, respectively.

Parameters:

context - ApplicationContext to be used during initialization.

listener - OnEngineInitListener to provide information when MapEngine initialization completes and if it has been successful.

See Also:

AndroidXMapFragment.init(OnEngineInitListener), AndroidXMapFragment.init(ApplicationContext, OnEngineInitListener), MapEngine.getResourceReferenceCount()

Note:

Users interested in SDK functions such as navigation without initializing a com.here.android.mpa.mapping.AndroidXMapFragment are responsible for manually calling MapEngine.onResume() or MapEngine.onPause() to put the MapEngine in an active state or inactive state, respectively. Users are also responsible for manually fetching map data using the MapLoader or the MapDataPrefetcher.

getResourceReferenceCount

public int getResourceReferenceCount()

Get the current reference count of map resource usage for this application. When this returns 0, it indicates that no reference to map resources is being held and the engine is paused. As a result, SDK functions will not work. When this returns 1 or greater, it is an indication that a reference to map resources is being held and the engine is active.

It is very important that an application holds a reference to map resources while in active operation and releases this reference when not in use (e.g. sent to the background). This method is a useful tool to use while developing an application. This value can be logged while testing to ensure that references to map resources are handled properly during the lifecycle of the app.

For users of AndroidXMapFragment class, map resource usage is handled automatically.

Returns:

The current reference count of map resource usage

onPause

public void onPause()

Decrements the reference count of map resource usage. When the count drops to 0 the engine will be paused. This should usually be called in an activity's onPause.

For users of AndroidXMapFragment class, it is not necessary to call MapEngine.onPause() as it is handled automatically.

onResume

public void onResume()

Increments the reference count of map resource usage. This will open all mapping resources if the reference count becomes 1. This should usually be called in an activity's onResume.

For users of AndroidXMapFragment class, it is not necessary to call MapEngine.onResume() as it is handled automatically.

addMapDataDownloadListener

public void addMapDataDownloadListener(MapEngine.OnMapDownloadListener listener)

Adds a OnMapDownloadListener to listen for map data download events.

Parameters:

listener - A OnMapDownloadListener to add to the MapEngine

See Also:

MapEngine.removeMapDataDownloadListener(OnMapDownloadListener)

removeMapDataDownloadListener

public void removeMapDataDownloadListener(MapEngine.OnMapDownloadListener listener)

Removes an existing MapDataDownloadListener.

Parameters:

listener - A MapDataDownloadListener to remove from the MapEngine

setOnline

public static void setOnline(boolean online)

Alter the data connectivity mode of the MapEngine.

Parameters:

online - Pass true to set MapEngine connectivity to ONLINE. If false, connectivity is OFFLINE.

If set to false then the HERE SDK will not access the network to download map data, perform searches, calculate routes or when providing any other service unless the service allows overriding this setting, e.g. see CoreRouter.Connectivity, Request.Connectivity, and CLE2Request.CLE2ConnectivityMode.

isOnlineEnabled

public static boolean isOnlineEnabled()

Gets the online configuration state of MapEngine.

If false is returned then the HERE SDK will not access the network to download map data, perform searches, calculate routes or when providing any other service unless the service allows overriding this setting, e.g. see CoreRouter.Connectivity, Request.Connectivity, and CLE2Request.CLE2ConnectivityMode.

Returns:

true if MapEngine is enabled to use network communications

enableTrafficInOfflineMode

public static void enableTrafficInOfflineMode(boolean enable)

Allows to use online traffic when MapEngine is set to OFFLINE.

Parameters:

enable - Pass true to set traffic connectivity to ONLINE. If false, traffic connectivity is OFFLINE.

Throws:

java.lang.IllegalStateException - If MapEngine connectivity mode is ONLINE.

Note:

MapEngine.setOnline(boolean) method resets traffic connectivity mode. Therefore this method must be called only after MapEngine.setOnline(boolean)., This method must be called only when MapEngine connectivity is set to OFFLINE. Otherwise IllegalStateException will be thrown.

isInitialized

public static boolean isInitialized()

Gets the initialization state of MapEngine.

Returns:

true if MapEngine is initialized and ready for service.

getMapApprovalCode

public java.lang.String getMapApprovalCode(java.util.Locale locale)

Gets map approval code for specific country.

Parameters:

locale - Locale with country code. To create Locale with country use new Locale(language, country) constructor, or use one of the predefined locales, e.g. Locale.ENGLISH.

Returns:

Map approval code or null if approval code is not required for provided country.

Throws:

java.lang.IllegalArgumentException - if provided locale.getCountry() is null or empty.

getProviderCopyrightStatement

public java.lang.String getProviderCopyrightStatement(java.util.Locale locale)

Gets provider copyright statement for specific country.

Parameters:

locale - Locale with country code. To create Locale with country use new Locale(language, country) constructor, or use one of the predefined locales, e.g. Locale.ENGLISH.

Returns:

provider copyright statement or null if there is no such statement.

Throws:

java.lang.IllegalArgumentException - if provided locale.getCountry() is null or empty.