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 as displayed to the user.
066     *
067     * @return Name of the tile layer
068     */
069    String getName();
070
071    /**
072     * A unique id for this tile source.
073     * 
074     * Unlike the name it has to be unique and has to consist only of characters
075     * valid for filenames.
076     * 
077     * @return the id
078     */
079    String getId();
080
081    /**
082     * Constructs the tile url.
083     *
084     * @param zoom
085     * @param tilex
086     * @param tiley
087     * @return fully qualified url for downloading the specified tile image
088     */
089    String getTileUrl(int zoom, int tilex, int tiley) throws IOException;
090
091    /**
092     * Specifies the tile image type. For tiles rendered by Mapnik or
093     * Osmarenderer this is usually <code>"png"</code>.
094     *
095     * @return file extension of the tile image type
096     */
097    String getTileType();
098
099    /**
100     * Specifies how large each tile is.
101     * @return The size of a single tile in pixels.
102     */
103    int getTileSize();
104
105    /**
106     * Gets the distance using Spherical law of cosines.
107     *  @return the distance, m.
108     */
109    double getDistance(double la1, double lo1, double la2, double lo2);
110
111    /**
112     * Transform longitude to pixelspace.
113     * @return [0..2^Zoomlevel*TILE_SIZE[
114     */
115    int LonToX(double aLongitude, int aZoomlevel);
116
117    /**
118     * Transforms latitude to pixelspace.
119     * @return [0..2^Zoomlevel*TILE_SIZE[
120     */
121    int LatToY(double aLat, int aZoomlevel);
122
123    /**
124     * Transforms pixel coordinate X to longitude
125     * @return ]-180..180[
126     */
127    double XToLon(int aX, int aZoomlevel);
128
129    /**
130     * Transforms pixel coordinate Y to latitude.
131     * @return [MIN_LAT..MAX_LAT]
132     */
133    double YToLat(int aY, int aZoomlevel);
134
135    /**
136     * Transforms longitude to X tile coordinate.
137     * @return [0..2^Zoomlevel[
138     */
139    double lonToTileX(double lon, int zoom);
140
141    /**
142     * Transforms latitude to Y tile coordinate.
143     * @return [0..2^Zoomlevel[
144     */
145    double latToTileY(double lat, int zoom);
146
147    /**
148     * Transforms tile X coordinate to longitude.
149     * @return ]-180..180[
150     */
151    double tileXToLon(int x, int zoom);
152
153    /**
154     * Transforms tile Y coordinate to latitude.
155     * @return [MIN_LAT..MAX_LAT]
156     */
157    double tileYToLat(int y, int zoom);
158}