001package org.openstreetmap.gui.jmapviewer.interfaces;
002
003import java.io.IOException;
004
005import org.openstreetmap.gui.jmapviewer.JMapViewer;
006
007//License: GPL. Copyright 2008 by Jan Peter Stotz
008
009/**
010 *
011 * @author Jan Peter Stotz
012 */
013public interface TileSource extends Attributed {
014
015    /**
016     * Specifies the different mechanisms for detecting updated tiles
017     * respectively only download newer tiles than those stored locally.
018     *
019     * <ul>
020     * <li>{@link #IfNoneMatch} Server provides ETag header entry for all tiles
021     * and <b>supports</b> conditional download via <code>If-None-Match</code>
022     * header entry.</li>
023     * <li>{@link #ETag} Server provides ETag header entry for all tiles but
024     * <b>does not support</b> conditional download via
025     * <code>If-None-Match</code> header entry.</li>
026     * <li>{@link #IfModifiedSince} Server provides Last-Modified header entry
027     * for all tiles and <b>supports</b> conditional download via
028     * <code>If-Modified-Since</code> header entry.</li>
029     * <li>{@link #LastModified} Server provides Last-Modified header entry for
030     * all tiles but <b>does not support</b> conditional download via
031     * <code>If-Modified-Since</code> header entry.</li>
032     * <li>{@link #None} The server does not support any of the listed
033     * mechanisms.</li>
034     * </ul>
035     *
036     */
037    public enum TileUpdate {
038        IfNoneMatch, ETag, IfModifiedSince, LastModified, None
039    }
040
041    /**
042     * Specifies the maximum zoom value. The number of zoom levels is [0..
043     * {@link #getMaxZoom()}].
044     *
045     * @return maximum zoom value that has to be smaller or equal to
046     *         {@link JMapViewer#MAX_ZOOM}
047     */
048    int getMaxZoom();
049
050    /**
051     * Specifies the minimum zoom value. This value is usually 0.
052     * Only for maps that cover a certain region up to a limited zoom level
053     * this method should return a value different than 0.
054     *
055     * @return minimum zoom value - usually 0
056     */
057    int getMinZoom();
058
059    /**
060     * @return The supported tile update mechanism
061     * @see TileUpdate
062     */
063    TileUpdate getTileUpdate();
064
065    /**
066     * A tile layer name has to be unique and has to consist only of characters
067     * valid for filenames.
068     *
069     * @return Name of the tile layer
070     */
071    String getName();
072
073    /**
074     * Constructs the tile url.
075     *
076     * @param zoom
077     * @param tilex
078     * @param tiley
079     * @return fully qualified url for downloading the specified tile image
080     */
081    String getTileUrl(int zoom, int tilex, int tiley) throws IOException;
082
083    /**
084     * Specifies the tile image type. For tiles rendered by Mapnik or
085     * Osmarenderer this is usually <code>"png"</code>.
086     *
087     * @return file extension of the tile image type
088     */
089    String getTileType();
090
091    /**
092     * Specifies how large each tile is.
093     * @return The size of a single tile in pixels.
094     */
095    int getTileSize();
096
097    double latToTileY(double lat, int zoom);
098
099    double lonToTileX(double lon, int zoom);
100
101    double tileYToLat(int y, int zoom);
102
103    double tileXToLon(int x, int zoom);
104}