javax.microedition.location.services
Interface ServiceProvider

All Known Subinterfaces:

GeocodingServiceProvider, MapServiceProvider, NavigationServiceProvider

public interface ServiceProvider

This is a super interface for all service providers defined in this API. It contains the methods common to all providers.

Since:

2.0

Method Summary

void	abort() Requests the service provider to abort the request.
long	getDataTransferred() A method to retrieve the number of bytes that a service provider has transferred over the network.
ProviderCapabilities	getProviderCapabilities() Returns capabilities about the service provider.
ServicePreferences	getServicePreferences(boolean defaultValues) Returns the service preferences for this service provider.
void	showConfigurationUI(ServiceListener listener, ServicePreferences preferences) With this method the application can request the service provider to show it's configuration to the user.

Method Detail

getProviderCapabilities

ProviderCapabilities getProviderCapabilities()

Returns capabilities about the service provider. This information contains for example the type of the service and the name of the service provider. The method returns the capabilities of the service type of the specific service provider. This means that if an application has, for example, searched and connected to a MapServiceProvider, this method returns only the capabilities related to the mapping service.

Returns:

the service provider capabilities

getServicePreferences

ServicePreferences getServicePreferences(boolean defaultValues)

Returns the service preferences for this service provider. The method returns a new instance of the ServicePreferences. With the parameter defaultValues an application controls whether it requests the default values of the service provider or the values that were used in the last service request. If there has not been any service requests and the last preferences are requested (meaning defaultValues is set to false), the default values are returned. The values for each preference are returned with the ServicePreferences.get* methods. An application may change these values with ServicePreferences.set* methods.

The returned instance of the ServicePreferences is tight to one specific ServiceProvider. Passing in preferences retrieved from another service provider causes an IllegalArgumentException to be thrown in the service request.

Parameters:

defaultValues - true if application requests default values of the service provider, false is last used preferences are requested

Returns:

the service preferences for this service provider

abort

void abort()

Requests the service provider to abort the request. This method is asynchronous and all pending service requests will be aborted on best effort basis. This method may be used with both asynchronous and synchronous service requests.

In the asynchronous service requests the application is notified from the abort request through ServiceListener.requestAborted callback method.

In the synchronous service requests the method throws a InterrupedException when this methods is called.

showConfigurationUI

void showConfigurationUI(ServiceListener listener,
                         ServicePreferences preferences)

With this method the application can request the service provider to show it's configuration to the user. An application can check if the service provider supports this configuration UI with ProviderCapabilities.getPropertyValue() method using SUPPORTS_CONFIGURATION_UI key.

An application may have already modified some of the service provider settings through the ServicePreferences class. This instance is passed in as the parameter to capture the already changed settings. Also the language used in the configuration UI is set in the ServicePreferences object. The preferences that are passed in as the parameter are not changed during this method call.

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 ServiceListener callback method. When the user has completed the configuration, ServiceListener.configurationCompleted notification is sent to the application and the application receives a new instance of the ServicePreferences. If the service provider does not support configuration UI, the ServiceListener.configurationCompleted notification is sent immediately.

Parameters:

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

preferences - the start with the currently used preferences for the service provider, null to show the default values of the service provider

Throws:

java.lang.IllegalArgumentException - if preferences are not preferences for the current service provider

java.lang.NullPointerException - if listener is null

getDataTransferred

long getDataTransferred()

A method to retrieve the number of bytes that a service provider has transferred over the network. This counter counts the number of bytes during the lifetime of this instance. For a newly created instance this counter returns 0, unless connecting to a service provider already requires network access. In this case the return value may be > 0.

If the API implementation does not use network to retrieve content data, it will return 0.

Returns:

the number of bytes transferred over the network