javax.microedition.location.services
Class GeocodingServicePreferences

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

public class GeocodingServicePreferences
extends ServicePreferences

This class captures the preferences related to geocoding service provider. The preferences include, for example, controlling number of matches and timeout.

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 geocoding service provider may also add new service preferences. The mechanism to define additional preference properties is provided in the ServicePreferences superclass. Property keys for the additional preferences defined by each geocoding service provider can be retrieved with ServicePreferences.getAdditionalPropertyKeys method.

Since:

2.0

Method Summary

java.lang.String[]	getAdditionalPropertyKeys() Returns the list of the property keys for additional preferences that have been defined for a service provider.
int	getMaximumNumberOfMatches() With this method an application can query the maximum number of matches set for the geocoding service provider.
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.
int	getTimeout() Returns the timeout preference that has been set for the service request.
boolean	isExactMatch() With this method an application can query if the geocoding service provider must find results that match to all the given information in the service requests or not.
void	setExactMatch(boolean exactMatch) With this method an application can query if the geocoding service provider must find results that match exactly to the given information in the service requests or not.
void	setMaximumNumberOfMatches(int maxNumberOfMatches) This method controls the maximum number of matched returned from the geocoding service provider.
void	setPropertyValue(java.lang.String key, java.lang.Object value) Sets the property value for the specified key.
void	setTimeout(int timeout) This method is used to set the preferences for a maximum timeout of the geocoding service provider service requests.

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

Method Detail

setTimeout

public void setTimeout(int timeout)

This method is used to set the preferences for a maximum timeout of the geocoding service provider service requests.

When this timeout is reached and the service request has not been completed, the API implementation must abort the service request. The blocking method in GeocodingServiceProvider throw an InterruptedException when the timeout is reached.

Parameters:

timeout - the maximum execution time for the service request in seconds

Throws:

java.lang.IllegalArgumentException - if timeout <= 0

getTimeout

public int getTimeout()

Returns the timeout preference that has been set for the service request. The method returns the default value set by the service provider or value set with method setTimeout.

Returns:

the maximum service request execution time in seconds

setExactMatch

public void setExactMatch(boolean exactMatch)

With this method an application can query if the geocoding service provider must find results that match exactly to the given information in the service requests or not. Exact match means that all fields in the address or the criterion parameters in the geocode methods must match exactly in the results. If the fields in the address and the criterion parameters can be substrings in the results, exactMatch must be set to false. Characters '*' and '?' do not have any special meaning. If the preference is to find exact matches and there are no results, the service requests return an empty array.

Parameters:

exactMatch - true, if exact matches are requested, else false

isExactMatch

public boolean isExactMatch()

With this method an application can query if the geocoding service provider must find results that match to all the given information in the service requests or not. If the given information in the service request is incomplete, the service provider may not find results that match in all fields to it, but several near matches. If the exactMatch is set to true, the all the fields in the given address info or the given criterion parameters in geocode methods must match exactly in the results. If false is used parameters may be substrings. The method returns the default value set by the service provider or value set with method setExactMatch.

Returns:

true, if exact matches must be found, else false

setMaximumNumberOfMatches

public void setMaximumNumberOfMatches(int maxNumberOfMatches)

This method controls the maximum number of matched returned from the geocoding service provider. In some cases the given information is inadequate and the geocoding service provider is not able to find only one result, only matches near by. The geocoding service provider must return the matches in the relevance order. However that order is relevance is determined by the geocoding service provider.

Parameters:

maxNumberOfMatches - maximum number of matches expected by the application

Throws:

java.lang.IllegalArgumentException - if maxNumberOfMatches <= 0

getMaximumNumberOfMatches

public int getMaximumNumberOfMatches()

With this method an application can query the maximum number of matches set for the geocoding service provider. The method returns the default value set by the service provider or value set with method setMaximumNumberOfMatches.

Returns:

the maximum number of matches

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