javax.microedition.location.services
Interface Map

public interface Map

This class represents a dynamic map generated by a map service provider. With this object, an application can render a map on the context it is providing and on top of that whatever it needs to render.

The size for the area where the map is rendered is set when calling the MapServiceProvider.getMap method. The size is given in pixels. An application also sets the initial viewport to the map in the service request. This viewport means the area of the map that is rendered to the graphics context and it is given as a RectangleGeographicArea. The actual map may contain area bigger than the initial viewport to enable panning and moving of the map.

Map is a mutable object. This means that after getting a Map object, an application can modify the viewport to the map. It can pan, rotate, zoom or move the viewport as it needs. After any of these operations, the results are made visible by calling the renderMap method. The realized new viewport to the map can be retrieved with getViewport method. An application controls the layers and map base used in the renderMap method through the MapServicePreferences that are set using setMapServicePreferences method and retrieved with getMapServicePreferences method.

The success of the operations on the map are indicated with the return values of the methods. If requested operation can not be performed to the map, the application should retrieve a new Map object from a map service provider.

Some API implementations may retrieve the map data over the network. Therefore the complete map may not be instantly available for rendering. In the renderMap method an application can control whether all the content must be rendered when the method is called, or if the implementation may only render the data it currently has. An application receives notifications about the new map data through MapServiceListener interface that it can register in the MapServiceProvider.getMap service request. When the map service provider has new map data is available the application is notified through MapServiceListener.mapContentUpdated callback method.

This class also provides two convenience methods that help in converting points on the map to WGS84 coordinates (see reference [WGS84]) and vice versa.

Since:

2.0

Method Summary

void	abort() Aborts ongoing renderMap method execution .
int[]	centerOnCoordinates(Coordinates center) Centers the map to the given coordinates.
float	getAzimuth() Returns the current azimuth of the map.
int	getHeight() Returns the height of the map in pixels.
MapServicePreferences	getMapServicePreferences() Returns the preferences set to be used in renderMap method.
int	getNumberOfZoomLevels() Returns the number of zoom levels that are supported in this Map object.
RectangleGeographicArea	getViewport() Returns a RectangleGeographicArea object that defines the current viewport to the map.
int	getWidth() Returns the width of the map in pixels.
int	getZoomLevel() Returns the current zoom level used in this Map object.
int[]	pan(int x, int y, boolean wholeAmount) Pans the map to the given direction.
void	renderMap(java.lang.Object graphics, boolean needCompleteImage) Renders this map to the graphics context passed in as parameter graphics.
float	rotate(float azimuth) Rotates the map to the given azimuth.
void	setMapServicePreferences(MapServicePreferences preferences) Sets new preferences to this Map object.
boolean	setSize(int width, int height, boolean keepZoomLevel) Changes the size of area where the map is rendered.
boolean	setViewport(RectangleGeographicArea area) Set a new viewport to the map.
boolean	setZoomLevel(int level) Sets a new zoom level for this Map object.
Coordinates	transformPixelsToWGS84Coordinates(int x, int y) Converts a point on area where the map is rendered into WGS84 coordinates.
int[]	transformWGS84CoordinatesToPixels(Coordinates coordinates) Converts coordinates in WGS84 projection system into the coordinate system of the area where the map is rendered.

Method Detail

setMapServicePreferences

void setMapServicePreferences(MapServicePreferences preferences)

Sets new preferences to this Map object. These preferences are used in the renderMap method when rending the map to the given graphics context. If an application does not call this after this Map object is returned from the MapServiceProvider.getMap method, the default values of the service preferences are used.

Parameters:

preferences - preferences to be used in renderMap method, null to indicate default preferences

Throws:

java.lang.IllegalArgumentException - if preferences is not preferences for the service provider used to retrieve this object

getMapServicePreferences

MapServicePreferences getMapServicePreferences()

Returns the preferences set to be used in renderMap method. If an application has not set any preferences for this Map object with method setMapServicePreferences, the default values of the service preferences are returned.

Returns:

the service preferences for this map object

renderMap

void renderMap(java.lang.Object graphics,
               boolean needCompleteImage)
               throws java.lang.InterruptedException

Renders this map to the graphics context passed in as parameter graphics. The API implementation must render at least the current viewport (geographic area).

With parameter needCompleteImage an application can control whether the all the map content for the viewport must be available and rendered completely to the graphic context or if the map content may be updated later. If an application accepts partial map content, it sets the needCompleteImage parameter to false. The MapServiceListener has been set in MapServiceListener.getMap method call. When new map content is available, an application is notified through MapServiceListener.mapContentUpdated callback method. After receiving this notification an application should render the map again.

This is a synchronous method and it blocks until the map has been rendered completely. The application may cancel the synchronous request with abort() method. This will cause the request to throw an InterruptedException.

Parameters:

graphics - the graphics context the map is rendered to

needCompleteImage - true, if an application needs full content in the map, false, if partial content is accepted

Throws:

java.lang.IllegalArgumentException - if given graphics context is not supported by the implementation

java.lang.InterruptedException - if the operation has been canceled by the application

java.lang.NullPointerException - if graphics is null

getViewport

RectangleGeographicArea getViewport()

Returns a RectangleGeographicArea object that defines the current viewport to the map. If the map has been rotated this method returns a the minimum RectangleGgeographicArea that contains the rotated viewport area. In this case, the returned area may be bigger than the rotated viewport.

Returns:

the viewport of the map as a geographic area

setViewport

boolean setViewport(RectangleGeographicArea area)

Set a new viewport to the map. This method sets the viewport in direction to true north. If an application needs a rotated viewport, it must call rotate method when this method has been finished. Setting the viewport may fail, if for example the viewport is outside the supported area.

Parameters:

area - the new viewport to the map

Returns:

true, if setting the viewport was successful, else false

Throws:

java.lang.NullPointerException - if area is null

getAzimuth

float getAzimuth()

Returns the current azimuth of the map. The value has been set in rotate method.

Returns:

the azimuth of the map

pan

int[] pan(int x,
          int y,
          boolean wholeAmount)

Pans the map to the given direction. The panning can be done to upwards, downwards, left or right. Upward and left direction must be indicated with negative number of pixels. Movement to downwards and right must be indicated with positive number of pixels. The new viewport to the map can be retrieved with method getViewport.

With the parameter wholeAmount an application controls whether panning is done if only partial amount of pixels can be moved. If wholeAmount is set to true and panning the requested amount of pixels can not be done, the method returns without actions and the returned array contains two 0 values.

The method returns the number of pixels that were panned. The first element in the return array indicates movement in horizontal direction and second element the movement in vertical direction.

Parameters:

x - the number of x pixels to be panned in horizontal direction

y - the number of y pixels to be panned in vertical direction

wholeAmount - true, if panning is done only if requested amount of pixels can be panned, false if partial panning is accepted by the application

Returns:

an int array, where the first element contains the number of pixels moved in horizontal direction and the second element the number of pixels moved in vertical direction

getWidth

int getWidth()

Returns the width of the map in pixels. The value is set when requesting this map from the service provider with MapServiceProvider.getMap method or in setSize method.

Returns:

the width of the map in pixels

getHeight

int getHeight()

Returns the height of the map in pixels. The value is set when requesting this map from the service provider with MapServiceProvider.getMap method or in setSize method.

Returns:

the height of the map in pixels

centerOnCoordinates

int[] centerOnCoordinates(Coordinates center)

Centers the map to the given coordinates. The size of the viewport does not change and the new viewport area can be retrieved with getViewport method.

The method returns the number of pixels that the map moved. Movement to upwards and left direction is indicated with negative number of pixels. Movement to downwards and right direction is indicated with positive number of pixels. The first element in the return array indicates movement in horizontal direction and second element the movement in vertical direction.

Parameters:

center - the Coordinates where the map is centered

Returns:

an int array, where the first element contains the number of pixels moved in horizontal direction and the second element the number of pixels moved in vertical direction

Throws:

java.lang.IllegalArgumentException - if center is not within this Map object

abort

void abort()

Aborts ongoing renderMap method execution . The renderMap method throws InterruptedException when this method is called.

transformPixelsToWGS84Coordinates

Coordinates transformPixelsToWGS84Coordinates(int x,
                                              int y)

Converts a point on area where the map is rendered into WGS84 coordinates. x and y are presented in the coordinates system of the rendering area. The origin point is the top left corner of the area. The values on the x axis grow to right and on the y axis grow to down. Pixels outside the current rendered area may also be given.

This method does not include any information about the altitude into the returned Coordinates object. Therefore the altitude is set to Float.NaN.

Parameters:

x - position of the point in the horizontal axis of the area where the map is rendered

y - position of the point in the vertical axis of the area where the map is rendered

Returns:

the Coordinates object for the given point in the WGS84 projection, null if conversion can not be done

transformWGS84CoordinatesToPixels

int[] transformWGS84CoordinatesToPixels(Coordinates coordinates)

Converts coordinates in WGS84 projection system into the coordinate system of the area where the map is rendered. The first element in the returned array contains the point on the x axis and the second element is the point on the y axis of the rendering area. The origin point is the top left corner of the current viewport. The values on the x axis grow to right and on the y axis grow to down. Even if the given coordinates is not within the viewport, the rendering area coordinates are returned in relation to the origin point.

Parameters:

coordinates - coordinates in WGS84 projection to be converted

Returns:

an int array containing two items, first the point in the x and second the point in the y axis in the viewport coordinate system, null if conversion can not be done

Throws:

java.lang.NullPointerException - if coordinates is null

getNumberOfZoomLevels

int getNumberOfZoomLevels()

Returns the number of zoom levels that are supported in this Map object. The Map objects must supports at least 1 zoom level. The supported zoom levels are from 1 to the number returned from this method. If the method returns, for example, 4, the supported zoom levels are 1,2,3 and 4.

Returns:

the number of available zoom levels

setZoomLevel

boolean setZoomLevel(int level)

Sets a new zoom level for this Map object. The value must be within range [1, number of zoom levels]. The number of supported zoom levels can be retrieved with method getNumberOfZoomLevels. Setting the zoom level to a value smaller than the current zoom level zooms the map out. If the new zoom level is bigger than the current zoom level, the map is zoomed in.

Parameters:

level - the new zoom level for the map

Returns:

true if operation was successful, else false

Throws:

java.lang.IllegalArgumentException - if level is not within in range [1, number of zoom levels]

getZoomLevel

int getZoomLevel()

Returns the current zoom level used in this Map object. The returned value is within range [1, number of zoom levels]. The number of supported zoom levels can be retrieved with method getNumberOfZoomLevels.

Returns:

the current zoom level of the map

rotate

float rotate(float azimuth)

Rotates the map to the given azimuth. The azimuth is given as degrees from true north. The support for rotation can be checked with method ProviderCapabilities.getPropertyValue using MAP_SUPPORTS_MAP_ROTATION as the property key. If the service provider that constructed this object does not support rotation, this method throws an IllegalArgumentException if azimuth is other than 0.0. If rotation is supported but the rotation can not be made to the given azimuth, it is made to the closest possible azimuth. If the requested azimuth is in the middle of two supported azimuths, the rotation is done to the smaller supported azimuth. The realized rotation azimuth is returned. If the rotation fails, Float.NaN is returned.

When the map is rotated, the geographical area shown on the map changes. The center point of the geographical area remains the same. The new viewport is the area around the center point that fits into the current graphics context. The zoom level must not be changed. The geographical area can be retrieved with method getViewport.

Parameters:

azimuth - the rotation angle from true north in the clockwise direction

Returns:

the azimuth to which the map was rotated, Float.NaN if rotation failed

Throws:

java.lang.IllegalArgumentException - if azimuth < 0.0 or azimuth >= 360.0 or if map service provider does not support rotation and azimuth is other than 0.0

setSize

boolean setSize(int width,
                int height,
                boolean keepZoomLevel)

Changes the size of area where the map is rendered. The given width and height form the minimum area that is rendered with the renderMap method. This method can be used, for example, if the orientation of the device display changes. The new size is given in pixels.

With the parameter keepZoomLevel an application controls how the area size change affects the map. If keepZoomLevel is set to true, the zoom level of the map remains the same, and only the area shown changes. If keepZoomLevel is false, the zoom level of the map changes and implementation does its best to show the same area as before calling this method. In both cases the coordinates of the center point of the viewport must remain the same.

Parameters:

width - the width of the area where map is rendered in pixels

height - the height of the area where map is rendered in pixels

keepZoomLevel - true, if zoom level does not change, false if zoom level changes

Returns:

true, if operation was successful, else false

Throws:

java.lang.IllegalArgumentException - if width <= 0 or height <= 0