locationprovider.java

这是一款基于PlaceLab软件开发的导航系统中间件的客户端程序.

	 * 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.
	 * 
	 * 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.
	 * 
	 * @param listener
	 *            the listener to be registered. If set to null the registration
	 *            of any previously set listener is cancelled.
	 * @param 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.
	 * @param 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 the interval is 0, this parameter has no
	 *            effect.
	 * @param 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. If the interval is 0, this parameter has no effect.
	 * @throws java.lang.IllegalArgumentException
	 *             if interval < -1, or if (interval != -1) and (timeout >
	 *             interval or maxAge > interval or (timeout < 1 and timeout !=
	 *             -1) or (maxAge < 1 and maxAge != -1))
	 * @throws java.lang.SecurityException
	 *             if the calling application does not have a permission to
	 *             query the location information
	 */
	public abstract void setLocationListener(LocationListener listener,
			int interval, int timeout, int maxAge);
	
	
	/**
	 * 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.
	 */
	public abstract void reset();
	
	
	/**
	 * 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.
	 * 
	 * @return a location object. null is returned if the implementation doesn't
	 *         have any previous location information.
	 * @throws java.lang.SecurityException
	 *             if the calling application does not have a permission to
	 *             query the location information
	 */
	public static Location getLastKnownLocation() {
		if (provider == null)
			return null;
		
		return provider.getLastKnownLocationImpl();	
	}
	
	/**
	 * 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.
	 * 
	 * @param listener
	 *            the listener to be registered
	 * @param coordinates
	 *            the coordinates to be registered
	 * @param 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
	 * @throws java.lang.IllegalArgumentException
	 *             if the proximity radius is 0 or negative* or Float.NaN
	 * @throws java.lang.NullPointerException
	 *             if the listener or coordinates parameter is null
	 * @throws java.lang.SecurityException
	 *             if the application does not have the permission to register a
	 *             proximity listener
	 */
	public static void addProximityListener(ProximityListener listener,
			Coordinates coordinates, float proximityRadius)
			throws LocationException {
		
		if ((proximityRadius == Float.NaN) || (proximityRadius <= 0F)) 
			throw new IllegalArgumentException();
		
		if ((listener == null) || (coordinates == null)) 
			throw new NullPointerException();
		
		provider.addProximityListenerImpl(listener, coordinates, proximityRadius);
	}
	
	/**
	 * 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.
	 * 
	 * @param listener
	 *            the listener to remove
	 * @throws java.lang.NullPointerException
	 *             if the parameter is null
	 */
	public static void removeProximityListener(ProximityListener listener) {
		if (provider != null) 
			provider.removeProximityListenerImpl(listener);
	}
}