|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.j4me.bluetoothgps.Criteria
public class Criteria
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) |
Allow local LBS | true (use the LBS on the device running this MIDlet if it meets the other criteria) |
Remote LBS address | null (only use the local LBS on the device running this MIDlet) |
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. |
java.lang.String |
getRemoteDeviceAddress()
Returns the Bluetooth address of the remote GPS device to use if no local LBS matches the other criteria. |
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 |
isLocalLBSAllowed()
Returns if the LBS on this device should be used if it meets the other criteria. |
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 |
setAllowLocalLBS(boolean allowLocalLBS)
Sets if the LBS on this device should be used if it meets the other criteria. |
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 |
setRemoteDeviceAddress(java.lang.String address)
Sets the Bluetooth address of the remote GPS device. |
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 |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int NO_REQUIREMENT
public static final int POWER_USAGE_LOW
public static final int POWER_USAGE_MEDIUM
public static final int POWER_USAGE_HIGH
Constructor Detail |
---|
public Criteria()
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.
Method Detail |
---|
public int getPreferredPowerConsumption()
NO_REQUIREMENT
,
POWER_USAGE_LOW
, POWER_USAGE_MEDIUM
,
POWER_USAGE_HIGH
.setPreferredPowerConsumption(int)
public boolean isAllowedToCost()
true
if allowed to cost,
false
if it must be free of charge.setCostAllowed(boolean)
public int getVerticalAccuracy()
Criteria
.
setVerticalAccuracy(int)
public int getHorizontalAccuracy()
Criteria
.
setHorizontalAccuracy(int)
public int getPreferredResponseTime()
setPreferredResponseTime(int)
public boolean isSpeedAndCourseRequired()
true
means that it should be able, false
means that this is not required.setSpeedAndCourseRequired(boolean)
public boolean isAltitudeRequired()
true
means that it should be able, false
means that this is not required.setAltitudeRequired(boolean)
public boolean isAddressInfoRequired()
true
means that it should be
able, false
means that this is not required.setAddressInfoRequired(boolean)
public boolean isLocalLBSAllowed()
remoteDeviceAddress
.
If false
only the remote LBS at setRemoteDeviceAddress
can
be used.
true
if local LBS can be used; false
if remote LBS
must be used.public java.lang.String getRemoteDeviceAddress()
null
than only
local LBS can be used.
LocationProvider.discoverBluetoothDevices
method. If this is null
than only local LBS will be used.setRemoteDeviceAddress(String)
public void setHorizontalAccuracy(int accuracy)
NO_REQUIREMENT
,
meaning no preference on horizontal accuracy.
accuracy
- - the preferred horizontal accuracy in metersgetHorizontalAccuracy()
public void setVerticalAccuracy(int accuracy)
accuracy
- - the preferred vertical accuracy in metersgetVerticalAccuracy()
public void setPreferredResponseTime(int time)
NO_REQUIREMENT
, meaning no response time
constraint.
time
- - the preferred time constraint and timeout value in
millisecondsgetPreferredResponseTime()
public void setPreferredPowerConsumption(int level)
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.
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 setCostAllowed(boolean costAllowed)
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.
costAllowed
- - false
if location determination is not
allowed to cost, true
if it is allowed to costisAllowedToCost()
public void setSpeedAndCourseRequired(boolean speedAndCourseRequired)
false
.
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 setAltitudeRequired(boolean altitudeRequired)
Default is false
.
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 setAddressInfoRequired(boolean addressInfoRequired)
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
.
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 setAllowLocalLBS(boolean allowLocalLBS)
remoteDeviceAddress
.
To force remote LBS to be used set this value to false
and provide
a remote address to setRemoteDeviceAddress
.
Default is true
.
allowLocalLBS
- when true
uses LBS on the current device
if it meets the other criteria; when false
forces remote LBS
to be used.public void setRemoteDeviceAddress(java.lang.String address)
LocationProvider.discoverBluetoothDevices
method. Once the address is known, it should be stored using the
Record Management System (RMS) for the next time the MIDlet is run.
If this value is set to null
, the default, than only LBS providers
built into the device running the MIDlet will be used.
address
- - the Bluetooth address of the remote GPS device or
null
if only local LBS can be used.getRemoteDeviceAddress()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |