javax.microedition.location.services
Class ProviderManager

java.lang.Object
  javax.microedition.location.services.ProviderManager

public class ProviderManager
extends java.lang.Object

This class is the starting point for using service provider interfaces in Location API 2.0. This class is used to search different service providers and get the actual provider instances. First an application searches for a certain service provider and gets back a list of supported providers. Then the application selects which service provider to use and connects to that particular service provider. After this the services from the provider are available for the application to use. A code example how this is done can be found in Appendix B: Code examples.

If there are several service providers for a service, the API implementation must select one of those to be the default service provider and the default provider must not require any additional information in the extraInfo parameter. That default service provider is used when an application requests a service provider instance without specifying the name of the provider. For more information on this, see the description in connectToServiceProvider method.

There can be situations where there are several applications running and they all need services from the same service provider. When an application requests an instance of a service provider, the API implementation must return different instance of the service provider to requesting applications.

Since:

2.0

Field Summary

static int	GEOCODING Service provider type for geocoding and reverse geocoding services.
static int	MAP Service provider type for map services.
static int	NAVIGATION Service provider type for navigation services.

Method Summary

static ServiceProvider	connectToServiceProvider(java.lang.String name, int type, java.lang.String extraInfo) Gets an instance of requested service provider to be used in the service requests.
static ProviderCapabilities[]	getServiceProviderCapabilities(int type) With this method an application is able to get the capabilities for service providers of specified service type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAP

public static final int MAP

Service provider type for map services.

See Also:

Constant Field Values

NAVIGATION

public static final int NAVIGATION

Service provider type for navigation services.

See Also:

Constant Field Values

GEOCODING

public static final int GEOCODING

Service provider type for geocoding and reverse geocoding services.

See Also:

Constant Field Values

Method Detail

getServiceProviderCapabilities

public static ProviderCapabilities[] getServiceProviderCapabilities(int type)

With this method an application is able to get the capabilities for service providers of specified service type. The possible service types are defined as constants in this class. This method may return information about more than one service provider. An application can check the capabilities of different service provides from the returned ProviderCapabilities objects.

This method returns an array of ProviderCapabilities objects of all service providers on the device that provide the requested service. The default service provider defined by the API implementation is returned in the first element of the array. The returned ProviderCapabilities objects contain only the capabilities of the service providers for the requested service type.

In some implementations the actual service request may be performed on a remote server. However even for these kind of services the capabilities of the service must be stored on the device. So searching the service providers the API implementation supports must not cause network traffic.

Parameters:

type - the type of the requested service

Returns:

an array ProviderCapabilities objects for all the service providers that support the specified service type, an empty array if there are no providers for the specified service type

Throws:

java.lang.IllegalArgumentException - if type is not one of the constants defined in this class

connectToServiceProvider

public static ServiceProvider connectToServiceProvider(java.lang.String name,
                                                       int type,
                                                       java.lang.String extraInfo)
                                                throws ServiceException

Gets an instance of requested service provider to be used in the service requests. The type parameter is passed in to clarify which type of service is requested, if the service provider supports more than one type of services. If null is given as the service name, the API implementation must return the default provider for the requested service type. The type of the service must be one of the constant defined in this class. The API implementation must always return a new instance of the requested service provider

In some cases the service provider may require authentication or some other additional information. This information can be sent to the service provider with extraInfo parameter. The service provider specifies the format of this additional information. There may be service provider specific property keys in the ProviderCapabilities class to define this information. null is used if there is no additional information. If connecting to the service provider requires additional information and extraInfo is null or contains wrong information, an IllegalArgumentException is thrown.

Parameters:

name - the name of the service provider to be instantiated, null to request default provider

type - the type of the requested service

extraInfo - additional information, for example, username or URL that is sent to the service provider, null if no additional information is needed

Returns:

a new instance of the requested service provider, null if no service provider fulfils the given name and type requirements or if additional information is needed, but it was not provided with the extraInfo parameter

Throws:

java.lang.IllegalArgumentException - if type is not one of the constant defined in this class or if additional information is needed, but it was not provided with the extraInfo parameter

ServiceException - if connection to the service provider could not be made