Revision as of 02:44, 30 January 2012 by hamishwillee (Talk | contribs)

Implementing a custom MapUrlProvider overlay with Maps API for Java ME

From Nokia Developer Wiki
Jump to: navigation, search

This article explains how to implement a custom MapUrlProvider and how to add it as overlay over a map by using the Maps API for Java ME

Needs-update.pngThis article needs to be updated: If you found this article useful, please fix the problems below then delete the {{ArticleNeedsUpdate}} template from the article to remove this warning.

The code in this article needs to be updated in order to work with the release v0.5 of the Nokia Maps API



JavaMELocationAPI MapOverlay.png

The Ovi Maps Java ME Location API offers a feature to easily add new transparent layers over the default map tiles, or to replace the default tiles with custom ones, thanks to the MapProvider object.

MapProvider and MapUrlProvider

A MapProvider object is responsible for generating the map tile Images that are displayed by a MapDisplay. Those Image objects are generated and returned by the getTileImage() object, that returns a tile corresponding to a row/column/zoom and with a given width and height.

The row and column parameters are generated by using the Mercator projection, and a sample implementation is available on the MapProvider JavaDocs page.

The MapProvider base class has a direct subclass, MapUrlProvider, that allows to retrieve tiles from remote providers, and integrates all the logic for fetching and generating the tile Image objects.

This is done by implementing a method that returns the URL of the remote tile, corresponding to the given row, column, zoom, width and height parameters:

public String getTileUrl(int zoom, int column, int row, int width, int height) 

Implementing a CustomMapUrlProvider

The CustomMapUrlProvider class must extend MapUrlProvider, as shown below.

public class CustomMapUrlProvider extends MapUrlProvider

The MapUrlProvider defines two abstract methods, that must be implemented by the extending class:

  • public String getTileUrl(int zoom, int column, int row, int width, int height) that returns the URL of a given tile
  • public String getName() that returns the name of the custom map provider

Since the tile image must be generated by a remote script or page, the getTileUrl method has to pass all its parameter to the remote Web server, and so the generated URL has to contain those parameters in its query string.

public String getTileUrl(int zoom, int column, int row, int width, int height) 
return "http://www.nokiadevs.com/various/custommapprovider/index.php?" +
"column=" + column + "&" +
"row=" + row + "&" +
"zoom=" + zoom + "&" +
"width=" + width + "&" +
"height=" + height;

The getName() method can be simply implemented by returning a name for the implemented custom map provider.

public String getName()
return "My Map URL Provider";

Adding the CustomMapUrlProvider to a MapDisplay

Once the custom provider has been implemented, it is necessary to add it to the desired MapDisplay object. This can be done by using the MapDisplay addMapOverlay() method.

myMapDisplay.addMapOverlay(new CustomMapUrlProvider());

Implementing the provider's server

A MapUrlProvider server can be implemented in any available technology (for instance, Java, PHP, Perl). The following code snippet shows how to write a simple script that generate tiles with a thin border and with the column and row parameters displayed on the tile itself.

$row = $_REQUEST['row'];
$column = $_REQUEST['column'];
$width = $_REQUEST['width'];
$height = $_REQUEST['height'];
$zoom = $_REQUEST['zoom'];
// create an empty image with the given width and height
$image = imagecreatetruecolor($width, $height);
// set the background color as transparent
$black = imagecolorallocate($image, 0, 0, 0);
imagecolortransparent($image, $black);
// create the needed colors
$redColor = imagecolorallocatealpha($image, 255, 0, 0, 0);
$grayColor = imagecolorallocatealpha($image, 10, 10, 10, 0);
// paint a border around the tile image
imagerectangle($image, 0, 0, $width - 1, $height - 1, $redColor);
// write the column and row parameters on the tile
$text = $column . ' - ' . $row;
imagestring($image, 5, $width / 2 - 50, $height / 2 + 1, $text, $grayColor);
imagestring($image, 5, $width / 2 - 50, $height / 2, $text, $redColor);
// send the image to the client
header("Content-type: image/png");

The final result of applying the CustomMapUrlProvider defined above is visible in the following screenshot.

JavaMELocationAPI CustomMapUrlProvider.png


A sample MIDlet showing the CustomMapUrlProvider in action is available for download here: File:CustomMapUrlProviderMIDlet.zip

Full source code of the CustomMapUrlProvider class is available here: File:CustomMapUrlProvider.java.zip


The MapUrlProvider allows to easily define interfaces to remote providers of map tiles. If an application needs more control over the generated map tiles, then the MapProvider should be used instead.

Article Metadata
Code ExampleTested with
Devices(s): X3-02
Platform(s): S40, Symbian^1, Symbian^3
Series 40
Device(s): All
Keywords: Location API, Ovi Maps, MapProvider, MapUrlProvider, MapDisplay
Created: jappit (29 June, 2011 -->)
Last edited: hamishwillee (30 Jan 2012)
125 page views in the last 30 days.