Added core map support.

enough-polish-j2me/source/src/de/enough/polish/maps/MapProvider.java

@@ -0,0 +1,74 @@
+package de.enough.polish.maps;
+
+/**
+ * This interface defines the functionality required to implement a map provider. This includes methods for generating {@link MapRequests} that are guaranteed to be valid when used with the provider,
+ * using the generated {@link MapRequest} to generate a valid {@link MapResponse} and being able to resolve the {@link MapTile}s of the generated {@link MapResponse}. Additional methods include converting from geo-coordinates to world-pixels and vice-versa.
+ * Although possible, inter-changing {@link MapRequest}s, {@link MapResponse}s and {@link MapTile}s between different provider implementations is not guaranteed to work. 
+ * @author Ovidiu Iliescu
+ */
+public interface MapProvider {
+
+	/**
+	 * Generates a map request for the given parameters. {@link MapRequest}s generated by using this method are guaranteed to be valid with this provider's {@link MapProvider#prepareResponse(MapRequest)} method.
+	 * @param lat the latitude of the map request center point
+	 * @param lon the longitude of the map request center point
+	 * @param width the width of the map request (in pixels)
+	 * @param height the height of the map request (in pixels)
+	 * @param zoom the desired zoom level
+	 * @return a MapRequest object
+	 */
+	public MapRequest getRequestForCoords(double lat, double lon, int width, int height, int zoom);
+
+	/**
+	 * Prepares a MapResponse based on the given {@link MapRequest}. Only {@link MapRequest}s generated using the provider's {@link MapProvider#getRequestForCoords(double, double, int, int, int)} method are guaranteed to
+	 * be valid with this method.
+	 * @param request the source request
+	 * @return the map response
+	 */
+	public MapResponse prepareResponse(MapRequest request);
+
+	/**
+	 * Resolves a given {@link MapTile}. This typically involves retrieving the server-side image corresponding to the tile. Only {@link MapTile}s that belong to a {@link MapResponse} generated by the provider are guaranteed to be valid and working with this method.
+	 * @param tile the tile to resolve
+	 * @throws Exception
+	 */
+	public void resolveTile(MapTile tile) throws Exception;
+
+	/**
+	 * Returns the provider's minimum zoom level
+	 * @return the provider's minimum zoom level
+	 */
+	public int getMinZoomLevel();
+
+	/**
+	 * Returns the provider's maximum zoom level
+	 * @return the provider's maximum zoom level
+	 */
+	public int getMaxZoomLevel();
+
+	/**
+	 * Returns the provider's recommended zoom level
+	 * @return the provider's recommended zoom level
+	 */
+	public int getRecommendedZoomLevel();
+
+	/**
+	 * Calculates destination geo-coordinates based on a set of original geo-coordinates and X/Y offsets (in pixels).
+	 * @param lat the original latitude
+	 * @param lon the original longitude
+	 * @param deltaY the Y offset (in pixels)
+	 * @param deltaX the X offset (in pixels)
+	 * @param zoom the zoom level
+	 * @return the resulting {lat, lon} set of coordinates
+	 */
+	public double[] getCoordsByPixelOffset(double lat, double lon, int deltaY, int deltaX, int zoom);
+
+	/**
+	 * Converts a set of geo-coordinates to world-pixels, based on the specified zoom level. 
+	 * @param lat the latitude
+	 * @param lon the longitude
+	 * @param zoomLevel the zoom level 
+	 * @return the resulting {y,x} coordinates (in pixels)
+	 */
+	public int[] coordsToPixels(double lat, double lon, int zoomLevel);
+}

enough-polish-j2me/source/src/de/enough/polish/maps/MapRequest.java

@@ -0,0 +1,134 @@
+package de.enough.polish.maps;
+
+/**
+ * This class defines a map request, used to define what part of the world map is needed, and at what zoom level 
+ * @author Ovidiu Iliescu
+ */
+public class MapRequest {
+
+	/**
+	 * The latitude of the map request's center point
+	 */
+	protected double lat;
+
+	/**
+	 * The longitude of the map request's center point
+	 */
+	protected double lon;
+
+	/**
+	 * The width of the map request (in pixels)	
+	 */
+	protected int pixelW = 100;
+
+	/**
+	 * The height of the map request (in pixels)
+	 */
+	protected int pixelH = 100;
+
+	/**
+	 * The desired zoom level
+	 */
+	protected int zoom = 1;
+
+	/**
+	 * The desired tile size
+	 */
+	protected int tileSize;
+
+	/**
+	 * Retrieves the desired tile size for this request
+	 * @return the desired tile size for this request
+	 */
+	public int getTileSize() {
+		return tileSize;
+	}
+
+	/**
+	 * Sets the desired tile size for this request
+	 * @param tileSize  the desired tile size for this request
+	 */
+	public void setTileSize(int tileSize) {
+		this.tileSize = tileSize;
+	}
+
+	/**
+	 * Returns the latitude of the map request's center point
+	 * @return the latitude of the map request's center point
+	 */
+	public double getLat() {
+		return this.lat;
+	}
+
+	/**
+	 * Returns the longitude of the map request's center point
+	 * @return the longitude of the map request's center point
+	 */
+	public double getLon() {
+		return this.lon;
+	}	
+
+	/**
+	 * Sets the latitude of the map request's center point
+	 * @param lat the latitude of the map request's center point
+	 */
+	public void setLat(double lat) {
+		this.lat = lat;
+	}
+
+	/**
+	 * Sets the longitude of the map request's center point
+	 * @param lat the longitude of the map request's center point
+	 */
+	public void setLon(double lon) {
+		this.lon = lon;
+	}	
+
+	/**
+	 * Returns the request's width (in pixels)
+	 * @return the request's width (in pixels)
+	 */
+	public int getWidthInPixels() {
+		return this.pixelW;
+	}
+
+	/** Sets the request's width (in pixels)
+	 * @param w the request's width (in pixels)
+	 */
+	public void setWidthInPixels(int w) {
+		this.pixelW = w;
+	}
+
+	/**
+	 * Returns the request's height (in pixels)
+	 * @return the request's height (in pixels)
+	 */
+	public int getHeightInPixels() {
+		return this.pixelH;
+	}
+
+	/**
+	 * Sets the request's height (in pixels)
+	 * @param h the request's height (in pixels)
+	 */
+	public void setHeightInPixels(int h) {
+		this.pixelH = h;
+	}
+
+	/**
+	 * Returns the request's desired zoom level
+	 * @return the request's desired zoom level
+	 */
+	public int getZoom() {
+		return this.zoom;
+	}
+
+	/**
+	 * Sets the request's desired zoom level
+	 * @param zoom the request's desired zoom level
+	 */
+	public void setZoom(int zoom) {
+		this.zoom = zoom;
+	}
+
+}

enough-polish-j2me/source/src/de/enough/polish/maps/MapResponse.java

@@ -0,0 +1,165 @@
+package de.enough.polish.maps;
+
+import java.util.Vector;
+
+/**
+ * This class defines a map response received from a {@link MapProvider} as a result of processing a {@link MapRequest}. A map response contains a list
+ * of {@link MapTile}s required to pain the response, as well as all the information needed to properly paint it.
+ * @author Ovidiu Iliescu
+ */
+public class MapResponse {
+
+	/**
+	 * The {@link MapRequest} associated with this map response
+	 */
+	protected MapRequest associatedMapRequest;
+
+	/**
+	 * The x offset needed to properly paint the map response.
+	 */
+	protected int xOffset;
+
+	/**
+	 * The y offset needed to properly paint the map response.
+	 */
+	protected int yOffset;
+
+	/**
+	 * As the map response is a rectangular map section made out of a tile matrix, this represents the number of tiles per matrix row.
+	 */
+	protected int tilesPerRow;
+
+	/**
+	 * The map response width (in pixels)
+	 */
+	protected int width;
+
+	/**
+	 * The map response height (in pixels)
+	 */
+	protected int height;
+
+	/**
+	 * The actual map tiles needed to paint the response.
+	 */
+	protected Vector tiles = new Vector() ;
+
+
+	/**
+	 * Returns the map response width (in pixels)
+	 * @return the map response width (in pixels)
+	 */
+	public int getWidth() {
+		return width;
+	}
+
+	/**
+	 * Sets the map response width (in pixels)
+	 * @param width the map response width (in pixels)
+	 */
+	public void setWidth(int width) {
+		this.width = width;
+	}
+
+	/**
+	 * Returns the map response height (in pixels)
+	 * @return the map response height (in pixels)
+	 */
+	public int getHeight() {
+		return height;
+	}
+
+	/**
+	 * Sets the map response height (in pixels)
+	 * @param height the map response height (in pixels)
+	 */
+	public void setHeight(int height) {
+		this.height = height;
+	}
+
+	/**
+	 * Returns the associated map request, based on which this map response has been created
+	 * @return the associated map request
+	 */
+	public MapRequest getAssociatedMapRequest() {
+		return associatedMapRequest;
+	}
+
+	/**
+	 * Sets the associated map request
+	 * @param associatedMapRequest the associated map request
+	 */
+	public void setAssociatedMapRequest(MapRequest associatedMapRequest) {
+		this.associatedMapRequest = associatedMapRequest;
+	}
+
+	/**
+	 * Returns the number of map tiles per row (the map response width in tiles)
+	 * @return the number of map tiles per row (the map response width in tiles)
+	 */
+	public int getTilesPerRow() {
+		return tilesPerRow;
+	}
+
+	/**
+	 * Sets the number of map tiles per row (the map response width in tiles)
+	 * @param tilesPerRow the number of map tiles per row (the map response width in tiles)
+	 */
+	public void setTilesPerRow(int tilesPerRow) {
+		this.tilesPerRow = tilesPerRow;
+	}
+
+	/**
+	 * The map response is made up of a matrix of map tiles, which are typically obtained by splitting the world-map into fixed-size pieces (tiles) starting
+	 * at world offset (0,0). However, depending on the map coordinates given and on the map provider used, there is usually a need to paint
+	 * the top-left tile of the response matrix with an offset, for example if the map response's top-left PIXEL is actually located in the center of the map response's top-left TILE.
+	 * This method returns the horizontal top-left tile offset needed to properly paint the map response starting with the right pixels.
+	 * @return the horizontal top-left tile offset needed to properly paint the map response starting with the right pixels.
+	 */
+	public int getXOffset() {
+		return xOffset;
+	}
+
+	/**
+	 * Sets the horizontal top-left tile offset needed to properly paint the map response starting with the right pixels.
+	 * @param xOffset the horizontal top-left tile offset needed to properly paint the map response starting with the right pixels.
+	 */
+	public void setXOffset(int xOffset) {
+		this.xOffset = xOffset;
+	}
+
+	/**
+	 * The map response is made up of a matrix of map tiles, which are typically obtained by splitting the world-map into fixed-size pieces (tiles) starting
+	 * at world offset (0,0). However, depending on the map coordinates given and on the map provider used, there is usually a need to paint
+	 * the top-left tile of the response matrix with an offset, for example if the map response's top-left PIXEL is actually located in the center of the map response's top-left TILE.
+	 * This method returns the vertical top-left tile offset needed to properly paint the map response starting with the right pixels.
+	 * @return the vertical top-left tile offset needed to properly paint the map response starting with the right pixels.
+	 */
+	public int getYOffset() {
+		return yOffset;
+	}
+
+	/**
+	 * Sets the vertical top-left tile offset needed to properly paint the map response starting with the right pixels.
+	 * @param yOffset the vertical top-left tile offset needed to properly paint the map response starting with the right pixels.
+	 */
+	public void setYOffset(int yOffset) {
+		this.yOffset = yOffset;
+	}
+
+	/**
+	 * Returns the set of map tiles needed to paint the map response
+	 * @return the set of map tiles needed to paint the map response
+	 */
+	public Vector getTiles() {
+		return tiles;
+	}
+
+	/**
+	 * Sets the set of map tiles needed to paint the map response
+	 * @param tiles the set of map tiles needed to paint the map response
+	 */
+	public void setTiles(Vector tiles) {
+		this.tiles = tiles;
+	}
+}