public class Criteria
extends java.lang.Object
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:
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) |
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. that can obtain
locations constrained by these values.
Modifier and Type | Field and Description |
---|---|
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 and Description |
---|
Criteria()
Constructs a Criteria object.
|
Modifier and Type | Method and Description |
---|---|
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 |
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)
Sets whether the location provider should be able to determine textual address
information.
|
void |
setAltitudeRequired(boolean altitudeRequired)
Sets whether the location provider should be able to determine altitude.
|
void |
setCostAllowed(boolean costAllowed)
Sets the preferred cost setting.
|
void |
setHorizontalAccuracy(int accuracy)
Sets the desired horizontal accuracy preference.
|
void |
setPreferredPowerConsumption(int level)
Sets the preferred maximum level of power consumption.
|
void |
setPreferredResponseTime(int time)
Sets the desired maximum response time preference.
|
void |
setSpeedAndCourseRequired(boolean speedAndCourseRequired)
Sets whether the location provider should be able to determine speed and course.
|
void |
setVerticalAccuracy(int accuracy)
Sets the desired vertical accuracy preference.
|
public static final int NO_REQUIREMENT
Note that because the API defines this as integer value 0, it means that it is impossible to tell the difference between values of zero, and those with no requirement. For example, there is no way to differentiate between "no error" and "no requirement on error".
public static final int POWER_USAGE_HIGH
public static final int POWER_USAGE_LOW
public static final int POWER_USAGE_MEDIUM
public Criteria()
public int getHorizontalAccuracy()
setHorizontalAccuracy(int)
public int getPreferredPowerConsumption()
#setPreferredPowerConsumption(int)}
public int getPreferredResponseTime()
setPreferredResponseTime(int)
public int getVerticalAccuracy()
public boolean isAddressInfoRequired()
setAddressInfoRequired(boolean)
public boolean isAllowedToCost()
#setCostAllowed(boolean)}
public boolean isAltitudeRequired()
setAltitudeRequired(boolean)
public boolean isSpeedAndCourseRequired()
setSpeedAndCourseRequired(boolean)
public void setAddressInfoRequired(boolean addressInfoRequired)
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.isAddressInfoRequired()
public void setAltitudeRequired(boolean altitudeRequired)
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.isAltitudeRequired()
public void setCostAllowed(boolean costAllowed)
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.
costAllowed
- false if location determination is not allowed to cost, true if it is
allowed to costisAllowedToCost()
public void setHorizontalAccuracy(int accuracy)
accuracy
- the preferred horizontal accuracy in metersgetHorizontalAccuracy()
public void setPreferredPowerConsumption(int level)
level
- the preferred maximum level of power consumption. Should be one of
NO_REQUIREMENT, POWER_USAGE_LOW, POWER_USAGE_MEDIUM, POWER_USAGE_HIGH.getPreferredPowerConsumption()
public void setPreferredResponseTime(int time)
time
- the preferred time constraint and timeout value in millisecondsgetPreferredResponseTime()
public void setSpeedAndCourseRequired(boolean speedAndCourseRequired)
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.isSpeedAndCourseRequired()
public void setVerticalAccuracy(int accuracy)
accuracy
- the preferred vertical accuracy in metersgetVerticalAccuracy()