×
Namespaces

Variants
Actions
Revision as of 12:00, 15 January 2013 by jasfox (Talk | contribs)

Using the PositioningManager from Maps API for Java ME

From Nokia Developer Wiki
Jump to: navigation, search
Featured Article
17 Jul
2011

This article explains how to use the PositioningManager from the Ovi Maps Java ME Location API to get information about the device location.

Archived.pngArchived: This article is archived because it is not considered relevant for third-party developers creating commercial solutions today. If you think this article is still relevant, let us know by adding the template {{ReviewForRemovalFromArchive|user=~~~~|write your reason here}}.

This article is reliant upon an alpha pre-release of the Nokia Maps API for Java ME, and the PositioningManager was removed from the 1.0 version of the Nokia Maps API for Java ME since the PositioningManager relied upon Manufacturer permissions in the MIDlet. Error handling for permissions should instead be handled within the code itself as described in the Using a Location Provider Example

Contents

Introduction

JavaMELocationAPI PositioningManager.png

The Java ME Location API offers a PositioningManager class that allows to get notified and updated about the location of the user device. This class wraps all the logic involved in detecting the user position, for instance by using an internal GPS or other positioning methods.

The code described in this article has been used in the Run Tracker MIDlet available on Nokia Developer Projects: Run Tracker.

PositioningManager and PositionListener

The PositioninhManager offers various features that allow to start, stop and get asynchronous updates about the user location. This mechanism is accomplished with the use of the PositionListener, an interface defining the methods that get called to notify location updates.

Implementing the FollowUserMIDlet

To explain in detail the features of the PositioningManager, this article shows a simple MIDlet that tracks the user position and displays his movements on a map.

Its base structure, that just shows a map on the screen, is the following:

public class FollowUserMIDlet extends MIDlet {
 
MapCanvas mapCanvas = null;
 
protected void startApp() throws MIDletStateChangeException {
ApplicationContext ctx = ApplicationContext.getInstance();
 
ctx.setAppID("MyAppId");
ctx.setToken("MyToken");
 
Display display = Display.getDisplay(this);
mapCanvas = new MapCanvas(display);
display.setCurrent(mapCanvas);
}
}

The FollowUserMIDlet then defines a MapContainer that will hold all the MapPolyline objects used to display the user movements on the map:

public class FollowUserMIDlet extends MIDlet implements PositionListener, CommandListener {
 
[...]
 
MapContainer pathContainer = null;
 
protected void startApp() throws MIDletStateChangeException {
[...]
 
pathContainer = mapCanvas.getMapFactory().createMapContainer(false);
mapCanvas.getMapDisplay().addMapObject(pathContainer);
}
}

To add the PositioningManager functionality to the FollowUserMIDlet, it is necessary to grab a reference to the PositioningManager instance, through its getInstance() method, and then set the MIDlet itself as listener, to properly receive notifications.

protected void startApp() throws MIDletStateChangeException {           
[...]
 
positioningManager = PositioningManager.getInstance();
positioningManager.setListener(this);
}

Implementing the PositionListener

As the FollowUserMIDlet has to be able to track the user position, it must implement the PositionListener interface, that defines four different methods:

  • positioningStarted() - called when the PositioningManager starts to detect the user position
  • positioningEnded() - called when the PositioningManager stop detecting the user position
  • positioningError(java.lang.Throwable detail) - called when an error occurs during the position detection
  • positioningUpdated(GeoPosition position) - called to notify about the current user position

The first thing to add is the implements clause to the FollowUserMIDlet:

public class FollowUserMIDlet extends MIDlet implements PositionListener {
[...]
}

The core interface method is positioningUpdated(), that is responsible for notifying the listener about the updated user position.

Before implementing this method, the FollowUserMIDlet defines a GeoCoordinate variable to hold the last detected user position, as follows:

public class FollowUserMIDlet extends MIDlet implements PositionListener {
 
GeoCoordinate currentCoordinate = null;
 
[...]
}

When the positioningUpdated() method gets called, the FollowUserMIDlet should draw a line from the previous user position to the new one. The map gets also centered in the new position, to have a better feedback of the updated position. The implementation of the positioningUpdated() method is the following:

public void positioningUpdated(GeoPosition position)
{
GeoCoordinate newCoordinate = position.getCoordinate();
 
if(currentCoordinate != null)
{
MapPolyline line = mapCanvas.getMapFactory().createMapPolyline(new GeoCoordinate[]{
currentCoordinate, newCoordinate
});
 
pathContainer.addMapObject(line);
}
currentCoordinate = newCoordinate;
 
mapCanvas.getMapDisplay().setCenter(position.getCoordinate());
 
mapCanvas.mapContentUpdated();
}

When an error occurs, the positioningError() method gets called. In this case, it could be useful to display an error message to the user, as shown in the sample implementation below:

public void positioningError(Throwable error) {
Alert errorAlert = new Alert(error.getMessage());
Display.getDisplay(this).setCurrent(errorAlert);
}

When the positioning gets started, the interface positioningStarted() method gets called. The FollowUserMIDlet in this case removes all the previously displayed polylines, cleaning up the map for the new user movements.

public void positioningStarted()
{
pathContainer.removeAllMapObjects();
}

As soon as the PositioningManager stopPositioning() method is called, the positioningEnded() method of the PositionListener interface is called. The FollowUserMIDlet, in this case, should reset the currentCoordinate variable, as follows:

public void positioningEnded()
{
currentCoordinate = null;
}

Adding Commands to start and stop positioning

Two Command objects are added to the MapCanvas, to allow the user to manually start and stop the positioning operation. The FollowUserMIDlet so implements the CommandListener interface, implementing its commandAction() method:

public class FollowUserMIDlet extends MIDlet implements PositionListener, CommandListener {
 
[...]
 
Command startCommand, stopCommand;
 
protected void startApp() throws MIDletStateChangeException {
[...]
 
mapCanvas.addCommand(startCommand = new Command("Start", Command.OK, 1));
mapCanvas.addCommand(stopCommand = new Command("Stop", Command.CANCEL, 1));
mapCanvas.setCommandListener(this);
 
}
public void commandAction(Command c, Displayable d)
{
if(c == startCommand)
{
positioningManager.startPositioning();
}
else if(c == stopCommand)
{
positioningManager.stopPositioning();
}
}
}

The FollowUserMIDlet in action

Once started, the FollowUserMIDlet just shows a map on the device screen. When the user presses the "Start" command button, the device prompts the user for permission of using the location services, as shown in the shots below. If the user confirms these prompts, then the user movements will start appearing on the map, shown as black lines.

JavaMELocationAPI FollowUserMIDlet.png

Resources

The FollowUserMIDlet is available for download here: File:FollowUserMIDlet.zip

Full source code can be found here: File:FollowUserMIDlet.java.zip

Article Metadata
Code Example
Installation file: Media:FollowUserMIDlet.zip
Tested with
Devices(s): X3-02
Compatibility
Platform(s): S40, Symbian^1, Symbian^3
Series 40
Symbian
Device(s): All
Article
Keywords: Nokia Maps, Java ME, Location API, Ovi Maps, PositioningManager, PositionListener, positioning
Created: jappit (29 June, 2011 -->)
Last edited: jasfox (15 Jan 2013)
190 page views in the last 30 days.
×