javax.microedition.location
Class LocationProvider

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

public abstract class LocationProvider
extends java.lang.Object

This is the starting point for applications using location information in 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 one of the factory methods. It is the responsibility of the implementation to return the correct LocationProvider-derived object.

Applications that need to specify criteria for the location provider selection, must first create a Criteria object, and pass it to the factory method. The methods that access the location related information shall throw SecurityException if the application does not have the relevant permission to access the location information.

Some applications may want to list the preferred location technologies that the desired location provider should use and instantiate the location provider based on that list. This possibility is also provided in the factory methods.

Field Summary

static int	AVAILABLE Availability status code: the location provider is available.
static int	OUT_OF_SERVICE Availability status code: the location provider is out of service.
static int	PROVIDER_DEFAULT Constant for the default value of the location provider.
static int	TEMPORARILY_UNAVAILABLE Availability status code: the location provider is temporarily unavailable.

Constructor Summary

protected

LocationProvider() Empty constructor to help implementations and extensions.

Method Summary

static void	addAreaListener(AreaListener listener, GeographicArea area, Criteria criteria, int interval) Adds an AreaListener for updates when a boundary of the specified geographical area is crossed.
static void	addAreaListener(AreaListener listener, GeographicArea area, int[] preferredLocationMethods, java.lang.String parameters, int interval) Adds an AreaListener for updates when a boundary of the specified geographical area is crossed.
static void	addProximityListener(ProximityListener listener, Coordinates coordinates, float proximityRadius) Deprecated. in 2.0, replaced by addAreaListener
static LocationProvider	getInstance(Criteria criteria) This factory method is used to get an actual LocationProvider implementation based on the defined criteria.
static LocationProvider	getInstance(int[] preferredLocationMethods, java.lang.String parameters) This factory method is used to get an actual LocationProvider implementation based on the preferred location methods and/or platform specific parameters.
static Location	getLastKnownLocation() Returns the last known location that the implementation has.
abstract Location	getLocation(int timeout) Retrieves a Location object.
abstract int	getState() Returns the current state of this LocationProvider.
static void	removeAreaListener(AreaListener listener) Removes a AreaListener from the list of recipients for the updates.
static void	removeProximityListener(ProximityListener listener) Deprecated. in 2.0, replaced by removeAreaListener
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

PROVIDER_DEFAULT

public static final int PROVIDER_DEFAULT

Constant for the default value of the location provider. This may be used with timeout and interval values.

Since:

2.0

See Also:

Constant Field Values

AVAILABLE

public static final int AVAILABLE

Availability status code: the location provider is available.

See Also:

Constant Field Values

TEMPORARILY_UNAVAILABLE

public static final int TEMPORARILY_UNAVAILABLE

Availability status code: the location provider is temporarily unavailable. Temporary unavailability means that the method is unavailable due to reasons that can be expected to possibly change in the future and the provider to become available. An example is not being able to receive the signal because the signal used by the location method is currently being obstructed, e.g. when deep inside a building for satellite based methods. However, a very short transient obstruction of the signal should not cause the provider to toggle quickly between TEMPORARILY_UNAVAILABLE and AVAILABLE.

Another example is that a power save mode is being used because the location information is not being currently requested, for example, by using a registered LocationListener or the getLocation method.

See Also:

Constant Field Values

OUT_OF_SERVICE

public static final int OUT_OF_SERVICE

Availability status code: the location provider is out of service. Being out of service means that the method is unavailable and the implementation is not able to expect that this situation would change in the near future. An example is when using a location method implemented in an external device and the external device is detached.

See Also:

Constant Field Values

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

getInstance

public static LocationProvider getInstance(Criteria criteria)
                                    throws LocationException

This factory method is used to get an actual LocationProvider implementation based on the defined criteria. The implementation chooses the LocationProvider so that it best fits the defined criteria, taking into account also possible implementation dependent preferences of the end user. If no concrete LocationProvider could be created that typically can match the defined criteria but there are other location providers not meeting the criteria that could be returned for a more relaxed criteria, null is returned to indicate this. The LocationException is thrown, if all supported location providers are out of service.

A LocationProvider instance is returned if there is a location provider meeting the criteria in either the available or temporarily unavailable state. Implementations should try to select providers in the available state before providers in temporarily unavailable state, but this can not be always guaranteed because the implementation may not always know the state correctly at this point in time. If a LocationProvider meeting the criteria can be supported but is currently out of service, it shall not be returned.

When this method is called with a Criteria that has all fields set to the default values (i.e. the least restrictive criteria possible), the implementation shall return a LocationProvider if there is any provider that is not in the out of service state. Passing null as the parameter is equal to passing a Criteria that has all fields set to the default values, i.e. the least restrictive set of criteria.

This method only makes the selection of the provider based on the criteria and is intended to return it quickly to the application. Any possible initialization of the provider is done at an implementation dependent time and must not block the call to this method.

This method may, depending on the implementation, return the same LocationProvider instance as has been returned previously from this method to the calling application, if the same instance can be used to fulfil both defined criteria. Note that there can be only one LocationListener associated with a LocationProvider instance.

Parameters:

criteria - the criteria for provider selection or null to indicate the least restrictive criteria with default values

Returns:

a LocationProvider meeting the defined criteria or null if a LocationProvider that meets the defined criteria can not be returned but there are other supported available or temporarily unavailable providers that do not meet the criteria

Throws:

LocationException - if all LocationProviders are currently out of service

See Also:

Criteria

getInstance

public static LocationProvider getInstance(int[] preferredLocationMethods,
                                           java.lang.String parameters)
                                    throws LocationException

This factory method is used to get an actual LocationProvider implementation based on the preferred location methods and/or platform specific parameters. The location methods are defined in Location class. Each element represents preferred location technology and is a bitwise combination (OR) of the method technology, method type and assistance information. This means that each element in the preferredLocationMethods array contains one technology bit (MTE_*), one method type bit (MTY_*) and method assistance information bit (MTA_*). This specification does not define any format for the String object containing the parameters. It is left to the implementation and to the location provider to specify them.

The order of the preferredLocationMethods array is interpreted so that the first item is the most preferred location technology. If that is not available, then the location technology in the second item should be used. This preferred order is only a hint to the implementation and it may select another location technology to be used if it sees fit. If preferredLocationMethods is an empty array, it is interpreted as passing in null. If a LocationProvider meeting the preferred location method can be supported but is currently out of service, it must not be returned.

If both preferred location methods and platform specific parameters are given, the location method takes precedence. The platform specific parameters are used only if preferred location methods can not be fulfilled.

Parameters:

preferredLocationMethods - the preferred location methods, may be null

parameters - platform specific parameters to find a specific LocationProvider, may be null

Returns:

a LocationProvider matching the preferred location methods and/or platform specific parameters, or null if a LocationProvider that meets the defined conditions can not be found but there are other available or temporarily unavailable providers that do not support the defined conditions

Throws:

java.lang.IllegalArgumentException - if all elements in preferredLocationMethods array are not bitwise combinations of one location method technology, one method type and one assistance information bits

java.lang.NullPointerException - if both preferredLocationMethods and parameters are null

LocationException - if all LocationProviders are currently out of service

Since:

2.0

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 does not have any previous location information.

Throws:

java.lang.SecurityException - if the calling application does not have a permission to query the location information

addProximityListener

public static void addProximityListener(ProximityListener listener,
                                        Coordinates coordinates,
                                        float proximityRadius)
                                 throws LocationException

Deprecated. in 2.0, replaced by addAreaListener

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 not be currently done due to the current state of the method used to implement it, this method shall succeed and the ProximityListener.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:

java.lang.IllegalArgumentException - if the proximity radius is 0 or negative or Float.NaN

java.lang.NullPointerException - if the listener or coordinates parameter is null

java.lang.SecurityException - if the application does not have the permission to register a proximity listener

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)

Deprecated. in 2.0, replaced by removeAreaListener

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

addAreaListener

public static void addAreaListener(AreaListener listener,
                                   GeographicArea area,
                                   Criteria criteria,
                                   int interval)
                            throws LocationException

Adds an AreaListener for updates when a boundary of the specified geographical area is crossed. This listener differs from the ProximityListener so that the notification is sent when the crossing the boundary of the the given geographical area happens instead of being in proximity of that area. The application registering this listener is responsible for checking is the current location inside or outside the defined area boundary. This listener monitors only crossing of the boundary.

If this method is called with a AreaListener that is already registered, the registration to the specified geographical area is added in to the list of geographical areas it has been previously registered for. A single listener can handle events for multiple geographical areas. It is optional to provide area monitoring feature as it may not be reasonably implementable with all methods used to implement this API.

Area monitoring is an conditionally mandatory feature that must be implemented if the location methods support it. The support for area monitoring can be queried with microedition.location.areamonitoring system property. If the return value of the system property is true, it means that there is at least one location method that is able to support area monitoring in the API implementation. If area monitoring is not supported by any location method, this method throws a LocationException.

When using this method, an application does not care which location method performs the actual area monitoring. The criteria parameter allows an application to guide the API implementation in the selection of the location method performing the area monitoring. With the Criteria an application can specify, for example, whether the area monitoring is allowed to cost or what are the accuracy requirements for it. The API implementation must select a location method that supports area monitoring, best fits into the given criteria, is able to do boundary check in the requested interval and that is in available or temporarily unavailable state. If all matching location method are in out of service state, a LocationException is thrown. The criterion for allowing the area monitoring to cost must be followed. When the AreaListener has been added and the selected location method goes out of service or becomes temporarily unavailable, the API implementation may select a new location method that matches the given Criteria, supports area monitoring and is in available state to continue the area monitoring. Information about this change is sent to the application through AreaListener.monitoringStateChanged and AreaListener.monitoringInfo notification.

With the interval parameter an application defines what is the interval that the API implementation must check if the area boundary has been crossed. The API implementation may perform the check more frequently. Specifying this interval, an application allows to API implementation to optimize battery consumption in the area* monitoring. The currently used location method and boundary check interval are sent to the application through AreaListener.monitoringInfo notification.

The area monitoring must be started immediately when the listener is registered. Detecting the area boundaries 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 crossing the boundary is always detected; especially if the terminal is close to the boundary when the AreaListener is registered, it is possible that the implementation misses this.

If the API implementation is capable of supporting the area monitoring and has resources to add the new listener and geographical area to be monitored but the monitoring can not be done because all matching location providers are in temporarily unavailable state, this method must succeed and the AreaListener.monitoringStateChanged method of the listener must be immediately called to notify that the monitoring is not active currently. The AreaListener.monitoringStateChanged notification must also be sent when the state of the location provider performing the area monitoring changes.

Parameters:

listener - the listener to be registered

area - the geographical area which proximity is detected

criteria - the criteria for location provider selection or null if an application does not have any criteria

interval - the required boundary check interval in seconds, PROVIDER_DEFAULT if an application does not have any requirements

Throws:

java.lang.IllegalArgumentException - if interval = 0 or < PROVIDER_DEFAULT (-1)

java.lang.NullPointerException - if the listener or area parameter is null

java.lang.SecurityException - if the application does not have the permission to register a area listener

LocationException - if the platform does not have resources to add a new listener and geographical area to be monitored or if none of the location methods can meet the interval parameter or if all location providers matching the given criteria are out of service or if none of the location methods supports area monitoring at all

Since:

2.0

addAreaListener

public static void addAreaListener(AreaListener listener,
                                   GeographicArea area,
                                   int[] preferredLocationMethods,
                                   java.lang.String parameters,
                                   int interval)
                            throws LocationException

Adds an AreaListener for updates when a boundary of the specified geographical area is crossed. This listener differs from the ProximityListener so that the notification is sent when the crossing the boundary of the the given geographical area happens instead of being in proximity of that area. The application registering this listener is responsible for checking is the current location inside or outside the defined area boundary. This listener monitors only crossing of the boundary.

If this method is called with a AreaListener that is already registered, the registration to the specified geographical area is added in to the list of geographical areas it has been previously registered for. A single listener can handle events for multiple geographical areas. It is optional to provide area monitoring feature as it may not be reasonably implementable with all methods used to implement this API.

Area monitoring is an conditionally mandatory feature that must be implemented if the location methods support it. The support for area monitoring can be queried with microedition.location.areamonitoring system property. If the return value of the system property is true, it means that there is at least one location method that is able to support area monitoring in the API implementation. If area monitoring is not supported by any requested location method, this method throws a LocationException.

When using this method, an application requests a certain location method to perform the actual area monitoring. The requested location methods are given in the preferredLocationMethods parameter. In the array the most preferred location method is given as the first item and the second best as the second item and so on. The API implementation goes through the given array and selects the first available location method that is able to support area monitoring and is able to check the boundary crossing on the requested interval. If none of the location methods is in available state, the implementation may select a location method that is currently temporarily unavailable. If the API implementation is capable of supporting the area monitoring and has resources to add the new listener and geographical area to be monitored but the monitoring can not be currently done due to the current state of all given location methods, this method throws a LocationException.

With the interval parameter an application defines what is the interval that the API implementation must check if the area boundary has been crossed. The API implementation may perform the check more frequently. By specifying this interval, an application allows to API implementation to optimize battery consumption in the area monitoring. The currently used location method and boundary check interval are sent to the application through AreaListener.monitoringInfo notification. If none of the location methods can not meet the interval requirement a LocationException is thrown.

If this selected location method goes out of service or becomes temporarily unavailable after this method has been called, the API implementation does not select a new location method automatically, but the area monitoring is interrupted. The state of the area monitoring is sent to the application through AreaListener.monitoringStateChanged notification.

The area monitoring must be started immediately when the listener is registered. Detecting the area boundaries is done on a best effort basis by the location method implementation. Due to the limitations of the methods used to implement this, there are no guarantees that crossing the boundary is always detected; especially if the terminal is close to the boundary when the AreaListener is registered, it is possible that the implementation misses this.

Parameters:

listener - the listener to be registered

area - the geographical area which proximity is detected

preferredLocationMethods - the preferred location methods for area monitoring

parameters - platform specific parameters to find a specific location method, may be null

interval - the required boundary check interval in seconds, PROVIDER_DEFAULT if an application does not have any requirements

Throws:

java.lang.IllegalArgumentException - if all elements in preferredLocationMethods array are not bitwise combinations of one location method technology, one method type and one assistance information bits or null or if preferrefLocationMethods is an empty array or if interval = 0 or < PROVIDER_DEFAULT (-1)

java.lang.NullPointerException - if the listener or area is null or if both preferredLocationMethods and parameters are null

java.lang.SecurityException - if the application does not have the permission to register a area listener

LocationException - if the platform does not have resources to add a new listener and geographical area to be monitored or if all the location methods are out of service or if none of the location methods can meet the interval parameter or if none of the location methods support area monitoring at all

Since:

2.0

removeAreaListener

public static void removeAreaListener(AreaListener listener)

Removes a AreaListener from the list of recipients for the updates. If the specified listener is not registered or if the listener parameter is null, this method silently returns with no action.

Parameters:

listener - the listener to remove

Since:

2.0

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 LocationProvider class.

When the state is TEMPORARILY_UNAVAILABLE, the implementation is allowed not to attempt to measure the location if there are no pending requests from an application to get the location, for example, by using a registered LocationListener or the getLocation method. This allows the implementation to use, for example, power save modes where the location is not being measured unless it is being requested. In this kind of situations, the state of the LocationProvider should be TEMPORARILY_UNAVAILABLE because the current up to date location information is not immediately available. The transition from TEMPORARILY_UNAVAILABLE to AVAILABLE might happen only if the application requests the location. Therefore, an application must not wait for the state to become AVAILABLE before requesting the location information, but try to request the location even if the current state is TEMPORARILY_UNAVAILABLE.

Returns:

the availability state of this LocationProvider

getLocation

public abstract Location getLocation(int timeout)
                              throws LocationException,
                                     java.lang.InterruptedException

Retrieves a Location object. If no result could be retrieved, a LocationException is thrown. If the location can not 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.

Parameters:

timeout - a timeout value in seconds, PROVIDER_DEFAULT is used to indicate that the implementation shall use its default timeout value for this provider

Returns:

a Location object

Throws:

java.lang.IllegalArgumentException - if the timeout = 0 or timeout < -1 (=PROVIDER_DEFAULT)

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

LocationException - if the location could not be retrieved or if the timeout period expired

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 availability state of the LocationProvider changes.

Passing in PROVIDER_DEFAULT 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 is 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 is 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.

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. PROVIDER_DEFAULT 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 PROVIDER_DEFAULT, the default timeout for this provider is used. Also, if the interval is PROVIDER_DEFAULT to indicate the default, the value of this parameter has no effect and the default timeout for this provider is used. If timeout == -1 (=PROVIDER_DEFAULT) 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 PROVIDER_DEFAULT to indicate that the default maximum age for this provider is used. Also, if the interval is PROVIDER_DEFAULT to indicate the default, the value of this parameter has no effect and the default maximum age for this provider is used. If maxAge == -1 (=PROVIDER_DEFAULT) and interval > 0 and the default maximum age of the provider is greater than the specified interval, then the maxAge parameter is handled as if the application had passed the same value as maxAge as the interval (i.e. maxAge is considered to be equal to the interval). If the interval is 0, this parameter has no effect.

Throws:

java.lang.IllegalArgumentException - if interval < -1 (=PROVIDER_DEFAULT), or if (interval != PROVIDER_DEFAULT and timeout > interval) or maxAge > interval or (timeout < 1 and timeout != PROVIDER_DEFAULT) or (maxAge < 1 and maxAge != PROVIDER_DEFAULT)

java.lang.SecurityException - if the calling application does not have a permission to query the location information

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.