javax.microedition.location.services
Interface MapServiceProvider

All Superinterfaces:

ServiceProvider

public interface MapServiceProvider
extends ServiceProvider

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

An application can set preferences for a map service provider by using MapServicePreferences class. These preferences include map type, selection details, map layers and user instructions. The preferences are passed in as parameter to the service requests. Map service provider must follow these preferences. If it is not able to do that, a ServiceException is thrown in service requests.

In asynchronous methods the application hands over the control to the map service provider. This means that the map service provider may take over the whole screen from the application to display maps or select targets from the map. The state and results of the asynchronous service requests are delivered to the application through MapServiceListener interface callback methods. In order to receive this 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.

At the lower levels, there may be only one map service provider implementation that handles all the service requests. In these situations the map 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

void	displayMap(RectangleGeographicArea initialViewport, GeographicArea[] areas, Landmark[] landmarks, Coordinates[] coordinates, Route[] routes, MapServicePreferences preferences, MapServiceListener listener) Requests a map service provider to display a map.
Map	getMap(RectangleGeographicArea initialViewport, GeographicArea[] areas, Landmark[] landmarks, Coordinates[] coordinates, Route[] routes, int width, int height, MapServiceListener listener) Requests a Map object from a map service provider.

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

abort, getDataTransferred, getProviderCapabilities, getServicePreferences, showConfigurationUI

Method Detail

displayMap

void displayMap(RectangleGeographicArea initialViewport,
                GeographicArea[] areas,
                Landmark[] landmarks,
                Coordinates[] coordinates,
                Route[] routes,
                MapServicePreferences preferences,
                MapServiceListener listener)
                throws ServiceException

Requests a map service provider to display a map. An application may specify a set geographical areas, landmarks, coordinates object and routes to be shown on the map. An application may request only one of these alternatives or any combination of them. The application also specifies what is the initial viewport to the map that is shown to the user with initialViewport parameter. Passing null as the initial viewport, means that the map service provider decides the initial viewport. If all map items and initial viewport are null, the map service provider decides what area is shown on the map.

The initial viewport defined by the application must fit to the map shown to the user. If some of the given items to be included into the map are within the given initial viewport, those items must be shown on the map. The items outside the initial viewport must be shown if the map is moved to them. The map service provider may do some scaling to to fit the initial viewport to the screen. The map service provider may also provide means for the user to pan or rotate the map shown on the screen.

An application may give some preferences for the map service provider. These are done through MapServicePreferences 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 map type, is selection of items on the map allowed and what map layers are show. An application may also add an instruction to the service provider that it should show to the user during execution of this method. 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 a service provider. The status of the service request is notified through the MapServiceListener callback methods and this listener is set in the method call. If an application allows the user to make selection(s) from the map (through MapServicePreferences), the selected items (one or many) are received through MapServiceListener.selectionUpdated notification. This notification contains information about all currently selected items. The API implementation should call this method only once when the selection has been completed. When the user the exits map, ServiceListener.requestCompleted notification is sent to the application.

Parameters:

initialViewport - the initial area that is shown to the user, may be null

areas - geographical areas to be shown on the map, may be null or an empty array

landmarks - landmarks to be shown on the map, may be null or an empty array

coordinates - coordinates objects to be shown on the map, may be null or an empty array

routes - routes to be shown on the map, may be null or an empty array

preferences - the preferences for the map 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 - if listener is null or if areas, landmarks, coordinates or routes contain null elements

ServiceException - if the service provider can not serve the request or if initialViewport or any of the items to be shown on the map are outside the supported area of the service provider

getMap

Map getMap(RectangleGeographicArea initialViewport,
           GeographicArea[] areas,
           Landmark[] landmarks,
           Coordinates[] coordinates,
           Route[] routes,
           int width,
           int height,
           MapServiceListener listener)
           throws java.lang.InterruptedException,
                  ServiceException

Requests a Map object from a map service provider. An application may specify geographic areas, landmarks, coordinates objects and routes that are included into the generated Map object. This means that the specified item are rendered into the generated map. An application may request only one of these items or any combination of them. An application can not modify the items included into the map.

Some service providers may not support generation of Map objects. The support can be queried with key MAP_SUPPORTS_MAP_CREATION from the ProviderCapabilities.getPropertyValue method. If the generation of Map objects is not supported, this method throws a ServiceException.

The initial geographic area that is visible from the Map object is defined with initialViewport parameter. This part of the map is rendered when calling the Map.renderMap method. If an application does not set the initial viewport, it is defined by the map service provider. The width and height parameters define the size of area where the generated map is later rendered by the application. The size is defined in pixels. All the requested items must be included into the map. The map service provider determines the needed zoom level of the based on the requested items. An application may later change the zoom levels in the returned Map object with Map.setZoomLevel method. The realized viewport can be queried with Map.getViewport method.

The Map object is always constructed due to true north. If an application needs to rotate the map, it does that with Map.rotate method.

This is a synchronous method and it blocks until the map image generation 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. Even if the listener has been set, calling the ServiceProvider.abort method must not cause ServiceListener.requestAborted notification to be sent.

A map service provider may create the requested Map object partially. This means that the returned Map object only contains the data for the initial viewport area, but not for the other areas. The returned Map object must contain data at least for the initial viewport area. If map service provider does not return the data for the whole map, the implementation of Map.renderMap method must be able to retrieve the missing data from the map service provider. Therefore an application should set a listener to received notifications when map content has been updated. This is done with parameter listener. When new data is available, MapServiceListener.mapContentUpdated notification is sent to the application.

Parameters:

initialViewport - the initial area that is visible from the Map, may be null

areas - geographic areas to be rendered on the map, may be null or an empty array

landmarks - landmarks to be rendered on the map, may be null or an empty array

coordinates - coordinates objects to be rendered on the map, may be null or an empty array

routes - routes to be rendered on the map, may be null or an empty array

width - the width of the area where map is rendered in pixels

height - the height of the area where map is rendered in pixels

listener - the listener thought which map content updates are notified and which is associated with the resulting Map object, may be null

Returns:

a generated Map object or null if the map service provider is not able to generate the map according to the input parameters

Throws:

java.lang.IllegalArgumentException - if width <= 0 or height <= 0

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

java.lang.NullPointerException - if areas, landmarks, coordinates or routes contain null elements

ServiceException - if the service provider can not serve the request or if the service provider does not support map image generation or if initialViewport or any of the items to be placed on the map are outside the supported area of the service provider