javax.microedition.location.services
Interface NavigationServiceProvider

All Superinterfaces:

ServiceProvider

public interface NavigationServiceProvider
extends ServiceProvider

This interface collects the services that navigation providers offer. Through this interface applications are able to request navigation related services from the navigation service provider. There are both asynchronous and synchronous methods in this interface.

An application can set preferences for the navigation service provider by using NavigationServicePreferences class. The preferences include, for example, the type of the route, the transport mode used to travel the route and the areas and features to be avoided when calculating the route. The application can also control whether the current location, instructions and map is shown or not. The preferences are passed in as parameter to the service requests. Navigation service provider must follow these preferences. If it is not able to do that, a ServiceException is thrown in service requests.

When requesting an asynchronous service through this interface, applications hand over the control to the service provider. This means that if, for example, an application requests navigation to specified location, the navigation provider may take over the whole screen from the application and display the navigation information on the screen. The state and results of the asynchronous service requests are delivered through NavigationServiceListener interface callback methods. In order to receive these results, the application must implement that interface and set the listener in the asynchronous method calls.

The synchronous methods block the execution until the service request has been completed. The application may abort both the synchronous and the asynchronous service request with ServiceProvider.abort method. This will cause the synchronous service request to throw an InterruptedException. In the asynchronous service requests the application is notified from through ServiceListener.requestAborted callback method.

Some navigation service providers may support generating Route objects from the specified set of coordinates. The support can be queried with ProviderCapabilities.getPropertyValue method using key NAV_SUPPORTS_ROUTE_GENERATION. This interface provides a mechanism to request generation of Route objects. Since generating a route may be an extensive operation, the navigation service provider is not required to support generation of more than one route at a time.

At the lower levels, there may be only one navigation service provider implementation that handles all the service requests. In these situations the navigation service provider implementation decided how to handle possibly concurrent service request. Some implementations may want to queue the requests, whereas some other implementation may override the service request or ask the user what to do.

Since:

2.0

Method Summary

Route[]	getRoute(Coordinates[] waypoints, NavigationServicePreferences preferences) Requests a routing service from a navigation service provider.
void	navigate(Coordinates[] waypoints, NavigationServicePreferences preferences, NavigationServiceListener listener) Requests a navigation service from a navigation service provider.
void	navigate(Route route, NavigationServicePreferences preferences, NavigationServiceListener listener) Requests a navigation from the current location through the given Route object from a navigation service provider.
void	showRoute(Coordinates[] waypoints, NavigationServicePreferences preferences, NavigationServiceListener listener) Requests a navigation service provider to show the given coordinates as a route.
void	showRoute(Route route, NavigationServicePreferences preferences, NavigationServiceListener listener) Requests a navigation service provider to show the given route on a map.

Methods inherited from interface javax.microedition.location.services.ServiceProvider

abort, getDataTransferred, getProviderCapabilities, getServicePreferences, showConfigurationUI

Method Detail

navigate

void navigate(Coordinates[] waypoints,
              NavigationServicePreferences preferences,
              NavigationServiceListener listener)
              throws ServiceException

Requests a navigation service from a navigation service provider. The navigation is always done from the current location. The last item on the waypoints array is the destination. All the other coordinates are waypoints in the route. If waypoints array contains only one element it is considered as the destination of the route. The navigation service provider must start going through the waypoint in given order. However if the user goes off the route the navigation may recalculate the route and skip some waypoints. If the current location and the destination are the same and there are no waypoints, the navigation service provider must handle this as a normal request, meaning that the NavigationServiceListener.destinationReached notification is sent immediately.

An application may give some preferences for the navigation service provider. These are done through NavigationServicePreferences class and passed in as a parameter to the request. Application retrieves the preferences with ServiceProvider.getServicePreferences method or received them through ServiceListener.configurationCompleted notification. The preferences include, for example, the route type, transport type, what features should be avoided or what kind of instructions are given. If null is passed in as the preferences, the default values of the service preferences are used.

To be able to do navigation the navigation service provider has to be able to retrieve the current location. When this method is called and the location retrieval is out of service a ServiceException is thrown.

This is an asynchronous method. The service request is passed through this interface to the actual navigation service provider. The status of the service request is notified through the NavigationServiceListener callback methods and this listener is set in the method call. When an end point of a route segment is reached, the NavigationServiceListener.watpointReached notification must be sent to the application.

Parameters:

waypoints - the array of coordinates through which the navigation is done

preferences - the preferences for the navigation service request, null to use provider default preferences

listener - the listener that receives the status information about the service request

Throws:

java.lang.NullPointerException - if waypoints or listener is null or if waypoints contains null elements

java.lang.IllegalArgumentException - if the length of parameter waypoints is < 1 or if preferences is not preferences for this service provider

ServiceException - if the service provider can not serve the request or if the service provider does not have needed navigation information

navigate

void navigate(Route route,
              NavigationServicePreferences preferences,
              NavigationServiceListener listener)
              throws ServiceException

Requests a navigation from the current location through the given Route object from a navigation service provider. The navigation service provider must start navigating from the current location through the given route, but if the user goes off the route, the navigation service provider may recalculate the route, skip some route segments and navigate through the changed route. In this case, the application must be notified about the changed route through NavigationServiceListener.offRoute and NavigationServiceListener.routeChanged notifications.

If the Route object was originally constructed by an application, the service provider may not have all the data needed to navigate through it or the Route may contain invalid information. In this case the service provider can not serve the request and a ServiceException is thrown.

An application may give some preferences for the navigation service provider. These are done through NavigationServicePreferences class and passed in as a parameter to the request. Application retrieves the preferences with ServiceProvider.getServicePreferences method or received them through ServiceListener.configurationCompleted notification. The preferences include, for example, the route type, transport type, what features should be avoided or what kind of instructions are given. If null is passed in as the preferences, the default values of the service preferences are used.

To be able to do navigation the navigation service provider has to be able to retrieve the current location. When this method is called and the location retrieval is out of service a ServiceException is thrown.

This is an asynchronous method. The service request is passed through this interface to the actual navigation service provider. The status of the service request is notified through the NavigationServiceListener callback methods and this listener is set in the method call.

Parameters:

route - the route to be navigated

preferences - the preferences for the navigation service request, null to use provider default preferences

listener - the listener that receives the status information about the service request

Throws:

java.lang.IllegalArgumentException - if preferences is not preferences for this service provider

java.lang.NullPointerException - is route or listener is null

ServiceException - if the service provider can not serve the request or if the service provider does not have needed navigation information

showRoute

void showRoute(Coordinates[] waypoints,
               NavigationServicePreferences preferences,
               NavigationServiceListener listener)
               throws ServiceException

Requests a navigation service provider to show the given coordinates as a route. This method differs from the corresponding navigation request so that it does not start any navigation automatically. It only shows the route on a map and may provide mechanism to browse through the waypoints and show details about them. The navigation service provider may also provide feature that starts the navigation through the given route to the user.

The fist item in the waypoints array is the starting point in the route and the last is the destination. All the other coordinates are waypoints on the route. The waypoints array must contains at least two elements. The navigation service provider must generate a route that goes through the waypoints in given order.

An application may give some preferences for the navigation service provider. These are done through NavigationServicePreferences class and passed in as a parameter to the request. Application retrieves the preferences with ServiceProvider.getServicePreferences method or received them through ServiceListener.configurationCompleted notification. The preferences include, for example, the route type, transport type, what features should be avoided or what kind of instructions are given. If null is passed in as the preferences, the default values of the service preferences are used.

This is an asynchronous method. The service request is passed through this interface to the actual navigation service provider. The status of the service request is notified through the NavigationServiceListener callback methods and this listener is set in the method call.

Parameters:

waypoints - the array of coordinates through which the route is generated

preferences - the preferences for the navigation service request, null to use provider default preferences

listener - the listener that receives the status information about the service request

Throws:

java.lang.NullPointerException - waypoints or listener is null or if waypoints contains null elements

java.lang.IllegalArgumentException - if the length of parameter waypoints is < 2 or if preferences is not preferences for this service provider

ServiceException - if the service provider can not serve the request or if the service provider does not have needed navigation information

showRoute

void showRoute(Route route,
               NavigationServicePreferences preferences,
               NavigationServiceListener listener)
               throws ServiceException

Requests a navigation service provider to show the given route on a map. This method differs from the corresponding navigation request so that it does not start any navigation automatically. It only shows the route on a map and may provide mechanism to browse through the waypoints and show details about them. The navigation service provider may also provide feature that starts the navigation through the given route to the user.

If the Route object was originally constructed by an application, the service provider may not have all the data needed to show details of it or the Route may contain invalid information. In this case the service provider can not serve the request and a ServiceException is thrown.

An application may give some preferences for the navigation service provider. These are done through NavigationServicePreferences class and passed in as a parameter to the request. Application retrieves the preferences with ServiceProvider.getServicePreferences method or received them through ServiceListener.configurationCompleted notification. The preferences include, for example, the route type, transport type, what features should be avoided or what kind of instructions are given. If null is passed in as the preferences, the default values of the service preferences are used.

This is an asynchronous method. The service request is passed through this interface to the actual navigation service provider. The status of the service request is notified through the NavigationServiceListener callback methods and this listener is set in the method call.

Parameters:

route - the route to be shown

preferences - the preferences for the navigation service request, null to use provider default preferences

listener - the listener that receives the status information about the service request

Throws:

java.lang.IllegalArgumentException - if preferences is not preferences for this service provider

java.lang.NullPointerException - is route or listener is null

ServiceException - if the service provider can not serve the request or if the service provider does not have needed navigation information

getRoute

Route[] getRoute(Coordinates[] waypoints,
                 NavigationServicePreferences preferences)
                 throws java.lang.InterruptedException,
                        ServiceException

Requests a routing service from a navigation service provider. The provider may return more than one route alternative. The coordinates in the first position of the waypoints array are considered as the starting point and the last item as the destination for the route. All the other coordinates in the waypoints array are waypoints in the route. The route is generated through the given waypoints in the given order. Splitting a route into smaller route segments is left to the navigation service provider. All the given coordinates in the waypoints array must be found from the geometry of the route segments.

The waypoints array must always contain at least two coordinates, the starting point and the destination point. If the starting point and the destination are the same and there are no waypoints, the navigation service provider must create a Route object with one route segment. If an application wants to get a route from the current location to some destination, the application has to fetch the current location itself.

An application may give some preferences for the navigation service provider. These are done through NavigationServicePreferences class and passed in as a parameter to the request. Application retrieves the preferences with ServiceProvider.getServicePreferences method or received them through ServiceListener.configurationCompleted notification. The preferences include, for example, the route type, transport type, what features should be avoided or what kind of instructions are given. If null is passed in as the preferences, the default values of the service preferences are used.

This is a synchronous method and it blocks the execution until the service request has been completed. The application may abort the synchronous service request with ServiceProvider.abort() method. This will cause the service request to throw an InterruptedException.

Parameters:

waypoints - the coordinates through which a route is generated

preferences - the preferences for the navigation service request, null to use provider default preferences

Returns:

an array of Route object containing generated routes

Throws:

java.lang.IllegalArgumentException - if length of waypoints array < 2 or if preferences is not preferences for this service provider

java.lang.InterruptedException - if the service request has been aborted by the application

java.lang.NullPointerException - if waypoints is null or if waypoints contains null elements

ServiceException - if the service provider can not serve the request or does not support route generation