HERE Android SDK Developer's Guide

VenueService

The class VenueService is a member of com.here.android.mpa.venues3d .

Class Summary

public final class VenueService

extends java.lang.Object

VenueService offers methods to search for venues and to get Venue objects based on search.

[For complete information, see the section Class Details]

Nested Class Summary

Table 1. Nested Classes in VenueService
Nested Classes

public static final enumeration VenueService.InitStatus

Represents values that describe the initialization status of the VenueService.

public static abstract interface VenueService.VenueAuthenticationListener

Represents a listener to provide notification of the venue authentication event.

public static abstract interface VenueService.VenueLoadListener

Represents a listener to provide notification of the venue load events.

public static final enumeration VenueService.VenueLoadStatus

Represents values that describe the venue load status of the VenueService.

public static abstract interface VenueService.VenueServiceClearCacheListener

Represents a listener to provide notification of the venue service's status upon its cache clearing.

public static abstract interface VenueService.VenueServiceListener

Represents a listener to provide notification of the venue service's status upon its initialization.

public static abstract interface VenueService.VenueServiceStopListener

Represents a listener to provide notification of the venue service's status upon its stopping.

Method Summary

Table 2. Methods in VenueService
Methods

public void addListener (VenueServiceListener listener)

Adds VenueService.VenueServiceListener object to VenueService object.

public void addVenueLoadListener (VenueLoadListener listener)

Adds VenueService.VenueLoadListener object to VenueService object.

public void authenticate (VenueAuthenticationListener listener)

Starts VenueService authentication asynchronously, without starting VenueService .

public static VenueService createAdditionalService (Context context)

Creates an additional instance of VenueService class.

public void enableVenueZoom (boolean enable)

Enables or disables Venue Zoom.

public VenueAccount getActiveVenueAccount ()

Returns the active VenueAccount, if any exists, or null otherwise.

public InitStatus getInitStatus ()

Returns status of starting the VenueService .

public static VenueService getInstance (Context context)

Gets an main instance of this class.

public java.util.List <VenueAccount> getVenueAccounts ()

Returns all available VenueAccount objects, if any.

public void getVenueAsync (VenueInfo venue)

Asynchronously gets the Venue object that is specified by the given VenueInfo object.

public VenueInfo getVenueAt (GeoCoordinate point)

Searches for a venue near the given GeoCoordinate.

public VenueInfo getVenueAt (GeoCoordinate point, float radius)

Searches for a venue near the given GeoCoordinate.

public VenueInfo getVenueById (String id)

Searches for a venue by the given venue identifier.

public void getVenuesAsync (java.util.List <VenueInfo> venues)

Asynchronously gets the Venue object that is specified by the given list of VenueInfo objects.

public void getVenuesAsync (java.util.List <VenueInfo> venues, GeoCoordinate center)

Asynchronously gets the Venue object that is specified by the given list of VenueInfo objects.

public java.util.List <VenueInfo> getVenuesAt (GeoCoordinate point)

Searches for venues at a given GeoCoordinate.

public java.util.List <VenueInfo> getVenuesAt (GeoCoordinate point, float radius)

Searches for venues near the given GeoCoordinate.

public void getVenuesGentlyAsync (java.util.List <VenueInfo> venues, GeoCoordinate center)

public java.util.List <VenueInfo> getVenuesIn (GeoBoundingBox searchBox)

Searches for venues inside the given GeoBoundingBox.

public boolean isCombinedContent ()

Gets a value indicating whether the HERE SDK and the HERE private 3D venue content will be used together.

public boolean isDevEnv ()

Gets a value indicating whether the development or another backend is used.

public boolean isPrivateContent ()

Gets a value indicating whether the HERE SDK or the HERE private 3D venue content is to be used.

public boolean isTestEnv ()

Gets a value indicating whether a normal or a test backend is used.

public boolean isVenueZoomEnabled ()

Returns boolean value indicating whether Venue Zoom is enabled or not.

public void removeListener (VenueServiceListener listener)

Removes given VenueService.VenueServiceListener object from the list of listeners, which receive the Venue related events.

public void removeVenueLoadListener (VenueLoadListener listener)

Removes given VenueService.VenueLoadListener object from the list of listeners, which receive the Venue load events.

public boolean setActiveVenueAccount (VenueAccount account)

Sets an active VenueAccount object.

public void setDevEnv (boolean useDevEnv)

Sets a value indicating whether the development or another backend is used.

public void setHereAccountToken (String token)

Sets a HERE account token.

public void setIsCombinedContent (boolean isCombinedContent)

Sets a value indicating whether the HERE SDK and the HERE private 3D venue content will be used together.

public void setPrivateContent (boolean isPrivateContent)

Sets a value indicating whether the HERE SDK or the HERE private 3D venue content is to be used.

public void setTestEnv (boolean useTestEnv)

Sets a value indicating whether a normal or a test backend is used.

public void startAsync ()

Starts VenueService asynchronously.

public static void stopAndClearCache (VenueServiceClearCacheListener listener)

Clears cached data including all downloaded venues.

public void stopAsync (VenueServiceStopListener stopListener)

Stops VenueService asynchronously.

Class Details

VenueService offers methods to search for venues and to get Venue objects based on search. Use of this object does not necessitate Map involvement.

This class can not be instantiated directly. Use getInstance(Context) method to get an instance of the class instead.

Method Details

public void addListener (VenueServiceListener listener)

Adds VenueService.VenueServiceListener object to VenueService object.

Parameters:

  • listener

    The VenueServiceListener object to be added.

public void addVenueLoadListener (VenueLoadListener listener)

Adds VenueService.VenueLoadListener object to VenueService object.

Parameters:

  • listener

    The VenueLoadListener object to be added.

public void authenticate (VenueAuthenticationListener listener)

Starts VenueService authentication asynchronously, without starting VenueService . Can be used to retrieve information about available @link VenueAccount object for current HERE account.

An authentication status is returned to the object registered as VenueService.VenueAuthenticationListener.

Parameters:

See also:

setHereAccountToken(String)

getActiveVenueAccount()

getVenueAccounts()

setActiveVenueAccount(VenueAccount)

public static VenueService createAdditionalService (Context context)

Creates an additional instance of VenueService class.

Parameters:

  • context

    Android application android.content.Contex.

public void enableVenueZoom (boolean enable)

Enables or disables Venue Zoom. Venue Zoom allows bigger zoom levels for opened venues. By default Venue Zoom is not used. In order to view a particular venue in Venue Zoom mode, use VenueGestureListener. Alternatively, use useVenueZoom(boolean).

Parameters:

  • enable

    if true, Venue Zoom is enabled, otherwise not.

See also:

isVenueZoomEnabled()

public VenueAccount getActiveVenueAccount ()

Returns the active VenueAccount, if any exists, or null otherwise. A VenueAccount object only exists if the user is authenticated with a HERE account token and if the account is connected to at least one private content sources. If an account has been made active by a call to setActiveVenueAccount(VenueAccount), that account is returned. Otherwise, the first account in the list of accounts is returned. VenueService will use this account only if private content is active.

Returns:

VenueAccount object if any exist, and null otherwise.

See also:

setHereAccountToken(String)

authenticate(VenueAuthenticationListener)

getVenueAccounts()

setActiveVenueAccount(VenueAccount)

public InitStatus getInitStatus ()

Returns status of starting the VenueService .

Returns:

the VenueService.InitStatus of starting the VenueService.

public static VenueService getInstance (Context context)

Gets an main instance of this class.

Parameters:

  • context

    Android application android.content.Contex.

public java.util.List <VenueAccount> getVenueAccounts ()

Returns all available VenueAccount objects, if any. The VenueAccount object exists only if the user is authenticated with a HERE account token and if this account is connected to at least one private content sources.

Returns:

The array of VenueAccount, if any available, empty list otherwise.

See also:

setHereAccountToken(String)

authenticate(VenueAuthenticationListener)

getActiveVenueAccount()

setActiveVenueAccount(VenueAccount)

public void getVenueAsync (VenueInfo venue)

Asynchronously gets the Venue object that is specified by the given VenueInfo object.

Use addListener(VenueServiceListener) to add object implementing listener for loading completion.

Parameters:

  • venue

    The VenueInfo specifying venue to be get.

Throws:

  • AccessControlException

    Access to this operation is denied. Contact your HERE representative for more information.

public VenueInfo getVenueAt (GeoCoordinate point)

Searches for a venue near the given GeoCoordinate.

Parameters:

  • point

    Defines a point near which venue is searching.

Returns:

The closest VenueInfo to the specified point or null if there is no any

public VenueInfo getVenueAt (GeoCoordinate point, float radius)

Searches for a venue near the given GeoCoordinate.

Parameters:

  • point

    Defines a point near which a venue is searching.

  • radius

    Defines a radius in meters where to search a venue.

Returns:

The closest VenueInfo to the specified point or null if there is no any

public VenueInfo getVenueById (String id)

Searches for a venue by the given venue identifier.

Parameters:

  • id

    The venue identifier to be searched.

Returns:

VenueInfo representing the found venue. Null if no venue found with the given identifier.

Throws:

  • AccessControlException

    Access to this operation is denied. Contact your HERE representative for more information.

See also:

getId()

public void getVenuesAsync (java.util.List <VenueInfo> venues)

Asynchronously gets the Venue object that is specified by the given list of VenueInfo objects.

Use addListener(VenueServiceListener) to add object implementing listener for loading completion.

Parameters:

  • venues

    The list of VenueInfo specifying venues to be get.

Throws:

  • IllegalArgumentException

    if the list of venues is null or empty.

  • AccessControlException

    Access to this operation is denied. Contact your HERE representative for more information.

public void getVenuesAsync (java.util.List <VenueInfo> venues, GeoCoordinate center)

Asynchronously gets the Venue object that is specified by the given list of VenueInfo objects.

Use addListener(VenueServiceListener) to add object implementing listener for loading completion.

Parameters:

  • venues

    The list of VenueInfo specifying venues to be get.

  • center

    The center GeoCoordinate. The closest venue to the center will be loaded first.

Throws:

  • IllegalArgumentException

    if the list of venues is null or empty.

  • AccessControlException

    Access to this operation is denied. Contact your HERE representative for more information.

public java.util.List <VenueInfo> getVenuesAt (GeoCoordinate point)

Searches for venues at a given GeoCoordinate.

Parameters:

  • point

    Defines a point at which venues are searching.

Returns:

The array of VenueInfo found at the specified point

public java.util.List <VenueInfo> getVenuesAt (GeoCoordinate point, float radius)

Searches for venues near the given GeoCoordinate.

Parameters:

  • point

    Defines a point near which venues are searching.

  • radius

    Defines a radius in meters where to search venues.

Returns:

The array of VenueInfo found near the specified point

public void getVenuesGentlyAsync (java.util.List <VenueInfo> venues, GeoCoordinate center)

Parameters:

  • venues
  • center

public java.util.List <VenueInfo> getVenuesIn (GeoBoundingBox searchBox)

Searches for venues inside the given GeoBoundingBox.

Parameters:

  • searchBox

    Defines an area in which venues are searching.

Returns:

The array of VenueInfo found inside the specified area

Throws:

  • AccessControlException

    Access to this operation is denied. Contact your HERE representative for more information.

public boolean isCombinedContent ()

Gets a value indicating whether the HERE SDK and the HERE private 3D venue content will be used together. By default combined content is not used.

If VenueService is using private content, then data from the private content will be used as the primary source, and HERE SDK data as an alternative one. Otherwise HERE SDK content will be the primary source of data and the private content will be an alternative one. This method needs to be called before starting VenueService with startAsync() or, if available, VenueMapLayer with VenueMapLayer#startAsync().

public boolean isDevEnv ()

Gets a value indicating whether the development or another backend is used. The backend specified by setTestEnv is used by default.

public boolean isPrivateContent ()

Gets a value indicating whether the HERE SDK or the HERE private 3D venue content is to be used. The HERE SDK content is used by default.

public boolean isTestEnv ()

Gets a value indicating whether a normal or a test backend is used. The normal backend is used by default. The value returned by this method is irrelevant when isDevEnv() returns true, because then the development environment is used.

public boolean isVenueZoomEnabled ()

Returns boolean value indicating whether Venue Zoom is enabled or not.

Returns:

true if Venue Zoom is enabled, otherwise false.

See also:

enableVenueZoom(boolean)

public void removeListener (VenueServiceListener listener)

Removes given VenueService.VenueServiceListener object from the list of listeners, which receive the Venue related events.

Parameters:

  • listener

    The VenueServiceListener object to be removed.

public void removeVenueLoadListener (VenueLoadListener listener)

Removes given VenueService.VenueLoadListener object from the list of listeners, which receive the Venue load events.

Parameters:

  • listener

    The VenueLoadListener object to be removed.

public boolean setActiveVenueAccount (VenueAccount account)

Sets an active VenueAccount object. In case of success, the user can restart the current VenueService object with the startAsync() method to switch to another private content source, related to the new active VenueAccount object. VenueService will use this account only if private content is activated.

Parameters:

  • account

    VenueAccount object which needs to be active.

Returns:

true if VenueAccount was set successfully, false otherwise.

See also:

setHereAccountToken(String)

authenticate(VenueAuthenticationListener)

getActiveVenueAccount()

getVenueAccounts()

public void setDevEnv (boolean useDevEnv)

Sets a value indicating whether the development or another backend is used. By default, the backend specified by setTestEnv is used.

This method needs to be called before starting VenueService with startAsync() or, if available, VenueMapLayer with VenueMapLayer#startAsync(). If VenueService is already running, stop it first using stopAsync(VenueService.VenueServiceStopListener), and then after calling this method, start it again using startAsync().

Parameters:

  • useDevEnv

    if true, development environment is set, otherwise the environment specified by setTestEnv is used.

public void setHereAccountToken (String token)

Sets a HERE account token. In case of valid token and if private content is used, VenueService will be using private bucket of a HERE account instead of private bucket of the app.

Parameters:

  • token

    HERE account token. Can be null. In this case the token is removed.

public void setIsCombinedContent (boolean isCombinedContent)

Sets a value indicating whether the HERE SDK and the HERE private 3D venue content will be used together. By default combined content is not used.

If VenueService is using private content, then data from the private content will be used as the primary source, and HERE SDK data as an alternative one. Otherwise HERE SDK content will be the primary source of data and the private content will be an alternative one. This method needs to be called before starting VenueService with startAsync() or, if available, VenueMapLayer with VenueMapLayer#startAsync(). If VenueService is already running, stop it first using stopAsync(VenueService.VenueServiceStopListener), and then after calling this method, start it again using startAsync().

Parameters:

  • isCombinedContent

    if true, the combined content is set, otherwise one source of data will be used.

public void setPrivateContent (boolean isPrivateContent)

Sets a value indicating whether the HERE SDK or the HERE private 3D venue content is to be used. The HERE SDK content is used by default.

This method needs to be called before starting VenueService with startAsync() or, if available, VenueMapLayer with VenueMapLayer#startAsync(). If VenueService is already running, stop it first using stopAsync(VenueService.VenueServiceStopListener), and then after calling this method, start it again using startAsync().

Parameters:

  • isPrivateContent

    if true, the PRIVATE content is set, otherwise the HERE SDK content is used.

public void setTestEnv (boolean useTestEnv)

Sets a value indicating whether a normal or a test backend is used. The normal backend is used by default. If setDevEnv has been set to true, this setting is meaningless, as the development environment will be used.

This method needs to be called before starting VenueService with startAsync() or, if available, VenueMapLayer with VenueMapLayer#startAsync(). If VenueService is already running, stop it first using stopAsync(VenueService.VenueServiceStopListener), and then after calling this method, start it again using startAsync().

Parameters:

  • useTestEnv

    if true, test environment is set, otherwise normal environment is used.

public void startAsync ()

Starts VenueService asynchronously. The method will do nothing if VenueService is already initialized with status ONLINE_SUCCESS.

An initialization status is returned to objects registered as VenueService.VenueServiceListener.

public static void stopAndClearCache (VenueServiceClearCacheListener listener)

Clears cached data including all downloaded venues. All running instances of VenueService will be stopped asynchronously and locked ( getInitStatus() will return LOCKED during the operation). After cache is cleared, VenueService needs to be started again using startAsync().

Parameters:

  • listener

    VenueServiceClearCacheListener#onVenueServiceCacheCleared() is called when cache is cleared.

public void stopAsync (VenueServiceStopListener stopListener)

Stops VenueService asynchronously. The callback interface given as a parameter will be called when the service has been stopped and Venue loading is not happening any more. Use startAsync() to start VenueService again.

Parameters:

  • stopListener

    VenueServiceStopListener#onVenueServiceStopped() is called when Venue loading has been stopped.