javax.microedition.location.services
Class MapServicePreferences

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

public class MapServicePreferences
extends ServicePreferences

This class captures the preferences related to map service provider. The preferences include, for example, the type of the map, is selecting items from the map allowed, what kind of items can be selected, information about the map layers and instruction shown to the user.

Some of these preferences are valid only on the asynchronous service requests, that is in MapServiceProvider.displayMap methods. These preferences are allowing selection from the map, selecting multiple items from the map and is the selection order saved. The map service provider must support selecting all items from the map, selection of multiple items and saving the selection order.

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 map 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 map service provider can be retrieved with ServicePreferences.getAdditionalPropertyKeys method.

Since:

2.0

Field Summary

static int	NO_SELECTION_ALLOWED Constant for not allowing any selections from a map.
static int	SELECT_CIRCLE Constant for selecting CircleGeographicArea object(s) on a map.
static int	SELECT_COORDINATES Constant for selecting Coordinates object(s) on a map.
static int	SELECT_LANDMARKS Constant for selecting Landmark object(s) on a map.
static int	SELECT_NEW_CIRCLE Constant for selecting new CircleGeographicArea object(s) from a map.
static int	SELECT_NEW_COORDINATES Constant for selecting new Coordinates object(s) on a map.
static int	SELECT_NEW_LANDMARKS Constant for selecting new Landmark object(s) on a map.
static int	SELECT_NEW_POLYGON Constant for selecting new PolygonGeographicArea object(s) from a map.
static int	SELECT_NEW_RECTANGLE Constant for selecting new RectangleGeographicArea object(s) from a map.
static int	SELECT_NEW_ROUTE Constant for selecting new Route object(s) from a map.
static int	SELECT_POLYGON Constant for selecting PolygonGeographicArea object(s) on a map.
static int	SELECT_RECTANGLE Constant for selecting RectangleGeographicArea object(s) from a map.
static int	SELECT_ROUTE Constant for selecting Route object(s) from a map.

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	getAllowSelection() With this method an application can query if the map service provider must allow the user to select items from a displayed map.
java.lang.String[]	getLayers() With this method an application can query what are the layers that must be included into the map on top of the map base.
java.lang.String	getMapBase() Returns the preference for map base to be used in the service request.
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	getUserInstruction() With this method an application can query what instruction is be shown to the user during asynchronous service request.
boolean	isBackgroundTransparency() With this method an application can query if background transparency must be used on by the map service provider when generating Map objects.
boolean	isMultipleSelected() With this method an application can query if the user is able to select multiple items from a displayed map.
boolean	isSelectionOrderSaved() With this method an application can query if the order of the items selected from a map is saved or not.
void	setAllowSelection(int allowSelection) With this method an application controls whether the map service provider must allow the user to select items from a displayed map or not.
void	setBackgroundTransparency(boolean transparentBackground) This method allows an application to request maps to be generated with a transparent background.
void	setLayers(java.lang.String[] layers) With this method an application can set map layers that must be included on map service provider service requests.
void	setMapBase(java.lang.String mapBase) This method is used to set the preferences for the map base in the map service provider service requests.
void	setMultipleSelected(boolean allowed) With this method an application controls whether the map service provider must allow the user to select multiple items from a displayed map or not.
void	setPropertyValue(java.lang.String key, java.lang.Object value) Sets the property value for the specified key.
void	setSelectionOrderSaved(boolean saved) With this is method an application controls whether the map service provider must preserve the order of item selected from a map.
void	setUserInstruction(java.lang.String instruction) This method allows an application set instruction to the user that a service provider must show to the user when performing asynchronous service request.

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

NO_SELECTION_ALLOWED

public static final int NO_SELECTION_ALLOWED

Constant for not allowing any selections from a map.

See Also:

Constant Field Values

SELECT_RECTANGLE

public static final int SELECT_RECTANGLE

Constant for selecting RectangleGeographicArea object(s) from a map. Selection is done from the existing items on the map.

See Also:

Constant Field Values

SELECT_CIRCLE

public static final int SELECT_CIRCLE

Constant for selecting CircleGeographicArea object(s) on a map. Selection is done from the existing items on the map.

See Also:

Constant Field Values

SELECT_POLYGON

public static final int SELECT_POLYGON

Constant for selecting PolygonGeographicArea object(s) on a map. Selection is done from the existing items on the map.

See Also:

Constant Field Values

SELECT_LANDMARKS

public static final int SELECT_LANDMARKS

Constant for selecting Landmark object(s) on a map. Selection is done from the existing items on the map.

See Also:

Constant Field Values

SELECT_COORDINATES

public static final int SELECT_COORDINATES

Constant for selecting Coordinates object(s) on a map. Selection is done from the existing items on the map.

See Also:

Constant Field Values

SELECT_ROUTE

public static final int SELECT_ROUTE

Constant for selecting Route object(s) from a map. Selection is done from the existing items on the map.

See Also:

Constant Field Values

SELECT_NEW_RECTANGLE

public static final int SELECT_NEW_RECTANGLE

Constant for selecting new RectangleGeographicArea object(s) from a map. Selection of the rectangle is made freely by the user.

See Also:

Constant Field Values

SELECT_NEW_CIRCLE

public static final int SELECT_NEW_CIRCLE

Constant for selecting new CircleGeographicArea object(s) from a map. Selection of the circle is made freely by the user.

See Also:

Constant Field Values

SELECT_NEW_POLYGON

public static final int SELECT_NEW_POLYGON

Constant for selecting new PolygonGeographicArea object(s) from a map. Selection of the polygon is made freely by the user.

See Also:

Constant Field Values

SELECT_NEW_LANDMARKS

public static final int SELECT_NEW_LANDMARKS

Constant for selecting new Landmark object(s) on a map. Selection of the landmark is made freely by the user.

See Also:

Constant Field Values

SELECT_NEW_COORDINATES

public static final int SELECT_NEW_COORDINATES

Constant for selecting new Coordinates object(s) on a map. The selection of the coordinate is made freely by the user.

See Also:

Constant Field Values

SELECT_NEW_ROUTE

public static final int SELECT_NEW_ROUTE

Constant for selecting new Route object(s) from a map. The selection of the route is made freely by the user.

See Also:

Constant Field Values

Method Detail

getMapBase

public java.lang.String getMapBase()

Returns the preference for map base to be used in the service request. The base of the map can be, for example, regular map, satellite image, aerial image, terrain map or only latitude and longitude grid. The map bases supported by the map service provider can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.MAP_SUPPORTED_MAP_BASES property key. The method returns the default value set by the service provider or value set with method setMapBase.

Returns:

the map base preference for service requests

setMapBase

public void setMapBase(java.lang.String mapBase)

This method is used to set the preferences for the map base in the map service provider service requests. The base of the map can be, for example, regular map, satellite image, aerial image, terrain map or only latitude and longitude grid. The map bases supported by the map service provider can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.MAP_SUPPORTED_MAP_BASES property key.

Parameters:

mapBase - the preferred map base in service requests

Throws:

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

getLayers

public java.lang.String[] getLayers()

With this method an application can query what are the layers that must be included into the map on top of the map base. These layers can be, for example, streets, highways, public transportation lines, water areas, parks, buildings, sidewalks or administrative areas. The names of map layers supported by the map service provider can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.MAP_SUPPORTED_LAYERS property key. The method returns the default layer names set by the service provider or values in the same order as set with method setLayers.

Returns:

an array of map layer names included into a displayed map, an empty array if no preference has been set

setLayers

public void setLayers(java.lang.String[] layers)

With this method an application can set map layers that must be included on map service provider service requests. These layers can be, for example, streets, highways, public transportation lines, water areas, parks, buildings, sidewalks or administrative areas. The names of map layers supported by the map service provider can be retrieved with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.MAP_SUPPORTED_LAYERS property key. An application does not need to worry about setting the layers into right order. The service provider defines in what order the layers are placed on top of the map base when the map is being rendered. Passing null or an empty array means that there are no layers on top of the map base.

Parameters:

layers - names of the map layers to be included into generated or displayed maps, may be null or an empty array

Throws:

java.lang.IllegalArgumentException - if layers contains elements that are not supported by the service provider

java.lang.NullPointerException - if layers contains null elements

getAllowSelection

public int getAllowSelection()

With this method an application can query if the map service provider must allow the user to select items from a displayed map. The method returns the default value set by the service provider or value set with method setAllowSelection.

Returns:

items to be selected form a map

setAllowSelection

public void setAllowSelection(int allowSelection)

With this method an application controls whether the map service provider must allow the user to select items from a displayed map or not. The method also defines which of the items on the map may be selected. The map service provider must support selecting all items from the map. If selecting items from the map is allowed by the application, the value of the allowSelection parameter must be one of the constants starting with prefix SELECT_ defined in this class or a bitwise (or) combination of them. If selection is not allowed at all, allowSelection parameter must be set to NO_SELECTION_ALLOWED.

If selecting new items from a map is allowed, meaning that one or more of bits starting with prefix SELECT_NEW_ is set, the items selected by the user are returned in MapServiceListener.selectionUpdated notification. If in this case some other selections (for example landmarks shown on the map) are allowed, those items that are inside the user selected areas are not selected and they must not be returned in addition to the user selected areas in the same notification.

This preference has effect only on MapServiceProvider.displayMap method call.

Parameters:

allowSelection - an element to be selected from a map, or a bitwise (or) combination of selectable items or NO_SELECTION_ALLOWED if selection is not allowed at all

Throws:

java.lang.IllegalArgumentException - is allowSelection is not NO_SELECTION_ALLOWED constant or one of the constants starting with prefix SELECT_ defined in this class or a bitwise (or) combination of them

isMultipleSelected

public boolean isMultipleSelected()

With this method an application can query if the user is able to select multiple items from a displayed map. The method returns the default value set by the service provider or value set with method setMultipleSelected. If the user is not allowed to select items from a map, meaning getAllowSelection method returns NO_SELECTION_ALLOWED, this preference has no meaning.

If this preference is set to true, the user may select multiple items within in one item type (areas, landmarks or coordinates) or items from several item types.

Returns:

true, if the user may select multiple items from a map, else false

setMultipleSelected

public void setMultipleSelected(boolean allowed)

With this method an application controls whether the map service provider must allow the user to select multiple items from a displayed map or not. If the user is not allowed to select items from a map, meaning that getAllowSelection method returns NO_SELECTION_ALLOWED, this preference has no meaning.

This preference has effect only on MapServiceProvider.displayMap method calls.

If this preference is set to true, the user may select multiple items within in one item type (areas, landmarks or coordinates) or items from several item types.

Parameters:

allowed - true, if the user may select multiple items from a map, else false

isSelectionOrderSaved

public boolean isSelectionOrderSaved()

With this method an application can query if the order of the items selected from a map is saved or not. The method returns the default value set by the service provider or value set with method setSelectionOrderSaved. The order of selection is saved within one item type (areas, landmarks or coordinates). If the user is not allowed to select items from a map, meaning getAllowSelection method returns NO_SELECTION_ALLOWED, or if multiple items may not be selected, meaning that getMultipleSelected method returns false, this preference has no meaning.

Returns:

true, if the selection order of items within the same item type is saved, else false

setSelectionOrderSaved

public void setSelectionOrderSaved(boolean saved)

With this is method an application controls whether the map service provider must preserve the order of item selected from a map. The order of selection is saved within one item type (areas, landmarks or coordinates). If the user is not allowed to select items from a map, meaning that getAllowSelection method returns NO_SELECTION_ALLOWED, or if multiple items may not be selected, meaning that getMultipleSelected method returns false, this preference has no meaning.

This preference has effect only on MapServiceProvider.displayMap method calls.

Parameters:

saved - true, if the selection order of items within the same item type is saved, else false

getUserInstruction

public java.lang.String getUserInstruction()

With this method an application can query what instruction is be shown to the user during asynchronous service request. The method returns the value default set by the service provider or value set with method setUserInstruction.

Returns:

instruction to be shown to the user in asynchronous service request, an empty String if preference has not been set

setUserInstruction

public void setUserInstruction(java.lang.String instruction)

This method allows an application set instruction to the user that a service provider must show to the user when performing asynchronous service request. Passing null or an empty String means that there is no instruction to be shown. This instruction is not localized by the service provider and therefore the localization is in responsibility of the application.

This preference has effect only on MapServiceProvider.displayMap method call.

Parameters:

instruction - guidance to the user during asynchronous service request, may be null or an empty String

isBackgroundTransparency

public boolean isBackgroundTransparency()

With this method an application can query if background transparency must be used on by the map service provider when generating Map objects. The support for transparent maps can be queried with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.MAP_SUPPORTS_TRANSPARENT_BACKGROUND property key. The method returns the default value set by the service provider or value set with method setBackgroundTransparency. This preference is applicable only in synchronous map service requests.

Returns:

true, if maps with transparent background has been requested, else false

setBackgroundTransparency

public void setBackgroundTransparency(boolean transparentBackground)

This method allows an application to request maps to be generated with a transparent background. The support for transparent maps can be queried with ProviderCapabilities.getPropertyValue method using ProviderCapabilities.MAP_SUPPORTS_TRANSPARENT_BACKGROUND property key. By setting the transparentBackground parameter to true, the map service provider must generate a Map object that has a transparent background. This preference is applicable only in synchronous map service requests. More detailed transparency settings may be handled in the service provider specific configuration UIs. If the service provider does not support transparent background and true is passed in as the parameter, an IllegalArgumentException is thrown.

Parameters:

transparentBackground - true if transparent background is requested, false if background is opaque

Throws:

java.lang.IllegalArgumentException - if transparentBackgournd is true and the service provider does not support transparent background at all

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