javax.microedition.location.services
Class ServicePreferences

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

Direct Known Subclasses:

GeocodingServicePreferences, MapServicePreferences, NavigationServicePreferences

public abstract class ServicePreferences
extends java.lang.Object

This class is a superclass for service preferences. The subclasses have dedicated method to control the service specific preferences. This class provides a mechanism to control additional service provider specific preferences. The service providers must define a default language and a length unit.

A service provider may add additional preferences for the services. This means that they must define new property keys for the new preferences. In this case the property key name must begin with a reverse domain name of the service provider. The new preferences must also have a default value. 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 preferences and therefore additional property keys, the getAdditionalPropertyKeys method must return an empty array.

Any asynchronous method taking ServicePreferences as a parameter must read all the needed settings from the ServicePreferences before the method call finishes and the methods must not modify given preferences in any way.

Since:

2.0

Method Summary

abstract java.lang.String[]	getAdditionalPropertyKeys() Returns the list of the property keys for additional preferences that have been defined for a service provider.
java.lang.String	getLanguage() Returns the language to be used in the service requests.
java.lang.String	getLengthUnit() Returns the preferred length unit to be used in the service provider UIs.
abstract java.lang.String[]	getPropertyDisplayName(java.lang.String propertyKey, boolean getValue, java.lang.String languageTag) Returns the presentation name for a given additional preference property.
abstract java.lang.Object	getPropertyValue(java.lang.String key) Returns the value of the requested additional property as an Object.
void	setLanguage(java.lang.String languageTag) This method is used to sets the language to be used in service requests.
void	setLengthUnit(java.lang.String lengthUnit) Sets the length unit to be used in the service provider UIs.
abstract void	setPropertyValue(java.lang.String key, java.lang.Object value) Sets the property value for the specified key.

Methods inherited from class java.lang.Object

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

Method Detail

setLanguage

public void setLanguage(java.lang.String languageTag)

This method is used to sets the language to be used in service requests. The possible language tag values can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.SUPPORTED_LANGUAGES property key. Passing null or an empty String as the languageTag sets the language to the default language of the service provider.

Parameters:

languageTag - the language to be used in service requests

Throws:

java.lang.IllegalArgumentException - if languageTag is not one of the values retrieved with ProviderCapabilities.getPropertyValue(SUPPORTED_LANGUAGES) method or null or an empty String

getLanguage

public java.lang.String getLanguage()

Returns the language to be used in the service requests. The possible language tag values can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.SUPPORTED_LANGUAGES property key. The method returns the default value set by the service provider or value set with method setLanguage.

Returns:

the preferred language, or the default language of the service provider if no preference for language has been set

setLengthUnit

public void setLengthUnit(java.lang.String lengthUnit)

Sets the length unit to be used in the service provider UIs. Possible length unit values can be retrieved with ProviderCapabilities.getPropertyValue(key) method key values SUPPORTED_LENGTH_UNITS. Passing null or an empty String as the lengthUnit sets the length unit to the default length unit of the service provider.

Parameters:

lengthUnit - the length unit to be used in service provider UIs

Throws:

java.lang.IllegalArgumentException - if lengthUnit is not one of the values retrieved with ProviderCapabilities.getPropertyValue(SUPPORTED_LENGTH_UNITS) method or null or an empty String

getLengthUnit

public java.lang.String getLengthUnit()

Returns the preferred length unit to be used in the service provider UIs. The possible length units can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.SUPPORTED_LENGTH_UNITS property key. The method returns the default value set by the service provider or value set with method setLengthUnit.

Returns:

the preferred length unit, or the default length unit of the service provider if no preference for length unit has been set

getAdditionalPropertyKeys

public abstract java.lang.String[] getAdditionalPropertyKeys()

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.

Returns:

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

getPropertyValue

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

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.

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

setPropertyValue

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

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.

Parameters:

key - the key identifier of the property

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

Throws:

java.lang.IllegalArgumentException - if key is not one of the additional keys or if value is invalid for the the specified key

java.lang.NullPointerException - if key is null

getPropertyDisplayName

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

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.

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

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