com.openlapi
Class LocationProviderSimplified

java.lang.Object
  extended by com.openlapi.LocationProvider
      extended by com.openlapi.LocationProviderSimplified
Direct Known Subclasses:
LocationProviderNMEA

public abstract class LocationProviderSimplified
extends LocationProvider

All of the LocationProvider implementations in OpenLAPI share common code, here is the place where we store it. This also makes creating new implementations somewhat easier as there is not so much boilerplate to worry about.

This class should not be used directly by applications.


Field Summary
 
Fields inherited from class com.openlapi.LocationProvider
AVAILABLE, OUT_OF_SERVICE, TEMPORARILY_UNAVAILABLE
 
Constructor Summary
LocationProviderSimplified()
           
 
Method Summary
 Location getLocation(int timeout)
          Retrieves a Location with the constraints given by the Criteria associated with this class.
 int getState()
          Returns the current state of this LocationProvider.
 void reset()
          Resets the LocationProvider.
 void setLocationListener(LocationListener listener, int interval, int timeout, int maxAge)
          Adds a LocationListener for updates at the defined interval.
protected abstract  void startBackend()
          Start a new backend in a background thread.
protected abstract  void stopBackend()
          Stop the backend that is currently running.
 void updateLocation(Location newLocation)
          We extracted a Location from the backend.
 void updateState(int newState)
          We believe we are in a particular state.
 
Methods inherited from class com.openlapi.LocationProvider
addProximityListener, alertProximityListeners, getInstance, getLastKnownLocation, removeProximityListener, setLastKnownLocation
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LocationProviderSimplified

public LocationProviderSimplified()
Method Detail

getLocation

public final Location getLocation(int timeout)
                           throws LocationException,
                                  java.lang.InterruptedException,
                                  java.lang.SecurityException,
                                  java.lang.IllegalArgumentException
Description copied from class: LocationProvider
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 fulfil 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.

Specified by:
getLocation in class LocationProvider
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:
Throws:
LocationException - if the location couldn't be retrieved or if the timeout period expired
java.lang.InterruptedException - if the operation is interrupted by calling reset() from another thread
java.lang.SecurityException - if the calling application does not have a permission to query the location information
java.lang.IllegalArgumentException - if the timeout = 0 or timeout < -1

getState

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

Specified by:
getState in class LocationProvider
Returns:
the availability state of this LocationProvider

reset

public final void reset()
Description copied from class: LocationProvider
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.

Specified by:
reset in class LocationProvider

setLocationListener

public final void setLocationListener(LocationListener listener,
                                      int interval,
                                      int timeout,
                                      int maxAge)
Description copied from class: LocationProvider
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.

The implementation shall initiate obtaining the first location result immediately when the listener is registered and provide the location to the listener as soon as it is available. Subsequent location updates will happen at the defined interval after the first one. If the specified update interval is smaller than the time it takes to obtain the first result, the listener shall receive location updates with invalid Locations at the defined interval until the first location result is available. Note that prior to getting the first valid location result, the timeout parameter has no effect. When the first valid location result is obtained, the implementation may return it to the application immediately, i.e. before the next interval is due. This implies that in the beginning when starting to obtain location results, the listener may first get updates with invalid location results at the defined interval and when the first valid location result is obtained, it may be returned to the listener as soon as it is available before the next interval is due. After the first valid location result is delivered to the application the timeout parameter is used and the next update is delivered between the time defined by the interval and time interval+timeout after the previous update.

The timeout parameter determines a timeout that is used if it's not possible to obtain a new location result when the update is scheduled to be provided. This timeout value indicates how many seconds the update is allowed to be provided late compared to the defined interval. If it's not possible to get a new location result (interval + timeout) seconds after the previous update, the update will be made and an invalid Location instance is returned. This is also done if the reason for the inability to obtain a new location result is due to the provider being temporarily unavailable or out of service. For example, if the interval is 60 seconds and the timeout is 10 seconds, the update must be delivered at most 70 seconds after the previous update and if no new location result is available by that time the update will be made with an invalid Location instance.

The maxAge parameter defines how old the location result is allowed to be provided when the update is made. This allows the implementation to reuse location results if it has a recent location result when the update is due to be delivered. This parameter can only be used to indicate a larger value than the normal time of obtaining a location result by a location method. The normal time of obtaining the location result means the time it takes normally to obtain the result when a request is made. If the application specifies a time value that is less than what can be realized with the used location method, the implementation shall provide as recent location results as are possible with the used location method. For example, if the interval is 60 seconds, the maxAge is 20 seconds and normal time to obtain the result is 10 seconds, the implementation would normally start obtaining the result 50 seconds after the previous update. If there is a location result otherwise available that is more recent than 40 seconds after the previous update, then the maxAge setting to 20 seconds allows to return this result and not start obtaining a new one.

The requirements for the intervals hold while the application is executing. If the application environment or the device is suspended so that the application will not execute at all and then the environment is later resumed, the periodic updates MUST continue at the defined interval but there may be a shift after the suspension period compared to the original interval schedule.

Specified by:
setLocationListener in class LocationProvider
Parameters:
listener - the listener to be registered. If set to null the registration of any previously set listener is cancelled.
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.

updateLocation

public final void updateLocation(Location newLocation)
We extracted a Location from the backend. No defined interval.

Parameters:
newLocation - the latest Location that we extracted. May be invalid, but never null.

updateState

public final void updateState(int newState)
We believe we are in a particular state. This does not imply that the state has changed, just updates our latest belief.

Parameters:
newState - one of LocationProvider.OUT_OF_SERVICE, LocationProvider.TEMPORARILY_UNAVAILABLE or LocationProvider.AVAILABLE which reflects the state of this daemon. If LocationProvider.OUT_OF_SERVICE is received, it may be possible to recover by discarding the daemon and starting a new one.

startBackend

protected abstract void startBackend()
                              throws LocationException
Start a new backend in a background thread. Ignore if a backend is currently running. Always called from a block that is synchronized on this.

Throws:
LocationException - if the backend could not be started

stopBackend

protected abstract void stopBackend()
Stop the backend that is currently running. Ignore if no backend is currently running. Always called from a block that is synchronized on this.

Throws:
LocationException - if the backend could not be stopped