Location API

Mobile Designer provides an API to access the location services of the mobile device. This is provided through classes in the com.softwareag.mobile.md.location package. A class conforming to the ILocationManager interface can be obtained using the getService() method of MDApplication as follows:

ILocationManager locationManager =
(ILocationManager)MyNewApplication.getInstance()
.getService(IMDApplication.LOCATION_MANAGER_SERVICE);

Location updates are passed back through a class conforming to the ILocationWatcher interface. This interface allows information about location updates, errors during use, and initial setup failures to be provided. The locationUpdatesEnded() method is called at any time that location updates are stopped. This can happen normally through ILocationManager.stopLocationUpdates() or after an error occured. Calls to locationUpdatesEnded() do not happen if an initial setup failure occurs, since a failure at that level produces no location updates.

class ResultHandler implements ILocationWatcher
{
public void locationUpdate(Location location)
{
System.out.println("Location was updated at "
+ location.timestamp + "\n" +
"Latitude : " + location.latitude + " +/- "
+ location.latitudeAccuracy + "\n" +
"Longitude : " + location.longitude + " +/- "
+ location.longitudeAccuracy + "\n" +
"Altitude : " + location.altitude + " +/- "
+ location.altitudeAccuracy);
}

public void locationUpdatesEnded()
{
System.out.println("Location updates ended.");
}

public void onError(int why, String description)
{
System.out.println("An error : " + why + " " + description);
}

public void onFailure(int why, String description)
{
System.out.println("A failure : " + why + " " + description);
}
}

To configure the location hardware, create a LocationSettings object and pass it to the appropriate call in the ILocationManager. The LocationSettings object encapsulates the application's preferences in terms of an accuracy/power consumption trade-off. It also determines if the updates should come back to the application code at a preferred time interval or a preferred distance travelled.

Note:
For both distances and times given, the operating system makes a best-effort attempt to get as close as possible to the requested value, but this is not exact due to many factors (including GPS signal loss, operating system, power or CPU constraints, requests or interrupts from other applications, buffering, etc). Therefore, the application must not make any direct assumptions based only on the fact that an update happened.

//prefer updates once per minute (average)
LocationSettings settings =
new LocationSettings(LocationSettings.PROFILE_HIGH_POWER_ACCURATE, 60000L);
ILocationWatcher myLocationWatcher = new ResultHandler();
locationManager.beginLocationUpdates(myLocationWatcher, settings);

It is important to consider that the one-shot getLocation() method also requires a LocationSettings object. This is because the location hardware may not already be in use and needs to be initialised fully in case it is needed elsewhere before the pending request is served. The getLastKnownLocation() method does not need to switch any hardware on to return a result and so does not need a LocationSettings object to function (and can therefore be very useful in low-power situations).

Additionally, a CoordinateHelper class is available to provide some methods to assist in coordinate conversion to/from human-readable forms and measuring distances between Location objects.