|
||||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||
javax.microedition.location package contains the
basic classes needed to request and get a location result.
See:
Description
| Interface Summary | |
| LocationListener | The LocationListener represents a listener that receives
events associated with a particular
LocationProvider. |
| ProximityListener | This interface represents a listener to events associated with detecting proximity to some registered coordinates. |
| Class Summary | |
| AddressInfo | The AddressInfo class holds textual address information
about a location. |
| Coordinates | The Coordinates class represents coordinates as
latitude-longitude-altitude values.
|
| Criteria | The criteria used for the selection of the location provider is defined by the values in this class. |
| Landmark | The Landmark class represents a landmark, i.e. a known location
with a name. |
| LandmarkStore | The LandmarkStore class provides methods to store, delete
and retrieve landmarks from a persistent landmark store.
|
| Location | The Location class represents the standard set of
basic location information. |
| LocationProvider | This is the starting point for applications using this API and represents a source of the location information. |
| Orientation | The Orientation class represents the physical orientation
of the terminal.
|
| QualifiedCoordinates | The QualifiedCoordinates class represents coordinates as
latitude-longitude-altitude values that are associated with
an accuracy value. |
| Exception Summary | |
| LandmarkException | The LandmarkException is thrown when an error related
to handling landmarks has occurred. |
| LocationException | The LocationException is thrown when a location API
specific error has occurred.
|
The javax.microedition.location package contains the
basic classes needed to request and get a location result.
The LocationProvider class represents a module that
is able to determine the location of the terminal. This may be
implemented using any possible location methods, for example,
satellite based methods like GPS, cellular network based
methods, short-range positioning methods like Bluetooth Local
Positioning, etc. The implementation may also combine the
methods in various ways to get the optimal result.
The application can specify criteria for selecting the location provider
and obtain a LocationProvider instance that is able to
fulfil these criteria as closely as possible. By using the
LocationProvider, the application can get
Location objects representing the
location of the terminal at the time of the measurement.
The application can either request a single Location
object or be periodically updated with new Location objects
via a LocationListener implemented by the application.
The location is represented by the Location object that
contains a QualifiedCoordinates object representing
the geographical coordinates (latitude, longitude and altitude) and
information about their accuracy, a timestamp and possibly
information about speed and course of the terminal.
For some location methods,
the Location object may also contain an AddressInfo object
that includes textual address information, e.g. a street address.
The Location gives the accuracy of the
coordinates as the radius of a circular area indicating
the 1-sigma confidence level. The 1-sigma confidence refers
to the standard deviation of the distribution. Assuming a normal
distribution (which is not necessarily the case), this implies
that the actual location is within the circle defined by
the returned point and radius at a probability of
approximately 68%. The actual location may thus be also outside
of the circle, which has to be taken into account when
using the location information in applications.
This package also includes a database of landmarks. A landmark is a known physical location that is associated with a name representing that location for the end user. The user can store commonly used locations in the database. Examples of landmarks could be e.g. the user's home, office, etc. The landmark database must be shared between all Java applications and may be shared with other applications in the terminal, including native applications, so that the end user has a consistent user experience across all location based applications on the terminal.
This API contains some options whose availability depends on the used location methods. These features are not optional in order to allow for differences in the implementations and to cause unnecessary fragmentation, but they are unavoidable due to the differences in the underlying location methods. Implementations should support all features that are possible with the locations methods that are used.
Mandatory features for all location methods are:
Mandatory other API features for the terminal are:
LandmarkStore for storing landmarks
Features whose availability depend on the used location method:
Optional features whose availability depend on the landmark store implementation of the terminal and its possible relation to landmark stores shared with native applications:
Additionally, depending on the hardware capabilities of the terminal, the following features are optionally supported:
In general, every implementation MUST contain all the classes, interfaces and methods as defined in this specification. Those features that are optional to implement have a defined behaviour in the case the feature is not supported by the implementation.
Some methods in this API are defined to throw a SecurityException
if the caller does not have the permissions needed to perform the action.
This MUST be enforced by an appropriate security framework in the platform.
If this API is implemented on the MIDP 2.0 platform, the security framework of MIDP 2.0 MUST be used as defined below.
The table below defines the names of the permissions used and the methods that are protected by each permission. The definition of the policy for these permissions is out of scope for this specification.
|
Permission name |
Methods protected by this permission |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To enable applications to test for the presence of the Location API
and its version during runtime, a system property is defined.
Platforms where this API is implemented according to this specification
shall include a system property with a key "microedition.location.version".
When System.getProperty is called with this key,
implementations conforming to this specification shall return the
version string "1.0". (Note: although the specification version number for this Maintenance Release contains three digits, this system property includes only the two-digit major.minor part of it, because the difference is so small that it should not be significant for applications. If a later release of this specification contains such changes that are relevant for applications then the major and/or minor digit of the version number will be changed.).
The following piece of code illustrates how to obtain
the current location of the terminal. This piece of code illustrates
obtaining the location syncronously. An application would normally
perform this within a separate thread, because the getLocation
method may block for a long time.
try {
// Create a Criteria object for defining desired selection criteria
Criteria cr = new Criteria();
// Specify horizontal accuracy of 500 meters, leave other parameters
// at default values.
cr.setHorizontalAccuracy(500);
LocationProvider lp = LocationProvider.getInstance(cr);
// get the location, one minute timeout
Location l = lp.getLocation(60);
Coordinates c = l.getQualifiedCoordinates();
if (c != null) {
// use coordinate information
...
}
} catch (LocationException e) {
// not able to retrive location information
...
}
The following example illustrates how to use the
LocationListener for subscribing to periodic location
updates. This example creates a handler thread to handle the updates
so that the methods on the listener would not block the platform
implementation threads for a long time.
class MovementTracker implements LocationListener {
float movementDistance;
LocationProvider provider;
Location lastValidLocation;
UpdateHandler handler;
boolean done;
public MovementTracker(float movementDistance) throws LocationException {
this.movementDistance = movementDistance;
done = false;
handler = new UpdateHandler();
new Thread(handler).start();
provider = LocationProvider.getInstance(null);
provider.setLocationListener(this, -1, -1, -1);
}
public void locationUpdated(LocationProvider provider, Location location) {
handler.handleUpdate(location);
}
public void providerStateChanged(LocationProvider provider, int newState) {
}
class UpdateHandler implements Runnable {
private Location updatedLocation = null;
// The run method performs the actual processing of the location
// updates
public void run() {
Location locationToBeHandled = null;
while (!done) {
synchronized(this) {
if (updatedLocation == null) {
try {
wait();
} catch (Exception e) {
// Handle interruption
}
}
locationToBeHandled = updatedLocation;
updatedLocation = null;
}
// The benefit of the MessageListener is here.
// This thread could via similar triggers be
// handling other kind of events as well in
// addition to just receiving the location updates.
if (locationToBeHandled != null)
processUpdate(locationToBeHandled);
}
}
public synchronized void handleUpdate(Location update) {
updatedLocation = update;
notify();
}
private void processUpdate(Location update) {
if ( update.getQualifiedCoordinates().distance(
lastValidLocation.getQualifiedCoordinates() )
> movementDistance ) {
// Alert user to movement...
// Cache new position as we have moved a sufficient distance
// from last one
lastValidLocation = location;
}
}
}
}
|
||||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||