javax.microedition.location.services
Class NavigationServicePreferences

java.lang.Object
  javax.microedition.location.services.ServicePreferences
      javax.microedition.location.services.NavigationServicePreferences

public class NavigationServicePreferences
extends ServicePreferences

This class encapsulates the preferences that are used when requesting routing services from a navigation service provider. The preferences include, for example, the type of the route, the transport mode used to travel the route and the areas and features to be avoided when calculating the route. The application can also control whether instructions and the map is shown or not. Controlling the showing of instructions and map is only applicable in the asynchronous service requests of the NavigationServiceProvider.

An application retrieves an instance of this class with method ServiceProvider.getServicePreferences. The returned instance contains either the default values or the last used values for all the preferences. An application can check the values with get* methods and it may change these default values with set* methods. The preference values may also be changed with the configuration UI of the service provider invoked with method ServiceProvider.showConfigurationUI.

The API implementation and a navigation service provider may also add new preferences. The mechanism to define additional preference properties is provided in the ServicePreferences superclass. Property keys for the additional preferences defined by each navigation service provider can be retrieved with ServicePreferences.getAdditionalPropertyKeys method.

Since:

2.0

Field Summary

static java.lang.String	ROUTE_FASTEST Route type for the fastest route.
static java.lang.String	ROUTE_LEAST_TRAFFIC Route type for a lower traffic route.
static java.lang.String	ROUTE_SCENIC Route type for a scenic route.
static java.lang.String	ROUTE_SHORTEST Route type for shortest route.
static java.lang.String	TRANSPORT_BICYCLE A constant for a bicycle transport mode.
static java.lang.String	TRANSPORT_CAR A constant for car transport mode.
static java.lang.String	TRANSPORT_PEDESTRIAN A constant for a pedestrian transport mode.
static java.lang.String	TRANSPORT_PUBLIC A constant for a public transport mode.

Method Summary

java.lang.String[]	getAdditionalPropertyKeys() Returns the list of the property keys for additional preferences that have been defined for a service provider.
GeographicArea[]	getAreasToAvoid() Returns an array of geographical areas that should be avoided in the navigation and route generation.
java.lang.String[]	getFeaturesToAvoid() Returns an array of features that must be avoided in the navigation and route generation.
java.lang.String[]	getPropertyDisplayName(java.lang.String propertyKey, boolean getValue, java.lang.String languageTag) Returns the presentation name for a given additional preference property.
java.lang.Object	getPropertyValue(java.lang.String key) Returns the value of the requested additional property as an Object.
java.lang.String	getRouteType() Returns the preferred route type set by the application for the navigation and route generation.
java.lang.String	getTransportMode() Returns the preferred transport mode set by the application for the navigation and route generation.
boolean	isInstructionsUsed() Returns the preference for showing the instructions on the service requests.
boolean	isMapShown() Returns the preference for showing the map on the service requests.
void	setAreasToAvoid(GeographicArea[] areas) Sets the areas to be avoided in navigation and route generation.
void	setFeaturesToAvoid(java.lang.String[] features) Sets the features to be avoided in navigation and in route generation.
void	setInstructionsUsed(boolean instructionsUsed) Sets the flag whether the navigation service provider must show the instructions in the service requests or not.
void	setMapShown(boolean mapShown) Sets the flag whether the navigation service provider must show the map in the service requests or not.
void	setPropertyValue(java.lang.String key, java.lang.Object value) Sets the property value for the specified key.
void	setRouteType(java.lang.String routeType) Sets the route type to be used in navigation and route generation.
void	setTransportMode(java.lang.String transportMode) Sets the transport mode to be used in navigation and route generation.

Methods inherited from class javax.microedition.location.services.ServicePreferences

getLanguage, getLengthUnit, setLanguage, setLengthUnit

Methods inherited from class java.lang.Object

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

Field Detail

TRANSPORT_CAR

public static final java.lang.String TRANSPORT_CAR

A constant for car transport mode.

See Also:

Constant Field Values

TRANSPORT_BICYCLE

public static final java.lang.String TRANSPORT_BICYCLE

A constant for a bicycle transport mode.

See Also:

Constant Field Values

TRANSPORT_PUBLIC

public static final java.lang.String TRANSPORT_PUBLIC

A constant for a public transport mode.

See Also:

Constant Field Values

TRANSPORT_PEDESTRIAN

public static final java.lang.String TRANSPORT_PEDESTRIAN

A constant for a pedestrian transport mode.

See Also:

Constant Field Values

ROUTE_FASTEST

public static final java.lang.String ROUTE_FASTEST

Route type for the fastest route.

See Also:

Constant Field Values

ROUTE_SHORTEST

public static final java.lang.String ROUTE_SHORTEST

Route type for shortest route.

See Also:

Constant Field Values

ROUTE_SCENIC

public static final java.lang.String ROUTE_SCENIC

Route type for a scenic route.

See Also:

Constant Field Values

ROUTE_LEAST_TRAFFIC

public static final java.lang.String ROUTE_LEAST_TRAFFIC

Route type for a lower traffic route.

See Also:

Constant Field Values

Method Detail

setInstructionsUsed

public void setInstructionsUsed(boolean instructionsUsed)

Sets the flag whether the navigation service provider must show the instructions in the service requests or not.

Parameters:

instructionsUsed - true, if the instructions are shown, else false

isInstructionsUsed

public boolean isInstructionsUsed()

Returns the preference for showing the instructions on the service requests. The method returns the default value set by the service provider or value set with method setInstructionsUsed.

Returns:

true, if the instructions are shown, else false

setMapShown

public void setMapShown(boolean mapShown)

Sets the flag whether the navigation service provider must show the map in the service requests or not.

Parameters:

mapShown - true, if the map is shown, else false

isMapShown

public boolean isMapShown()

Returns the preference for showing the map on the service requests. The method returns the default value set by the service provider or value set with method setMapShown.

Returns:

true, if the map is shown, else false

setRouteType

public void setRouteType(java.lang.String routeType)

Sets the route type to be used in navigation and route generation. Possible route type values can be retrieved with ProviderCapabilities.getPropertyValue(key) method using ProviderCapabilities.NAV_SUPPORTED_ROUTE_TYPES as the property key.

Parameters:

routeType - the type of the requested route

Throws:

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

java.lang.NullPointerException - if routeType is null

getRouteType

public java.lang.String getRouteType()

Returns the preferred route type set by the application for the navigation and route generation. Possible route type values can be retrieved with ProviderCapabilities.getPropertyValue(key) method using ProviderCapabilities.NAV_SUPPORTED_ROUTE_TYPES as the property key. The method returns the default value set by the service provider or value set with method setRouteType.

Returns:

the preferred route type

setTransportMode

public void setTransportMode(java.lang.String transportMode)

Sets the transport mode to be used in navigation and route generation. Possible transport mode values can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.NAV_SUPPORTED_TRANSPORT_MODES as the key value.

Parameters:

transportMode - transport mode to be used in navigation and route generation

Throws:

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

java.lang.NullPointerException - if transportMode is null

getTransportMode

public java.lang.String getTransportMode()

Returns the preferred transport mode set by the application for the navigation and route generation. Possible transport mode values can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.NAV_SUPPORTED_TRANSPORT_MODES as the key value. The method returns the default value set by the service provider or value set with method setTransportMode.

Returns:

the preferred transport mode

setFeaturesToAvoid

public void setFeaturesToAvoid(java.lang.String[] features)

Sets the features to be avoided in navigation and in route generation. These avoid features can be, for example, toll ways or bridges. Possible values for features to be avoided can be retrieved with ProviderCapabilities.getPropertyValue() method using ProviderCapabilities.NAV_SUPPORTED_FEATURES_TO_AVOID as the property key. Passing null or an empty array as the parameter means that there are no features to be avoided.

Parameters:

features - the features to be avoided in navigation and route generation

Throws:

java.lang.IllegalArgumentException - if features contains elements not supported by the service provider

java.lang.NullPointerException - if features contains null elements

getFeaturesToAvoid

public java.lang.String[] getFeaturesToAvoid()

Returns an array of features that must be avoided in the navigation and route generation. Possible values for features to be avoided can be retrieved with ProviderCapabilities.getPropertyValue() method using ProviderCapabilities.NAV_SUPPORTED_FEATURES_TO_AVOID as the property key. The returned array contains the default values set by the service provider or values set with method setFeaturesToAvoid.

Returns:

an array of the features to be avoided, an empty array if no features have been set

setAreasToAvoid

public void setAreasToAvoid(GeographicArea[] areas)

Sets the areas to be avoided in navigation and route generation. Passing null or an empty array as the parameter means that there are no areas to be avoided. An application can check if the service provider supports requested areas with method ProviderCapabilities.supportsArea.

Parameters:

areas - geographical areas to be avoided in navigation and route generation

Throws:

java.lang.NullPointerException - if areas contains null elements

getAreasToAvoid

public GeographicArea[] getAreasToAvoid()

Returns an array of geographical areas that should be avoided in the navigation and route generation. The returned array contains the default values set by the service provider or values set with method setAreasToAvoid.

Returns:

an array of the geographical area to be avoided, an empty array if no areas to be avoided have been set

getAdditionalPropertyKeys

public java.lang.String[] getAdditionalPropertyKeys()

Description copied from class: ServicePreferences

Returns the list of the property keys for additional preferences that have been defined for a service provider. The actual property value can be retrieved with getPropertyValue method and set with setPropertyValue method.

Specified by:

getAdditionalPropertyKeys in class ServicePreferences

Returns:

key values of properties for additional service preferences, an empty array if no properties have been defined

getPropertyValue

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

Description copied from class: ServicePreferences

Returns the value of the requested additional 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 retrieved with method getAdditionalPropertyKeys.

Specified by:

getPropertyValue in class ServicePreferences

Parameters:

key - the identifier of the property

Returns:

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

setPropertyValue

public void setPropertyValue(java.lang.String key,
                             java.lang.Object value)

Description copied from class: ServicePreferences

Sets the property value for the specified key. The additional key values can be retrieved with getAdditionalPropertyKeys method. Passing null as the property value, will reset the property to the default value.

Specified by:

setPropertyValue in class ServicePreferences

Parameters:

key - the key identifier of the property

value - the value of the property, null to reset the property

getPropertyDisplayName

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

Description copied from class: ServicePreferences

Returns the presentation name for a given additional preference property. These presentation 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 presentation 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 presentation name of the additional preference 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 additional preferences that it supports. This means that if a service provider defines new provider specific preference, the presentation name for it must also be supported. The service provider must support presentation names for String property values for all preferences.

Specified by:

getPropertyDisplayName in class ServicePreferences

Parameters:

propertyKey - the additional property key which presentation name is queried

getValue - true if the property value is 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