javax.microedition.location
Class Criteria

java.lang.Object
  |
  +--javax.microedition.location.Criteria

public class Criteria
extends 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:

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.

RIM Implementation Mode Chart - Generic

Horizontal Accuracy

Vertical Accuracy

Cost

Power Consumption

Resulting Mode

N/A

N/A

Not Allowed

N/A

Autonomous

N/A

N/A

Allowed

Medium, High or No Requirement

Assisted

Not Required

Not Required

Allowed

Low

Cellsite

Since:
JDE 4.0.2

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
 boolean equals(Object obj)
          Indicates whether some other object is "equal to" this one.
 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.
 
Methods inherited from class java.lang.Object
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. Value = 0
Since:
JDE 4.0.2

POWER_USAGE_HIGH

public static final int POWER_USAGE_HIGH
Level indicating high power consumption allowed. Value = 3
Since:
JDE 4.0.2

POWER_USAGE_LOW

public static final int POWER_USAGE_LOW
Level indicating only low power consumption allowed. Value = 1
Since:
JDE 4.0.2

POWER_USAGE_MEDIUM

public static final int POWER_USAGE_MEDIUM
Level indicating average power consumption allowed. Value = 2
Since:
JDE 4.0.2
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.
Since:
JDE 4.0.2
Method Detail

equals

public boolean equals(Object obj)
Description copied from class: Object
Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation:

  • It is reflexive: for any reference value x, x.equals(x) should return true.
  • It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified.
  • For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).

Overrides:
equals in class Object
Since:
JDE 4.2.1

Following copied from class: Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Boolean.hashCode(), Hashtable

getHorizontalAccuracy

public int getHorizontalAccuracy()

Returns the horizontal accuracy value set in this Criteria.

Returns:
the horizontal accuracy in meters
Since:
JDE 4.0.2
See Also:
setHorizontalAccuracy(int)

getPreferredPowerConsumption

public int getPreferredPowerConsumption()

Returns the preferred power consumption.

Returns:
the power consumption level; one of NO_REQUIREMENT, POWER_USAGE_LOW, POWER_USAGE_MEDIUM, POWER_USAGE_HIGH.
Since:
JDE 4.0.2
See Also:
setPreferredPowerConsumption(int)

getPreferredResponseTime

public int getPreferredResponseTime()

Returns the preferred maximum response time.

Returns:
the maximum response time in milliseconds
Since:
JDE 4.0.2
See Also:
setPreferredResponseTime(int)

getVerticalAccuracy

public int getVerticalAccuracy()

Returns the vertical accuracy value set in this Criteria.

Returns:
the accuracy in meters
Since:
JDE 4.0.2
See Also:
setVerticalAccuracy(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.
Since:
JDE 4.0.2
See Also:
setAddressInfoRequired(boolean)

isAllowedToCost

public boolean isAllowedToCost()

Returns the preferred cost setting.

Returns:
the preferred cost setting. true if allowed to cost, false if it must be free of charge.
Since:
JDE 4.0.2
See Also:
setCostAllowed(boolean)

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.
Since:
JDE 4.0.2
See Also:
setAltitudeRequired(boolean)

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.
Since:
JDE 4.0.2
See Also:
setSpeedAndCourseRequired(boolean)

setAddressInfoRequired

public void setAddressInfoRequired(boolean addressInfoRequired)

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.

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.

RIM Implementation Note

Do not call setAddressInfoRequired(true) because the RIM implementation does not support textual address (See the RIM Implementation Mode Chart below). Invoking LocationProvider.getInstance(Criteria) with a Criteria instance that requires textual address causes it to return null.

Since:
JDE 4.0.2
See Also:
isAddressInfoRequired()

setAltitudeRequired

public void setAltitudeRequired(boolean altitudeRequired)

Sets whether the location provider should be able to determine altitude. Default is false.

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.
Since:
JDE 4.0.2
See Also:
isAltitudeRequired()

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
Since:
JDE 4.0.2
See Also:
isAllowedToCost()

setHorizontalAccuracy

public void setHorizontalAccuracy(int accuracy)

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.

Parameters:
accuracy - the preferred horizontal accuracy in meters
Since:
JDE 4.0.2
See Also:
getHorizontalAccuracy()

setPreferredPowerConsumption

public void setPreferredPowerConsumption(int level)

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.

Parameters:
level - the preferred maximum level of power consumption. Must be one of NO_REQUIREMENT, POWER_USAGE_LOW, POWER_USAGE_MEDIUM, POWER_USAGE_HIGH.
Since:
JDE 4.0.2
See Also:
getPreferredPowerConsumption()

setPreferredResponseTime

public void setPreferredResponseTime(int time)

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. The value is also used as a timeout value if the implementation is not able to produce the result within the defined time. Default is NO_REQUIREMENT, meaning no response time constraint.

Parameters:
time - the preferred time constraint and timeout value in milliseconds
Since:
JDE 4.0.2
See Also:
getPreferredResponseTime()

setSpeedAndCourseRequired

public void setSpeedAndCourseRequired(boolean speedAndCourseRequired)

Sets whether the location provider should be able to determine speed and course. Default is false.

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.
Since:
JDE 4.0.2
See Also:
isSpeedAndCourseRequired()

setVerticalAccuracy

public void setVerticalAccuracy(int accuracy)

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.

Parameters:
accuracy - the preferred vertical accuracy in meters
Since:
JDE 4.0.2
See Also:
getVerticalAccuracy()



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.