001// License: GPL. For details, see Readme.txt file.
002package org.openstreetmap.gui.jmapviewer.interfaces;
003
004import java.io.IOException;
005
006import org.openstreetmap.gui.jmapviewer.JMapViewer;
007
008/**
009 *
010 * @author Jan Peter Stotz
011 */
012public interface TileSource extends Attributed {
013
014    /**
015     * Specifies the different mechanisms for detecting updated tiles
016     * respectively only download newer tiles than those stored locally.
017     *
018     * <ul>
019     * <li>{@link #IfNoneMatch} Server provides ETag header entry for all tiles
020     * and <b>supports</b> conditional download via <code>If-None-Match</code>
021     * header entry.</li>
022     * <li>{@link #ETag} Server provides ETag header entry for all tiles but
023     * <b>does not support</b> conditional download via
024     * <code>If-None-Match</code> header entry.</li>
025     * <li>{@link #IfModifiedSince} Server provides Last-Modified header entry
026     * for all tiles and <b>supports</b> conditional download via
027     * <code>If-Modified-Since</code> header entry.</li>
028     * <li>{@link #LastModified} Server provides Last-Modified header entry for
029     * all tiles but <b>does not support</b> conditional download via
030     * <code>If-Modified-Since</code> header entry.</li>
031     * <li>{@link #None} The server does not support any of the listed
032     * mechanisms.</li>
033     * </ul>
034     *
035     */
036    public enum TileUpdate {
037        IfNoneMatch, ETag, IfModifiedSince, LastModified, None
038    }
039
040    /**
041     * Specifies the maximum zoom value. The number of zoom levels is [0..
042     * {@link #getMaxZoom()}].
043     *
044     * @return maximum zoom value that has to be smaller or equal to
045     *         {@link JMapViewer#MAX_ZOOM}
046     */
047    int getMaxZoom();
048
049    /**
050     * Specifies the minimum zoom value. This value is usually 0.
051     * Only for maps that cover a certain region up to a limited zoom level
052     * this method should return a value different than 0.
053     *
054     * @return minimum zoom value - usually 0
055     */
056    int getMinZoom();
057
058    /**
059     * @return The supported tile update mechanism
060     * @see TileUpdate
061     */
062    TileUpdate getTileUpdate();
063
064    /**
065     * A tile layer name has to be unique and has to consist only of characters
066     * valid for filenames.
067     *
068     * @return Name of the tile layer
069     */
070    String getName();
071
072    /**
073     * Constructs the tile url.
074     *
075     * @param zoom
076     * @param tilex
077     * @param tiley
078     * @return fully qualified url for downloading the specified tile image
079     */
080    String getTileUrl(int zoom, int tilex, int tiley) throws IOException;
081
082    /**
083     * Specifies the tile image type. For tiles rendered by Mapnik or
084     * Osmarenderer this is usually <code>"png"</code>.
085     *
086     * @return file extension of the tile image type
087     */
088    String getTileType();
089
090    /**
091     * Specifies how large each tile is.
092     * @return The size of a single tile in pixels.
093     */
094    int getTileSize();
095
096    /**
097     * Gets the distance using Spherical law of cosines.
098     *  @return the distance, m.
099     */
100    double getDistance(double la1, double lo1, double la2, double lo2);
101
102    /**
103     * Transform longitude to pixelspace.
104     * @return [0..2^Zoomlevel*TILE_SIZE[
105     */
106    int LonToX(double aLongitude, int aZoomlevel);
107
108    /**
109     * Transforms latitude to pixelspace.
110     * @return [0..2^Zoomlevel*TILE_SIZE[
111     */
112    int LatToY(double aLat, int aZoomlevel);
113
114    /**
115     * Transforms pixel coordinate X to longitude
116     * @return ]-180..180[
117     */
118    double XToLon(int aX, int aZoomlevel);
119
120    /**
121     * Transforms pixel coordinate Y to latitude.
122     * @return [MIN_LAT..MAX_LAT]
123     */
124    double YToLat(int aY, int aZoomlevel);
125
126    /**
127     * Transforms longitude to X tile coordinate.
128     * @return [0..2^Zoomlevel[
129     */
130    double lonToTileX(double lon, int zoom);
131
132    /**
133     * Transforms latitude to Y tile coordinate.
134     * @return [0..2^Zoomlevel[
135     */
136    double latToTileY(double lat, int zoom);
137
138    /**
139     * Transforms tile X coordinate to longitude.
140     * @return ]-180..180[
141     */
142    double tileXToLon(int x, int zoom);
143
144    /**
145     * Transforms tile Y coordinate to latitude.
146     * @return [MIN_LAT..MAX_LAT]
147     */
148    double tileYToLat(int y, int zoom);
149}