MapTileProviderBase.java

// Created by plusminus on 21:46:22 - 25.09.2008
package org.mozilla.osmdroid.tileprovider;

import android.graphics.drawable.Drawable;
import android.os.Handler;

import org.mozilla.mozstumbler.service.core.logging.ClientLog;
import org.mozilla.mozstumbler.svclocator.services.log.LoggerUtil;
import org.mozilla.osmdroid.tileprovider.constants.OSMConstants;
import org.mozilla.osmdroid.tileprovider.tilesource.ITileSource;

/**
 * This is an abstract class. The tile provider is responsible for:
 * <ul>
 * <li>determining if a map tile is available,</li>
 * <li>notifying the client, via a callback handler</li>
 * </ul>
 * see {@link MapTile} for an overview of how tiles are served by this provider.
 *
 * @author Marc Kurtz
 * @author Nicolas Gramlich
 */
public abstract class MapTileProviderBase implements IMapTileProviderCallback,
        OSMConstants {

    private static final String LOG_TAG = LoggerUtil.makeLogTag(MapTileProviderBase.class);

    protected final MapTileCache mTileCache;
    protected Handler mTileRequestCompleteHandler;
    protected boolean mUseDataConnection = true;

    private ITileSource mTileSource;

    public MapTileProviderBase(final ITileSource pTileSource) {
        this(pTileSource, null);
    }

    public MapTileProviderBase(final ITileSource pTileSource,
                               final Handler pDownloadFinishedListener) {
        mTileCache = this.createTileCache();
        mTileRequestCompleteHandler = pDownloadFinishedListener;
        mTileSource = pTileSource;
    }

    /**
     * Attempts to get a Drawable that represents a {@link MapTile}. If the tile is not immediately
     * available this will return null and attempt to get the tile from known tile sources for
     * subsequent future requests. Note that this may return a {@link ReusableBitmapDrawable} in
     * which case you should follow proper handling procedures for using that Drawable or it may
     * reused while you are working with it.
     *
     * @see ReusableBitmapDrawable
     */
    public abstract Drawable getMapTile(MapTile pTile);

    public abstract void detach();

    /**
     * Gets the minimum zoom level this tile provider can provide
     *
     * @return the minimum zoom level
     */
    public abstract int getMinimumZoomLevel();

    /**
     * Gets the maximum zoom level this tile provider can provide
     *
     * @return the maximum zoom level
     */
    public abstract int getMaximumZoomLevel();

    /**
     * Gets the tile source for this tile provider.
     *
     * @return the tile source
     */
    public ITileSource getTileSource() {
        return mTileSource;
    }

    /**
     * Sets the tile source for this tile provider.
     *
     * @param pTileSource the tile source
     */
    public void setTileSource(final ITileSource pTileSource) {
        mTileSource = pTileSource;
        clearTileCache();
    }

    /**
     * Creates a {@link MapTileCache} to be used to cache tiles in memory.
     */
    public MapTileCache createTileCache() {
        return new MapTileCache();
    }

    /**
     * Called by implementation class methods indicating that they have completed the request as
     * best it can. The tile is added to the cache, and a MAPTILE_SUCCESS_ID message is sent.
     *
     * @param pState    the map tile request state object
     * @param pDrawable the Drawable of the map tile
     */
    @Override
    public void mapTileRequestCompleted(final MapTileRequestState pState, final Drawable pDrawable) {
        // put the tile in the cache
        putTileIntoCache(pState, pDrawable);

        // tell our caller we've finished and it should update its view
        if (mTileRequestCompleteHandler != null) {
            mTileRequestCompleteHandler.sendEmptyMessage(MapTile.MAPTILE_SUCCESS_ID);
        }

        if (DEBUG_TILE_PROVIDERS) {
            ClientLog.d(LOG_TAG, "MapTileProviderBase.mapTileRequestCompleted(): " + pState.getMapTile());
        }
    }

    /**
     * Called by implementation class methods indicating that they have failed to retrieve the
     * requested map tile. a MAPTILE_FAIL_ID message is sent.
     *
     * @param pState the map tile request state object
     */
    @Override
    public void mapTileRequestFailed(final MapTileRequestState pState) {
        if (mTileRequestCompleteHandler != null) {
            mTileRequestCompleteHandler.sendEmptyMessage(MapTile.MAPTILE_FAIL_ID);
        }

        if (DEBUG_TILE_PROVIDERS) {
            ClientLog.d(LOG_TAG, "MapTileProviderBase.mapTileRequestFailed(): " + pState.getMapTile());
        }
    }

    /**
     * Called by implementation class methods indicating that they have produced an expired result
     * that can be used but better results may be delivered later. The tile is added to the cache,
     * and a MAPTILE_SUCCESS_ID message is sent.
     *
     * @param pState    the map tile request state object
     * @param pDrawable the Drawable of the map tile
     */
    @Override
    public void mapTileRequestExpiredTile(MapTileRequestState pState, Drawable pDrawable) {
        // Put the expired tile into the cache
        putExpiredTileIntoCache(pState, pDrawable);

        // tell our caller we've finished and it should update its view
        if (mTileRequestCompleteHandler != null) {
            mTileRequestCompleteHandler.sendEmptyMessage(MapTile.MAPTILE_SUCCESS_ID);
        }

        if (DEBUG_TILE_PROVIDERS) {
            ClientLog.d(LOG_TAG, "MapTileProviderBase.mapTileRequestExpiredTile(): " + pState.getMapTile());
        }
    }

    protected void putTileIntoCache(MapTileRequestState pState, Drawable pDrawable) {
        final MapTile tile = pState.getMapTile();
        if (pDrawable != null) {
            mTileCache.putTile(tile, pDrawable);
        }
    }

    protected void putExpiredTileIntoCache(MapTileRequestState pState, Drawable pDrawable) {
        final MapTile tile = pState.getMapTile();
        if (pDrawable != null && !mTileCache.containsTile(tile)) {
            mTileCache.putTile(tile, pDrawable);
        }
    }

    public void setTileRequestCompleteHandler(final Handler handler) {
        mTileRequestCompleteHandler = handler;
    }

    public void ensureCapacity(final int pCapacity) {
        mTileCache.ensureCapacity(pCapacity);
    }

    public void clearTileCache() {
        mTileCache.clear();
    }

    /**
     * Whether to use the network connection if it's available.
     */
    @Override
    public boolean useDataConnection() {
        return mUseDataConnection;
    }

    /**
     * Set whether to use the network connection if it's available.
     *
     * @param pMode if true use the network connection if it's available. if false don't use the
     *              network connection even if it's available.
     */
    public void setUseDataConnection(final boolean pMode) {
        mUseDataConnection = pMode;
    }
}