javax.microedition.location
Class LocationProvider

java.lang.Object
  extended by javax.microedition.location.LocationProvider

public abstract class LocationProvider
extends Object

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.

Author:
BB

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

AVAILABLE

public static final int AVAILABLE
See Also:
Constant Field Values

TEMPORARILY_UNAVAILABLE

public static final int TEMPORARILY_UNAVAILABLE
See Also:
Constant Field Values

OUT_OF_SERVICE

public static final int OUT_OF_SERVICE
See Also:
Constant Field Values

listeners

protected static final Vector listeners
This is where we store the proximity listeners. The elements are 3 element Object [] arrays:-

Constructor Detail

LocationProvider

protected LocationProvider()
Empty constructor to help implementations and extensions. This is not intended to be used by applications. Applications should not make subclasses of this class and invoke this constructor from the subclass.

Method Detail

getState

public abstract int getState()
Returns the current state of this LocationProvider. The return value shall be one of the availability status code constants defined in this class.

Returns:
the availability state of this LocationProvider

getInstance

public static LocationProvider getInstance(Criteria criteria)
                                    throws LocationException
This is a factory method to retrieve an instance of LocationProvider. With leJOS NXJ the LocationProvider is the class ??? i.e. a Bluetooth GPS unit. It looks through all the paired Bluetooth devices on your NXT brick and tries connecting to any that are identified as GPS units.

Parameters:
criteria - Just use null instead of an actual Criteria object
Returns:
a LocationProvider that is a Bluetooth GPS already paired with your NXT brick
Throws:
LocationException

getLocation

public abstract Location getLocation(int timeout)
                              throws LocationException,
                                     InterruptedException
Retrieves a Location with the constraints given by the Criteria associated with this class. If no result could be retrieved, a LocationException is thrown. If the location can't be determined within the timeout period specified in the parameter, the method shall throw a LocationException.

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.

Parameters:
timeout - a timeout value in seconds. -1 is used to indicate that the implementation shall use its default timeout value for this provider.
Returns:
a Location object
Throws:
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 thread

setLocationListener

public abstract void setLocationListener(LocationListener listener,
                                         int interval,
                                         int timeout,
                                         int maxAge)
Adds a LocationListener for updates at the defined interval. The listener will be called with updated location at the defined interval. The listener also gets updates when the availablilty state of the LocationProvider changes.

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.

Parameters:
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.

reset

public abstract void reset()
Resets the LocationProvider.

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.


getLastKnownLocation

public static Location getLastKnownLocation()
Returns the last known location that the implementation has. This is the best estimate that the implementation has for the previously known location.

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.

Returns:
a location object. null is returned if the implementation doesn't have any previous location information.

addProximityListener

public static void addProximityListener(ProximityListener listener,
                                        Coordinates coordinates,
                                        float proximityRadius)
                                 throws LocationException
Adds a ProximityListener for updates when proximity to the specified coordinates is detected.

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.

Parameters:
listener - the listener to be registered
coordinates - the coordinates to be registered
proximityRadius - the radius in meters that is considered to be the threshold for being in the proximity of the specified coordinates
Throws:
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 all

removeProximityListener

public static void removeProximityListener(ProximityListener listener)
Removes a ProximityListener from the list of recipients for updates. If the specified listener is not registered or if the parameter is null, this method silently returns with no action.

Parameters:
listener - the listener to remove