tasks/astrid/src/main/java/edu/mit/mobile/android/imagecache/ImageCache.java

package edu.mit.mobile.android.imagecache;

/*
 * Copyright (C) 2011-2012 MIT Mobile Experience Lab
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.net.URL;
import java.net.URLConnection;
import java.util.Collections;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.concurrent.PriorityBlockingQueue;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.StatusLine;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.HttpResponseException;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.params.ClientPNames;
import org.apache.http.conn.scheme.PlainSocketFactory;
import org.apache.http.conn.scheme.Scheme;
import org.apache.http.conn.scheme.SchemeRegistry;
import org.apache.http.conn.ssl.SSLSocketFactory;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager;
import org.apache.http.params.CoreConnectionPNames;
import org.apache.http.params.HttpParams;

import android.annotation.SuppressLint;
import android.app.Activity;
import android.content.Context;
import android.content.res.Resources;
import android.graphics.Bitmap;
import android.graphics.Bitmap.CompressFormat;
import android.graphics.BitmapFactory;
import android.graphics.drawable.BitmapDrawable;
import android.graphics.drawable.Drawable;
import android.net.Uri;
import android.os.Handler;
import android.os.Message;
import android.util.Log;
import android.util.SparseArray;
import android.widget.ImageView;

/**
 * <p>
 * An image download-and-cacher that also knows how to efficiently generate thumbnails of various
 * sizes.
 * </p>
 *
 * <p>
 * The cache is shared with the entire process, so make sure you
 * {@link #registerOnImageLoadListener(OnImageLoadListener)} and
 * {@link #unregisterOnImageLoadListener(OnImageLoadListener)} any load listeners in your
 * activities.
 * </p>
 *
 * @author <a href="mailto:spomeroy@mit.edu">Steve Pomeroy</a>
 *
 */
public class ImageCache extends DiskCache<String, Bitmap> {
    private static final String TAG = ImageCache.class.getSimpleName();

    static final boolean DEBUG = false;

    // whether to use Apache HttpClient or URL.openConnection()
    private static final boolean USE_APACHE_NC = true;

    // the below settings are copied from AsyncTask.java
    private static final int CORE_POOL_SIZE = 5; // thread
    private static final int MAXIMUM_POOL_SIZE = 128; // thread
    private static final int KEEP_ALIVE_TIME = 1; // second

    private final HashSet<OnImageLoadListener> mImageLoadListeners = new HashSet<ImageCache.OnImageLoadListener>();

    public static final int DEFAULT_CACHE_SIZE = (24 /* MiB */* 1024 * 1024); // in bytes

    private DrawableMemCache<String> mMemCache = new DrawableMemCache<String>(DEFAULT_CACHE_SIZE);

    private Integer mIDCounter = 0;

    private static ImageCache mInstance;

    // this is a custom Executor, as we want to have the tasks loaded in FILO order. FILO works
    // particularly well when scrolling with a ListView.
    private final ThreadPoolExecutor mExecutor = new ThreadPoolExecutor(CORE_POOL_SIZE,
            MAXIMUM_POOL_SIZE, KEEP_ALIVE_TIME, TimeUnit.SECONDS,
            new PriorityBlockingQueue<Runnable>());

    // ignored as SparseArray isn't thread-safe
    private final Map<Integer, Runnable> jobs = Collections
            .synchronizedMap(new HashMap<Integer, Runnable>());

    private final HttpClient hc;

    private CompressFormat mCompressFormat;
    private int mQuality;

    private final Resources mRes;

    private static final int MSG_IMAGE_LOADED = 100;

    private final KeyedLock<String> mDownloading = new KeyedLock<String>();

    private static class ImageLoadHandler extends Handler {
        private final ImageCache mCache;

        public ImageLoadHandler(ImageCache cache) {
            super();
            mCache = cache;
        }

        @Override
        public void handleMessage(Message msg) {
            switch (msg.what) {
                case MSG_IMAGE_LOADED:
                    mCache.notifyListeners((LoadResult) msg.obj);
                    break;
            }
        };
    }

    private final ImageLoadHandler mHandler = new ImageLoadHandler(this);

    // TODO make it so this is customizable on the instance level.
    /**
     * Gets an instance of the cache.
     *
     * @param context
     * @return an instance of the cache
     */
    public static ImageCache getInstance(Context context) {
        if (mInstance == null) {
            mInstance = new ImageCache(context, CompressFormat.JPEG, 85);
        }
        return mInstance;
    }

    /**
     * Generally, it's best to use the shared image cache using {@link #getInstance(Context)}. Use
     * this if you want to customize a cache or keep it separate.
     *
     * @param context
     * @param format
     * @param quality
     */
    public ImageCache(Context context, CompressFormat format, int quality) {
        super(context.getCacheDir(), null, getExtension(format));
        if (USE_APACHE_NC) {
            hc = getHttpClient();
        } else {
            hc = null;
        }

        mRes = context.getResources();

        mCompressFormat = format;
        mQuality = quality;
    }

    /**
     * Sets the compression format for resized images.
     *
     * @param format
     */
    public void setCompressFormat(CompressFormat format) {
        mCompressFormat = format;
    }

    /**
     * Set the image quality. Hint to the compressor, 0-100. 0 meaning compress for small size, 100
     * meaning compress for max quality. Some formats, like PNG which is lossless, will ignore the
     * quality setting
     *
     * @param quality
     */
    public void setQuality(int quality) {
        mQuality = quality;
    }

    /**
     * Sets the maximum size of the memory cache. Note, this will clear the memory cache.
     *
     * @param maxSize
     *            the maximum size of the memory cache in bytes.
     */
    public void setMemCacheMaxSize(int maxSize) {
        mMemCache = new DrawableMemCache<String>(maxSize);
    }

    private static String getExtension(CompressFormat format) {
        String extension;
        switch (format) {
            case JPEG:
                extension = ".jpg";
                break;

            case PNG:
                extension = ".png";
                break;

            default:
                throw new IllegalArgumentException();
        }

        return extension;
    }

    /**
     * If loading a number of images where you don't have a unique ID to represent the individual
     * load, this can be used to generate a sequential ID.
     *
     * @return a new unique ID
     */
    public int getNewID() {
        synchronized (mIDCounter) {
            return mIDCounter++;
        }
    }

    @Override
    protected Bitmap fromDisk(String key, InputStream in) {

        if (DEBUG) {
            Log.d(TAG, "disk cache hit for key " + key);
        }
        try {
            final Bitmap image = BitmapFactory.decodeStream(in);
            return image;

        } catch (final OutOfMemoryError oom) {
            oomClear();
            return null;
        }
    }

    @Override
    protected void toDisk(String key, Bitmap image, OutputStream out) {
        if (DEBUG) {
            Log.d(TAG, "disk cache write for key " + key);
        }
        if (image != null) {
            if (!image.compress(mCompressFormat, mQuality, out)) {
                Log.e(TAG, "error writing compressed image to disk for key " + key);
            }
        } else {
            Log.e(TAG, "Ignoring attempt to write null image to disk cache");
        }
    }

    /**
     * Gets an instance of AndroidHttpClient if the devices has it (it was introduced in 2.2), or
     * falls back on a http client that should work reasonably well.
     *
     * @return a working instance of an HttpClient
     */
    private HttpClient getHttpClient() {
        HttpClient ahc;
        try {
            final Class<?> ahcClass = Class.forName("android.net.http.AndroidHttpClient");
            final Method newInstance = ahcClass.getMethod("newInstance", String.class);
            ahc = (HttpClient) newInstance.invoke(null, "ImageCache");

        } catch (final ClassNotFoundException e) {
            DefaultHttpClient dhc = new DefaultHttpClient();
            final HttpParams params = dhc.getParams();
            dhc = null;

            params.setIntParameter(CoreConnectionPNames.CONNECTION_TIMEOUT, 20 * 1000);

            final SchemeRegistry registry = new SchemeRegistry();
            registry.register(new Scheme("http", PlainSocketFactory.getSocketFactory(), 80));
            registry.register(new Scheme("https", SSLSocketFactory.getSocketFactory(), 443));

            final ThreadSafeClientConnManager manager = new ThreadSafeClientConnManager(params,
                    registry);
            ahc = new DefaultHttpClient(manager, params);

        } catch (final NoSuchMethodException e) {

            final RuntimeException re = new RuntimeException("Programming error");
            re.initCause(e);
            throw re;

        } catch (final IllegalAccessException e) {
            final RuntimeException re = new RuntimeException("Programming error");
            re.initCause(e);
            throw re;

        } catch (final InvocationTargetException e) {
            final RuntimeException re = new RuntimeException("Programming error");
            re.initCause(e);
            throw re;
        }
        return ahc;
    }

    /**
     * <p>
     * Registers an {@link OnImageLoadListener} with the cache. When an image is loaded
     * asynchronously either directly by way of {@link #scheduleLoadImage(int, Uri, int, int)} or
     * indirectly by {@link #loadImage(int, Uri, int, int)}, any registered listeners will get
     * called.
     * </p>
     *
     * <p>
     * This should probably be called from {@link Activity#onResume()}.
     * </p>
     *
     * @param onImageLoadListener
     */
    public void registerOnImageLoadListener(OnImageLoadListener onImageLoadListener) {
        mImageLoadListeners.add(onImageLoadListener);
    }

    /**
     * <p>
     * Unregisters the listener with the cache. This will not cancel any pending load requests.
     * </p>
     *
     * <p>
     * This should probably be called from {@link Activity#onPause()}.
     * </p>
     *
     * @param onImageLoadListener
     */
    public void unregisterOnImageLoadListener(OnImageLoadListener onImageLoadListener) {
        mImageLoadListeners.remove(onImageLoadListener);
    }

    private class LoadResult {
        public LoadResult(int id, Uri image, Drawable drawable) {
            this.id = id;
            this.drawable = drawable;
            this.image = image;
        }

        final Uri image;
        final int id;
        final Drawable drawable;
    }

    /**
     * @param uri
     *            the image uri
     * @return a key unique to the given uri
     */
    public String getKey(Uri uri) {
        return uri.toString();
    }

    /**
     * Gets the given key as a drawable, retrieving it from memory cache if it's present.
     *
     * @param key
     *            a key generated by {@link #getKey(Uri)} or {@link #getKey(Uri, int, int)}
     * @return the drawable if it's in the memory cache or null.
     */
    public Drawable getDrawable(String key) {
        final Drawable img = mMemCache.get(key);
        if (img != null) {
            if (DEBUG) {
                Log.d(TAG, "mem cache hit for key " + key);
            }
            touchKey(key);
            return img;
        }

        return null;
    }

    /**
     * Puts a drawable into memory cache.
     *
     * @param key
     *            a key generated by {@link #getKey(Uri)} or {@link #getKey(Uri, int, int)}
     * @param drawable
     */
    public void putDrawable(String key, Drawable drawable) {
        mMemCache.put(key, drawable);
    }

    /**
     * A blocking call to get an image. If it's in the cache, it'll return the drawable immediately.
     * Otherwise it will download, scale, and cache the image before returning it. For non-blocking
     * use, see {@link #loadImage(int, Uri, int, int)}
     *
     * @param uri
     * @param width
     * @param height
     * @return
     * @throws ClientProtocolException
     * @throws IOException
     * @throws ImageCacheException
     */
    public Drawable getImage(Uri uri, int width, int height) throws ClientProtocolException,
            IOException, ImageCacheException {

        final String scaledKey = getKey(uri, width, height);

        mDownloading.lock(scaledKey);

        try {
            Drawable d = getDrawable(scaledKey);
            if (d != null) {
                return d;
            }

            Bitmap bmp = get(scaledKey);

            if (bmp == null) {
                if ("file".equals(uri.getScheme())) {
                    bmp = scaleLocalImage(new File(uri.getPath()), width, height);
                } else {
                    final String sourceKey = getKey(uri);

                    mDownloading.lock(sourceKey);

                    try {
                        if (!contains(sourceKey)) {
                            downloadImage(sourceKey, uri);
                        }
                    } finally {
                        mDownloading.unlock(sourceKey);
                    }

                    bmp = scaleLocalImage(getFile(sourceKey), width, height);
                    if (bmp == null) {
                        clear(sourceKey);
                    }
                }
                put(scaledKey, bmp);

            }
            if (bmp == null) {
                throw new ImageCacheException("got null bitmap from request to scale");

            }
            d = new BitmapDrawable(mRes, bmp);
            putDrawable(scaledKey, d);

            return d;

        } finally {
            mDownloading.unlock(scaledKey);
        }
    }

    private final SparseArray<String> mKeyCache = new SparseArray<String>();

    /**
     * Returns an opaque cache key representing the given uri, width and height.
     *
     * @param uri
     *            an image uri
     * @param width
     *            the desired image max width
     * @param height
     *            the desired image max height
     * @return a cache key unique to the given parameters
     */
    public String getKey(Uri uri, int width, int height) {
        // collisions are possible, but unlikely.
        final int hashId = uri.hashCode() + width + height * 10000;

        String key = mKeyCache.get(hashId);
        if (key == null) {
            key = uri.buildUpon().appendQueryParameter("width", String.valueOf(width))
                    .appendQueryParameter("height", String.valueOf(height)).build().toString();
            mKeyCache.put(hashId, key);
        }
        return key;
    }

    @Override
    public synchronized boolean clear() {
        final boolean success = super.clear();

        mMemCache.evictAll();

        mKeyCache.clear();

        return success;
    }

    @Override
    public synchronized boolean clear(String key) {
        final boolean success = super.clear(key);

        mMemCache.remove(key);

        return success;
    }

    private class ImageLoadTask implements Runnable, Comparable<ImageLoadTask> {
        private final int id;
        private final Uri uri;
        private final int width;
        private final int height;
        private final long when = System.nanoTime();

        public ImageLoadTask(int id, Uri image, int width, int height) {
            this.id = id;
            this.uri = image;
            this.width = width;
            this.height = height;
        }

        @Override
        public void run() {

            if (DEBUG) {
                Log.d(TAG, "ImageLoadTask.doInBackground(" + id + ", " + uri + ", " + width + ", "
                        + height + ")");
            }

            try {
                final LoadResult result = new LoadResult(id, uri, getImage(uri, width, height));
                synchronized (jobs) {
                    if (jobs.containsKey(id)) {
                        // Job still valid.
                        jobs.remove(id);
                        mHandler.obtainMessage(MSG_IMAGE_LOADED, result).sendToTarget();
                    }
                }

                // TODO this exception came about, no idea why:
                // java.lang.IllegalArgumentException: Parser may not be null
            } catch (final IllegalArgumentException e) {
                Log.e(TAG, e.getLocalizedMessage(), e);
            } catch (final OutOfMemoryError oom) {
                oomClear();
            } catch (final ClientProtocolException e) {
                Log.e(TAG, e.getLocalizedMessage(), e);
            } catch (final IOException e) {
                Log.e(TAG, e.getLocalizedMessage(), e);
            } catch (final ImageCacheException e) {
                Log.e(TAG, e.getLocalizedMessage(), e);
            }
        }

        @Override
        public int compareTo(ImageLoadTask another) {
            return Long.valueOf(another.when).compareTo(when);
        };
    }

    private void oomClear() {
        Log.w(TAG, "out of memory, clearing mem cache");
        mMemCache.evictAll();
    }

    /**
     * Checks the cache for an image matching the given criteria and returns it. If it isn't
     * immediately available, calls {@link #scheduleLoadImage}.
     *
     * @param id
     *            An ID to keep track of image load requests. For one-off loads, this can just be
     *            the ID of the {@link ImageView}. Otherwise, an unique ID can be acquired using
     *            {@link #getNewID()}.
     *
     * @param image
     *            the image to be loaded. Can be a local file or a network resource.
     * @param width
     *            the maximum width of the resulting image
     * @param height
     *            the maximum height of the resulting image
     * @return the cached bitmap if it's available immediately or null if it needs to be loaded
     *         asynchronously.
     */
    public Drawable loadImage(int id, Uri image, int width, int height) throws IOException {
        if (DEBUG) {
            Log.d(TAG, "loadImage(" + id + ", " + image + ", " + width + ", " + height + ")");
        }
        final Drawable res = getDrawable(getKey(image, width, height));
        if (res == null) {
            if (DEBUG) {
                Log.d(TAG,
                        "Image not found in memory cache. Scheduling load from network / disk...");
            }
            scheduleLoadImage(id, image, width, height);
        }
        return res;
    }

    /**
     * Deprecated to make IDs ints instead of longs. See {@link #loadImage(int, Uri, int, int)}.
     *
     * @param id
     * @param image
     * @param width
     * @param height
     * @return
     * @throws IOException
     */
    @Deprecated
    public Drawable loadImage(long id, Uri image, int width, int height) throws IOException {
        return loadImage(id, image, width, height);
    }

    /**
     * Schedules a load of the given image. When the image has finished loading and scaling, all
     * registered {@link OnImageLoadListener}s will be called.
     *
     * @param id
     *            An ID to keep track of image load requests. For one-off loads, this can just be
     *            the ID of the {@link ImageView}. Otherwise, an unique ID can be acquired using
     *            {@link #getNewID()}.
     *
     * @param image
     *            the image to be loaded. Can be a local file or a network resource.
     * @param width
     *            the maximum width of the resulting image
     * @param height
     *            the maximum height of the resulting image
     */
    public void scheduleLoadImage(int id, Uri image, int width, int height) {
        if (DEBUG) {
            Log.d(TAG, "executing new ImageLoadTask in background...");
        }
        final ImageLoadTask imt = new ImageLoadTask(id, image, width, height);

        jobs.put(id, imt);
        mExecutor.execute(imt);
    }

    /**
     * Deprecated in favour of {@link #scheduleLoadImage(int, Uri, int, int)}.
     *
     * @param id
     * @param image
     * @param width
     * @param height
     */
    @Deprecated
    public void scheduleLoadImage(long id, Uri image, int width, int height) {
        scheduleLoadImage(id, image, width, height);
    }

    /**
     * Cancels all the asynchronous image loads. Note: currently does not function properly.
     *
     */
    public void cancelLoads() {
        jobs.clear();
        mExecutor.getQueue().clear();
    }

    public void cancel(int id) {
        synchronized (jobs) {
            final Runnable job = jobs.get(id);
            if (job != null) {
                jobs.remove(id);
                mExecutor.remove(job);
                if (DEBUG) {
                    Log.d(TAG, "removed load id " + id);
                }
            }
        }
    }

    /**
     * Deprecated in favour of {@link #cancel(int)}.
     *
     * @param id
     */
    @Deprecated
    public void cancel(long id) {
        cancel(id);
    }

    /**
     * Blocking call to scale a local file. Scales using preserving aspect ratio
     *
     * @param localFile
     *            local image file to be scaled
     * @param width
     *            maximum width
     * @param height
     *            maximum height
     * @return the scaled image
     * @throws ClientProtocolException
     * @throws IOException
     */
    private static Bitmap scaleLocalImage(File localFile, int width, int height)
            throws ClientProtocolException, IOException {

        if (DEBUG) {
            Log.d(TAG, "scaleLocalImage(" + localFile + ", " + width + ", " + height + ")");
        }

        if (!localFile.exists()) {
            throw new IOException("local file does not exist: " + localFile);
        }
        if (!localFile.canRead()) {
            throw new IOException("cannot read from local file: " + localFile);
        }

        // the below borrowed from:
        // https://github.com/thest1/LazyList/blob/master/src/com/fedorvlasov/lazylist/ImageLoader.java

        // decode image size
        final BitmapFactory.Options o = new BitmapFactory.Options();
        o.inJustDecodeBounds = true;

        BitmapFactory.decodeStream(new FileInputStream(localFile), null, o);

        // Find the correct scale value. It should be the power of 2.
        //final int REQUIRED_WIDTH = width, REQUIRED_HEIGHT = height;
        int width_tmp = o.outWidth, height_tmp = o.outHeight;
        int scale = 1;
        while (true) {
            if (width_tmp / 2 <= width || height_tmp / 2 <= height) {
                break;
            }
            width_tmp /= 2;
            height_tmp /= 2;
            scale *= 2;
        }

        // decode with inSampleSize
        final BitmapFactory.Options o2 = new BitmapFactory.Options();
        o2.inSampleSize = scale;
        final Bitmap prescale = BitmapFactory
                .decodeStream(new FileInputStream(localFile), null, o2);

        if (prescale == null) {
            Log.e(TAG, localFile + " could not be decoded");
        } else if (DEBUG) {
            Log.d(TAG, "Successfully completed scaling of " + localFile + " to " + width + "x"
                    + height);
        }

        return prescale;
    }

    /**
     * Blocking call to download an image. The image is placed directly into the disk cache at the
     * given key.
     *
     * @param uri
     *            the location of the image
     * @return a decoded bitmap
     * @throws ClientProtocolException
     *             if the HTTP response code wasn't 200 or any other HTTP errors
     * @throws IOException
     */
    protected void downloadImage(String key, Uri uri) throws ClientProtocolException, IOException {
        if (DEBUG) {
            Log.d(TAG, "downloadImage(" + key + ", " + uri + ")");
        }
        if (USE_APACHE_NC) {
            final HttpGet get = new HttpGet(uri.toString());
            final HttpParams params = get.getParams();
            params.setParameter(ClientPNames.HANDLE_REDIRECTS, true);

            final HttpResponse hr = hc.execute(get);
            final StatusLine hs = hr.getStatusLine();
            if (hs.getStatusCode() != 200) {
                throw new HttpResponseException(hs.getStatusCode(), hs.getReasonPhrase());
            }

            final HttpEntity ent = hr.getEntity();

            // TODO I think this means that the source file must be a jpeg. fix this.
            try {

                putRaw(key, ent.getContent());
                if (DEBUG) {
                    Log.d(TAG, "source file of " + uri + " saved to disk cache at location "
                            + getFile(key).getAbsolutePath());
                }
            } finally {
                ent.consumeContent();
            }
        } else {
            final URLConnection con = new URL(uri.toString()).openConnection();
            putRaw(key, con.getInputStream());
            if (DEBUG) {
                Log.d(TAG,
                        "source file of " + uri + " saved to disk cache at location "
                                + getFile(key).getAbsolutePath());
            }
        }

    }

    private void notifyListeners(LoadResult result) {
        for (final OnImageLoadListener listener : mImageLoadListeners) {
            listener.onImageLoaded(result.id, result.image, result.drawable);
        }
    }

    /**
     * Implement this and register it using
     * {@link ImageCache#registerOnImageLoadListener(OnImageLoadListener)} to be notified when
     * asynchronous image loads have completed.
     *
     * @author <a href="mailto:spomeroy@mit.edu">Steve Pomeroy</a>
     *
     */
    public interface OnImageLoadListener {
        /**
         * Called when the image has been loaded and scaled.
         *
         * @param id
         *            the ID provided by {@link ImageCache#loadImage(int, Uri, int, int)} or
         *            {@link ImageCache#scheduleLoadImage(int, Uri, int, int)}
         * @param imageUri
         *            the uri of the image that was originally requested
         * @param image
         *            the loaded and scaled image
         */
        public void onImageLoaded(int id, Uri imageUri, Drawable image);
    }
}