javax.microedition.location
Class Criteria

java.lang.Object
  javax.microedition.location.Criteria

public class Criteria
extends java.lang.Object

The criteria used for the selection of the location provider is defined by the values in this class. It is up to the implementation to provide a LocationProvider that can obtain locations constrained by these values.

Instances of Criteria are used by the application to indicate criteria for choosing the location provider in the LocationProvider.getInstance method call. The implementation considers the different criteria fields to choose the location provider that best fits the defined criteria. The different criteria fields do not have any defined priority order but the implementation uses some implementation specific logic to choose the location provider that can typically best meet the defined criteria.

However, the cost criteria field is treated differently from others. If the application has set the cost field to indicate that the returned location provider is not allowed to incur financial cost to the end user, the implementation must guarantee that the returned location provider does not incur cost.

If there is no available location provider that is able to meet all the specified criteria, the implementation is allowed to make its own best effort selection of a location provider that is closest to the defined criteria (provided that the cost criteria is met). However, an implementation is not required to return a location provider if it does not have any available provider that is able to meet these criteria or be sufficiently close to meeting them, where the judgement of sufficiently close is an implementation dependent best effort choice. It is left up to the implementation to consider what is close enough to the specified requirements that it is worth providing the location provider to the application.

The default values for the criteria fields are specified below in the table. The default values are always the least restrictive option that will match all location providers. Default values:

Default values for criteria fields

Criteria field	Default value
Horizontal accuracy	NO_REQUIREMENT
Vertical accuracy	NO_REQUIREMENT
Preferred response time	NO_REQUIREMENT
Power consumption	NO_REQUIREMENT
Cost allowed	true (allowed to cost)
Speed and course required	false (not required)
Altitude required	false (not required)
Address info required	false (not required)

An application is able to prioritize the criteria by setting priorities for the different criteria fields. The priorities are positive integer numbers and they are ordered from the smallest to the biggest. Number 1 means the highest priority and that is assigned always to cost criterion. Different criteria fields may have the same priority. An application may set the priorities to values in range [2,100]. If the criteria field does not have any priority set, the priority is set to by the implementation to a value bigger than 100. The priorities can be set with new variants of the set* methods. The prioritization of the criteria was added to Location API 2.0.

In order to better guide the implementation in the LocationProvider selection the application should set the priorities for the important criteria.

The implementation of this class only retains the values that are passed in using the set* methods. It does not try to validate the values of the parameters in any way. Applications may set any values it likes, even negative values, but the consequence may be that no matching LocationProvider can be created.

Field Summary

static int	NO_REQUIREMENT Constant indicating no requirements for the parameter.
static int	POWER_USAGE_HIGH Level indicating high power consumption allowed.
static int	POWER_USAGE_LOW Level indicating only low power consumption allowed.
static int	POWER_USAGE_MEDIUM Level indicating average power consumption allowed.

Constructor Summary

Criteria()
Constructs a Criteria object.

Method Summary

int	getHorizontalAccuracy() Returns the horizontal accuracy value set in this Criteria.
int	getPreferredPowerConsumption() Returns the preferred power consumption.
int	getPreferredResponseTime() Returns the preferred maximum response time.
int[]	getPriorities() Returns the priorities set for different criterion.
int	getVerticalAccuracy() Returns the vertical accuracy value set in this Criteria.
boolean	isAddressInfoRequired() Returns whether the location provider should be able to determine textual address information.
boolean	isAllowedToCost() Returns the preferred cost setting.
boolean	isAltitudeRequired() Returns whether the location provider should be able to determine altitude.
boolean	isSpeedAndCourseRequired() Returns whether the location provider should be able to determine speed and course.
void	setAddressInfoRequired(boolean addressInfoRequired) Deprecated. in version 2.0, replaced by setAddressInfoRequired(addressInfoRequired, priority)
void	setAddressInfoRequired(boolean addressInfoRequired, int priority) Sets whether the location provider should be able to determine textual address information.
void	setAltitudeRequired(boolean altitudeRequired) Deprecated. in version 2.0, replaced by setSpeedAndCourseRequired(altitudeRequired, priority)
void	setAltitudeRequired(boolean altitudeRequired, int priority) Sets whether the location provider should be able to determine altitude.
void	setCostAllowed(boolean costAllowed) Sets the preferred cost setting.
void	setHorizontalAccuracy(int accuracy) Deprecated. in version 2.0, replaced by setHorizontalAccuracy(accuracy, priority)
void	setHorizontalAccuracy(int accuracy, int priority) Sets the desired horizontal accuracy preference.
void	setPreferredPowerConsumption(int level) Deprecated. in version 2.0, replaced by setPreferredPowerConsumption(level, priority)
void	setPreferredPowerConsumption(int level, int priority) Sets the preferred maximum level of power consumption.
void	setPreferredResponseTime(int time) Deprecated. in version 2.0, replaced by setPreferredResponseTime(time, priority)
void	setPreferredResponseTime(int time, int priority) Sets the desired maximum response time preference.
void	setSpeedAndCourseRequired(boolean speedAndCourseRequired) Deprecated. in version 2.0, replaced by setSpeedAndCourseRequired(speedAndCourseRequired, priority)
void	setSpeedAndCourseRequired(boolean speedAndCourseRequired, int priority) Sets whether the location provider should be able to determine speed and course.
void	setVerticalAccuracy(int accuracy) Deprecated. in version 2.0, replaced by setVerticalAccuracy(accuracy, priority)
void	setVerticalAccuracy(int accuracy, int priority) Sets the desired vertical accuracy preference.

Methods inherited from class java.lang.Object

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

Field Detail

NO_REQUIREMENT

public static final int NO_REQUIREMENT

Constant indicating no requirements for the parameter.

See Also:

Constant Field Values

POWER_USAGE_LOW

public static final int POWER_USAGE_LOW

Level indicating only low power consumption allowed.

See Also:

Constant Field Values

POWER_USAGE_MEDIUM

public static final int POWER_USAGE_MEDIUM

Level indicating average power consumption allowed.

See Also:

Constant Field Values

POWER_USAGE_HIGH

public static final int POWER_USAGE_HIGH

Level indicating high power consumption allowed.

See Also:

Constant Field Values

Constructor Detail

Criteria

public Criteria()

Constructs a Criteria object. All the fields are set to the default values that are specified below in the specification of the set* methods for the parameters. The priorities of all fields (except cost) must be set by the implementation to a value bigger than 100.

Method Detail

getPreferredPowerConsumption

public int getPreferredPowerConsumption()

Returns the preferred power consumption.

Returns:

the power consumption level, should be one of NO_REQUIREMENT, POWER_USAGE_LOW, POWER_USAGE_MEDIUM,POWER_USAGE_HIGH.

See Also:

setPreferredPowerConsumption(int, int)

isAllowedToCost

public boolean isAllowedToCost()

Returns the preferred cost setting.

Returns:

the preferred cost setting, true if it is allowed to cost, false if it must be free of charge

See Also:

setCostAllowed(boolean)

getVerticalAccuracy

public int getVerticalAccuracy()

Returns the vertical accuracy value set in this Criteria.

Returns:

the accuracy in meters

See Also:

setVerticalAccuracy(int, int)

getHorizontalAccuracy

public int getHorizontalAccuracy()

Returns the horizontal accuracy value set in this Criteria.

Returns:

the horizontal accuracy in meters

See Also:

setHorizontalAccuracy(int, int)

getPreferredResponseTime

public int getPreferredResponseTime()

Returns the preferred maximum response time.

Returns:

the maximum response time in milliseconds

See Also:

setPreferredResponseTime(int, int)

isSpeedAndCourseRequired

public boolean isSpeedAndCourseRequired()

Returns whether the location provider should be able to determine speed and course.

Returns:

whether the location provider should be able to determine speed and course. true means that it should be able, false means that this is not required.

See Also:

setSpeedAndCourseRequired(boolean, int)

isAltitudeRequired

public boolean isAltitudeRequired()

Returns whether the location provider should be able to determine altitude.

Returns:

whether the location provider should be able to determine altitude, true means that it should be able, false means that this is not required.

See Also:

setAltitudeRequired(boolean, int)

isAddressInfoRequired

public boolean isAddressInfoRequired()

Returns whether the location provider should be able to determine textual address information.

Returns:

whether the location provider should be able to normally provide textual address information, true means that it should be able, false means that this is not required.

See Also:

setAddressInfoRequired(boolean, int)

setHorizontalAccuracy

public void setHorizontalAccuracy(int accuracy)

Deprecated. in version 2.0, replaced by setHorizontalAccuracy(accuracy, priority)

Sets the desired horizontal accuracy preference. Accuracy is measured in meters. The preference indicates maximum allowed typical 1-sigma standard deviation for the location method. Default is NO_REQUIREMENT, meaning no preference on horizontal accuracy. The priority of horizontal accuracy must be set by the API implementation to value bigger than 100.

Parameters:

accuracy - the preferred horizontal accuracy in meters

setHorizontalAccuracy

public void setHorizontalAccuracy(int accuracy,
                                  int priority)

Sets the desired horizontal accuracy preference. Accuracy is measured in meters. The preference indicates maximum allowed typical 1-sigma standard deviation for the location method. Default is NO_REQUIREMENT, meaning no preference on horizontal accuracy. The priority parameter sets the priority among other criteria fields for the horizontal accuracy. Priority is a positive integer value in range [2,100].

Parameters:

accuracy - the preferred horizontal accuracy in meters

priority - the priority of horizontal accuracy

Throws:

java.lang.IllegalArgumentException - if priority < 2 or if priority > 100

Since:

2.0

See Also:

getHorizontalAccuracy()

setVerticalAccuracy

public void setVerticalAccuracy(int accuracy)

Deprecated. in version 2.0, replaced by setVerticalAccuracy(accuracy, priority)

Sets the desired vertical accuracy preference. Accuracy is measured in meters. The preference indicates maximum allowed typical 1-sigma standard deviation for the location method. Default is NO_REQUIREMENT, meaning no preference on vertical accuracy. The priority of vertical accuracy must be set by the API implementation to value bigger than 100.

Parameters:

accuracy - the preferred vertical accuracy in meters

setVerticalAccuracy

public void setVerticalAccuracy(int accuracy,
                                int priority)

Sets the desired vertical accuracy preference. Accuracy is measured in meters. The preference indicates maximum allowed typical 1-sigma standard deviation for the location method. Default is NO_REQUIREMENT, meaning no preference on vertical accuracy. The priority parameter sets the priority among other criteria fields for the vertical accuracy. Priority is a positive integer value in range [2,100].

Parameters:

accuracy - the preferred vertical accuracy in meters

priority - the priority of vertical accuracy

Throws:

java.lang.IllegalArgumentException - if priority < 2 or if priority > 100

Since:

2.0

See Also:

getVerticalAccuracy()

setPreferredResponseTime

public void setPreferredResponseTime(int time)

Deprecated. in version 2.0, replaced by setPreferredResponseTime(time, priority)

Sets the desired maximum response time preference. This value is typically used by the implementation to determine a location method that typically is able to produce the location information within the defined time. Default is NO_REQUIREMENT, meaning no response time constraint. The priority of preferred response time must be set by the API implementation to value bigger than 100.

Parameters:

time - the preferred time constraint and timeout value in milliseconds

setPreferredResponseTime

public void setPreferredResponseTime(int time,
                                     int priority)

Sets the desired maximum response time preference. This value is typically used by the implementation to determine a location method that typically is able to produce the location information within the defined time. Default is NO_REQUIREMENT, meaning no response time constraint. The priority parameter sets the priority among other criteria fields for the response time. Priority is a positive integer value in range [2,100].

Parameters:

time - the preferred time constraint and timeout value in milliseconds

priority - the priority of response time

Throws:

java.lang.IllegalArgumentException - if priority < 2 or if priority > 100

Since:

2.0

See Also:

getPreferredResponseTime()

setPreferredPowerConsumption

public void setPreferredPowerConsumption(int level)

Deprecated. in version 2.0, replaced by setPreferredPowerConsumption(level, priority)

Sets the preferred maximum level of power consumption.

These levels are inherently indeterminable and depend on many factors. It is the judgement of the implementation that defines a positioning method as consuming low power or high power. Default is NO_REQUIREMENT, meaning power consumption is not a quality parameter. The priority of preferred power consumption must be set by the API implementation to value bigger than 100.

Parameters:

level - the preferred maximum level of power consumption, should be one of NO_REQUIREMENT, POWER_USAGE_LOW, POWER_USAGE_MEDIUM, POWER_USAGE_HIGH.

setPreferredPowerConsumption

public void setPreferredPowerConsumption(int level,
                                         int priority)

Sets the preferred maximum level of power consumption.

These levels are inherently indeterminable and depend on many factors. It is the judgement of the implementation that defines a positioning method as consuming low power or high power. Default is NO_REQUIREMENT, meaning power consumption is not a quality parameter. The priority parameter sets the priority among other criteria fields for the power consumption. Priority is a positive integer value in range [2,100].

Parameters:

level - the preferred maximum level of power consumption, should be one of NO_REQUIREMENT, POWER_USAGE_LOW, POWER_USAGE_MEDIUM, POWER_USAGE_HIGH.

priority - the priority of power consumption

Throws:

java.lang.IllegalArgumentException - if priority < 2 or if priority > 100

Since:

2.0

See Also:

getPreferredPowerConsumption()

setCostAllowed

public void setCostAllowed(boolean costAllowed)

Sets the preferred cost setting.

Sets whether the requests for location determination is allowed to incur any financial cost to the user of the terminal.

The default is true, i.e. the method is allowed to cost.

Note that the platform implementation may not always be able to know if a location method implies cost to the end user or not. If the implementation doesn't know, it must assume that it may cost. When this criteria is set to false, the implementation may only return a LocationProvider of which it is certain that using it for determining the location does not cause a per usage cost to the end user.

Parameters:

costAllowed - false if location determination is not allowed to cost, true if it is allowed to cost

See Also:

isAllowedToCost()

setSpeedAndCourseRequired

public void setSpeedAndCourseRequired(boolean speedAndCourseRequired)

Deprecated. in version 2.0, replaced by setSpeedAndCourseRequired(speedAndCourseRequired, priority)

Sets whether the location provider should be able to determine speed and course. Default is false. The priority of speed and course required must be set by the API implementation to value bigger than 100.

Parameters:

speedAndCourseRequired - If set to true, the LocationProvider is required to be able to normally determine the speed and course. If set the false, the speed and course are not required.

setSpeedAndCourseRequired

public void setSpeedAndCourseRequired(boolean speedAndCourseRequired,
                                      int priority)

Sets whether the location provider should be able to determine speed and course. Default is false. The priority parameter sets the priority among other criteria fields for the speed and course determination. Priority is a positive integer value in range [2,100].

Parameters:

speedAndCourseRequired - If set to true, the LocationProvider is required to be able to normally determine the speed and course. If set the false, the speed and course are not required.

priority - the priority of speed and course determination

Throws:

java.lang.IllegalArgumentException - if priority < 2 or if priority > 100

Since:

2.0

See Also:

isSpeedAndCourseRequired()

setAltitudeRequired

public void setAltitudeRequired(boolean altitudeRequired)

Deprecated. in version 2.0, replaced by setSpeedAndCourseRequired(altitudeRequired, priority)

Sets whether the location provider should be able to determine altitude. Default is false. The priority of altitude required must be set by the API implementation to value bigger than 100.

Parameters:

altitudeRequired - If set to true, the LocationProvider is required to be able to normally determine the altitude. If set the false, the altitude is not required.

setAltitudeRequired

public void setAltitudeRequired(boolean altitudeRequired,
                                int priority)

Sets whether the location provider should be able to determine altitude. Default is false. The priority parameter sets the priority among other criteria fields for altitude determination. Priority is a positive integer value in range [2,100].

Parameters:

altitudeRequired - If set to true, the LocationProvider is required to be able to normally determine the altitude. If set the false, the altitude is not required.

priority - the priority of altitude determination

Throws:

java.lang.IllegalArgumentException - if priority < 2 or if priority > 100

Since:

2.0

See Also:

isAltitudeRequired()

setAddressInfoRequired

public void setAddressInfoRequired(boolean addressInfoRequired)

Deprecated. in version 2.0, replaced by setAddressInfoRequired(addressInfoRequired, priority)

Sets whether the location provider should be able to determine textual address information. Setting this criteria to true implies that a location provider should be selected that is capable of providing the textual address information. This does not mean that every returned location instance necessarily will have all the address information filled in, though. The priority of address info required must be set by the API implementation to value bigger than 100.

Default is false.

Parameters:

addressInfoRequired - If set to true, the LocationProvider is required to be able to normally determine the textual address information. If set the false, the textual address information is not required.

setAddressInfoRequired

public void setAddressInfoRequired(boolean addressInfoRequired,
                                   int priority)

Sets whether the location provider should be able to determine textual address information. Setting this criteria to true implies that a location provider should be selected that is capable of providing the textual address information. This does not mean that every returned location instance necessarily will have all the address information filled in, though. The priority parameter sets the priority among other criteria fields for address information determination. Priority is a positive integer value in range [2,100].

Default is false.

Parameters:

addressInfoRequired - If set to true, the LocationProvider is required to be able to normally determine the textual address information. If set the false, the textual address information is not required.

priority - the priority of address information determination

Throws:

java.lang.IllegalArgumentException - if priority < 2 or if priority > 100

Since:

2.0

See Also:

isAddressInfoRequired()

getPriorities

public int[] getPriorities()

Returns the priorities set for different criterion. The returned array contains the criterion in the same order as defined in the table in the description of this class. Cost allowed has always the highest priority since it is the most important criterion and it is not included into the returned array.

Returns:

an array containing the priorities set for the different criterion

Since:

2.0