HERE Android SDK Developer's Guide

MapEngine

The class MapEngine is a member of com.here.android.mpa.common .

Class Summary

public final class MapEngine

extends java.lang.Object

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

[For complete information, see the section Class Details]

Nested Class Summary

Table 1. Nested Classes in MapEngine
Nested Classes

public static final enumeration MapEngine.MapVariant

Supported map variants.

public static abstract interface MapEngine.OnMapDownloadListener

Represents a listener to provide notification upon the start and completion of a data download event.

Method Summary

Table 2. Methods in MapEngine
Methods

public void addMapDataDownloadListener (OnMapDownloadListener listener)

Adds a OnMapDownloadListener to listen for map data download events.

public static MapEngine getInstance ()

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

public int getResourceReferenceCount ()

Get the current reference count of map resource usage for this application.

public void init (Context context, OnEngineInitListener listener)

Deprecated: As of SDK 3.4.

Asynchronously initialize the MapEngine .

public void init (Context context, MapVariant variant, OnEngineInitListener listener)

Deprecated: As of SDK 3.4.

Asynchronously initialize the MapEngine .

public void init (ApplicationContext context, OnEngineInitListener listener)

Asynchronously initialize the MapEngine .

public static boolean isInitialized ()

Gets the initialization state of MapEngine .

public static boolean isOnlineEnabled ()

Gets the online configuration state of MapEngine .

public void onPause ()

Decrements the reference count of map resource usage.

public void onResume ()

Increments the reference count of map resource usage.

public void removeMapDataDownloadListener (OnMapDownloadListener listener)

Removes an existing MapDataDownloadListener .

public static void setOnline (boolean online)

Alter the data connectivity mode of the MapEngine .

Class Details

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 init(Context, OnEngineInitListener).

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

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

Method Details

public void addMapDataDownloadListener (OnMapDownloadListener listener)

Adds a OnMapDownloadListener to listen for map data download events.

Parameters:

  • listener

    A OnMapDownloadListener to add to the MapEngine

See also:

removeMapDataDownloadListener(OnMapDownloadListener)

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:

Returns:

MapEngine instance

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 MapFragment and MapActivity classes, map resource usage is handled automatically.

Returns:

The current reference count of map resource usage

public void init (Context context, OnEngineInitListener listener)

Deprecated: As of SDK 3.4.

Use init(ApplicationContext, OnEngineInitListener) instead.

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 MapFragments.

This method will initialize MapEngine with GLOBAL map variant on first SDK usage and with stored map variant on sub-sequent usages.

Parameters:

  • context

    context to be used during initialization.

  • listener

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

See also:

init(OnEngineInitListener)

init(Context, OnEngineInitListener)

public void init (Context context, MapVariant variant, OnEngineInitListener listener)

Deprecated: As of SDK 3.4.

Use init(ApplicationContext, OnEngineInitListener) instead.

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 MapFragments.

This method can configure map variant which will be used by MapEngine. If initialization fails - OPERATION_NOT_ALLOWED will be reported. Currently following variants are supported: - GLOBAL - initialize MapEngine to use international map variant; - KOREA - initialize MapEngine to use Korean map variant; - null - initialize MapEngine to use stored map variant or international map variant for first run. This method is used to configure MapEngine to use certain map variant. If MapEngine was already configured and passed variant differs - error will be reported and initialization fails.

Parameters:

  • context

    context to be used during initialization.

  • variant

    map variant to use.

  • listener

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

See also:

init(OnEngineInitListener)

init(Context, OnEngineInitListener)

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 MapFragments.

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

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:

init(OnEngineInitListener)

init(ApplicationContext, OnEngineInitListener)

public static boolean isInitialized ()

Gets the initialization state of MapEngine .

Returns:

true if MapEngine is initialized and ready for service.

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

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 MapFragment and MapActivity classes, it is not necessary to call onPause() as it is handled automatically.

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 MapFragment, and MapActivity classes, it is not necessary to call onResume() as it is handled automatically.

public void removeMapDataDownloadListener (OnMapDownloadListener listener)

Removes an existing MapDataDownloadListener .

Parameters:

  • listener

    A MapDataDownloadListener to remove from the MapEngine

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.