|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.microedition.location.LocationProvider
public abstract class LocationProvider
This is the starting point for applications using this API and represents a source of the location information. A LocationProvider represents a location-providing module, generating Locations.
Applications obtain LocationProvider instances (classes implementing the actual functionality by extending this abstract class) by calling the factory method getInstance(). It is the responsibility of the implementation to return the correct LocationProvider-derived object.
Rather than passing an actual Criteria object to getInstance(), just use null because leJOS NXJ has no need for criteria arguments.
Field Summary | |
---|---|
static int |
AVAILABLE
|
protected static Vector |
listeners
This is where we store the proximity listeners. |
static int |
OUT_OF_SERVICE
|
static int |
TEMPORARILY_UNAVAILABLE
|
Constructor Summary | |
---|---|
protected |
LocationProvider()
Empty constructor to help implementations and extensions. |
Method Summary | |
---|---|
static void |
addProximityListener(ProximityListener listener,
Coordinates coordinates,
float proximityRadius)
Adds a ProximityListener for updates when proximity to the specified coordinates is detected. |
static LocationProvider |
getInstance(Criteria criteria)
This is a factory method to retrieve an instance of LocationProvider. |
static Location |
getLastKnownLocation()
Returns the last known location that the implementation has. |
abstract Location |
getLocation(int timeout)
Retrieves a Location with the constraints given by the Criteria associated with this class. |
abstract int |
getState()
Returns the current state of this LocationProvider. |
static void |
removeProximityListener(ProximityListener listener)
Removes a ProximityListener from the list of recipients for updates. |
abstract void |
reset()
Resets the LocationProvider. |
abstract void |
setLocationListener(LocationListener listener,
int interval,
int timeout,
int maxAge)
Adds a LocationListener for updates at the defined interval. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int AVAILABLE
public static final int TEMPORARILY_UNAVAILABLE
public static final int OUT_OF_SERVICE
protected static final Vector listeners
Constructor Detail |
---|
protected LocationProvider()
Method Detail |
---|
public abstract int getState()
public static LocationProvider getInstance(Criteria criteria) throws LocationException
criteria
- Just use null instead of an actual Criteria object
LocationException
public abstract Location getLocation(int timeout) throws LocationException, InterruptedException
If the provider is temporarily unavailable, the implementation shall wait and try to obtain the location until the timeout expires. If the provider is out of service, then the LocationException is thrown immediately.
Note that the individual Location returned might not fulfill exactly the criteria used for selecting this LocationProvider. The Criteria is used to select a location provider that typically is able to meet the defined criteria, but not necessarily for every individual location measurement.
timeout
- a timeout value in seconds. -1 is used to indicate that the implementation shall use its default timeout value for this provider.
LocationException
- if the location couldn't be retrieved or if the timeout period expired
InterruptedException
- if the operation is interrupted by calling reset() from another threadpublic abstract void setLocationListener(LocationListener listener, int interval, int timeout, int maxAge)
Passing in -1 as the interval selects the default interval which is dependent on the used location method. Passing in 0 as the interval registers the listener to only receive provider status updates and not location updates at all.
Only one listener can be registered with each LocationProvider instance. Setting the listener replaces any possibly previously set listener. Setting the listener to null cancels the registration of any previously set listener.
listener
- the listener to be registered. If set to null the registration of any previously set listener is canceled.interval
- the interval in seconds. -1 is used for the default interval of this provider. 0 is used to indicate that the application wants to receive only provider status updates and not location updates at all.timeout
- timeout value in seconds, must be greater than 0. if the value is -1, the default timeout for this provider is used. Also, if the interval is -1 to indicate the default, the value of this parameter has no effect and the default timeout for this provider is used. If timeout == -1 and interval > 0 and the default timeout of the provider is greater than the specified interval, then the timeout parameter is handled as if the application had passed the same value as timeout as the interval (i.e. timeout is considered to be equal to the interval). If the interval is 0, this parameter has no effect.maxAge
- maximum age of the returned location in seconds, must be greater than 0 or equal to -1 to indicate that the default maximum age for this provider is used. Also, if the interval is -1 to indicate the default, the value of this parameter has no effect and the default maximum age for this provider is used.public abstract void reset()
All pending synchronous location requests will be aborted and any blocked getLocation method calls will terminate with InterruptedException.
Applications can use this method e.g. when exiting to have its threads freed from blocking synchronous operations.
public static Location getLastKnownLocation()
Applications can use this method to obtain the last known location and check the timestamp and other fields to determine if this is recent enough and good enough for the application to use without needing to make a new request for the current location.
public static void addProximityListener(ProximityListener listener, Coordinates coordinates, float proximityRadius) throws LocationException
If this method is called with a ProximityListener that is already registered, the registration to the specified coordinates is added in addition to the set of coordinates it has been previously registered for. A single listener can handle events for multiple sets of coordinates.
If the current location is known to be within the proximity radius of the specified coordinates, the listener shall be called immediately.
Detecting the proximity to the defined coordinates is done on a best effort basis by the implementation. Due to the limitations of the methods used to implement this, there are no guarantees that the proximity is always detected; especially in situations where the terminal briefly enters the proximity area and exits it shortly afterwards, it is possible that the implementation misses this. It is optional to provide this feature as it may not be reasonably implementable with all methods used to implement this API.
If the implementation is capable of supporting the proximity monitoring and has resources to add the new listener and coordinates to be monitored but the monitoring can't be currently done due to the current state of the method used to implement it, this method shall succeeed and the monitoringStateChanged method of the listener shall be immediately called to notify that the monitoring is not active currently.
listener
- the listener to be registeredcoordinates
- the coordinates to be registeredproximityRadius
- the radius in meters that is considered to be the threshold for being in the proximity of the specified coordinates
LocationException
- if the platform does not have resources to add a new listener and coordinates to be monitored or does not support proximity monitoring at allpublic static void removeProximityListener(ProximityListener listener)
listener
- the listener to remove
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |