javax.microedition.location.services
Class ProviderCapabilities

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

public class ProviderCapabilities
extends java.lang.Object

This class collects the information about the capabilities of a service provider. This information includes the type and the name of the service and additional information about the capabilities of the service provider. One instance of this class collects capabilities of one service type. So even if the same service provider supports multiple service types, like mapping and navigation, it must have two separate instances of this class for the capabilities of the services. With this information an application is able to decide which service provider to use when requesting services. This class also offers a method for an application to check if the service provider supports needed geographic area. This will also help in the service provider selection.

Since the capabilities of different service providers vary, this class offers a mechanism to store the capabilities as key and value pairs. For this reason, the class defines a set of key values for the capabilities that were identified when writing this specification. The service provider must support the general property keys (SUPPORTED_LANGUAGES, SUPPORTS_CONFIGURATION_UI, SUPPORTED_LENGTH_UNITS and USES_NETWORK) and all the service specific properties starting with the service prefix defined in this class. The service provider may add new property keys for new capabilities specific to that service provider. In this case the key name must begin with a reverse domain name of the API implementation or of the service provider. The service provider is also responsible for specifying the object types of these additional properties in their own documentation. If the service provider do not support additional property keys defined in this class, these keys must not be returned in getPropertyKeys method.

Since:

2.0

Field Summary

static java.lang.String	GEO_SUPPORTS_GEOCODING Property key value for an application to query does the service provider support geocoding service.
static java.lang.String	GEO_SUPPORTS_REVERSE_GEOCODING Property key value for an application to query does the service provider support reverse geocoding service.
static java.lang.String	MAP_CONTINUOUS_ROTATION Constant to indicate that the map service provider supports continuous map rotation.
static java.lang.String	MAP_DISCRETE_ROTATION Constant to indicate that the map service provider supports map rotation to discrete azimuths.
static java.lang.String	MAP_NO_ROTATION Constant to indicate that the map service provider does not support map rotation.
static java.lang.String	MAP_PROJECTION Property key value for an application to query what is the map projection the map service provider uses.
static java.lang.String	MAP_SUPPORTED_LAYERS Property key value for an application to query what are the map layers the map service provider supports.
static java.lang.String	MAP_SUPPORTED_MAP_BASES Property key value for an application to query what are the map bases the map service provider supports.
static java.lang.String	MAP_SUPPORTED_ROTATION_AZIMUTHS Property key value for an application to query what azimuth values the map service provider supports in the rotation.
static java.lang.String	MAP_SUPPORTS_MAP_CREATION Property key value for an application to query is the map service provider able to create Map objects.
static java.lang.String	MAP_SUPPORTS_MAP_ROTATION Property key value for an application to query is the map service provider able to rotate maps.
static java.lang.String	MAP_SUPPORTS_TRANSPARENT_BACKGROUND Property key value for an application to query if the map service provider supports generating Map objects with transparent background.
static java.lang.String	NAV_SUPPORTED_FEATURES_TO_AVOID Property key value for an application to query what are the features that could be avoided the navigation service provider supports.
static java.lang.String	NAV_SUPPORTED_ROUTE_TYPES Property key value for an application to query what are the route types the navigation service provider supports.
static java.lang.String	NAV_SUPPORTED_TRANSPORT_MODES Property key value for an application to query what are the transport modes the navigation service provider supports.
static java.lang.String	NAV_SUPPORTS_DYNAMIC_INSTRUCTIONS Property key value for an application to query whether the navigation service provider is able to dynamically trigger instructions based on the current location.
static java.lang.String	NAV_SUPPORTS_LOCATION_RETRIEVAL Property key value for an application to query whether the navigation service provider is able to retrieve current location during navigation.
static java.lang.String	NAV_SUPPORTS_ROUTE_GENERATION Property key value for an application to query does the navigation service provider support route generation.
static java.lang.String	SUPPORTED_LANGUAGES Property key value for an application to query what languages does the service provider support.
static java.lang.String	SUPPORTED_LENGTH_UNITS Property key value for an application to query what units service provider supports.
static java.lang.String	SUPPORTS_CONFIGURATION_UI Property key value for an application to query if the service provider has a separate configuration UI that can be shown to the user.
static java.lang.String	USES_NETWORK Property key value for an application to query if the service provider uses network when performing the service request.

Method Summary

java.lang.String[]	getPropertyDisplayName(java.lang.String propertyKey, boolean getValue, java.lang.String languageTag) Returns the presentation name for a given property.
java.lang.String[]	getPropertyKeys() Returns the list of the property keys that have been set.
java.lang.Object	getPropertyValue(java.lang.String key) Returns the value of the requested property as an Object.
java.lang.String	getServiceProviderDescription(java.lang.String languageTag) Returns a description for the service provider.
java.lang.String	getServiceProviderName() Returns the name of the service provider.
int	getServiceProviderType() Returns the service type of this instance of the service provider capabilities.
boolean	supportsArea(RectangleGeographicArea area) With this method an application may check if a service provider has a specified information about the given geographical area.

Methods inherited from class java.lang.Object

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

Field Detail

SUPPORTED_LANGUAGES

public static final java.lang.String SUPPORTED_LANGUAGES

Property key value for an application to query what languages does the service provider support. The value of this property is String[] that contains an array of supported languages as language tags defined in RFC 4646 (see reference [RFC4646]) and their simplified formats as defined in RFC 4647 (see reference [RFD4647]). A service provider must have one default language. The default language must be set as the first item to the array of supported languages.

See Also:

Constant Field Values

USES_NETWORK

public static final java.lang.String USES_NETWORK

Property key value for an application to query if the service provider uses network when performing the service request. Network access is needed if, for example, a navigation service provider does the route calculation on a remote server using data connection. Use of network may create financial cost to the user. The value of this property is Boolean.

See Also:

Constant Field Values

SUPPORTS_CONFIGURATION_UI

public static final java.lang.String SUPPORTS_CONFIGURATION_UI

Property key value for an application to query if the service provider has a separate configuration UI that can be shown to the user. The value of this property is Boolean.

See Also:

Constant Field Values

SUPPORTED_LENGTH_UNITS

public static final java.lang.String SUPPORTED_LENGTH_UNITS

Property key value for an application to query what units service provider supports. The value of this property is String[] that contains an array of supported length units. The possible unit values are "METRIC", "IMPERIAL" and "NAUTICAL". In metric system the length unit is meter, in imperial system yard and in nautical system nautical mile. The service provider must support at least one length unit.

See Also:

Constant Field Values

GEO_SUPPORTS_GEOCODING

public static final java.lang.String GEO_SUPPORTS_GEOCODING

Property key value for an application to query does the service provider support geocoding service. The value of this property is Boolean.

See Also:

Constant Field Values

GEO_SUPPORTS_REVERSE_GEOCODING

public static final java.lang.String GEO_SUPPORTS_REVERSE_GEOCODING

Property key value for an application to query does the service provider support reverse geocoding service. The value of this property is Boolean.

See Also:

Constant Field Values

MAP_PROJECTION

public static final java.lang.String MAP_PROJECTION

Property key value for an application to query what is the map projection the map service provider uses. The value of this property is String that contains the name of the projection as defined in EPSG Geodetic Parameter Dataset (see reference [EPSG]).

See Also:

Constant Field Values

MAP_SUPPORTS_MAP_CREATION

public static final java.lang.String MAP_SUPPORTS_MAP_CREATION

Property key value for an application to query is the map service provider able to create Map objects. The value of this property is Boolean.

See Also:

Constant Field Values

MAP_SUPPORTS_MAP_ROTATION

public static final java.lang.String MAP_SUPPORTS_MAP_ROTATION

Property key value for an application to query is the map service provider able to rotate maps. This applies to both MapServiceProvider.displayMap service request and in Map objects. The value of this property is String. The possible values are MAP_NO_ROTATION, MAP_CONTINUOUS_ROTATION and MAP_DISCRETE_ROTATION defined in this class. If discrete rotation is supported, the possible azimuth values can be queried with MAP_SUPPORTED_ROTATION_AZIMUTHS property key.

See Also:

Constant Field Values

MAP_SUPPORTED_ROTATION_AZIMUTHS

public static final java.lang.String MAP_SUPPORTED_ROTATION_AZIMUTHS

Property key value for an application to query what azimuth values the map service provider supports in the rotation. The azimuth values are given as degrees from the true north. The value of this property is int[] that contains an array of supported azimuths. The azimuths must be given in ascending order. If the rotation is not supported (MAP_NO_ROTATION) or it is continuous (MAP_CONTINUOUS_ROTATION), the value of this property must be an empty array.

See Also:

Constant Field Values

MAP_SUPPORTS_TRANSPARENT_BACKGROUND

public static final java.lang.String MAP_SUPPORTS_TRANSPARENT_BACKGROUND

Property key value for an application to query if the map service provider supports generating Map objects with transparent background. The value of this property is Boolean.

See Also:

Constant Field Values

MAP_SUPPORTED_MAP_BASES

public static final java.lang.String MAP_SUPPORTED_MAP_BASES

Property key value for an application to query what are the map bases the map service provider supports. The value of this property is String[] that contains an array of supported map bases. Map bases may be, for example, regular map, satellite image, aerial image, terrain map or only latitude and longitude grid. The map service provider must support at least one map base.

See Also:

Constant Field Values

MAP_SUPPORTED_LAYERS

public static final java.lang.String MAP_SUPPORTED_LAYERS

Property key value for an application to query what are the map layers the map service provider supports. The value of this property is String[] that contains an array of supported map layers. These layers may be, for example, streets, highways, public transportation lines, water areas, parks, buildings, sidewalks or administrative areas. These layers correspond to the layers used in OpenLS specification (see reference [OpenLS]). The map service provider must support at least one map layer. The layers included into this property must be supported on top of all supported map bases.

See Also:

Constant Field Values

MAP_NO_ROTATION

public static final java.lang.String MAP_NO_ROTATION

Constant to indicate that the map service provider does not support map rotation.

See Also:

Constant Field Values

MAP_CONTINUOUS_ROTATION

public static final java.lang.String MAP_CONTINUOUS_ROTATION

Constant to indicate that the map service provider supports continuous map rotation. With continuous rotation the map can be rotated to any azimuth.

See Also:

Constant Field Values

MAP_DISCRETE_ROTATION

public static final java.lang.String MAP_DISCRETE_ROTATION

Constant to indicate that the map service provider supports map rotation to discrete azimuths. The azimuth values that the map can be rotated to can be queried with property key MAP_SUPPORTED_ROTATION_AZIMUTHS.

See Also:

Constant Field Values

NAV_SUPPORTS_ROUTE_GENERATION

public static final java.lang.String NAV_SUPPORTS_ROUTE_GENERATION

Property key value for an application to query does the navigation service provider support route generation. The value of this property is Boolean.

See Also:

Constant Field Values

NAV_SUPPORTED_ROUTE_TYPES

public static final java.lang.String NAV_SUPPORTED_ROUTE_TYPES

Property key value for an application to query what are the route types the navigation service provider supports. The value of this property is String[] that contains an array of supported route types. Some of the basic route types are defined as constants in NavigationServicePreferences class and they start with prefix ROUTE_. If a service provider supports other route types than those listed in NavigationServicePreferences they are also included into the returned array. The navigation service provider must support at least one route type.

See Also:

Constant Field Values

NAV_SUPPORTED_TRANSPORT_MODES

public static final java.lang.String NAV_SUPPORTED_TRANSPORT_MODES

Property key value for an application to query what are the transport modes the navigation service provider supports. The value of this property is String[] that contains an array of supported transport modes. Some of the basic transport modes are defined as constants in NavigationServicePreferences class and they start with prefix TRANSPORT_. If a service provider supports other transport modes than those listed in NavigationServicePreferences they are also included into the returned array. The navigation service provider must support at least one transport mode.

See Also:

Constant Field Values

NAV_SUPPORTED_FEATURES_TO_AVOID

public static final java.lang.String NAV_SUPPORTED_FEATURES_TO_AVOID

Property key value for an application to query what are the features that could be avoided the navigation service provider supports. For example toll ways and bridges could be these features. The value of this property is String[] that contains an array of avoid features. If the navigation service provider does not support any features to avoid, an empty array must be used as the value of this property.

These features to be avoided may be shown to the user. The service provider must support the names of features in all the languages it supports. The localized names of the features can be retrieved with method getPropertyDisplayName.

Some navigation service provider may be able to determine whether traveling routes with different transport modes creates cost to the user. Cost may be a toll road or a bridge fee. If navigation service providers are able to determine cost, they should define cost as one of the avoid features. This way an application may request routes that do not create any cost to the user.

See Also:

Constant Field Values

NAV_SUPPORTS_LOCATION_RETRIEVAL

public static final java.lang.String NAV_SUPPORTS_LOCATION_RETRIEVAL

Property key value for an application to query whether the navigation service provider is able to retrieve current location during navigation. The value of this property is Boolean.

See Also:

Constant Field Values

NAV_SUPPORTS_DYNAMIC_INSTRUCTIONS

public static final java.lang.String NAV_SUPPORTS_DYNAMIC_INSTRUCTIONS

Property key value for an application to query whether the navigation service provider is able to dynamically trigger instructions based on the current location. The value of this property is Boolean.

See Also:

Constant Field Values

Method Detail

getServiceProviderType

public int getServiceProviderType()

Returns the service type of this instance of the service provider capabilities. One instance of ProviderCapabilities class collects capabilities of one service type. The types are defined as constants in the ProviderManager class.

Returns:

the type the service provider capabilities

getServiceProviderName

public java.lang.String getServiceProviderName()

Returns the name of the service provider. This name should be descriptive, since the application may show it to the user.

Returns:

the name of the service provider

getServiceProviderDescription

public java.lang.String getServiceProviderDescription(java.lang.String languageTag)

Returns a description for the service provider. This description should be descriptive, since the application may show this to the user. The service provider description must be returned in the language given in languageTag parameter. The possible language tag values can be retrieved with ProviderCapabilities.getPropertyValue method using SUPPORTED_LANGUAGES property key.

Parameters:

languageTag - the language in which the description is requested

Returns:

the description of the service provider, null if description is not available in requested language

Throws:

java.lang.IllegalArgumentException - if languageTag is not supported by the service provider

java.lang.NullPointerException - if languageTag is null

getPropertyValue

public java.lang.Object getPropertyValue(java.lang.String key)

Returns the value of the requested property as an Object. The application must cast the returned value into right object type defined in the property key description. If null is passed in as the key a NullPointerException is thrown.

The property keys are identified by the values of the String constants defined in this class and extended by the service provider. The input parameter does not need to be the instance of the String defined by the constant field.

Parameters:

key - the identifier of the property

Returns:

value of the property, null if the key is not defined

Throws:

java.lang.NullPointerException - if key is null

getPropertyKeys

public java.lang.String[] getPropertyKeys()

Returns the list of the property keys that have been set. The actual property value can be retrieved with method getPropertyValue(key). The service provider must support the general property keys (SUPPORTED_LANGUAGES, SUPPORTS_CONFIGURATION_UI, SUPPORTED_LENGTH_UNITS and USES_NETWORK) and all the service specific properties starting with the service prefix defined in this class. Additional property keys are included based on the capabilities of the service provider and they must have values defined.

Returns:

key values of assigned properties

supportsArea

public boolean supportsArea(RectangleGeographicArea area)

With this method an application may check if a service provider has a specified information about the given geographical area. The information may be geocoding data, maps or navigation information depending on the type of the service provider. With this method the application can check the support for needed areas before connecting to any particular service provider. The method must return true only if the whole given geographic area is supported by the service provider.

Parameters:

area - geographical area for which the information is needed

Returns:

true if the service provider has information for the requested geographical area, false

Throws:

java.lang.NullPointerException - if area is null

getPropertyDisplayName

public java.lang.String[] getPropertyDisplayName(java.lang.String propertyKey,
                                                 boolean getValue,
                                                 java.lang.String languageTag)

Returns the presentation name for a given property. These display names can be used in the user interface. An application may request either a property key or a String or String array property value. The display name for the property value is requested by setting the getValue parameter to true. If the requested property value is an array, the array must be returned in the same order as with getPropertyValue method. If getValue is false, the display name of the property key is returned. If the value of requested property key is not a String or a String array or the propertyKey or languageTag is not supported by the service provider, an IllegalArgumentException is thrown.

The presentation names must be returned in the language given in languageTag parameter. The possible language tag values can be retrieved with ProviderCapabilities.getPropertyValue method using SUPPORTED_LANGUAGES property key.

The service provider implementations must support presentation names for all the service capabilities it supports. This means that if a service provider defines new provider specific capability, the display name for it must also be supported. The service provider must support presentation names for String property values for all capabilities.

Parameters:

propertyKey - the property key which display name is queried

getValue - true if the property value should be returned, else false

languageTag - the language in which the display name is requested

Returns:

the display name of the requested property key or property key value

Throws:

java.lang.IllegalArgumentException - if getValue is set to true and the value of the given propertyKey is not a String or a String array or if languageTag or propertyKey is not supported by the service provider

java.lang.NullPointerException - if propertyKey or languageTag is null