locationprovider.java

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

package javax.microedition.location;

import org.placelab.jsr0179.LocationProviderImpl;

/**
 * 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. 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.
 * 
 *  
 */
public abstract class LocationProvider {
	/** Availability status code: the location provider is available. */
	public static final int AVAILABLE = 1;

	/**
	 * 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.
	 */
	public static final int TEMPORARILY_UNAVAILABLE = 2;

	/**
	 * 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.
	 */
	public static final int OUT_OF_SERVICE = 3;

	
	/**
	 * LocationProvider is currently hard-wired to work with only one provider, ours.
	 */
	private static LocationProviderImpl provider = null;
	
	
	/**
	 * 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.
	 */
	protected LocationProvider() {

	}

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

	/**
	 * 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't
	 * 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 isn't 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.
	 * 
	 * @param criteria
	 *            the criteria for provider selection or null to indicate the
	 *            least restrictive criteria with default values
	 * @return a LocationProvider meeting the defined criteria or null if a
	 *         LocationProvider that meets the defined criteria can't be
	 *         returned but there are other supported available or temporarily
	 *         unavailable providers that do not meet the criteria.
	 * @throws LocationException
	 *             LocationException if all LocationProviders are currently out
	 *             of service
	 * @see Criteria
	 */
	public static LocationProvider getInstance(Criteria criteria)
			throws LocationException {
		
		if (provider != null) 
			return provider;
		
		provider = new LocationProviderImpl();
		return provider;
	}
	
	/**
	 * 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.
	 * 
	 * @param timeout
	 *            a timeout value in seconds. -1 is used to indicate that the
	 *            implementation shall use its default timeout value for this
	 *            provider.
	 * @return a Location object
	 * @throws LocationException
	 *             if the location couldn't be retrieved or if the timeout
	 *             period expired
	 * @throws java.lang.InterruptedException
	 *             if the operation is interrupted by calling reset() from
	 *             another thread
	 * @throws java.lang.SecurityException
	 *             if the calling application does not have a permission to
	 *             query the location information
	 * @throws java.lang.IllegalArgumentException
	 *             if the timeout = 0 or timeout < -1
	 */
	public abstract Location getLocation(int timeout) throws LocationException,
			java.lang.InterruptedException;
	
	/**
	 * 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.
	 *