javax.microedition.location.services
Interface GeocodingServiceProvider

All Superinterfaces:

ServiceProvider

public interface GeocodingServiceProvider
extends ServiceProvider

This interface collects the services that geocoding service providers offer. With this interface the application is able to request geocoding and reverse geocoding related services from the service provider. Geocoding means that a service provider converts a street address information into coordinates. In reverse geocoding coordinates are converted into street address information.

Some service providers may only provide either geocoding or reverse geocoding service, but not both. Support for geocoding service can be queried from the ProviderCapabilities class with key value ProviderCapabilities.GEO_SUPPORTS_GEOCODING. Support for reverse geocoding service can be queried with key value ProviderCapabilities.GEO_SUPPORTS_REVERSE_GEOCODING. If an application tries to use a service that is not supported by the service provider, a ServiceException is thrown.

An application can set preferences for the geocoding service provider by using GeocodingServicePreferences class. These preferences include controlling the service request timeout, exact matches control and the maximum number of matches. The preferences are passed in as parameter to the service requests. Geocoding service provider must follow these preferences. If it is not able to do that, a ServiceException is thrown in service requests.

This interface contains only synchronous methods. The application's execution is blocked until geocoding service has been completed or aborted. The application may abort the synchronous service request with ServiceProvider.abort() method. This will cause the service request to throw an InterruptedException.

Since:

2.0

Method Summary

Landmark[]	geocode(AddressInfo address, GeographicArea locationHint, GeocodingServicePreferences preferences) Requests a geocoding service from a geocoding service provider.
Landmark[]	geocode(java.lang.String criterion, GeographicArea locationHint, GeocodingServicePreferences preferences) Requests a geocoding service from a geocoding service provider.
Landmark[]	reverseGeocode(Coordinates coordinates, GeocodingServicePreferences preferences) Requests a reverse geocoding service from a geocoding service provider.

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

abort, getDataTransferred, getProviderCapabilities, getServicePreferences, showConfigurationUI

Method Detail

geocode

Landmark[] geocode(AddressInfo address,
                   GeographicArea locationHint,
                   GeocodingServicePreferences preferences)
                   throws java.lang.InterruptedException,
                          ServiceException

Requests a geocoding service from a geocoding service provider. Geocoding converts a street address into coordinates. This synchronous method blocks until the service request is completed or it has been aborted.

Since geocoding converts a street address into coordinates, it is clear that the more complete the address information is, easier it is for a geocoding service provider to find the matching coordinates. The AddressInfo provided an input parameter should contain at least a street address. The returned Landmark objects contain both coordinates and address information. The service provider must treat the provided address information in case insensitive manner.

The application may abort the synchronous service request with ServiceProvider.abort() method. This causes the method to throw an InterruptedException.

The geocoding service provider must return the best match for the given address info as the first element in the returned array. If the provided address info is incomplete, the geocoding service provider may find several coordinates for it. This situation can happen, for example, when several cities have the same street name and the given AddressInfo does not contain city information. How the different matches are ranked into order is left to the geocoding service provider. The matches returned from this method must match in all the given AddressInfo fields, however the matches may be substrings. If the geocoding service provider can not find matches for the given address info, an empty array is returned.

An application may give some preferences for the geocoding service provider. These are done through GeocodingServicePreferences 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 number of matches and are exact matches required. The preferences also contain maximum allowed time for the service request. When this timeout has been reached, the method throws InterruptedException. If null is passed in as the preferences, the default values of the service preferences are used.

With parameter locationHint applications can provide a hint for the geocoding service provider where the best match for the service request is. Providing this hint area is optional and null indicates that no hint is given.

Parameters:

address - the address to convert into coordinates, may be updated during the method call by geocoding service provider

locationHint - a hint for the service provider where the best match is, may be null

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

Returns:

an array of matching Landmark objects for the specified address, an empty array, if no match can be found

Throws:

java.lang.IllegalArgumentException - if address does not have any field set or if preferences is not preferences for this service provider

java.lang.InterruptedException - if the request has been aborted by the application or if the timeout given in the service preferences has been exceeded

java.lang.NullPointerException - if address is null

ServiceException - if the service provider can not serve the request

geocode

Landmark[] geocode(java.lang.String criterion,
                   GeographicArea locationHint,
                   GeocodingServicePreferences preferences)
                   throws java.lang.InterruptedException,
                          ServiceException

Requests a geocoding service from a geocoding service provider. In this method the service provider returns all the places that have a field set that matches to the given criterion search. The match may be on other than address info fields. This synchronous method blocks until the service request is completed or it has been aborted. The service provider must treat the provided criterion in case insensitive manner.

The application may abort the synchronous service request with ServiceProvider.abort() method. This causes the method to throw an InterruptedException.

An application may give some preferences for the geocoding service provider. These are done through GeocodingServicePreferences 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 number of matches and are exact matches required. The preferences also contain maximum allowed time for the service request. When this timeout has been reached, the method throws InterruptedException. If null is passed in as the preferences, the default values of the service preferences are used.

With parameter locationHint applications can provide a hint for the geocoding service provider where the best match for the service request is. Providing this hint area is optional and null indicates that no hint is given.

Parameters:

criterion - text that is searched from the fields of the places

locationHint - a hint for the service provider where the best match is, may be null

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

Returns:

a Landmark array for the specified criterion, an empty array if no match can be found

Throws:

java.lang.IllegalArgumentException - if criterion is an empty String or if preferences is not preferences for this service provider

java.lang.InterruptedException - if the request has been aborted by the application or if the timeout given in the service preferences has been exceeded

java.lang.NullPointerException - if criterion is null

ServiceException - if the service provider can not serve the request

reverseGeocode

Landmark[] reverseGeocode(Coordinates coordinates,
                          GeocodingServicePreferences preferences)
                          throws java.lang.InterruptedException,
                                 ServiceException

Requests a reverse geocoding service from a geocoding service provider. This synchronous method blocks until the service request is completed or aborted. An application may abort the synchronous service request with ServiceProvider.abort method. This causes the method to throw an InterruptedException.

In some cases the provided coordinates can be mapped into several street addresses. This situation can happen, for example, if the coordinates are in the street crossing and can be mapped into either of the crossing streets. The service provider must return the best match as the first element in the array. How the different matches are ranked into order is left to the service provider. If the geocoding service provider can not find matches for the given coordinates, an empty array is returned. Atltitude information is ignored.

An application may give some preferences for the geocoding service provider. These are done through GeocodingServicePreferences 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 number of matches and are exact matches required. The preferences also contain maximum allowed time for the service request. When this timeout has been reached, the method throws InterruptedException. If null is passed in as the preferences, the default values of the service preferences are used.

Parameters:

coordinates - coordinates to be converted to a street address. objects for the specified coordinates, an empty array, if no match can be found

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

Returns:

a Landmark array for the specified text, an empty array if no match can be found

Throws:

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

java.lang.InterruptedException - if the request has been aborted by the application or if the timeout given in the service preferences has been exceeded

java.lang.NullPointerException - if coordinates is null

ServiceException - if the service provider can not serve the request