location.java

一个基于PlaceLab的室内和室外的智能导航系统

package javax.microedition.location;

/**
 * <P>
 * The <code>Location</code> class represents the standard set of basic
 * location information. This includes the timestamped coordinates, accuracy,
 * speed, course, and information about the positioning method used for the
 * location, plus an optional textual address.
 * <p>
 * The location method is indicated using a bit field. The individual bits are
 * defined using constants in this class. This bit field is a bitwise
 * combination of the location method technology bits (MTE_*), method type
 * (MTY_*) and method assistance information (MTA_*). All other bits in the 32
 * bit integer than those that have defined constants in this class are reserved
 * and MUST not be set by implementations (i.e. these bits must be 0).
 * </p>
 * <p>
 * A <code>Location</code> object may be either 'valid' or 'invalid'. The
 * validity can be queried using the <code>isValid</code> method. A valid
 * <code>Location</code> object represents a location with valid coordinates
 * and the <code>getQualifiedCoordinates</code> method must return there
 * coordinates. An invalid <code>Location</code> object doesn't have valid
 * coordinates, but the extra info that is obtained from the
 * <code>getExtraInfo</code> method can provide information about the reason
 * why it was not possible to provide a valid <code>Location</code>. For an
 * invalid <code>Location</code> object, the
 * <code>getQualifiedCoordinates</code> method may return either
 * <code>null</code> or some coordinates where the information is not
 * necessarily fully correct. The periodic location updates to the
 * <code>LocationListener</code> may return invalid Location objects if it
 * isn't possible to determine the location.
 * </p>
 * <p>
 * This class is only a container for the information. When the platform
 * implementation returns <code>Location</code> objects, it MUST ensure that
 * it only returns objects where the parameters have values set as described for
 * their semantics in this class.
 * </p>
 * <P>
 */
public class Location {
	/**
	 * Location method is assisted by the other party (Terminal assisted for
	 * Network based, Network assisted for terminal based). MTA_ASSISTED =
	 * 0x00040000
	 */
	public static final int MTA_ASSISTED = 0x00040000;

	/**
	 * Location method is unassisted. This bit and MTA_ASSISTED bit MUST NOT
	 * both be set. Only one of these bits may be set or neither to indicate
	 * that the assistance information is not known. MTA_UNASSISTED = 0x00080000
	 */
	public static final int MTA_UNASSISTED = 0x00080000;

	/**
	 * Location method Angle of Arrival for cellular / terrestrial RF system.
	 * MTE_ANGLEOFARRIVAL = 0x00000020
	 */
	public static final int MTE_ANGLEOFARRIVAL = 0x00000020;

	/**
	 * Location method Cell-ID for cellular (in GSM, this is the same as CGI,
	 * Cell Global Identity). MTE_CELLID = 0x00000008
	 */
	public static final int MTE_CELLID = 0x00000008;

	/**
	 * Location method using satellites (for example, Global Positioning System
	 * (GPS)). MTE_SATELLITE = 0x00000001
	 */
	public static final int MTE_SATELLITE = 4;

	/**
	 * Location method Short-range positioning system (for example, Bluetooth
	 * LP). MTE_SHORTRANGE = 0x00000010
	 */
	public static final int MTE_SHORTRANGE = 0x00000010;

	/**
	 * Location method Time Difference for cellular / terrestrial RF system (for
	 * example, Enhanced Observed Time Difference (E-OTD) for GSM).
	 * MTE_TIMEDIFFERENCE = 0x00000002
	 */
	public static final int MTE_TIMEDIFFERENCE = 0x00000002;

	/**
	 * Location method Time of Arrival (TOA) for cellular / terrestrial RF
	 * system. MTE_TIMEOFARRIVAL = 0x00000004
	 */
	public static final int MTE_TIMEOFARRIVAL = 0x00000004;

	/**
	 * Location method is of type network based. This means that the final
	 * location result is calculated in the network. This bit and
	 * MTY_TERMINALBASED bit MUST NOT both be set. Only one of these bits may be
	 * set or neither to indicate that it is not known where the result is
	 * calculated. MTY_NETWORKBASED = 0x00020000
	 */
	public static final int MTY_NETWORKBASED = 0x00020000;

	/**
	 * Location method is of type terminal based. This means that the final
	 * location result is calculated in the terminal. MTY_TERMINALBASED =
	 * 0x00010000
	 */
	public static final int MTY_TERMINALBASED = 0x00010000;

	/**
	 * A protected constructor for the Location to allow implementations of
	 * LocationProviders to construct the Location instances.
	 * 
	 * This method is not intended to be used by applications.
	 * 
	 * This constructor sets the fields to implementation specific default
	 * values. Location providers are expected to set the fields to the correct
	 * values after constructing the object instance.
	 *  
	 */
	protected Location() {

	}

	/**
	 * Returns whether this Location instance represents a valid location with
	 * coordinates or an invalid one where all the data, especially the latitude
	 * and longitude coordinates, may not be present.
	 * 
	 * A valid Location object contains valid coordinates whereas an invalid
	 * Location object may not contain valid coordinates but may contain other
	 * information via the getExtraInfo() method to provide information on why
	 * it was not possible to provide a valid Location object.
	 * 
	 * @return a boolean value with true indicating that this Location instance
	 *         is valid and false indicating an invalid Location instance
	 * @see #getExtraInfo(String)
	 */
	public boolean isValid() {
		return false;
	}

	/**
	 * Returns the time stamp at which the data was collected. This timestamp
	 * should represent the point in time when the measurements were made.
	 * Implementations make best effort to set the timestamp as close to this
	 * point in time as possible. The time returned is the time of the local
	 * clock in the terminal in milliseconds using the same clock and same time
	 * representation as System.currentTimeMillis().
	 * 
	 * @return a timestamp representing the time
	 * @see System.currentTimeMillis()
	 */
	public long getTimestamp() {
		return 0L;
	}

	/**
	 * Returns the coordinates of this location and their accuracy.
	 * 
	 * @return QualifiedCoordinates object. If the coordinates are not known,
	 *         returns null
	 */
	public QualifiedCoordinates getQualifiedCoordinates() {
		return null;
	}

	/**
	 * Returns the terminal's current ground speed in meters per second (m/s) at
	 * the time of measurement. The speed is always a non-negative value. Note
	 * that unlike the coordinates, speed does not have an associated accuracy
	 * because the methods used to determine the speed typically are not able to
	 * indicate the accuracy.
	 * 
	 * @return the current ground speed in m/s for the terminal or Float.NaN if
	 *         the speed is not known
	 */
	public float getSpeed() {
		return 0F;
	}

	/**
	 * Returns the terminal's course made good in degrees relative to true
	 * north. The value is always in the range [0.0,360.0) degrees.
	 * 
	 * @return the terminal's course made good in degrees relative to true north
	 *         or Float.NaN if the course is not known
	 */
	public float getCourse() {
		return 0F;
	}
	
	/**
	 * Returns information about the location method used. The returned value is
	 * a bitwise combination (OR) of the method technology, method type and
	 * assistance information. The method technology values are defined as
	 * constant values named MTE_* in this class, the method type values are
	 * named MTY_* and assistance information values are named MTA_*.
	 * 
	 * For example, if the location method used is terminal based, network
	 * assisted E-OTD, the value 0x00050002 ( = MTY_TERMINALBASED | MTA_ASSISTED |
	 * MTE_TIMEDIFFERENCE) would be returned.
	 * 
	 * If the location is determined by combining several location technologies,
	 * the returned value may have several MTE_* bits set.
	 * 
	 * If the used location method is unknown, the returned value must have all
	 * the bits set to zero.
	 * 
	 * Only bits that have defined constants within this class are allowed to be
	 * used. Other bits are reserved and must be set to 0.
	 * 
	 * @return a bitfield identifying the used location method
	 */
	public int getLocationMethod() {
		return 0;
	}

	/**
	 * Returns the AddressInfo associated with this Location object. If no
	 * address is available, null is returned.
	 * 
	 * @return an AddressInfo associated with this Location object
	 */
	public AddressInfo getAddressInfo() {
		return null;
	}

	/**
	 * Returns extra information about the location. This method is intended to
	 * provide location method specific extra information that applications that
	 * are aware of the used location method and information format are able to
	 * use.
	 * 
	 * A MIME type is used to identify the type of the extra information when
	 * requesting it. If the implementation supports this type, it returns the
	 * extra information as a String encoded according to format identified by
	 * the MIME type. If the implementation does not support this type, the
	 * method returns null.
	 * 
	 * This specification does not require implementations to support any extra
	 * information type.
	 * 
	 * The following MIME types are defined here together with their definitions
	 * in order to ensure interoperability of implementations wishing to use
	 * these types. The definition of these types here is not an indication that
	 * these formats are preferred over any other format not defined here.
	 * 
	 * When the MIME type is "application/X-jsr179-location-nmea", the returned
	 * string shall be a valid sequence of NMEA sentences formatted according to
	 * the syntax specified in the NMEA 0183 v3.1 specification. These sentences
	 * shall represent the set of NMEA sentences that are related to this
	 * location at the time this location was created.
	 * 
	 * When the MIME type is "application/X-jsr179-location-lif", the returned
	 * string shall contain an XML formatted document containing the "pd"
	 * element defined in the LIF Mobile Location Protocol TS 101 v3.0.0 as the
	 * root element of the document.
	 * 
	 * When the MIME type is "text/plain", the returned string shall contain
	 * textual extra information that can be displayed to the end user.
	 * 
	 * @param mimetype
	 *            the MIME type of the requested extra information
	 * @return string encoded according to the format identified by the MIME
	 *         type defined in the parameter. null if the information for the
	 *         requested MIME type is not available or not supported by this
	 *         implementation.
	 */
	public String getExtraInfo(String mimetype) {
		return null;
	}
}